@cairnkeep/cli 2.11.0 → 2.12.0

package/docs/native-windows.md

@@ -32,6 +32,20 @@ recovery contract as POSIX. It writes a restricted `.ai/cairnkeep.json` setup
 record and never syncs machine assets automatically. `cairn bootstrap` remains
 the deterministic compatibility primitive for existing scripts.
 
+For Codex memory without a harness-wide sync, select only Codex:
+
+```powershell
+cairn setup $Project --git init --harness codex --memory local --yes
+Set-Location $Project
+cairn doctor
+.\.ai\start-codex.cmd
+```
+
+Review `.codex\config.toml` and accept Codex's project-trust prompt. Setup does
+not edit the user-wide Codex configuration or grant trust. It preserves a
+different existing project configuration and doctor verifies a manually merged
+`mcp_servers.cairn-memory` table.
+
 Setup and bootstrap write both the established Unix launchers and native Windows
 launchers. Each `.cmd` file enters `start-harness.ps1`, loads `.ai/.env`, changes
 to the project root, and forwards arguments without shell interpolation.

package/docs/operating.md

@@ -70,7 +70,7 @@ cairn setup /path/to/project --git init --harness claude,pi --memory local --yes
 ```
 
 The deterministic form accepts `--git init|existing|none`, a comma-separated
-subset of `claude,opencode,pi,kimi,qwen`, and `--memory local|none`. `--git
+subset of `claude,opencode,pi,kimi,qwen,codex`, and `--memory local|none`. `--git
 existing` requires the target to be in an existing work tree. `--git init`
 requires Git and is the only non-interactive authorization to initialize a
 repository. `--git none` is an explicit limited mode: repository-aware features
@@ -91,8 +91,10 @@ assets. It contains no credentials, endpoints, or absolute paths.
 
 Setup never installs or refreshes machine-level harness assets. Its
 `machine_sync.automatic` field is always false, and the human output labels the
