@bli-cockpit/cli 0.2.27 → 0.2.29

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;
+    }
+}

package/dist/adapters/raw-evidence-pack-store.js

@@ -0,0 +1,136 @@
+/**
+ * Where the bytes live on this disk.
+ *
+ * Staging first, promotion second (BLI-3066). A pack's id is derived from the
+ * content in it, so it cannot be known until collection is done: bytes land in
+ * a private `.staging-<pid>-<rand>` directory, and only then does the directory
+ * become its content-keyed name. Identical content on the next sync resolves to
+ * the identical directory instead of a 560th copy.
+ *
+ * Everything written here is mode `0600` inside a `0700` directory, on every
+ * platform except Windows, where the chmod is a no-op.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { makeManifest, manifestDescribesEntries, } from "./raw-evidence-manifest.js";
+import { writeRawEvidenceStagingState, } from "../raw-evidence-staging.js";
+/**
+ * Turn the staging directory into the content-keyed pack directory.
+ *
+ * Three outcomes, all of them named:
+ * - the pack does not exist yet: rename staging into place (`new`);
+ * - it exists and holds every file this pass staged: adopt it and delete the
+ *   staging copy (`reused`) — nothing is copied twice;
+ * - it exists but is missing files: fill the gaps from staging
+ *   (`restaged_incomplete`), because a half-written pack must not be trusted.
+ *
+ * Never deletes an existing pack directory wholesale: another pack's entries
+ * can point into it through the staged-object index.
+ */
+export async function promoteStagedPack(options) {
+    const evidenceDir = path.join(options.rawEvidenceRoot, options.packId);
+    const priorPackCount = await countPriorPacks(options.rawEvidenceRoot, options.workContextId, options.packId);
+    const existing = await fs.stat(evidenceDir).catch(() => null);
+    if (!existing?.isDirectory()) {
+        try {
+            await fs.rename(options.stagingDir, evidenceDir);
+            return {
+                state: "new",
+                evidenceDir,
+                priorPackCount,
+                refilledFileCount: 0,
+            };
+        }
+        catch {
+            // A concurrent sync can win the race to the same content-keyed name.
+            // Losing it is fine: the winner staged the identical bytes.
+        }
+    }
+    const refilledFileCount = await refillMissingPackFiles(evidenceDir, options.entries);
+    await fs
+        .rm(options.stagingDir, { recursive: true, force: true })
+        .catch(() => undefined);
+    return {
+        state: refilledFileCount > 0 ? "restaged_incomplete" : "reused",
+        evidenceDir,
+        priorPackCount,
+        refilledFileCount,
+    };
+}
+/** A file already there at the right size is left alone; anything else is recopied. */
+async function refillMissingPackFiles(evidenceDir, entries) {
+    let refilledFileCount = 0;
+    await ensurePrivateDir(path.join(evidenceDir, "files"));
+    for (const entry of entries) {
+        if (!entry.staged_in_pack)
+            continue;
+        const target = path.join(evidenceDir, "files", path.basename(entry.local_path));
+        const info = await fs.stat(target).catch(() => null);
+        if (info?.isFile() && info.size === entry.byte_size)
+            continue;
+        await fs.copyFile(entry.local_path, target).catch(() => undefined);
+        await chmodPrivate(target, 0o600);
+        refilledFileCount += 1;
+    }
+    return refilledFileCount;
+}
+async function countPriorPacks(rawEvidenceRoot, workContextId, packId) {
+    const entries = await fs
+        .readdir(rawEvidenceRoot, { withFileTypes: true })
+        .catch(() => []);
+    return entries.filter((entry) => entry.isDirectory() &&
+        entry.name !== packId &&
+        entry.name.startsWith(`${workContextId}-`)).length;
+}
+/**
+ * Write the manifest, or keep the one already in a reused pack.
+ *
+ * Byte-stability matters here: the manifest's object key is the only key that
+ * embeds the pack id, so rewriting it with a fresh `created_at` every sync
+ * would push different bytes at the same content-addressed key forever. A
+ * reused pack whose manifest already describes exactly these files keeps it.
+ */
+export async function stageManifest(options) {
+    if (options.reusePack) {
+        const existing = await fs.readFile(options.manifestPath).catch(() => null);
+        if (existing && manifestDescribesEntries(existing, options.entries)) {
+            return existing;
+        }
+    }
+    const manifestBytes = Buffer.from(`${JSON.stringify(makeManifest({
+        context: options.context,
+        packId: options.packId,
+        entries: options.entries,
+        skipped: options.skipped,
+        redacted: options.redacted,
+        reused: options.reused,
+    }), null, 2)}\n`, "utf8");
+    await fs.writeFile(options.manifestPath, manifestBytes, { mode: 0o600 });
+    await chmodPrivate(options.manifestPath, 0o600);
+    return manifestBytes;
+}
+/**
+ * Record which content hashes are staged where, so the next sync can adopt the
+ * copy instead of writing it again. Losing this file costs reuse and attempt
+ * counts, not evidence, so it must never fail a collection — but it must never
+ * be silent either.
+ */
+export async function persistStagingState(stateDir, staging, nowIso) {
+    staging.updated_at = nowIso;
+    await writeRawEvidenceStagingState(stateDir, staging).catch((error) => {
+        console.error("[raw-evidence] staging state write failed", JSON.stringify({
+            reason: "staging_state_write_failed",
+            detail: error instanceof Error ? error.name : typeof error,
+            staged_count: Object.keys(staging.staged).length,
+        }));
+    });
+}
+export async function ensurePrivateDir(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmodPrivate(dir, 0o700);
+}
+export async function chmodPrivate(target, mode) {
+    if (process.platform === "win32")
+        return;
+    await fs.chmod(target, mode).catch(() => undefined);
+}