@cairnkeep/cli 2.22.1 → 2.22.3

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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
+
+- Bind mutable private context-pack pointers, source records and graph-cache
+  reads to one opened descriptor. Reject replacement, non-private ownership,
+  symlink/special-file substitution, growth and invalid encoding under bounded
+  reads; close descriptors on success and failure. Update inspection uses the
+  same strict source-record parser as installation/listing.
+- Add deterministic replacement and denial controls, including fabricated
+  pointer approvals, bounded parsing and descriptor cleanup. Keep schemas,
+  feature gates and approval policy unchanged; update recovery/security and
+  learning guidance. Existing security-analysis findings remain visible.
+
 ## [2.22.1] - 2026-10-07
 
 ### Fixed

package/docs/context-packs.md

@@ -69,6 +69,15 @@ If the bounded wait expires, let the active update finish, inspect `cairn doctor
 for temporary remnants, and retry. A persistent lock is not proof of abandonment;
 never delete it blindly or change ACLs to silence the error.
 
+From 2.22.2, mutable private pointers, source records and graph-cache state are
+opened once and read through that descriptor under their existing size limits.
+Metadata, private ownership and path/parent identity are checked before and
+after reading. Concurrent replacement or growth fails closed: retry after the
+writer finishes, then inspect `cairn doctor` if the problem persists. Malformed
+state is reported without quoting private JSON content. Missing state is not
+an excuse to follow a dangling symlink or infer skill approval. These controls
+do not protect against a hostile process with the same account's full access.
+
 ## Retrieval and skill approval
 
 Set `CAIRN_CONTEXT_PACKS=1` and restart the memory server to register the

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.22.1
+**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.1
+**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.1
+**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.1
+**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.1
+   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.1 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.1 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.1
+   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.1
+**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.1
+**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.1 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.1 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.1, 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.1
+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.1; 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.1 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.1 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.1 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.1 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.1 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.1 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.
@@ -67,6 +67,7 @@ npm run security:baseline
 scripts/test-security-baseline.sh
 npm --prefix mcp-memory-server run check:security-assurance
 npm --prefix mcp-memory-server run check:http-guard
+node mcp-memory-server/scripts/smoke-context-pack-state.mjs
 ```
 
 The baseline rejects unpinned external Actions, `pull_request_target` and
@@ -83,6 +84,13 @@ Do not republish an immutable version to demonstrate the test.
 The smoke tests cover token non-disclosure, request bounds, and deterministic
 portable-path adversarial cases.
 
+The pack-state control deterministically substitutes a second valid pointer
+after metadata inspection. The descriptor-bound reader rejects it, including
+fabricated approvals; growth, unsafe types and non-private state are rejected
+under bounded reads. A resolved review thread or green CodeQL job does not mean
+all historical alerts are fixed: inspect current findings and test the actual
+boundary without dismissing results merely to improve an advisory score.
+
 ## Common failures
 
 - A private `.ai` file is group/world accessible on POSIX: restore mode `0600`.

package/docs/learning/video-scripts/V28-security-assurance.md

@@ -62,6 +62,13 @@ Windows contention/denial and unsafe-lock cases deterministically, then checks
 real cross-process exclusion. Explain bounded retry versus lock stealing; a
 Linux run with injected Windows errors is not native-Windows evidence.
 
+Run `node mcp-memory-server/scripts/smoke-context-pack-state.mjs` next. Explain
+check-then-reopen races with two synthetic pointer files: a valid metadata
+check must not authorize reading a replacement file. Show descriptor-bound
+rejection, bounded growth and cleanup; use no real private pointer/approval
+data. Distinguish resolved old review comments from current analysis findings,
+and do not imply a green CI run certifies an empty security backlog.
+
 Briefly open `.github/workflows/publish.yml` beside the permission table in
 `docs/releasing.md`. Contrast the read-only preparation job with the necessary
 npm and OCI publication grants. Explain that explicit maps deny unspecified

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/docs/security-assurance.md

