@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/commands/backfill-batches.js

@@ -0,0 +1,34 @@
+/**
+ * Which scanned sessions are actually uploadable, and how they are cut into
+ * the units one upload call handles. Batches are per worktree because the sync
+ * path uploads one repo's envelope at a time, and capped in size so a single
+ * failure costs one batch rather than the whole history.
+ */
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+export const BACKFILL_UPLOAD_BATCH_SESSIONS = 25;
+export function uploadableCandidates(candidates) {
+    return candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+        candidate.worktree);
+}
+export function buildBackfillBatches(candidates) {
+    const byWorktree = new Map();
+    for (const candidate of candidates) {
+        if (!candidate.worktree)
+            continue;
+        const key = candidate.worktree.worktree_fingerprint;
+        byWorktree.set(key, [...(byWorktree.get(key) ?? []), candidate]);
+    }
+    const batches = [];
+    for (const group of byWorktree.values()) {
+        const worktree = group[0]?.worktree;
+        if (!worktree)
+            continue;
+        for (let offset = 0; offset < group.length; offset += BACKFILL_UPLOAD_BATCH_SESSIONS) {
+            batches.push({
+                worktree,
+                candidates: group.slice(offset, offset + BACKFILL_UPLOAD_BATCH_SESSIONS),
+            });
+        }
+    }
+    return batches;
+}

package/dist/commands/backfill-candidates.js

