@bli-cockpit/cli 0.2.48 → 0.2.50

package/dist/commands/backfill.js

@@ -1,28 +1,54 @@
-import { NO_UPLOAD_ATTEMPT_RECORDED, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, notUploadableAttributionStateReason } from "@bli-cockpit/telemetry-core";
-import crypto from "node:crypto";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describeError } from "../health-detail.js";
-import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
-import { defaultCodexSessionDirs, scanAndAttributeCodexSessions } from "../adapters/codex-attribution.js";
-import { RAW_EVIDENCE_DEFAULT_BYTE_BUDGET, RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET } from "../adapters/raw-evidence.js";
-import { acquireBackfillLock, } from "../backfill-lock.js";
-import { BACKFILL_COMPLETION_RECHECK_MS, BACKFILL_COVERAGE_VERSION, emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCursor, recordBackfillCursorObservations, recordBackfillScanCoverage, writeBackfillCompletionMarker, writeBackfillCursor, } from "../cursors/backfill-cursor.js";
-import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
-import { getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, startLocalWorkContext } from "../local-state.js";
-import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, collectionRootPathAliases, discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
-import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
-import { normalizeCollectionRoots } from "../root-normalization.js";
+/**
+ * `cockpit backfill` — collect the archived Codex and Claude history that the
+ * every-15-minutes sync was never running to see.
+ *
+ * Read `runBackfill` below as the table of contents. It is four stages, in
+ * order, and every part of this command lives in exactly one of them:
+ *
+ *   SCAN    backfill-scan.ts       which roots, stores and window; read both
+ *                                  stores into candidates; census the gaps
+ *   PLAN    backfill-plan.ts       confirm `--all`, or answer a `--dry-run`
+ *   UPLOAD  backfill-upload.ts     sync in batches under the shared lock
+ *   REPORT  backfill-report.ts     post, checkpoint, decide, assemble
+ *
+ * The supporting modules each own one thing the stages share:
+ *
+ *   backfill-types.ts              the shapes every stage passes along
+ *   backfill-command-line.ts       the flag surface and the retry command
+ *   backfill-scope.ts              paired? which roots, sources and window
+ *   backfill-candidates.ts         one session's identity and ordering
+ *   backfill-batches.ts            what is uploadable, cut into batches
+ *   backfill-issues.ts             the ledger of what could not be accounted for
+ *   backfill-reasons.ts            the skip-reason table an operator reads
+ *   backfill-evidence-outcomes.ts  what one upload achieved per session
+ *   backfill-session-report.ts     one attribution row per session seen
+ *   backfill-checkpoint.ts         the durable cursor and pointer writes
+ *   backfill-result.ts             the `--json` payload
+ *   backfill-output.ts             every line and prompt a person sees
+ *
+ * Two rules run through all four stages and explain most of the apparent
+ * complexity. First, a session may never be silently dropped: everything the
+ * scan could not account for lands on the issue ledger and everything a person
+ * reads names its own reason. Second, the cursor is the only irreversible
+ * thing here — it advances solely through a contiguous prefix of sessions that
+ * both earned a durable pointer and were acknowledged by the server, so a
+ * misjudged "resolved" loses that history for good.
+ */
+import { acquireBackfillLock } from "../backfill-lock.js";
+import { writeBackfillCursor } from "../cursors/backfill-cursor.js";
 import { acquireSyncLock } from "../sync-lock.js";
