@bli-cockpit/cli 0.2.48 → 0.2.50

package/dist/adapters/raw-evidence-attribution-gaps.js

@@ -0,0 +1,133 @@
+import { isLiveRawEvidenceSyncAttribution } from "../raw-evidence-attribution-policy.js";
+import { recordScanned, recordSkipCount, recordTruncationCount, } from "./raw-evidence-completeness.js";
+/**
+ * Record every Codex session the attribution scan saw, capped or lost, so the
+ * pass reports them as its own gaps.
+ */
+export function recordCodexAttributionCompleteness(ledger, scan, selectedPaths) {
+    recordScanned(ledger, "codex_attribution", scan.scanned_file_count);
+    ledger.caps.push(...codexAttributionCaps(scan));
+    recordSkipCount(ledger, "codex_attribution", "session_limit_overflow", Math.max(0, scan.discovered_file_count - scan.scanned_file_count));
+    recordSkipCount(ledger, "codex_attribution", "directory_read_failed", scan.directory_read_failed_count);
+    recordSkipCount(ledger, "codex_attribution", "file_stat_failed", scan.stat_failed_count);
+    recordSkipCount(ledger, "codex_attribution", "secret_like_directory", scan.secret_path_skipped_count);
+    recordAttributionResultSkips(ledger, "codex_attribution", scan.results, selectedPaths);
+}
+/** Every limit the Codex attribution scan ran under, and whether it bit. */
+function codexAttributionCaps(scan) {
+    return [
+        {
+            source: "codex_attribution",
+            cap_type: "scan_window_minutes",
+            limit: scan.since_minutes,
+            observed: scan.since_minutes,
+            applied: false,
+        },
+        {
+            source: "codex_attribution",
+            cap_type: "session_limit",
+            limit: scan.session_limit,
+            observed: scan.discovered_file_count,
+            applied: scan.session_limit_applied,
+        },
+    ];
+}
+/**
+ * Record every Claude session the attribution scan saw, capped or lost —
+ * sidecars included, because a subagent transcript nobody could read is missing
+ * evidence exactly like a main.
+ */
+export function recordClaudeAttributionCompleteness(ledger, scan, selectedPaths) {
+    recordScanned(ledger, "claude_attribution", scan.scanned_session_count);
+    if (scan.disabled_reason) {
+        recordSkipCount(ledger, "claude_attribution", scan.disabled_reason, 1);
+    }
+    ledger.caps.push(...claudeAttributionCaps(scan));
+    recordClaudeAttributionSkips(ledger, scan);
+    recordTruncationCount(ledger, "claude_attribution", "oversized_jsonl_line", scan.counts.oversized_lines_skipped, { max_bytes: scan.max_line_buffer_bytes });
+    recordAttributionResultSkips(ledger, "claude_attribution", scan.results, selectedPaths);
+    recordClaudeSidecarSkips(ledger, scan);
+}
+/** Every limit the Claude attribution scan ran under, and whether it bit. */
+function claudeAttributionCaps(scan) {
+    return [
+        {
+            source: "claude_attribution",
+            cap_type: "scan_window_minutes",
+            limit: scan.since_minutes,
+            observed: scan.since_minutes,
+            applied: false,
+        },
+        {
+            source: "claude_attribution",
+            cap_type: "session_limit",
+            limit: scan.session_limit,
+            observed: scan.discovered_session_count,
+            applied: scan.session_limit_applied,
+        },
+        {
+            source: "claude_attribution",
+            cap_type: "max_file_bytes",
+            limit: scan.max_file_bytes,
+            applied: scan.counts.mains_oversized > 0 ||
+                scan.results.some((result) => result.reason === "file_too_large"),
+        },
+        {
+            source: "claude_attribution",
+            cap_type: "max_sidecar_files",
+            limit: scan.max_sidecar_files,
+            observed: scan.max_sidecar_files + scan.counts.sidecars_capped,
+            applied: scan.counts.sidecars_capped > 0,
+        },
+        {
+            source: "claude_attribution",
+            cap_type: "max_line_buffer_bytes",
+            limit: scan.max_line_buffer_bytes,
+            applied: scan.counts.oversized_lines_skipped > 0,
+        },
+    ];
+}
+/** Each way the Claude scan lost whole sessions, one named skip count apiece. */
+function recordClaudeAttributionSkips(ledger, scan) {
+    recordSkipCount(ledger, "claude_attribution", "session_limit_overflow", Math.max(0, scan.discovered_session_count - scan.scanned_session_count));
+    recordSkipCount(ledger, "claude_attribution", "secret_like_project_dir", scan.project_dirs_skipped);
+    recordSkipCount(ledger, "claude_attribution", "project_dir_read_failed", scan.project_dir_read_failed_count);
+    recordSkipCount(ledger, "claude_attribution", "session_stat_failed", scan.session_stat_failed_count);
+    recordSkipCount(ledger, "claude_attribution", "sidecar_dir_read_failed", scan.sidecar_dir_read_failed_count);
+    recordSkipCount(ledger, "claude_attribution", "sidecar_stat_failed", scan.sidecar_stat_failed_count);
+    recordSkipCount(ledger, "claude_attribution", "sidecar_limit_overflow", scan.counts.sidecars_capped);
+}
+/** One skip per sidecar the scan declined, labelled with its own reason. */
+function recordClaudeSidecarSkips(ledger, scan) {
+    for (const result of scan.results) {
+        for (const sidecar of result.sidecar_files) {
+            if (!sidecar.skipped_reason)
+                continue;
+            recordSkipCount(ledger, "claude_attribution", `sidecar_${sidecar.skipped_reason}`, 1);
+        }
+    }
+}
+/** One skip per scanned session this pass is neither collecting nor excusing. */
+function recordAttributionResultSkips(ledger, source, results, selectedPaths) {
+    for (const result of results) {
+        if (isAttributionAccountedFor(result, selectedPaths))
+            continue;
+        const reason = result.state === "skipped"
+            ? result.reason
+            : `attribution_${result.state}:${result.reason}`;
+        recordSkipCount(ledger, source, reason, 1);
+    }
+}
+/**
+ * Not every unattributed result is a gap. A selected session is being collected
+ * by this pass, and a live-sync-safe synthetic target is owned by another
+ * workspace's pack — neither is missing evidence.
+ */
+function isAttributionAccountedFor(result, selectedPaths) {
+    if (result.state === "attributed")
+        return true;
+    if (selectedPaths.has(result.file_path))
+        return true;
+    return (result.worktree !== null &&
+        isLiveRawEvidenceSyncAttribution(result.state, result.reason, true));
+}