@@ -0,0 +1,54 @@
+/**
+ * How backfill identifies and orders one archived session. The cursor key is
+ * the durable identity every later stage keys on — batches, durability, the
+ * resume cursor — so it is computed in exactly one place, from the source, the
+ * session id and a path normalized the same way on every host.
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+export function isAfterCursor(candidate, cursor) {
+    const source = cursor.sources[candidate.source];
+    const oldest = source?.oldest_mtime_ms_processed;
+    if (oldest === null || oldest === undefined)
+        return true;
+    if (candidate.session_file_mtime_ms < oldest)
+        return true;
+    const key = candidateCursorKey(candidate);
+    if (candidate.session_file_mtime_ms === oldest) {
+        return !source.processed_keys_at_oldest_mtime.includes(key);
+    }
+    const newest = source.newest_mtime_ms_covered;
+    // A cursor written before upper-edge coverage existed gets one safe
+    // migration pass across the previously processed interval. Once that pass is
+    // acknowledged, subsequent --all runs only inspect genuinely newer files.
+    if (newest === null)
+        return true;
+    if (candidate.session_file_mtime_ms > newest)
+        return true;
+    if (candidate.session_file_mtime_ms < newest)
+        return false;
+    // A legacy cursor has no boundary identities. Rechecking the equal-time
+    // boundary is safe because durable evidence is content-addressed.
+    return !source.processed_keys_at_newest_mtime.includes(key);
+}
+export function compareBackfillCandidates(a, b) {
+    return (b.session_file_mtime_ms - a.session_file_mtime_ms ||
+        candidateCursorKey(a).localeCompare(candidateCursorKey(b)));
+}
+export function candidateCursorKey(candidate) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify([
+        candidate.source,
+        candidate.session_id,
+        normalizedCursorPath(candidate.file_path),
+    ]))
+        .digest("hex");
+}
+function normalizedCursorPath(filePath) {
+    const windowsStyle = path.win32.isAbsolute(filePath) && !path.posix.isAbsolute(filePath);
+    if (windowsStyle)
+        return path.win32.normalize(filePath).toLowerCase();
+    const normalized = path.resolve(filePath);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/dist/commands/backfill-checkpoint.js

@@ -0,0 +1,101 @@
+/**
+ * The only irreversible writes backfill makes: the pointer a delivered session
+ * earns in the live raw-evidence cursor, and the backfill cursor's advance.
+ *
+ * The cursor advances solely through a contiguous prefix of sessions that both
+ * earned a durable pointer and were acknowledged by the server, and not at all
+ * while discovery is incomplete — a misjudged "resolved" here loses that
+ * history for good. Backfill and scheduled sync share these cursor files; the
+ * caller holds the collection lock for exactly that reason.
+ */
+import { recordBackfillCursorObservations, } from "../cursors/backfill-cursor.js";
+import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
+import { indexDurableMainObjectKeys } from "./backfill-evidence-outcomes.js";
+/**
+ * Writes the pointer a session earned back into the live raw-evidence cursor,
+ * so the next scheduled sync knows it is already delivered. Backfill and sync
+ * share these cursors; the caller holds the collection lock for exactly this.
+ */
+export async function recordBackfillDurableSessionPointers(options) {
+    const durableObjectBySession = indexDurableMainObjectKeys(options.syncResults);
+    let recordedCount = 0;
+    for (const source of ["codex", "claude_code"]) {
+        const filename = source === "claude_code" ? CLAUDE_CURSOR_FILENAME : undefined;
+        const cursor = await readRawEvidenceCursor(options.paths, { filename });
+        let changed = false;
+        for (const candidate of options.candidates) {
+            if (candidate.source !== source)
+                continue;
+            const objectKey = durableObjectBySession.get(`${source}:${candidate.session_id}`);
+            const prior = cursor.sessions[candidate.session_id];
+            // No pointer, no prior entry, or already pointed: nothing this pass owes.
+            if (!objectKey || !prior || prior.uploaded_object_key)
+                continue;
+            cursor.sessions[candidate.session_id] = deliveredCursorEntry(prior, candidate, objectKey, options.now);
+            changed = true;
+            recordedCount += 1;
+        }
+        if (changed) {
+            await writeRawEvidenceCursor(options.paths, cursor, {
+                filename,
+                sessionsOnly: source === "claude_code",
+            });
+        }
+    }
+    if (recordedCount > 0) {
+        console.error("[backfill] terminal session pointers recorded", JSON.stringify({ count: recordedCount }));
+    }
+}
+/** The cursor entry for a session backfill has just delivered in full. */
+function deliveredCursorEntry(prior, candidate, objectKey, now) {
+    return {
+        ...prior,
+        file_hash_sha256: candidate.content_hash_sha256,
+        file_mtime_ms: candidate.session_file_mtime_ms,
+        byte_size: candidate.byte_size,
+        // The whole file was delivered, so the incremental reader starts at its end.
+        byte_offset: candidate.byte_size,
+        state: candidate.state,
+        reason: candidate.reason,
+        worktree_fingerprint: candidate.worktree?.worktree_fingerprint ?? null,
+        uploaded_object_key: objectKey,
+        uploaded_at: now.toISOString(),
+        uploaded_byte_size: candidate.byte_size,
+        last_seen_at: now.toISOString(),
+    };
+}
+export function advanceBackfillCursorThroughResolvedPrefix(options) {
+    if (!options.discoveryComplete)
+        return false;
+    const observations = [];
+    for (const source of ["codex", "claude_code"]) {
+        const remaining = options.candidates
+            .filter((candidate) => candidate.source === source &&
+            isAfterCursor(candidate, options.cursor))
+            .sort(compareBackfillCandidates);
+        for (const candidate of remaining) {
+            const key = candidateCursorKey(candidate);
+            if (options.retryableCandidateKeys.has(key))
+                break;
+            const resolved = isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null)
+                ? options.durableCandidateKeys.has(key)
+                : true;
+            if (!resolved)
+                break;
+            observations.push({
+                source: candidate.source,
+                cursor_key: key,
+                state: candidate.state,
+                reason: candidate.reason,
+                session_file_mtime_ms: candidate.session_file_mtime_ms,
+                session_file_mtime: candidate.session_file_mtime,
+            });
+        }
+    }
+    if (observations.length === 0)
+        return false;
+    recordBackfillCursorObservations(options.cursor, observations, options.now);
+    return true;
+}

package/dist/commands/backfill-command-line.js

