@cairnkeep/cli 2.9.0 → 2.12.0

package/scripts/cairn-cli.mjs

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { runWindowsCommand, powershellCompletion } from "./windows-platform.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const NODE_COMMANDS = new Map([
+  ["memory-server", "index.js"],
+  ["trajectory", "trajectory-cli.js"],
+  ["artifact", "artifact-cli.js"],
+  ["capabilities", "capability-cli.js"],
+  ["mcp-tools", "mcp-tool-cli.js"],
+  ["pack", "context-pack-cli.js"],
+  ["notes", "note-cli.js"],
+  ["eval", "eval-cli.js"],
+  ["skill", "skill-cli.js"],
+  ["graph", "graph-cli.js"],
+]);
+
+const POSIX_COMMANDS = new Map([
+  ["bootstrap", "bootstrap.sh"],
+  ["doctor", "doctor.sh"],
+  ["uninstall", "uninstall.sh"],
+  ["memory", "memory-store.sh"],
+  ["sync", "sync-claude-assets.sh"],
+  ["sync-pi", "sync-pi-assets.sh"],
+  ["sync-kimi", "sync-kimi-assets.sh"],
+  ["audit-timer", "install-audit-timer.sh"],
+  ["completion", "completion.sh"],
+]);
+
+export const USAGE = `cairn — Cairnkeep CLI
+
+Usage:
+  cairn bootstrap [--untracked] [path]
+  cairn setup PATH --git init|existing|none --harness LIST --memory local|none [--policy PATH] --yes [--json]
+  cairn memory-server
+  cairn sync [--check|--apply] [--live-root DIR]
+  cairn sync-pi [--check|--apply] [--live-root DIR]
+  cairn sync-kimi [--check|--apply] [--live-root DIR]
+  cairn doctor [--repair]
+  cairn trajectory <list|show|prune>
+  cairn artifact <list|show|delete|prune>
+  cairn capabilities <list|status|enable|disable|reset|logging>
+  cairn mcp-tools <list|status|set|reset>
+  cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>
+  cairn notes <distill|search-error|promote|doctor>
+  cairn eval <validate|run|ablate|report|prune|delete>
+  cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
+  cairn graph <build|query|status|diff|explain|path>
+  cairn memory <path|export|import>
+  cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--purge-packs] [PROJECT ...]
+  cairn completion bash|zsh|fish|powershell
+  cairn version
+  cairn help
+
+Native Windows support does not require WSL or Git Bash. Windows x64 is the
+supported native target; Windows ARM64 currently runs through x64 emulation.`;
+
+function run(executable, args, options = {}) {
+  const result = spawnSync(executable, args, { stdio: "inherit", ...options });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+function version() {
+  const pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
+  console.log(`cairnkeep ${pkg.version}`);
+}
+
+export async function main(argv) {
+  const [command = "help", ...args] = argv;
+
+  if (["help", "--help", "-h"].includes(command)) {
+    console.log(USAGE);
+    return;
+  }
+  if (["version", "--version", "-v"].includes(command)) {
+    version();
+    return;
+  }
+
+  const nodeEntry = NODE_COMMANDS.get(command);
+  if (nodeEntry) {
+    // Preserve the historical dispatcher contract: child Node resolution comes
+    // from PATH, which supports managed runtimes and test/probe wrappers.
+    run("node", [resolve(ROOT, "mcp-memory-server", "dist", nodeEntry), ...args]);
+    return;
+  }
+
+  if (command === "completion" && args[0] === "powershell") {
+    process.stdout.write(powershellCompletion());
+    return;
+  }
+
+  if (command === "setup" && process.platform !== "win32") {
+    const { runSetup } = await import("./setup.mjs");
+    process.exitCode = await runSetup(args);
+    return;
+  }
+
+  if (process.platform === "win32") {
+    const handled = await runWindowsCommand({ command, args, root: ROOT });
+    if (handled) return;
+  } else {
+    const script = POSIX_COMMANDS.get(command);
+    if (script) {
+      run(resolve(ROOT, "scripts", script), args);
+      return;
+    }
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.error(USAGE);
+  process.exitCode = 2;
+}

package/scripts/cairn-container-cli.mjs

@@ -0,0 +1,121 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename, dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const USAGE = `Usage:
+  cairn-container stdio [--image IMAGE] [--volume VOLUME]
+  cairn-container http --token-file FILE [--port PORT] [--name NAME]
+                       [--allowed-hosts HOSTS] [--image IMAGE]
+                       [--volume VOLUME] [--env-file FILE]
+  cairn-container workspace --repo PATH [--mode sandbox|shared]
+                            [--image IMAGE] [--data-volume VOLUME]
+                            [--workspace-volume VOLUME] [--home-volume VOLUME]
+                            [--env-file FILE] [--secret NAME=FILE]... [--] [COMMAND...]`;
+
+function options(args) {
+  const values = new Map();
+  const rest = [];
+  const valued = new Set(["--image", "--volume", "--token-file", "--port", "--name", "--allowed-hosts", "--env-file", "--repo", "--mode", "--data-volume", "--workspace-volume", "--home-volume", "--secret"]);
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--") { rest.push(...args.slice(index + 1)); break; }
+    if (!args[index].startsWith("--")) { rest.push(...args.slice(index)); break; }
+    if (!valued.has(args[index])) throw new Error(`unknown option: ${args[index]}`);
+    if (index + 1 >= args.length) throw new Error(`${args[index]} requires a value`);
+    const value = args[++index];
+    if (args[index - 1] === "--secret") values.set("--secret", [...(values.get("--secret") ?? []), value]);
+    else values.set(args[index - 1], value);
+  }
+  return { values, rest };
+}
+
+function regularFile(path) {
+  const absolute = resolve(path);
+  if (!existsSync(absolute)) throw new Error(`not a regular file: ${path}`);
+  const info = lstatSync(absolute);
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error(`refusing non-regular or symlink file: ${path}`);
+  if (process.platform === "win32") {
+    const script = "$m=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value;$a=Get-Acl -LiteralPath $args[0];$ok=@($m,'S-1-5-18','S-1-5-32-544');foreach($e in $a.Access){if($e.AccessControlType -eq 'Allow'){$s=$e.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value;if($ok -notcontains $s){exit 1}}};exit 0";
+    const acl = spawnSync("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script, absolute], { stdio: "ignore", windowsHide: true });
+    if (acl.status !== 0) throw new Error(`secret file ACL must be restricted to the current user and system administrators: ${path}`);
+  }
+  return absolute;
+}
+
+function execute(engine, args) {
+  const result = spawnSync(engine, args, { stdio: "inherit", windowsHide: true });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+function baseArgs() {
+  return ["run", "--rm", "--userns=keep-id:uid=10001,gid=10001", "--cap-drop=all", "--security-opt=no-new-privileges", "--read-only", "--tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777"];
+}
+
+export function runNativeContainer(args, root = ROOT, executor = execute) {
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+  const engine = process.env.CONTAINER_ENGINE || "podman.exe";
+  const serverImage = process.env.CAIRNKEEP_CONTAINER_IMAGE || `ghcr.io/cairnkeep/cairnkeep:${pkg.version}`;
+  const workspaceImage = process.env.CAIRNKEEP_WORKSPACE_IMAGE || `ghcr.io/cairnkeep/cairnkeep-workspace:${pkg.version}`;
+  const [command = "help", ...commandArgs] = args;
+  if (["help", "-h", "--help"].includes(command)) { console.log(USAGE); return; }
+  const { values, rest } = options(commandArgs);
+  const common = baseArgs();
+  if (command === "stdio") {
+    executor(engine, [...common, "-i", "--volume", `${values.get("--volume") || "cairnkeep-data"}:/data:Z,U`, values.get("--image") || serverImage, "stdio"]);
+    return;
+  }
+  if (command === "http") {
+    if (!values.get("--token-file")) throw new Error("http mode requires --token-file");
+    const token = regularFile(values.get("--token-file"));
+    const port = values.get("--port") || "7801";
+    if (!/^\d+$/.test(port)) throw new Error(`invalid port: ${port}`);
+    const hosts = values.get("--allowed-hosts") || `localhost:${port},127.0.0.1:${port},localhost:7801,127.0.0.1:7801`;
+    const extra = values.get("--env-file") ? ["--env-file", regularFile(values.get("--env-file"))] : [];
+    executor(engine, [...common, "--detach", "--replace", "--name", values.get("--name") || "cairnkeep", ...extra,
+      "--publish", `127.0.0.1:${port}:7801`, "--volume", `${values.get("--volume") || "cairnkeep-data"}:/data:Z,U`,
+      "--volume", `${token}:/run/secrets/http-token:ro,Z`, "--env", "MCP_HTTP_HOST=0.0.0.0", "--env", "MCP_HTTP_PORT=7801",
+      "--env", `CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=${hosts}`, "--env", "CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token",
+      values.get("--image") || serverImage, "http"]);
+    return;
+  }
+  if (command === "workspace") {
+    if (!values.get("--repo")) throw new Error("workspace mode requires --repo");
+    const repo = resolve(values.get("--repo"));
+    if (!existsSync(repo) || !lstatSync(repo).isDirectory()) throw new Error(`not a directory: ${repo}`);
+    const mode = values.get("--mode") || "sandbox";
+    if (!["sandbox", "shared"].includes(mode)) throw new Error("--mode must be sandbox or shared");
+    const slug = basename(repo).toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    const id = createHash("sha256").update(repo).digest("hex").slice(0, 12);
+    const workspace = values.get("--workspace-volume") || `cairnkeep-workspace-${slug}-${id}`;
+    const mounts = mode === "shared" ? ["--volume", `${repo}:/workspace:rw,Z`] : ["--volume", `${repo}:/source:ro,Z`, "--volume", `${workspace}:/workspace:Z,U`];
+    const secrets = [];
+    for (const specification of values.get("--secret") ?? []) {
+      const index = specification.indexOf("=");
+      if (index < 1) throw new Error("--secret requires NAME=FILE");
+      const name = specification.slice(0, index);
+      if (!/^[A-Z0-9_]+$/.test(name)) throw new Error(`invalid secret variable name: ${name}`);
+      const file = regularFile(specification.slice(index + 1));
+      const target = name.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+      secrets.push("--volume", `${file}:/run/secrets/${target}:ro,Z`, "--env", `${name}_FILE=/run/secrets/${target}`);
+    }
+    const envFile = values.get("--env-file") ? ["--env-file", regularFile(values.get("--env-file"))] : [];
+    executor(engine, [...common, "-i", "--volume", `${values.get("--data-volume") || "cairnkeep-data"}:/data:Z,U`,
+      "--volume", `${values.get("--home-volume") || "cairnkeep-home"}:/home/cairn:Z,U`, "--env", `CAIRN_WORKSPACE_MODE=${mode}`,
+      ...mounts, ...envFile, ...secrets, values.get("--image") || workspaceImage, ...(rest.length ? rest : ["bash"])]);
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}
+
+export async function main(args) {
+  if (process.platform !== "win32") {
+    const result = spawnSync(resolve(ROOT, "scripts", "cairn-container"), args, { stdio: "inherit" });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  runNativeContainer(args);
+}

package/scripts/cairn-hook.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SERVER = join(ROOT, "mcp-memory-server", "dist", "index.js");
+const TRAJECTORY = join(ROOT, "mcp-memory-server", "dist", "trajectory-cli.js");
+const ARTIFACT = join(ROOT, "mcp-memory-server", "dist", "artifact-cli.js");
+const CAPABILITY = join(ROOT, "mcp-memory-server", "dist", "capability-cli.js");
+
+function enabled(name) {
+  return /^(1|true|yes|on)$/i.test(String(process.env[name] ?? "").trim());
+}
+
+async function stdin() {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) input += chunk;
+  return input;
+}
+
+function json(input) {
+  try { return JSON.parse(input); } catch { return {}; }
+}
+
+function node(entry, args = [], options = {}) {
+  return spawnSync(process.execPath, [entry, ...args], { encoding: "utf8", timeout: 3000, windowsHide: true, ...options });
+}
+
+function hookOutput(event, prefix, context) {
+  if (!context.trim()) return;
+  process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: `${prefix}\n\n${context.trim()}` } })}\n`);
+}
+
+async function wakeup() {
+  const repo = process.cwd();
+  const projectDb = join(repo, ".agentfs", "project.db");
+  const wiki = join(repo, ".planning", "wiki", "index.md");
+  if (!existsSync(projectDb) && !existsSync(wiki) && !enabled("CAIRN_COMPACTION_CAPTURE")) return;
+  if (existsSync(projectDb) && existsSync(SERVER)) {
+    const result = node(SERVER, ["wakeup"]);
+    if (result.stdout) process.stdout.write(`## Project memory (AgentFS)\n${result.stdout}`);
+  }
+  if (existsSync(wiki)) process.stdout.write(`\n## Wiki index\n${readFileSync(wiki, "utf8")}\n`);
+  const contradictions = join(repo, ".planning", "wiki", "CONTRADICTIONS.md");
+  if (existsSync(contradictions)) {
+    const text = readFileSync(contradictions, "utf8");
+    const open = text.match(/<!-- wiki:contradictions:open:start -->([\s\S]*?)<!-- wiki:contradictions:open:end -->/)?.[1] ?? "";
+    const hard = open.split(/\r?\n/).filter((line) => /severity:\s*hard/i.test(line));
+    if (hard.length) process.stdout.write(`\n## Open HARD contradictions — resolve before dependent work\n${hard.join("\n")}\n`);
+  }
+  const staging = join(repo, ".planning", "memory-staging");
+  if (existsSync(staging)) {
+    const count = readdirSync(staging).filter((name) => name.endsWith(".json")).length;
+    if (count) process.stdout.write(`\n## Staged memory candidates (${count} session(s)) — UNREVIEWED\nRun /memory-review to accept or discard them.\n`);
+  }
+  if (enabled("CAIRN_COMPACTION_CAPTURE") && existsSync(ARTIFACT)) {
+    const payload = json(await stdin());
+    const args = ["recover", repo];
+    if (/^[A-Za-z0-9._:/-]{1,160}$/.test(payload.session_id ?? "")) args.push("--session-ref", `claude-code:${payload.session_id}`);
+    const result = node(ARTIFACT, args);
+    if (result.stdout?.trim()) process.stdout.write(`\n${result.stdout}`);
+  }
+}
+
+async function capture() {
+  const repo = process.cwd();
+  const input = json(await stdin());
+  const transcript = typeof input.transcript_path === "string" ? resolve(input.transcript_path) : "";
+  if (!transcript || !existsSync(transcript)) return;
+  if (enabled("CAIRN_TRAJECTORY_CAPTURE") && existsSync(TRAJECTORY)) node(TRAJECTORY, ["capture-claude", transcript, repo]);
+  if (!existsSync(join(repo, ".agentfs", "project.db")) || !existsSync(SERVER)
+      || !process.env.CAIRN_LLM_API_KEY || !process.env.CAIRN_LLM_EXTRACTION_MODEL) return;
+  const helper = join(ROOT, "scripts", "transcript-to-text.mjs");
+  const text = node(helper, [transcript]);
+  if (!text.stdout?.trim()) return;
+  const result = node(SERVER, ["extract", process.env.CAIRN_LLM_EXTRACTION_MODEL], { input: text.stdout, timeout: 20_000 });
+  const candidates = json(result.stdout);
+  if (!Array.isArray(candidates.candidates) || candidates.candidates.length === 0) return;
+  const staging = join(repo, ".planning", "memory-staging");
+  mkdirSync(staging, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  writeFileSync(join(staging, `${stamp}.json`), `${JSON.stringify(candidates)}\n`, { mode: 0o600 });
+  const files = readdirSync(staging).filter((name) => name.endsWith(".json"))
+    .map((name) => ({ name, mtime: statSync(join(staging, name)).mtimeMs })).sort((a, b) => b.mtime - a.mtime);
+  for (const old of files.slice(5)) rmSync(join(staging, old.name), { force: true });
+}
+
+async function compact() {
+  if (!enabled("CAIRN_COMPACTION_CAPTURE") || !existsSync(ARTIFACT)) return;
+  const input = await stdin();
+  const version = spawnSync("claude", ["--version"], { encoding: "utf8", timeout: 2000, windowsHide: true }).stdout?.match(/\d+\.\d+\.\d+/)?.[0] ?? "unknown";
+  node(ARTIFACT, ["capture-claude", process.cwd(), "--harness-version", version], { input });
+}
+
+async function recall() {
+  const repo = process.cwd();
+  const input = json(await stdin());
+  const file = input.tool_input?.file_path || input.tool_input?.path;
+  if (typeof file !== "string") return;
+  const base = basename(file);
+  const stem = base.replace(/\.[^.]+$/, "");
+  if (stem.length < 4) return;
+  const sections = [];
+  if (existsSync(join(repo, ".agentfs", "project.db")) && existsSync(SERVER)) {
+    const result = node(SERVER, ["wakeup"]);
+    const hits = (result.stdout ?? "").split(/\r?\n/).filter((line) => line.toLowerCase().includes(stem.toLowerCase())).slice(0, 8);
+    if (hits.length) sections.push(`## Relevant project memory for ${base}\n\n${hits.join("\n")}`);
+  }
+  const sources = join(repo, ".planning", "wiki", "sources");
+  if (existsSync(sources)) {
+    const hits = readdirSync(sources).filter((name) => name.endsWith(".md")).filter((name) => {
+      try { return readFileSync(join(sources, name), "utf8").toLowerCase().includes(stem.toLowerCase()); } catch { return false; }
+    }).slice(0, 8);
+    if (hits.length) sections.push(`## Relevant wiki pages for ${base}\n\n${hits.map((name) => `- ${name}`).join("\n")}`);
+  }
+  hookOutput("PreToolUse", "Memory recall (auto-injected for this file edit):", sections.join("\n\n"));
+}
+
+async function explore() {
+  if (!process.env.CAIRN_EXPLORE_BINARY || process.env.CAIRN_EXPLORE_AUTOINVOKE !== "1" || !existsSync(SERVER)) return;
+  const prompt = json(await stdin()).prompt;
+  if (typeof prompt !== "string" || prompt.length < 10 || prompt.startsWith("/") || /^\s*(ok|yes|no|thanks?)\.?\s*$/i.test(prompt)) return;
+  const result = node(SERVER, ["explore", prompt], { timeout: 20_000 });
+  const value = json(result.stdout);
+  if (value.ok !== true || !Array.isArray(value.citations) || !value.citations.length) return;
+  const context = value.citations.slice(0, 40).map((citation) => {
+    let line = `${citation.path}:${citation.start_line}-${citation.end_line}`;
+    const refs = [];
+    if (citation.memory_refs?.length) refs.push(`memory: ${citation.memory_refs.join(", ")}`);
+    if (citation.wiki_refs?.length) refs.push(`wiki: ${citation.wiki_refs.join(", ")}`);
+    return refs.length ? `${line} <- ${refs.join(" - ")}` : line;
+  }).join("\n");
+  hookOutput("UserPromptSubmit", "Auto-invoked exploration context (context_explore):", context);
+}
+
+function validSession(value) {
+  return typeof value === "string" && /^(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value) && value !== "unknown";
+}
+
+async function capabilityStart() {
+  const block = () => { process.stdout.write('{"decision":"block","reason":"capability disabled"}\n'); process.exitCode = 2; };
+  if (!enabled("CAIRN_CAPABILITY_CONTRACT")) { process.stdout.write("{}\n"); return; }
+  if (!existsSync(CAPABILITY)) { block(); return; }
+  const value = json(await stdin());
+  const commands = new Set(["wiki-ingest", "wiki-query", "wiki-lint", "graphify", "security-audit"]);
+  const required = ["session_id", "transcript_path", "cwd", "hook_event_name", "expansion_type", "command_name", "command_args", "command_source", "prompt"];
+  const valid = required.every((key) => Object.hasOwn(value, key))
+    && value.hook_event_name === "UserPromptExpansion"
+    && ["slash_command", "mcp_prompt"].includes(value.expansion_type)
+    && commands.has(value.command_name)
+    && validSession(value.session_id)
+    && resolve(value.cwd || "") === resolve(process.cwd());
+  if (!valid) { block(); return; }
+  const payload = JSON.stringify({ schema_version: 1, harness: "claude-code", command: value.command_name, session_id: value.session_id, project_root: resolve(process.cwd()) });
+  const result = node(CAPABILITY, ["harness-before"], { input: payload });
+  if (result.stdout?.trim() === '{"schema_version":1,"decision":"block","reason":"capability-disabled"}') block();
+  else process.stdout.write("{}\n");
+}
+
+async function capabilityFinish() {
+  if (!enabled("CAIRN_CAPABILITY_CONTRACT") || !existsSync(CAPABILITY)) return;
+  const value = json(await stdin());
+  if (!validSession(value.session_id) || typeof value.hook_event_name !== "string") return;
+  let operation;
+  let body;
+  if (value.hook_event_name === "Stop" && typeof value.stop_hook_active === "boolean") {
+    operation = "harness-terminal"; body = { outcome: "success" };
+  } else if (value.hook_event_name === "StopFailure" && typeof value.error === "string") {
+    operation = "harness-terminal"; body = { outcome: "error" };
+  } else if (value.hook_event_name === "SessionEnd" && typeof value.reason === "string") {
+    operation = "harness-terminal"; body = { outcome: "abandoned" };
+  } else if (value.hook_event_name === "CwdChanged" && typeof value.old_cwd === "string" && typeof value.new_cwd === "string") {
+    operation = "harness-cwd"; body = { old_cwd: value.old_cwd, new_cwd: value.new_cwd };
+  } else return;
+  node(CAPABILITY, [operation], { input: JSON.stringify({ ...body, schema_version: 1, harness: "claude-code", session_id: value.session_id }) });
+}
+
+const handlers = new Map([
+  ["memory-wakeup", wakeup],
+  ["memory-capture", capture],
+  ["compaction-capture", compact],
+  ["memory-recall", recall],
+  ["context-explore-pretask", explore],
+  ["capability-command-start", capabilityStart],
+  ["capability-command-finish", capabilityFinish],
+]);
+
+const handler = handlers.get(process.argv[2]);
+if (!handler) process.exitCode = 2;
+else handler().catch(() => {
+  if (process.argv[2] === "capability-command-start") {
+    process.stdout.write('{"decision":"block","reason":"capability disabled"}\n');
+    process.exitCode = 2;
+  }
+}); // Other harness callbacks are deliberately fail-open.

package/scripts/completion.sh

@@ -1,23 +1,26 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+harnesses=$(node "$CAIRN_ROOT/scripts/harness-registry.mjs" ids)
 shell=${1:-}
 
 case "$shell" in
   bash)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 _cairn_complete() {
   local current previous commands
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
+  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
   fi
   case "${COMP_WORDS[1]}" in
     bootstrap) COMPREPLY=( $(compgen -W "--untracked" -- "$current") ) ;;
