@colbymchenry/codegraph-darwin-x64 0.9.4 → 0.9.5

package/lib/dist/installer/instructions-template.d.ts

@@ -18,11 +18,11 @@ export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
  * instructions file. Includes the start/end markers so the section
  * can be detected and replaced on re-install.
  */
-export declare const INSTRUCTIONS_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Give me focused context for a task/area\" | `codegraph_context` |\n| \"See several related symbols' source at once\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don't delegate exploration.** For \"how does X work\" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** (\"how does X reach Y\") start with `codegraph_trace` from\u2192to \u2014 one call returns the whole path with dynamic hops bridged \u2014 then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that's slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
+export declare const INSTRUCTIONS_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Give me focused context for a task/area\" | `codegraph_context` |\n| \"See several related symbols' source at once\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don't delegate exploration.** For \"how does X work\" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** (\"how does X reach Y\") start with `codegraph_trace` from\u2192to \u2014 one call returns the whole path with dynamic hops bridged \u2014 then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that's slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag \u2014 check the staleness banner, don't guess a wait.** When a codegraph response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under \"Pending sync\".\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
 /**
  * Backwards-compat alias. Existing downstream code may import
  * `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
  * `claude-md-template.ts`.
  */
-export declare const CLAUDE_MD_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Give me focused context for a task/area\" | `codegraph_context` |\n| \"See several related symbols' source at once\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don't delegate exploration.** For \"how does X work\" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** (\"how does X reach Y\") start with `codegraph_trace` from\u2192to \u2014 one call returns the whole path with dynamic hops bridged \u2014 then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that's slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
+export declare const CLAUDE_MD_TEMPLATE = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Give me focused context for a task/area\" | `codegraph_context` |\n| \"See several related symbols' source at once\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Rules of thumb\n\n- **Answer directly \u2014 don't delegate exploration.** For \"how does X work\" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** (\"how does X reach Y\") start with `codegraph_trace` from\u2192to \u2014 one call returns the whole path with dynamic hops bridged \u2014 then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent \u2014 or running a grep + read loop \u2014 repeats work codegraph already did and costs more for the same answer.\n- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep \u2014 that's slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.\n- **Index lag \u2014 check the staleness banner, don't guess a wait.** When a codegraph response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under \"Pending sync\".\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n<!-- CODEGRAPH_END -->";
 //# sourceMappingURL=instructions-template.d.ts.map