@@ -46,6 +46,7 @@ be enabled and evaluated independently.
 |---|---|---|
 | Traversal, alternate separators, drive paths, ADS, forbidden Windows characters/device aliases, invalid Unicode, or case collisions in portable data | One cross-platform path validator is used by context packs, OKF, artifacts, and evaluations; deterministic adversarial cases run in the smoke suite | Filesystems can have additional locale- or mount-specific semantics; containment checks remain required at every write |
 | Symlink or special-file substitution | Canonical roots, non-symlink regular-file checks, atomic replacement, and existing symlink/race regression tests | A hostile process running as the same account can race or replace resources outside Cairnkeep's process boundary |
+| Replaced or growing private pack state between inspection and use | One descriptor for metadata and bounded content reads; name/parent identity rechecks, private ownership and encoding validation; deterministic replacement/denial controls | Concurrent legitimate replacement can require retry; these checks are not per-user ACLs or a defense against an account with full local control |
 | Concurrent context-pack project pointer updates | Exclusive directory locks, bounded Windows contention retries, unsafe-lock rejection, injected denial controls and native cross-process exclusion tests | A persistent lock can block progress; recovery never infers abandonment or steals the lock |
 | Unauthenticated or rebound HTTP access | HTTP refuses to start without a token, compares it in constant time, validates `Host`, denies CORS by default, and bounds headers, request time, keep-alive time, and bodies to 8 MiB | Bearer tokens are not user identities; deploy TLS at the ingress for non-loopback traffic |
 | Excessive MCP authority | Explicit MCP annotations, restrictive profiles, capability intersection, and separate HTTP consent for sensitive optional tools | The default profile remains `full` for compatibility; operators should choose `read-only` or `custom` for observation-only clients |

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.22.1","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/mcp-memory-server/dist/context-pack-state.js

