@cairnkeep/cli 2.22.0 → 2.22.2

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [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
+
+- Handle bounded Windows context-pack pointer-lock contention during concurrent
+  updates, including delete-pending access errors. Preserve exclusive ownership,
+  unsafe-lock rejection, denied access and the existing retry budget; never
+  steal another writer's lock. Add deterministic fault controls and native
+  cross-process exclusion coverage without changing persisted data or approval.
+- Align lesson npm/container installation commands with the current release;
+  add a regression rejecting stale pins and update Windows/context-pack recovery
+  guidance and learning baselines.
+
+### CI
+
+- Restrict publication token permissions to the preparation, npm and container
+  jobs that need them. Read-only workflow defaults and parsed-YAML positive/
+  mutation controls reject unnecessary authority and missing provenance grants.
+  Update maintainer guidance and the security learning/video supplement; no
+  runtime package or deployed configuration change is required.
+
 ## [2.22.0] - 2026-10-07
 
 ### Added

package/docs/context-packs.md

@@ -59,6 +59,25 @@ cairn pack update my-pack --apply --confirm CANDIDATE-DIGEST --project ./project
 requires the candidate digest, installs an immutable object, and atomically
 switches only the named project.
 
+Project enablement, disablement and skill approvals serialize through an
+exclusive directory lock before reading/replacing the pointer. Windows can
+temporarily report access errors while a previous directory deletion completes;
+2.22.1 retries this contention under the existing 200-attempt, 10 ms wait budget.
+Unsafe symlink/non-directory locks and unrelated access failures are rejected.
+No contender removes another writer's lock or grants approval on a failed write.
+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.0
+**Baseline:** Cairnkeep 2.22.2
 **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.0
+**Baseline:** Cairnkeep 2.22.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.22.0
+**Tested with:** Cairnkeep 2.22.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.22.0
+**Tested with:** Cairnkeep 2.22.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.1
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.22.2
    ```
 
 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.1 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.22.2 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.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.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.1
+   npm install --global @cairnkeep/cli@2.22.2
    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.0
+**Tested with:** Cairnkeep 2.22.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.22.0
+**Tested with:** Cairnkeep 2.22.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.22.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.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.22.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.2 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome
@@ -54,6 +54,10 @@ copies them into a harness.
   an enabled digest all fail closed.
 - Enabling the pack does not expose a skill until its current file digest is
   approved.
+- A concurrent project update can exhaust the bounded pointer-lock wait. Let
+  the writer finish, inspect `cairn doctor`, then retry; do not delete another
+  writer's lock or weaken permissions. Windows contention recovery is included
+  in 2.22.1, with symlink/non-directory locks still rejected.
 
 ## Privacy and trust boundary
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.22.0, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.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.1
+npm install --global @cairnkeep/cli@2.22.2
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'
@@ -62,6 +62,7 @@ the removed managed assets.
 | Hook registration reports drift | Managed `.cmd` hook or settings entry is absent | Run `cairn sync --apply`, then repeat `cairn sync --check` |
 | Memory export fails | `sqlite3.exe` is absent | Install SQLite and confirm `Get-Command sqlite3.exe`; runtime and import remain available |
 | A private-state check fails | The file inherited a broader ACL | Preserve the file, inspect it with `Get-Acl`, and recreate it through the owning Cairnkeep command |
+| A context-pack project update is locked | Another writer is active or a directory remains delete-pending | Allow the writer to finish, inspect `cairn doctor`, then retry; never blindly delete a lock or weaken ACLs |
 
 ## Privacy and trust boundary
 

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.0; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.22.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.22.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.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.22.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.2 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.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.2 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.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.2 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.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.2 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.0 or use a disposable source checkout.
+- Install Cairnkeep 2.22.2 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,12 +67,30 @@ 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 and `pull_request_target`. The
-smoke tests cover token non-disclosure, request bounds, and deterministic
+The baseline rejects unpinned external Actions, `pull_request_target` and
+workflow-wide write permissions. It also checks the exact preparation/npm/OCI
+job permission maps, including missing provenance grants and unnecessary write
+authority. Inspect `.github/workflows/publish.yml` and compare its maps with
+[Releasing](../../releasing.md): preparation must not inherit publishing or
+signing authority. Unspecified entries in an explicit job map are denied.
+
+These are static contract checks, not a live publication test. The npm secret
+is a separate credential, and steps within one job share its token authority.
+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

@@ -56,6 +56,26 @@ Highlight full-SHA action pins, CodeQL, dependency review, token non-leakage,
 portable Windows/POSIX path cases, and the HTTP 413 test. Do not show repository
 secrets or live security-alert details.
 
+Include the offline pointer-lock control in a source checkout:
+`node mcp-memory-server/scripts/smoke-context-pack-lock.mjs`. It reproduces
+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
+permissions, but steps in a job still share authority and the npm secret is
+separate. The baseline checks declared grants; do not present it as a successful
+live publish or rerun a release merely for this recording.
+
 ### 9:20–10:30 — Read the residual risks
 
 End on `docs/security-assurance.md`, not on a green checkmark. Call out the

package/docs/releasing.md

@@ -3,6 +3,23 @@
 Publishing is driven by a GitHub Release. Maintainers do not publish the package
 from a workstation.
 
+## Advisory Scorecard recovery
+
+The repository's Actions policy must allow the exact pinned
+`ossf/scorecard-action@<full-SHA-from-scorecard.yml>` reference. An entry ending
+in `scorecard-action/*` does not allow the root action. Keep SHA pinning required;
+do not enable all third-party actions to recover this one workflow.
+
+If GitHub rejects a run before creating any jobs and refuses to retry it, fix
+the repository allowlist and start a fresh advisory analysis explicitly:
+
+```bash
+gh workflow run scorecard.yml --ref main
+```
+
+This does not bypass required platform, CodeQL or dependency-review gates and
+does not require republishing the npm package.
+
 ## Release contract
 
 1. Update the root `package.json` version and `CHANGELOG.md` on a pull request.
@@ -52,11 +69,28 @@ different version or tree.
 
 The repository must provide an `NPM_TOKEN` Actions secret authorized to publish
 `@cairnkeep/cli`. Keep that credential out of local files and rotate it according
-to the npm account's security policy. The workflow grants `actions: read`,
-`contents: write`, `packages: write`, `attestations: write`, and
-`id-token: write`. Read access resolves the successful tree-addressed CI
-artifact; the last two permissions are required for registry-backed build
-provenance.
+to the npm account's security policy. Workflow defaults grant only
+`contents: read`; publication authority is explicit and job-scoped:
+
+| Job | Token permissions | Purpose |
+|---|---|---|
+| `prepare` | `contents: read`, `actions: read` | Check the tag and download the successful exact-tree CI candidate; no publication or signing authority |
+| `npm` | `contents: write`, `id-token: write` | Attach verified release assets and request npm provenance; registry publication uses the separate `NPM_TOKEN` |
+| `containers` | `contents: read`, `packages: write`, `attestations: write`, `id-token: write`, `artifact-metadata: write` | Read source, publish OCI images, sign/upload provenance and create the pinned action's registry storage record |
+
+Each job declares its complete permission map. Unspecified token permissions
+are denied rather than inherited; see [GitHub's permission semantics](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions).
+The container grant retains `artifact-metadata: write` because the pinned
+[attestation implementation](https://github.com/actions/attest/blob/508db95dd578ae2727ebd6217d5ba78e4fbda05d/README.md#usage)
+creates a storage record. Do not remove required provenance permissions merely
+to improve an advisory score.
+
+The parsed-YAML baseline rejects workflow-wide writes, unexpected publication
+jobs and any missing or excessive grant in these maps. Its positive control
+and mutation tests verify the declared contract, not GitHub's execution or a
+future privileged publication. Keep the required platform/security gates and
+verify the next normal release's publication and attestations separately.
+CI-only permission changes do not require republishing an immutable version.
 
 GitHub creates each new GHCR package as private. After the first container
 release, a package administrator must change both `cairnkeep` and

package/docs/security-assurance.md

@@ -46,6 +46,8 @@ 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 |
 | Malicious repository or context content influencing an agent | Memory results are locators, skills need digest-bound approval, pack content stays read-only, and maintained source must be verified | Prompt injection is not solved; the harness/model must continue treating retrieved text as untrusted data |
@@ -105,6 +107,16 @@ provenance, produces CycloneDX 1.6 and container SBOMs, and attests container
 provenance. A digest proves content integrity, not publisher identity; verify
 the repository, release tag, registry namespace, and provenance together.
 
+Workflow token defaults are read-only. Publication grants are explicit per job:
+candidate preparation receives only source/Actions read access, npm receives
+release-attachment and provenance authority, and container publication receives
+registry/signing/attestation/storage-record authority without release-write
+access. See the exact maps in [Releasing](releasing.md). The security baseline
+rejects excess and missing grants with positive and adversarial controls.
+This reduces unnecessary token authority; it neither isolates steps within a
+job nor constrains the separate npm publishing secret. Static checks do not
+prove a future privileged publish run succeeds.
+
 ## Deliberate non-goals and residual risks
 
 - Cairnkeep is not a sandbox, endpoint-security product, secret manager, TLS

package/examples/eval/bundled-fake.json

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

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

@@ -0,0 +1,48 @@
+import { lstatSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+const filesystem = {
+    platform: process.platform,
+    create: (path) => mkdir(path, { mode: 0o700 }),
+    inspect: (path) => lstatSync(path),
+    remove: (path) => rm(path, { recursive: true, force: true }),
+    wait: (milliseconds) => new Promise((resolveWait) => setTimeout(resolveWait, milliseconds)),
+};
+// The internal filesystem seam lets offline controls reproduce platform errors
+// without replacing process.platform or weakening the real filesystem checks.
+export async function acquireContextPackPointerLock(lock, operations = filesystem) {
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+        try {
+            await operations.create(lock);
+            return () => operations.remove(lock);
+        }
+        catch (error) {
+            const code = error.code;
+            const windowsContention = operations.platform === "win32" && code === "EPERM";
+            if (code !== "EEXIST" && !windowsContention)
+                throw error;
+            let info;
+            try {
+                info = operations.inspect(lock);
+            }
+            catch (inspectionError) {
+                const inspectionCode = inspectionError.code;
+                if (inspectionCode === "ENOENT") {
+                    // A Windows delete-pending directory can temporarily appear
+                    // absent; pace this case under the same bounded retry budget.
+                    if (windowsContention)
+                        await operations.wait(10);
+                    continue;
+                }
+                if (operations.platform === "win32" && ["EPERM", "EBUSY"].includes(inspectionCode ?? "")) {
+                    await operations.wait(10);
+                    continue;
+                }
+                throw inspectionError;
+            }
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Context pack project pointer lock is unsafe.");
+            await operations.wait(10);
+        }
+    }
+    throw new Error("Context pack project pointer is locked; retry after the active update finishes.");
+}

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,8 +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;
@@ -77,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;
@@ -603,44 +599,13 @@ 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);
-}
-function delay(milliseconds) {
-    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+    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);
     await mkdir(dirname(identity.path), { recursive: true, mode: 0o700 });
-    const lock = `${identity.path}.lock`;
-    for (let attempt = 0; attempt < 200; attempt += 1) {
-        try {
-            await mkdir(lock, { mode: 0o700 });
-            return () => rm(lock, { recursive: true, force: true });
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            let info;
-            try {
-                info = lstatSync(lock);
-            }
-            catch (inspectionError) {
-                if (inspectionError.code === "ENOENT")
-                    continue;
-                throw inspectionError;
-            }
-            if (!info.isDirectory() || info.isSymbolicLink())
-                throw new Error("Context pack project pointer lock is unsafe.");
-            await delay(10);
-        }
-    }
-    throw new Error("Context pack project pointer is locked; retry after the active update finishes.");
+    return acquireContextPackPointerLock(`${identity.path}.lock`);
 }
 async function mutateProjectPointer(options, mutate) {
     const release = await acquirePointerLock(options);
@@ -684,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.");
@@ -1174,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]);
@@ -1237,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.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.0",
+    "version": "2.22.2",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",

package/scripts/test-learning-docs.sh

@@ -74,6 +74,7 @@ done < <(bin/cairn help | sed -n 's/^  cairn \([a-z-]*\).*/\1/p' | sort -u)
 node <<'NODE'
 const { existsSync, readdirSync, readFileSync } = require("node:fs");
 const { dirname, resolve } = require("node:path");
+const packageVersion = JSON.parse(readFileSync("package.json", "utf8")).version;
 
 function markdownFiles(root) {
   return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
@@ -84,6 +85,13 @@ function markdownFiles(root) {
 
 for (const file of markdownFiles("docs/learning")) {
   const text = readFileSync(file, "utf8");
+  if (file.startsWith("docs/learning/lessons/")) {
+    for (const match of text.matchAll(/(?:@cairnkeep\/cli@|ghcr\.io\/cairnkeep\/cairnkeep(?:-workspace)?:)(\d+\.\d+\.\d+(?:-[\w.-]+)?)/g)) {
+      if (match[1] !== packageVersion) {
+        throw new Error(`stale installation command in ${file}: ${match[1]} instead of ${packageVersion}`);
+      }
+    }
+  }
   for (const match of text.matchAll(/\]\(([^)]+)\)/g)) {
     const target = match[1].split("#", 1)[0];
     if (!target || /^[a-z]+:/i.test(target)) continue;

package/scripts/verify-security-baseline.mjs

@@ -35,6 +35,10 @@ function walk(value, visit, path = "workflow") {
 
 function validateWorkflow(name, workflow) {
     assert.ok(workflow && typeof workflow === "object" && !Array.isArray(workflow), `${name} is not a workflow mapping`);
+    assert.ok(workflow.permissions && typeof workflow.permissions === "object" && !Array.isArray(workflow.permissions), `${name} must have an explicit workflow permission mapping`);
+    for (const [permission, level] of Object.entries(workflow.permissions)) {
+        assert.ok(["read", "none"].includes(level), `${name} has a non-read-only workflow permission: ${permission}`);
+    }
     const triggers = workflow.on;
     const triggerNames = typeof triggers === "string" ? [triggers] : Array.isArray(triggers) ? triggers : Object.keys(triggers ?? {});
     assert.ok(!triggerNames.includes("pull_request_target"), `${name} uses pull_request_target`);
@@ -51,24 +55,81 @@ function validateWorkflow(name, workflow) {
     });
 }
 
-for (const { name, workflow } of sources) validateWorkflow(name, workflow);
+const PUBLICATION_PERMISSIONS = {
+    prepare: { actions: "read", contents: "read" },
+    npm: { contents: "write", "id-token": "write" },
+    containers: {
+        contents: "read",
+        packages: "write",
+        attestations: "write",
+        "id-token": "write",
+        "artifact-metadata": "write",
+    },
+};
+
+function validatePublicationPermissions(workflow) {
+    validateWorkflow("publish.yml", workflow);
+    assert.deepEqual(workflow.permissions, { contents: "read" }, "publication workflow default must be contents-read only");
+    assert.deepEqual(Object.keys(workflow.jobs).sort(), Object.keys(PUBLICATION_PERMISSIONS).sort(), "publication jobs require explicit permission review");
+    for (const [job, permissions] of Object.entries(PUBLICATION_PERMISSIONS)) {
+        assert.deepEqual(workflow.jobs[job].permissions, permissions, `publication ${job} permissions must match its reviewed tasks`);
+    }
+}
+
+const publish = sources.find(({ name }) => name === "publish.yml")?.workflow;
+assert.ok(publish, "publication workflow is missing");
+const permissionControl = structuredClone(publish);
+permissionControl.permissions = { contents: "read" };
+for (const [job, permissions] of Object.entries(PUBLICATION_PERMISSIONS)) {
+    permissionControl.jobs[job].permissions = structuredClone(permissions);
+}
+validatePublicationPermissions(permissionControl);
+
+let permissionFixtures = 0;
+function rejectPermissionMutation(mutate, expected) {
+    const fixture = structuredClone(permissionControl);
+    mutate(fixture);
+    assert.throws(() => validatePublicationPermissions(fixture), expected, "unsafe publication permission mutation was accepted");
+    permissionFixtures += 1;
+}
+for (const permission of ["actions", "contents", "id-token", "packages", "attestations", "artifact-metadata"]) {
+    rejectPermissionMutation((fixture) => { fixture.permissions[permission] = "write"; }, /non-read-only workflow permission/);
+}
+rejectPermissionMutation((fixture) => { delete fixture.permissions; }, /explicit workflow permission mapping/);
+rejectPermissionMutation((fixture) => { fixture.permissions = "write-all"; }, /explicit workflow permission mapping/);
+rejectPermissionMutation((fixture) => { fixture.jobs.extra = { permissions: { contents: "read" } }; }, /explicit permission review/);
+for (const [job, permissions] of Object.entries(PUBLICATION_PERMISSIONS)) {
+    rejectPermissionMutation((fixture) => { delete fixture.jobs[job].permissions; }, /permissions must match/);
+    rejectPermissionMutation((fixture) => { fixture.jobs[job].permissions = "write-all"; }, /broad scalar permissions/);
+    for (const permission of Object.keys(permissions)) {
+        rejectPermissionMutation((fixture) => { delete fixture.jobs[job].permissions[permission]; }, /permissions must match/);
+    }
+    for (const permission of ["actions", "contents", "id-token", "packages", "attestations", "artifact-metadata"]) {
+        if (permissions[permission] === "write") continue;
+        rejectPermissionMutation((fixture) => { fixture.jobs[job].permissions[permission] = "write"; }, /permissions must match/);
+    }
+}
 
 const maliciousFixtures = [
-    "name: bad\non: push\npermissions: write-all\njobs: {}\n",
-    "name: bad\non: pull_request_target\njobs: {}\n",
-    "name: bad\non: push\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: >-\n          actions/checkout@v7\n",
-    "name: bad\non: push\njobs:\n  call:\n    uses: 'owner/repo/.github/workflows/reuse.yml@main'\n",
-    `name: bad\non: push\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: evil/action@${"a".repeat(40)}\n`,
+    ["name: bad\non: push\npermissions: write-all\njobs: {}\n", /explicit workflow permission mapping/],
+    ["name: bad\non: pull_request_target\npermissions: {contents: read}\njobs: {}\n", /uses pull_request_target/],
+    ["name: bad\non: push\npermissions: {contents: read}\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: >-\n          actions/checkout@v7\n", /not pinned to a full commit/],
+    ["name: bad\non: push\npermissions: {contents: read}\njobs:\n  call:\n    uses: 'owner/repo/.github/workflows/reuse.yml@main'\n", /not pinned to a full commit/],
+    [`name: bad\non: push\npermissions: {contents: read}\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: evil/action@${"a".repeat(40)}\n`, /not on the maintained allowlist/],
 ];
-for (const [index, fixture] of maliciousFixtures.entries()) {
-    assert.throws(() => validateWorkflow(`malicious-${index}.yml`, parse(fixture)), undefined, `malicious workflow fixture ${index} was accepted`);
+for (const [index, [fixture, expected]] of maliciousFixtures.entries()) {
+    assert.throws(() => validateWorkflow(`malicious-${index}.yml`, parse(fixture)), expected, `malicious workflow fixture ${index} was accepted`);
 }
 
+for (const { name, workflow } of sources) validateWorkflow(name, workflow);
+validatePublicationPermissions(publish);
+
 const security = sources.find(({ name }) => name === "security.yml")?.text ?? "";
 assert.match(security, /github\/codeql-action\/init@[a-f0-9]{40}/);
 assert.match(security, /actions\/dependency-review-action@[a-f0-9]{40}/);
 assert.match(security, /queries:\s*security-extended/);
 const scorecard = sources.find(({ name }) => name === "scorecard.yml")?.text ?? "";
+assert.ok(Object.hasOwn(parse(scorecard).on, "workflow_dispatch"), "Scorecard must support manual recovery without a source push");
 assert.match(scorecard, /ossf\/scorecard-action@[a-f0-9]{40}/);
 assert.match(scorecard, /publish_results:\s*true/);
 
@@ -76,4 +137,4 @@ const rootPackage = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))
 assert.match(rootPackage.scripts["audit:runtime"] ?? "", /npm audit --omit=dev/);
 assert.match(rootPackage.scripts["check:public"] ?? "", /security:baseline/);
 
-console.log(`PASS: ${workflowFiles.length} workflows and ${maliciousFixtures.length} adversarial fixtures enforce parsed YAML, allowlisted full-SHA actions, bounded triggers, and required security controls`);
+console.log(`PASS: ${workflowFiles.length} workflows, ${maliciousFixtures.length} action/trigger fixtures and ${permissionFixtures} permission mutations enforce parsed YAML, full-SHA actions, read-only defaults and job-scoped publication authority`);