@cairnkeep/cli 2.15.4 → 2.17.0

package/docs/quickstart.md

@@ -7,18 +7,19 @@ the default store stays on this computer.
 ## Codex CLI
 
 Install Cairnkeep, then let guided setup initialize an empty project and write
-Codex's project-scoped MCP entry:
+Codex's project-scoped MCP entry. Select **Initialize a Git repository**,
+tick **Codex CLI** with Space, keep local memory, review the plan, and apply it:
 
 ```bash
 npm install --global @cairnkeep/cli
-cairn setup /path/to/project --git init --harness codex --memory local --yes
+cairn setup /path/to/project
 cd /path/to/project
 cairn doctor
 ./.ai/start-codex.sh
 ```
 
-Use `--git existing` instead when the target is already a Git work tree. On
-native Windows, launch with `.\.ai\start-codex.cmd`.
+The wizard recommends the existing repository mode when the target is already
+a Git work tree. On native Windows, launch with `.\.ai\start-codex.cmd`.
 
 Before the first session, review `.codex/config.toml` and accept Codex's project
 trust prompt. The generated entry runs `cairn memory-server` locally. Setup
@@ -53,6 +54,13 @@ cairn doctor
 Setup reports machine-level commands but never executes them. This keeps
 project scaffolding separate from harness-wide changes.
 
+For scripts, CI, or reproducible fleet setup, skip the selector and provide all
+choices explicitly:
+
+```bash
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+```
+
 ## First memory cycle
 
 In a harness with Cairnkeep commands, remember one durable fact and recall it:

package/docs/releasing.md

@@ -10,37 +10,45 @@ from a workstation.
    `npm --prefix mcp-memory-server test`.
 3. Merge only after every required CI check passes.
 4. Publish a GitHub Release whose tag is exactly `v<package.json version>`.
-5. The `Publish release` workflow checks out that immutable tag, repeats the
-   tests, and publishes `@cairnkeep/cli` with npm provenance.
-6. The workflow uses the exact locked `@cyclonedx/cyclonedx-npm` development
-   dependency to generate a reproducible CycloneDX 1.6 SBOM from
-   `package-lock.json`. Generation includes schema validation and runs before
-   npm publication, so an invalid document blocks both publication and
-   attachment. The workflow attaches that SBOM, the npm tarball, and SHA-256
-   checksums to the GitHub Release.
-7. The workflow publishes versioned `linux/amd64` and `linux/arm64`
-   memory-server and workspace images to GHCR. It also updates `latest` for a
-   stable release or `next` for a prerelease.
-8. Verify both image digests, SBOM attestations, provenance attestations, and an
+5. After every platform and runtime job passes, CI builds one release candidate
+   keyed by the exact Git tree. It contains the npm tarball, reproducible
+   CycloneDX 1.6 SBOM, checksums, and a tree/version manifest. CI retains it for
+   30 days.
+6. The `Publish release` workflow checks out the immutable tag, resolves its
+   tree, and accepts a candidate only from a successful `CI` run for that exact
+   tree. It verifies the manifest and checksums instead of rebuilding or
+   repeating the complete test suite.
+7. After candidate verification, npm publication and the memory-server and
+   workspace container publications run in parallel. npm retains provenance;
+   the containers retain their per-image SBOM and provenance attestations.
+8. The workflow attaches the verified SBOM, npm tarball, and SHA-256 checksums
+   to the GitHub Release. It publishes versioned `linux/amd64` and
+   `linux/arm64` images to GHCR and updates `latest` for a stable release or
+   `next` for a prerelease.
+9. Verify both image digests, SBOM attestations, provenance attestations, and an
    anonymous pull before announcing the release.
 
 Stable versions must use a stable GitHub Release and publish to npm's `latest`
 tag. SemVer prerelease versions must use a GitHub prerelease and publish to
 `next`. A mismatch fails before publication.
 
