@cairnkeep/cli 2.11.0 → 2.13.0

package/scripts/completion.sh

@@ -1,30 +1,33 @@
 #!/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 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"
+  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence 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") ) ;;
+    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") ) ;;
     doctor) COMPREPLY=( $(compgen -W "--repair" -- "$current") ) ;;
     trajectory) COMPREPLY=( $(compgen -W "list show prune --json --dry-run" -- "$current") ) ;;
     artifact) COMPREPLY=( $(compgen -W "list show delete prune --kind --session --json --dry-run --include-protected" -- "$current") ) ;;
+    evidence) COMPREPLY=( $(compgen -W "list show delete prune doctor --status --json --dry-run --repair" -- "$current") ) ;;
     capabilities)
       case "${COMP_WORDS[2]:-}" in
         enable|disable)
@@ -78,7 +81,7 @@ complete -F _cairn_complete cairn
 EOF
     ;;
   zsh)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 #compdef cairn
 _cairn() {
   local -a commands
@@ -92,6 +95,7 @@ _cairn() {
     'doctor:check runtime dependencies and endpoints'
     'trajectory:inspect and prune local session trajectories'
     'artifact:inspect, delete, and prune local artifacts'
+    'evidence:inspect and manage local Git-linked work evidence'
     'capabilities:inspect and manage project capability state'
     'mcp-tools:inspect and restrict MCP tool exposure'
     'pack:manage immutable context packs and skill approvals'
@@ -112,7 +116,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]' ;;
+    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 -/' ;;
@@ -127,6 +131,7 @@ _cairn() {
         *) _values 'artifact command' list show delete prune ;;
       esac
       ;;
+    evidence) _values 'work evidence command' list show delete prune doctor '--status[filter records]:status:(pending complete)' '--dry-run[report without mutation]' '--repair[remove safe temporary remnants]' '--json[emit JSON]' ;;
     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)
@@ -175,10 +180,10 @@ _cairn "$@"
 EOF
     ;;
   fish)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 complete -c cairn -f
-for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact 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
+for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence 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 evidence 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
@@ -188,7 +193,7 @@ 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 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
@@ -202,6 +207,11 @@ complete -c cairn -n "__fish_seen_subcommand_from artifact; and __fish_seen_subc
 complete -c cairn -n "__fish_seen_subcommand_from artifact; and __fish_seen_subcommand_from list show delete prune" -l json
 complete -c cairn -n "__fish_seen_subcommand_from artifact; and __fish_seen_subcommand_from delete prune" -l dry-run
 complete -c cairn -n "__fish_seen_subcommand_from artifact; and __fish_seen_subcommand_from prune" -l include-protected
+complete -c cairn -n "__fish_seen_subcommand_from evidence" -a "list show delete prune doctor"
+complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from list" -l status -r -a "pending complete"
+complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from list show delete prune doctor" -l json
+complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from delete prune" -l dry-run
+complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from doctor" -l repair
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and not __fish_seen_subcommand_from list status enable disable reset logging" -a "list status enable disable reset logging"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from enable disable; and not __fish_seen_subcommand_from memory.write memory.search notes.distill wiki graph security.audit route.check context.explore" -a "memory.write memory.search notes.distill wiki graph security.audit route.check context.explore"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from reset; and not __fish_seen_subcommand_from memory.write memory.search notes.distill wiki graph security.audit route.check context.explore" -a "memory.write memory.search notes.distill wiki graph security.audit route.check context.explore"

package/scripts/doctor.sh