package/dist/adapters/raw-evidence-claude-reader.js

@@ -0,0 +1,108 @@
+/**
+ * Claude Code sessions: one main transcript, its subagent sidecars, and the
+ * images either of them attached.
+ *
+ * Sync always attributes first, so there is no directory-walk fallback here —
+ * the caller either names the sessions or Claude is not collected this pass.
+ *
+ * The main file has three named outcomes and the sidecars are independent of
+ * all of them: an oversized main (D7) is skipped for its bytes while its
+ * sidecars still collect, and a growth-damped main (D9) is not re-collected at
+ * all while the session still reports the durable copy it already has.
+ */
+import path from "node:path";
+import { isSecretLikePath, safeKeySegment } from "./raw-evidence-keys.js";
+import { recordScanned } from "./raw-evidence-completeness.js";
+import { CLAUDE_MAX_COLLECT_FILE_BYTES, } from "./raw-evidence-collection-state.js";
+import { collectOneEvidenceFile } from "./raw-evidence-transcript-file.js";
+import { collectAgentImagesFromTranscript } from "./raw-evidence-image-reader.js";
+export async function collectClaudeJsonlFiles(collection, sessions) {
+    recordScanned(collection, "claude_jsonl", sessions.reduce((count, session) => count + 1 + session.sidecar_files.length, 0));
+    for (const session of sessions) {
+        await collectOneClaudeSession(collection, session);
+    }
+}
+async function collectOneClaudeSession(collection, session) {
+    const sessionId = session.claude_session_id;
+    const mainOutcome = await collectClaudeMainFile(collection, session);
+    if (mainOutcome === "collected" || mainOutcome === "damped_reuse") {
+        await collectAgentImagesFromTranscript(collection, {
+            filePath: session.local_path,
+            source: "claude_code",
+            sessionId,
+            kind: "claude_image_attachment",
+            contentAddress: (hash16, extension) => `claude/${safeKeySegment(sessionId)}/images/${hash16}.${extension}`,
+        });
+    }
+    for (const sidecar of session.sidecar_files) {
+        await collectOneClaudeSidecar(collection, session, sidecar.local_path);
+    }
+}
+/**
+ * What happens to a Claude main file, as a decision table:
+ *
+ * | condition             | main bytes                | outcome             |
+ * | --------------------- | ------------------------- | ------------------- |
+ * | `main_file_oversized` | skipped `file_too_large`  | `skipped_too_large` |
+ * | `skip_main` (D9)      | not re-collected          | `damped_reuse`      |
+ * | otherwise             | collected, or named skip  | `collected` / `not_collected` |
+ *
+ * Its images are collected for every outcome except `skipped_too_large` and
+ * `not_collected` — the caller decides that, this function only reports.
+ *
+ * D7: an oversized main was attributed via a streamed read but its bytes are
+ * never uploaded (server commit assembles in memory). Its sidecars still
+ * collect. D9 damped: the prior durable copy is still good enough, and the
+ * session reports `reused_existing` from cursor state, so no skip is recorded.
+ */
+async function collectClaudeMainFile(collection, session) {
+    if (session.main_file_oversized) {
+        collection.skipped.push({
+            kind: "claude_jsonl",
+            label: path.basename(session.local_path),
+            reason: "file_too_large",
+        });
+        return "skipped_too_large";
+    }
+    if (session.skip_main)
+        return "damped_reuse";
+    const accepted = await collectOneEvidenceFile(collection, {
+        filePath: session.local_path,
+        kind: "claude_jsonl",
+        sessionId: session.claude_session_id,
+        mediaType: "application/jsonl",
+        // Re-check size at collection: a main that grew past the cap between
+        // attribution and collection is an honest file_too_large skip, not an
+        // upload_failed at the chunk client.
+        maxFileBytes: CLAUDE_MAX_COLLECT_FILE_BYTES,
+        redactedSummary: "Raw Claude Code JSONL transcript with prompts, responses, tool arguments, and tool outputs preserved locally.",
+        contentAddress: (hash16) => `claude/${safeKeySegment(session.claude_session_id)}/${hash16}.jsonl`,
+    });
+    return accepted ? "collected" : "not_collected";
+}
+async function collectOneClaudeSidecar(collection, session, sidecarPath) {
+    const sessionId = session.claude_session_id;
+    const stem = path.basename(sidecarPath).replace(/\.jsonl$/i, "");
+    const safeSidecarId = isSecretLikePath(stem)
+        ? "redacted-file-name"
+        : safeKeySegment(stem);
+    const sidecarAccepted = await collectOneEvidenceFile(collection, {
+        filePath: sidecarPath,
+        kind: "claude_jsonl_sidecar",
+        sessionId,
+        mediaType: "application/jsonl",
+        maxFileBytes: CLAUDE_MAX_COLLECT_FILE_BYTES,
+        redactedSummary: "Raw Claude Code subagent transcript with prompts, responses, tool arguments, and tool outputs preserved locally.",
+        contentAddress: (hash16) => `claude/${safeKeySegment(sessionId)}/subagents/${safeSidecarId}-${hash16}.jsonl`,
+    });
+    if (!sidecarAccepted)
+        return;
+    await collectAgentImagesFromTranscript(collection, {
+        filePath: sidecarPath,
+        source: "claude_code",
+        sessionId,
+        sidecarId: safeSidecarId,
+        kind: "claude_image_attachment",
+        contentAddress: (hash16, extension) => `claude/${safeKeySegment(sessionId)}/subagents/${safeSidecarId}/images/${hash16}.${extension}`,
+    });
+}

