@cairnkeep/cli 2.22.0 → 2.22.1

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [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,16 @@ 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.
+
 ## 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.1
 **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.1
 
 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.1
 
 ## 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.1
 
 ## 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.1
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.17.1 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.22.1 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.22.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.22.1 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.1
    cairn --version
    ```
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.22.0
+**Tested with:** Cairnkeep 2.22.1
 
 ## 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.1
 
 ## 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.1 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.1 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.1, 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.1
 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.1; 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.1 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.1 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.1 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.1 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.1 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.1 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.
@@ -69,8 +69,18 @@ npm --prefix mcp-memory-server run check:security-assurance
 npm --prefix mcp-memory-server run check:http-guard
 ```
 
-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.
 
 ## Common failures

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

@@ -56,6 +56,19 @@ 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.
+
+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,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 |
+| 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 +106,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.1","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.js

@@ -11,6 +11,7 @@ import { doctorProgressiveContextCache, loadProgressiveContext, publicTree, sele
 import { indexOkfBundle, validateOkfBundle, validatedOkfFileContent } from "./okf.js";
 import { atomicReplace, hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
 import { portablePathCollisionKey, portableRelativePathIssue } from "./path-security.js";
+import { acquireContextPackPointerLock } from "./context-pack-lock.js";
 const execFileAsync = promisify(execFile);
 export const CONTEXT_PACK_MANIFEST = "context-pack.json";
 export const CONTEXT_PACK_MAX_FILE_BYTES = 1024 * 1024;
@@ -611,36 +612,10 @@ export function readProjectPointer(options) {
         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));
-}
 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);

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-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.1",
     "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`);