@@ -201,7 +201,36 @@ try {
   [[ $artifact_status -eq 0 || "$artifact_state" == "broken" ]] || true
 fi
 
-# 9. Typed metadata overlays and canonical-note transaction state. The internal
+# 9. Project-local Git-linked work-evidence records. Absence is healthy because
+#    capture is opt-in. Repair removes safe temporary remnants only; it never
+#    finalizes an interrupted session or invents a Git state.
+evidence_cli="$CAIRN_ROOT/mcp-memory-server/dist/work-evidence-cli.js"
+if [[ ! -f "$evidence_cli" ]]; then
+  fail "work-evidence diagnostics unavailable — rebuild mcp-memory-server"
+else
+  evidence_args=(doctor --json)
+  [[ $REPAIR_STORES -eq 1 ]] && evidence_args+=(--repair)
+  evidence_json=$(node "$evidence_cli" "${evidence_args[@]}" 2>/dev/null)
+  evidence_status=$?
+  evidence_state=$(node -e '
+try {
+  const value = JSON.parse(process.argv[1])
+  if (!value.exists) process.stdout.write("absent")
+  else if (value.ok && value.repaired) process.stdout.write("repaired")
+  else if (value.ok) process.stdout.write("ok")
+  else process.stdout.write("broken")
+} catch { process.stdout.write("invalid") }
+' "$evidence_json" 2>/dev/null)
+  case "$evidence_state" in
+    absent) skip "work-evidence store (not present — capture is opt-in)" ;;
+    repaired) pass "work-evidence store repaired (temporary remnants removed; evidence preserved)" ;;
+    ok) pass "work-evidence records and append-only links are valid" ;;
+    *) fail "work-evidence validation failed — inspect with: cairn evidence doctor --json" ;;
+  esac
+  [[ $evidence_status -eq 0 || "$evidence_state" == "broken" ]] || true
+fi
+
+# 10. Typed metadata overlays and canonical-note transaction state. The internal
 #    JSON seam enumerates only contained local databases and the one notes root;
 #    raw KV cells and unmarked Markdown bytes are never repair inputs.
 node_cli="$CAIRN_ROOT/mcp-memory-server/dist/node-cli.js"
@@ -443,18 +472,19 @@ fi
 # 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
+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 value = module.diagnoseSetup(process.argv[3]);
+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[3], ".ai", "cairnkeep.json"), "utf8"));
-  if (!Array.isArray(state.harnesses) || state.harnesses.some((name) => !["claude", "opencode", "pi", "kimi", "qwen"].includes(name))) process.exit(1);
+  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"}`);

package/scripts/harness-registry.mjs

