@cairnkeep/cli 2.17.2 → 2.18.0

package/omp/extensions/cairnkeep-memory.ts

@@ -0,0 +1,288 @@
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@oh-my-pi/pi-coding-agent";
+import { spawn, type ChildProcess } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+// The bridge runs as a node child process because compiled Bun standalone
+// binaries cannot resolve node_modules for runtime-imported files.
+const CAIRN_ROOT = "@@INFRA_ROOT@@";
+const CHILD_ENTRY = join(CAIRN_ROOT, "mcp-memory-server", "dist", "pi-bridge-child.js");
+
+const STARTUP_TIMEOUT_MS = 10_000;
+const CALL_TIMEOUT_MS = 30_000;
+const STDERR_LIMIT_BYTES = 16 * 1024;
+const SHUTDOWN_GRACE_MS = 3_000;
+
+type CatalogTool = {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+};
+
+type ChildResult =
+    | { type: "ready" }
+    | { type: "result"; id: number; ok: true; tools?: CatalogTool[]; result?: unknown }
+    | { type: "result"; id: number; ok: false; error: string; stderr?: string };
+
+type PendingRequest = {
+    resolve: (value: unknown) => void;
+    reject: (error: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+};
+
+// Minimal line-delimited JSON client for pi-bridge-child.js: requests carry
+// an id, results route back by id, and an unexpected child exit rejects
+// everything pending with the captured stderr tail.
+class BridgeChildClient {
+    #child: ChildProcess;
+    #nextId = 1;
+    #stdoutBuffer = "";
+    #stderrTail = "";
+    #pending = new Map<number, PendingRequest>();
+    #readyPending: PendingRequest | undefined;
+    #exitPromise: Promise<void>;
+    #closed = false;
+
+    private constructor(child: ChildProcess) {
+        this.#child = child;
+        this.#exitPromise = new Promise((resolvePromise) => {
+            child.once("exit", () => resolvePromise());
+            child.once("error", () => resolvePromise());
+        });
+        child.stdout?.on("data", (chunk: Buffer | string) => this.#onStdout(chunk));
+        child.stderr?.on("data", (chunk: Buffer | string) => this.#appendStderr(chunk));
+        child.on("error", () => this.#failAll(new Error("Cairnkeep bridge child failed to start.")));
+        child.once("exit", (code, signal) => {
+            const detail = this.#stderrTail.trim();
+            const suffix = detail ? ` (child stderr: ${detail})` : "";
+            this.#failAll(new Error(`Cairnkeep bridge child exited (${signal ?? code}).${suffix}`));
+            this.#readyPending?.reject(new Error(`Cairnkeep bridge child exited before ready (${signal ?? code}).${suffix}`));
+            this.#readyPending = undefined;
+        });
+        const pidLog = process.env.CAIRN_BRIDGE_CHILD_PID_LOG;
+        if (pidLog && child.pid) appendFileSync(pidLog, `${child.pid}\n`);
+    }
+
+    static spawn(cwd: string): BridgeChildClient {
+        const child = spawn("node", [CHILD_ENTRY, cwd], { stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.on("error", () => undefined);
+        return new BridgeChildClient(child);
+    }
+
+    ready(): Promise<void> {
+        return new Promise((resolvePromise, rejectPromise) => {
+            const timer = setTimeout(() => {
+                this.#readyPending = undefined;
+                rejectPromise(new Error("Cairnkeep bridge child timed out waiting for ready."));
+            }, STARTUP_TIMEOUT_MS);
+            this.#readyPending = {
+                resolve: () => {
+                    clearTimeout(timer);
+                    resolvePromise();
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    rejectPromise(error);
+                },
+                timer,
+            };
+        });
+    }
+
+    request(message: Omit<{ type: "list" | "close" }, "id"> | { type: "call"; tool: unknown; args: Record<string, unknown> }, timeoutMs: number): Promise<unknown> {
+        const id = this.#nextId++;
+        return new Promise((resolvePromise, rejectPromise) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                rejectPromise(new Error(`Cairnkeep bridge child request ${message.type} timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timer });
+            this.#write({ ...message, id });
+        });
+    }
+
+    // One MCP tool call: 30s backstop timer plus cancellation forwarded to the
+    // child as a protocol-level cancel.
+    call(tool: unknown, args: Record<string, unknown>, signal: AbortSignal | undefined): Promise<unknown> {
+        const id = this.#nextId++;
+        return new Promise((resolvePromise, rejectPromise) => {
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            const cancel = (): void => {
+                if (timer) clearTimeout(timer);
+                this.#pending.delete(id);
+                this.#write({ type: "cancel", id });
+                rejectPromise(new Error("cancelled"));
+            };
+            timer = setTimeout(() => {
+                this.#pending.delete(id);
+                this.#write({ type: "cancel", id });
+                rejectPromise(new Error(`Cairnkeep MCP call timed out after ${CALL_TIMEOUT_MS}ms.`));
+            }, CALL_TIMEOUT_MS);
+            this.#pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timer });
+            if (signal) {
+                if (signal.aborted) {
+                    cancel();
+                    return;
+                }
+                signal.addEventListener("abort", cancel, { once: true });
+            }
+            this.#write({ type: "call", id, tool, args });
+        });
+    }
+
+    async close(): Promise<void> {
+        if (this.#closed) return;
+        this.#closed = true;
+        try {
+            this.#write({ type: "close" });
+        } catch {
+            // Child already gone — the exit handler rejected everything pending.
+        }
+        const grace = setTimeout(() => {
+            try {
+                this.#child.kill("SIGKILL");
+            } catch {
+                // best-effort kill only
+            }
+        }, SHUTDOWN_GRACE_MS);
+        await this.#exitPromise;
+        clearTimeout(grace);
+    }
+
+    #write(message: unknown): void {
+        this.#child.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+
+    #appendStderr(chunk: Buffer | string): void {
+        const next = this.#stderrTail + (Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
+        this.#stderrTail = next.length <= STDERR_LIMIT_BYTES ? next : next.slice(next.length - STDERR_LIMIT_BYTES);
+    }
+
+    #onStdout(chunk: Buffer | string): void {
+        this.#stdoutBuffer += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+        let newline = this.#stdoutBuffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.#stdoutBuffer.slice(0, newline);
+            this.#stdoutBuffer = this.#stdoutBuffer.slice(newline + 1);
+            newline = this.#stdoutBuffer.indexOf("\n");
+            if (!line.trim()) continue;
+            let message: ChildResult;
+            try {
+                message = JSON.parse(line) as ChildResult;
+            } catch {
+                continue;
+            }
+            if (message.type === "ready") {
+                this.#readyPending?.resolve(undefined);
+                this.#readyPending = undefined;
+                continue;
+            }
+            if (message.type !== "result") continue;
+            const pending = this.#pending.get(message.id);
+            if (!pending) continue;
+            this.#pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.ok) pending.resolve(message.tools ?? message.result);
+            else {
+                const detail = typeof message.stderr === "string" && message.stderr.trim() ? ` (child stderr: ${message.stderr.trim()})` : "";
+                pending.reject(new Error(`${message.error}${detail}`));
+            }
+        }
+    }
+
+    #failAll(error: Error): void {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+
+// AgentToolResult.content accepts text and base64 image blocks; the bridge
+// child already reduces MCP content to exactly those two shapes.
+function toAgentToolResult(result: unknown): AgentToolResult {
+    const { content, details } = result as {
+        content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+        details?: unknown;
+    };
+    return {
+        content: content.map((item) =>
+            item.type === "text"
+                ? { type: "text" as const, text: item.text ?? "" }
+                : { type: "image" as const, data: item.data ?? "", mimeType: item.mimeType ?? "" },
+        ),
+        details,
+    };
+}
+
+// omp rebinds extensions to ephemeral side-turn runtimes (e.g. title
+// generation) whose action methods are uninitialized stubs that throw; bridge
+// startup is skipped there and the real session starts it later.
+function runtimeUninitialized(pi: ExtensionAPI): boolean {
+    try {
+        pi.getAllTools();
+        return false;
+    } catch (error) {
+        if (error instanceof Error && error.message.includes("Extension runtime not initialized")) return true;
+        throw error;
+    }
+}
+
+function existingToolNames(pi: ExtensionAPI): Set<string> {
+    return new Set(pi.getAllTools().map((tool) => tool.name));
+}
+
+export default function cairnMemoryExtension(pi: ExtensionAPI): void {
+    let client: BridgeChildClient | undefined;
+    let startPromise: Promise<void> | undefined;
+    let shutdownPromise: Promise<void> | undefined;
+
+    const start = async (ctx: ExtensionContext): Promise<void> => {
+        const connected = BridgeChildClient.spawn(ctx.cwd);
+        try {
+            await connected.ready();
+            const tools = (await connected.request({ type: "list" }, STARTUP_TIMEOUT_MS)) as CatalogTool[];
+            const existing = existingToolNames(pi);
+            const collisions = tools.map(({ name }) => name).filter((name) => existing.has(name));
+            if (collisions.length) {
+                throw new Error(`Cairnkeep MCP tool collision would override an existing omp tool: ${collisions.join(", ")}.`);
+            }
+            for (const tool of tools) {
+                pi.registerTool({
+                    name: tool.name,
+                    label: tool.title ?? tool.name,
+                    description: tool.description ?? tool.title ?? tool.name,
+                    // omp accepts a plain JSON Schema document (TJsonSchema) for
+                    // extension-authored tools; MCP inputSchema is already one.
+                    parameters: tool.inputSchema as ToolDefinition["parameters"],
+                    strict: false,
+                    execute: async (_toolCallId, args, signal) =>
+                        toAgentToolResult(await connected.call(tool, args as Record<string, unknown>, signal)),
+                });
+            }
+            client = connected;
+        } catch (error) {
+            await connected.close().catch(() => undefined);
+            throw error;
+        }
+    };
+
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        if (shutdownPromise) throw new Error("Cairnkeep MCP bridge is already shutting down.");
+        if (runtimeUninitialized(pi)) return;
+        if (!startPromise) startPromise = start(ctx);
+        await startPromise;
+    });
+
+    pi.on("session_shutdown", async () => {
+        if (!shutdownPromise) {
+            shutdownPromise = (async () => {
+                await startPromise?.catch(() => undefined);
+                await client?.close();
+            })();
+        }
+        await shutdownPromise;
+    });
+}

package/package.json

@@ -1,78 +1,79 @@
 {
-  "name": "@cairnkeep/cli",
-  "version": "2.17.2",
-  "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "cairn": "bin/cairn",
-    "cairn-container": "bin/cairn-container"
-  },
-  "files": [
-    "bin/",
-    "scripts/",
-    "templates/",
-    "claude/",
-    "opencode/",
-    "pi/",
-    "kimi/",
-    "examples/anythingllm/",
-    "examples/overlay-distribution/",
-    "examples/eval/",
-    "containers/",
-    "schemas/",
-    "docs/",
-    "CHANGELOG.md",
-    "CONTRIBUTING.md",
-    "SECURITY.md",
-    "mcp-memory-server/dist/",
-    "mcp-memory-server/scripts/fixtures/compaction-*.json",
-    "mcp-memory-server/package.json",
-    "AGENTS.md"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "agentfs-sdk": "^0.6.4",
-    "yaml": "2.9.0",
-    "zod": "^4.4.3"
-  },
-  "scripts": {
-    "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",
-    "fix:perms": "node scripts/fix-permissions.mjs",
-    "prepack": "npm run build:server && npm run fix:perms",
-    "test": "node scripts/run-repository-tests.mjs",
-    "test:windows": "node scripts/test-windows-native.mjs",
-    "audit:runtime": "node scripts/verify-dependency-security.mjs && npm audit --omit=dev --audit-level=high && npm --prefix mcp-memory-server audit --omit=dev --audit-level=high",
-    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run audit:runtime && npm run build:server && npm test",
-    "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server test --global=false --dry-run=false"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/cairnkeep/cairnkeep.git"
-  },
-  "homepage": "https://github.com/cairnkeep/cairnkeep#readme",
-  "bugs": {
-    "url": "https://github.com/cairnkeep/cairnkeep/issues"
-  },
-  "keywords": [
-    "mcp",
-    "memory",
-    "agent",
-    "claude-code",
-    "codex-cli",
-    "opencode",
-    "qwen-code",
-    "pi-coding-agent",
-    "context",
-    "rag"
-  ],
-  "devDependencies": {
-    "@cyclonedx/cyclonedx-npm": "6.0.1"
-  }
+    "name": "@cairnkeep/cli",
+    "version": "2.18.0",
+    "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
+    "license": "Apache-2.0",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "cairn": "bin/cairn",
+        "cairn-container": "bin/cairn-container"
+    },
+    "files": [
+        "bin/",
+        "scripts/",
+        "templates/",
+        "claude/",
+        "opencode/",
+        "pi/",
+        "kimi/",
+        "omp/",
+        "examples/anythingllm/",
+        "examples/overlay-distribution/",
+        "examples/eval/",
+        "containers/",
+        "schemas/",
+        "docs/",
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "SECURITY.md",
+        "mcp-memory-server/dist/",
+        "mcp-memory-server/scripts/fixtures/compaction-*.json",
+        "mcp-memory-server/package.json",
+        "AGENTS.md"
+    ],
+    "engines": {
+        "node": ">=22"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.30.0",
+        "agentfs-sdk": "^0.6.4",
+        "yaml": "2.9.0",
+        "zod": "^4.4.3"
+    },
+    "scripts": {
+        "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",
+        "fix:perms": "node scripts/fix-permissions.mjs",
+        "prepack": "npm run build:server && npm run fix:perms",
+        "test": "node scripts/run-repository-tests.mjs",
+        "test:windows": "node scripts/test-windows-native.mjs",
+        "audit:runtime": "node scripts/verify-dependency-security.mjs && npm audit --omit=dev --audit-level=high && npm --prefix mcp-memory-server audit --omit=dev --audit-level=high",
+        "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run audit:runtime && npm run build:server && npm test",
+        "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server test --global=false --dry-run=false"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/cairnkeep/cairnkeep.git"
+    },
+    "homepage": "https://github.com/cairnkeep/cairnkeep#readme",
+    "bugs": {
+        "url": "https://github.com/cairnkeep/cairnkeep/issues"
+    },
+    "keywords": [
+        "mcp",
+        "memory",
+        "agent",
+        "claude-code",
+        "codex-cli",
+        "opencode",
+        "qwen-code",
+        "pi-coding-agent",
+        "context",
+        "rag"
+    ],
+    "devDependencies": {
+        "@cyclonedx/cyclonedx-npm": "6.0.1"
+    }
 }

package/scripts/cairn-cli.mjs

@@ -30,6 +30,7 @@ const POSIX_COMMANDS = new Map([
   ["sync", "sync-claude-assets.sh"],
   ["sync-pi", "sync-pi-assets.sh"],
   ["sync-kimi", "sync-kimi-assets.sh"],
+  ["sync-omp", "sync-omp-assets.sh"],
   ["audit-timer", "install-audit-timer.sh"],
   ["completion", "completion.sh"],
 ]);
@@ -44,6 +45,7 @@ Usage:
   cairn sync [--check|--apply] [--live-root DIR]
   cairn sync-pi [--check|--apply] [--live-root DIR]
   cairn sync-kimi [--check|--apply] [--live-root DIR]
+  cairn sync-omp [--check|--apply] [--live-root DIR]
   cairn doctor [--repair]
   cairn trajectory <list|show|prune>
   cairn proposals <create|list|show|apply|doctor>

package/scripts/completion.sh

@@ -13,7 +13,7 @@ _cairn_complete() {
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help"
+  commands="bootstrap setup memory-server sync sync-pi sync-kimi sync-omp doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
@@ -24,6 +24,7 @@ _cairn_complete() {
     sync) COMPREPLY=( $(compgen -W "--apply --live-root" -- "$current") ) ;;
     sync-pi) COMPREPLY=( $(compgen -W "--apply --live-root" -- "$current") ) ;;
     sync-kimi) COMPREPLY=( $(compgen -W "--apply --live-root" -- "$current") ) ;;
+    sync-omp) COMPREPLY=( $(compgen -W "--apply --live-root" -- "$current") ) ;;
     doctor) COMPREPLY=( $(compgen -W "--repair" -- "$current") ) ;;
     trajectory) COMPREPLY=( $(compgen -W "list show prune --json --dry-run" -- "$current") ) ;;
     artifact) COMPREPLY=( $(compgen -W "list show delete prune --kind --session --json --dry-run --include-protected" -- "$current") ) ;;
@@ -94,6 +95,7 @@ _cairn() {
     'sync:install the Claude operating layer'
     'sync-pi:install the Pi trajectory extension and graph prompt'
     'sync-kimi:install the Kimi graph Skill'
+    'sync-omp:install the oh-my-pi memory extension'
     'doctor:check runtime dependencies and endpoints'
     'trajectory:inspect and prune local session trajectories'
     'artifact:inspect, delete, and prune local artifacts'
@@ -124,6 +126,7 @@ _cairn() {
     sync) _arguments '--apply[apply changes]' '--live-root[project Claude root]:directory:_files -/' ;;
     sync-pi) _arguments '--apply[apply changes]' '--live-root[Pi agent root]:directory:_files -/' ;;
     sync-kimi) _arguments '--apply[apply changes]' '--live-root[Kimi Code root]:directory:_files -/' ;;
+    sync-omp) _arguments '--apply[apply changes]' '--live-root[omp agent root]:directory:_files -/' ;;
     doctor) _arguments '--repair[repair trajectory metadata and indexes]' ;;
     trajectory) _values 'trajectory command' list show prune ;;
     artifact)
@@ -188,8 +191,8 @@ EOF
   fish)
     sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 complete -c cairn -f
-for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help
-complete -c cairn -n "not __fish_seen_subcommand_from bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help" -a $command
+for command in bootstrap setup memory-server sync sync-pi sync-kimi sync-omp doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help
+complete -c cairn -n "not __fish_seen_subcommand_from bootstrap setup memory-server sync sync-pi sync-kimi sync-omp doctor trajectory artifact evidence playbook capabilities mcp-tools pack proposals notes eval skill graph memory audit-timer uninstall completion version help" -a $command
 end
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l live-root -r
@@ -197,6 +200,8 @@ complete -c cairn -n "__fish_seen_subcommand_from sync-pi" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync-pi" -l live-root -r
 complete -c cairn -n "__fish_seen_subcommand_from sync-kimi" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync-kimi" -l live-root -r
+complete -c cairn -n "__fish_seen_subcommand_from sync-omp" -l apply
+complete -c cairn -n "__fish_seen_subcommand_from sync-omp" -l live-root -r
 complete -c cairn -n "__fish_seen_subcommand_from bootstrap" -l untracked
 complete -c cairn -n "__fish_seen_subcommand_from setup" -l git -r -a "init existing none"
 complete -c cairn -n "__fish_seen_subcommand_from setup" -l harness -r -a "__CAIRN_HARNESSES__"

package/scripts/lib/omp-capture-stage.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// omp capture staging child for the cairnkeep-capture extension.
+//
+// Reads transcript text on stdin, runs the shared extraction
+// (`node <server-entry> extract <model>`, stdin-piped — transcript text is
+// never interpolated into a shell line), and stages the candidate JSON under
+// <repo>/.planning/memory-staging/ with the exact same filename, JSON, and
+// retention-cap-5 contract as stageCandidates in opencode/plugins/memory-capture.ts.
+//
+// Invoked detached + unref'd by the extension so staging completes even when
+// the agent process exits before extraction returns. Fail-open: always exits 0.
+//
+// Usage: node omp-capture-stage.mjs <repo> <server-entry> <model>
+
+import { spawn } from "node:child_process";
+import { mkdirSync, readdirSync, writeFileSync, unlinkSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const RETENTION_CAP = 5;
+const EXTRACT_TIMEOUT_MS = 120_000;
+
+const [, , repo, serverEntry, model] = process.argv;
+
+function stageCandidates(repoRoot, candidatesJson) {
+  const stagingDir = join(repoRoot, ".planning", "memory-staging");
+  mkdirSync(stagingDir, { recursive: true });
+  const ts = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const stageFile = join(stagingDir, `${ts}.json`);
+  writeFileSync(stageFile, `${candidatesJson}\n`);
+
+  // Keep the staging dir bounded — drop the oldest beyond 5 sessions.
+  const staged = readdirSync(stagingDir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => ({ f, mtime: statSync(join(stagingDir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  for (const { f } of staged.slice(RETENTION_CAP)) {
+    unlinkSync(join(stagingDir, f));
+  }
+  return stageFile;
+}
+
+function runExtract(entry, extractModel, input) {
+  return new Promise((resolvePromise) => {
+    let stdout = "";
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise(stdout);
+    };
+    const child = spawn("node", [entry, "extract", extractModel], { stdio: ["pipe", "pipe", "ignore"] });
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* best-effort kill only */ }
+    }, EXTRACT_TIMEOUT_MS);
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+      if (stdout.length > 1024 * 1024) {
+        stdout = "";
+        try { child.kill("SIGKILL"); } catch { /* best-effort kill only */ }
+      }
+    });
+    child.on("close", finish);
+    child.on("error", finish);
+    child.stdin.on("error", () => {
+      // EPIPE after a failed/terminated child is part of the fail-open path.
+    });
+    child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+
+async function main() {
+  if (!repo || !serverEntry || !model || !existsSync(serverEntry)) return;
+  let input = "";
+  try {
+    for await (const chunk of process.stdin) input += chunk.toString("utf8");
+  } catch {
+    return;
+  }
+  input = input.trim();
+  if (!input) return;
+
+  const candidatesJson = (await runExtract(serverEntry, model, input)).trim();
+  if (!candidatesJson) return;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(candidatesJson);
+  } catch {
+    return;
+  }
+  if (!Array.isArray(parsed.candidates) || parsed.candidates.length === 0) return;
+
+  stageCandidates(repo, candidatesJson);
+}
+
+try {
+  await main();
+} catch {
+  // Fail open — staging is best-effort.
+}
+process.exit(0);