@@ -0,0 +1,70 @@
+/**
+ * The flag surface of `cockpit backfill`, read back out: the window a bare
+ * invocation means, and the copyable command that reproduces or widens a run.
+ * Every retry an operator is handed is built here, so the flags stay spelled
+ * one way and quoting stays correct on both supported shells.
+ */
+import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, } from "../repo-identity.js";
+// Window a bare `cockpit backfill` uses. Wide enough to cover a new machine's
+// recent history and an intern who went quiet for a few weeks, narrow enough
+// that it is not the whole-history scan `--all` deliberately gates.
+export const DEFAULT_BACKFILL_SINCE_DAYS = 30;
+export function defaultBackfillWindowNotice() {
+    return [
+        `No window given — backfilling the last ${DEFAULT_BACKFILL_SINCE_DAYS} days.`,
+        "The effective start is capped at the collector paired_at timestamp.",
+        "Use `cockpit backfill --since-days N` for a different window, or `cockpit backfill --all` for the full local history (review a dry-run first; add `--yes` on headless agent runs).",
+    ].join("\n");
+}
+/**
+ * Produces a copyable retry that preserves the requested history window and
+ * every discovery/selection override. Values that need quoting use syntax
+ * accepted by the supported native shells: POSIX shells on macOS and
+ * PowerShell on Windows.
+ */
+export function backfillRetryCommand(command) {
+    const parts = ["cockpit", "backfill"];
+    if (command.all) {
+        parts.push("--all", "--yes");
+    }
+    else if (command.sinceDays !== undefined) {
+        parts.push("--since-days", String(command.sinceDays));
+    }
+    if (command.source)
+        parts.push("--source", command.source);
+    if (command.maxFiles !== undefined) {
+        parts.push("--max-files", String(command.maxFiles));
+    }
+    if (command.maxDepth !== undefined) {
+        parts.push("--max-depth", String(command.maxDepth));
+    }
+    if (command.maxRepos !== undefined) {
+        parts.push("--max-repos", String(command.maxRepos));
+    }
+    if (command.repoRoot) {
+        parts.push("--workspace", quoteCliArgument(command.repoRoot));
+    }
+    if (command.dryRun)
+        parts.push("--dry-run");
+    return parts.join(" ");
+}
+export function backfillDiscoveryRetryCommand(command, discovery) {
+    const retry = { ...command };
+    if (discovery.incomplete_reasons.includes("max_depth_reached")) {
+        retry.maxDepth =
+            (command.maxDepth ?? DEFAULT_DISCOVERY_MAX_DEPTH) + 1;
+    }
+    if (discovery.incomplete_reasons.includes("max_worktrees_reached")) {
+        retry.maxRepos =
+            (command.maxRepos ?? DEFAULT_DISCOVERY_MAX_REPOS) * 2;
+    }
+    return backfillRetryCommand(retry);
+}
+function quoteCliArgument(value) {
+    if (/^[a-z0-9_./:\\-]+$/iu.test(value))
+        return value;
+    const escaped = process.platform === "win32"
+        ? value.replaceAll("'", "''")
+        : value.replaceAll("'", `'\"'\"'`);
+    return `'${escaped}'`;
+}

package/dist/commands/backfill-evidence-outcomes.js

