@cairnkeep/cli 2.17.0 → 2.17.2

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.17.2] - 2026-09-02
+
+### Fixed
+
+- Generate the project Codex memory entry as `mcp_servers.cairn-memory-local`
+  instead of `cairn-memory`: Codex merges the user-wide and project MCP server
+  tables by id, so a project stdio entry collided with a user-wide remote
+  (url) entry of the same id and Codex >= 0.152 refused to start ("url is not
+  supported for stdio"). `cairn doctor` now diagnoses that legacy conflict
+  with a targeted recovery, and still accepts the old id on machines without
+  a user-wide remote entry.
+
+## [2.17.1] - 2026-08-31
+
+### Fixed
+
+- Release TTY stdin after every interactive `cairn setup` selector so setup
+  returns to the shell after completion, including through SSH terminals that
+  report stdin as already flowing.
+- Keep the context-usage receipt smoke fixture relative to the test run so its
+  doctor assertion cannot fail merely because a hard-coded timestamp aged out.
+
 ## [2.17.0] - 2026-08-29
 
 ### Added

package/docs/ecosystem.md

@@ -14,7 +14,6 @@ graph workflows have their own explicit companion requirements.
 
 | Tool | What it adds | Integration |
 |---|---|---|
-| [lean-ctx](https://github.com/yvgude/lean-ctx) | Compressed file reads, searches, shell output, and directory maps | Register it as an MCP server in the chosen harness |
 | [token-miser](https://github.com/cairnkeep/token-miser) | Model routing and compact codebase exploration | Configure `CAIRN_ROUTE_ENDPOINT` and/or `CAIRN_EXPLORE_BINARY` |
 | [rtk](https://github.com/rtk-ai/rtk) | Token-reduced output for common Git, npm, and Cargo commands | Install as a shell-level proxy; Cairnkeep wiring is not required |
 

package/docs/harness-compatibility.md

@@ -229,11 +229,16 @@ Native Windows uses `.\.ai\start-codex.cmd`. The generated
 `.codex/config.toml` contains only:
 
 ```toml
-[mcp_servers.cairn-memory]
+[mcp_servers.cairn-memory-local]
 command = "cairn"
 args = ["memory-server"]
 ```
 
+The id is `cairn-memory-local`, not `cairn-memory`: Codex merges the user-wide
+and project `mcp_servers` tables by id, so a project stdio entry named
+`cairn-memory` collides with a user-wide remote (url) entry of the same id and
+Codex >= 0.152 refuses to start.
+
 Review this file before accepting Codex's project-trust prompt. Cairnkeep does
 not grant trust, edit the user-wide Codex configuration, or start Codex during
 setup. If an operator-owned `.codex/config.toml` already differs, setup reports
@@ -252,10 +257,10 @@ writes during setup. An operator who has explicitly authorized a bounded,
 unattended workflow may add narrow per-tool policy to the isolated Codex config:
 
 ```toml
-[mcp_servers.cairn-memory.tools.memory_write]
+[mcp_servers.cairn-memory-local.tools.memory_write]
 approval_mode = "approve"
 
-[mcp_servers.cairn-memory.tools.memory_supersede]
+[mcp_servers.cairn-memory-local.tools.memory_supersede]
 approval_mode = "approve"
 ```
 

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.17.0
+**Baseline:** Cairnkeep 2.17.2
 **Last reviewed:** 2026-08-19
 
 This map prevents the course from drifting behind the product. It assigns each

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.17.0
+**Baseline:** Cairnkeep 2.17.2
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.17.0
+**Tested with:** Cairnkeep 2.17.2
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.17.0
+**Tested with:** Cairnkeep 2.17.2
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.17.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.17.1
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.17.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.17.1 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 
 ## Outcome
 
@@ -47,7 +47,7 @@ sync. Codex project trust remains an explicit operator decision.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.17.0
+   npm install --global @cairnkeep/cli@2.17.1
    cairn --version
    ```
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.0
+**Tested with:** Cairnkeep 2.17.2
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.17.0
+**Tested with:** Cairnkeep 2.17.2
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.17.0, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 
@@ -16,7 +16,7 @@ perform a reversible uninstall without relying on WSL or Git Bash.
 From PowerShell:
 
 ```powershell
-npm install --global @cairnkeep/cli@2.17.0
+npm install --global @cairnkeep/cli@2.17.1
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.17.0; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.17.2; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 

package/docs/learning/lessons/L24-okf-exchange.md

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L25-playbooks.md

@@ -1,7 +1,7 @@
 # L25 - Bounded workflow playbooks
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.17.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/native-windows.md

@@ -54,7 +54,7 @@ cairn doctor
 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.
+`mcp_servers.cairn-memory-local` 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

package/docs/operating.md

@@ -127,7 +127,7 @@ cairn doctor
 
 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`.
+generated `mcp_servers.cairn-memory-local` 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.
 

package/docs/quickstart.md

@@ -22,16 +22,19 @@ The wizard recommends the existing repository mode 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.
+trust prompt. The generated entry runs `cairn memory-server` locally under the
+server id `cairn-memory-local`: Codex merges the user-wide and project
+`mcp_servers` tables by id, so a project entry named `cairn-memory` collides
+with a user-wide remote (url) entry of the same id and Codex >= 0.152 refuses
+to start. 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]
+[mcp_servers.cairn-memory-local]
 command = "cairn"
 args = ["memory-server"]
 ```

package/examples/eval/bundled-fake.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.17.0",
+  "version": "2.17.2",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",
@@ -73,6 +73,6 @@
     "rag"
   ],
   "devDependencies": {
-    "@cyclonedx/cyclonedx-npm": "6.0.0"
+    "@cyclonedx/cyclonedx-npm": "6.0.1"
   }
 }

package/scripts/setup.mjs

@@ -10,6 +10,7 @@ import {
   readFileSync,
 } from "node:fs";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as defaultInput, stdout as defaultOutput, stderr as defaultError } from "node:process";
@@ -353,33 +354,63 @@ function readPrivateState(path) {
   }
 }
 
