@cairnkeep/cli 2.17.2 → 2.18.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.18.0] - 2026-09-28
+
+### Added
+
+- oh-my-pi (omp) integration: `omp/extensions/cairnkeep-memory.ts` registers
+  the cairn-memory MCP tools as native omp tools (collision-guarded), and
+  `omp/extensions/cairnkeep-capture.ts` stages durable-memory candidates at
+  session stop and surfaces them on the next session start, with a
+  `/cairn-staged` review command. The bridge runs as a node child process so
+  it also works under compiled Bun standalone binaries.
+- `cairn sync-omp` command, bash/zsh/fish completion entries, and
+  `verify-omp-mcp-bridge.mjs` / `verify-omp-capture.mjs` verification gates.
+- Smoke gates for the pi-mcp-bridge child environment: Bun node-shim PATH
+  stripping, `MCP_HTTP_PORT` isolation, and the node child bridge protocol.
+
+### Fixed
+
+- `pi-mcp-bridge` strips Bun `/tmp/bun-node-*` shim dirs from the stdio child
+  environment; grandchildren like `cairn memory-server` spawn a real node.
+- Work-evidence smoke used fixed calendar dates that aged past the retention
+  window; timestamps are relative to the run.
+
+### Documentation
+
+- `docs/harness-compatibility.md`: oh-my-pi (omp) section.
+- `docs/operating.md`: `CAIRN_PI_BRIDGE_COMMAND` / `CAIRN_PI_BRIDGE_ARGS`.
+
+## [2.17.3] - 2026-09-03
+
+### Security
+
+- Refresh the production dependency locks to `fast-uri` 3.1.7 and `qs`
+  6.16.0 so published server and workspace containers do not retain the URI
+  parsing, SSRF, host-confusion, or denial-of-service advisories affecting the
+  versions locked by 2.17.2. Runtime APIs and command behavior are unchanged.
+
 ## [2.17.2] - 2026-09-02
 
 ### Fixed