package/dist/adapters/raw-evidence-codex-reader.js

@@ -0,0 +1,147 @@
+/**
+ * Which Codex transcripts this pass reads, and the walk it falls back to.
+ *
+ * Attribution normally hands over an exact list, and that list is never
+ * trimmed: the session limit guards only the fallback walk, which can turn up
+ * every Codex session on the machine and would otherwise let one busy laptop
+ * spend the whole sync. Either way the cap is declared, observed and recorded,
+ * so a trimmed pass says how many it left out.
+ *
+ * A session is a transcript first and its attached images second, never the
+ * reverse — images are only collected once the transcript itself was accepted.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { describeError } from "../health-detail.js";
+import { defaultCodexSessionDirs } from "./codex-attribution.js";
+import { isSecretLikePath, safeKeySegment, shortHash, } from "./raw-evidence-keys.js";
+import { recordScanned } from "./raw-evidence-completeness.js";
+import { collectOneEvidenceFile } from "./raw-evidence-transcript-file.js";
+import { collectAgentImagesFromTranscript } from "./raw-evidence-image-reader.js";
+export async function collectCodexJsonlFiles(collection, options) {
+    for (const candidate of await chooseCodexCandidates(collection, options)) {
+        recordScanned(collection, "codex_jsonl");
+        await collectOneCodexSession(collection, candidate);
+    }
+}
+/**
+ * Which Codex transcripts this pass will look at, and the record of how many it
+ * had to leave out. Attribution's own list is never trimmed — the session limit
+ * only guards the fallback walk, which can turn up every session on the machine.
+ */
+async function chooseCodexCandidates(collection, options) {
+    const attributed = Boolean(options.codexSessionFiles);
+    const candidates = options.codexSessionFiles
+        ? options.codexSessionFiles.map((file) => ({
+            filePath: file.local_path,
+            codexSessionId: file.codex_session_id,
+        }))
+        : (await walkRecentCodexJsonlFiles(collection, options)).map((filePath) => ({ filePath, codexSessionId: null }));
+    collection.caps.push({
+        source: "codex_jsonl",
+        cap_type: "session_limit",
+        limit: options.limit,
+        observed: candidates.length,
+        applied: !attributed && candidates.length > options.limit,
+    });
+    return attributed ? candidates : candidates.slice(0, options.limit);
+}
+/** The transcript, then the images it explicitly attached — never the reverse. */
+async function collectOneCodexSession(collection, candidate) {
+    const codexSessionId = candidate.codexSessionId ?? shortHash(candidate.filePath);
+    const transcriptAccepted = await collectOneEvidenceFile(collection, {
+        filePath: candidate.filePath,
+        kind: "codex_jsonl",
+        sessionId: codexSessionId,
+        mediaType: "application/jsonl",
+        // Guard before read/toString: Codex files can exceed the buffered commit
+        // ceiling just like Claude mains.
+        maxFileBytes: RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES,
+        redactedSummary: "Raw Codex JSONL transcript with prompts, responses, tool arguments, and tool outputs preserved locally.",
+        contentAddress: (hash16) => `codex/${safeKeySegment(codexSessionId)}/${hash16}.jsonl`,
+    });
+    if (!transcriptAccepted)
+        return;
+    await collectAgentImagesFromTranscript(collection, {
+        filePath: candidate.filePath,
+        source: "codex",
+        sessionId: codexSessionId,
+        kind: "codex_image_attachment",
+        contentAddress: (hash16, extension) => `codex/${safeKeySegment(codexSessionId)}/images/${hash16}.${extension}`,
+    });
+}
+/** The unattributed fallback: every recent Codex transcript on this machine. */
+function walkRecentCodexJsonlFiles(collection, options) {
+    const dirs = options.sessionsDirs ??
+        (options.sessionsDir
+            ? [options.sessionsDir]
+            : defaultCodexSessionDirs(os.homedir()));
+    return walkJsonlFiles(dirs, collection.context.now.getTime() - options.sinceMinutes * 60 * 1000);
+}
+// ---------------------------------------------------------------------------
+// Walking the session store
+// ---------------------------------------------------------------------------
+/**
+ * Newest-first `.jsonl` files under these directories, modified since `cutoffMs`.
+ *
+ * Secret-like directory and file names are never descended into or opened;
+ * symlinked duplicates are collapsed by real path so one transcript reachable
+ * two ways is collected once.
+ */
+async function walkJsonlFiles(dir, cutoffMs) {
+    const out = [];
+    const stack = Array.isArray(dir) ? [...dir] : [dir];
+    const seen = new Set();
+    // Counted rather than logged per directory: a wide walk can hit many, and
+    // the useful signal is "N directories in the session store were skipped and
+    // here is the first reason", not N near-identical lines (BLI-3238).
+    let unreadableDirCount = 0;
+    let firstUnreadableDir = null;
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current || isSecretLikePath(current))
+            continue;
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            // A directory that cannot be listed hides every session under it, and
+            // the walk's only visible effect is a smaller file count.
+            unreadableDirCount += 1;
+            firstUnreadableDir ??= describeError(error);
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (isSecretLikePath(full))
+                continue;
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+                continue;
+            const stat = await fs.stat(full);
+            if (stat.mtimeMs < cutoffMs)
+                continue;
+            const dedupeKey = await fs.realpath(full).catch(() => path.resolve(full));
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            out.push({ file: full, mtimeMs: stat.mtimeMs });
+        }
+    }
+    if (unreadableDirCount > 0) {
+        console.error("[raw-evidence] session-store directories skipped during the walk", JSON.stringify({
+            reason: "session_dir_unreadable",
+            unreadable_dir_count: unreadableDirCount,
+            found_file_count: out.length,
+            ...firstUnreadableDir,
+        }));
+    }
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return out.map((entry) => entry.file);
+}

