@cairnkeep/cli 2.9.0 → 2.12.0

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

@@ -0,0 +1,185 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+const DEFAULT_STARTUP_TIMEOUT_MS = 10_000;
+const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+const DEFAULT_STDERR_LIMIT_BYTES = 16 * 1024;
+const DEFAULT_RESULT_LIMIT_BYTES = 4 * 1024 * 1024;
+const MAX_CATALOG_PAGES = 1_000;
+function positiveInteger(value, fallback, name) {
+    const selected = value ?? fallback;
+    if (!Number.isSafeInteger(selected) || selected <= 0)
+        throw new Error(`${name} must be a positive integer.`);
+    return selected;
+}
+function childEnvironment(source) {
+    const env = {};
+    for (const [name, value] of Object.entries(source)) {
+        if (value !== undefined && name !== "MCP_HTTP_PORT")
+            env[name] = value;
+    }
+    return env;
+}
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf8");
+    }
+    catch {
+        throw new Error("MCP result could not be measured safely.");
+    }
+}
+function boundedMessage(error, stderr) {
+    const base = error instanceof Error ? error.message : String(error);
+    const tail = stderr.trim();
+    return tail ? `${base} (server stderr: ${tail})` : base;
+}
+function transportBufferSize(resultLimitBytes) {
+    return Math.min(Math.max(resultLimitBytes + 64 * 1024, resultLimitBytes * 4), 64 * 1024 * 1024);
+}
+function failureText(result) {
+    const text = result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text.trim())
+        .filter(Boolean)
+        .join("; ");
+    return text || "The MCP server reported a tool failure.";
+}
+function piContent(result) {
+    return result.content.map((item) => {
+        if (item.type === "text")
+            return { ...item };
+        if (item.type === "image")
+            return { ...item };
+        throw new Error(`Unsupported MCP result content type: ${item.type}.`);
+    });
+}
+export async function connectCairnPiBridge(options = {}) {
+    const startupTimeoutMs = positiveInteger(options.startupTimeoutMs, DEFAULT_STARTUP_TIMEOUT_MS, "startupTimeoutMs");
+    const callTimeoutMs = positiveInteger(options.callTimeoutMs, DEFAULT_CALL_TIMEOUT_MS, "callTimeoutMs");
+    const stderrLimitBytes = positiveInteger(options.stderrLimitBytes, DEFAULT_STDERR_LIMIT_BYTES, "stderrLimitBytes");
+    const resultLimitBytes = positiveInteger(options.resultLimitBytes, DEFAULT_RESULT_LIMIT_BYTES, "resultLimitBytes");
+    const transport = new StdioClientTransport({
+        command: options.command ?? "cairn",
+        args: options.args ? [...options.args] : ["memory-server"],
+        cwd: options.cwd ?? process.cwd(),
+        env: childEnvironment(options.env ?? process.env),
+        stderr: "pipe",
+        maxBufferSize: transportBufferSize(resultLimitBytes),
+    });
+    const client = new Client({ name: "cairnkeep-pi-bridge", version: "1" }, { capabilities: {} });
+    let state = "idle";
+    let stderr = Buffer.alloc(0);
+    let transportFailure;
+    let catalog = [];
+    let closePromise;
+    transport.stderr?.on("data", (chunk) => {
+        const next = Buffer.concat([stderr, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        stderr = next.byteLength <= stderrLimitBytes ? next : next.subarray(next.byteLength - stderrLimitBytes);
+    });
+    const stderrTail = () => stderr.toString("utf8");
+    const requireReady = () => {
+        if (state !== "ready")
+            throw new Error(`Pi MCP bridge is ${state}; calls require ready state.`);
+    };
+    const discover = async () => {
+        const tools = [];
+        const names = new Set();
+        const cursors = new Set();
+        let cursor;
+        for (let pageNumber = 0; pageNumber < MAX_CATALOG_PAGES; pageNumber += 1) {
+            const page = await client.listTools(cursor ? { cursor } : undefined, { timeout: startupTimeoutMs });
+            if (byteLength(page) > resultLimitBytes)
+                throw new Error("MCP tool catalog exceeds the configured result size limit.");
+            for (const tool of page.tools) {
+                if (names.has(tool.name))
+                    throw new Error(`MCP tool catalog contains duplicate name: ${tool.name}.`);
+                names.add(tool.name);
+                tools.push(tool);
+            }
+            if (!page.nextCursor)
+                return tools;
+            if (cursors.has(page.nextCursor))
+                throw new Error("MCP tool catalog pagination repeated a cursor.");
+            cursors.add(page.nextCursor);
+            cursor = page.nextCursor;
+        }
+        throw new Error("MCP tool catalog exceeded the pagination limit.");
+    };
+    const close = () => {
+        if (closePromise)
+            return closePromise;
+        state = "closing";
+        closePromise = (async () => {
+            try {
+                await client.close();
+            }
+            finally {
+                state = "closed";
+                catalog = [];
+            }
+        })();
+        return closePromise;
+    };
+    state = "starting";
+    try {
+        await client.connect(transport, { timeout: startupTimeoutMs, maxTotalTimeout: startupTimeoutMs });
+        const protocolErrorHandler = transport.onerror;
+        transport.onerror = (error) => {
+            transportFailure = error;
+            protocolErrorHandler?.(error);
+        };
+        const protocolCloseHandler = transport.onclose;
+        transport.onclose = () => {
+            protocolCloseHandler?.();
+            if (state === "starting" || state === "ready") {
+                state = "closed";
+                catalog = [];
+            }
+        };
+        const pid = transport.pid;
+        if (pid !== null)
+            options.onSpawn?.({ pid });
+        catalog = await discover();
+        state = "ready";
+    }
+    catch (error) {
+        await close().catch(() => undefined);
+        throw new Error(`Unable to start local Pi MCP bridge: ${boundedMessage(error, stderrTail())}`, { cause: error });
+    }
+    return {
+        get state() { return state; },
+        async listAllTools() {
+            requireReady();
+            return catalog.map((tool) => structuredClone(tool));
+        },
+        async call(tool, args, callOptions = {}) {
+            requireReady();
+            const discovered = catalog.find(({ name }) => name === tool.name);
+            if (!discovered)
+                throw new Error(`MCP tool was not discovered for this session: ${tool.name}.`);
+            try {
+                const result = await client.callTool({ name: discovered.name, arguments: args }, undefined, { signal: callOptions.signal, timeout: callTimeoutMs, maxTotalTimeout: callTimeoutMs });
+                if (byteLength(result) > resultLimitBytes)
+                    throw new Error("MCP tool result exceeds the configured size limit.");
+                if (result.isError)
+                    throw new Error(failureText(result));
+                const details = {
+                    tool: discovered,
+                    annotations: discovered.annotations,
+                    outputSchema: discovered.outputSchema,
+                    content: result.content,
+                    structuredContent: result.structuredContent,
+                    isError: false,
+                    ...(result._meta ? { _meta: result._meta } : {}),
+                };
+                return { content: piContent(result), details };
+            }
+            catch (error) {
+                const failure = transportFailure && /closed/i.test(error instanceof Error ? error.message : String(error))
+                    ? transportFailure
+                    : error;
+                throw new Error(`Pi MCP call ${discovered.name} failed: ${boundedMessage(failure, stderrTail())}`, { cause: error });
+            }
+        },
+        close,
+    };
+}

package/mcp-memory-server/dist/platform-security.js

@@ -0,0 +1,102 @@
+import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
+import { rename } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+function currentWindowsSid() {
+    const result = spawnSync("whoami.exe", ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true });
+    if (result.status !== 0)
+        throw new Error("Unable to resolve the current Windows security identity.");
+    const match = result.stdout.match(/"(S-1-[0-9-]+)"/i);
+    if (!match)
+        throw new Error("Unable to resolve the current Windows security identity.");
+    return match[1];
+}
+export function hardenPrivatePath(path) {
+    if (process.platform !== "win32") {
+        chmodSync(path, lstatSync(path).isDirectory() ? 0o700 : 0o600);
+        return;
+    }
+    const sid = currentWindowsSid();
+    const args = [
+        path,
+        "/inheritance:r",
+        "/grant:r", `*${sid}:(F)`,
+        "/grant:r", "*S-1-5-18:(F)",
+        "/grant:r", "*S-1-5-32-544:(F)",
+    ];
+    const result = spawnSync("icacls.exe", args, { encoding: "utf8", windowsHide: true });
+    if (result.status !== 0)
+        throw new Error("Unable to restrict Windows ACLs for private Cairnkeep state.");
+}
+export function privatePathIsSafe(path) {
+    if (!existsSync(path))
+        return false;
+    const info = lstatSync(path);
+    if (info.isSymbolicLink())
+        return false;
+    if (process.platform !== "win32")
+        return (info.mode & 0o077) === 0;
+    const script = [
+        "$p=$env:CK_INTERNAL_PRIVATE_PATH",
+        "$me=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value",
+        "$ok=@($me,'S-1-5-18','S-1-5-32-544')",
+        "$acl=Get-Acl -LiteralPath $p",
+        "foreach($a in $acl.Access){",
+        "if($a.AccessControlType -eq 'Allow'){",
+        "try{$sid=$a.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value}catch{exit 1}",
+        "if($ok -notcontains $sid){exit 1}",
+        "}",
+        "}",
+        "exit 0",
+    ].join(";");
+    const result = spawnSync("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], {
+        encoding: "utf8",
+        windowsHide: true,
+        env: { ...process.env, CK_INTERNAL_PRIVATE_PATH: path },
+    });
+    return result.status === 0;
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+export async function atomicReplace(source, destination) {
+    if (process.platform === "win32") {
+        let lastError = "Windows atomic replacement failed.";
+        for (let attempt = 0; attempt < 12; attempt += 1) {
+            if (!existsSync(destination)) {
+                try {
+                    await rename(source, destination);
+                    return;
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error.message : String(error);
+                }
+            }
+            else {
+                const backup = `${destination}.replace-backup-${randomUUID()}`;
+                const result = spawnSync("powershell.exe", [
+                    "-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
+                    "[IO.File]::Replace($env:CK_INTERNAL_ATOMIC_SOURCE,$env:CK_INTERNAL_ATOMIC_DESTINATION,$env:CK_INTERNAL_ATOMIC_BACKUP,$true)",
+                ], {
+                    encoding: "utf8",
+                    windowsHide: true,
+                    env: {
+                        ...process.env,
+                        CK_INTERNAL_ATOMIC_SOURCE: source,
+                        CK_INTERNAL_ATOMIC_DESTINATION: destination,
+                        CK_INTERNAL_ATOMIC_BACKUP: backup,
+                    },
+                });
+                if (result.status === 0) {
+                    rmSync(backup, { force: true });
+                    return;
+                }
+                rmSync(backup, { force: true });
+                lastError = result.stderr.trim() || result.stdout.trim() || lastError;
+            }
+            await delay(25 * (attempt + 1));
+        }
+        throw new Error(lastError);
+    }
+    await rename(source, destination);
+}

package/mcp-memory-server/dist/skill-store.js

@@ -1,10 +1,11 @@
 import { createHash, randomBytes } from "node:crypto";
-import { constants, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { constants, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { canonicalDigest } from "./eval-schema.js";
 import { EvalProcessError, runBoundedJsonProcess } from "./eval-process.js";
 import { noteNodeSchema } from "./node-schema.js";
 import { getNoteLayout, listAddressedNotes } from "./note-store.js";
+import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
 import { MAX_SKILL_BYTES, SKILL_SCHEMA_VERSION, skillAdapterConfigSchema, skillApplicationSchema, skillCandidateSchema, skillEvaluationSchema, skillProposalRequestSchema, skillProposalResponseSchema, skillProposalSchema, skillRelativePathSchema, } from "./skill-schema.js";
 const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024;
 const PROTECTED_ADAPTER_ENVIRONMENT = new Set([
@@ -38,10 +39,21 @@ function isContained(root, candidate) {
     const path = relative(root, candidate);
     return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
 }
+function pathCrossesSymlink(path) {
+    const absolute = resolve(path);
+    const root = parse(absolute).root;
+    let cursor = root;
+    for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
+        cursor = join(cursor, segment);
+        if (lstatSync(cursor).isSymbolicLink())
+            return true;
+    }
+    return false;
+}
 function requireProjectRoot(projectRoot) {
     const absolute = resolve(projectRoot);
     const info = lstatSync(absolute);
-    if (info.isSymbolicLink() || !info.isDirectory() || realpathSync(absolute) !== absolute) {
+    if (!info.isDirectory() || pathCrossesSymlink(absolute)) {
         throw new Error("Project root must be a real, non-symlink directory.");
     }
     return absolute;
@@ -49,10 +61,10 @@ function requireProjectRoot(projectRoot) {
 function privateDirectory(path) {
     mkdirSync(path, { recursive: true, mode: 0o700 });
     const info = lstatSync(path);
-    if (info.isSymbolicLink() || !info.isDirectory() || realpathSync(path) !== path) {
+    if (!info.isDirectory() || pathCrossesSymlink(path)) {
         throw new Error(`Unsafe skill state directory: ${path}`);
     }
-    chmodSync(path, 0o700);
+    hardenPrivatePath(path);
 }
 export function getSkillStore(projectRoot = process.cwd(), create = true) {
     const rootProject = requireProjectRoot(projectRoot);
@@ -97,12 +109,13 @@ function atomicWrite(path, value) {
     finally {
         closeSync(descriptor);
     }
-    chmodSync(temporary, 0o600);
+    hardenPrivatePath(temporary);
     renameSync(temporary, path);
+    hardenPrivatePath(path);
 }
 function readJson(path) {
     const info = lstatSync(path);
-    if (info.isSymbolicLink() || !info.isFile() || info.size > MAX_ARTIFACT_BYTES || (info.mode & 0o077) !== 0) {
+    if (info.isSymbolicLink() || !info.isFile() || info.size > MAX_ARTIFACT_BYTES || !privatePathIsSafe(path)) {
         throw new Error(`Unsafe skill artifact: ${path}`);
     }
     const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
@@ -117,7 +130,7 @@ function listJson(directory, parse) {
     if (!existsSync(directory))
         return [];
     const info = lstatSync(directory);
-    if (info.isSymbolicLink() || !info.isDirectory() || (info.mode & 0o077) !== 0)
+    if (info.isSymbolicLink() || !info.isDirectory() || !privatePathIsSafe(directory))
         throw new Error("Unsafe skill artifact directory.");
     return [...new Set(readdirSync(directory))]
         .filter((name) => /^[a-z0-9][a-z0-9._-]{0,127}\.json$/.test(name))
@@ -315,8 +328,10 @@ function loadAdapterConfig(path) {
     if (!isAbsolute(config.command.program))
         throw new Error("Skill adapter program must be an absolute path.");
     const programInfo = lstatSync(config.command.program);
-    if (programInfo.isSymbolicLink() || !programInfo.isFile() || (programInfo.mode & 0o111) === 0
-        || realpathSync(config.command.program) !== config.command.program) {
+    const windowsRunnable = /\.(?:cjs|mjs|js|exe|com)$/i.test(config.command.program);
+    if (!programInfo.isFile()
+        || pathCrossesSymlink(config.command.program)
+        || (process.platform === "win32" ? !windowsRunnable : (programInfo.mode & 0o111) === 0)) {
         throw new Error("Skill adapter program must be a real executable file.");
     }
     return { config, digest: canonicalDigest(config), program_digest: sha256File(config.command.program) };
@@ -502,7 +517,7 @@ export function applySkillProposal(options) {
         rolled_back_at: null,
     });
     writeFileSync(backupPath, target.content, { encoding: "utf8", mode: 0o600, flag: "wx" });
-    chmodSync(backupPath, 0o600);
+    hardenPrivatePath(backupPath);
     try {
         atomicWriteTarget(target.path, proposal.candidate_content, proposal.target_mode);
         if (sha256(readFileSync(target.path)) !== proposal.candidate_content_digest) {
@@ -563,7 +578,7 @@ export function rollbackSkillApplication(options) {
     const backup = resolve(store.project_root, application.backup_path);
     const backupInfo = lstatSync(backup);
     if (!isContained(store.backups, backup) || backupInfo.isSymbolicLink() || !backupInfo.isFile()
-        || backupInfo.size > MAX_SKILL_BYTES || (backupInfo.mode & 0o077) !== 0) {
+        || backupInfo.size > MAX_SKILL_BYTES || !privatePathIsSafe(backup)) {
         throw new Error("Skill backup is missing or unsafe.");
     }
     const original = readFileSync(backup, "utf8");

package/mcp-memory-server/package.json

@@ -47,10 +47,11 @@
         "check:skill-lifecycle": "node scripts/smoke-skill-lifecycle.mjs",
         "check:graph-cli": "node scripts/smoke-graph-cli.mjs",
         "check:mcp-trust": "node scripts/smoke-mcp-trust.mjs",
+        "check:pi-mcp-bridge": "node scripts/smoke-pi-mcp-bridge.mjs",
         "check:context-pack": "node scripts/smoke-context-pack.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: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:context-pack",
+        "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: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",
         "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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.9.0",
+  "version": "2.12.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,7 +9,7 @@
   },
   "bin": {
     "cairn": "bin/cairn",
-    "cairn-container": "scripts/cairn-container"
+    "cairn-container": "bin/cairn-container"
   },
   "files": [
     "bin/",
@@ -43,9 +43,10 @@
   },
   "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": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
+    "fix:perms": "node scripts/fix-permissions.mjs",
     "prepack": "npm run build:server && npm run fix:perms",
-    "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
+    "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"
@@ -63,6 +64,7 @@
     "memory",
     "agent",
     "claude-code",
+    "codex-cli",
     "opencode",
     "qwen-code",
     "pi-coding-agent",

package/pi/extensions/cairnkeep-memory.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CAIRN_ROOT = "@@INFRA_ROOT@@";
+const BRIDGE_ENTRY = join(CAIRN_ROOT, "mcp-memory-server", "dist", "pi-mcp-bridge.js");
+
+type BridgeModule = typeof import("../../mcp-memory-server/dist/pi-mcp-bridge.js");
+type Bridge = Awaited<ReturnType<BridgeModule["connectCairnPiBridge"]>>;
+
+function existingToolNames(pi: ExtensionAPI): Set<string> {
+    return new Set(pi.getAllTools().map((tool) => tool.name));
+}
+
+export default function cairnMemoryExtension(pi: ExtensionAPI): void {
+    let bridge: Bridge | undefined;
+    let startPromise: Promise<void> | undefined;
+    let shutdownPromise: Promise<void> | undefined;
+
+    const start = async (ctx: ExtensionContext): Promise<void> => {
+        const module = await import(pathToFileURL(BRIDGE_ENTRY).href) as BridgeModule;
+        const connected = await module.connectCairnPiBridge({ cwd: ctx.cwd, env: { ...process.env } });
+        try {
+            const tools = await connected.listAllTools();
+            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 Pi 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,
+                    parameters: tool.inputSchema,
+                    execute: async (_callId, args, signal) => connected.call(tool, args, { signal }),
+                });
+            }
+            bridge = 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 (!startPromise) startPromise = start(ctx);
+        await startPromise;
+    });
+
+    pi.on("session_shutdown", async () => {
+        if (!shutdownPromise) {
+            shutdownPromise = (async () => {
+                await startPromise?.catch(() => undefined);
+                await bridge?.close();
+            })();
+        }
+        await shutdownPromise;
+    });
+}

package/schemas/cairnkeep-setup-policy.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/cairnkeep-setup-policy.schema.json",
+  "title": "Cairnkeep guided setup policy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "defaults", "constraints"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "git": {"enum": ["init", "existing", "none"]},
+        "harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
+        },
+        "memory": {"enum": ["local", "none"]}
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "git": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["init", "existing", "none"]}
+        },
+        "harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
+        },
+        "required_harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
+        },
+        "memory": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["local", "none"]}
+        }
+      }
+    }
+  }
+}

package/schemas/cairnkeep-setup.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/cairnkeep-setup.schema.json",
+  "title": "Cairnkeep project setup state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "cairnkeep_version", "git", "memory", "harnesses", "assets"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "cairnkeep_version": {"type": "string", "minLength": 1, "maxLength": 128},
+    "git": {"enum": ["init", "existing", "none"]},
+    "memory": {"enum": ["local", "none"]},
+    "harnesses": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
+    },
+    "assets": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^\\.(?:ai|planning|agentfs|codex)/(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/-]+$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["digest", "mode", "template"],
+        "properties": {
+          "digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "mode": {"type": "integer", "minimum": 0, "maximum": 511},
+          "template": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"}
+        }
+      }
+    }
+  }
+}

