@cairnkeep/cli 2.8.0 → 2.11.0

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

@@ -11,13 +11,14 @@ _cairn_complete() {
   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 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 claude opencode pi kimi qwen 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") ) ;;
@@ -51,6 +52,8 @@ _cairn_complete() {
         *) COMPREPLY=( $(compgen -W "list status enable disable reset logging" -- "$current") ) ;;
       esac
       ;;
+    mcp-tools) COMPREPLY=( $(compgen -W "list status set reset full read-only custom --tool --project --json" -- "$current") ) ;;
+    pack) COMPREPLY=( $(compgen -W "init lock validate install list show remove enable disable update skills approve-skill revoke-skill --id --version --title --description --license --ref --project --project-id --check --apply --confirm --json" -- "$current") ) ;;
     notes) COMPREPLY=( $(compgen -W "distill search-error promote doctor --project --session --all-projects --para-root --text --component --with --confirm --repair --json" -- "$current") ) ;;
     eval)
       case "${COMP_WORDS[2]:-}" in
@@ -67,7 +70,7 @@ _cairn_complete() {
     graph) COMPREPLY=( $(compgen -W "build query status diff explain path --force" -- "$current") ) ;;
     memory) COMPREPLY=( $(compgen -W "path export import" -- "$current") ) ;;
     audit-timer) COMPREPLY=( $(compgen -W "--on-calendar --para-root --render-only" -- "$current") ) ;;
-    uninstall) COMPREPLY=( $(compgen -W "--dry-run --yes --purge-memory --live-root --pi-live-root --kimi-live-root" -- "$current") ) ;;
+    uninstall) COMPREPLY=( $(compgen -W "--dry-run --yes --purge-memory --purge-packs --live-root --pi-live-root --kimi-live-root" -- "$current") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$current") ) ;;
   esac
 }
@@ -81,6 +84,7 @@ _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'
@@ -89,6 +93,8 @@ _cairn() {
     'trajectory:inspect and prune local session trajectories'
     'artifact:inspect, delete, and prune local artifacts'
     'capabilities:inspect and manage project capability state'
+    'mcp-tools:inspect and restrict MCP tool exposure'
+    'pack:manage immutable context packs and skill approvals'
     'notes:distill and search local hindsight notes'
     'eval:run and inspect default-off local evaluations'
     'skill:review and evaluate evidence-backed skill improvements'
@@ -106,6 +112,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:(claude opencode pi kimi qwen)' '--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 -/' ;;
@@ -120,6 +127,8 @@ _cairn() {
         *) _values 'artifact command' list show delete prune ;;
       esac
       ;;
+    mcp-tools) _values 'MCP tool profile command' list status set reset full read-only custom '--tool[allow an exact tool]:tool:' '--project[project root]:directory:_files -/' '--json[emit JSON]' ;;
+    pack) _values 'context pack command' init lock validate install list show remove enable disable update skills approve-skill revoke-skill '--ref[pinned Git ref]:ref:' '--project[project root]:directory:_files -/' '--project-id[remote project ID]:project ID:' '--check[inspect update]' '--apply[apply update]' '--confirm[confirm digest]:digest:' '--json[emit JSON]' ;;
     capabilities)
       case $words[3] in
         list|status) _arguments '--json[emit JSON]' ;;
@@ -157,7 +166,7 @@ _cairn() {
     graph) _values 'graph command' build query status diff explain path '--force[allow a smaller graph after code deletion]' ;;
     memory) _values 'memory command' path export import ;;
     audit-timer) _arguments '--on-calendar[systemd calendar]:calendar:' '--para-root[PARA root]:directory:_files -/' '--render-only[render directory]:directory:_files -/' ;;
-    uninstall) _arguments '--dry-run[show changes]' '--yes[skip confirmation]' '--purge-memory[delete memory]' '--live-root[project Claude root]:directory:_files -/' '--pi-live-root[Pi agent root]:directory:_files -/' '--kimi-live-root[Kimi Code root]:directory:_files -/' '*:project directory:_files -/' ;;
+    uninstall) _arguments '--dry-run[show changes]' '--yes[skip confirmation]' '--purge-memory[delete memory]' '--purge-packs[delete context packs]' '--live-root[project Claude root]:directory:_files -/' '--pi-live-root[Pi agent root]:directory:_files -/' '--kimi-live-root[Kimi Code root]:directory:_files -/' '*:project directory:_files -/' ;;
     completion) _values 'shell' bash zsh fish ;;
     *) _arguments '*:argument:_files' ;;
   esac
@@ -168,8 +177,8 @@ EOF
   fish)
     cat <<'EOF'
 complete -c cairn -f