-reported command as not run automatically. Apply the relevant machine command
-explicitly, check it, then diagnose and launch:
+reported command as not run automatically. For selections such as Codex and
+Qwen that need no machine sync, `machine_sync.command` is `null` and the human
+output says that sync is not required. Apply any reported command explicitly,
+check it, then diagnose and launch:
 
 ```bash
 cairn sync --apply                    # Claude Code operating assets
@@ -105,6 +107,25 @@ cd /path/to/project && cairn doctor
 `cairn bootstrap [--untracked] PATH` remains available for scripts that depend
 on its original scaffold and Git-exclusion contract.
 
+## Setup order (Codex CLI)
+
+Codex uses project-scoped configuration, so setup owns the complete local MCP
+wiring without editing user-wide state:
+
+```bash
+npm install -g @cairnkeep/cli
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-codex.sh                    # native Windows: .\.ai\start-codex.cmd
+```
+
+Review `.codex/config.toml` and accept Codex's project-trust prompt before use.
+An existing different file is preserved and reported as skipped; merge the
+generated `mcp_servers.cairn-memory` table into it, then run `cairn doctor`.
+Uninstall leaves that operator-owned file intact. Selecting
+`--memory none` creates the launcher but deliberately omits the MCP entry.
+
 ## Setup order (Claude Code)
 
 The commands below install the default local topology: `cairn-memory` runs as a
@@ -865,13 +886,13 @@ maintain a running install — without forking the core. All are opt-in.
 ### Launcher seams
 
 The generic launchers (`.ai/start-claude.sh`, `.ai/start-opencode.sh`,
-`.ai/start-kimi.sh`, `.ai/start-qwen.sh`, and `.ai/start-pi.sh`) run optional hooks around the
+`.ai/start-kimi.sh`, `.ai/start-qwen.sh`, `.ai/start-codex.sh`, and `.ai/start-pi.sh`) run optional hooks around the
 harness, each a no-op when absent:
 
 | Seam | When | Purpose |
 |---|---|---|
 | `.ai/pre-launch.sh` | sourced after `.env`, before launch | export env (e.g. a provider base URL / auth), refresh credentials, or abort by returning non-zero |
-| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi, Qwen, and Pi leave the variable available to hooks but do not interpret it |
+| `CAIRN_EXTRA_SETTINGS` | read just before launch | path to a settings file layered on Claude Code (`--settings`) or OpenCode (`OPENCODE_CONFIG`); Kimi, Qwen, Codex, and Pi leave the variable available to hooks but do not interpret it |
 | `.ai/post-exit.sh` | sourced after the harness exits | teardown; `CAIRN_EXIT_STATUS` holds the exit code |
 
 A wrapper that needs a non-default provider drops a `pre-launch.sh` that renders

package/docs/privacy-and-data-flow.md

@@ -37,6 +37,7 @@ request unless the corresponding endpoint and credential are configured.
 | Explicit artifact read/show | The redacted body only when HTTP is separately enabled and the operator/client explicitly reads it | Local terminal/stdio, or the explicitly registered authenticated server |
 | Opt-in evaluation coordinator | Adapter-defined inference may leave the machine only according to the explicit operator-owned adapter and inherited environment | Local adapter subprocess; Cairnkeep supplies no provider, endpoint, credential, model, or network default |
 | Guided project setup | None | Selected scaffold assets and private `.ai/cairnkeep.json` state in the target; machine sync is never automatic |
+| Codex project setup and launcher | None | Local `.codex/config.toml` starts `cairn memory-server` over stdio only after the operator trusts the project |
 | Pi memory extension | None | Local `cairn memory-server` stdio child; no HTTP transport is inherited |
 
 Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
@@ -93,7 +94,7 @@ and its generated `revert.sh` restores exact bytes, modes, and layout. Explicit
 `cairn eval delete` and `prune` remove selected contained experiment trees with
 no hidden tombstone.
 
-## Guided setup and Pi bridge
+## Guided setup, Codex, and Pi bridge
 
 Guided setup performs a read-only target and Git preflight before project
 writes. Its schema-v1 `.ai/cairnkeep.json` record contains the package version,
@@ -103,6 +104,12 @@ endpoints, absolute paths, prompts, or memory values. The file is mode `0600`
 on POSIX and receives the private managed-file ACL on native Windows. Setup
 never invokes machine sync, and it does not start a harness or server child.
 
+Selecting Codex with local memory adds a non-secret project MCP table that
+invokes `cairn memory-server`. Setup never edits user-wide Codex configuration,
+grants project trust, or overwrites a different `.codex/config.toml`. Doctor can
+validate a manually merged Cairnkeep table without claiming ownership of the
+surrounding operator configuration, and uninstall leaves that file intact.
+
 When the explicitly installed Pi memory extension starts a session, it spawns
 `cairn memory-server` as a child in the project directory over local stdio. The
 bridge removes `MCP_HTTP_PORT` from the child environment, retains only the

package/docs/quickstart.md

@@ -0,0 +1,86 @@
+# Cairnkeep quickstart
+
+This is the shortest supported route from an empty directory or existing Git
+repository to durable, local agent memory. The default transport is stdio and
+the default store stays on this computer.
+
+## Codex CLI
+
+Install Cairnkeep, then let guided setup initialize an empty project and write
+Codex's project-scoped MCP entry:
+
+```bash
+npm install --global @cairnkeep/cli
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-codex.sh
+```
+
+Use `--git existing` instead when the target is already a Git work tree. On
+native Windows, launch with `.\.ai\start-codex.cmd`.
+
+Before the first session, review `.codex/config.toml` and accept Codex's project
+trust prompt. The generated entry runs `cairn memory-server` locally. Setup
+does not edit the user-wide Codex configuration and does not enable networking,
+telemetry, embeddings, session capture, or context packs.
+
+If `.codex/config.toml` already exists and differs, setup reports it as
+`skipped` and preserves it byte-for-byte. Merge this table into the existing
+file, then run `cairn doctor`:
+
+```toml
+[mcp_servers.cairn-memory]
+command = "cairn"
+args = ["memory-server"]
+```
+
+## Claude Code
+
+Claude Code has the full Cairnkeep operating layer, so it needs one explicit
+machine-level sync in addition to project setup:
+
+```bash
+npm install --global @cairnkeep/cli
+claude mcp add cairn-memory -s user -- cairn memory-server
+cairn sync --apply
+cairn setup /path/to/project --git init --harness claude --memory local --yes
+cd /path/to/project
+cairn doctor
+./.ai/start-claude.sh
+```
+
+Setup reports machine-level commands but never executes them. This keeps
+project scaffolding separate from harness-wide changes.
+
+## First memory cycle
+
+In a harness with Cairnkeep commands, remember one durable fact and recall it:
+
+```text
+> /remember Use transactional migrations for schema changes
+> /recall transactional migrations
+```
+
+In Codex or another MCP client, ask the client to call `memory_write`, then
+`memory_search`. Close the session, start a new one, and repeat the search. The
+result should survive the restart.
+
+## What setup owns
+
+`cairn setup` creates only the selected harness assets plus the common `.ai`,
+`.planning`, and `.agentfs` scaffold. It initializes Git only with explicit
+`--git init`, preserves unrelated files, does not overwrite modified files it
+does not own, and records managed digests in private `.ai/cairnkeep.json`.
+
+Useful follow-ups:
+
+```bash
+cairn setup . --git existing --harness codex --memory local --yes  # reconcile
+cairn doctor                                                       # diagnose
+cairn uninstall --dry-run .                                       # preview removal
+```
+
+For all harnesses, remote HTTP, storage, profiles, context packs, overlays, and
+recovery details, continue with [Operating Cairnkeep](operating.md) or the
+[learning path](learning/README.md).

package/examples/eval/bundled-fake.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",
@@ -64,6 +64,7 @@
     "memory",
     "agent",
     "claude-code",
+    "codex-cli",
     "opencode",
     "qwen-code",
     "pi-coding-agent",

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

@@ -16,7 +16,7 @@
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
         },
         "memory": {"enum": ["local", "none"]}
       }
@@ -35,13 +35,13 @@
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
         },
         "required_harnesses": {
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
         },
         "memory": {
           "type": "array",

package/schemas/cairnkeep-setup.schema.json

@@ -14,12 +14,12 @@
       "type": "array",
       "minItems": 1,
       "uniqueItems": true,
-      "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+      "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen", "codex"]}
     },
     "assets": {
       "type": "object",
       "propertyNames": {
-        "pattern": "^\\.(?:ai|planning|agentfs)/(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/-]+$"
+        "pattern": "^\\.(?:ai|planning|agentfs|codex)/(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/-]+$"
       },
       "additionalProperties": {
         "type": "object",

package/scripts/bootstrap.sh

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

package/scripts/completion.sh

@@ -1,11 +1,13 @@
 #!/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=()
@@ -18,7 +20,7 @@ _cairn_complete() {
   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") ) ;;
@@ -78,7 +80,7 @@ complete -F _cairn_complete cairn
 EOF
     ;;
   zsh)
-    cat <<'EOF'
+    sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 #compdef cairn
 _cairn() {
   local -a commands
@@ -112,7 +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:(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 -/' ;;
@@ -175,7 +177,7 @@ _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
@@ -188,7 +190,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

package/scripts/doctor.sh

@@ -443,18 +443,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",