@bli-cockpit/cli 0.2.28 → 0.2.30

package/README.md

@@ -13,9 +13,9 @@ added <packages> in <seconds>s
 
 ```bash
 $ cockpit do-everything
-Cockpit harvest onboarding
+Setting up Cockpit
 Dashboard: https://bli-cockpit-dashboard.vercel.app
-Ticket: general ambient
+Ticket: none (general work)
 What's your @buildlaunchiterate.ca email? (press enter to skip): ian@buildlaunchiterate.ca
 Signing in as ian@buildlaunchiterate.ca.
 Code sent; valid 1h, resend in 60s by rerunning this command.
@@ -28,7 +28,7 @@ What you can do:
 Code: 482913
 Signed in as ian@buildlaunchiterate.ca.
 2/5 Device paired.
-PASS: Cockpit collector is ready for harvest.
+PASS: Cockpit is set up and collecting.
 You're live.
 Dashboard: https://bli-cockpit-dashboard.vercel.app/my-work
 Next: cockpit status
@@ -36,9 +36,15 @@ Next: cockpit status
 
 ```bash
 $ cockpit status
-Install: ready
-Auth: paired
-Upload state: ready
+Cockpit status
+Installed: yes
+Signed in: yes
+Ticket: none (general work)
+Last collected: recently
+Uploads: ready
+Waiting to upload: 0
+Old sessions: done
+Stuck files: none
 ```
 
 The OTP proves you own an approved BLI mailbox. The JWT is used once to register this device and is never saved; the durable local credential remains the existing Cockpit device token.
@@ -47,13 +53,14 @@ The OTP proves you own an approved BLI mailbox. The JWT is used once to register
 
 On a blank Mac or Windows PC, `npm i -g @bli-cockpit/cli && cockpit do-everything` is enough to sign in, choose roots, and converge the machine. `onboard` remains the named setup subset, and the rest exist for recovery and maintenance.
 
-The core collection contract is the same on Apple Silicon macOS and native
-Windows: every eligible Codex and Claude session attributable to an approved
-root is collected, redacted before ingest, and either uploaded with a durable
-receipt or surfaced with an explicit ambiguity, skip, or retry reason. A green
-machine must not hide silently missing sessions. This support claim remains
-release-gated: the packed candidate must pass normal-user canaries on both host
-families before its exact version is promoted to npm `latest`.
+Cockpit works the same way on an Apple Silicon Mac and on a normal Windows
+PC. Every Codex and Claude session in a folder you have approved is collected,
+stripped of anything sensitive before it leaves your machine, and then either
+uploaded with a receipt or listed with the exact reason it was not. If a
+session is missing, Cockpit says so — a green screen never hides one.
+
+We only publish a version to npm after it has been tested end-to-end, as a
+normal user, on both macOS and Windows.
 
 | Command | What it does | Why it exists / why this name |
 |---|---|---|
@@ -171,11 +178,11 @@ Local files:
 
 - `~/.config/bli-cockpit/config.json`: dashboard URL, device label, collection roots.
 - `~/.config/bli-cockpit/session.json`: paired device token and owner metadata.
-- `~/.local/state/bli-cockpit/spool/`: safe retry records.
+- `~/.local/state/bli-cockpit/spool/`: uploads waiting to be retried.
 - `~/.local/state/bli-cockpit/spool/install-events/`: private atomic collector
   health receipts waiting for authenticated delivery. Receipts contain only
   sanitized operation metadata, never command output or transcript content.
-- `~/.local/state/bli-cockpit/cursors/`: upload/backfill cursors, no raw content.
+- `~/.local/state/bli-cockpit/cursors/`: bookmarks for how far uploading has got, no raw content.
 - `.codex-autorunner/contextspace/active_context.md`: current work context inside a repo.
 
 Remote data:

package/dist/adapters/local-sources.js

@@ -36,6 +36,7 @@ export async function runLocalSourceCollectors(options) {
             byteBudget: options.rawEvidenceByteBudget,
             objectBudget: options.rawEvidenceObjectBudget,
             budget: options.rawEvidenceBudget,
+            deliveryMode: options.rawEvidenceDeliveryMode,
         })
         : {
             scan: makeUnavailableScan(context, "codex_jsonl", "codex-jsonl", "raw_evidence_state_dir_not_configured"),

package/dist/adapters/raw-evidence-completeness.js

@@ -0,0 +1,226 @@
+import { EvidenceCompletenessPayloadSchema } from "@bli-cockpit/telemetry-core";
+// ---------------------------------------------------------------------------
+// Writing to the ledger
+// ---------------------------------------------------------------------------
+export function recordScanned(ledger, source, count = 1) {
+    ledger.scanned.set(source, (ledger.scanned.get(source) ?? 0) + count);
+}
+export function recordSkipCount(ledger, source, reason, count) {
+    if (count <= 0)
+        return;
+    ledger.skipped.push({ kind: source, label: reason, reason, count });
+}
+export function recordTruncationCount(ledger, source, reason, count, details = {}) {
+    if (count <= 0)
+        return;
+    ledger.truncated.push({ kind: source, reason, count, ...details });
+}
+export function markCapApplied(ledger, source, capType) {
+    const cap = ledger.caps.find((candidate) => candidate.source === source && candidate.cap_type === capType);
+    if (cap)
+        cap.applied = true;
+}
+export function markBudgetCapApplied(ledger, reason) {
+    markCapApplied(ledger, "raw_evidence", reason === "deferred_object_budget" ? "object_budget" : "byte_budget");
+}
+// ---------------------------------------------------------------------------
+// Counting
+// ---------------------------------------------------------------------------
+/** A record with no explicit `count` stands for exactly one file. */
+export function evidenceEntryCount(entry) {
+    return entry.count ?? 1;
+}
+export function countEvidenceEntries(entries, predicate = () => true) {
+    return entries.reduce((sum, entry) => sum + (predicate(entry) ? evidenceEntryCount(entry) : 0), 0);
+}
+export function makeEvidenceCompleteness(ledger, options) {
+    const sourceCounts = listSourceNames(ledger).map((source) => summarizeSource(ledger, source));
+    const totals = sumSourceTotals(sourceCounts);
+    const hasGaps = hasAnyGap(ledger, totals);
+    return EvidenceCompletenessPayloadSchema.parse({
+        schema_version: "evidence-completeness.v1",
+        status: decideCompletenessStatus(totals, hasGaps),
+        generated_at: options.finishedAt,
+        scan_window: {
+            started_at: options.startedAt,
+            finished_at: options.finishedAt,
+            since_minutes: options.sinceMinutes,
+        },
+        source_counts: sourceCounts,
+        totals,
+        caps: ledger.caps,
+        skip_reasons: sortedBySourceAndReason(tallyByReason(ledger.skipped)),
+        failure_reasons: sortedBySourceAndReason(tallyByReason(ledger.failed)),
+        truncation_markers: sortedBySourceAndReason(tallyTruncationMarkers(ledger)),
+        redaction_markers: tallyRedactionMarkers(ledger).sort((a, b) => `${a.source}:${a.mode}`.localeCompare(`${b.source}:${b.mode}`)),
+        notes: completenessNotes(ledger, totals, hasGaps),
+    });
+}
+/** Every source that either offered a candidate or produced a record. */
+function listSourceNames(ledger) {
+    const sources = new Set(ledger.scanned.keys());
+    for (const entry of ledger.entries)
+        sources.add(entry.kind);
+    for (const entry of ledger.skipped)
+        sources.add(entry.kind);
+    for (const entry of ledger.reused)
+        sources.add(entry.kind);
+    for (const entry of ledger.truncated)
+        sources.add(entry.kind);
+    for (const entry of ledger.failed)
+        sources.add(entry.kind);
+    for (const entry of ledger.redacted)
+        sources.add(entry.kind);
+    return [...sources].sort();
+}
+function summarizeSource(ledger, source) {
+    const skipped = ledger.skipped.filter((entry) => entry.kind === source);
+    return {
+        source,
+        scanned_count: ledger.scanned.get(source) ?? 0,
+        included_count: ledger.entries.filter((entry) => entry.kind === source)
+            .length,
+        skipped_count: countEvidenceEntries(skipped),
+        truncated_count: countEvidenceEntries(ledger.truncated, (entry) => entry.kind === source),
+        deferred_count: countEvidenceEntries(skipped, (entry) => entry.reason.startsWith("deferred_")),
+        reused_count: ledger.reused.filter((entry) => entry.kind === source).length,
+        failed_count: countEvidenceEntries(ledger.failed, (entry) => entry.kind === source),
+    };
+}
+function sumSourceTotals(sourceCounts) {
+    return sourceCounts.reduce((sum, count) => ({
+        scanned_count: sum.scanned_count + count.scanned_count,
+        included_count: sum.included_count + count.included_count,
+        skipped_count: sum.skipped_count + count.skipped_count,
+        truncated_count: sum.truncated_count + count.truncated_count,
+        deferred_count: sum.deferred_count + count.deferred_count,
+        reused_count: sum.reused_count + count.reused_count,
+        failed_count: sum.failed_count + count.failed_count,
+    }), {
+        scanned_count: 0,
+        included_count: 0,
+        skipped_count: 0,
+        truncated_count: 0,
+        deferred_count: 0,
+        reused_count: 0,
+        failed_count: 0,
+    });
+}
+/** Collapse records to one row per (source, reason), summing their counts. */
+function tallyByReason(records) {
+    const counts = new Map();
+    for (const record of records) {
+        const key = `${record.kind}:${record.reason}`;
+        const existing = counts.get(key);
+        if (existing) {
+            existing.count += evidenceEntryCount(record);
+            continue;
+        }
+        counts.set(key, {
+            source: record.kind,
+            reason: record.reason,
+            count: evidenceEntryCount(record),
+        });
+    }
+    return [...counts.values()];
+}
+/**
+ * Truncations of the same source and reason merge, keeping the WORST numbers
+ * seen: the largest observed size and the largest amount actually included.
+ */
+function tallyTruncationMarkers(ledger) {
+    const counts = new Map();
+    for (const truncated of ledger.truncated) {
+        const key = `${truncated.kind}:${truncated.reason}`;
+        const existing = counts.get(key);
+        if (existing) {
+            existing.count += evidenceEntryCount(truncated);
+            existing.observed_bytes = Math.max(existing.observed_bytes ?? 0, truncated.observed_bytes ?? 0);
+            existing.included_bytes = Math.max(existing.included_bytes ?? 0, truncated.included_bytes ?? 0);
+            continue;
+        }
+        counts.set(key, {
+            source: truncated.kind,
+            reason: truncated.reason,
+            count: evidenceEntryCount(truncated),
+            ...(truncated.max_bytes !== undefined
+                ? { max_bytes: truncated.max_bytes }
+                : {}),
+            ...(truncated.observed_bytes !== undefined
+                ? { observed_bytes: truncated.observed_bytes }
+                : {}),
+            ...(truncated.included_bytes !== undefined
+                ? { included_bytes: truncated.included_bytes }
+                : {}),
+        });
+    }
+    return [...counts.values()];
+}
+/** Grouped by source, masking mode, and the exact set of rules that fired. */
+function tallyRedactionMarkers(ledger) {
+    const counts = new Map();
+    for (const redacted of ledger.redacted) {
+        const ruleIds = redacted.redaction.rule_counts.map((rule) => rule.rule_id);
+        const key = `${redacted.kind}:${redacted.completenessLabel}:${ruleIds.sort().join(",")}`;
+        const existing = counts.get(key);
+        if (existing) {
+            existing.count += 1;
+            existing.rule_ids = [
+                ...new Set([...existing.rule_ids, ...ruleIds]),
+            ].sort();
+            continue;
+        }
+        counts.set(key, {
+            source: redacted.kind,
+            status: "sanitized",
+            mode: redacted.completenessLabel,
+            count: 1,
+            rule_ids: [...new Set(ruleIds)].sort(),
+        });
+    }
+    return [...counts.values()];
+}
+function sortedBySourceAndReason(markers) {
+    return markers.sort((a, b) => `${a.source}:${a.reason}`.localeCompare(`${b.source}:${b.reason}`));
+}
+/** Anything at all that keeps this pass from being raw-complete. */
+function hasAnyGap(ledger, totals) {
+    return (totals.skipped_count > 0 ||
+        totals.truncated_count > 0 ||
+        totals.deferred_count > 0 ||
+        totals.failed_count > 0 ||
+        ledger.redacted.length > 0 ||
+        ledger.caps.some((cap) => cap.applied));
+}
+/**
+ * | condition                                  | status     |
+ * | ------------------------------------------ | ---------- |
+ * | a failure and nothing landed at all        | `failed`   |
+ * | nothing landed and nothing was missing     | `empty`    |
+ * | anything was skipped, cut, deferred, masked| `partial`  |
+ * | otherwise                                  | `complete` |
+ */
+function decideCompletenessStatus(totals, hasGaps) {
+    const landed = totals.included_count + totals.reused_count;
+    if (totals.failed_count > 0 && landed === 0)
+        return "failed";
+    if (landed === 0 && !hasGaps)
+        return "empty";
+    return hasGaps ? "partial" : "complete";
+}
+function completenessNotes(ledger, totals, hasGaps) {
+    if (totals.failed_count > 0) {
+        return [
+            "Evidence collection failed; downstream analysis should not infer confidence.",
+        ];
+    }
+    if (ledger.redacted.length > 0) {
+        return [
+            "Evidence was sanitized before upload; downstream analysis should not treat it as raw-complete.",
+        ];
+    }
+    if (hasGaps) {
+        return ["Evidence is incomplete; downstream analysis should lower confidence."];
+    }
+    return [];
+}

package/dist/adapters/raw-evidence-git-diff.js

@@ -0,0 +1,90 @@
+/**
+ * Reading a working tree's diff without letting it read a secret or run away.
+ *
+ * Three protections, all of them caps that name themselves when they fire:
+ *
+ * - **the pathspec** never even asks git for `.env*`, `*secret*`, `*credential*`,
+ *   `*private-key*`, `*.pem` or `*.key`; those files are not read, not skipped.
+ * - **`MAX_GIT_DIFF_BYTES`** stops buffering at 2 MiB and kills the child once
+ *   more than that has been observed, so a giant rebase cannot exhaust memory.
+ * - **`GIT_DIFF_TIMEOUT_MS`** kills a diff that hangs.
+ *
+ * Either cap yields a *truncated* result rather than a failure: the bytes that
+ * were captured are real evidence, and the truncation reason travels with them.
+ */
+import { spawn } from "node:child_process";
+export const MAX_GIT_DIFF_BYTES = 2 * 1024 * 1024;
+export const GIT_DIFF_TIMEOUT_MS = 3_000;
+/** Paths Cockpit never reads, excluded at the git level rather than after. */
+const SECRET_EXCLUDING_PATHSPEC = [
+    ".",
+    ":(exclude).env",
+    ":(exclude).env.*",
+    ":(exclude)**/.env",
+    ":(exclude)**/.env.*",
+    ":(exclude)**/*secret*",
+    ":(exclude)**/*credential*",
+    ":(exclude)**/*private-key*",
+    ":(exclude)**/*.pem",
+    ":(exclude)**/*.key",
+];
+export async function runGitDiff(args, repoRoot) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", [...args, ...SECRET_EXCLUDING_PATHSPEC], {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let observedBytes = 0;
+        let includedBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            truncated = true;
+            child.kill("SIGTERM");
+        }, GIT_DIFF_TIMEOUT_MS);
+        child.stdout.on("data", (chunk) => {
+            observedBytes += chunk.byteLength;
+            if (includedBytes < MAX_GIT_DIFF_BYTES) {
+                const next = chunk.subarray(0, MAX_GIT_DIFF_BYTES - includedBytes);
+                stdoutChunks.push(next);
+                includedBytes += next.byteLength;
+            }
+            if (observedBytes > MAX_GIT_DIFF_BYTES) {
+                truncated = true;
+                child.kill("SIGTERM");
+            }
+        });
+        // Only enough stderr to name a failure; never enough to hold content.
+        child.stderr.on("data", (chunk) => {
+            if (stderrChunks.reduce((sum, item) => sum + item.byteLength, 0) < 4096) {
+                stderrChunks.push(chunk.subarray(0, 4096));
+            }
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timeout);
+            // A cap that fired killed the child on purpose, so SIGTERM and a
+            // non-zero code are both success here, not failure.
+            if (code === 0 || truncated || signal === "SIGTERM") {
+                resolve({
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    truncated,
+                    observedBytes,
+                    truncationReason: timedOut
+                        ? "git_diff_timeout"
+                        : "max_git_diff_bytes",
+                    truncationCapType: timedOut ? "timeout_ms" : "max_bytes_per_diff",
+                });
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+            reject(new Error(stderr || `git diff failed with code ${code ?? signal}`));
+        });
+    });
+}

package/dist/adapters/raw-evidence-keys.js

@@ -0,0 +1,92 @@
+/**
+ * What a piece of raw evidence is called.
+ *
+ * Two naming jobs live here and nothing else:
+ *
+ * 1. **Hashing** — `sha256` names bytes, `shortHash` names a string in twelve
+ *    hex characters. Content hashes are how a pack recognises bytes it has
+ *    already staged, so they must never depend on a clock or a path.
+ * 2. **Remote object keys** — the readable `operators/…/repos/…/sessions/…`
+ *    namespace an operator reads during an incident, followed by an immutable
+ *    content address (or a pack-relative manifest path).
+ *
+ * Everything here is pure: same input, same name, on every machine and every
+ * platform. Nothing in this file reads a file, spawns a process or logs.
+ */
+import { SECRET_FILE_SEGMENT_PATTERN } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import path from "node:path";
+export function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+export function shortHash(value) {
+    return crypto
+        .createHash("sha256")
+        .update(value, "utf8")
+        .digest("hex")
+        .slice(0, 12);
+}
+/**
+ * Object keys must satisfy the server's key pattern; ids derived from file
+ * content fall back to a hash rather than failing the whole upload batch.
+ */
+export function safeKeySegment(value) {
+    return /^[A-Za-z0-9._-]{1,80}$/.test(value) ? value : shortHash(value);
+}
+export function isSecretLikePath(value) {
+    return SECRET_FILE_SEGMENT_PATTERN.test(value);
+}
+/**
+ * Raw evidence keys start with human-readable context, then end in immutable
+ * content addresses or pack-relative manifest paths. The local cursor reuses
+ * prior content hashes across syncs; the readable date/session folders are for
+ * operator debugging and incident response.
+ */
+export function remoteObjectKey(options) {
+    const namespace = readableEvidenceNamespace(options.context);
+    if (options.contentAddress) {
+        return posixPath([...namespace, options.contentAddress]);
+    }
+    return posixPath([...namespace, options.packId, options.relativePath]);
+}
+function readableEvidenceNamespace(context) {
+    return [
+        "operators",
+        operatorSlug(context),
+        "repos",
+        readableKeySegment(context.repoLabel ?? path.basename(context.repoRoot), "repo"),
+        "worktrees",
+        readableKeySegment(context.worktreeLabel ?? path.basename(context.repoRoot), "worktree"),
+        "tickets",
+        readableKeySegment(context.activeTicketId ?? "unbound", "unbound", {
+            lowercase: false,
+        }),
+        "dates",
+        context.now.toISOString().slice(0, 10),
+        "sessions",
+        readableKeySegment(context.sessionId, "session"),
+        "ids",
+        safeKeySegment(context.operatorId),
+        safeKeySegment(context.workContextId),
+    ];
+}
+function operatorSlug(context) {
+    const labelBeforeDomain = (context.operatorLabel ?? context.operatorId)
+        .split("@", 1)[0]
+        .trim();
+    const readable = readableKeySegment(labelBeforeDomain, "operator");
+    return `${readable}-${shortHash(context.operatorId).slice(0, 6)}`;
+}
+function readableKeySegment(value, fallback, options = {}) {
+    const base = options.lowercase === false ? value : value.toLowerCase();
+    const slug = base
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-")
+        .slice(0, 80);
+    return slug || fallback;
+}
+function posixPath(parts) {
+    return parts.join("/").replace(/\\/g, "/").replace(/\/+/g, "/");
+}

package/dist/adapters/raw-evidence-manifest.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { remoteObjectKey, sha256 } from "./raw-evidence-keys.js";
+export const RAW_EVIDENCE_BUCKET = "ambient-raw-evidence";
+export const RAW_EVIDENCE_RETENTION_MODE = "remote_durable";
+export function evidenceEntry(options) {
+    const digest = sha256(options.bytes);
+    const objectKey = remoteObjectKey({
+        context: options.context,
+        packId: options.packId,
+        relativePath: options.relativePath,
+        contentAddress: options.contentAddress,
+    });
+    return {
+        kind: options.kind,
+        local_path: options.localPath,
+        relative_path: options.relativePath,
+        object_key: objectKey,
+        content_hash_sha256: digest,
+        byte_size: options.bytes.byteLength,
+        media_type: options.mediaType,
+        redacted_summary: options.redactedSummary,
+        ...(options.redaction ? { redaction: options.redaction } : {}),
+        codex_session_id: options.codexSessionId ?? null,
+        staged_in_pack: options.stagedInPack !== false,
+        source_key: options.sourceKey ?? null,
+        ...(options.artifactMetadata
+            ? {
+                artifact_metadata: {
+                    ...options.artifactMetadata,
+                    raw_evidence_pointer_id: objectKey,
+                    storage_bucket: RAW_EVIDENCE_BUCKET,
+                    object_key: objectKey,
+                    content_hash_sha256: digest,
+                    byte_size: options.bytes.byteLength,
+                },
+            }
+            : {}),
+    };
+}
+export function pointerFromEntry(entry) {
+    return {
+        raw_evidence_pointer_id: entry.object_key,
+        privacy_classification: "remote_durable_raw_evidence",
+        retention_policy: {
+            mode: RAW_EVIDENCE_RETENTION_MODE,
+            privacy_classification: "remote_durable_raw_evidence",
+        },
+        storage_scope: "remote_object",
+        storage_bucket: RAW_EVIDENCE_BUCKET,
+        object_key: entry.object_key,
+        content_hash_sha256: entry.content_hash_sha256,
+        byte_size: entry.byte_size,
+        media_type: entry.media_type,
+        redacted_summary: entry.redacted_summary,
+        ...(entry.redaction ? { redaction: entry.redaction } : {}),
+    };
+}
+export function makeManifest(options) {
+    return {
+        schema: "bli.local_raw_evidence_pack.v1",
+        pack_id: options.packId,
+        created_at: options.context.now.toISOString(),
+        work_context_id: options.context.workContextId,
+        session_id: options.context.sessionId,
+        operator_id: options.context.operatorId,
+        operator_label: options.context.operatorLabel,
+        repo_label: options.context.repoLabel ?? path.basename(options.context.repoRoot),
+        worktree_label: options.context.worktreeLabel,
+        active_ticket_id: options.context.activeTicketId ?? null,
+        repo_basename: path.basename(options.context.repoRoot),
+        branch: options.context.branch,
+        storage_bucket: RAW_EVIDENCE_BUCKET,
+        raw_policy: {
+            raw_prompts: "preserved_private_durable_remote",
+            raw_responses: "preserved_private_durable_remote",
+            transcripts: "preserved_private_durable_remote",
+            claude_transcripts: "preserved_private_durable_remote",
+            tool_payloads: "preserved_private_durable_remote",
+            git_diffs: "preserved_private_durable_remote_env_secret_paths_excluded",
+            agent_image_attachments: "preserved_private_durable_remote_explicit_agent_session_attachment_only",
+            env_files: "never_read",
+            stdout: "manifest_only_no_raw_content",
+        },
+        files: options.entries.map(redactManifestEntry),
+        skipped: options.skipped,
+        redacted: options.redacted,
+        reused: options.reused,
+    };
+}
+// `local_path` is redacted out, and so are the staging bookkeeping fields:
+// where a copy happens to live on this disk is not part of the pack's identity,
+// and putting it in the manifest would make byte-identical content produce
+// different manifests.
+function redactManifestEntry(entry) {
+    return {
+        kind: entry.kind,
+        relative_path: entry.relative_path,
+        object_key: entry.object_key,
+        content_hash_sha256: entry.content_hash_sha256,
+        byte_size: entry.byte_size,
+        media_type: entry.media_type,
+        redacted_summary: entry.redacted_summary,
+        ...(entry.redaction ? { redaction: entry.redaction } : {}),
+        ...(entry.artifact_metadata
+            ? { artifact_metadata: entry.artifact_metadata }
+            : {}),
+    };
+}
+/**
+ * Does a manifest already on disk describe exactly this set of files?
+ *
+ * Compared by sorted content hash, not by order or by name: the question is
+ * whether the reused pack's manifest is still true, and an unreadable or
+ * unparseable manifest answers no.
+ */
+export function manifestDescribesEntries(manifestBytes, entries) {
+    try {
+        const parsed = JSON.parse(manifestBytes.toString("utf8"));
+        const recorded = (parsed.files ?? [])
+            .map((file) => typeof file.content_hash_sha256 === "string"
+            ? file.content_hash_sha256
+            : "")
+            .filter(Boolean)
+            .sort();
+        const expected = entries.map((entry) => entry.content_hash_sha256).sort();
+        return (recorded.length === expected.length &&
+            recorded.every((hash, index) => hash === expected[index]));
+    }
+    catch {
+        return false;
+    }
+}