@cairnkeep/cli 2.17.1 → 2.17.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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

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.1
+**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.1
+**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.1
+**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.1
+**Tested with:** Cairnkeep 2.17.2
 
 ## Outcome
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2 and Node.js 22 or newer
 
 ## Outcome
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.17.1
+**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.1
+**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.1 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.1 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.1, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.17.2, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 

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.1; 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.1 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.1 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.1","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.1",
+  "version": "2.17.2",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",

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/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/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"]