@@ -525,7 +561,8 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.15.1...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.18.0...HEAD
+[2.18.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.17.3...v2.18.0
 [2.15.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.15.0...v2.15.1
 [2.15.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.14.0...v2.15.0
 [2.14.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.1...v2.14.0

package/docs/harness-compatibility.md

@@ -19,6 +19,7 @@ Cairnkeep commands, hooks or native trajectory capture.
 | Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph and cairn-work Skills | Launcher tested; remote MCP tested with Kimi Code 0.30.0; Skills contract-tested |
 | Qwen Code | Memory MCP, launcher, project `AGENTS.md` durable-context and playbook guidance | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
 | Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, graph and cairn-work prompts | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
+| oh-my-pi (omp) | Memory MCP through maintained local stdio extension (Pi-successor API) | Smoke-tested against the local omp checkout with the deterministic bridge verification |
 | Codex CLI | Project-scoped memory MCP, launcher, and project `AGENTS.md` durable-context and playbook guidance | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
@@ -77,6 +78,52 @@ release, together with Node.js 22/24/26, Bash 3.2, and native Windows. The
 executable paths were distinct; both reported 0.84.1 because that was also the
 registry-current release.
 
+## oh-my-pi (omp)
+
+Run `cairn sync-omp --apply` explicitly to install
+`extensions/cairnkeep-memory.ts` and `extensions/cairnkeep-capture.ts` under
+the omp agent root (default
+`~/.omp/agent`; `PI_CODING_AGENT_DIR` overrides it, matching omp's agent
+directory resolution). Use `--check` for drift. Uninstall removes only that
+owned path, backup-first.
+
+The extension is the Pi memory extension ported to omp's successor extension
+API: it supervises `cairn memory-server` as a local stdio child through the
+same bridge, discovers the effective MCP catalog dynamically, and registers
+each tool natively with omp under its bare MCP name. omp accepts the MCP input
+schema as a plain JSON Schema document and normalizes results to its
+`AgentToolResult` shape, preserving the trusted call metadata in `details`. A
+`cairn-memory` entry in the omp MCP config coexists without collision:
+config-served MCP tools are minted with an `mcp__` name prefix, so the two
+surfaces never claim the same tool name. Server feature gates, capability
+state, and least-authority profiles continue to decide which tools exist.
+
+Startup, calls, results, stderr retention, cancellation, and shutdown are
+bounded. The extension adds tools only: it does not run prompts, activate
+context-pack skills, create an autonomous loop, or add a remote transport.
+`bun scripts/verify-omp-mcp-bridge.mjs` renders, loads, and exercises the
+installed extension against a supervised memory server, including catalog
+parity, the result shape, cancellation, shutdown, orphan-freedom, and
+tool-name collision refusal.
+
+Sync also installs `extensions/cairnkeep-capture.ts`, the omp port of the
+Claude SessionEnd/SessionStart `memory-capture` + `memory-wakeup` hook pair.
+On the first `session_stop` of a main session (the event never fires for
+task/subagent sessions), it converts the persisted branch to transcript text
+(user/assistant text only, capped at 12000 characters keeping the most recent
+turns) and pipes it to a detached staging child that runs the shared
+extraction and writes candidates to `.planning/memory-staging/` — one file
+per session, retention capped at 5 — so staging completes even if the agent
+process exits first. Candidates are staged for review only: writes to AgentFS
+stay agent-gated via the `memory_write` tool. On `session_start` of the main
+session, staged candidates are surfaced through a UI notification and a
+`deliverAs: "nextTurn"` context message injected at the next user turn; the
+`/cairn-staged` command lists the staged files on demand. Both halves are
+fail-open and skip ephemeral side-turn runtimes whose extension actions are
+not initialized. `bun scripts/verify-omp-capture.mjs` exercises the guards,
+transcript shaping, staging contract, retention cap, session de-dupe, wakeup
+injection, and the skip paths.
+
 ## Kimi Code
 
 Kimi Code reads three MCP files, in increasing precedence:

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.17.2
+**Baseline:** Cairnkeep 2.18.0
 **Last reviewed:** 2026-08-19
 
 This map prevents the course from drifting behind the product. It assigns each
@@ -91,6 +91,7 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn sync` | L02 |
 | `cairn sync-pi` | L13 and L23 |
 | `cairn sync-kimi` | L02 |
+| `cairn sync-omp` | L02 |
 | `cairn doctor` | L03; advanced repair in L13-L14 |
 | `cairn playbook` | L25 |
 | `cairn trajectory` | L13 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.17.2
+**Baseline:** Cairnkeep 2.18.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.17.2
+**Tested with:** Cairnkeep 2.18.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.17.2
+**Tested with:** Cairnkeep 2.18.0
 
 ## Outcome
 

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.2
+**Tested with:** Cairnkeep 2.18.0
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.17.2
+**Tested with:** Cairnkeep 2.18.0
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.17.2, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.17.2; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.18.0; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 

package/docs/learning/lessons/L24-okf-exchange.md

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L25-playbooks.md

@@ -1,7 +1,7 @@
 # L25 - Bounded workflow playbooks
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.18.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/operating.md

@@ -461,6 +461,8 @@ vendor or host.
 | `CAIRN_LLM_API_KEY` | API key for the extraction / embeddings endpoint (unset → substring-only memory) |
 | `CAIRN_LLM_API_URL` | Base URL of the OpenAI-compatible endpoint |
 | `CAIRN_LLM_EXTRACTION_MODEL` | Chat model for `memory-capture` extraction |
+| `CAIRN_PI_BRIDGE_COMMAND` | Memory-server command for the `pi-bridge-child` stdio host (default `cairn`) |
+| `CAIRN_PI_BRIDGE_ARGS` | JSON argument array for the bridge child server command (default `["memory-server"]`) |
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.17.2","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.18.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/pi-bridge-child.js

@@ -0,0 +1,109 @@
+import { childEnvironment, connectCairnPiBridge } from "./pi-mcp-bridge.js";
+const STDERR_LIMIT_BYTES = 16 * 1024;
+let stderrTail = "";
+const stderrWrite = process.stderr.write.bind(process.stderr);
+process.stderr.write = ((chunk, ...rest) => {
+    const text = typeof chunk === "string" ? chunk : String(chunk);
+    const next = stderrTail + text;
+    stderrTail = next.length <= STDERR_LIMIT_BYTES ? next : next.slice(next.length - STDERR_LIMIT_BYTES);
+    return stderrWrite(chunk, ...rest);
+});
+function send(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+function fatal(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${JSON.stringify({ type: "error", error: message })}\n`);
+    process.exit(1);
+}
+process.on("uncaughtException", fatal);
+process.on("unhandledRejection", (reason) => fatal(reason));
+async function main() {
+    const cwd = process.argv[2] ?? process.cwd();
+    const command = process.env.CAIRN_PI_BRIDGE_COMMAND ?? "cairn";
+    const args = JSON.parse(process.env.CAIRN_PI_BRIDGE_ARGS ?? '["memory-server"]');
+    const bridge = await connectCairnPiBridge({ cwd, command, args, env: childEnvironment(process.env) });
+    const controllers = new Map();
+    let stdinBuffer = "";
+    let closing = false;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        await bridge.close().catch(() => undefined);
+        process.exit(0);
+    };
+    process.on("SIGTERM", () => void close());
+    process.on("SIGINT", () => void close());
+    process.stdin.on("end", () => void close());
+    async function handle(request) {
+        try {
+            switch (request.type) {
+                case "list": {
+                    send({ type: "result", id: request.id, ok: true, tools: await bridge.listAllTools() });
+                    break;
+                }
+                case "call": {
+                    const controller = new AbortController();
+                    controllers.set(request.id, controller);
+                    try {
+                        const result = await bridge.call(request.tool, request.args ?? {}, { signal: controller.signal });
+                        send({ type: "result", id: request.id, ok: true, result });
+                    }
+                    catch (error) {
+                        send({
+                            type: "result",
+                            id: request.id,
+                            ok: false,
+                            error: error instanceof Error ? error.message : String(error),
+                            stderr: stderrTail,
+                        });
+                    }
+                    finally {
+                        controllers.delete(request.id);
+                    }
+                    break;
+                }
+                case "cancel": {
+                    controllers.get(request.id)?.abort(new Error("cancelled"));
+                    break;
+                }
+                case "close": {
+                    await close();
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            const id = typeof request.id === "number" ? request.id : -1;
+            send({
+                type: "result",
+                id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+                stderr: stderrTail,
+            });
+        }
+    }
+    process.stdin.on("data", (chunk) => {
+        stdinBuffer += chunk.toString("utf8");
+        let newline = stdinBuffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = stdinBuffer.slice(0, newline);
+            stdinBuffer = stdinBuffer.slice(newline + 1);
+            newline = stdinBuffer.indexOf("\n");
+            if (!line.trim())
+                continue;
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            void handle(request);
+        }
+    });
+    send({ type: "ready" });
+}
+main().catch(fatal);

package/mcp-memory-server/dist/pi-mcp-bridge.js

@@ -11,11 +11,23 @@ function positiveInteger(value, fallback, name) {
         throw new Error(`${name} must be a positive integer.`);
     return selected;
 }
-function childEnvironment(source) {
+// Bun-hosted agents (pi, omp) prepend a /tmp/bun-node-* dir whose `node` is
+// Bun itself; grandchildren like `cairn memory-server` spawn real node
+// subprocesses, so those shim dirs must not shadow it.
+const BUN_NODE_SHIM = /\/tmp\/bun-node-[^/:]+$/;
+export function childEnvironment(source) {
     const env = {};
     for (const [name, value] of Object.entries(source)) {
-        if (value !== undefined && name !== "MCP_HTTP_PORT")
-            env[name] = value;
+        if (value === undefined || name === "MCP_HTTP_PORT")
+            continue;
+        if (name === "PATH") {
+            env[name] = value
+                .split(":")
+                .filter((entry) => !BUN_NODE_SHIM.test(entry))
+                .join(":");
+            continue;
+        }
+        env[name] = value;
     }
     return env;
 }

package/mcp-memory-server/package.json

@@ -2,7 +2,7 @@
     "name": "@cairnkeep/memory-server",
     "version": "0.1.0",
     "private": true,
-    "description": "Durable, harness-agnostic memory MCP server for coding agents — the core of Cairnkeep.",
+    "description": "Durable, harness-agnostic memory MCP server for coding agents \u2014 the core of Cairnkeep.",
     "license": "Apache-2.0",
     "type": "module",
     "engines": {
@@ -61,10 +61,12 @@
         "check:playbook": "node scripts/smoke-playbook.mjs",
         "check:notes": "npm run build && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:memory-proposals && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack && npm run check:context-pack-retrieval && npm run check:context-pack-v216-compat && npm run check:context-usage && npm run check:domain-retrieval && npm run check:retrieval-benchmark && npm run check:work-evidence && npm run check:okf && npm run check:playbook",
+        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:memory-proposals && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:pi-bridge-env && npm run check:pi-bridge-child && npm run check:context-pack && npm run check:context-pack-retrieval && npm run check:context-pack-v216-compat && npm run check:context-usage && npm run check:domain-retrieval && npm run check:retrieval-benchmark && npm run check:work-evidence && npm run check:okf && npm run check:playbook",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
-        "test:all": "npm run test:memory"
+        "test:all": "npm run test:memory",
+        "check:pi-bridge-env": "node scripts/smoke-pi-bridge-env.mjs",
+        "check:pi-bridge-child": "node scripts/smoke-pi-bridge-child.mjs"
     },
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",

package/omp/extensions/cairnkeep-capture.ts

@@ -0,0 +1,226 @@
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// omp port of the claude/hooks memory-capture + memory-wakeup pair (D-03/D-04,
+// OCP-01/OCP-05 contracts).
+//
+// CAPTURE: on the first `session_stop` of a main session (the event never
+// fires for task/subagent sessions and is awaited while the process is fully
+// alive), the session branch is converted to transcript text and piped to a
+// DETACHED, unref'd `node scripts/lib/omp-capture-stage.mjs` child that runs
+// the shared `extract` subcommand and stages candidates under
+// .planning/memory-staging/ — so staging survives even if the agent process
+// exits before the extraction call returns. Extraction candidates are staged
+// for review only; writes to AgentFS stay agent-gated via the memory_* tools
+// from cairnkeep-memory.ts.
+//
+// WAKEUP: on `session_start` of the main session (and only when the extension
+// runtime is initialized — omp's title-generation ephemeral agents rebind
+// extensions with uninitialized action stubs), staged candidates are surfaced
+// via a UI notification and a `deliverAs: "nextTurn"` context message injected
+// at the next real user turn. `/cairn-staged` lists staged files on demand.
+//
+// Fail-open everywhere: every guard is a cheap check and every path is
+// try/caught so a throw can never reach the extension runner.
+const CAIRN_ROOT = "@@INFRA_ROOT@@";
+const SERVER_ENTRY = join(CAIRN_ROOT, "mcp-memory-server", "dist", "index.js");
+const STAGE_ENTRY = join(CAIRN_ROOT, "scripts", "lib", "omp-capture-stage.mjs");
+
+const MAX_TEXT_CHARS = 12000;
+const STAGED_MAX_FILES = 5;
+const STAGED_FILE_READ_CAP = 8192;
+const STAGED_CUSTOM_TYPE = "sh.cairnkeep.staged-memory";
+
+// Minimal structural view of omp's persisted SessionEntry (entry.type
+// "message", camelCase role per docs/extensions.md); anything else is skipped.
+type BranchEntry = {
+    type?: string;
+    message?: {
+        role?: string;
+        content?: unknown;
+    };
+};
+
+type SessionStopLike = {
+    type: "session_stop";
+    session_id?: string;
+};
+
+function transcriptText(branch: BranchEntry[]): string {
+    const turns: string[] = [];
+    for (const entry of branch) {
+        if (entry?.type !== "message") continue;
+        const role = entry.message?.role;
+        if (role !== "user" && role !== "assistant") continue;
+        if (!Array.isArray(entry.message?.content)) continue;
+        const text = (entry.message.content as Array<{ type?: string; text?: unknown }>)
+            .filter((block) => block && block.type === "text" && typeof block.text === "string")
+            .map((block) => block.text as string)
+            .join("\n")
+            .trim();
+        if (!text) continue;
+        turns.push(`${role === "user" ? "USER" : "ASSISTANT"}: ${text}`);
+    }
+    let out = turns.join("\n\n");
+    if (out.length > MAX_TEXT_CHARS) out = out.slice(-MAX_TEXT_CHARS);
+    return out;
+}
+
+// Same detection as cairnkeep-memory.ts: omp rebinds extensions to ephemeral
+// side-turn runtimes whose action methods are uninitialized throwing stubs.
+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;
+    }
+}
+
+type StagedCandidate = {
+    file: string;
+    count: number;
+};
+
+// Bounded staged-candidate scan: the STAGED_MAX_FILES most recent *.json
+// files, each read capped, malformed JSON skipped (fail-open).
+function stagedCandidates(repo: string): StagedCandidate[] {
+    const stagingDir = join(repo, ".planning", "memory-staging");
+    if (!existsSync(stagingDir)) return [];
+    const files = readdirSync(stagingDir)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => ({ name, mtime: statSync(join(stagingDir, name)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, STAGED_MAX_FILES)
+        .map(({ name }) => name);
+    const staged: StagedCandidate[] = [];
+    for (const file of files) {
+        try {
+            const path = join(stagingDir, file);
+            if (statSync(path).size > STAGED_FILE_READ_CAP) continue;
+            const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+            const count = Array.isArray((parsed as { candidates?: unknown })?.candidates)
+                ? ((parsed as { candidates: unknown[] }).candidates.length)
+                : 0;
+            if (count > 0) staged.push({ file, count });
+        } catch {
+            // Malformed staged file — skip it, never wedge session start.
+        }
+    }
+    return staged;
+}
+
+export default function cairnCaptureExtension(pi: ExtensionAPI): void {
+    const capturedSessions = new Set<string>();
+
+    pi.on("session_stop", async (event: SessionStopLike, ctx: ExtensionContext) => {
+        try {
+            if (ctx.agent?.kind !== "main") return;
+            const sessionId = typeof event?.session_id === "string" ? event.session_id : "";
+            // One capture attempt per session, no matter how many times
+            // session_stop fires for it (continuation cap).
+            if (!sessionId || capturedSessions.has(sessionId)) return;
+
+            const repo = ctx.cwd;
+            // Cheap guards first, mirroring the claude hook's ordering.
+            if (!existsSync(join(repo, ".agentfs", "project.db"))) return;
+            if (!existsSync(SERVER_ENTRY)) return;
+            if (!existsSync(STAGE_ENTRY)) return;
+            const apiKey = process.env.CAIRN_LLM_API_KEY;
+            const model = process.env.CAIRN_LLM_EXTRACTION_MODEL;
+            if (!apiKey || !model) return;
+
+            // Mark before the async boundary so a re-fire never double-stages.
+            capturedSessions.add(sessionId);
+
+            let text = "";
+            try {
+                text = transcriptText(ctx.sessionManager.getBranch() as BranchEntry[]);
+            } catch {
+                return;
+            }
+            if (!text) return;
+
+            // Detached + unref'd: the staging child outlives the agent process,
+            // so the result lands even if omp exits right after settle.
+            const child = spawn(
+                process.execPath,
+                [STAGE_ENTRY, repo, SERVER_ENTRY, model],
+                { detached: true, stdio: ["pipe", "ignore", "ignore"] },
+            );
+            child.on("error", () => undefined);
+            child.stdin.on("error", () => undefined);
+            child.stdin.write(text);
+            child.stdin.end();
+            child.unref();
+        } catch {
+            // Fail open — never block session settle because capture failed.
+        }
+    });
+
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        try {
+            if (ctx.agent?.kind !== "main") return;
+            if (runtimeUninitialized(pi)) return;
+            const staged = stagedCandidates(ctx.cwd);
+            if (staged.length === 0) return;
+
+            const notice =
+                `${staged.length} memory candidate file(s) staged for review in ` +
+                `.planning/memory-staging/ (${staged.reduce((total, { count }) => total + count, 0)} candidate(s) from ` +
+                "the previous session's transcript). Review them and write accepted ones with the memory_write tool " +
+                "(agent-gated), then remove or rename the staged file. Do not write to AgentFS without that review.";
+            if (ctx.hasUI) ctx.ui.notify(notice, "info");
+            pi.sendMessage(
+                {
+                    customType: STAGED_CUSTOM_TYPE,
+                    content: notice,
+                    attribution: "agent",
+                    display: false,
+                },
+                { deliverAs: "nextTurn" },
+            );
+        } catch {
+            // Fail open — never block session start because wakeup failed.
+        }
+    });
+
+    pi.registerCommand("cairn-staged", {
+        description: "List staged memory candidates awaiting review",
+        handler: async (_args, ctx: ExtensionContext) => {
+            try {
+                const stagingDir = join(ctx.cwd, ".planning", "memory-staging");
+                if (!existsSync(stagingDir)) {
+                    if (ctx.hasUI) ctx.ui.notify("No staged memory candidates (.planning/memory-staging is absent).", "info");
+                    return;
+                }
+                const files = readdirSync(stagingDir)
+                    .filter((name) => name.endsWith(".json"))
+                    .map((name) => ({ name, mtime: statSync(join(stagingDir, name)).mtimeMs }))
+                    .sort((a, b) => b.mtime - a.mtime)
+                    .slice(0, STAGED_MAX_FILES)
+                    .map(({ name }) => name);
+                if (files.length === 0) {
+                    if (ctx.hasUI) ctx.ui.notify("No staged memory candidates.", "info");
+                    return;
+                }
+                const sections = files.map((file) => {
+                    let body: string;
+                    try {
+                        body = readFileSync(join(stagingDir, file), "utf8").slice(0, STAGED_FILE_READ_CAP);
+                    } catch {
+                        body = "(unreadable)";
+                    }
+                    return `### ${file}\n${body}`;
+                });
+                const listing = `Staged memory candidates — review, then accept via memory_write or discard.\n\n${sections.join("\n\n")}`;
+                if (ctx.hasUI) ctx.ui.notify(listing, "info");
+            } catch {
+                // Fail open — command inspection is best-effort.
+            }
+        },
+    });
+}