+    setup) COMPREPLY=( $(compgen -W "--git --harness --memory --policy --yes --json init existing none __CAIRN_HARNESSES__ local" -- "$current") ) ;;
     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") ) ;;
@@ -77,12 +80,13 @@ complete -F _cairn_complete cairn
 EOF
     ;;
   zsh)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 #compdef cairn
 _cairn() {
   local -a commands
   commands=(
     'bootstrap:scaffold a project'
+    'setup:configure selected project harnesses'
     'memory-server:run the memory MCP server'
     'sync:install the Claude operating layer'
     'sync-pi:install the Pi trajectory extension and graph prompt'
@@ -110,6 +114,7 @@ _cairn() {
   fi
   case $words[2] in
     bootstrap) _arguments '--untracked[keep scaffold out of Git]' '*:project directory:_files -/' ;;
+    setup) _arguments '*:project directory:_files -/' '--git[Git mode]:mode:(init existing none)' '--harness[selected harnesses]:harnesses:(__CAIRN_HARNESSES__)' '--memory[memory mode]:mode:(local none)' '--policy[setup policy]:file:_files' '--yes[confirm setup]' '--json[emit JSON]' ;;
     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 -/' ;;
@@ -172,10 +177,10 @@ _cairn "$@"
 EOF
     ;;
   fish)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 complete -c cairn -f