@@ -0,0 +1,126 @@
+import { pathToFileURL } from "node:url";
+
+/**
+ * Declarative registry for every CLI harness supported by project setup.
+ *
+ * Keep harness-specific project assets and lifecycle guidance here. Consumers
+ * must derive choices from this registry instead of maintaining local lists.
+ */
+const DEFINITIONS = [
+  {
+    id: "claude",
+    title: "Claude Code",
+    launcher: { template: "start-claude.sh.template", path: ".ai/start-claude.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync --apply",
+  },
+  {
+    id: "opencode",
+    title: "OpenCode",
+    launcher: { template: "start-opencode.sh.template", path: ".ai/start-opencode.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync --apply",
+  },
+  {
+    id: "pi",
+    title: "Pi",
+    launcher: { template: "start-pi.sh.template", path: ".ai/start-pi.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync-pi --apply",
+  },
+  {
+    id: "kimi",
+    title: "Kimi Code",
+    launcher: { template: "start-kimi.sh.template", path: ".ai/start-kimi.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync-kimi --apply",
+  },
+  {
+    id: "qwen",
+    title: "Qwen Code",
+    launcher: { template: "start-qwen.sh.template", path: ".ai/start-qwen.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: null,
+  },
+  {
+    id: "codex",
+    title: "Codex CLI",
+    launcher: { template: "start-codex.sh.template", path: ".ai/start-codex.sh", mode: 0o755 },
+    project_assets: [
+      {
+        template: "codex-config.toml.template",
+        path: ".codex/config.toml",
+        mode: 0o644,
+        memory: "local",
+        // An existing operator-owned TOML file is valid when doctor finds the
+        // exact MCP table; it must not become setup/uninstall-owned.
+        required: false,
+      },
+    ],
+    machine_sync: null,
+  },
+];
+
+function freezeDefinition(definition) {
+  const launcher = Object.freeze({ ...definition.launcher });
+  const projectAssets = Object.freeze(definition.project_assets.map((asset) => Object.freeze({ ...asset })));
+  return Object.freeze({ ...definition, launcher, project_assets: projectAssets });
+}
+
+export const HARNESS_REGISTRY = Object.freeze(DEFINITIONS.map(freezeDefinition));
+export const HARNESS_IDS = Object.freeze(HARNESS_REGISTRY.map(({ id }) => id));
+
+export function harnessDefinition(id) {
+  return HARNESS_REGISTRY.find((definition) => definition.id === id) ?? null;
+}
+
+export function harnessProjectAssets(id, memory = "local") {
+  const definition = harnessDefinition(id);
+  if (!definition) throw new Error(`Unknown harness: ${id}.`);
+  return Object.freeze([
+    definition.launcher,
+    ...definition.project_assets.filter((asset) => !asset.memory || asset.memory === memory),
+  ]);
+}
+
+export function requiredHarnessAssetPaths(harnesses, memory = "local") {
+  return Object.freeze(harnesses.flatMap((id) => harnessProjectAssets(id, memory)
+    .filter((asset) => asset.required !== false)
+    .map(({ path }) => path)));
+}
+
+export function machineSyncCommand(harnesses) {
+  const commands = harnesses.map(harnessDefinition).map((definition) => definition?.machine_sync).filter(Boolean);
+  if (commands.includes("cairn sync-pi --apply")) return "cairn sync-pi --apply";
+  return commands[0] ?? null;
+}
+
+function validateRegistry() {
+  if (new Set(HARNESS_IDS).size !== HARNESS_IDS.length) throw new Error("Harness registry contains duplicate IDs.");
+  for (const definition of HARNESS_REGISTRY) {
+    if (!/^[a-z][a-z0-9-]*$/.test(definition.id) || !definition.title) throw new Error("Invalid harness registry entry.");
+    const assets = [definition.launcher, ...definition.project_assets];
+    if (new Set(assets.map(({ path }) => path)).size !== assets.length) throw new Error(`Duplicate project asset for ${definition.id}.`);
+    for (const asset of assets) {
+      if (!asset.template || !asset.path || ![0o600, 0o644, 0o755].includes(asset.mode)) throw new Error(`Invalid project asset for ${definition.id}.`);
+    }
+  }
+}
+
+validateRegistry();
+
+// The legacy bootstrap is a shell script for Bash 3.2 portability. This bounded
+// output lets it consume the same registry without parsing JavaScript or JSON.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  if (!new Set(["bootstrap-assets", "ids"]).has(process.argv[2])) {
+    console.error("Usage: node harness-registry.mjs bootstrap-assets|ids");
+    process.exitCode = 2;
+  } else if (process.argv[2] === "ids") {
+    process.stdout.write(`${HARNESS_IDS.join(" ")}\n`);
+  } else {
+    for (const definition of HARNESS_REGISTRY) {
+      const asset = definition.launcher;
+      process.stdout.write(`${asset.template}\t${asset.path}\t${asset.mode.toString(8)}\n`);
+    }
+  }
+}

package/scripts/setup-core.mjs

@@ -3,12 +3,13 @@ import { accessSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { HARNESS_IDS, harnessProjectAssets } from "./harness-registry.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATE_ROOT = join(ROOT, "templates");
 const POLICY_LIMIT_BYTES = 1024 * 1024;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
-const HARNESSES = Object.freeze(["claude", "opencode", "pi", "kimi", "qwen"]);
+const HARNESSES = HARNESS_IDS;
 const MEMORY_MODES = Object.freeze(["local", "none"]);
 
 const COMMON_ASSETS = Object.freeze([
@@ -293,7 +294,8 @@ export function buildSetupPlan({ target, preflight, choices }) {
   if (choices.git !== "none" && preflight.gitExecutable === "missing") throw operational("missing-git", "The selected Git mode requires the Git executable.");
   const harnesses = HARNESSES.filter((name) => choices.harnesses.includes(name));
   const assets = [
-    ...harnesses.map((harness) => templateAsset(`start-${harness}.sh.template`, `.ai/start-${harness}.sh`, 0o755, harness)),
+    ...harnesses.flatMap((harness) => harnessProjectAssets(harness, choices.memory)
+      .map(({ template, path, mode }) => templateAsset(template, path, mode, harness))),
     ...COMMON_ASSETS.map(([template, path, mode]) => templateAsset(template, path, mode)),
   ];
   const version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;

package/scripts/setup-reconcile.mjs

@@ -16,16 +16,17 @@ import {
 import { open, rename } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { HARNESS_IDS } from "./harness-registry.mjs";
 
 export const SETUP_STATE_SCHEMA_VERSION = 1;
 
-const HARNESSES = Object.freeze(["claude", "opencode", "pi", "kimi", "qwen"]);
+const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
 const MEMORY_MODES = Object.freeze(["local", "none"]);
 const STATE_KEYS = Object.freeze(["schema_version", "cairnkeep_version", "git", "memory", "harnesses", "assets"]);
 const ASSET_KEYS = Object.freeze(["digest", "mode", "template"]);
 const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
-const RELATIVE_PATH_PATTERN = /^\.(?:ai|planning|agentfs)\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
+const RELATIVE_PATH_PATTERN = /^\.(?:ai|planning|agentfs|codex)\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
 const TEMPLATE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
 export function hashSetupAsset(bytes) {

package/scripts/setup.mjs

@@ -21,13 +21,14 @@ import {
   resolveSetupChoices,
 } from "./setup-core.mjs";
 import { reconcileSetupPlan } from "./setup-reconcile.mjs";
+import { HARNESS_IDS, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
 
-const HARNESSES = Object.freeze(["claude", "opencode", "pi", "kimi", "qwen"]);
+const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
 const MEMORY_MODES = Object.freeze(["local", "none"]);
 const STATE_KEYS = Object.freeze(["schema_version", "cairnkeep_version", "git", "memory", "harnesses", "assets"]);
 const ASSET_KEYS = Object.freeze(["digest", "mode", "template"]);
-const SAFE_ASSET = /^\.(?:ai|planning|agentfs)\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
+const SAFE_ASSET = /^\.(?:ai|planning|agentfs|codex)\/(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9._/-]+$/;
 const COMMON_SETUP_ASSETS = Object.freeze([
   ".ai/env.example",
   ".ai/trajectory-redaction.json",
@@ -108,7 +109,7 @@ function setupRecovery(plan) {
 }
 
 function resultFor(plan, reconciliation, platform) {
-  const machineCommand = plan.harnesses.includes("pi") ? "cairn sync-pi --apply" : "cairn sync --apply";
+  const machineCommand = machineSyncCommand(plan.harnesses);
   return Object.freeze({
     schema_version: 1,
     status: plan.limited ? "limited" : "complete",
@@ -139,7 +140,12 @@ export function renderSetupResult(result, stream) {
   for (const command of result.launch_commands) writeLine(stream, `Launch: ${command}`);
   for (const command of result.recovery) writeLine(stream, `Recovery: ${command}`);
   for (const limitation of result.limitations) writeLine(stream, `Limitation: ${limitation}`);
-  writeLine(stream, `Machine sync: ${result.machine_sync.command} (not run automatically)`);
+  if (result.harnesses.includes("codex") && result.memory === "local") {
+    writeLine(stream, "Codex: review .codex/config.toml and accept the project trust prompt before use");
+  }
+  writeLine(stream, result.machine_sync.command
+    ? `Machine sync: ${result.machine_sync.command} (not run automatically)`
+    : "Machine sync: not required for the selected harnesses");
 }
 
 function createTarget(target) {
@@ -260,6 +266,33 @@ function readPrivateState(path) {
   }
 }
 
+function hasCodexMemoryConfig(project) {
+  const path = join(project, ".codex", "config.toml");
+  if (!existsSync(path)) return false;
+  const info = lstatSync(path);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) return false;
+  let descriptor;
+  let text;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) return false;
+    text = readFileSync(descriptor, "utf8");
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+  const lines = text.split(/\r?\n/);
+  const headers = lines.flatMap((line, index) => (
+    ["[mcp_servers.cairn-memory]", "[mcp_servers.\"cairn-memory\"]"].includes(line.trim()) ? [index] : []
+  ));
+  if (headers.length !== 1) return false;
+  const [start] = headers;
+  const next = lines.findIndex((line, index) => index > start && /^\s*\[[^\]]+\]\s*$/.test(line));
+  const section = lines.slice(start + 1, next < 0 ? lines.length : next).join("\n");
+  return (section.match(/^\s*command\s*=\s*["']cairn["']\s*$/gm) ?? []).length === 1
+    && (section.match(/^\s*args\s*=\s*\[\s*["']memory-server["']\s*\]\s*$/gm) ?? []).length === 1;
+}
+
 export function diagnoseSetup(target = ".") {
   const project = resolve(target);
   const statePath = join(project, ".ai", "cairnkeep.json");
@@ -292,8 +325,11 @@ export function diagnoseSetup(target = ".") {
       const digest = createHash("sha256").update(readFileSync(destination)).digest("hex");
       if (digest !== record.digest || (process.platform !== "win32" && (info.mode & 0o777) !== record.mode)) return incompleteDiagnosis(recovery);
     }
-    const requiredAssets = [...COMMON_SETUP_ASSETS, ...state.harnesses.map((harness) => `.ai/start-${harness}.sh`)];
+    const requiredAssets = [...COMMON_SETUP_ASSETS, ...requiredHarnessAssetPaths(state.harnesses, state.memory)];
     if (requiredAssets.some((path) => !Object.hasOwn(state.assets, path))) return incompleteDiagnosis(recovery);
+    if (state.memory === "local" && state.harnesses.includes("codex") && !hasCodexMemoryConfig(project)) {
+      return incompleteDiagnosis(recovery);
+    }
     return Object.freeze({
       schema_version: 1,
       status: state.git === "none" ? "limited" : "complete",

package/scripts/test-bootstrap-untracked.sh

@@ -55,6 +55,7 @@ git -C "$tmp/repo" init -q
 [[ -f "$tmp/repo/.ai/start-claude.sh" ]] || fail "scaffold missing"
 [[ -x "$tmp/repo/.ai/start-kimi.sh" ]] || fail "Kimi launcher missing"
 [[ -x "$tmp/repo/.ai/start-qwen.sh" ]] || fail "Qwen launcher missing"
+[[ -x "$tmp/repo/.ai/start-codex.sh" ]] || fail "Codex launcher missing"
 [[ -f "$tmp/repo/.planning/config.json" ]] || fail "planning layer missing"
 graph_policy="$tmp/repo/.planning/graphs/policy.md"
 grep -qF '`uv tool install graphifyy`' "$graph_policy" ||
@@ -89,7 +90,7 @@ grep -qxF "/.agentfs/" "$tmp/repo/.git/info/exclude" || fail "missing /.agentfs/
 printf '%s\n' '{"schema_version":1,"capabilities":{"wiki":false},"logging":{"callbacks":true}}' >"$tmp/repo/.ai/capabilities.json"
 chmod 600 "$tmp/repo/.ai/capabilities.json"
 printf '%s\n' '# operator-owned environment' >"$tmp/repo/.ai/env.example"
-asset_paths='.ai/start-claude.sh .ai/start-opencode.sh .ai/start-pi.sh .ai/start-kimi.sh .ai/start-qwen.sh .ai/env.example .ai/trajectory-redaction.json .ai/capabilities.json .agentfs/.gitignore .planning/config.json .planning/wiki/index.md .planning/wiki/policy.md .planning/wiki/CONTRADICTIONS.md .planning/wiki/LOG.md .planning/alignment/policy.md .planning/alignment/gap-register.yaml .planning/graphs/policy.md .planning/graphs/.gitignore .planning/security/policy.md'
+asset_paths='.ai/start-claude.sh .ai/start-opencode.sh .ai/start-pi.sh .ai/start-kimi.sh .ai/start-qwen.sh .ai/start-codex.sh .ai/env.example .ai/trajectory-redaction.json .ai/capabilities.json .agentfs/.gitignore .planning/config.json .planning/wiki/index.md .planning/wiki/policy.md .planning/wiki/CONTRADICTIONS.md .planning/wiki/LOG.md .planning/alignment/policy.md .planning/alignment/gap-register.yaml .planning/graphs/policy.md .planning/graphs/.gitignore .planning/security/policy.md'
 mkdir -p "$tmp/assets-before"
 for path in $asset_paths; do
   cp "$tmp/repo/$path" "$tmp/assets-before/${path//\//__}"

package/scripts/test-cli-dispatch.sh

@@ -15,6 +15,7 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 "$cairn" help | grep -q "cairn memory-server" || fail "help missing memory-server"
 "$cairn" help | grep -q "cairn notes" || fail "help missing notes"
 "$cairn" help | grep -q "cairn artifact <list|show|delete|prune>" || fail "help missing artifact"
+"$cairn" help | grep -q "cairn evidence <list|show|delete|prune|doctor>" || fail "help missing evidence"
 "$cairn" help | grep -q "cairn capabilities <list|status|enable|disable|reset|logging>" || fail "help missing capabilities"
 "$cairn" help | grep -q "cairn mcp-tools <list|status|set|reset>" || fail "help missing mcp-tools"
 "$cairn" help | grep -q "cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>" || fail "help missing pack"
@@ -24,6 +25,7 @@ tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 "$cairn" sync-kimi --help >/dev/null 2>&1 || fail "cairn sync-kimi dispatch"
 env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "cairn notes dispatch"
 "$cairn" artifact --help | grep -q "cairn artifact list" || fail "cairn artifact dispatch"
+"$cairn" evidence --help | grep -q "cairn evidence list" || fail "cairn evidence dispatch"
 "$cairn" capabilities --help >"$tmp/capabilities-help" 2>/dev/null || fail "cairn capabilities dispatch"
 "$cairn" mcp-tools list --json >"$tmp/mcp-tools.json" || fail "cairn mcp-tools dispatch"
 CAIRN_PACK_BASE_DIR="$tmp/pack-store" "$cairn" pack list --json >"$tmp/packs.json" || fail "cairn pack dispatch"
@@ -70,4 +72,4 @@ CAIRN_AGENTFS_BASE_DIR="$tmp/store" "$cairn" memory path | grep -qx "$tmp/store"
 "$cairn" audit-timer --render-only "$tmp/u" >/dev/null || fail "cairn audit-timer dispatch"
 [[ -f "$tmp/u/memory-wiki-audit.timer" ]] || fail "audit-timer render via cairn produced no units"
 
-echo "PASS: cairn dispatch (doctor, memory, artifact, audit-timer)"
+echo "PASS: cairn dispatch (doctor, memory, artifact, evidence, audit-timer)"

package/scripts/test-completion.sh

@@ -48,6 +48,9 @@ for shell in bash zsh fish; do
   grep -q 'pack' "$tmp/$shell"
   grep -q 'init.*lock.*validate.*install.*list.*show.*remove.*enable.*disable.*update.*skills.*approve-skill.*revoke-skill\|init lock validate install list show remove enable disable update skills approve-skill revoke-skill' "$tmp/$shell"
   grep -q -- '--purge-packs\|-l purge-packs' "$tmp/$shell"
+  grep -q 'evidence' "$tmp/$shell"
+  grep -q 'list.*show.*delete.*prune.*doctor\|list show delete prune doctor' "$tmp/$shell"
+  grep -q -- '--status\|-l status' "$tmp/$shell"
 done
 
 "$ROOT/bin/cairn" help >"$tmp/root-help"
@@ -64,6 +67,7 @@ if grep -q 'doctor-diagnosis' "$tmp/eval-help"; then
   exit 1
 fi
 grep -qF 'cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>' "$tmp/root-help"
+grep -qF 'cairn evidence <list|show|delete|prune|doctor>' "$tmp/root-help"
 node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/skill-help"
 for command in $skill_commands; do
   grep -q "cairn skill $command" "$tmp/skill-help"
@@ -87,10 +91,12 @@ grep -q '#compdef cairn' "$tmp/zsh"
 grep -q 'complete -c cairn' "$tmp/fish"
 for shell in bash zsh; do
   grep -q 'sync-pi' "$tmp/$shell"
+  grep -q 'codex' "$tmp/$shell"
   grep -q 'sync-kimi' "$tmp/$shell"
   grep -q -- '--live-root' "$tmp/$shell"
 done
 grep -q 'sync-pi' "$tmp/fish"
+grep -q 'codex' "$tmp/fish"
 grep -q 'sync-kimi' "$tmp/fish"
 grep -q 'not __fish_seen_subcommand_from .*sync-pi sync-kimi' "$tmp/fish"
 grep -q -- '-l live-root' "$tmp/fish"

package/scripts/test-harness-registry.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+node --input-type=module - "$ROOT" "$tmp" <<'NODE'
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const [root, sandbox] = process.argv.slice(2);
+const registry = await import(pathToFileURL(join(root, "scripts", "harness-registry.mjs")).href);
+assert.deepEqual(registry.HARNESS_IDS, ["claude", "opencode", "pi", "kimi", "qwen", "codex"]);
+assert.equal(new Set(registry.HARNESS_IDS).size, registry.HARNESS_IDS.length);
+for (const id of registry.HARNESS_IDS) {
+  const definition = registry.harnessDefinition(id);
+  assert.equal(definition.id, id);
+  assert.ok(definition.title);
+  assert.match(definition.launcher.path, new RegExp(`^\\.ai/start-${id}\\.sh$`));
+}
+assert.deepEqual(registry.harnessProjectAssets("codex", "local").map(({ path }) => path), [
+  ".ai/start-codex.sh",
+  ".codex/config.toml",
+]);
+assert.deepEqual(registry.requiredHarnessAssetPaths(["codex"], "local"), [".ai/start-codex.sh"]);
+assert.deepEqual(registry.requiredHarnessAssetPaths(["codex"], "none"), [".ai/start-codex.sh"]);
+assert.equal(registry.machineSyncCommand(["codex"]), null);
+
+const schema = JSON.parse(readFileSync(join(root, "schemas", "cairnkeep-setup.schema.json"), "utf8"));
+assert.deepEqual(schema.properties.harnesses.items.enum, registry.HARNESS_IDS, "setup schema drifted from harness registry");
+const policySchema = JSON.parse(readFileSync(join(root, "schemas", "cairnkeep-setup-policy.schema.json"), "utf8"));
+assert.deepEqual(policySchema.properties.defaults.properties.harnesses.items.enum, registry.HARNESS_IDS);
+assert.deepEqual(policySchema.properties.constraints.properties.harnesses.items.enum, registry.HARNESS_IDS);
+assert.deepEqual(policySchema.properties.constraints.properties.required_harnesses.items.enum, registry.HARNESS_IDS);
+
+const target = join(sandbox, "codex-project");
+const setup = spawnSync(join(root, "bin", "cairn"), [
+  "setup", target, "--git", "init", "--harness", "codex", "--memory", "local", "--yes", "--json",
+], { encoding: "utf8", shell: false });
+assert.equal(setup.status, 0, setup.stderr);
+const result = JSON.parse(setup.stdout);
+assert.deepEqual(result.harnesses, ["codex"]);
+assert.equal(result.machine_sync.command, null);
+assert.deepEqual(result.launch_commands, [".ai/start-codex.sh"]);
+assert.match(readFileSync(join(target, ".codex", "config.toml"), "utf8"), /\[mcp_servers\.cairn-memory\][\s\S]*command = "cairn"[\s\S]*args = \["memory-server"\]/);
+
+const fakeBin = join(sandbox, "bin");
+mkdirSync(fakeBin);
+const fakeCodex = join(fakeBin, "codex");
+writeFileSync(fakeCodex, "#!/bin/sh\nprintf '%s\\n' \"$PWD\" \"${CAIRN_REGISTRY_TEST:-}\" \"$*\"\n");
+chmodSync(fakeCodex, 0o755);
+writeFileSync(join(target, ".ai", ".env"), "CAIRN_REGISTRY_TEST=loaded\n", { mode: 0o600 });
+const launch = spawnSync(join(target, ".ai", "start-codex.sh"), ["--fixture"], {
+  encoding: "utf8",
+  shell: false,
+  env: { ...process.env, PATH: `${fakeBin}:${process.env.PATH}` },
+});
+assert.equal(launch.status, 0, launch.stderr);
+assert.deepEqual(launch.stdout.trim().split("\n"), [target, "loaded", "--fixture"]);
+
+const noMemory = join(sandbox, "codex-no-memory");
+const noMemorySetup = spawnSync(join(root, "bin", "cairn"), [
+  "setup", noMemory, "--git", "init", "--harness", "codex", "--memory", "none", "--yes",
+], { encoding: "utf8", shell: false });
+assert.equal(noMemorySetup.status, 0, noMemorySetup.stderr);
+assert.throws(() => readFileSync(join(noMemory, ".codex", "config.toml")), /ENOENT/);
+
+const collision = join(sandbox, "codex-existing-config");
+mkdirSync(join(collision, ".codex"), { recursive: true });
+writeFileSync(join(collision, ".codex", "config.toml"), "[features]\nfixture = true\n");
+const collisionSetup = spawnSync(join(root, "bin", "cairn"), [
+  "setup", collision, "--git", "init", "--harness", "codex", "--memory", "local", "--yes", "--json",
+], { encoding: "utf8", shell: false });
+assert.equal(collisionSetup.status, 0, collisionSetup.stderr);
+assert.equal(JSON.parse(collisionSetup.stdout).counts.skipped, 1);
+assert.equal(readFileSync(join(collision, ".codex", "config.toml"), "utf8"), "[features]\nfixture = true\n");
+const setupModule = await import(pathToFileURL(join(root, "scripts", "setup.mjs")).href);
+assert.equal(setupModule.diagnoseSetup(collision).status, "incomplete");
+writeFileSync(join(collision, ".codex", "config.toml"), [
+  "[features]", "fixture = true", "", "[mcp_servers.cairn-memory]", 'command = "cairn"', 'args = ["memory-server"]', "",
+].join("\n"));
+assert.equal(setupModule.diagnoseSetup(collision).status, "complete");
+const uninstall = spawnSync(join(root, "bin", "cairn"), ["uninstall", "--yes", collision], {
+  encoding: "utf8", shell: false, env: { ...process.env, HOME: join(sandbox, "home") },
+});
+assert.equal(uninstall.status, 0, uninstall.stderr);
+assert.match(readFileSync(join(collision, ".codex", "config.toml"), "utf8"), /fixture = true/);
+NODE
+
+echo "PASS: declarative harness registry and first-class Codex setup contract"

package/scripts/test-package-install.sh

@@ -46,6 +46,7 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ -x "$tmp/project/.ai/start-pi.sh" ]] || fail "bootstrap did not install an executable Pi launcher"
 [[ -x "$tmp/project/.ai/start-kimi.sh" ]] || fail "bootstrap did not install an executable Kimi launcher"
 [[ -x "$tmp/project/.ai/start-qwen.sh" ]] || fail "bootstrap did not install an executable Qwen launcher"
+[[ -x "$tmp/project/.ai/start-codex.sh" ]] || fail "bootstrap did not install an executable Codex launcher"
 [[ -f "$tmp/project/.planning/config.json" ]] || fail "bootstrap did not install the planning scaffold"
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
@@ -267,6 +268,10 @@ NODE
   fail "npm tarball omitted the Kimi launcher template"
 [[ -f "$installed_root/templates/start-qwen.sh.template" ]] || \
   fail "npm tarball omitted the Qwen launcher template"
+[[ -f "$installed_root/templates/start-codex.sh.template" ]] || \
+  fail "npm tarball omitted the Codex launcher template"
+[[ -f "$installed_root/templates/codex-config.toml.template" ]] || \
+  fail "npm tarball omitted the Codex MCP configuration template"
 [[ -f "$installed_root/schemas/note.schema.json" ]] || \
   fail "npm tarball omitted the note schema"
 [[ -f "$installed_root/schemas/memory-node.schema.json" ]] || \
@@ -287,6 +292,10 @@ for module in artifact-schema artifact-store compaction-normalize artifact-cli;
   [[ -f "$installed_root/mcp-memory-server/dist/$module.js" ]] || \
     fail "npm tarball omitted compiled $module"
 done
+for module in work-evidence-schema work-evidence-store work-evidence-cli; do
+  [[ -f "$installed_root/mcp-memory-server/dist/$module.js" ]] || \
+    fail "npm tarball omitted compiled $module"
+done
 [[ -x "$installed_root/claude/hooks/compaction-capture.sh" ]] || \
   fail "npm tarball omitted the executable Claude compaction hook"
 [[ -f "$installed_root/opencode/plugins/memory-capture.ts" ]] || \