-The workflow is safe to rerun: it skips `npm publish` and each versioned OCI
-image when that exact version is already present. It regenerates release
-artifacts, retries attestations against the resolved image digests, and moves
+The workflow is safe to rerun: it re-verifies the same CI candidate, skips
+`npm publish` and each versioned OCI image when that exact version is already
+present, retries attestations against the resolved image digests, and moves
 only the `latest` or `next` channel tag. A versioned image tag is never rebuilt
-or moved.
+or moved. If the tree-addressed candidate has expired, rerun CI for the exact
+release commit before retrying publication; the workflow never substitutes a
+different version or tree.
 
 ## Repository configuration
 
 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 `contents: write`,
-`packages: write`, `attestations: write`, and `id-token: write`; the last two
-are required for registry-backed build provenance.
+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.
 
 GitHub creates each new GHCR package as private. After the first container
 release, a package administrator must change both `cairnkeep` and

package/docs/storage.md

@@ -576,3 +576,24 @@ link index is derived data under `cache/graphs/<pack-digest>.json`; corruption
 or deletion does not affect identity and causes a rebuild from the object. OKF
 exports are not stored automatically: `export-okf --apply` creates a new
 operator-selected directory only after its preview digest is confirmed.
+
+## Context-intelligence derived and review state
+
+Progressive context-pack abstracts and overviews live below
+`${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/cache/context/<pack-digest>/` as
+digest-named JSON. This cache is derived, permission-restricted, outside
+immutable pack objects, and safe to discard or deterministically rebuild.
+Validation rejects symlinks, invalid names, oversized records, digest mismatches,
+and temporary remnants. Repair removes invalid derived entries only; it never
+changes a project pointer or skill approval.
+
+Review-gated memory proposals live under
+`<project>/.agentfs/memory-proposals/<proposal-digest>.json`. The directory is mode
+`0700` and files are mode `0600` on POSIX. Proposals are immutable and include
+the source trajectory digest and base reviewed-memory hashes used to reject stale
+application. Applying a proposal writes through the existing reviewed-memory
+store; it does not turn the proposal directory into a second memory authority.
+
+Context-usage receipts are strict links in the existing work-evidence store.
+They inherit work-evidence inspection, retention, and doctor behavior; there is
+no separate prompt or retrieved-content log.

package/docs/work-evidence.md

@@ -52,6 +52,20 @@ bodies are not included. The patch is redacted, bounded by the lower of the
 work-evidence and artifact limits, and stored in the existing artifact store.
 Cairnkeep provides no patch apply, restore or replay command.
 
+## Context-usage receipts
+
+With context packs enabled, `context_pack_search` can return stable references
+when called with `include_refs: true`. With `CAIRN_WORK_EVIDENCE=1` active, set
+`CAIRN_CONTEXT_USAGE=1` as the second gate to expose the
+local-only `context_usage_record` mutation. It links `task_digest`,
+`result_digest`, and an outcome (`used`, `unused`, or `unknown`) to the active
+work-evidence record, or to an explicit `evidence_id`.
+
+Receipts intentionally exclude the query, prompt, retrieved text, and model
+response. Their ID is deterministic, repeat recording is idempotent, conflicting
+outcomes fail, and the normal work-evidence doctor and retention rules apply.
+Because recording changes evidence, the read-only MCP profile excludes the tool.
+
 ## Inspect and maintain
 
 ```sh

package/examples/eval/bundled-fake.json

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

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

@@ -21,6 +21,7 @@ function usage() {
   cairn pack skills [--project PATH | --project-id ID] [--json]
   cairn pack approve-skill SELECTOR PATH --confirm FILE_DIGEST [--project PATH | --project-id ID]
   cairn pack revoke-skill SELECTOR PATH [--project PATH | --project-id ID]
+  cairn pack doctor [--repair] [--json]
 `);
     process.exit(2);
 }