-for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help
-    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities mcp-tools pack 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 doctor trajectory artifact capabilities mcp-tools pack 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 capabilities mcp-tools pack 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
@@ -184,6 +189,12 @@ 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 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__"
+complete -c cairn -n "__fish_seen_subcommand_from setup" -l memory -r -a "local none"
+complete -c cairn -n "__fish_seen_subcommand_from setup" -l policy -r
+complete -c cairn -n "__fish_seen_subcommand_from setup" -l yes
+complete -c cairn -n "__fish_seen_subcommand_from setup" -l json
 complete -c cairn -n "__fish_seen_subcommand_from memory" -a "path export import"
 complete -c cairn -n "__fish_seen_subcommand_from doctor" -l repair
 complete -c cairn -n "__fish_seen_subcommand_from trajectory" -a "list show prune"

package/scripts/doctor.sh

@@ -439,6 +439,64 @@ else
   fail "context-pack objects or project pointers failed integrity checks"
 fi
 
+# 14. Guided setup ownership from .ai/cairnkeep.json is diagnosed without
+# repairing project or machine assets. The Node controller returns only bounded
+# states and exact recovery commands; setup remains the sole owner of project
+# reconciliation.
+setup_diagnosis=$(node --input-type=module - "$CAIRN_ROOT/scripts/setup.mjs" "$CAIRN_ROOT/scripts/harness-registry.mjs" "$PWD" <<'NODE' 2>/dev/null
+import { pathToFileURL } from "node:url";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const module = await import(pathToFileURL(process.argv[2]).href);
+const registry = await import(pathToFileURL(process.argv[3]).href);
+const value = module.diagnoseSetup(process.argv[4]);
+const allowed = new Set(["absent", "complete", "limited", "incomplete"]);
+if (value.schema_version !== 1 || !allowed.has(value.status) || !Array.isArray(value.recovery)) process.exit(1);
+let piSelected = false;
+if (value.status === "complete" || value.status === "limited") {
+  const state = JSON.parse(readFileSync(join(process.argv[4], ".ai", "cairnkeep.json"), "utf8"));
+  if (!Array.isArray(state.harnesses) || state.harnesses.some((name) => !registry.HARNESS_IDS.includes(name))) process.exit(1);
+  piSelected = state.harnesses.includes("pi");
+}
+process.stdout.write(`${value.status}:${value.code}:${value.recovery.join("|")}:${piSelected ? "yes" : "no"}`);
+NODE
+) || setup_diagnosis='incomplete:setup-state:cairn setup . --git existing --harness claude --memory local --yes:no'
+IFS=: read -r setup_status setup_code setup_recovery setup_pi_selected <<< "$setup_diagnosis"
+case "$setup_status:$setup_code" in
+  absent:*) skip "project setup state (not configured; legacy bootstrap remains supported)" ;;
+  complete:configured) pass "project setup is complete" ;;
+  limited:git-disabled) warn "project setup is limited (Git-less mode)" ;;
+  incomplete:*)
+    fail "project setup state is incomplete; run: ${setup_recovery:-cairn setup . --git existing --harness claude --memory local --yes}"
+    ;;
+  *) fail "project setup state is incomplete; run: cairn setup . --git existing --harness claude --memory local --yes" ;;
+esac
+
+# 15. A selected Pi harness requires the explicitly synchronized local bridge
+# extension and its built child entrypoint. Diagnosis compares bounded bytes
+# only; it never starts the bridge or repairs machine state.
+if [[ "${setup_pi_selected:-no}" == "yes" ]]; then
+  pi_source="$CAIRN_ROOT/pi/extensions/cairnkeep-memory.ts"
+  pi_bridge="$CAIRN_ROOT/mcp-memory-server/dist/pi-mcp-bridge.js"
+  pi_live_root="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+  pi_live="$pi_live_root/extensions/cairnkeep-memory.ts"
+  if [[ ! -f "$pi_source" || ! -f "$pi_bridge" ]]; then
+    fail "Pi memory bridge build is incomplete; reinstall Cairnkeep or rebuild the memory server"
+  elif [[ ! -f "$pi_live" ]]; then
+    fail "Pi memory extension cairnkeep-memory.ts is missing; run: cairn sync-pi --apply"
+  elif node --input-type=module - "$pi_source" "$pi_live" "$CAIRN_ROOT" <<'NODE' >/dev/null 2>&1
+import { readFileSync } from "node:fs";
+const expected = readFileSync(process.argv[2], "utf8").replaceAll("@@INFRA_ROOT@@", process.argv[4]);
+const current = readFileSync(process.argv[3], "utf8");
+process.exit(expected === current ? 0 : 1);
+NODE
+  then
+    pass "Pi memory extension is synchronized for the selected project harness"
+  else
+    fail "Pi memory extension cairnkeep-memory.ts has drifted; run: cairn sync-pi --apply"
+  fi
+fi
+
 echo
 if [[ "$fails" -gt 0 ]]; then
   echo "cairn doctor: $fails configured dependency check(s) failed."

package/scripts/fix-permissions.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { chmodSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+if (process.platform === "win32") process.exit(0);
+const result = spawnSync("git", ["ls-files", "-s"], { encoding: "utf8" });
+if (result.status !== 0) process.exit(result.status ?? 1);
+for (const line of result.stdout.split(/\r?\n/)) {
+  const match = line.match(/^100755\s+[0-9a-f]+\s+\d+\t(.+)$/);
+  if (match) chmodSync(match[1], 0o755);
+}