-for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities 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 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
@@ -178,6 +187,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 "claude opencode pi kimi qwen"
+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"
@@ -193,6 +208,17 @@ complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from reset" -l all
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from logging; and not __fish_seen_subcommand_from enable disable reset" -a "enable disable reset"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from list status enable disable reset logging" -l json
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -a "list status set reset"
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools; and __fish_seen_subcommand_from set" -a "full read-only custom"
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l tool -r
+complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l json
+complete -c cairn -n "__fish_seen_subcommand_from pack" -a "init lock validate install list show remove enable disable update skills approve-skill revoke-skill"
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l project-id -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l ref -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l confirm -r
+complete -c cairn -n "__fish_seen_subcommand_from pack" -l json
 complete -c cairn -n "__fish_seen_subcommand_from notes" -a "distill search-error promote doctor"
 complete -c cairn -n "__fish_seen_subcommand_from eval; and not __fish_seen_subcommand_from validate run ablate report prune delete" -a "validate run ablate report prune delete"
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate" -l task-set -r
@@ -234,6 +260,8 @@ complete -c cairn -n "__fish_seen_subcommand_from graph; and __fish_seen_subcomm
 complete -c cairn -n "__fish_seen_subcommand_from completion" -a "bash zsh fish"
 complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l pi-live-root -r
 complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l kimi-live-root -r
+complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l purge-memory
+complete -c cairn -n "__fish_seen_subcommand_from uninstall" -l purge-packs
 EOF
     ;;
   *)

package/scripts/doctor.sh

@@ -400,6 +400,102 @@ case "$eval_state" in
   unsafe) warn "evaluation report storage is unsafe" ;;
 esac
 
+# 12. MCP least-authority profile. Invalid or unknown custom tool names are a
+# startup failure, so doctor treats them as an actionable configuration error.
+mcp_profile_cli="$CAIRN_ROOT/mcp-memory-server/dist/mcp-tool-cli.js"
+if [[ ! -f "$mcp_profile_cli" ]]; then
+  fail "MCP tool profile checker is missing from the installed package"
+elif mcp_profile_json=$(node "$mcp_profile_cli" status --project "$PWD" --json 2>/dev/null); then
+  if mcp_profile_summary=$(node - "$mcp_profile_json" <<'NODE'
+try {
+  const value = JSON.parse(process.argv[2]);
+  if (value.schema_version !== 1 || !["full", "read-only", "custom"].includes(value.mode)
+      || !/^[a-f0-9]{64}$/.test(value.profile_digest) || !Array.isArray(value.allowed_tools)) process.exit(1);
+  process.stdout.write(`${value.mode}\t${value.profile_digest}`);
+} catch { process.exit(1); }
+NODE
+  ); then
+    pass "MCP tool profile $(printf '%s' "$mcp_profile_summary" | cut -f1) ($(printf '%s' "$mcp_profile_summary" | cut -f2))"
+  else
+    fail "MCP tool profile status returned invalid data"
+  fi
+else
+  fail "MCP tool profile is invalid (check .ai/mcp-tools.json and CAIRN_MCP_TOOL_PROFILE)"
+fi
+
+# 13. Context-pack objects and project pointers are verified even when MCP pack
+# retrieval is disabled. The feature gate controls reads, not integrity checks.
+pack_cli="$CAIRN_ROOT/mcp-memory-server/dist/context-pack-cli.js"
+pack_base="${CAIRN_PACK_BASE_DIR:-$HOME/.cairnkeep/packs}"
+pack_base="${pack_base/#\~/$HOME}"
+if [[ ! -e "$pack_base" ]]; then
+  skip "context packs (not installed)"
+elif [[ ! -f "$pack_cli" ]]; then
+  fail "context-pack checker is missing from the installed package"
+elif pack_json=$(node "$pack_cli" doctor --json 2>/dev/null) && node -e 'const v=JSON.parse(process.argv[1]); if(v.ok!==true)process.exit(1)' "$pack_json"; then
+  pack_counts=$(node -e 'const v=JSON.parse(process.argv[1]); process.stdout.write(`${v.objects} object(s), ${v.projects} project pointer(s)`)' "$pack_json")
+  pass "context packs healthy ($pack_counts)"
+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" "$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 value = module.diagnoseSetup(process.argv[3]);
+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[3], ".ai", "cairnkeep.json"), "utf8"));
+  if (!Array.isArray(state.harnesses) || state.harnesses.some((name) => !["claude", "opencode", "pi", "kimi", "qwen"].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);
+}