-function hasCodexMemoryConfig(project) {
-  const path = join(project, ".codex", "config.toml");
-  if (!existsSync(path)) return false;
+function readTomlConfig(path) {
+  if (!existsSync(path)) return null;
   const info = lstatSync(path);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) return false;
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) return null;
   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");
+    if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino || opened.size > 1024 * 1024) return null;
+    return readFileSync(descriptor, "utf8");
   } finally {
     if (descriptor !== undefined) closeSync(descriptor);
   }
+}
+
+function codexMemorySection(text, id) {
   const lines = text.split(/\r?\n/);
   const headers = lines.flatMap((line, index) => (
-    ["[mcp_servers.cairn-memory]", "[mcp_servers.\"cairn-memory\"]"].includes(line.trim()) ? [index] : []
+    [`[mcp_servers.${id}]`, `[mcp_servers."${id}"]`].includes(line.trim()) ? [index] : []
   ));
-  if (headers.length !== 1) return false;
+  if (headers.length !== 1) return null;
   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 lines.slice(start + 1, next < 0 ? lines.length : next).join("\n");
+}
+
+function isLocalMemorySection(section) {
   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;
 }
 
+function hasCodexMemoryConfig(project) {
+  const text = readTomlConfig(join(project, ".codex", "config.toml"));
+  if (text === null) return false;
+  // `cairn-memory-local` is the current template id; the bare `cairn-memory`
+  // stdio form is accepted so pre-existing setups still diagnose complete.
+  return ["cairn-memory-local", "cairn-memory"].some((id) => {
+    const section = codexMemorySection(text, id);
+    return section !== null && isLocalMemorySection(section);
+  });
+}
+
+// Codex merges the user-wide and project mcp_servers tables field by field, so
+// a legacy project stdio `cairn-memory` collides with a user-wide remote (url)
+// entry of the same id and Codex >= 0.152 refuses to start at all.
+function hasCodexRemoteMemoryConflict(project) {
+  const projectText = readTomlConfig(join(project, ".codex", "config.toml"));
+  if (projectText === null) return false;
+  const legacy = codexMemorySection(projectText, "cairn-memory");
+  if (legacy === null || !isLocalMemorySection(legacy)) return false;
+  const userHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  const userText = readTomlConfig(join(userHome, "config.toml"));
+  if (userText === null) return false;
+  const remote = codexMemorySection(userText, "cairn-memory");
+  return remote !== null && /^\s*url\s*=/m.test(remote);
+}
+
 export function diagnoseSetup(target = ".") {
   const project = resolve(target);
   const statePath = join(project, ".ai", "cairnkeep.json");
@@ -414,8 +445,11 @@ export function diagnoseSetup(target = ".") {
     }
     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);