package/dist/adapters/raw-evidence-collection-state.js

@@ -0,0 +1,199 @@
+/**
+ * What one collection pass carries, what it may spend, and where its bytes land.
+ *
+ * `CollectionState` is the single object every source path in this family
+ * threads through. Its gap-ledger fields (`scanned`, `skipped`, `truncated`,
+ * `failed`, `redacted`, `reused`, `caps`) are exactly the `EvidenceGapLedger`
+ * contract, so `raw-evidence-completeness.ts` can read and write them without
+ * knowing about packs, budgets or disks.
+ *
+ * Two mechanics live here rather than in any one reader, because the Codex
+ * reader, the Claude reader, the image reader and the git-diff reader all spend
+ * them:
+ *
+ * - **`admitToBudget`** — the per-sync byte and object budget (D7b),
+ *   decremented in place so one `cockpit sync` across many worktrees honours
+ *   one cap.
+ * - **`stageEvidenceBytes`** — bytes go on disk exactly once; content an
+ *   earlier sync already staged is adopted rather than copied again.
+ *
+ * Opening a pass is staging-first (BLI-3066): a pack is named by its content,
+ * so its id cannot be known yet and the bytes land in a private
+ * `.staging-<pid>-<rand>` directory that `raw-evidence-facts.ts` promotes once
+ * collection is done.
+ */
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DELIVERY_BACKOFF_BYPASS_REASON, deliveryBackoffApplies, heldSourceKeys, readRawEvidenceStagingState, resolveStagedObject, } from "../raw-evidence-staging.js";
+import { chmodPrivate } from "./raw-evidence-pack-store.js";
+import { GIT_DIFF_TIMEOUT_MS, MAX_GIT_DIFF_BYTES, } from "./raw-evidence-git-diff.js";
+export const DEFAULT_SINCE_MINUTES = 24 * 60;
+export const DEFAULT_SESSION_LIMIT = 50;
+// Per-sync upload budgets enforced at COLLECTION time (D7b). A single marathon
+// transcript can approach the 500 MiB wire cap (RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES),
+// so 2 GiB leaves room for several files without starving the sync; overflow
+// still defers and converges.
+export const RAW_EVIDENCE_DEFAULT_BYTE_BUDGET = 2 * 1024 * 1024 * 1024;
+export const RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET = 300;
+export const CLAUDE_MAX_COLLECT_FILE_BYTES = RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES;
+// ---------------------------------------------------------------------------
+// Opening a pass
+// ---------------------------------------------------------------------------
+/**
+ * Staging first, promotion second (BLI-3066). The pack id cannot be known until
+ * the content is, so bytes land in a private per-attempt directory, and that
+ * directory is then renamed to its content-keyed name — or dropped, when an
+ * identical pack is already there.
+ */
+export function newStagingDir(rawEvidenceRoot) {
+    return path.join(rawEvidenceRoot, `.staging-${process.pid}-${crypto.randomUUID().slice(0, 8)}`);
+}
+export async function openCollection(context, options, places) {
+    const byteBudget = options.byteBudget ?? RAW_EVIDENCE_DEFAULT_BYTE_BUDGET;
+    const objectBudget = options.objectBudget ?? RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET;
+    const staging = await readRawEvidenceStagingState(options.stateDir);
+    return {
+        context,
+        filesDir: path.join(places.stagingDir, "files"),
+        rawEvidenceRoot: places.rawEvidenceRoot,
+        packId: "",
+        staging,
+        heldSources: collectionHeldSources(staging, context.now, options),
+        stagedReusedCount: 0,
+        stagedNewCount: 0,
+        deliveryHeldCount: 0,
+        entries: [],
+        skipped: [],
+        truncated: [],
+        failed: [],
+        redacted: [],
+        reused: [],
+        scanned: new Map(),
+        caps: startingCaps({ byteBudget, objectBudget, budget: options.budget }),
+        skipContentHashes: options.skipContentHashes ?? new Set(),
+        budget: options.budget ?? {
+            remainingBytes: byteBudget,
+            remainingObjects: objectBudget,
+        },
+        index: { value: 0 },
+    };
+}
+/**
+ * Which sources this pass refuses to even read because their delivery is inside
+ * a backoff window — none of them, when a person asked for this pass.
+ *
+ * The bypass is logged rather than assumed: an operator retry that quietly
+ * ignored a hold would be as unreadable as the hold that quietly blocked it.
+ */
+function collectionHeldSources(staging, now, options) {
+    const held = heldSourceKeys(staging, now);
+    if (deliveryBackoffApplies(options.deliveryMode))
+        return held;
+    if (held.size > 0) {
+        console.error("[raw-evidence] delivery backoff bypassed for operator retry", JSON.stringify({
+            reason: DELIVERY_BACKOFF_BYPASS_REASON,
+            source_count: held.size,
+        }));
+    }
+    return new Set();
+}
+/** Every cap this pass could hit, declared up front and flipped when applied. */
+function startingCaps(options) {
+    return [
+        {
+            source: "raw_evidence",
+            cap_type: "byte_budget",
+            limit: options.byteBudget,
+            observed: options.budget?.remainingBytes ?? options.byteBudget,
+            applied: false,
+        },
+        {
+            source: "raw_evidence",
+            cap_type: "object_budget",
+            limit: options.objectBudget,
+            observed: options.budget?.remainingObjects ?? options.objectBudget,
+            applied: false,
+        },
+        {
+            source: "git_diff",
+            cap_type: "max_bytes_per_diff",
+            limit: MAX_GIT_DIFF_BYTES,
+            applied: false,
+        },
+        {
+            source: "git_diff",
+            cap_type: "timeout_ms",
+            limit: GIT_DIFF_TIMEOUT_MS,
+            applied: false,
+        },
+        {
+            source: "codex_jsonl",
+            cap_type: "max_file_bytes",
+            limit: RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES,
+            applied: false,
+        },
+        {
+            source: "claude_jsonl",
+            cap_type: "max_file_bytes",
+            limit: CLAUDE_MAX_COLLECT_FILE_BYTES,
+            applied: false,
+        },
+        {
+            source: "claude_jsonl_sidecar",
+            cap_type: "max_file_bytes",
+            limit: CLAUDE_MAX_COLLECT_FILE_BYTES,
+            applied: false,
+        },
+    ];
+}
+export async function discardStagingDir(stagingDir) {
+    await fs
+        .rm(stagingDir, { recursive: true, force: true })
+        .catch(() => undefined);
+}
+// ---------------------------------------------------------------------------
+// Staging and budgets
+// ---------------------------------------------------------------------------
+/**
+ * Put these bytes on disk once.
+ *
+ * If an earlier sync already staged this exact content and the copy is still
+ * there, that copy is used — the uploader only needs a readable path, and it
+ * does not care which pack directory holds it. This is the branch that stops
+ * one 334 MB rollout from becoming 559 copies while its commit keeps failing.
+ */
+export async function stageEvidenceBytes(collection, options) {
+    const existing = await resolveStagedObject(collection.rawEvidenceRoot, collection.staging, options.contentHash);
+    if (existing) {
+        collection.stagedReusedCount += 1;
+        console.error("[raw-evidence] staged copy reused", JSON.stringify({
+            reason: "staged_reused",
+            kind: options.kind,
+            content_hash_prefix: options.contentHash.slice(0, 16),
+            byte_size: existing.entry.byte_size,
+            pack_id: existing.entry.pack_id,
+        }));
+        return { local_path: existing.local_path, staged_in_pack: false };
+    }
+    const destination = path.join(collection.filesDir, options.fileName);
+    await fs.writeFile(destination, options.bytes, { mode: 0o600 });
+    await chmodPrivate(destination, 0o600);
+    collection.stagedNewCount += 1;
+    return { local_path: destination, staged_in_pack: true };
+}
+/**
+ * Decrements the per-sync budget when a file fits, or returns a deferred-skip
+ * reason when it does not. The object budget bounds request count; the byte
+ * budget bounds buffered bytes.
+ */
+export function admitToBudget(budget, byteLength) {
+    if (budget.remainingObjects <= 0)
+        return "deferred_object_budget";
+    if (byteLength > budget.remainingBytes)
+        return "deferred_byte_budget";
+    budget.remainingObjects -= 1;
+    budget.remainingBytes -= byteLength;
+    return null;
+}