fix(mcp): fail fast on a second direct-mode writer per project (#1740) (#1744)

Concurrent CODEGRAPH_NO_DAEMON / in-process fallback serve --mcp instances
each started a FileWatcher and contended on codegraph.lock until auto-sync
degraded. Add an exclusive .codegraph/writer.pid lock held by the daemon or
the single direct writer; a second writer exits with actionable guidance.
Daemon mode still multiplexes N proxies onto one writer.

Co-authored-by: Colby McHenry <colbymchenry@users.noreply.github.com>

src/mcp/daemon.ts

@@ -55,6 +55,7 @@ import {
   getDaemonSocketPath,
 } from './daemon-paths';
 import { CodeGraphPackageVersion } from './version';
+import { releaseWriterLock, tryAcquireWriterLock, writerLockHeldMessage } from './writer-lock';
 import { registerDaemon, deregisterDaemon } from './daemon-registry';
 
 /** Default idle linger after the last client disconnects. */
@@ -204,6 +205,16 @@ export class Daemon {
    * listening — the daemon then sticks around until idle/shutdown.
    */
   async start(): Promise<DaemonStartResult> {
+    // #1740: claim the project writer lock before opening/watching so a
+    // concurrent direct-mode serve --mcp cannot start a second watcher.
+    const writer = tryAcquireWriterLock(this.projectRoot, 'daemon');
+    if (writer.kind === 'taken') {
+      const msg = writerLockHeldMessage(writer.existing, writer.pidPath);
+      process.stderr.write(`[CodeGraph daemon] ${msg}\n`);
+      this.cleanupLockfile();
+      throw new Error(msg);
+    }
+
     // Engine init is deliberately backgrounded — see #172. The first session
     // to land waits on `ensureInitialized` either way, and unloaded sessions
     // (cross-project tool calls only) shouldn't pay any open cost.
@@ -498,6 +509,7 @@ export class Daemon {
   }
 
   private cleanupLockfile(): void {
+    releaseWriterLock(this.projectRoot);
     try {
       if (fs.existsSync(this.pidPath)) {
         // Only remove if it still belongs to us — another daemon may have

src/mcp/engine.ts

@@ -16,6 +16,7 @@ import type CodeGraph from '../index';
 import { resolveServerRoot } from '../directory';
 import { watchDisabledReason } from '../sync';
 import { ToolHandler } from './tools';
+import { releaseWriterLock, tryAcquireWriterLock, writerLockHeldMessage } from './writer-lock';
 import { QueryPool, resolvePoolSize } from './query-pool';
 
 // Lazy-load the heavy CodeGraph chain (sqlite + query/graph/context layers) OFF
@@ -67,6 +68,8 @@ export class MCPEngine {
   // bounded but shouldn't run on every tool call in the no-default state.
   private lastRetrySubScanAt = 0;
   private watcherStarted = false;
+  /** Set when this engine holds writer.pid (#1740). */
+  private writerLockRoot: string | null = null;
   private opts: Required<MCPEngineOptions>;
   private closed = false;
   // Off-loop read-tool pool (daemon mode only). Created lazily once the default
@@ -203,6 +206,10 @@ export class MCPEngine {
   stop(): void {
     if (this.closed) return;
     this.closed = true;
+    if (this.writerLockRoot) {
+      releaseWriterLock(this.writerLockRoot);
+      this.writerLockRoot = null;
+    }
     // Detach + terminate the worker pool first so no tool call routes to a
     // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
     this.toolHandler.setQueryPool(null);
@@ -278,6 +285,24 @@ export class MCPEngine {
   private startWatching(): void {
     if (!this.cg || this.watcherStarted || !this.opts.watch) return;
 
+    // #1740: only one live watcher/writer per project. Daemon and startDirect
+    // usually already hold writer.pid (re-entrant for this pid). Proxy
+    // in-process fallback acquires here; if another writer holds it, skip the
+    // watcher so we never contend on codegraph.lock until auto-sync degrades.
+    const lockRoot = this.projectPath;
+    if (lockRoot) {
+      const writer = tryAcquireWriterLock(lockRoot, 'fallback');
+      if (writer.kind === 'taken') {
+        const msg = writerLockHeldMessage(writer.existing, writer.pidPath);
+        process.stderr.write(
+          `[CodeGraph MCP] File watcher not started — ${msg}\n`
+        );
+        this.watcherStarted = true;
+        return;
+      }
+      this.writerLockRoot = lockRoot;
+    }
+
     const disabledReason = watchDisabledReason(this.projectPath ?? process.cwd());
     if (disabledReason) {
       process.stderr.write(

src/mcp/index.ts

@@ -48,6 +48,7 @@ import {
   tryAcquireDaemonLock,
 } from './daemon';
 import { connectWithHello, runLocalHandshakeProxy } from './proxy';
+import { releaseWriterLock, tryAcquireWriterLock, writerLockHeldMessage } from './writer-lock';
 import { getDaemonSocketCandidates, probeDaemonIdentity } from './daemon-paths';
 import { getTelemetry } from '../telemetry';
 import { checkForUpdateInBackground } from '../upgrade/update-check';
@@ -252,6 +253,8 @@ export class MCPServer {
   // Idempotency guard for stop().
   private stopped = false;
   private mode: 'unstarted' | 'direct' | 'proxy' | 'daemon' = 'unstarted';
+  /** Project root whose writer.pid we hold in direct mode (#1740); released on stop. */
+  private writerLockRoot: string | null = null;
 
   constructor(projectPath?: string) {
     this.projectPath = projectPath || null;
@@ -329,6 +332,10 @@ export class MCPServer {
   stop(): void {
     if (this.stopped) return;
     this.stopped = true;
+    if (this.writerLockRoot) {
+      releaseWriterLock(this.writerLockRoot);
+      this.writerLockRoot = null;
+    }
     if (this.ppidWatchdog) {
       clearInterval(this.ppidWatchdog);
       this.ppidWatchdog = null;
@@ -358,6 +365,20 @@ export class MCPServer {
     if (reason && process.env.CODEGRAPH_MCP_DEBUG) {
       process.stderr.write(`[CodeGraph MCP] Direct mode: ${reason}.\n`);
     }
+
+    // #1740: refuse a second direct writer on an initialized project. Daemon
+    // mode multiplexes clients; direct mode is single-writer-per-project.
+    const writerRoot = resolveDaemonRoot(this.projectPath);
+    if (writerRoot) {
+      const writer = tryAcquireWriterLock(writerRoot, 'direct');
+      if (writer.kind === 'taken') {
+        const msg = writerLockHeldMessage(writer.existing, writer.pidPath);
+        process.stderr.write(`[CodeGraph MCP] ${msg}\n`);
+        process.exit(1);
+      }
+      this.writerLockRoot = writerRoot;
+    }
+
     this.engine = new MCPEngine();
     const transport = new StdioTransport();
     this.session = new MCPSession(transport, this.engine, {

src/mcp/writer-lock.ts

@@ -0,0 +1,188 @@
+/**
+ * Project writer lock (#1740).
+ *
+ * At most one long-lived MCP *writer* (shared daemon OR direct-mode /
+ * in-process engine that owns the FileWatcher) may serve a given project.
+ * The shared daemon already multiplexes N stdio proxies onto one writer; this
+ * lock closes the same-OS gap where two direct-mode `serve --mcp` processes
+ * (via `CODEGRAPH_NO_DAEMON=1` or proxy→in-process fallback) each start a
+ * watcher, contend on `codegraph.lock`, and degrade auto-sync.
+ *
+ * Deliberately separate from `daemon.pid`: proxies probe the daemon socket
+ * and may clear a live pid that has no socket. A direct-mode holder must not
+ * look like a daemon. `writer.pid` is only about "who owns live auto-sync".
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCodeGraphDir } from '../directory';
+/** Signal-0 liveness (EPERM ⇒ alive). Local copy to avoid a daemon↔writer cycle. */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+
+/** Absolute path to the writer pid lockfile for `projectRoot`. */
+export function getWriterPidPath(projectRoot: string): string {
+  let root = projectRoot;
+  try { root = fs.realpathSync(projectRoot); } catch { /* keep lexical */ }
+  return path.join(getCodeGraphDir(root), 'writer.pid');
+}
+
+/** Structured contents of the writer pidfile. */
+export interface WriterLockInfo {
+  pid: number;
+  /** `direct` | `daemon` | `fallback` — for actionable error text only. */
+  mode: string;
+  startedAt: number;
+}
+
+export type WriterAcquireResult =
+  | { kind: 'acquired'; pidPath: string; info: WriterLockInfo }
+  | { kind: 'taken'; existing: WriterLockInfo | null; pidPath: string };
+
+function encode(info: WriterLockInfo): string {
+  return JSON.stringify(info) + '\n';
+}
+
+export function decodeWriterLockInfo(raw: string): WriterLockInfo | null {
+  try {
+    const parsed = JSON.parse(raw.trim()) as Partial<WriterLockInfo>;
+    if (typeof parsed.pid !== 'number' || typeof parsed.mode !== 'string') return null;
+    return {
+      pid: parsed.pid,
+      mode: parsed.mode,
+      startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomically create `writer.pid` (link-into-place, O_EXCL fallback). If held
+ * by a dead PID, clear and retry once. Does not steal from a live holder.
+ */
+export function tryAcquireWriterLock(
+  projectRoot: string,
+  mode: string,
+): WriterAcquireResult {
+  const pidPath = getWriterPidPath(projectRoot);
+  fs.mkdirSync(path.dirname(pidPath), { recursive: true });
+
+  const info: WriterLockInfo = {
+    pid: process.pid,
+    mode,
+    startedAt: Date.now(),
+  };
+
+  const attempt = (): WriterAcquireResult => {
+    const tmp = `${pidPath}.${process.pid}.tmp`;
+    let acquired = false;
+    try {
+      fs.writeFileSync(tmp, encode(info), { mode: 0o600 });
+      try {
+        fs.linkSync(tmp, pidPath);
+        acquired = true;
+      } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+          // taken
+        } else {
+          // No hard links — O_EXCL create.
+          try {
+            const fd = fs.openSync(pidPath, 'wx', 0o600);
+            try {
+              fs.writeSync(fd, encode(info));
+              acquired = true;
+            } finally {
+              fs.closeSync(fd);
+            }
+          } catch (e2: unknown) {
+            if ((e2 as NodeJS.ErrnoException).code !== 'EEXIST') throw e2;
+          }
+        }
+      }
+    } finally {
+      try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    }
+
+    if (acquired) return { kind: 'acquired', pidPath, info };
+
+    let existing: WriterLockInfo | null = null;
+    try {
+      existing = decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+    } catch { /* unreadable */ }
+    return { kind: 'taken', existing, pidPath };
+  };
+
+  let result = attempt();
+  if (result.kind === 'taken' && result.existing && result.existing.pid === process.pid) {
+    // Same process already holds it (daemon acquired before engine watch).
+    return { kind: 'acquired', pidPath: result.pidPath, info: result.existing };
+  }
+  if (result.kind === 'taken') {
+    const existing = result.existing;
+    if (!existing || existing.pid <= 0 || !isProcessAlive(existing.pid)) {
+      // Stale — clear (pid-verified) and retry once.
+      try {
+        const raw = fs.readFileSync(pidPath, 'utf8');
+        const cur = decodeWriterLockInfo(raw);
+        if (!cur || cur.pid === existing?.pid) {
+          if (!cur || cur.pid <= 0 || !isProcessAlive(cur.pid)) {
+            fs.unlinkSync(pidPath);
+          }
+        }
+      } catch { /* ENOENT ok */ }
+      result = attempt();
+    }
+  }
+  return result;
+}
+
+/** Release if we still own the lock (pid match). */
+export function releaseWriterLock(projectRoot: string): void {
+  const pidPath = getWriterPidPath(projectRoot);
+  try {
+    if (!fs.existsSync(pidPath)) return;
+    const info = decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+    if (info && info.pid === process.pid) {
+      fs.unlinkSync(pidPath);
+    }
+  } catch { /* best-effort */ }
+}
+
+/** Read current lock without acquiring. */
+export function readWriterLock(projectRoot: string): WriterLockInfo | null {
+  const pidPath = getWriterPidPath(projectRoot);
+  try {
+    return decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Actionable message when another live process owns the writer lock (#1740).
+ */
+export function writerLockHeldMessage(
+  existing: WriterLockInfo | null,
+  pidPath: string,
+): string {
+  const who = existing && existing.pid > 0
+    ? `PID ${existing.pid} (${existing.mode || 'unknown'} mode)`
+    : 'another process';
+  return (
+    'CodeGraph writer lock held by ' + who + '. ' +
+    'Only one live MCP writer may serve a project (auto-sync / index). ' +
+    'Stop the other server (codegraph daemon stop if a shared daemon, or end the other MCP session), ' +
+    'or unset CODEGRAPH_NO_DAEMON so additional clients proxy to the shared daemon. ' +
+    'If this is stale, delete ' + pidPath
+  );
+}