@@ -0,0 +1,104 @@
+import { candidateCursorKey } from "./backfill-candidates.js";
+/** Evidence the server accepted the batch for but had no budget left to store. */
+export function deferredEvidenceCount(sync) {
+    return (sync.raw_evidence_deferred_byte_budget +
+        sync.raw_evidence_deferred_object_budget);
+}
+/**
+ * Which candidates in this batch are now safe to leave behind forever: a
+ * session counts as durable only when its main transcript AND every sidecar
+ * we expected earned a pointer, and nothing in it failed. This set is what the
+ * cursor advances through, so an over-generous answer here loses history
+ * permanently.
+ */
+export function durableBackfillCandidateKeys(batch, sync) {
+    const durable = new Set();
+    if (sync.status !== "uploaded")
+        return durable;
+    if (deferredEvidenceCount(sync) > 0) {
+        // Deferred outcomes have no per-file identity. Advancing any candidate in
+        // this batch could therefore strand the deferred main transcript.
+        return durable;
+    }
+    const outcomesBySession = summarizeEvidenceOutcomesBySession(sync);
+    for (const candidate of batch.candidates) {
+        const summary = outcomesBySession.get(`${candidate.source}:${candidate.session_id}`);
+        if (summary &&
+            !summary.failed &&
+            summary.durableMainCount > 0 &&
+            summary.durableSidecarCount >= expectedSidecarCount(candidate)) {
+            durable.add(candidateCursorKey(candidate));
+        }
+    }
+    return durable;
+}
+function summarizeEvidenceOutcomesBySession(sync) {
+    const outcomesBySession = new Map();
+    for (const outcome of sync.raw_evidence_outcomes) {
+        const source = backfillSourceForEvidenceKind(outcome.kind);
+        if (!source || !outcome.codex_session_id)
+            continue;
+        const key = `${source}:${outcome.codex_session_id}`;
+        const summary = outcomesBySession.get(key) ?? {
+            durableMainCount: 0,
+            durableSidecarCount: 0,
+            failed: false,
+        };
+        if (outcome.upload_state === "upload_failed") {
+            summary.failed = true;
+        }
+        else if (outcome.raw_evidence_pointer_id &&
+            (outcome.upload_state === "uploaded" ||
+                outcome.upload_state === "reused_existing")) {
+            if (outcome.kind === "codex_jsonl" || outcome.kind === "claude_jsonl") {
+                summary.durableMainCount += 1;
+            }
+            else if (outcome.kind === "claude_jsonl_sidecar") {
+                summary.durableSidecarCount += 1;
+            }
+        }
+        outcomesBySession.set(key, summary);
+    }
+    return outcomesBySession;
+}
+/** Sidecars this session owes a pointer for; one already skipped at scan time is not owed. */
+function expectedSidecarCount(candidate) {
+    if (candidate.source !== "claude_code")
+        return 0;
+    return (candidate.claude?.sidecar_files.filter((sidecar) => !sidecar.skipped_reason)
+        .length ?? 0);
+}
+/** Storage keys for main transcripts that actually landed, keyed by source and session. */
+export function indexDurableMainObjectKeys(syncResults) {
+    const durableObjectBySession = new Map();
+    for (const sync of syncResults) {
+        for (const outcome of sync.raw_evidence_outcomes) {
+            if (!outcome.codex_session_id ||
+                (outcome.kind !== "codex_jsonl" && outcome.kind !== "claude_jsonl") ||
+                (outcome.upload_state !== "uploaded" &&
+                    outcome.upload_state !== "reused_existing") ||
+                !outcome.object_key) {
+                continue;
+            }
+            const source = outcome.kind === "codex_jsonl" ? "codex" : "claude_code";
+            durableObjectBySession.set(`${source}:${outcome.codex_session_id}`, outcome.object_key);
+        }
+    }
+    return durableObjectBySession;
+}
+export function countSessionUploadFailures(sync) {
+    return sync.raw_evidence_outcomes.filter((outcome) => Boolean(outcome.codex_session_id) &&
+        outcome.upload_state === "upload_failed" &&
+        Boolean(backfillSourceForEvidenceKind(outcome.kind))).length;
+}
+function backfillSourceForEvidenceKind(kind) {
+    if (kind === "codex_jsonl" || kind === "codex_image_attachment") {
+        return "codex";
+    }
+    if (kind === "claude_jsonl" ||
+        kind === "claude_jsonl_sidecar" ||
+        kind === "claude_image_attachment") {
+        return "claude_code";
+    }
+    return null;
+}

package/dist/commands/backfill-issues.js