package/lib/dist/installer/instructions-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions-template.d.ts","sourceRoot":"","sources":["../../src/installer/instructions-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAClE,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,yjGAkCT,CAAC;AAE1B;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yjGAAwB,CAAC"}
+{"version":3,"file":"instructions-template.d.ts","sourceRoot":"","sources":["../../src/installer/instructions-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAClE,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,y2GAkCT,CAAC;AAE1B;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,y2GAAwB,CAAC"}

package/lib/dist/installer/instructions-template.js

@@ -50,7 +50,7 @@ Use codegraph for **structural** questions — what calls what, what would break
 - **Don't grep first** when looking up a symbol by name. \`codegraph_search\` is faster and returns kind + location + signature in one call.
 - **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one call.
 - **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
-- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. \`codegraph_status\` also lists pending files under "Pending sync".
 
 ### If \`.codegraph/\` doesn't exist
 

package/lib/dist/mcp/daemon-paths.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Daemon socket + lockfile path helpers — issue #411.
+ *
+ * One shared `codegraph serve --mcp` daemon per project root means we need a
+ * stable, project-keyed rendezvous between cooperating processes. The IPC
+ * surface area is just two file paths:
+ *
+ *   - `daemon.sock` — Unix domain socket / named pipe the daemon listens on.
+ *   - `daemon.pid` — atomic-create lockfile holding the daemon's pid + version.
+ *
+ * Both live under `.codegraph/` so the project-scoped uninstall (`codegraph
+ * uninit`) sweeps them up for free.
+ *
+ * Special-case: Unix domain socket paths have a hard length limit (~104 on
+ * macOS, ~108 on Linux); when the in-project path exceeds it we fall back to
+ * an absolute-path hash under `os.tmpdir()`. The pidfile always stays in the
+ * project (it doesn't have a length limit) — and acts as the authoritative
+ * pointer to the socket path the daemon chose.
+ */
+/**
+ * Compute the socket / named-pipe path the daemon should listen on (and the
+ * proxy should connect to) for `projectRoot`. Deterministic given a project
+ * root, so independent processes converge without coordination.
+ */
+export declare function getDaemonSocketPath(projectRoot: string): string;
+/** Absolute path to the daemon pid lockfile for `projectRoot`. */
+export declare function getDaemonPidPath(projectRoot: string): string;
+/** Structured contents of the pid lockfile. */
+export interface DaemonLockInfo {
+    pid: number;
+    version: string;
+    socketPath: string;
+    startedAt: number;
+}
+/**
+ * Serialize a {@link DaemonLockInfo} for writing to the pidfile. JSON for
+ * human readability — operators occasionally `cat` this when debugging.
+ */
+export declare function encodeLockInfo(info: DaemonLockInfo): string;
+/**
+ * Parse a pidfile body. Tolerant of old-format pidfiles (plain decimal pid) so
+ * a 0.10.x daemon doesn't trip over a 0.9.x lockfile if that ever happens —
+ * we treat such a lockfile as "process is unknown version, refuse to share."
+ */
+export declare function decodeLockInfo(raw: string): DaemonLockInfo | null;
+//# sourceMappingURL=daemon-paths.d.ts.map

package/lib/dist/mcp/daemon-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-paths.d.ts","sourceRoot":"","sources":["../../src/mcp/daemon-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBjE"}

package/lib/dist/mcp/daemon-paths.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Daemon socket + lockfile path helpers — issue #411.
+ *
+ * One shared `codegraph serve --mcp` daemon per project root means we need a
+ * stable, project-keyed rendezvous between cooperating processes. The IPC
+ * surface area is just two file paths:
+ *
+ *   - `daemon.sock` — Unix domain socket / named pipe the daemon listens on.
+ *   - `daemon.pid` — atomic-create lockfile holding the daemon's pid + version.
+ *
+ * Both live under `.codegraph/` so the project-scoped uninstall (`codegraph
+ * uninit`) sweeps them up for free.
+ *
+ * Special-case: Unix domain socket paths have a hard length limit (~104 on
+ * macOS, ~108 on Linux); when the in-project path exceeds it we fall back to
+ * an absolute-path hash under `os.tmpdir()`. The pidfile always stays in the
+ * project (it doesn't have a length limit) — and acts as the authoritative
+ * pointer to the socket path the daemon chose.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDaemonSocketPath = getDaemonSocketPath;
+exports.getDaemonPidPath = getDaemonPidPath;
+exports.encodeLockInfo = encodeLockInfo;
+exports.decodeLockInfo = decodeLockInfo;
+const crypto = __importStar(require("crypto"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const directory_1 = require("../directory");
+/** Soft upper bound for in-project socket paths. */
+const POSIX_SOCKET_PATH_LIMIT = 100;
+/** Short stable identifier for a project root — used in tmpdir/pipe names. */
+function projectHash(projectRoot) {
+    return crypto.createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 16);
+}
+/**
+ * Compute the socket / named-pipe path the daemon should listen on (and the
+ * proxy should connect to) for `projectRoot`. Deterministic given a project
+ * root, so independent processes converge without coordination.
+ */
+function getDaemonSocketPath(projectRoot) {
+    if (process.platform === 'win32') {
+        return `\\\\.\\pipe\\codegraph-${projectHash(projectRoot)}`;
+    }
+    const inProject = path.join((0, directory_1.getCodeGraphDir)(projectRoot), 'daemon.sock');
+    if (inProject.length <= POSIX_SOCKET_PATH_LIMIT)
+        return inProject;
+    // Long project paths (deep monorepos, Bazel out dirs) need tmpdir fallback
+    // or `bind` returns EADDRINUSE / ENAMETOOLONG. Hash keeps it project-scoped.
+    return path.join(os.tmpdir(), `codegraph-${projectHash(projectRoot)}.sock`);
+}
+/** Absolute path to the daemon pid lockfile for `projectRoot`. */
+function getDaemonPidPath(projectRoot) {
+    return path.join((0, directory_1.getCodeGraphDir)(projectRoot), 'daemon.pid');
+}
+/**
+ * Serialize a {@link DaemonLockInfo} for writing to the pidfile. JSON for
+ * human readability — operators occasionally `cat` this when debugging.
+ */
+function encodeLockInfo(info) {
+    return JSON.stringify(info, null, 2) + '\n';
+}
+/**
+ * Parse a pidfile body. Tolerant of old-format pidfiles (plain decimal pid) so
+ * a 0.10.x daemon doesn't trip over a 0.9.x lockfile if that ever happens —
+ * we treat such a lockfile as "process is unknown version, refuse to share."
+ */
+function decodeLockInfo(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed &&
+            typeof parsed.pid === 'number' &&
+            typeof parsed.version === 'string' &&
+            typeof parsed.socketPath === 'string' &&
+            typeof parsed.startedAt === 'number') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        // Fall through to legacy plain-pid handling.
+    }
+    const pid = Number(trimmed);
+    if (Number.isFinite(pid) && pid > 0) {
+        return { pid, version: 'unknown', socketPath: '', startedAt: 0 };
+    }
+    return null;
+}
+//# sourceMappingURL=daemon-paths.js.map

package/lib/dist/mcp/daemon-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-paths.js","sourceRoot":"","sources":["../../src/mcp/daemon-paths.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBH,kDASC;AAGD,4CAEC;AAcD,wCAEC;AAOD,wCAuBC;AA9ED,+CAAiC;AACjC,uCAAyB;AACzB,2CAA6B;AAC7B,4CAA+C;AAE/C,oDAAoD;AACpD,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,8EAA8E;AAC9E,SAAS,WAAW,CAAC,WAAmB;IACtC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClG,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,WAAmB;IACrD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,0BAA0B,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;IAC9D,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAA,2BAAe,EAAC,WAAW,CAAC,EAAE,aAAa,CAAC,CAAC;IACzE,IAAI,SAAS,CAAC,MAAM,IAAI,uBAAuB;QAAE,OAAO,SAAS,CAAC;IAClE,2EAA2E;IAC3E,6EAA6E;IAC7E,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,aAAa,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED,kEAAkE;AAClE,SAAgB,gBAAgB,CAAC,WAAmB;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAA,2BAAe,EAAC,WAAW,CAAC,EAAE,YAAY,CAAC,CAAC;AAC/D,CAAC;AAUD;;;GAGG;AACH,SAAgB,cAAc,CAAC,IAAoB;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,GAAW;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IACE,MAAM;YACN,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;YACrC,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,EACpC,CAAC;YACD,OAAO,MAAwB,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/dist/mcp/daemon.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `codegraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.codegraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+import { DaemonLockInfo } from './daemon-paths';
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+declare const MAX_HELLO_LINE_BYTES = 4096;
+/**
+ * Wire format for the one-shot hello line the daemon emits on every new
+ * connection. Versioned with the package's own semver so a 0.9.x proxy never
+ * pipes through a 0.10.x daemon (or vice-versa) — the proxy falls back to
+ * direct mode on mismatch rather than risk subtle wire incompatibilities.
+ */
+export interface DaemonHello {
+    codegraph: string;
+    pid: number;
+    socketPath: string;
+    protocol: 1;
+}
+export interface DaemonStartResult {
+    /** Always-non-null for a successfully-started daemon. */
+    socketPath: string;
+    /** Lockfile contents as written. */
+    lock: DaemonLockInfo;
+}
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+export declare class Daemon {
+    private projectRoot;
+    private server;
+    private clients;
+    private idleTimer;
+    private idleTimeoutMs;
+    private engine;
+    private stopping;
+    private socketPath;
+    private pidPath;
+    constructor(projectRoot: string, opts?: {
+        idleTimeoutMs?: number;
+    });
+    /**
+     * Bind the socket, kick off engine init, and register signal handlers. The
+     * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+     * there is nothing to write here. The promise resolves once the server is
+     * listening — the daemon then sticks around until idle/shutdown.
+     */
+    start(): Promise<DaemonStartResult>;
+    /** Currently-connected client count. Exposed for tests / status output. */
+    getClientCount(): number;
+    /** The socket path the daemon is (or will be) listening on. */
+    getSocketPath(): string;
+    /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+    stop(reason?: string): Promise<void>;
+    private handleConnection;
+    private dropClient;
+    private armIdleTimer;
+    private disarmIdleTimer;
+    private cleanupLockfile;
+}
+/**
+ * Result of `tryAcquireDaemonLock`. Either we got the lockfile (caller becomes
+ * the daemon), or it already existed (caller should connect to the existing
+ * daemon as a proxy, or — if the holder is dead — clear it and retry).
+ */
+export type AcquireResult = {
+    kind: 'acquired';
+    pidPath: string;
+    info: DaemonLockInfo;
+} | {
+    kind: 'taken';
+    existing: DaemonLockInfo | null;
+    pidPath: string;
+};
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * the file existed but was empty; under concurrent daemon startup a third
+ * candidate could read that empty file, decode it as `null`, and `unlink` the
+ * winner's lock → two daemons (two watchers, two writers). The window was
+ * normally too small to hit, but the chokidar watcher's extra startup time made
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ */
+export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?: number): boolean;
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** Exported for test stubs that need to bound the hello-line read. */
+export { MAX_HELLO_LINE_BYTES };
+//# sourceMappingURL=daemon.d.ts.map

package/lib/dist/mcp/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/mcp/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAQH,OAAO,EACL,cAAc,EAKf,MAAM,gBAAgB,CAAC;AAMxB,yFAAyF;AACzF,QAAA,MAAM,oBAAoB,OAAO,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,CAAC,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,IAAI,EAAE,cAAc,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,MAAM;IAWf,OAAO,CAAC,WAAW;IAVrB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;gBAGd,WAAW,EAAE,MAAM,EAC3B,IAAI,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO;IASvC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAiDzC,2EAA2E;IAC3E,cAAc,IAAI,MAAM;IAIxB,+DAA+D;IAC/D,aAAa,IAAI,MAAM;IAIvB,gFAAgF;IAC1E,IAAI,CAAC,MAAM,GAAE,MAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBlD,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,eAAe;CAaxB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAsCvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAiBvF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASnD;AAUD,sEAAsE;AACtE,OAAO,EAAE,oBAAoB,EAAE,CAAC"}