@cairnkeep/cli 2.22.2 → 2.22.3

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.22.3] - 2026-10-07
+
+### Fixed
+
+- Diagnose preserved custom setup files separately from generated-file
+  ownership. A complete scaffold no longer fails merely because setup skipped
+  caller-owned files or its ownership map is empty. Keep missing/unsafe asset,
+  launcher-executable and recorded digest/mode checks; never adopt, rewrite or
+  remove custom files during diagnosis. Add cross-platform regression controls
+  and clarify operating and guided-setup learning documentation.
+
 ## [2.22.2] - 2026-10-07
 
 ### Security

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.22.2
+**Baseline:** Cairnkeep 2.22.3
 **Last reviewed:** 2026-10-07
 
 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.22.2
+**Baseline:** Cairnkeep 2.22.3
 
 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.22.2
+**Tested with:** Cairnkeep 2.22.3
 
 ## Outcome
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.22.2
+**Tested with:** Cairnkeep 2.22.3
 
 ## 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.22.2
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.22.3
    ```
 
 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.22.2 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.22.3 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.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 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.22.2
+   npm install --global @cairnkeep/cli@2.22.3
    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.22.2
+**Tested with:** Cairnkeep 2.22.3
 
 ## 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.22.2
+**Tested with:** Cairnkeep 2.22.3
 
 ## 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.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 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.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 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.22.2, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3, 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.22.2
+npm install --global @cairnkeep/cli@2.22.3
 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.22.2; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.22.3; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 
@@ -54,6 +54,13 @@ records the selected Pi harness in private `.ai/cairnkeep.json`, and reports
 created, updated, unchanged, and skipped assets. Repeating the same `cairn
 setup` command should report the managed files as unchanged.
 
+When an existing project has customized launchers or scaffold files, setup
+preserves and skips them. Its private asset map tracks ownership, not a full
+inventory. Doctor accepts safely present custom files without adopting them,
+but still rejects missing files, links, non-executable POSIX launchers and
+changes to recorded owned assets. Do not replace a custom file just to satisfy
+a generated digest. Diagnosis does not change file contents or ownership.
+
 Project setup never changes the Pi installation. Apply and check machine assets
 explicitly, then diagnose the project again:
 

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

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 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.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L26-context-intelligence.md

@@ -1,7 +1,7 @@
 # L26 - Context intelligence with explicit authority
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L27-ecosystem-evidence.md

@@ -1,6 +1,6 @@
 # L27 - Evaluate context companions without moving authority
 
-**Tested with:** Cairnkeep 2.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L28-security-assurance.md

@@ -1,7 +1,7 @@
 # L28 - Verify Cairnkeep's security posture
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.22.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.3 and Node.js 22 or newer
 
 ## Outcome
 
@@ -11,7 +11,7 @@ and choose least authority for a network-facing MCP client.
 
 ## Prerequisites
 
-- Install Cairnkeep 2.22.2 or use a disposable source checkout.
+- Install Cairnkeep 2.22.3 or use a disposable source checkout.
 - Complete [L20 - Least-authority MCP tool profiles](L20-mcp-tool-profiles.md).
 - Use synthetic values only; never paste a real bearer token into a recording,
   terminal transcript, or issue.

package/docs/operating.md

@@ -94,6 +94,12 @@ returns the same schema-v1 result. The private mode-`0600`
 selected harnesses, and digests/modes/template identifiers for setup-owned
 assets. It contains no credentials, endpoints, or absolute paths.
 
+The asset map records ownership, not every file in the project. Existing custom
+files that setup skips remain caller-owned. Doctor checks that every required
+selected asset is a regular file under non-symlinked scaffold directories and
+that POSIX launchers are executable, without adopting or rewriting custom files.
+An empty ownership map is valid when all required assets were already present.
+
 Setup never installs or refreshes machine-level harness assets. Its
 `machine_sync.automatic` field is always false, and the human output labels each
 reported command as not run automatically. The JSON result's
@@ -1072,7 +1078,9 @@ Unsupported schema, SQLite failure, invalid full records, or digest corruption
 fails untouched with guidance to preserve the database before manual recovery.
 
 When `.ai/cairnkeep.json` exists, doctor also validates its private state,
-selected assets, digests, and modes. It reports `limited` for explicit
+selected assets, and the digests and modes of recorded setup-owned files.
+Preserved caller-owned files need safe presence, not a generated-file digest;
+doctor never claims ownership of them. It reports `limited` for explicit
 `--git none`, fails an incomplete or drifted setup with the recorded
 deterministic `cairn setup` recovery command, and checks the Pi machine
 extension when Pi was selected. `cairn sync-pi --apply` repairs that

package/examples/eval/bundled-fake.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.22.2",
+    "version": "2.22.3",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",

package/scripts/setup.mjs

@@ -344,6 +344,21 @@ function safeStateAsset(path, record) {
     && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(record.template);
 }
 
+function safeRequiredAsset(project, path, launcher) {
+  // Presence is not ownership: setup intentionally skips pre-existing custom
+  // files. Validate the selected asset without adopting or reading its content.
+  const parts = path.split("/");
+  let destination = project;
+  for (const part of parts.slice(0, -1)) {
+    destination = join(destination, part);
+    const parent = lstatSync(destination);
+    if (!parent.isDirectory() || parent.isSymbolicLink()) return false;
+  }
+  const info = lstatSync(join(destination, parts.at(-1)));
+  return info.isFile() && !info.isSymbolicLink()
+    && (!launcher || process.platform === "win32" || (info.mode & 0o100) !== 0);
+}
+
 function readPrivateState(path) {
   const info = lstatSync(path);
   if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024) throw new Error("unsafe");
@@ -435,8 +450,7 @@ export function diagnoseSetup(target = ".") {
         || state.harnesses.some((name) => !HARNESSES.includes(name))
         || !state.assets
         || typeof state.assets !== "object"
-        || Array.isArray(state.assets)
-        || Object.keys(state.assets).length === 0) return incompleteDiagnosis();
+        || Array.isArray(state.assets)) return incompleteDiagnosis();
 
     const recovery = `cairn setup . --git ${state.git} --harness ${state.harnesses.join(",")} --memory ${state.memory} --yes`;
     for (const [path, record] of Object.entries(state.assets)) {
@@ -449,7 +463,8 @@ export function diagnoseSetup(target = ".") {
       if (digest !== record.digest || (process.platform !== "win32" && (info.mode & 0o777) !== record.mode)) return incompleteDiagnosis(recovery);
     }
     const requiredAssets = [...COMMON_SETUP_ASSETS, ...requiredHarnessAssetPaths(state.harnesses, state.memory)];
-    if (requiredAssets.some((path) => !Object.hasOwn(state.assets, path))) return incompleteDiagnosis(recovery);
+    const launchers = new Set(state.harnesses.map((id) => HARNESS_REGISTRY.find((harness) => harness.id === id).launcher.path));
+    if (requiredAssets.some((path) => !safeRequiredAsset(project, path, launchers.has(path)))) return incompleteDiagnosis(recovery);
     if (state.memory === "local" && state.harnesses.includes("codex")) {
       if (!hasCodexMemoryConfig(project)) return incompleteDiagnosis(recovery);
       if (hasCodexRemoteMemoryConflict(project)) {

package/scripts/test-setup-diagnosis.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildSetupPlan } from "./setup-core.mjs";
+import { reconcileSetupPlan } from "./setup-reconcile.mjs";
+import { diagnoseSetup } from "./setup.mjs";
+
+const sandbox = mkdtempSync(join(tmpdir(), "cairn-setup-diagnosis-"));
+try {
+  const project = join(sandbox, "project");
+  mkdirSync(project);
+  const plan = buildSetupPlan({
+    target: project,
+    preflight: { targetState: "empty", gitExecutable: "available", repository: "work-tree" },
+    choices: { git: "existing", harnesses: ["claude", "opencode", "omp"], memory: "local", confirmed: true },
+  });
+  const customPaths = [".ai/env.example", ".ai/start-claude.sh", ".ai/start-opencode.sh", ".planning/graphs/policy.md"];
+  for (const path of customPaths) {
+    const file = join(project, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, path.endsWith(".sh") ? "#!/bin/sh\n# Project-owned launcher\nexit 0\n" : "Project-owned configuration\n");
+    chmodSync(file, path.endsWith(".sh") ? 0o755 : 0o640);
+  }
+  const before = new Map(customPaths.map(path => [path, { bytes: readFileSync(join(project, path)), mode: statSync(join(project, path)).mode, mtime: statSync(join(project, path)).mtimeMs }]));
+  const result = await reconcileSetupPlan(plan);
+  assert.equal(result.counts.skipped, customPaths.length);
+  for (const path of customPaths) assert.equal(Object.hasOwn(result.state.assets, path), false, "custom file became setup-owned");
+  const statePath = join(project, ".ai/cairnkeep.json");
+  const stateBytes = readFileSync(statePath);
+  assert.equal(diagnoseSetup(project).status, "complete", "safe preserved custom assets must not make setup incomplete");
+  for (const [path, saved] of before) {
+    assert.deepEqual(readFileSync(join(project, path)), saved.bytes);
+    assert.equal(statSync(join(project, path)).mode, saved.mode);
+    assert.equal(statSync(join(project, path)).mtimeMs, saved.mtime);
+  }
+  assert.deepEqual(readFileSync(statePath), stateBytes, "diagnosis rewrote ownership state");
+
+  for (const path of customPaths) {
+    const file = join(project, path), saved = `${file}.saved`;
+    renameSync(file, saved);
+    assert.equal(diagnoseSetup(project).status, "incomplete", "missing unowned asset accepted");
+    mkdirSync(file);
+    assert.equal(diagnoseSetup(project).status, "incomplete", "directory asset accepted");
+    rmSync(file, { recursive: true });
+    if (process.platform !== "win32") {
+      symlinkSync(saved, file);
+      assert.equal(diagnoseSetup(project).status, "incomplete", "symlink asset accepted");
+      rmSync(file);
+    }
+    renameSync(saved, file);
+  }
+  if (process.platform !== "win32") {
+    const launcher = join(project, ".ai/start-claude.sh");
+    chmodSync(launcher, 0o644);
+    assert.equal(diagnoseSetup(project).status, "incomplete", "non-executable custom launcher accepted");
+    chmodSync(launcher, 0o755);
+    const directory = join(project, ".planning/graphs"), saved = `${directory}.saved`;
+    renameSync(directory, saved);
+    symlinkSync(saved, directory, "dir");
+    assert.equal(diagnoseSetup(project).status, "incomplete", "symlinked asset ancestor accepted");
+    rmSync(directory);
+    renameSync(saved, directory);
+  }
+  const owned = join(project, ".ai/start-omp.sh"), ownedBytes = readFileSync(owned);
+  writeFileSync(owned, "owned drift\n");
+  assert.equal(diagnoseSetup(project).status, "incomplete", "owned digest drift accepted");
+  writeFileSync(owned, ownedBytes);
+  assert.equal(diagnoseSetup(project).status, "complete");
+
+  // An ownership map can legitimately be empty when every asset was preserved.
+  const unowned = { ...result.state, assets: {} };
+  writeFileSync(statePath, JSON.stringify(unowned) + "\n");
+  chmodSync(statePath, 0o600);
+  assert.equal(diagnoseSetup(project).status, "complete", "all-custom setup falsely requires owned files");
+  assert.deepEqual(JSON.parse(readFileSync(statePath)), unowned);
+  assert.equal(existsSync(join(project, ".ai/start-omp.sh")), true);
+
+  const codexProject = join(sandbox, "codex");
+  mkdirSync(codexProject);
+  const codexPlan = buildSetupPlan({
+    target: codexProject,
+    preflight: { targetState: "empty", gitExecutable: "available", repository: "work-tree" },
+    choices: { git: "existing", harnesses: ["codex"], memory: "local", confirmed: true },
+  });
+  const codexResult = await reconcileSetupPlan(codexPlan);
+  const codexState = join(codexProject, ".ai/cairnkeep.json");
+  writeFileSync(codexState, JSON.stringify({ ...codexResult.state, assets: {} }) + "\n");
+  chmodSync(codexState, 0o600);
+  assert.equal(diagnoseSetup(codexProject).status, "complete");
+  writeFileSync(join(codexProject, ".codex/config.toml"), "# Caller-owned but no memory server configured\n");
+  assert.equal(diagnoseSetup(codexProject).status, "incomplete", "empty ownership map bypassed Codex MCP validation");
+  console.log("PASS: setup diagnosis preserves custom ownership and rejects missing, unsafe, non-executable and drifted assets");
+} finally {
+  rmSync(sandbox, { recursive: true, force: true });
+}

package/scripts/test-windows-native.mjs

@@ -19,6 +19,8 @@ import { runNativeContainer } from "./cairn-container-cli.mjs";
 import { HARNESS_IDS } from "./harness-registry.mjs";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+// Runs on real Windows and POSIX, independently of shell-only doctor checks.
+await import("./test-setup-diagnosis.mjs");
 const sandbox = mkdtempSync(join(tmpdir(), "cairn-windows-native-"));
 const originalBase = process.env.CAIRN_AGENTFS_BASE_DIR;
 const originalPackBase = process.env.CAIRN_PACK_BASE_DIR;