-import { LocalUploadBlockedError, postCodexSessionReport, syncLocalAmbientEnvelope } from "../upload.js";
-const BACKFILL_UPLOAD_BATCH_SESSIONS = 25;
-const BACKFILL_MAX_CONSECUTIVE_FAILURES = 3;
-const ALL_BACKFILL_SINCE_MINUTES = 20 * 365 * 24 * 60;
-// 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;
+import { DEFAULT_BACKFILL_SINCE_DAYS, backfillRetryCommand, defaultBackfillWindowNotice, } from "./backfill-command-line.js";
+import { isInteractiveStdin, writeHumanBackfillResult, writeLine, } from "./backfill-output.js";
+import { planBackfillRun } from "./backfill-plan.js";
+import { reportBackfillOutcome } from "./backfill-report.js";
+import { lockHeldResult } from "./backfill-result.js";
+import { scanBackfillRun } from "./backfill-scan.js";
+import { uploadBackfillBatches } from "./backfill-upload.js";
+// The command's public surface. Callers (doctor, onboard, local, the CLI
+// router, the BLI-3272 regression test) import these from `./backfill.js`;
+// which sibling implements one is this module's business, not theirs.
+export { DEFAULT_BACKFILL_SINCE_DAYS, backfillRetryCommand } from "./backfill-command-line.js";
+export { buildBackfillSessionReport } from "./backfill-session-report.js";
 export async function runBackfillCommand(command, io) {
     // A bare `cockpit backfill` used to refuse and print three lines telling the
     // operator to pick a window. That put a mandatory flag on the command that
@@ -75,19 +101,10 @@ export async function runBackfill(command, io) {
     const { paths } = scanned;
     const lock = await acquireBackfillLock(paths, now);
     if (!lock.acquired) {
-        return {
-            ...baseBackfillResult(command, backfillResultBaseArgs(scanned)),
-            status: "blocked",
-            retry_command: scanned.retryCommand,
-            failure_reason: "backfill_already_running",
-            blocked_at: {
-                what: "backfill lock held",
-                batch_index: 0,
-                batch_total: 0,
-                done: 0,
-                total: scanned.scan.candidates.length,
-            },
-        };
+        return lockHeldResult(command, scanned, {
+            failureReason: "backfill_already_running",
+            what: "backfill lock held",
+        });
     }
     let collectionLock;
     try {
@@ -99,19 +116,10 @@ export async function runBackfill(command, io) {
     }
     if (!collectionLock.acquired) {
         await lock.handle.release();
-        return {
-            ...baseBackfillResult(command, backfillResultBaseArgs(scanned)),
-            status: "blocked",
-            retry_command: scanned.retryCommand,
-            failure_reason: "sync_already_running",
-            blocked_at: {
-                what: "sync collection lock held",
-                batch_index: 0,
-                batch_total: 0,
-                done: 0,
-                total: scanned.scan.candidates.length,
-            },
-        };
+        return lockHeldResult(command, scanned, {
+            failureReason: "sync_already_running",
+            what: "sync collection lock held",
+        });
     }
     try {
         // Backfill and scheduled/manual sync share upload spool and raw-evidence
@@ -128,1659 +136,4 @@ export async function runBackfill(command, io) {
         await collectionLock.handle.release();
         await lock.handle.release();
     }
-}
-/** The `{now, dashboardUrl, sources, window, cursor, scan, reasonCounts}` bag every `baseBackfillResult` call needs. */
-function backfillResultBaseArgs(ctx) {
-    return {
-        now: ctx.now,
-        dashboardUrl: ctx.dashboardUrl,
-        sources: ctx.sources,
-        window: ctx.window,
-        cursor: ctx.cursor,
-        scan: ctx.scan,
-        reasonCounts: ctx.reasonCounts,
-    };
-}
-/**
- * SCAN: is this machine paired, what roots/sources/window apply, and what did
- * the archived Codex + Claude session stores actually contain. Returns either
- * a terminal "not paired" result or everything PLAN/UPLOAD/REPORT need next.
- */
-async function scanBackfillRun(command, io, now) {
-    const paths = getCollectorRuntimePaths(command.homeDir);
-    const config = await readLocalCollectorConfig(paths);
-    const sessionFile = await readLocalCollectorSessionFile(paths);
-    const session = await readLocalSessionReference(paths);
-    if (session.session_state !== "valid") {
-        return {
-            kind: "blocked",
-            result: blockedBackfillResult(command, {
-                now,
-                dashboardUrl: sessionFile.dashboard_url ?? config.dashboard_url,
-                reason: "collector_not_paired",
-                cursor: await readBackfillCursor(paths),
-            }),
-        };
-    }
-    const pairedAt = parseRequiredDate(sessionFile.paired_at, "paired_at");
-    const dashboardUrl = normalizeDashboardUrl(sessionFile.dashboard_url ?? config.dashboard_url);
-    const roots = backfillCollectionRoots(command, config.default_repo_paths);
-    const collectionRoots = normalizeCollectionRoots(await collectionRootPathAliases(roots));
-    const worktreeDiscovery = await discoverBackfillWorktrees(collectionRoots, command);
-    const retryCommand = backfillDiscoveryRetryCommand(command, worktreeDiscovery);
-    const worktrees = worktreeDiscovery.worktrees;
-    const sources = selectedSources(command.source);
-    const window = backfillWindow(command, now, pairedAt);
-    await validateBackfillReachability({
-        fetchImpl: io.fetch,
-        dashboardUrl,
-        dryRun: command.dryRun,
-    });
-    const storedCursor = command.dryRun
-        ? emptyBackfillCursorState()
-        : await readBackfillCursor(paths);
-    const scopedCursor = prepareBackfillCursorForScope(storedCursor, collectionRoots, sources);
-    const cursor = scopedCursor.cursor;
-    const pointerlessTerminalSessions = await loadPointerlessTerminalSessions(paths, sources);
-    const scan = await scanBackfillSessions({
-        command,
-        homeDir: command.homeDir ?? os.homedir(),
-        worktrees,
-        collectionRoots,
-        sources,
-        window,
-        cursor,
-        pointerlessTerminalSessions,
-        now,
-    });
-    // The scan issue ledger: every write below goes through a named operation
-    // (see "Scan issue ledger" further down) instead of a bare push/sort.
-    addRepoDiscoveryIssues(scan.issues, worktreeDiscovery.incomplete_reasons);
-    sortScanIssuesByPriority(scan.issues);
-    const guards = await countReadOnlyGuards(scan.candidates);
-    scan.retryable_candidate_keys = new Set([
-        ...scan.retryable_candidate_keys,
-        ...guards.retryable_candidate_keys,
-    ]);
-    addReadOnlyGuardIssues(scan.issues, guards.counts);
-    const reasonCounts = reasonCountsFor(scan.candidates, guards.counts, scan.issues);
-    const oversizedCandidateKeys = oversizedBackfillCandidateKeys(scan.candidates);
-    return {
-        kind: "scanned",
-        now,
-        paths,
-        dashboardUrl,
-        sources,
-        window,
-        collectionRoots,
-        worktrees,
-        retryCommand,
-        scopedCursor,
-        cursor,
-        scan,
-        reasonCounts,
-        oversizedCandidateKeys,
-    };
-}
-/**
- * PLAN: given the scan, should this run actually upload anything right now?
- * `--all` without `--yes` needs interactive confirmation; `--dry-run` reports
- * what would happen and stops there. Either returns a terminal result;
- * anything else proceeds to UPLOAD.
- */
-async function planBackfillRun(command, io, ctx) {
-    const { dashboardUrl, scan, reasonCounts, retryCommand } = ctx;
-    if (command.all && !command.yes) {
-        if (!command.json) {
-            writeDryRunSummary(io, {
-                candidates: scan.candidates,
-                reasonCounts,
-                dashboardUrl,
-                dryRunOnly: false,
-            });
-        }
-        const confirmed = await confirmAllBackfill(io);
-        if (!confirmed) {
-            return {
-                kind: "result",
-                result: {
-                    ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
-                    status: "blocked",
-                    counts: {
-                        ...baseBackfillResult(command, backfillResultBaseArgs(ctx)).counts,
-                        remaining: scan.candidates.length,
-                    },
-                    failure_reason: "confirmation_declined",
-                },
-            };
-        }
-    }
-    if (command.dryRun) {
-        if (!command.json) {
-            writeDryRunSummary(io, {
-                candidates: scan.candidates,
-                reasonCounts,
-                dashboardUrl,
-                dryRunOnly: true,
-            });
-        }
-        return {
-            kind: "result",
-            result: {
-                ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
-                status: blockingScanIssues(scan.issues).length > 0 ? "partial" : "complete",
-                dry_run: true,
-                retry_command: retryCommand,
-                ...(blockingScanIssues(scan.issues).length > 0
-                    ? { failure_reason: blockingScanIssues(scan.issues)[0]?.reason }
-                    : {}),
-            },
-        };
-    }
-    return { kind: "proceed" };
-}
-/**
- * UPLOAD: sync every uploadable candidate in fixed-size batches, heartbeating
- * the backfill lock between batches, stopping early on an exhausted budget or
- * three consecutive failed batches. A candidate whose main is durably
- * oversized-skipped (BLI-2727) is accounted for, not missing — it will never
- * earn a durable pointer under the current cap, and treating it as "still
- * missing" would fail every batch it happens to share with genuinely uploaded
- * siblings, so it is excluded via `oversizedCandidateKeys` throughout.
- */
-async function uploadBackfillBatches(command, io, lock, ctx) {
-    const { worktrees, scan, oversizedCandidateKeys } = ctx;
-    const uploadable = uploadableCandidates(scan.candidates);
-    const batches = buildBackfillBatches(uploadable);
-    const rawEvidenceBudget = {
-        remainingBytes: RAW_EVIDENCE_DEFAULT_BYTE_BUDGET,
-        remainingObjects: RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET,
-    };
-    const syncResults = [];
-    let completedBatches = 0;
-    let failedBatches = 0;
-    let consecutiveFailures = 0;
-    let done = 0;
-    let failed = 0;
-    let deferred = 0;
-    let uploadedObjects = 0;
-    let uploadedChunks = 0;
-    let backfilledSessions = 0;
-    const durableCandidateKeys = new Set();
-    let blockedAt;
-    let failureReason = blockingScanIssues(scan.issues)[0]?.reason;
-    for (const [index, batch] of batches.entries()) {
-        await lock.handle.heartbeat();
-        const sync = await syncBackfillBatch({
-            command,
-            batch,
-            worktrees,
-            codexAttribution: scan.codexAttribution,
-            claudeAttribution: scan.claudeAttribution,
-            rawEvidenceBudget,
-            fetchImpl: io.fetch,
-        });
-        syncResults.push(sync);
-        done += batch.candidates.length;
-        uploadedObjects += sync.raw_evidence_uploaded_object_count;
-        uploadedChunks += sync.raw_evidence_uploaded_chunk_count;
-        failed += countSessionUploadFailures(sync);
-        deferred +=
-            sync.raw_evidence_deferred_byte_budget +
-                sync.raw_evidence_deferred_object_budget;
-        const durableInBatch = durableBackfillCandidateKeys(batch, sync);
-        for (const key of durableInBatch)
-            durableCandidateKeys.add(key);
-        backfilledSessions = durableCandidateKeys.size;
-        const missingDurableMain = batch.candidates.filter((candidate) => !durableInBatch.has(candidateCursorKey(candidate)) &&
-            !oversizedCandidateKeys.has(candidateCursorKey(candidate))).length;
-        const batchFailed = sync.status !== "uploaded" ||
-            countSessionUploadFailures(sync) > 0 ||
-            missingDurableMain > 0;
-        const batchDeferred = sync.raw_evidence_deferred_byte_budget +
-            sync.raw_evidence_deferred_object_budget >
-            0;
-        if (batchFailed) {
-            failedBatches += 1;
-            consecutiveFailures += 1;
-        }
-        else {
-            consecutiveFailures = 0;
-        }
-        if (!batchFailed && !batchDeferred) {
-            completedBatches += 1;
-        }
-        if (!command.json) {
-            writeLine(io.stdout, `Uploaded ${done}/${uploadable.length} (batch ${index + 1}/${batches.length})`);
-        }
-        await yieldToEventLoop();
-        if (batchDeferred) {
-            blockedAt = {
-                what: "raw evidence budget exhausted",
-                batch_index: index + 1,
-                batch_total: batches.length,
-                done,
-                total: uploadable.length,
-            };
-            failureReason = "deferred_budget_exhausted";
-            break;
-        }
-        if (consecutiveFailures >= BACKFILL_MAX_CONSECUTIVE_FAILURES) {
-            blockedAt = {
-                what: "consecutive upload failures",
-                batch_index: index + 1,
-                batch_total: batches.length,
-                done,
-                total: uploadable.length,
-            };
-            failureReason =
-                sync.status === "spooled"
-                    ? sync.failure_reason
-                    : missingDurableMain > 0
-                        ? "durable_session_pointer_missing"
-                        : "upload_failed";
-            break;
-        }
-    }
-    return {
-        syncResults,
-        uploadable,
-        batches,
-        completedBatches,
-        failedBatches,
-        done,
-        failed,
-        deferred,
-        uploadedObjects,
-        uploadedChunks,
-        backfilledSessions,
-        durableCandidateKeys,
-        blockedAt,
-        failureReason,
-    };
-}
-/**
- * REPORT: post the session report, record durable pointers, advance the
- * cursor through the resolved contiguous prefix, decide completion, write the
- * all-history completion marker when this run actually finished it, and
- * assemble the final result. `remaining`/`completionBlocked` deliberately
- * treat an oversized skip differently (BLI-2727): it still counts toward
- * `remaining` so the JSON output never goes silent about it, but it never
- * blocks completion on its own — every completion-gating computation below
- * excludes it explicitly via `oversizedCandidateKeys`/`blockingScanIssues`.
- */
-async function reportBackfillOutcome(command, io, ctx, upload) {
-    const { now, paths, dashboardUrl, sources, collectionRoots, worktrees, retryCommand, scopedCursor, cursor, scan, oversizedCandidateKeys, } = ctx;
-    const { syncResults, uploadable, batches, completedBatches, failedBatches, done, deferred, uploadedObjects, uploadedChunks, backfilledSessions, durableCandidateKeys, } = upload;
-    let { blockedAt, failureReason, failed } = upload;
-    const sessions = buildBackfillSessionReport({
-        candidates: scan.candidates,
-        syncResults,
-        now,
-    });
-    const reportContext = sessions.length
-        ? await ensureBackfillReportContext({
-            homeDir: command.homeDir,
-            paths,
-            collectionRoots,
-            worktrees,
-            candidates: scan.candidates,
-        })
-        : null;
-    const report = sessions.length
-        ? await postCodexSessionReport({
-            homeDir: command.homeDir,
-            repoRoot: reportContext?.repoRoot,
-            dashboardUrl,
-            sessions,
-            fetch: io.fetch,
-            now,
-        })
-        : emptyReport("no_sessions_observed");
-    const reportAcknowledged = sessions.length === 0 ||
-        (report.posted && report.recorded_count >= sessions.length);
-    if (!reportAcknowledged && !blockedAt) {
-        blockedAt = {
-            what: "session report failed",
-            batch_index: completedBatches,
-            batch_total: batches.length,
-            done,
-            total: uploadable.length,
-        };
-        failureReason ??=
-            report.posted && report.recorded_count < sessions.length
-                ? "session_report_ack_incomplete"
-                : report.reason;
-    }
-    if (reportAcknowledged && durableCandidateKeys.size > 0) {
-        await recordBackfillDurableSessionPointers({
-            paths,
-            candidates: scan.candidates,
-            syncResults,
-            now,
-        });
-    }
-    // Raw evidence durability is necessary but not sufficient: the server must
-    // also acknowledge the session attribution rows before their historical
-    // cursor positions become irreversible.
-    if (reportAcknowledged) {
-        const cursorAdvanced = advanceBackfillCursorThroughResolvedPrefix({
-            cursor,
-            candidates: scan.candidates,
-            durableCandidateKeys,
-            retryableCandidateKeys: scan.retryable_candidate_keys,
-            discoveryComplete: !scan.issues.some((issue) => issue.scope === "global"),
-            now,
-        });
-        if (cursorAdvanced)
-            await writeBackfillCursor(paths, cursor);
-    }
-    const unresolvedUploadableKeys = new Set(uploadable
-        .filter((candidate) => !durableCandidateKeys.has(candidateCursorKey(candidate)))
-        .map(candidateCursorKey));
-    // "Blocking" views exclude a deterministic oversized skip (BLI-2727): it is
-    // still unresolved (it never gets a durable pointer), but it is a permanent,
-    // labeled fact rather than something completion should wait on forever.
-    const unresolvedUploadableBlocking = [...unresolvedUploadableKeys].filter((key) => !oversizedCandidateKeys.has(key)).length;
-    const unresolvedRetryableBlocking = [...scan.retryable_candidate_keys].filter((key) => !oversizedCandidateKeys.has(key)).length;
-    const unresolvedKnownKeys = new Set([
-        ...unresolvedUploadableKeys,
-        ...scan.retryable_candidate_keys,
-    ]);
-    const unseenGlobalFailures = scan.issues
-        .filter((issue) => issue.scope === "global")
-        .reduce((total, issue) => total + issue.count, 0);
-    const reportRetryable = reportAcknowledged
-        ? 0
-        // The cursor is intentionally all-or-nothing for the report. Even
-        // chunks already accepted by the server are retried idempotently when
-        // another required chunk lacks an acknowledgement.
-        : Math.max(1, sessions.length);
-    // `remaining` is a reporting total, not a completion gate: it still counts
-    // every unresolved candidate, including oversized skips, so the JSON output
-    // never goes silent about them (BLI-2727).
-    const remaining = unresolvedKnownKeys.size +
-        scan.omitted_candidate_count +
-        unseenGlobalFailures +
-        reportRetryable;
-    failed = Math.max(failed, unresolvedUploadableBlocking);
-    const blockingIssues = blockingScanIssues(scan.issues);
-    const completionBlocked = blockingIssues.length > 0 ||
-        unresolvedUploadableBlocking > 0 ||
-        unresolvedRetryableBlocking > 0 ||
-        deferred > 0 ||
-        failed > 0 ||
-        !reportAcknowledged;
-    if (!failureReason && completionBlocked) {
-        const retryableCandidateReason = scan.candidates.find((candidate) => scan.retryable_candidate_keys.has(candidateCursorKey(candidate)) &&
-            !oversizedCandidateKeys.has(candidateCursorKey(candidate)))?.reason;
-        failureReason =
-            blockingIssues[0]?.reason ??
-                (unresolvedUploadableBlocking > 0
-                    ? "durable_session_pointer_missing"
-                    : retryableCandidateReason ?? "backfill_incomplete");
-    }
-    const status = blockedAt || completionBlocked ? "partial" : "complete";
-    // The marker is consumed by doctor/status as proof that archived history
-    // is covered. A bounded --since-days run may complete its requested
-    // window, but it is not proof of an all-history backfill.
-    if (status === "complete" && command.all) {
-        recordBackfillScanCoverage(cursor, sources, now, now);
-        await writeBackfillCursor(paths, cursor);
-        const oversizedCandidates = scan.candidates.filter((candidate) => oversizedCandidateKeys.has(candidateCursorKey(candidate)));
-        await writeBackfillCompletionMarker(paths, {
-            schema_version: "cockpit-backfill-complete.v2",
-            coverage_version: BACKFILL_COVERAGE_VERSION,
-            collection_scope_id: scopedCursor.collection_scope_id,
-            sources,
-            completed_at: now.toISOString(),
-            revalidate_after: new Date(now.getTime() + BACKFILL_COMPLETION_RECHECK_MS).toISOString(),
-            cursor,
-            ...(oversizedCandidates.length > 0
-                ? {
-                    oversized_skips: {
-                        reason: "file_too_large",
-                        count: oversizedCandidates.length,
-                        byte_sizes: oversizedCandidates.map((candidate) => candidate.byte_size),
-                    },
-                }
-                : {}),
-        });
-    }
-    return {
-        ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
-        status,
-        retry_command: retryCommand,
-        counts: {
-            ...baseBackfillResult(command, backfillResultBaseArgs(ctx)).counts,
-            backfilled: backfilledSessions,
-            failed,
-            deferred,
-            remaining,
-        },
-        batches: {
-            total: batches.length,
-            completed: completedBatches,
-            failed: failedBatches,
-        },
-        report,
-        server_acknowledged: {
-            codex_session_report_recorded_count: report.recorded_count,
-            raw_evidence_uploaded_object_count: uploadedObjects,
-            raw_evidence_uploaded_chunk_count: uploadedChunks,
-        },
-        blocked_at: blockedAt,
-        failure_reason: failureReason,
-    };
-}
-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(" ");
-}
-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}'`;
-}
-function backfillCollectionRoots(command, savedRoots) {
-    if (command.repoRoot)
-        return [path.resolve(command.repoRoot)];
-    const roots = normalizeCollectionRoots(savedRoots);
-    if (roots.length === 0) {
-        throw new Error("No saved collection roots. Run `cockpit onboard --workspace <path>` or pass `cockpit backfill --workspace <path>`.");
-    }
-    return roots;
-}
-async function discoverBackfillWorktrees(roots, command) {
-    return discoverGitWorktreesInRootsWithStatus(roots, {
-        maxDepth: command.maxDepth ?? DEFAULT_DISCOVERY_MAX_DEPTH,
-        maxWorktrees: command.maxRepos ?? DEFAULT_DISCOVERY_MAX_REPOS,
-    });
-}
-function selectedSources(source) {
-    if (source === "codex")
-        return ["codex"];
-    if (source === "claude")
-        return ["claude_code"];
-    return ["codex", "claude_code"];
-}
-function backfillWindow(command, now, pairedAt) {
-    if (command.all) {
-        return {
-            mode: "all",
-            since_days: null,
-            started_at: new Date(now.getTime() - ALL_BACKFILL_SINCE_MINUTES * 60_000)
-                .toISOString(),
-            paired_at: pairedAt.toISOString(),
-            since_minutes: ALL_BACKFILL_SINCE_MINUTES,
-        };
-    }
-    const requestedMs = now.getTime() - (command.sinceDays ?? 1) * 24 * 60 * 60_000;
-    const startedAtMs = Math.max(requestedMs, pairedAt.getTime());
-    const sinceMinutes = Math.max(1, Math.ceil((now.getTime() - startedAtMs) / 60_000));
-    return {
-        mode: "since_days",
-        since_days: command.sinceDays ?? null,
-        started_at: new Date(startedAtMs).toISOString(),
-        paired_at: pairedAt.toISOString(),
-        since_minutes: sinceMinutes,
-    };
-}
-async function validateBackfillReachability(options) {
-    if (!options.dryRun)
-        return;
-    const response = await options.fetchImpl(options.dashboardUrl, {
-        method: "HEAD",
-    });
-    if (response.status >= 500) {
-        throw new Error(`Dashboard reachability failed with HTTP ${response.status}.`);
-    }
-}
-async function scanBackfillSessions(options) {
-    const scanLimit = options.command.maxFiles ?? 10_000;
-    const codexSessionDirs = defaultCodexSessionDirs(options.homeDir);
-    const claudeProjectsDir = path.join(options.homeDir, ".claude", "projects");
-    let codexAttribution = options.sources.includes("codex")
-        ? await scanAndAttributeCodexSessions({
-            sessionsDirs: codexSessionDirs,
-            worktrees: options.worktrees,
-            now: options.now,
-            sinceMinutes: options.window.since_minutes,
-            limit: scanLimit,
-            collectionRoots: options.collectionRoots,
-        })
-        : null;
-    if (codexAttribution?.session_limit_applied) {
-        // The adapter limit is a memory guard, not permission to silently leave
-        // history undiscovered. Re-scan the exact discovered population so a
-        // user-facing --max-files cap can resume from a truthful ordering.
-        codexAttribution = await scanAndAttributeCodexSessions({
-            sessionsDirs: codexSessionDirs,
-            worktrees: options.worktrees,
-            now: options.now,
-            sinceMinutes: options.window.since_minutes,
-            limit: Math.max(scanLimit + 1, codexAttribution.discovered_file_count),
-            collectionRoots: options.collectionRoots,
-        });
-    }
-    let claudeAttribution = options.sources.includes("claude_code")
-        ? await scanAndAttributeClaudeSessions({
-            projectsDir: claudeProjectsDir,
-            worktrees: options.worktrees,
-            now: options.now,
-            sinceMinutes: options.window.since_minutes,
-            limit: scanLimit,
-            collectionRoots: options.collectionRoots,
-        })
-        : null;
-    if (claudeAttribution?.session_limit_applied) {
-        claudeAttribution = await scanAndAttributeClaudeSessions({
-            projectsDir: claudeProjectsDir,
-            worktrees: options.worktrees,
-            now: options.now,
-            sinceMinutes: options.window.since_minutes,
-            limit: Math.max(scanLimit + 1, claudeAttribution.discovered_session_count),
-            collectionRoots: options.collectionRoots,
-        });
-    }
-    const allCandidates = [
-        ...(codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
-        ...(claudeAttribution?.results.map(normalizeClaudeCandidate) ?? []),
-    ]
-        .filter((candidate) => isAfterCursor(candidate, options.cursor) ||
-        isPointerlessTerminalRetry(candidate, options.pointerlessTerminalSessions))
-        .sort((a, b) => compareBackfillCandidatesForRetry(a, b, options.pointerlessTerminalSessions));
-    const candidates = allCandidates.slice(0, options.command.maxFiles ?? Number.MAX_SAFE_INTEGER);
-    const omittedCandidateCount = allCandidates.length - candidates.length;
-    const issues = await backfillScanIssues({
-        codexAttribution,
-        claudeAttribution,
-        codexSessionDirs,
-        claudeProjectsDir,
-        candidates,
-        omittedCandidateCount,
-    });
-    return {
-        candidates,
-        codexAttribution,
-        claudeAttribution,
-        issues,
-        retryable_candidate_keys: retryableCandidateKeys(candidates),
-        omitted_candidate_count: omittedCandidateCount,
-    };
-}
-async function loadPointerlessTerminalSessions(paths, sources) {
-    const [codexCursor, claudeCursor] = await Promise.all([
-        sources.includes("codex")
-            ? readRawEvidenceCursor(paths)
-            : Promise.resolve(null),
-        sources.includes("claude_code")
-            ? readRawEvidenceCursor(paths, { filename: CLAUDE_CURSOR_FILENAME })
-            : Promise.resolve(null),
-    ]);
-    const terminalIds = (sessions) => new Set(Object.entries(sessions ?? {})
-        .filter(([, entry]) => isPointerlessTerminalCursorEntry(entry))
-        .map(([sessionId]) => sessionId));
-    const result = {
-        codex: terminalIds(codexCursor?.sessions),
-        claude_code: terminalIds(claudeCursor?.sessions),
-    };
-    const count = result.codex.size + result.claude_code.size;
-    if (count > 0) {
-        console.error("[backfill] pointer-less terminal sessions reopened", JSON.stringify({
-            count,
-            codex_count: result.codex.size,
-            claude_count: result.claude_code.size,
-        }));
-    }
-    return result;
-}
-function isPointerlessTerminalCursorEntry(entry) {
-    return (!entry.uploaded_object_key &&
-        (entry.state === "ambiguous" ||
-            entry.state === "unattributed" ||
-            entry.state === "skipped"));
-}
-function isPointerlessTerminalRetry(candidate, sessions) {
-    return sessions[candidate.source].has(candidate.session_id);
-}
-function compareBackfillCandidatesForRetry(a, b, sessions) {
-    const aRetry = isPointerlessTerminalRetry(a, sessions);
-    const bRetry = isPointerlessTerminalRetry(b, sessions);
-    if (aRetry !== bRetry)
-        return aRetry ? -1 : 1;
-    if (aRetry && bRetry) {
-        return (a.session_file_mtime_ms - b.session_file_mtime_ms ||
-            candidateCursorKey(a).localeCompare(candidateCursorKey(b)));
-    }
-    return compareBackfillCandidates(a, b);
-}
-function normalizeCodexCandidate(result) {
-    return {
-        source: "codex",
-        session_id: result.codex_session_id,
-        file_path: result.file_path,
-        state: result.state,
-        reason: result.reason,
-        signals: result.signals,
-        attribution_score: result.attribution_score,
-        path_score: result.path_score,
-        content_hash_sha256: result.content_hash_sha256,
-        byte_size: result.byte_size,
-        session_file_mtime: result.session_file_mtime,
-        session_file_mtime_ms: result.session_file_mtime_ms,
-        worktree: result.worktree,
-        cwd_basename: result.cwd_basename,
-        cwd_hash: result.cwd_hash,
-    };
-}
-function normalizeClaudeCandidate(result) {
-    return {
-        source: "claude_code",
-        session_id: result.claude_session_id,
-        file_path: result.file_path,
-        state: result.state,
-        reason: result.reason,
-        signals: result.signals,
-        attribution_score: result.attribution_score,
-        path_score: result.path_score,
-        content_hash_sha256: result.content_hash_sha256,
-        byte_size: result.byte_size,
-        session_file_mtime: result.session_file_mtime,
-        session_file_mtime_ms: result.session_file_mtime_ms,
-        worktree: result.worktree,
-        cwd_basename: result.cwd_basename,
-        cwd_hash: result.cwd_hash,
-        claude: result,
-    };
-}
-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);
-}
-function compareBackfillCandidates(a, b) {
-    return (b.session_file_mtime_ms - a.session_file_mtime_ms ||
-        candidateCursorKey(a).localeCompare(candidateCursorKey(b)));
-}
-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;
-}
-async function backfillScanIssues(options) {
-    const issues = [];
-    const add = (reason, count, scope) => {
-        if (count > 0)
-            issues.push({ reason, count, scope });
-    };
-    if (options.codexAttribution) {
-        add("codex_session_limit_applied", options.codexAttribution.session_limit_applied
-            ? Math.max(1, options.codexAttribution.discovered_file_count -
-                options.codexAttribution.scanned_file_count)
-            : 0, "global");
-        const missingTopLevelDirs = (await Promise.all(options.codexSessionDirs.map(isMissingPath))).filter(Boolean).length;
-        add("codex_directory_read_failed", Math.max(0, options.codexAttribution.directory_read_failed_count -
-            missingTopLevelDirs), "global");
-        add("codex_session_stat_failed", options.codexAttribution.stat_failed_count, "global");
-    }
-    if (options.claudeAttribution) {
-        add("claude_session_limit_applied", options.claudeAttribution.session_limit_applied
-            ? Math.max(1, options.claudeAttribution.discovered_session_count -
-                options.claudeAttribution.scanned_session_count)
-            : 0, "global");
-        const projectsDirMissing = await isMissingPath(options.claudeProjectsDir);
-        add("claude_project_dir_read_failed", Math.max(0, options.claudeAttribution.project_dir_read_failed_count -
-            (projectsDirMissing ? 1 : 0)), "global");
-        add("claude_session_stat_failed", options.claudeAttribution.session_stat_failed_count, "global");
-        add("claude_sidecar_stat_failed", options.claudeAttribution.sidecar_stat_failed_count, "global");
-        add("claude_sidecar_dir_read_failed", await countUnreadableClaudeSidecarDirs(options.candidates), "global");
-    }
-    add("backfill_max_files_applied", options.omittedCandidateCount, "selection");
-    add("candidate_file_read_failed", options.candidates.filter((candidate) => candidate.reason === "file_read_failed").length, "candidate");
-    add("candidate_worktree_unavailable", options.candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
-        candidate.worktree === null).length, "candidate");
-    add("claude_main_file_too_large", options.candidates.filter((candidate) => candidate.source === "claude_code" &&
-        candidate.claude?.main_file_oversized).length, "candidate");
-    add("claude_sidecar_limit_applied", options.candidates.reduce((total, candidate) => total + (candidate.claude?.sidecars_capped ?? 0), 0), "candidate");
-    add("claude_sidecar_file_unreadable", options.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");
-    return issues.sort((a, b) => scanIssuePriority(a.scope) - scanIssuePriority(b.scope) ||
-        a.reason.localeCompare(b.reason));
-}
-function scanIssuePriority(scope) {
-    if (scope === "global")
-        return 0;
-    if (scope === "candidate")
-        return 1;
-    return 2;
-}
-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.
- */
-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);
-}
-/** Repo discovery could not fully enumerate a root: one global issue per reason. */
-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. */
-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. */
-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",
-]);
-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";
-}
-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,
-    };
-}
-function reasonCountsFor(candidates, guardCounts, scanIssues) {
-    const counts = new Map();
-    for (const candidate of candidates)
-        increment(counts, candidate.reason);
-    for (const [reason, count] of guardCounts) {
-        counts.set(reason, Math.max(counts.get(reason) ?? 0, count));
-    }
-    for (const issue of scanIssues) {
-        counts.set(issue.reason, Math.max(counts.get(issue.reason) ?? 0, issue.count));
-    }
-    for (const required of ["file_too_large", "repo_not_on_disk"]) {
-        counts.set(required, counts.get(required) ?? 0);
-    }
-    return [...counts.entries()]
-        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
-        .map(([reason, count]) => ({
-        reason,
-        count,
-        ...reasonClassification(reason),
-    }));
-}
-function reasonClassification(reason) {
-    if (reason === "secret_like_content_guard" || reason === "secret_redaction_failed") {
-        return {
-            classification: "retryable",
-            note: "historical guard result; collector now masks and retries",
-        };
-    }
-    if (reason === "file_too_large") {
-        return {
-            classification: "retryable",
-            note: "until the evidence file cap is raised",
-        };
-    }
-    if (reason === "repo_not_on_disk") {
-        return {
-            classification: "retryable",
-            note: "repo must exist on disk",
-        };
-    }
-    if (reason === "cwd_not_a_repo") {
-        return {
-            classification: "permanent",
-            note: "cwd exists but is not a repo or folder workspace",
-        };
-    }
-    if (reason === "multiple_transcript_origins") {
-        return {
-            classification: "permanent",
-            note: "multiple transcript origins; attribution is ambiguous",
-        };
-    }
-    if (reason === "single_repo_folder_fallback") {
-        return {
-            classification: "permanent",
-            note: "uploadable single-repo folder workspace fallback",
-        };
-    }
-    if (reason === "multi_repo_folder_workspace") {
-        return {
-            classification: "permanent",
-            note: "uploadable multi-repo folder workspace fallback",
-        };
-    }
-    if (reason.startsWith("deferred_")) {
-        return {
-            classification: "retryable",
-            note: "rerun cockpit backfill to continue",
-        };
-    }
-    return {
-        classification: "retryable",
-        note: "rerun after fixing source or collector state",
-    };
-}
-function uploadableCandidates(candidates) {
-    return candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
-        candidate.worktree);
-}
-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;
-}
-async function ensureBackfillReportContext(options) {
-    const candidateWorktree = options.candidates.find((candidate) => candidate.worktree)?.worktree;
-    const representative = candidateWorktree ?? options.worktrees[0] ?? null;
-    // A deleted repo or an approved folder workspace can legitimately produce
-    // report-only rows with no current git worktree. Use the exact approved root
-    // as a synthetic local context instead of falling through to process.cwd().
-    const repoRoot = representative?.repo_root ??
-        options.collectionRoots[0] ??
-        process.cwd();
-    try {
-        await readLocalWorkContextForRepo(options.paths, repoRoot);
-    }
-    catch {
-        // Reading it can legitimately fail — there is no context yet, which is
-        // precisely why the next line creates one. That read is a probe and stays
-        // silent; the CREATE is the branch that has to speak (BLI-3238).
-        await startLocalWorkContext({
-            homeDir: options.homeDir,
-            repoRoot,
-            branch: representative?.branch,
-        }).catch((error) => {
-            // Context creation is best-effort here: postCodexSessionReport converts
-            // a remaining local-context failure into a retryable report reason. But
-            // that reason is `collector_not_ready`, which points the operator at
-            // setup rather than at whatever actually failed here.
-            console.error("[cockpit-backfill] could not start a local work context for the batch", JSON.stringify({
-                reason: "work_context_start_failed",
-                ...describeError(error),
-            }));
-        });
-    }
-    return { repoRoot };
-}
-async function syncBackfillBatch(options) {
-    const syncOptions = {
-        homeDir: options.command.homeDir,
-        repoRoot: options.batch.worktree.repo_root,
-        worktreeInventory: worktreeInventoryForRepo(options.batch.worktree, options.worktrees),
-        codexSessionFiles: options.batch.candidates
-            .filter((candidate) => candidate.source === "codex")
-            .map((candidate) => ({
-            local_path: candidate.file_path,
-            codex_session_id: candidate.session_id,
-        })),
-        codexAttributionScan: options.codexAttribution ?? undefined,
-        claudeSessionFiles: options.batch.candidates
-            .filter((candidate) => candidate.source === "claude_code")
-            .map((candidate) => ({
-            local_path: candidate.file_path,
-            claude_session_id: candidate.session_id,
-            main_file_oversized: Boolean(candidate.claude?.main_file_oversized),
-            skip_main: false,
-            sidecar_files: candidate.claude?.sidecar_files
-                .filter((sidecar) => !sidecar.skipped_reason)
-                .map((sidecar) => ({ local_path: sidecar.local_path })) ?? [],
-        })),
-        claudeAttributionScan: options.claudeAttribution ?? undefined,
-        rawEvidenceBudget: options.rawEvidenceBudget,
-        // `cockpit backfill` is only ever an operator asking — by hand, through
-        // onboarding, through doctor, or by running the retry command Cockpit
-        // printed. The delivery-backoff window is the scheduler's cadence, so it
-        // does not gate this pass: honouring it here made the retry that follows a
-        // failed commit a 15-minute no-op that reported
-        // `durable_session_pointer_missing` and never named the hold (BLI-3118).
-        evidenceDeliveryMode: "operator_retry",
-        fetch: options.fetchImpl,
-    };
-    try {
-        return await syncLocalAmbientEnvelope(syncOptions);
-    }
-    catch (error) {
-        if (error instanceof LocalUploadBlockedError &&
-            error.blocker === "missing_context") {
-            await startLocalWorkContext({
-                homeDir: options.command.homeDir,
-                repoRoot: options.batch.worktree.repo_root,
-                branch: options.batch.worktree.branch,
-            });
-            return await syncLocalAmbientEnvelope(syncOptions);
-        }
-        throw error;
-    }
-}
-/** Exported for the BLI-3272 regression test; not part of the CLI surface. */
-export function buildBackfillSessionReport(options) {
-    const uploadByKey = new Map();
-    // BLI-2107: an outcome that names a failure but has no pointer used to be
-    // dropped on the floor here, taking its reason with it.
-    const noUploadReasonBySessionId = new Map();
-    for (const sync of options.syncResults) {
-        if (sync.status !== "uploaded")
-            continue;
-        for (const outcome of sync.raw_evidence_outcomes) {
-            if (!outcome.codex_session_id)
-                continue;
-            const source = outcome.kind === "claude_jsonl"
-                ? "claude_code"
-                : outcome.kind === "codex_jsonl"
-                    ? "codex"
-                    : null;
-            if (!source)
-                continue;
-            if (!outcome.raw_evidence_pointer_id) {
-                if (outcome.reason) {
-                    noUploadReasonBySessionId.set(outcome.codex_session_id, outcome.reason);
-                }
-                continue;
-            }
-            uploadByKey.set(`${source}:${outcome.codex_session_id}`, {
-                upload_state: outcome.upload_state,
-                raw_evidence_pointer_id: outcome.raw_evidence_pointer_id,
-                reason: outcome.reason,
-            });
-        }
-    }
-    const bestByKey = new Map();
-    for (const candidate of options.candidates) {
-        const key = `${candidate.source}:${candidate.session_id}`;
-        const existing = bestByKey.get(key);
-        if (!existing || rank(candidate.state) > rank(existing.state)) {
-            bestByKey.set(key, candidate);
-        }
-        else if (existing &&
-            rank(candidate.state) === rank(existing.state) &&
-            candidate.session_file_mtime_ms > existing.session_file_mtime_ms) {
-            bestByKey.set(key, candidate);
-        }
-    }
-    return [...bestByKey.values()].map((candidate) => {
-        const upload = uploadByKey.get(`${candidate.source}:${candidate.session_id}`);
-        return {
-            codex_session_id: candidate.session_id,
-            source: candidate.source,
-            observed_at: options.now.toISOString(),
-            attribution_state: candidate.state,
-            attribution_reason: candidate.reason,
-            attribution_score: candidate.attribution_score,
-            path_score: candidate.path_score,
-            signals: candidate.signals,
-            ...(candidate.content_hash_sha256
-                ? { session_file_hash_sha256: candidate.content_hash_sha256 }
-                : {}),
-            session_file_byte_size: candidate.byte_size,
-            session_file_mtime: candidate.session_file_mtime,
-            ...(candidate.worktree
-                ? {
-                    repo_fingerprint: candidate.worktree.repo_fingerprint,
-                    worktree_fingerprint: candidate.worktree.worktree_fingerprint,
-                    repo_label: candidate.worktree.repo_label,
-                    branch: candidate.worktree.branch,
-                }
-                : {}),
-            ...(candidate.cwd_basename ? { cwd_basename: candidate.cwd_basename } : {}),
-            ...(candidate.cwd_hash ? { cwd_hash: candidate.cwd_hash } : {}),
-            ...(upload
-                ? {
-                    raw_evidence_pointer_id: upload.raw_evidence_pointer_id,
-                    upload_state: upload.upload_state,
-                    ...(upload.upload_state === "upload_failed"
-                        ? { upload_reason: upload.reason ?? NO_UPLOAD_ATTEMPT_RECORDED }
-                        : {}),
-                }
-                : isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null)
-                    ? {
-                        upload_state: "not_uploaded",
-                        // BLI-2107: same rule as live sync — an attributed session with
-                        // no pointer always says why, even when the answer is that this
-                        // path never recorded one.
-                        upload_reason: noUploadReasonBySessionId.get(candidate.session_id) ??
-                            NO_UPLOAD_ATTEMPT_RECORDED,
-                    }
-                    : {
-                        // BLI-3272: and the refused-attribution branch says why too. Same
-                        // NULL/NULL hole as live sync, same fix — backfill is the path
-                        // that revisits old sessions, so leaving it silent would keep
-                        // rewriting the very rows this ticket found.
-                        upload_state: "not_uploaded",
-                        upload_reason: noUploadReasonBySessionId.get(candidate.session_id) ??
-                            notUploadableAttributionStateReason(candidate.reason),
-                    }),
-        };
-    });
-}
-function rank(state) {
-    switch (state) {
-        case "attributed":
-            return 5;
-        case "attributed_fallback":
-            return 4;
-        case "ambiguous":
-            return 3;
-        case "unattributed":
-            return 2;
-        case "skipped":
-            return 1;
-        default:
-            return 0;
-    }
-}
-function durableBackfillCandidateKeys(batch, sync) {
-    const durable = new Set();
-    if (sync.status !== "uploaded")
-        return durable;
-    if (sync.raw_evidence_deferred_byte_budget > 0 ||
-        sync.raw_evidence_deferred_object_budget > 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 = 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);
-    }
-    for (const candidate of batch.candidates) {
-        const summary = outcomesBySession.get(`${candidate.source}:${candidate.session_id}`);
-        const expectedSidecars = candidate.source === "claude_code"
-            ? (candidate.claude?.sidecar_files.filter((sidecar) => !sidecar.skipped_reason).length ?? 0)
-            : 0;
-        if (summary &&
-            !summary.failed &&
-            summary.durableMainCount > 0 &&
-            summary.durableSidecarCount >= expectedSidecars) {
-            durable.add(candidateCursorKey(candidate));
-        }
-    }
-    return durable;
-}
-async function recordBackfillDurableSessionPointers(options) {
-    const durableObjectBySession = new Map();
-    for (const sync of options.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);
-        }
-    }
-    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];
-            if (!objectKey || !prior || prior.uploaded_object_key)
-                continue;
-            cursor.sessions[candidate.session_id] = {
-                ...prior,
-                file_hash_sha256: candidate.content_hash_sha256,
-                file_mtime_ms: candidate.session_file_mtime_ms,
-                byte_size: candidate.byte_size,
-                byte_offset: candidate.byte_size,
-                state: candidate.state,
-                reason: candidate.reason,
-                worktree_fingerprint: candidate.worktree?.worktree_fingerprint ?? null,
-                uploaded_object_key: objectKey,
-                uploaded_at: options.now.toISOString(),
-                uploaded_byte_size: candidate.byte_size,
-                last_seen_at: options.now.toISOString(),
-            };
-            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 }));
-    }
-}
-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;
-}
-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;
-}
-function worktreeInventoryForRepo(current, worktrees) {
-    return worktrees
-        .filter((worktree) => worktree.repo_fingerprint
-        ? worktree.repo_fingerprint === current.repo_fingerprint
-        : worktree.repo_label === current.repo_label)
-        .map((worktree) => ({
-        repo: worktree.repo_root,
-        repo_label: worktree.repo_label,
-        repo_fingerprint: worktree.repo_fingerprint,
-        repo_origin_url: worktree.repo_origin_url ?? undefined,
-        head_sha: worktree.head_sha ?? undefined,
-        worktree_label: worktree.worktree_label,
-        worktree_fingerprint: worktree.worktree_fingerprint,
-        worktree_is_primary: worktree.worktree_is_primary,
-        branch: worktree.branch,
-    }));
-}
-function baseBackfillResult(command, options) {
-    const states = countBy(options.scan.candidates, (candidate) => candidate.state);
-    const uploadable = uploadableCandidates(options.scan.candidates);
-    const perSource = {
-        codex: sourceCounts("codex", options.scan),
-        claude_code: sourceCounts("claude_code", options.scan),
-    };
-    return {
-        status: "complete",
-        dry_run: command.dryRun,
-        dashboard_url: options.dashboardUrl,
-        verify_url: `${options.dashboardUrl}/my-work`,
-        sources: options.sources,
-        window: options.window,
-        counts: {
-            total: options.scan.candidates.length,
-            uploadable: uploadable.length,
-            backfilled: 0,
-            skipped: options.scan.candidates.length - uploadable.length,
-            failed: 0,
-            deferred: 0,
-            remaining: 0,
-            states,
-            reasons: options.reasonCounts,
-            per_source: perSource,
-        },
-        batches: {
-            total: Math.ceil(uploadable.length / BACKFILL_UPLOAD_BATCH_SESSIONS),
-            completed: 0,
-            failed: 0,
-        },
-        resume_cursor: options.cursor,
-        retry_command: backfillRetryCommand(command),
-        report: emptyReport("not_posted"),
-        server_acknowledged: {
-            codex_session_report_recorded_count: 0,
-            raw_evidence_uploaded_object_count: 0,
-            raw_evidence_uploaded_chunk_count: 0,
-        },
-    };
-}
-function blockedBackfillResult(command, options) {
-    return {
-        status: "blocked",
-        dry_run: command.dryRun,
-        dashboard_url: options.dashboardUrl,
-        verify_url: `${options.dashboardUrl}/my-work`,
-        sources: selectedSources(command.source),
-        window: {
-            mode: command.all ? "all" : "since_days",
-            since_days: command.sinceDays ?? null,
-            started_at: options.now.toISOString(),
-            paired_at: options.now.toISOString(),
-            since_minutes: 0,
-        },
-        counts: {
-            total: 0,
-            uploadable: 0,
-            backfilled: 0,
-            skipped: 0,
-            failed: 0,
-            deferred: 0,
-            remaining: 0,
-            states: {},
-            reasons: [],
-            per_source: {
-                codex: emptySourceCounts(),
-                claude_code: emptySourceCounts(),
-            },
-        },
-        batches: { total: 0, completed: 0, failed: 0 },
-        resume_cursor: options.cursor,
-        retry_command: backfillRetryCommand(command),
-        report: emptyReport("not_posted"),
-        server_acknowledged: {
-            codex_session_report_recorded_count: 0,
-            raw_evidence_uploaded_object_count: 0,
-            raw_evidence_uploaded_chunk_count: 0,
-        },
-        failure_reason: options.reason,
-    };
-}
-function sourceCounts(source, scan) {
-    const candidates = scan.candidates.filter((candidate) => candidate.source === source);
-    const scanned = source === "codex"
-        ? (scan.codexAttribution?.scanned_file_count ?? 0)
-        : (scan.claudeAttribution?.scanned_session_count ?? 0);
-    return {
-        scanned,
-        selected: candidates.length,
-        uploadable: uploadableCandidates(candidates).length,
-        states: countBy(candidates, (candidate) => candidate.state),
-    };
-}
-function emptySourceCounts() {
-    return { scanned: 0, selected: 0, uploadable: 0, states: {} };
-}
-function emptyReport(reason) {
-    return {
-        posted: false,
-        reason,
-        chunk_count: 0,
-        recorded_count: 0,
-        failed_count: 0,
-        chunks: [],
-    };
-}
-function countBy(items, keyOf) {
-    const counts = {};
-    for (const item of items) {
-        const key = keyOf(item);
-        counts[key] = (counts[key] ?? 0) + 1;
-    }
-    return counts;
-}
-function increment(counts, key) {
-    counts.set(key, (counts.get(key) ?? 0) + 1);
-}
-function writeDryRunSummary(io, options) {
-    const uploadable = uploadableCandidates(options.candidates);
-    writeLine(io.stdout, `${options.dryRunOnly ? "DRY-RUN" : "Review"}: ${options.candidates.length} session(s), ${uploadable.length} uploadable, ${options.candidates.length - uploadable.length} skipped.`);
-    writeReasonTable(io, options.reasonCounts);
-    if (options.dryRunOnly) {
-        writeLine(io.stdout, "DRY-RUN: wrote nothing (no cursor, marker, report, or upload).");
-    }
-    writeLine(io.stdout, `Verify after upload: ${options.dashboardUrl}/my-work`);
-}
-function writeHumanBackfillResult(result, io) {
-    if (result.status === "complete") {
-        writeLine(io.stdout, `PASS: ${result.counts.backfilled} backfilled, ${result.counts.skipped} skipped (table). Verify: ${result.verify_url}`);
-        writeReasonTable(io, result.counts.reasons);
-        return;
-    }
-    if (result.status === "partial") {
-        const at = result.blocked_at;
-        if (at) {
-            writeLine(io.stderr, `BLOCKED: ${at.what} at batch ${at.batch_index}/${at.batch_total}, ${at.done}/${at.total} done`);
-        }
-        writeLine(io.stderr, `Failure: ${result.failure_reason ?? "partial_backfill"}`);
-        writeLine(io.stderr, `Retry: ${result.retry_command}`);
-        writeLine(io.stderr, `Stopped: ${result.counts.remaining} remaining — rerun cockpit backfill to continue`);
-        writeReasonTable(io, result.counts.reasons);
-        return;
-    }
-    const at = result.blocked_at;
-    if (at) {
-        writeLine(io.stderr, `BLOCKED: ${at.what} at batch ${at.batch_index}/${at.batch_total}, ${at.done}/${at.total} done`);
-    }
-    else {
-        writeLine(io.stderr, "BLOCKED: backfill could not run.");
-    }
-    writeLine(io.stderr, `Failure: ${result.failure_reason ?? "no_sessions"}`);
-    writeLine(io.stderr, `Retry: ${result.retry_command}`);
-}
-function writeReasonTable(io, reasons) {
-    if (reasons.length === 0)
-        return;
-    writeLine(io.stdout, "Skip/reason table:");
-    for (const reason of reasons) {
-        writeLine(io.stdout, `- ${reason.reason}: ${reason.count} (${reason.classification}; ${reason.note})`);
-    }
-}
-async function confirmAllBackfill(io) {
-    const answer = await readLine(io, "Proceed with --all backfill upload? [y/N] ");
-    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
-}
-async function readLine(io, prompt) {
-    io.stdout.write(prompt);
-    io.stdin.setEncoding("utf8");
-    return new Promise((resolve) => {
-        const onData = (chunk) => {
-            io.stdin.removeListener("data", onData);
-            io.stdin.pause();
-            resolve(chunk);
-        };
-        io.stdin.resume();
-        io.stdin.on("data", onData);
-    });
-}
-function isInteractiveStdin(io) {
-    return Boolean(io.stdin.isTTY);
-}
-function parseRequiredDate(value, label) {
-    const date = new Date(value);
-    if (!Number.isFinite(date.getTime())) {
-        throw new Error(`Collector session ${label} is invalid.`);
-    }
-    return date;
-}
-function normalizeDashboardUrl(value) {
-    return value.trim().replace(/\/+$/, "");
-}
-function writeLine(stream, text) {
-    stream.write(`${text}\n`);
-}
-function yieldToEventLoop() {
-    return new Promise((resolve) => setTimeout(resolve, 0));
 }