package/scripts/bootstrap.sh

@@ -53,11 +53,9 @@ install_file() {
 }
 
 # .ai/ launchers + env
-install_file "$TPL/start-claude.sh.template"   "$target/.ai/start-claude.sh"   0755
-install_file "$TPL/start-opencode.sh.template" "$target/.ai/start-opencode.sh" 0755
-install_file "$TPL/start-pi.sh.template"       "$target/.ai/start-pi.sh"       0755
-install_file "$TPL/start-kimi.sh.template"     "$target/.ai/start-kimi.sh"     0755
-install_file "$TPL/start-qwen.sh.template"     "$target/.ai/start-qwen.sh"     0755
+while IFS=$'\t' read -r template destination mode; do
+  install_file "$TPL/$template" "$target/$destination" "0$mode"
+done < <(node "$CAIRN_ROOT/scripts/harness-registry.mjs" bootstrap-assets)
 install_file "$TPL/env.example.template"       "$target/.ai/env.example"       0644
 install_file "$TPL/trajectory-redaction.json.template" "$target/.ai/trajectory-redaction.json" 0644
 install_file "$TPL/capabilities.json.template" "$target/.ai/capabilities.json" 0600
@@ -100,13 +98,7 @@ fi
 
 echo
 echo "Cairnkeep bootstrapped into $target"
-echo "Next steps (full guide: docs/operating.md):"
-echo "  1. cp .ai/env.example .ai/.env  and edit"
-echo "  2. Register the memory server: claude mcp add cairn-memory -s user -- cairn memory-server"
-echo "  3. Install the operating layer (commands/agents/hooks): cairn sync --apply"
-echo "     For Pi trajectory + /graphify, also run: cairn sync-pi --apply"
-echo "     For Kimi /graphify, also run: cairn sync-kimi --apply"
-echo "     From a source clone, use bin/cairn in place of cairn."
-echo "  4. Launch: $target/.ai/start-claude.sh"
-echo "     Kimi memory-client launch: $target/.ai/start-kimi.sh"
-echo "     Qwen memory-client launch: $target/.ai/start-qwen.sh"
+echo "Codex: run 'cairn setup' in the project and select Codex; then review trust and run .ai/start-codex.sh"
+echo "Claude: claude mcp add cairn-memory -s user -- cairn memory-server; cairn sync --apply"
+echo "Optional project overrides: cp .ai/env.example .ai/.env"
+echo "For new projects, prefer 'cairn setup'; guide: docs/quickstart.md"