@@ -205,9 +206,10 @@ async function main() {
         return;
     }
     if (command === "doctor") {
+        const repair = flag(args, "--repair");
         if (args.length)
             usage();
-        const result = await doctorContextPacks();
+        const result = await doctorContextPacks({ repair });
         output(result, json, result.ok ? `Context packs healthy (${result.objects} objects, ${result.projects} projects).` : `Context pack problems: ${[...result.issues, ...result.temporary_remnants].join("; ")}`);
         if (!result.ok)
             process.exitCode = 1;

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

@@ -0,0 +1,413 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+function isDirectory(node) {
+    return "type" in node && node.type === "directory";
+}
+const CACHE_SCHEMA_VERSION = 1;
+const DERIVATION_ALGORITHM = "deterministic-progressive-v1";
+const ABSTRACT_MAX_BYTES = 512;
+const OVERVIEW_MAX_BYTES = 2048;
+const MAX_TRACE_EVENTS = 64;
+const MAX_SELECTED_FILES = 32;
+const MAX_SELECTED_DIRECTORIES = 12;
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function compact(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function boundedUtf8(value, maximum) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length <= maximum)
+        return value;
+    const suffix = Buffer.from("…", "utf8");
+    if (suffix.length > maximum)
+        return "";
+    let end = maximum - suffix.length;
+    while (end > 0) {
+        try {
+            return `${new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, end)).trimEnd()}…`;
+        }
+        catch {
+            end -= 1;
+        }
+    }
+    return "";
+}
+function fileAbstract(file) {
+    const metadata = [file.title, file.description, file.keywords.join(", ")].map(compact).filter(Boolean);
+    return boundedUtf8(metadata.join(" — "), ABSTRACT_MAX_BYTES);
+}
+function fileOverview(file, abstract) {
+    const headings = [...file.text.matchAll(/^#{1,6}\s+(.+)$/gm)].map((match) => compact(match[1])).filter(Boolean);
+    const paragraphs = file.text
+        .split(/\n\s*\n/g)
+        .map((paragraph) => compact(paragraph.replace(/^#{1,6}\s+/, "")))
+        .filter(Boolean)
+        .slice(0, 4);
+    const pieces = [abstract, headings.length ? `Sections: ${headings.join("; ")}` : "", ...paragraphs].filter(Boolean);
+    return boundedUtf8([...new Set(pieces)].join("\n"), OVERVIEW_MAX_BYTES);
+}
+function visibleSetDigest(files) {
+    return sha256([
+        DERIVATION_ALGORITHM,
+        ...files.map(({ path, file_digest }) => `${path}\0${file_digest}`).sort((left, right) => left.localeCompare(right, "en")),
+    ].join("\n"));
+}
+function validCache(value, packDigest, setDigest, files) {
+    if (!value || typeof value !== "object")
+        return false;
+    const row = value;
+    if (row.schema_version !== CACHE_SCHEMA_VERSION || row.algorithm !== DERIVATION_ALGORITHM || row.pack_digest !== packDigest || row.visible_set_digest !== setDigest || !Array.isArray(row.files))
+        return false;
+    const expected = new Map(files.map((file) => [file.path, file.file_digest]));
+    return row.files.length === files.length && row.files.every((file) => file && typeof file.path === "string" && expected.get(file.path) === file.file_digest
+        && typeof file.abstract === "string" && Buffer.byteLength(file.abstract) <= ABSTRACT_MAX_BYTES
+        && typeof file.overview === "string" && Buffer.byteLength(file.overview) <= OVERVIEW_MAX_BYTES);
+}
+async function writeCache(path, record) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        try {
+            await rename(temporary, path);
+        }
+        catch (error) {
+            // Concurrent deterministic builders may publish the same record.
+            try {
+                await readFile(path);
+            }
+            catch {
+                throw error;
+            }
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function enrichPackFiles(files, cacheBaseDirectory) {
+    const packDigest = files[0].pack_digest;
+    const setDigest = visibleSetDigest(files);
+    const cachePath = join(cacheBaseDirectory, packDigest, `${setDigest}.json`);
+    let cached;
+    try {
+        const parsed = JSON.parse(await readFile(cachePath, "utf8"));
+        if (validCache(parsed, packDigest, setDigest, files))
+            cached = parsed;
+    }
+    catch {
+        // Missing or corrupt derived data is rebuilt deterministically.
+    }
+    if (!cached) {
+        cached = {
+            schema_version: CACHE_SCHEMA_VERSION,
+            algorithm: DERIVATION_ALGORITHM,
+            pack_digest: packDigest,
+            visible_set_digest: setDigest,
+            files: files.map((file) => {
+                const abstract = fileAbstract(file);
+                return { path: file.path, file_digest: file.file_digest, abstract, overview: fileOverview(file, abstract) };
+            }),
+        };
+        await writeCache(cachePath, cached);
+    }
+    const summaries = new Map(cached.files.map((file) => [file.path, file]));
+    return files.map((file) => ({ ...file, ...summaries.get(file.path) }));
+}
+function buildTree(pack, files) {
+    const root = { type: "directory", path: "", title: pack.title, abstract: "", overview: "", children: [] };
+    for (const file of files) {
+        const segments = file.path.split("/");
+        let current = root;
+        for (let index = 0; index < segments.length - 1; index += 1) {
+            const path = segments.slice(0, index + 1).join("/");
+            let child = current.children.find((candidate) => isDirectory(candidate) && candidate.path === path);
+            if (!child) {
+                child = { type: "directory", path, title: segments[index], abstract: "", overview: "", children: [] };
+                current.children.push(child);
+            }
+            current = child;
+        }
+        current.children.push(file);
+    }
+    const summarize = (directory) => {
+        for (const child of directory.children)
+            if (isDirectory(child))
+                summarize(child);
+        directory.children.sort((left, right) => {
+            const leftDirectory = isDirectory(left);
+            const rightDirectory = isDirectory(right);
+            if (leftDirectory !== rightDirectory)
+                return leftDirectory ? -1 : 1;
+            const leftPath = leftDirectory ? left.path : left.path;
+            const rightPath = rightDirectory ? right.path : right.path;
+            return leftPath.localeCompare(rightPath, "en");
+        });
+        const childAbstracts = directory.children.map((child) => child.abstract);
+        directory.abstract = boundedUtf8(`${directory.title}: ${childAbstracts.join(" | ")}`, ABSTRACT_MAX_BYTES);
+        directory.overview = boundedUtf8([directory.abstract, ...directory.children.map((child) => child.overview)].join("\n"), OVERVIEW_MAX_BYTES);
+    };
+    summarize(root);
+    root.abstract = boundedUtf8(`${pack.title}: ${pack.description} — ${root.abstract}`, ABSTRACT_MAX_BYTES);
+    root.overview = boundedUtf8(`${root.abstract}\n${root.overview}`, OVERVIEW_MAX_BYTES);
+    return root;
+}
+export async function loadProgressiveContext(files, cacheBaseDirectory) {
+    const grouped = new Map();
+    for (const file of files)
+        grouped.set(file.pack_digest, [...(grouped.get(file.pack_digest) ?? []), file]);
+    const packs = [];
+    for (const [packDigest, packFiles] of grouped) {
+        packFiles.sort((left, right) => left.path.localeCompare(right.path, "en"));
+        const enriched = await enrichPackFiles(packFiles, cacheBaseDirectory);
+        const first = packFiles[0];
+        const tree = buildTree({ title: first.pack_title, description: first.pack_description }, enriched);
+        packs.push({
+            pack_id: first.pack_id,
+            version: first.version,
+            pack_digest: packDigest,
+            title: first.pack_title,
+            abstract: tree.abstract,
+            overview: tree.overview,
+            files: enriched,
+            tree,
+        });
+    }
+    return packs.sort((left, right) => left.pack_digest.localeCompare(right.pack_digest, "en"));
+}
+function normalizedTokens(value) {
+    return [...new Set(value.toLocaleLowerCase("en").match(/[\p{L}\p{N}._/-]+/gu) ?? [])].slice(0, 24);
+}
+function matchScore(query, text) {
+    const normalizedText = text.toLocaleLowerCase("en");
+    let score = normalizedText.includes(query) ? 20 : 0;
+    for (const token of normalizedTokens(query))
+        if (token.length > 1 && normalizedText.includes(token))
+            score += 1;
+    return score;
+}
+export function selectHierarchicalFiles(query, packs) {
+    const normalized = query.trim().toLocaleLowerCase("en");
+    const allFiles = packs.flatMap((pack) => pack.files);
+    const exact = allFiles.filter((file) => file.path.toLocaleLowerCase("en") === normalized || file.title.toLocaleLowerCase("en") === normalized);
+    if (exact.length) {
+        return {
+            files: exact.slice(0, MAX_SELECTED_FILES),
+            exactLeafBypass: true,
+            events: exact.slice(0, MAX_TRACE_EVENTS).map((file) => ({ phase: "file", pack_digest: file.pack_digest, path: file.path, score: 100, reason: "exact-leaf-bypass" })),
+        };
+    }
+    const events = [];
+    const rankedPacks = packs.map((pack) => ({ pack, score: matchScore(normalized, `${pack.title}\n${pack.abstract}\n${pack.overview}`) }))
+        .sort((left, right) => right.score - left.score || left.pack.pack_digest.localeCompare(right.pack.pack_digest, "en"));
+    for (const { pack, score } of rankedPacks.slice(0, MAX_TRACE_EVENTS)) {
+        events.push({ phase: "pack", pack_digest: pack.pack_digest, score, reason: score ? "summary-match" : "summary-miss" });
+    }
+    const matchingPackDigests = new Set(rankedPacks.filter(({ score }) => score > 0).map(({ pack }) => pack.pack_digest));
+    const packCandidates = matchingPackDigests.size ? allFiles.filter((file) => matchingPackDigests.has(file.pack_digest)) : allFiles;
+    const directories = [];
+    const visit = (packDigest, node) => {
+        if (node.path)
+            directories.push({ pack_digest: packDigest, node, score: matchScore(normalized, `${node.path}\n${node.abstract}\n${node.overview}`) });
+        for (const child of node.children)
+            if (isDirectory(child))
+                visit(packDigest, child);
+    };
+    for (const pack of rankedPacks.map(({ pack }) => pack)) {
+        if (!matchingPackDigests.size || matchingPackDigests.has(pack.pack_digest))
+            visit(pack.pack_digest, pack.tree);
+    }
+    directories.sort((left, right) => right.score - left.score || left.pack_digest.localeCompare(right.pack_digest, "en") || left.node.path.localeCompare(right.node.path, "en"));
+    const selectedDirectories = directories.filter(({ score }) => score > 0).slice(0, MAX_SELECTED_DIRECTORIES);
+    for (const { pack_digest, node, score } of selectedDirectories) {
+        if (events.length >= MAX_TRACE_EVENTS)
+            break;
+        events.push({ phase: "directory", pack_digest, path: node.path, score, reason: "selected-summary-match" });
+    }
+    const directoryCandidates = selectedDirectories.length
+        ? packCandidates.filter((file) => selectedDirectories.some(({ pack_digest, node }) => file.pack_digest === pack_digest && (file.path === node.path || file.path.startsWith(`${node.path}/`))))
+        : packCandidates;
+    const ranked = directoryCandidates.map((file) => ({ file, score: matchScore(normalized, `${file.path}\n${file.abstract}\n${file.overview}`) }))
+        .sort((left, right) => right.score - left.score || left.file.pack_digest.localeCompare(right.file.pack_digest, "en") || left.file.path.localeCompare(right.file.path, "en"));
+    let selected = ranked.filter(({ score }) => score > 0).slice(0, MAX_SELECTED_FILES);
+    if (!selected.length) {
+        selected = ranked.slice(0, MAX_SELECTED_FILES);
+        events.push({ phase: "fallback", reason: "no-summary-match" });
+    }
+    for (const { file, score } of selected) {
+        if (events.length >= MAX_TRACE_EVENTS)
+            break;
+        events.push({ phase: "file", pack_digest: file.pack_digest, path: file.path, score, reason: score ? "selected-summary-match" : "selected-fallback" });
+    }
+    return { files: selected.map(({ file }) => file), exactLeafBypass: false, events: events.slice(0, MAX_TRACE_EVENTS) };
+}
+export function publicTree(pack, detail) {
+    const project = (node) => {
+        if (isDirectory(node)) {
+            return { type: "directory", path: node.path, title: node.title, [detail]: node[detail], children: node.children.map(project) };
+        }
+        return {
+            type: "file",
+            pack_id: node.pack_id,
+            version: node.version,
+            pack_digest: node.pack_digest,
+            path: node.path,
+            kind: node.kind,
+            file_digest: node.file_digest,
+            title: node.title,
+            [detail]: node[detail],
+        };
+    };
+    return {
+        pack_id: pack.pack_id,
+        version: pack.version,
+        pack_digest: pack.pack_digest,
+        title: pack.title,
+        [detail]: pack[detail],
+        tree: project(pack.tree),
+    };
+}
+const CACHE_DIGEST = /^[a-f0-9]{64}$/;
+const CACHE_RECORD_MAX_BYTES = 4 * 1024 * 1024;
+const CACHE_MAX_FILES = 1024;
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort((left, right) => left.localeCompare(right, "en"));
+    const wanted = [...expected].sort((left, right) => left.localeCompare(right, "en"));
+    return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+function safeCachedPath(value) {
+    return value.length > 0
+        && !value.includes("\\")
+        && !value.startsWith("/")
+        && !value.split("/").some((part) => part === "" || part === "." || part === "..");
+}
+function validateCacheRecord(value, directoryDigest, fileDigest, installedFiles) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "record is not an object";
+    const record = value;
+    if (!exactKeys(record, ["schema_version", "algorithm", "pack_digest", "visible_set_digest", "files"]))
+        return "record has unknown or missing fields";
+    if (record.schema_version !== 1 || record.algorithm !== DERIVATION_ALGORITHM || record.pack_digest !== directoryDigest || record.visible_set_digest !== fileDigest)
+        return "record identity or algorithm does not match its path";
+    if (!Array.isArray(record.files) || record.files.length > CACHE_MAX_FILES)
+        return "record files are invalid or oversized";
+    const seen = new Set();
+    const visibleFiles = [];
+    for (const value of record.files) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return "record contains a non-object file";
+        const file = value;
+        if (!exactKeys(file, ["path", "file_digest", "abstract", "overview"]))
+            return "record file has unknown or missing fields";
+        if (typeof file.path !== "string" || !safeCachedPath(file.path) || seen.has(file.path))
+            return "record contains an unsafe or duplicate path";
+        if (typeof file.file_digest !== "string" || !CACHE_DIGEST.test(file.file_digest))
+            return "record contains an invalid file digest";
+        const source = installedFiles.get(file.path);
+        if (!source || source.file_digest !== file.file_digest)
+            return "record is not bound to installed pack content";
+        if (typeof file.abstract !== "string" || Buffer.byteLength(file.abstract, "utf8") > ABSTRACT_MAX_BYTES)
+            return "record abstract is invalid or oversized";
+        if (typeof file.overview !== "string" || Buffer.byteLength(file.overview, "utf8") > OVERVIEW_MAX_BYTES)
+            return "record overview is invalid or oversized";
+        const expectedAbstract = fileAbstract(source);
+        if (file.abstract !== expectedAbstract || file.overview !== fileOverview(source, expectedAbstract))
+            return "record summaries do not match immutable pack content";
+        seen.add(file.path);
+        visibleFiles.push({ pack_digest: directoryDigest, path: file.path, file_digest: file.file_digest });
+    }
+    if (visibleSetDigest(visibleFiles) !== fileDigest)
+        return "record visibility digest does not match its file set";
+    return null;
+}
+/**
+ * Validate the mutable, derived progressive-context cache. Cached records are
+ * addressed by both immutable pack digest and the exact visible file set, so a
+ * revoked skill can never be loaded through a document-only cache key.
+ *
+ * Repair is intentionally limited to deleting invalid derived entries. The
+ * next hierarchical read deterministically rebuilds them from immutable pack
+ * objects and the current project pointer.
+ */
+export async function doctorProgressiveContextCache(cacheBaseDirectory, packs, options = {}) {
+    const issues = [];
+    const temporaryRemnants = [];
+    const repaired = [];
+    const installed = new Map(packs.map((pack) => [
+        pack.pack_digest,
+        new Map(pack.files.map((file) => [file.path, file])),
+    ]));
+    const removeDerived = async (path, label) => {
+        if (!options.repair)
+            return;
+        await rm(path, { recursive: true, force: true });
+        repaired.push(label);
+    };
+    let rootInfo;
+    try {
+        rootInfo = await lstat(cacheBaseDirectory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { ok: true, issues, temporary_remnants: temporaryRemnants, repaired };
+        }
+        issues.push(`Unable to inspect progressive context cache: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, issues, temporary_remnants: temporaryRemnants, repaired };
+    }
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+        issues.push("Progressive context cache root is not a regular directory.");
+        await removeDerived(cacheBaseDirectory, "cache/context");
+        if (options.repair)
+            issues.length = 0;
+        return { ok: issues.length === 0, issues, temporary_remnants: temporaryRemnants, repaired };
+    }
+    for (const packEntry of (await readdir(cacheBaseDirectory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+        const packPath = join(cacheBaseDirectory, packEntry.name);
+        const packInfo = await lstat(packPath);
+        if (packEntry.name.endsWith(".tmp")) {
+            temporaryRemnants.push(`cache/context/${packEntry.name}`);
+            await removeDerived(packPath, `cache/context/${packEntry.name}`);
+            continue;
+        }
+        const installedFiles = installed.get(packEntry.name);
+        if (!CACHE_DIGEST.test(packEntry.name) || !packInfo.isDirectory() || packInfo.isSymbolicLink() || !installedFiles) {
+            issues.push(`Invalid progressive context cache pack entry: ${packEntry.name}`);
+            await removeDerived(packPath, `cache/context/${packEntry.name}`);
+            continue;
+        }
+        for (const cacheEntry of (await readdir(packPath, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+            const cachePath = join(packPath, cacheEntry.name);
+            const relative = `cache/context/${packEntry.name}/${cacheEntry.name}`;
+            const cacheInfo = await lstat(cachePath);
+            if (cacheEntry.name.endsWith(".tmp")) {
+                temporaryRemnants.push(relative);
+                await removeDerived(cachePath, relative);
+                continue;
+            }
+            const match = /^([a-f0-9]{64})\.json$/.exec(cacheEntry.name);
+            if (!match || !cacheInfo.isFile() || cacheInfo.isSymbolicLink() || cacheInfo.size > CACHE_RECORD_MAX_BYTES) {
+                issues.push(`Invalid progressive context cache entry: ${relative}`);
+                await removeDerived(cachePath, relative);
+                continue;
+            }
+            try {
+                const value = JSON.parse(await readFile(cachePath, "utf8"));
+                const invalid = validateCacheRecord(value, packEntry.name, match[1], installedFiles);
+                if (invalid)
+                    throw new Error(invalid);
+            }
+            catch (error) {
+                issues.push(`Invalid progressive context cache record: ${relative}: ${error instanceof Error ? error.message : String(error)}`);
+                await removeDerived(cachePath, relative);
+            }
+        }
+    }
+    if (options.repair) {
+        issues.length = 0;
+        temporaryRemnants.length = 0;
+    }
+    return { ok: issues.length === 0 && temporaryRemnants.length === 0, issues, temporary_remnants: temporaryRemnants, repaired };
+}