package/scripts/memory-wiki-audit.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function option(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+
+const para = resolve(option("--para-root", join(homedir(), "PARA")));
+const staleDays = Number(option("--stale-days", "30"));
+const reportPath = option("--report", "");
+const cutoff = Date.now() - staleDays * 86_400_000;
+const findings = [];
+let stale = 0;
+let hard = 0;
+let orphan = 0;
+let staged = 0;
+let noteStatus = "";
+
+function directories(root, depth = 0) {
+  if (!existsSync(root) || depth > 5) return [];
+  const result = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const path = join(root, entry.name);
+    if (entry.name === "wiki" && basename(dirname(path)) === ".planning") result.push(path);
+    else result.push(...directories(path, depth + 1));
+  }
+  return result;
+}
+
+for (const wiki of directories(para)) {
+  const project = resolve(wiki, "..", "..");
+  const rows = [];
+  const sources = join(wiki, "sources");
+  const sourceFiles = existsSync(sources) ? readdirSync(sources).filter((name) => name.endsWith(".md")) : [];
+  const staleFiles = sourceFiles.filter((name) => {
+    const match = readFileSync(join(sources, name), "utf8").match(/Last reviewed\*?\*?:\s*(\d{4}-\d{2}-\d{2})/i);
+    return match && Date.parse(`${match[1]}T00:00:00Z`) < cutoff;
+  });
+  if (staleFiles.length) { stale += staleFiles.length; rows.push(`- stale source pages (${staleFiles.length}): ${staleFiles.join(", ")}`); }
+  const contradictions = join(wiki, "CONTRADICTIONS.md");
+  if (existsSync(contradictions)) {
+    const open = readFileSync(contradictions, "utf8").match(/wiki:contradictions:open:start -->([\s\S]*?)<!-- wiki:contradictions:open:end/)?.[1] ?? "";
+    const count = (open.match(/severity:\s*hard|hard contradiction/gi) ?? []).length;
+    if (count) { hard += count; rows.push(`- open HARD contradictions: ${count}`); }
+  }
+  const indexPath = join(wiki, "index.md");
+  if (existsSync(indexPath)) {
+    const index = readFileSync(indexPath, "utf8");
+    const orphans = sourceFiles.filter((name) => !index.includes(name));
+    if (orphans.length) { orphan += orphans.length; rows.push(`- orphan source pages (${orphans.length}): ${orphans.join(", ")}`); }
+  }
+  const staging = join(project, ".planning", "memory-staging");
+  if (existsSync(staging)) {
+    const count = readdirSync(staging).filter((name) => name.endsWith(".json") && statSync(join(staging, name)).mtimeMs < cutoff).length;
+    if (count) { staged += count; rows.push(`- unreviewed staged memory candidates (>${staleDays} days): ${count}`); }
+  }
+  if (rows.length) findings.push(`### ${basename(project)}\n\n${rows.join("\n")}`);
+}
+
+let noteEligible = /^(1|true|yes|on)$/i.test(process.env.CAIRN_NOTE_DISTILLATION ?? "");
+if (/^(1|true|yes|on)$/i.test(process.env.CAIRN_CAPABILITY_CONTRACT ?? "")) {
+  const status = spawnSync(process.execPath, [join(ROOT, "bin", "cairn"), "capabilities", "status", "--json"], { encoding: "utf8", windowsHide: true });
+  try {
+    const value = JSON.parse(status.stdout);
+    noteEligible = value.capabilities?.some((row) => row.id === "notes.distill" && row.enabled === true) ?? false;
+  } catch { noteEligible = false; }
+}
+if (noteEligible) {
+  const result = spawnSync(process.execPath, [join(ROOT, "bin", "cairn"), "notes", "distill", "--all-projects", "--para-root", para, "--json"], { stdio: "ignore", windowsHide: true });
+  noteStatus = result.status === 0 ? "completed" : "failed (deterministic wiki findings remain valid)";
+}
+
+const report = `# Memory + Wiki Audit Report
+
+- Generated: ${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}
+- Scope: ${para} (staleness threshold: ${staleDays} days)
+- Stale source pages: ${stale}
+- Open hard contradictions: ${hard}
+- Orphan source pages: ${orphan}
+- Unreviewed staged candidates: ${staged}
+${noteStatus ? `- Note distillation: ${noteStatus}\n` : ""}
+
+${findings.length ? findings.join("\n\n") : "No deterministic findings."}
+`;
+process.stdout.write(report);
+if (reportPath) writeFileSync(resolve(reportPath), report, "utf8");

package/scripts/phase26-test-manifest.mjs