+    if (state.memory === "local" && state.harnesses.includes("codex")) {
+      if (!hasCodexMemoryConfig(project)) return incompleteDiagnosis(recovery);
+      if (hasCodexRemoteMemoryConflict(project)) {
+        return incompleteDiagnosis(`rename the project table to [mcp_servers.cairn-memory-local] in .codex/config.toml (Codex >= 0.152 rejects a project stdio 'cairn-memory' when the user-wide config defines a remote 'cairn-memory'), or delete the file and re-run: ${recovery}`);
+      }
     }
     return Object.freeze({
       schema_version: 1,

package/scripts/terminal-prompts.mjs

@@ -37,7 +37,6 @@ async function runKeypressPrompt({ input, output, draw, accept }) {
   let settled = false;
   let keypressHandler = null;
   let rawChanged = false;
-  let resumed = false;
   let cursorHidden = false;
 
   const render = () => {
@@ -59,7 +58,6 @@ async function runKeypressPrompt({ input, output, draw, accept }) {
     }
     if (wasPaused && typeof input.resume === "function") {
       input.resume();
-      resumed = true;
     }
     output.write("\x1b[?25l");
     cursorHidden = true;
@@ -92,7 +90,11 @@ async function runKeypressPrompt({ input, output, draw, accept }) {
     clear();
     if (cursorHidden) output.write("\x1b[?25h");
     if (rawChanged) input.setRawMode(false);
-    if (resumed && typeof input.pause === "function") input.pause();
+    // A TTY can report itself as already flowing before the first prompt (for
+    // example through an SSH pseudo-terminal). Leaving it flowing keeps Node's
+    // event loop alive after setup has printed its final result. Always pause
+    // prompt input after removing our listener; the next selector resumes it.
+    if (typeof input.pause === "function") input.pause();
   }
 }
 

package/scripts/test-harness-registry.sh

@@ -57,7 +57,7 @@ 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"\]/);
+assert.match(readFileSync(join(target, ".codex", "config.toml"), "utf8"), /\[mcp_servers\.cairn-memory-local\][\s\S]*command = "cairn"[\s\S]*args = \["memory-server"\]/);
 
 const fakeBin = join(sandbox, "bin");
 mkdirSync(fakeBin);
@@ -94,7 +94,21 @@ 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"));
+// Isolate the user-wide Codex config: the legacy stdio id only conflicts when
+// the user-wide layer defines a remote (url) cairn-memory.
+const codexHome = join(sandbox, "codex-home");
+mkdirSync(codexHome);
+process.env.CODEX_HOME = codexHome;
 assert.equal(setupModule.diagnoseSetup(collision).status, "complete");
+writeFileSync(join(codexHome, "config.toml"), '[mcp_servers.cairn-memory]\nurl = "http://127.0.0.1:8788/mcp"\n');
+const conflict = setupModule.diagnoseSetup(collision);
+assert.equal(conflict.status, "incomplete");
+assert.match(conflict.recovery[0], /cairn-memory-local/);
+writeFileSync(join(collision, ".codex", "config.toml"), [
+  "[features]", "fixture = true", "", "[mcp_servers.cairn-memory-local]", 'command = "cairn"', 'args = ["memory-server"]', "",
+].join("\n"));
+assert.equal(setupModule.diagnoseSetup(collision).status, "complete");
+delete process.env.CODEX_HOME;
 const uninstall = spawnSync(join(root, "bin", "cairn"), ["uninstall", "--yes", collision], {
   encoding: "utf8", shell: false, env: { ...process.env, HOME: join(sandbox, "home") },
 });

package/scripts/test-release-sbom.sh

@@ -19,7 +19,7 @@ const manifest = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
 const lock = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
 const candidateWorkflow = fs.readFileSync(process.argv[4], "utf8");
 const publishWorkflow = fs.readFileSync(process.argv[5], "utf8");
-const expected = "6.0.0";
+const expected = "6.0.1";
 
 if (manifest.devDependencies?.["@cyclonedx/cyclonedx-npm"] !== expected) {
   throw new Error(`package.json must pin @cyclonedx/cyclonedx-npm exactly to ${expected}`);

package/scripts/test-setup-preflight.mjs

@@ -300,6 +300,19 @@ async function testTerminalSelectors(prompts) {
   await assert.rejects(cancelled, (error) => error?.status === 130 && /cancelled/i.test(error.message));
   assert.equal(input.isRaw, false);
   assert.equal(input.isPaused(), true);
+
+  const flowingInput = new FakeTTY();
+  flowingInput.paused = false;
+  const flowing = prompts.selectOnePrompt({
+    message: "Release flowing input",
+    choices: [{ value: "done", label: "Done" }],
+    input: flowingInput,
+    output: output.stream,
+  });
+  setImmediate(() => flowingInput.emit("keypress", "", { name: "return" }));
+  assert.equal(await flowing, "done");
+  assert.equal(flowingInput.isRaw, false);
+  assert.equal(flowingInput.isPaused(), true, "terminal prompt must release flowing stdin so the CLI can exit");
 }
 
 async function testStructuredSetupSelectors(setup, fixture) {

package/templates/PROJECT-INSTRUCTIONS.md.template

@@ -38,5 +38,4 @@ Scopes defined in `.opencode/memory.json`:
 ## Tool Roles
 - AgentFS is the durable structured memory layer.
 - AnythingLLM is the long-form document retrieval layer.
-- `lean-ctx` is the default context layer (reads, search, exploration), not durable project memory.
 - RTK is a recommended companion for shell-heavy sessions (git, listings, failing builds); Token Savior is not default.

package/templates/codex-config.toml.template

@@ -1,5 +1,10 @@
 # Cairnkeep project-scoped memory server. Codex loads project configuration only
 # after the project has been trusted.
-[mcp_servers.cairn-memory]
+#
+# The id is `cairn-memory-local`, not `cairn-memory`: Codex merges the user-wide
+# and project mcp_servers tables field by field, so a project stdio entry named
+# `cairn-memory` collides with a user-wide remote (url) entry of the same id and
+# Codex >= 0.152 refuses to start ("url is not supported for stdio").
+[mcp_servers.cairn-memory-local]
 command = "cairn"
 args = ["memory-server"]