@@ -0,0 +1,93 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { dirname } from "node:path";
+import { posixPrivateMetadataIsSafe, privatePathIsSafe } from "./platform-security.js";
+function sameFile(left, right) {
+    return right.isFile() && !right.isSymbolicLink()
+        && left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs
+        && left.uid === right.uid && left.mode === right.mode;
+}
+// Mutable private pack state must be inspected and read through one opened
+// descriptor. Pathname checks alone cannot authorize a later pathname read.
+export function readPrivatePackJson(path, options) {
+    const { label, maxBytes } = options;
+    let descriptor;
+    try {
+        const nonBlocking = process.platform === "win32" ? 0 : (constants.O_NONBLOCK ?? 0);
+        descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | nonBlocking);
+        const opened = fstatSync(descriptor);
+        if (!opened.isFile() || opened.size > maxBytes
+            || (process.platform !== "win32" && !posixPrivateMetadataIsSafe(opened))) {
+            throw new Error(`${label} is unsafe or too large.`);
+        }
+        const parent = lstatSync(dirname(path));
+        if (!parent.isDirectory() || parent.isSymbolicLink() || !sameFile(opened, lstatSync(path))) {
+            throw new Error(`${label} is unsafe or changed.`);
+        }
+        if (process.platform === "win32") {
+            if (!privatePathIsSafe(path))
+                throw new Error(`${label} is unsafe.`);
+            if (!sameFile(opened, lstatSync(path)))
+                throw new Error(`${label} changed during ACL inspection.`);
+        }
+        const buffer = Buffer.allocUnsafe(opened.size + 1);
+        let offset = 0;
+        while (offset < buffer.byteLength) {
+            const count = readSync(descriptor, buffer, offset, buffer.byteLength - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        const after = fstatSync(descriptor);
+        const named = lstatSync(path);
+        const parentAfter = lstatSync(dirname(path));
+        if (!sameFile(opened, after) || !sameFile(opened, named) || offset !== after.size
+            || parentAfter.isSymbolicLink() || !parentAfter.isDirectory()
+            || parent.dev !== parentAfter.dev || parent.ino !== parentAfter.ino) {
+            throw new Error(`${label} changed while it was being read.`);
+        }
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
+        }
+        catch {
+            throw new Error(`${label} contains invalid UTF-8.`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${label} contains invalid JSON.`);
+        }
+    }
+    catch (error) {
+        if (descriptor === undefined && options.optional && error.code === "ENOENT") {
+            // A dangling link is unsafe state, not an absent project/source.
+            try {
+                lstatSync(path);
+                throw new Error(`${label} is unsafe or changed.`);
+            }
+            catch (missingError) {
+                if (missingError.code !== "ENOENT")
+                    throw missingError;
+            }
+            try {
+                const parent = lstatSync(dirname(path));
+                if (!parent.isDirectory() || parent.isSymbolicLink())
+                    throw new Error(`${label} directory is unsafe.`);
+            }
+            catch (parentError) {
+                if (parentError.code !== "ENOENT")
+                    throw parentError;
+            }
+            return undefined;
+        }
+        if (error instanceof Error && error.message.startsWith(`${label} `))
+            throw error;
+        throw new Error(`${label} is unsafe or unreadable.`);
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}

package/mcp-memory-server/dist/context-pack.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { constants, existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { constants, existsSync, lstatSync, realpathSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -9,9 +9,10 @@ import { z } from "zod";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText } from "./embeddings.js";
 import { doctorProgressiveContextCache, loadProgressiveContext, publicTree, selectHierarchicalFiles, } from "./context-pack-retrieval.js";
 import { indexOkfBundle, validateOkfBundle, validatedOkfFileContent } from "./okf.js";
-import { atomicReplace, hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
+import { atomicReplace, hardenPrivatePath } from "./platform-security.js";
 import { portablePathCollisionKey, portableRelativePathIssue } from "./path-security.js";
 import { acquireContextPackPointerLock } from "./context-pack-lock.js";
+import { readPrivatePackJson } from "./context-pack-state.js";
 const execFileAsync = promisify(execFile);
 export const CONTEXT_PACK_MANIFEST = "context-pack.json";
 export const CONTEXT_PACK_MAX_FILE_BYTES = 1024 * 1024;
@@ -78,15 +79,9 @@ function assertUtf8(bytes, path) {
 function readPackSource(digest) {
     const directory = join(packBaseDir(), "sources");
     const path = join(directory, `${digest}.json`);
-    if (!existsSync(path))
+    const value = readPrivatePackJson(path, { label: "Context pack source record", maxBytes: 64 * 1024, optional: true });
+    if (value === undefined)
         return undefined;
-    const directoryInfo = lstatSync(directory);
-    const info = lstatSync(path);
-    if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink() || !info.isFile() || info.isSymbolicLink()
-        || info.size > 64 * 1024 || !privatePathIsSafe(path)) {
-        throw new Error(`Context pack source record is unsafe: ${digest}`);
-    }
-    const value = JSON.parse(readFileSync(path, "utf8"));
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error(`Context pack source record is invalid: ${digest}`);
     const record = value;
@@ -604,13 +599,8 @@ function parseProjectPointer(value, expectedId) {
 }
 export function readProjectPointer(options) {
     const identity = projectIdentity(options);
-    if (!existsSync(identity.path))
-        return emptyPointer(identity.id);
-    const info = lstatSync(identity.path);
-    if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024
-        || !privatePathIsSafe(identity.path))
-        throw new Error("Context pack project pointer is unsafe.");
-    return parseProjectPointer(JSON.parse(readFileSync(identity.path, "utf8")), identity.id);
+    const value = readPrivatePackJson(identity.path, { label: "Context pack project pointer", maxBytes: 1024 * 1024, optional: true });
+    return value === undefined ? emptyPointer(identity.id) : parseProjectPointer(value, identity.id);
 }
 async function acquirePointerLock(options) {
     const identity = projectIdentity(options);
@@ -659,15 +649,10 @@ async function allPointers() {
         throw new Error("Context pack project pointer directory is unsafe.");
     const result = [];
     for (const entry of await readdir(directory, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith(".json"))
+        if (!entry.name.endsWith(".json"))
             continue;
         const path = join(directory, entry.name);
-        const info = lstatSync(path);
-        if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024
-            || !privatePathIsSafe(path)) {
-            throw new Error(`Context pack project pointer is unsafe: ${path}`);
-        }
-        const raw = JSON.parse(await readFile(path, "utf8"));
+        const raw = readPrivatePackJson(path, { label: "Context pack project pointer", maxBytes: 1024 * 1024 });
         const value = raw;
         if (typeof value.project_id !== "string")
             throw new Error("Context pack project pointer is invalid.");
@@ -1149,14 +1134,14 @@ export async function doctorContextPacks(options = {}) {
             for (const entry of await readdir(graphDirectory, { withFileTypes: true })) {
                 const match = /^([a-f0-9]{64})\.json$/.exec(entry.name);
                 const path = join(graphDirectory, entry.name);
-                if (!entry.isFile() || entry.isSymbolicLink() || !match || lstatSync(path).size > CONTEXT_PACK_MAX_FILE_BYTES || !privatePathIsSafe(path)) {
+                if (!entry.isFile() || entry.isSymbolicLink() || !match) {
                     issues.push(`Invalid context pack graph cache entry: ${entry.name}`);
                     continue;
                 }
                 if (!existsSync(objectRoot(match[1])))
                     issues.push(`Orphaned context pack graph cache: ${entry.name}`);
                 try {
-                    const cached = JSON.parse(await readFile(path, "utf8"));
+                    const cached = readPrivatePackJson(path, { label: "Context pack graph cache", maxBytes: CONTEXT_PACK_MAX_FILE_BYTES });
                     if (cached.schema_version !== 1 || !Array.isArray(cached.files) || !Array.isArray(cached.diagnostics))
                         throw new Error("invalid graph cache schema");
                     const expected = expectedGraphs.get(match[1]);
@@ -1212,8 +1197,9 @@ export async function inspectContextPackUpdate(selector, options) {
     const enabled = pointer.enabled.find((entry) => entry.id === selector || entry.digest === selector || entry.digest.startsWith(selector));
     if (!enabled)
         throw new Error("Context pack is not enabled for this project.");
-    const sourceRecord = JSON.parse(await readFile(join(packBaseDir(), "sources", `${enabled.digest}.json`), "utf8"));
-    const source = sourceRecord.source;
+    const source = readPackSource(enabled.digest);
+    if (!source)
+        throw new Error("Context pack source record is missing.");
     const current = await validateContextPack(objectRoot(enabled.digest));
     const materialized = await materializeSource(source.kind === "local" ? source.path : source.url, source.kind === "git" ? source.ref : undefined);
     let prepared;

package/mcp-memory-server/package.json

@@ -51,7 +51,7 @@
         "check:graph-cli": "node scripts/smoke-graph-cli.mjs",
         "check:mcp-trust": "node scripts/smoke-mcp-trust.mjs",
         "check:pi-mcp-bridge": "node scripts/smoke-pi-mcp-bridge.mjs",
-        "check:context-pack": "node scripts/smoke-context-pack-lock.mjs && node scripts/smoke-context-pack.mjs",
+        "check:context-pack": "node scripts/smoke-context-pack-state.mjs && node scripts/smoke-context-pack-lock.mjs && node scripts/smoke-context-pack.mjs",
         "check:context-pack-retrieval": "node scripts/smoke-context-pack-retrieval.mjs",
         "check:context-pack-v216-compat": "node scripts/smoke-context-pack-v216-compat.mjs",
         "check:context-usage": "node scripts/smoke-context-usage.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.22.1",
+    "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;