@@ -0,0 +1,26 @@
+const REQUIRED_PHASE26_TEST_PATHS = Object.freeze([
+  "scripts/test-setup-preflight.mjs",
+  "scripts/test-setup-reconcile.mjs",
+  "scripts/test-setup-compatibility.mjs",
+  "scripts/test-pi-lifecycle.mjs",
+  "mcp-memory-server/scripts/smoke-pi-mcp-bridge.mjs",
+]);
+
+export const PHASE26_TEST_MANIFEST = Object.freeze(REQUIRED_PHASE26_TEST_PATHS.map((path) => Object.freeze({
+  path,
+  state: "routine",
+})));
+
+export function validatePhase26TestManifest(entries = PHASE26_TEST_MANIFEST) {
+  if (!Array.isArray(entries)) throw new Error("Phase 26 test manifest must be an array.");
+  if (entries.length !== REQUIRED_PHASE26_TEST_PATHS.length) throw new Error("Phase 26 test manifest entry count drifted.");
+  const paths = entries.map((entry) => entry?.path);
+  if (JSON.stringify(paths) !== JSON.stringify(REQUIRED_PHASE26_TEST_PATHS)) throw new Error("Phase 26 test manifest paths or order drifted.");
+  if (new Set(paths).size !== paths.length) throw new Error("Phase 26 test manifest contains duplicate paths.");
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error("Phase 26 test manifest entry must be an object.");
+    if (Object.keys(entry).sort().join(",") !== "path,state") throw new Error(`Phase 26 test manifest fields drifted for ${entry.path ?? "unknown"}.`);
+    if (entry.state !== "red-only" && entry.state !== "routine") throw new Error(`Invalid Phase 26 test state for ${entry.path}.`);
+  }
+  return entries;
+}

package/scripts/run-repository-tests.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { PHASE26_TEST_MANIFEST, validatePhase26TestManifest } from "./phase26-test-manifest.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function dispatchPhase26Tests(spawn = spawnSync) {
+  const results = [];
+  for (const entry of validatePhase26TestManifest().filter(({ state }) => state === "routine")) {
+    const result = spawn(process.execPath, [join(root, ...entry.path.split("/"))], { cwd: root, stdio: "inherit" });
+    results.push({ path: entry.path, status: result.status ?? 1 });
+    if (result.status !== 0) break;
+  }
+  return results;
+}
+
+function verifyPhase26RedRegistration() {
+  validatePhase26TestManifest();
+  const scheduled = dispatchPhase26Tests((_command, args) => {
+    throw new Error(`RED-only Phase 26 test was scheduled: ${args[0]}`);
+  });
+  if (scheduled.length !== 0) throw new Error("RED-only Phase 26 tests must not run in routine dispatch.");
+  console.log(`PASS: Phase 26 manifest has ${PHASE26_TEST_MANIFEST.length} exact RED-only entries and routine dispatch schedules none`);
+}
+
+function verifyPhase26RoutineRegistration() {
+  const entries = validatePhase26TestManifest();
+  if (!entries.every(({ state }) => state === "routine")) {
+    throw new Error("Every Phase 26 test must be routine after learning and track routing complete.");
+  }
+  const recorded = [];
+  const scheduled = dispatchPhase26Tests((command, args, options) => {
+    if (command !== process.execPath) throw new Error("Phase 26 dispatch must use the active Node executable.");
+    if (!Array.isArray(args) || args.length !== 1) throw new Error("Phase 26 dispatch arguments drifted.");
+    if (options?.cwd !== root || options?.stdio !== "inherit") throw new Error("Phase 26 dispatch options drifted.");
+    recorded.push(relative(root, args[0]).split(sep).join("/"));
+    return { status: 0 };
+  });
+  const expected = entries.map(({ path }) => path);
+  if (JSON.stringify(recorded) !== JSON.stringify(expected)) throw new Error("Phase 26 executable dispatch paths or order drifted.");
+  if (JSON.stringify(scheduled.map(({ path }) => path)) !== JSON.stringify(expected)) throw new Error("Phase 26 dispatch result paths drifted.");
+  if (new Set(recorded).size !== expected.length) throw new Error("Phase 26 executable dispatch scheduled a duplicate contract.");
+  console.log(`PASS: Phase 26 routine dispatch schedules all ${expected.length} exact contracts once`);
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === "--verify-phase26-registration=red") {
+    verifyPhase26RedRegistration();
+    return;
+  }
+  if (args.length === 1 && args[0] === "--verify-phase26-registration=routine") {
+    verifyPhase26RoutineRegistration();
+    return;
+  }
+  if (args.length !== 0) throw new Error(`Unknown repository test option: ${args.join(" ")}`);
+
+  if (process.platform !== "win32") {
+    for (const test of readdirSync(join(root, "scripts")).filter((name) => /^test-.*\.sh$/.test(name)).sort()) {
+      const result = spawnSync(join(root, "scripts", test), [], { cwd: root, stdio: "inherit" });
+      if (result.status !== 0) process.exit(result.status ?? 1);
+    }
+  }
+  const native = spawnSync(process.execPath, [join(root, "scripts", "test-windows-native.mjs")], { cwd: root, stdio: "inherit" });
+  if (native.status !== 0) process.exit(native.status ?? 1);
+  const phase26 = dispatchPhase26Tests();
+  const failed = phase26.find(({ status }) => status !== 0);
+  if (failed) process.exit(failed.status);
+}
+
+run();