@@ -0,0 +1,265 @@
+/**
+ * Everything the scan could not account for cleanly, in one ledger — the
+ * module that exists so a session is never silently dropped.
+ *
+ * Scope is the load-bearing distinction. A global issue means discovery may
+ * have hidden a session at any mtime, so no source watermark is safe to
+ * advance; a candidate issue only stops the contiguous cursor prefix at the
+ * affected session; a selection issue is the operator's own `--max-files` cap.
+ * Every write goes through a named operation here rather than a bare `.push`,
+ * so the ledger's shape and priority order have one owner.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { describeError } from "../health-detail.js";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { candidateCursorKey } from "./backfill-candidates.js";
+/**
+ * Everything the scan could not account for cleanly, in one ledger. Read in
+ * three passes — what the Codex store hid, what the Claude store hid, then
+ * what is wrong with the candidates that survived — because the first two are
+ * global (discovery may have missed a session at any mtime, so no watermark is
+ * safe to advance) and the third only stops the contiguous cursor prefix.
+ */
+export async function backfillScanIssues(options) {
+    const issues = [];
+    if (options.codexAttribution) {
+        await addCodexStoreScanIssues(issues, options.codexAttribution, options.codexSessionDirs);
+    }
+    if (options.claudeAttribution) {
+        await addClaudeStoreScanIssues(issues, options.claudeAttribution, options.claudeProjectsDir, options.candidates);
+    }
+    addCandidateScanIssues(issues, options.candidates, options.omittedCandidateCount);
+    sortScanIssuesByPriority(issues);
+    return issues;
+}
+/** What the archived Codex store could not tell us — every one of these hides history. */
+async function addCodexStoreScanIssues(issues, codexAttribution, codexSessionDirs) {
+    countScanIssue(issues, "codex_session_limit_applied", codexAttribution.session_limit_applied
+        ? Math.max(1, codexAttribution.discovered_file_count -
+            codexAttribution.scanned_file_count)
+        : 0, "global");
+    // A session directory that simply does not exist on this machine is not a
+    // read failure; subtract those before reporting one.
+    const missingTopLevelDirs = (await Promise.all(codexSessionDirs.map(isMissingPath))).filter(Boolean).length;
+    countScanIssue(issues, "codex_directory_read_failed", Math.max(0, codexAttribution.directory_read_failed_count - missingTopLevelDirs), "global");
+    countScanIssue(issues, "codex_session_stat_failed", codexAttribution.stat_failed_count, "global");
+}
+/** The same census for the Claude store, which also has sidecars to account for. */
+async function addClaudeStoreScanIssues(issues, claudeAttribution, claudeProjectsDir, candidates) {
+    countScanIssue(issues, "claude_session_limit_applied", claudeAttribution.session_limit_applied
+        ? Math.max(1, claudeAttribution.discovered_session_count -
+            claudeAttribution.scanned_session_count)
+        : 0, "global");
+    const projectsDirMissing = await isMissingPath(claudeProjectsDir);
+    countScanIssue(issues, "claude_project_dir_read_failed", Math.max(0, claudeAttribution.project_dir_read_failed_count -
+        (projectsDirMissing ? 1 : 0)), "global");
+    countScanIssue(issues, "claude_session_stat_failed", claudeAttribution.session_stat_failed_count, "global");
+    countScanIssue(issues, "claude_sidecar_stat_failed", claudeAttribution.sidecar_stat_failed_count, "global");
+    countScanIssue(issues, "claude_sidecar_dir_read_failed", await countUnreadableClaudeSidecarDirs(candidates), "global");
+}
+/** What is wrong with the sessions that did survive discovery, plus the one we chose to drop. */
+function addCandidateScanIssues(issues, candidates, omittedCandidateCount) {
+    countScanIssue(issues, "backfill_max_files_applied", omittedCandidateCount, "selection");
+    countScanIssue(issues, "candidate_file_read_failed", candidates.filter((candidate) => candidate.reason === "file_read_failed")
+        .length, "candidate");
+    countScanIssue(issues, "candidate_worktree_unavailable", candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) && candidate.worktree === null).length, "candidate");
+    countScanIssue(issues, "claude_main_file_too_large", candidates.filter((candidate) => candidate.source === "claude_code" &&
+        candidate.claude?.main_file_oversized).length, "candidate");
+    countScanIssue(issues, "claude_sidecar_limit_applied", candidates.reduce((total, candidate) => total + (candidate.claude?.sidecars_capped ?? 0), 0), "candidate");
+    countScanIssue(issues, "claude_sidecar_file_unreadable", candidates.reduce((total, candidate) => total +
+        (candidate.claude?.sidecar_files.filter((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
+            sidecar.skipped_reason === "file_too_large").length ?? 0), 0), "candidate");
+}
+function scanIssuePriority(scope) {
+    if (scope === "global")
+        return 0;
+    if (scope === "candidate")
+        return 1;
+    return 2;
+}
+export function retryableCandidateKeys(candidates) {
+    return new Set(candidates
+        .filter((candidate) => candidate.reason === "file_read_failed" ||
+        candidate.reason === "repo_not_on_disk" ||
+        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+            !candidate.worktree) ||
+        Boolean(candidate.claude?.main_file_oversized) ||
+        (candidate.claude?.sidecars_capped ?? 0) > 0 ||
+        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
+            sidecar.skipped_reason === "file_too_large")))
+        .map(candidateCursorKey));
+}
+/**
+ * A main session file whose only story is "too large to upload under the
+ * current cap" (BLI-2727). This mirrors exactly the two branches in
+ * `countReadOnlyGuards` that emit the `file_too_large` reason, so a candidate
+ * is in this set if and only if it contributed to that scan issue's count —
+ * one predicate, no drift between "why the issue fired" and "which candidate
+ * caused it". Deterministic and non-retryable: rerunning backfill cannot
+ * resolve it (only a larger cap or a smaller file can), so unlike a transient
+ * read failure it must never poison completion or a batch's success.
+ */
+export function oversizedBackfillCandidateKeys(candidates) {
+    const keys = new Set();
+    for (const candidate of candidates) {
+        if ((candidate.source === "claude_code" &&
+            candidate.claude?.main_file_oversized) ||
+            candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+            keys.add(candidateCursorKey(candidate));
+        }
+    }
+    return keys;
+}
+// --- Scan issue ledger --------------------------------------------------
+//
+// `scan.issues` is the running ledger of everything the scan could not
+// account for cleanly. Every write to it goes through one of the named
+// operations below instead of a bare `.push`/`.sort`, so the ledger's shape
+// (global vs candidate vs selection scope, priority order) has one owner.
+/** Record one issue on the ledger. */
+function addScanIssue(issues, issue) {
+    issues.push(issue);
+}
+/** Record one issue only if it actually happened; a zero count is not a finding. */
+function countScanIssue(issues, reason, count, scope) {
+    if (count > 0)
+        addScanIssue(issues, { reason, count, scope });
+}
+/** Repo discovery could not fully enumerate a root: one global issue per reason. */
+export function addRepoDiscoveryIssues(issues, incompleteReasons) {
+    for (const reason of incompleteReasons) {
+        addScanIssue(issues, {
+            reason: `repo_discovery_${reason}`,
+            count: 1,
+            scope: "global",
+        });
+    }
+}
+/** Stable read order: global issues first, then candidate, then selection; alphabetical within a scope. */
+export function sortScanIssuesByPriority(issues) {
+    issues.sort((a, b) => scanIssuePriority(a.scope) - scanIssuePriority(b.scope) ||
+        a.reason.localeCompare(b.reason));
+}
+/** The read-only guard pass's two aggregate outcomes, each recorded once if it fired at all. */
+export function addReadOnlyGuardIssues(issues, guardCounts) {
+    const readFailed = guardCounts.get("file_read_failed");
+    if (readFailed) {
+        addScanIssue(issues, {
+            reason: "candidate_file_read_failed",
+            count: readFailed,
+            scope: "candidate",
+        });
+    }
+    const tooLarge = guardCounts.get("file_too_large");
+    if (tooLarge) {
+        addScanIssue(issues, {
+            reason: "file_too_large",
+            count: tooLarge,
+            scope: "candidate",
+        });
+    }
+}
+// BLI-2727: a deterministic, labeled oversized skip must never poison
+// completion — it is a permanent, non-retryable fact about the file, not an
+// in-flight problem a rerun can fix. `scan.issues`/`retryable_candidate_keys`
+// still carry it (so it's never silently dropped from reporting); every
+// completion-gating computation excludes it explicitly instead, by filtering
+// through `blockingScanIssues` below.
+//
+// Two scan issues describe the exact same oversized-main candidates:
+// `backfillScanIssues` pushes the Claude-specific `claude_main_file_too_large`
+// (from `claude?.main_file_oversized`) and `countReadOnlyGuards` (via
+// `addReadOnlyGuardIssues` above) separately pushes the source-agnostic
+// `file_too_large` (same predicate as `oversizedBackfillCandidateKeys`, so
+// this list can never drift from it). Both must be excluded from
+// completion-gating together.
+const OVERSIZED_SCAN_ISSUE_REASONS = new Set([
+    "file_too_large",
+    "claude_main_file_too_large",
+]);
+export function blockingScanIssues(issues) {
+    return issues.filter((issue) => !OVERSIZED_SCAN_ISSUE_REASONS.has(issue.reason));
+}
+async function countUnreadableClaudeSidecarDirs(candidates) {
+    let unreadable = 0;
+    for (const candidate of candidates) {
+        if (candidate.source !== "claude_code")
+            continue;
+        const subagentsDir = path.join(path.dirname(candidate.file_path), path.basename(candidate.file_path).replace(/\.jsonl$/i, ""), "subagents");
+        try {
+            await fs.readdir(subagentsDir);
+        }
+        catch (error) {
+            if (!isMissingFsError(error))
+                unreadable += 1;
+        }
+    }
+    return unreadable;
+}
+async function isMissingPath(filePath) {
+    try {
+        await fs.stat(filePath);
+        return false;
+    }
+    catch (error) {
+        return isMissingFsError(error);
+    }
+}
+function isMissingFsError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+export async function countReadOnlyGuards(candidates) {
+    const counts = new Map();
+    const retryableCandidateKeys = new Set();
+    // Aggregated: this runs over the whole archived history, so a per-candidate
+    // line could be thousands. The count already travels; the reason did not
+    // (BLI-3238).
+    let firstReadFailure = null;
+    for (const candidate of candidates) {
+        if (candidate.reason === "repo_not_on_disk") {
+            increment(counts, "repo_not_on_disk");
+            retryableCandidateKeys.add(candidateCursorKey(candidate));
+        }
+        if (candidate.source === "claude_code" && candidate.claude?.main_file_oversized) {
+            increment(counts, "file_too_large");
+            retryableCandidateKeys.add(candidateCursorKey(candidate));
+            continue;
+        }
+        if (candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+            increment(counts, "file_too_large");
+            retryableCandidateKeys.add(candidateCursorKey(candidate));
+            continue;
+        }
+        if (!isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null))
+            continue;
+        try {
+            await fs.readFile(candidate.file_path);
+        }
+        catch (error) {
+            increment(counts, "file_read_failed");
+            firstReadFailure ??= describeError(error);
+            retryableCandidateKeys.add(candidateCursorKey(candidate));
+        }
+    }
+    const readFailedCount = counts.get("file_read_failed") ?? 0;
+    if (readFailedCount > 0) {
+        console.error("[cockpit-backfill] archived sessions could not be read", JSON.stringify({
+            reason: "file_read_failed",
+            read_failed_count: readFailedCount,
+            candidate_count: candidates.length,
+            ...firstReadFailure,
+        }));
+    }
+    return {
+        counts,
+        retryable_candidate_keys: retryableCandidateKeys,
+    };
+}
+export function increment(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+}