@bli-cockpit/cli 0.2.47 → 0.2.49

package/dist/commands/backfill.js

@@ -1,3 +1,25 @@
+/**
+ * `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 function in this file belongs to exactly one of them:
+ *
+ *   SCAN    resolveBackfillScope   paired? which roots, stores and window
+ *           scanBackfillSessions   read both stores into candidates
+ *           auditScannedCandidates census what could not be accounted for
+ *   PLAN    planBackfillRun        confirm `--all`, or answer a `--dry-run`
+ *   UPLOAD  uploadBackfillBatches  sync in batches under the shared lock
+ *   REPORT  reportBackfillOutcome  post, checkpoint, decide, assemble
+ *
+ * Two rules run through all four 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 { 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";
@@ -75,19 +97,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 +112,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
@@ -129,6 +133,26 @@ export async function runBackfill(command, io) {
         await lock.handle.release();
     }
 }
+/**
+ * Someone else is already holding a lock this run needs. Reported as blocked
+ * with nothing done rather than as a failure — the scan is still valid, and
+ * the retry command in it works as soon as the other run finishes.
+ */
+function lockHeldResult(command, scanned, blocker) {
+    return {
+        ...baseBackfillResult(command, backfillResultBaseArgs(scanned)),
+        status: "blocked",
+        retry_command: scanned.retryCommand,
+        failure_reason: blocker.failureReason,
+        blocked_at: {
+            what: blocker.what,
+            batch_index: 0,
+            batch_total: 0,
+            done: 0,
+            total: scanned.scan.candidates.length,
+        },
+    };
+}
 /** The `{now, dashboardUrl, sources, window, cursor, scan, reasonCounts}` bag every `baseBackfillResult` call needs. */
 function backfillResultBaseArgs(ctx) {
     return {
@@ -148,34 +172,19 @@ function backfillResultBaseArgs(ctx) {
  */
 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") {
+    const scope = await resolveBackfillScope(command, io, now, paths);
+    if (scope.kind === "not_paired") {
         return {
             kind: "blocked",
             result: blockedBackfillResult(command, {
                 now,
-                dashboardUrl: sessionFile.dashboard_url ?? config.dashboard_url,
+                dashboardUrl: scope.dashboardUrl,
                 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 { collectionRoots, sources, worktreeDiscovery } = scope;
     const storedCursor = command.dryRun
         ? emptyBackfillCursorState()
         : await readBackfillCursor(paths);
@@ -185,43 +194,88 @@ async function scanBackfillRun(command, io, now) {
     const scan = await scanBackfillSessions({
         command,
         homeDir: command.homeDir ?? os.homedir(),
-        worktrees,
+        worktrees: worktreeDiscovery.worktrees,
         collectionRoots,
         sources,
-        window,
+        window: scope.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);
+    const reasonCounts = await auditScannedCandidates(scan, worktreeDiscovery.incomplete_reasons);
     return {
         kind: "scanned",
         now,
         paths,
-        dashboardUrl,
+        dashboardUrl: scope.dashboardUrl,
         sources,
-        window,
+        window: scope.window,
         collectionRoots,
-        worktrees,
-        retryCommand,
+        worktrees: worktreeDiscovery.worktrees,
+        retryCommand: scope.retryCommand,
         scopedCursor,
         cursor,
         scan,
         reasonCounts,
-        oversizedCandidateKeys,
+        oversizedCandidateKeys: oversizedBackfillCandidateKeys(scan.candidates),
     };
 }
+/**
+ * Answers the four questions every later stage assumes: is this collector
+ * paired, which approved roots and repos does it cover, which stores and how
+ * far back was it asked for, and — on a dry run — can it even reach the
+ * dashboard. Nothing here reads a session; a machine that is not paired stops
+ * before any history is touched.
+ */
+async function resolveBackfillScope(command, io, now, paths) {
+    const config = await readLocalCollectorConfig(paths);
+    const sessionFile = await readLocalCollectorSessionFile(paths);
+    const session = await readLocalSessionReference(paths);
+    if (session.session_state !== "valid") {
+        return {
+            kind: "not_paired",
+            dashboardUrl: sessionFile.dashboard_url ?? config.dashboard_url,
+        };
+    }
+    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 window = backfillWindow(command, now, pairedAt);
+    await validateBackfillReachability({
+        fetchImpl: io.fetch,
+        dashboardUrl,
+        dryRun: command.dryRun,
+    });
+    return {
+        kind: "ready",
+        dashboardUrl,
+        collectionRoots,
+        worktreeDiscovery,
+        retryCommand: backfillDiscoveryRetryCommand(command, worktreeDiscovery),
+        sources: selectedSources(command.source),
+        window,
+    };
+}
+/**
+ * Finishes the scan's ledger before anything acts on it: adds what repo
+ * discovery could not enumerate, reads every candidate file once to find the
+ * ones this machine cannot actually deliver, and folds all of it into the
+ * reason table the operator sees. Mutates `scan` in place — it is the one
+ * owner of `issues` and `retryable_candidate_keys` — and returns the table.
+ */
+async function auditScannedCandidates(scan, discoveryIncompleteReasons) {
+    addRepoDiscoveryIssues(scan.issues, discoveryIncompleteReasons);
+    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);
+    return reasonCountsFor(scan.candidates, guards.counts, scan.issues);
+}
 /**
  * PLAN: given the scan, should this run actually upload anything right now?
  * `--all` without `--yes` needs interactive confirmation; `--dry-run` reports
@@ -229,7 +283,7 @@ async function scanBackfillRun(command, io, now) {
  * anything else proceeds to UPLOAD.
  */
 async function planBackfillRun(command, io, ctx) {
-    const { dashboardUrl, scan, reasonCounts, retryCommand } = ctx;
+    const { dashboardUrl, scan, reasonCounts } = ctx;
     if (command.all && !command.yes) {
         if (!command.json) {
             writeDryRunSummary(io, {
@@ -241,18 +295,7 @@ async function planBackfillRun(command, io, ctx) {
         }
         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",
-                },
-            };
+            return { kind: "result", result: confirmationDeclinedResult(command, ctx) };
         }
     }
     if (command.dryRun) {
@@ -264,21 +307,37 @@ async function planBackfillRun(command, io, ctx) {
                 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: "result", result: dryRunResult(command, ctx) };
     }
     return { kind: "proceed" };
 }
+/** The operator saw the `--all` review and said no. Nothing was written; everything remains. */
+function confirmationDeclinedResult(command, ctx) {
+    const base = baseBackfillResult(command, backfillResultBaseArgs(ctx));
+    return {
+        ...base,
+        status: "blocked",
+        counts: { ...base.counts, remaining: ctx.scan.candidates.length },
+        failure_reason: "confirmation_declined",
+    };
+}
+/**
+ * What a `--dry-run` would have done. It completes unless the scan itself hit
+ * something blocking, because a dry run that reports "complete" over a scan
+ * that could not see all the history would be the confident wrong answer.
+ */
+function dryRunResult(command, ctx) {
+    const blockingIssues = blockingScanIssues(ctx.scan.issues);
+    return {
+        ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
+        status: blockingIssues.length > 0 ? "partial" : "complete",
+        dry_run: true,
+        retry_command: ctx.retryCommand,
+        ...(blockingIssues.length > 0
+            ? { failure_reason: blockingIssues[0]?.reason }
+            : {}),
+    };
+}
 /**
  * UPLOAD: sync every uploadable candidate in fixed-size batches, heartbeating
  * the backfill lock between batches, stopping early on an exhausted budget or
@@ -289,116 +348,124 @@ async function planBackfillRun(command, io, ctx) {
  * 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 uploadable = uploadableCandidates(ctx.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;
+    const tally = emptyUploadTally();
     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;
+    let failureReason = blockingScanIssues(ctx.scan.issues)[0]?.reason;
+    const stoppedAt = (what, index) => ({
+        what,
+        batch_index: index + 1,
+        batch_total: batches.length,
+        done: tally.done,
+        total: uploadable.length,
+    });
     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;
-        }
+        const outcome = await uploadOneBackfillBatch(command, io, ctx, batch, rawEvidenceBudget);
+        foldBatchIntoTally(tally, batch, outcome);
+        consecutiveFailures = outcome.failed ? consecutiveFailures + 1 : 0;
         if (!command.json) {
-            writeLine(io.stdout, `Uploaded ${done}/${uploadable.length} (batch ${index + 1}/${batches.length})`);
+            writeLine(io.stdout, `Uploaded ${tally.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,
-            };
+        if (outcome.deferred) {
+            blockedAt = stoppedAt("raw evidence budget exhausted", index);
             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";
+            blockedAt = stoppedAt("consecutive upload failures", index);
+            failureReason = failedBatchReason(outcome.sync, outcome.missingDurableMain);
             break;
         }
     }
+    return { ...tally, uploadable, batches, blockedAt, failureReason };
+}
+/** Uploads one batch and judges it; every judgement here is a named predicate. */
+async function uploadOneBackfillBatch(command, io, ctx, batch, rawEvidenceBudget) {
+    const sync = await syncBackfillBatch({
+        command,
+        batch,
+        worktrees: ctx.worktrees,
+        codexAttribution: ctx.scan.codexAttribution,
+        claudeAttribution: ctx.scan.claudeAttribution,
+        rawEvidenceBudget,
+        fetchImpl: io.fetch,
+    });
+    const durableInBatch = durableBackfillCandidateKeys(batch, sync);
+    const missingDurableMain = countMissingDurableMains(batch, durableInBatch, ctx.oversizedCandidateKeys);
     return {
-        syncResults,
-        uploadable,
-        batches,
-        completedBatches,
-        failedBatches,
-        done,
-        failed,
-        deferred,
-        uploadedObjects,
-        uploadedChunks,
-        backfilledSessions,
-        durableCandidateKeys,
-        blockedAt,
-        failureReason,
+        sync,
+        durableInBatch,
+        missingDurableMain,
+        failed: didBatchFail(sync, missingDurableMain),
+        deferred: deferredEvidenceCount(sync) > 0,
+    };
+}
+function emptyUploadTally() {
+    return {
+        syncResults: [],
+        completedBatches: 0,
+        failedBatches: 0,
+        done: 0,
+        failed: 0,
+        deferred: 0,
+        uploadedObjects: 0,
+        uploadedChunks: 0,
+        backfilledSessions: 0,
+        durableCandidateKeys: new Set(),
     };
 }
+function foldBatchIntoTally(tally, batch, outcome) {
+    tally.syncResults.push(outcome.sync);
+    tally.done += batch.candidates.length;
+    tally.uploadedObjects += outcome.sync.raw_evidence_uploaded_object_count;
+    tally.uploadedChunks += outcome.sync.raw_evidence_uploaded_chunk_count;
+    tally.failed += countSessionUploadFailures(outcome.sync);
+    tally.deferred += deferredEvidenceCount(outcome.sync);
+    for (const key of outcome.durableInBatch)
+        tally.durableCandidateKeys.add(key);
+    tally.backfilledSessions = tally.durableCandidateKeys.size;
+    if (outcome.failed)
+        tally.failedBatches += 1;
+    if (!outcome.failed && !outcome.deferred)
+        tally.completedBatches += 1;
+}
+/** Evidence the server accepted the batch for but had no budget left to store. */
+function deferredEvidenceCount(sync) {
+    return (sync.raw_evidence_deferred_byte_budget +
+        sync.raw_evidence_deferred_object_budget);
+}
+/**
+ * Candidates in this batch that still owe a durable main transcript. An
+ * oversized skip is excluded (BLI-2727): it can never earn a pointer under the
+ * current cap, and counting it here would fail every batch it happens to share
+ * with genuinely uploaded siblings.
+ */
+function countMissingDurableMains(batch, durableInBatch, oversizedCandidateKeys) {
+    return batch.candidates.filter((candidate) => !durableInBatch.has(candidateCursorKey(candidate)) &&
+        !oversizedCandidateKeys.has(candidateCursorKey(candidate))).length;
+}
+/** A batch counts as failed if it did not upload, lost a session, or left one pointerless. */
+function didBatchFail(sync, missingDurableMain) {
+    return (sync.status !== "uploaded" ||
+        countSessionUploadFailures(sync) > 0 ||
+        missingDurableMain > 0);
+}
+/** Names which of the three failure shapes ended the run, most specific first. */
+function failedBatchReason(sync, missingDurableMain) {
+    if (sync.status === "spooled")
+        return sync.failure_reason;
+    if (missingDurableMain > 0)
+        return "durable_session_pointer_missing";
+    return "upload_failed";
+}
 /**
  * REPORT: post the session report, record durable pointers, advance the
  * cursor through the resolved contiguous prefix, decide completion, write the
@@ -410,107 +477,150 @@ async function uploadBackfillBatches(command, io, lock, ctx) {
  * 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;
+    let { blockedAt, failureReason } = upload;
+    const posted = await postBackfillSessionReport(command, io, ctx, upload);
+    if (!posted.acknowledged && !blockedAt) {
+        blockedAt = sessionReportStopPoint(upload);
+        failureReason ??= sessionReportFailureReason(posted);
+    }
+    if (posted.acknowledged) {
+        await checkpointResolvedBackfillProgress(ctx, upload);
+    }
+    const completion = summarizeBackfillCompletion({
+        ctx,
+        upload,
+        posted,
+        stoppedEarly: Boolean(blockedAt),
+        failureReason,
+    });
+    if (completion.status === "complete" && command.all) {
+        await writeAllHistoryCompletionMarker(ctx);
+    }
+    return assembleBackfillResult({
+        command,
+        ctx,
+        upload,
+        posted,
+        completion,
+        blockedAt,
+    });
+}
+/**
+ * Tells the server what this run observed about every session, uploaded or
+ * not. Its acknowledgement — not raw-evidence durability alone — is what makes
+ * a historical cursor position irreversible, so the caller gates the whole
+ * checkpoint on the `acknowledged` flag returned here.
+ */
+async function postBackfillSessionReport(command, io, ctx, upload) {
     const sessions = buildBackfillSessionReport({
-        candidates: scan.candidates,
-        syncResults,
-        now,
+        candidates: ctx.scan.candidates,
+        syncResults: upload.syncResults,
+        now: ctx.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,
+    if (sessions.length === 0) {
+        return {
             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,
+            report: emptyReport("no_sessions_observed"),
+            acknowledged: true,
         };
-        failureReason ??=
-            report.posted && report.recorded_count < sessions.length
-                ? "session_report_ack_incomplete"
-                : report.reason;
     }
-    if (reportAcknowledged && durableCandidateKeys.size > 0) {
+    const reportContext = await ensureBackfillReportContext({
+        homeDir: command.homeDir,
+        paths: ctx.paths,
+        collectionRoots: ctx.collectionRoots,
+        worktrees: ctx.worktrees,
+        candidates: ctx.scan.candidates,
+    });
+    const report = await postCodexSessionReport({
+        homeDir: command.homeDir,
+        repoRoot: reportContext.repoRoot,
+        dashboardUrl: ctx.dashboardUrl,
+        sessions,
+        fetch: io.fetch,
+        now: ctx.now,
+    });
+    return {
+        sessions,
+        report,
+        acknowledged: report.posted && report.recorded_count >= sessions.length,
+    };
+}
+/** Where a run that uploaded cleanly but could not file its report stopped. */
+function sessionReportStopPoint(upload) {
+    return {
+        what: "session report failed",
+        batch_index: upload.completedBatches,
+        batch_total: upload.batches.length,
+        done: upload.done,
+        total: upload.uploadable.length,
+    };
+}
+/** A partial acknowledgement is its own reason; otherwise the post's own. */
+function sessionReportFailureReason(posted) {
+    return posted.report.posted &&
+        posted.report.recorded_count < posted.sessions.length
+        ? "session_report_ack_incomplete"
+        : posted.report.reason;
+}
+/**
+ * Makes this run's progress durable once the server has acknowledged it:
+ * session pointers first, then the backfill cursor through the contiguous
+ * resolved prefix. Raw-evidence durability is necessary but not sufficient —
+ * both writes wait on the report acknowledgement, because a cursor advanced
+ * past a session the server never recorded can never be walked back.
+ */
+async function checkpointResolvedBackfillProgress(ctx, upload) {
+    const { paths, scan, cursor, now } = ctx;
+    if (upload.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"),
+            syncResults: upload.syncResults,
             now,
         });
-        if (cursorAdvanced)
-            await writeBackfillCursor(paths, cursor);
     }
-    const unresolvedUploadableKeys = new Set(uploadable
-        .filter((candidate) => !durableCandidateKeys.has(candidateCursorKey(candidate)))
+    const cursorAdvanced = advanceBackfillCursorThroughResolvedPrefix({
+        cursor,
+        candidates: scan.candidates,
+        durableCandidateKeys: upload.durableCandidateKeys,
+        retryableCandidateKeys: scan.retryable_candidate_keys,
+        discoveryComplete: !scan.issues.some((issue) => issue.scope === "global"),
+        now,
+    });
+    if (cursorAdvanced)
+        await writeBackfillCursor(paths, cursor);
+}
+/**
+ * Answers "is this backfill finished, and if not, why not" as pure arithmetic
+ * over what the scan found and what the upload resolved — no side effects, so
+ * the one place BLI-2727's oversized-skip rule is applied is readable in full.
+ * `remaining` is a reporting total that still counts oversized skips so the
+ * JSON never goes silent about them; every `*Blocking` count excludes them,
+ * because a file too large for the current cap is a permanent labeled fact
+ * that no rerun can resolve and completion must not wait on forever.
+ */
+function summarizeBackfillCompletion(options) {
+    const { scan, oversizedCandidateKeys } = options.ctx;
+    const { upload, posted } = options;
+    const unresolvedUploadableKeys = new Set(upload.uploadable
+        .filter((candidate) => !upload.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 remaining = countRemainingHistory({
+        scan,
+        unresolvedUploadableKeys,
+        posted,
+    });
+    const failed = Math.max(upload.failed, unresolvedUploadableBlocking);
     const blockingIssues = blockingScanIssues(scan.issues);
     const completionBlocked = blockingIssues.length > 0 ||
         unresolvedUploadableBlocking > 0 ||
         unresolvedRetryableBlocking > 0 ||
-        deferred > 0 ||
+        upload.deferred > 0 ||
         failed > 0 ||
-        !reportAcknowledged;
+        !posted.acknowledged;
+    let failureReason = options.failureReason;
     if (!failureReason && completionBlocked) {
         const retryableCandidateReason = scan.candidates.find((candidate) => scan.retryable_candidate_keys.has(candidateCursorKey(candidate)) &&
             !oversizedCandidateKeys.has(candidateCursorKey(candidate)))?.reason;
@@ -518,59 +628,98 @@ async function reportBackfillOutcome(command, io, ctx, upload) {
             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),
-                    },
-                }
-                : {}),
-        });
+                    : (retryableCandidateReason ?? "backfill_incomplete"));
     }
     return {
-        ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
-        status,
-        retry_command: retryCommand,
+        remaining,
+        failed,
+        status: options.stoppedEarly || completionBlocked ? "partial" : "complete",
+        failureReason,
+    };
+}
+/**
+ * How much history a rerun still has to do. A reporting total, not a
+ * completion gate: it counts every unresolved candidate — oversized skips
+ * included, so `--json` never goes silent about them (BLI-2727) — plus what
+ * selection dropped, what discovery never saw, and the report itself when the
+ * server has not acknowledged it.
+ */
+function countRemainingHistory(options) {
+    const unresolvedKnownKeys = new Set([
+        ...options.unresolvedUploadableKeys,
+        ...options.scan.retryable_candidate_keys,
+    ]);
+    const unseenGlobalFailures = options.scan.issues
+        .filter((issue) => issue.scope === "global")
+        .reduce((total, issue) => total + issue.count, 0);
+    const reportRetryable = options.posted.acknowledged
+        ? 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, options.posted.sessions.length);
+    return (unresolvedKnownKeys.size +
+        options.scan.omitted_candidate_count +
+        unseenGlobalFailures +
+        reportRetryable);
+}
+/**
+ * Proof, for doctor and status, that archived history is covered. Only an
+ * `--all` run earns it: a bounded `--since-days` run may complete its
+ * requested window, but that is not proof of an all-history backfill.
+ */
+async function writeAllHistoryCompletionMarker(ctx) {
+    const { paths, cursor, sources, scopedCursor, scan, oversizedCandidateKeys, now } = ctx;
+    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),
+                },
+            }
+            : {}),
+    });
+}
+/** The `--json` payload: every stage's numbers merged onto the scan's baseline. */
+function assembleBackfillResult(options) {
+    const { command, ctx, upload, posted, completion } = options;
+    const base = baseBackfillResult(command, backfillResultBaseArgs(ctx));
+    return {
+        ...base,
+        status: completion.status,
+        retry_command: ctx.retryCommand,
         counts: {
-            ...baseBackfillResult(command, backfillResultBaseArgs(ctx)).counts,
-            backfilled: backfilledSessions,
-            failed,
-            deferred,
-            remaining,
+            ...base.counts,
+            backfilled: upload.backfilledSessions,
+            failed: completion.failed,
+            deferred: upload.deferred,
+            remaining: completion.remaining,
         },
         batches: {
-            total: batches.length,
-            completed: completedBatches,
-            failed: failedBatches,
+            total: upload.batches.length,
+            completed: upload.completedBatches,
+            failed: upload.failedBatches,
         },
-        report,
+        report: posted.report,
         server_acknowledged: {
-            codex_session_report_recorded_count: report.recorded_count,
-            raw_evidence_uploaded_object_count: uploadedObjects,
-            raw_evidence_uploaded_chunk_count: uploadedChunks,
+            codex_session_report_recorded_count: posted.report.recorded_count,
+            raw_evidence_uploaded_object_count: upload.uploadedObjects,
+            raw_evidence_uploaded_chunk_count: upload.uploadedChunks,
         },
-        blocked_at: blockedAt,
-        failure_reason: failureReason,
+        blocked_at: options.blockedAt,
+        failure_reason: completion.failureReason,
     };
 }
 function defaultBackfillWindowNotice() {
@@ -686,77 +835,98 @@ async function validateBackfillReachability(options) {
         throw new Error(`Dashboard reachability failed with HTTP ${response.status}.`);
     }
 }
+/**
+ * Reads both archived session stores and turns them into the candidates this
+ * run will consider: scan each selected store, keep what the cursor has not
+ * already resolved, order it, apply the operator's `--max-files` cap, then
+ * census what could not be accounted for.
+ */
 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,
-        })
+    const codexAttribution = options.sources.includes("codex")
+        ? await scanCodexHistory(options, codexSessionDirs, scanLimit)
         : 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,
-        })
+    const claudeAttribution = options.sources.includes("claude_code")
+        ? await scanClaudeHistory(options, claudeProjectsDir, scanLimit)
         : 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 selection = selectBackfillCandidates({
+        codexAttribution,
+        claudeAttribution,
+        cursor: options.cursor,
+        pointerlessTerminalSessions: options.pointerlessTerminalSessions,
+        maxFiles: options.command.maxFiles,
+    });
     const issues = await backfillScanIssues({
         codexAttribution,
         claudeAttribution,
         codexSessionDirs,
         claudeProjectsDir,
-        candidates,
-        omittedCandidateCount,
+        candidates: selection.candidates,
+        omittedCandidateCount: selection.omittedCandidateCount,
     });
     return {
-        candidates,
+        candidates: selection.candidates,
         codexAttribution,
         claudeAttribution,
         issues,
-        retryable_candidate_keys: retryableCandidateKeys(candidates),
-        omitted_candidate_count: omittedCandidateCount,
+        retryable_candidate_keys: retryableCandidateKeys(selection.candidates),
+        omitted_candidate_count: selection.omittedCandidateCount,
+    };
+}
+/**
+ * The adapter's own limit is a memory guard, not permission to silently leave
+ * history undiscovered. When it fires, re-scan the exact discovered population
+ * so a user-facing `--max-files` cap can resume from a truthful ordering.
+ */
+async function scanCodexHistory(request, sessionsDirs, scanLimit) {
+    const scan = (limit) => scanAndAttributeCodexSessions({
+        sessionsDirs,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_file_count));
+}
+/** Same rule for the Claude store: a capped first pass is rescanned in full. */
+async function scanClaudeHistory(request, projectsDir, scanLimit) {
+    const scan = (limit) => scanAndAttributeClaudeSessions({
+        projectsDir,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_session_count));
+}
+/**
+ * Which scanned sessions this run will actually work on. A session is in play
+ * if the cursor has not passed it, or if it is a terminal session that never
+ * earned a pointer and so deserves another attempt; those retries sort first
+ * so a `--max-files` cap spends its budget on them before newer history.
+ */
+function selectBackfillCandidates(options) {
+    const allCandidates = [
+        ...(options.codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
+        ...(options.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.maxFiles ?? Number.MAX_SAFE_INTEGER);
+    return {
+        candidates,
+        omittedCandidateCount: allCandidates.length - candidates.length,
     };
 }
 async function loadPointerlessTerminalSessions(paths, sources) {
@@ -890,46 +1060,62 @@ function normalizedCursorPath(filePath) {
     const normalized = path.resolve(filePath);
     return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
+/**
+ * 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.
+ */
 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");
+        await addCodexStoreScanIssues(issues, options.codexAttribution, options.codexSessionDirs);
     }
     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" &&
+        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");
-    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 +
+    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");
-    return issues.sort((a, b) => scanIssuePriority(a.scope) - scanIssuePriority(b.scope) ||
-        a.reason.localeCompare(b.reason));
 }
 function scanIssuePriority(scope) {
     if (scope === "global")
@@ -981,6 +1167,11 @@ function oversizedBackfillCandidateKeys(candidates) {
 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. */
 function addRepoDiscoveryIssues(issues, incompleteReasons) {
     for (const reason of incompleteReasons) {
@@ -1135,59 +1326,84 @@ function reasonCountsFor(candidates, guardCounts, scanIssues) {
         ...reasonClassification(reason),
     }));
 }
-function reasonClassification(reason) {
-    if (reason === "secret_like_content_guard" || reason === "secret_redaction_failed") {
-        return {
+/**
+ * The skip-reason table printed under every backfill run. These strings are
+ * what a person reads when coverage is short, so each note says what would
+ * have to change, not merely that something went wrong. Reason labels here
+ * must match the ones the scan and the guards emit verbatim.
+ */
+const REASON_VERDICTS = new Map([
+    [
+        "secret_like_content_guard",
+        {
             classification: "retryable",
             note: "historical guard result; collector now masks and retries",
-        };
-    }
-    if (reason === "file_too_large") {
-        return {
+        },
+    ],
+    [
+        "secret_redaction_failed",
+        {
             classification: "retryable",
-            note: "until the evidence file cap is raised",
-        };
-    }
-    if (reason === "repo_not_on_disk") {
-        return {
+            note: "historical guard result; collector now masks and retries",
+        },
+    ],
+    [
+        "file_too_large",
+        {
             classification: "retryable",
-            note: "repo must exist on disk",
-        };
-    }
-    if (reason === "cwd_not_a_repo") {
-        return {
+            note: "until the evidence file cap is raised",
+        },
+    ],
+    [
+        "repo_not_on_disk",
+        { classification: "retryable", note: "repo must exist on disk" },
+    ],
+    [
+        "cwd_not_a_repo",
+        {
             classification: "permanent",
             note: "cwd exists but is not a repo or folder workspace",
-        };
-    }
-    if (reason === "multiple_transcript_origins") {
-        return {
+        },
+    ],
+    [
+        "multiple_transcript_origins",
+        {
             classification: "permanent",
             note: "multiple transcript origins; attribution is ambiguous",
-        };
-    }
-    if (reason === "single_repo_folder_fallback") {
-        return {
+        },
+    ],
+    [
+        "single_repo_folder_fallback",
+        {
             classification: "permanent",
             note: "uploadable single-repo folder workspace fallback",
-        };
-    }
-    if (reason === "multi_repo_folder_workspace") {
-        return {
+        },
+    ],
+    [
+        "multi_repo_folder_workspace",
+        {
             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",
-    };
+        },
+    ],
+]);
+const DEFERRED_REASON_VERDICT = {
+    classification: "retryable",
+    note: "rerun cockpit backfill to continue",
+};
+const UNKNOWN_REASON_VERDICT = {
+    classification: "retryable",
+    note: "rerun after fixing source or collector state",
+};
+function reasonClassification(reason) {
+    const known = REASON_VERDICTS.get(reason);
+    if (known)
+        return known;
+    // A budget deferral is the one family, rather than one label: whichever
+    // budget ran out, the remedy is the same rerun.
+    if (reason.startsWith("deferred_"))
+        return DEFERRED_REASON_VERDICT;
+    return UNKNOWN_REASON_VERDICT;
 }
 function uploadableCandidates(candidates) {
     return candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
@@ -1248,8 +1464,33 @@ async function ensureBackfillReportContext(options) {
     }
     return { repoRoot };
 }
+/**
+ * Hands one batch to the ordinary sync path. A batch whose repo has no local
+ * work context yet is not a failure — backfill routinely visits repos this
+ * machine has never synced — so that one blocker is answered by creating the
+ * context and retrying; every other error propagates.
+ */
 async function syncBackfillBatch(options) {
-    const syncOptions = {
+    const syncOptions = backfillBatchSyncOptions(options);
+    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;
+    }
+}
+/** The batch translated into the live sync path's envelope, session files and all. */
+function backfillBatchSyncOptions(options) {
+    return {
         homeDir: options.command.homeDir,
         repoRoot: options.batch.worktree.repo_root,
         worktreeInventory: worktreeInventoryForRepo(options.batch.worktree, options.worktrees),
@@ -1282,29 +1523,21 @@ async function syncBackfillBatch(options) {
         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. */
+/**
+ * One attribution row per session this run saw, uploaded or not — the only
+ * record the server ever gets of a session the collector could not upload.
+ * 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 uploads = indexMainTranscriptUploads(options.syncResults);
+    const bestBySession = bestCandidatePerSession(options.candidates);
+    return [...bestBySession.values()].map((candidate) => sessionAttributionRow(candidate, uploads, options.now));
+}
+function indexMainTranscriptUploads(syncResults) {
+    const bySourceAndSession = new Map();
     const noUploadReasonBySessionId = new Map();
-    for (const sync of options.syncResults) {
+    for (const sync of syncResults) {
         if (sync.status !== "uploaded")
             continue;
         for (const outcome of sync.raw_evidence_outcomes) {
@@ -1323,15 +1556,23 @@ export function buildBackfillSessionReport(options) {
                 }
                 continue;
             }
-            uploadByKey.set(`${source}:${outcome.codex_session_id}`, {
+            bySourceAndSession.set(`${source}:${outcome.codex_session_id}`, {
                 upload_state: outcome.upload_state,
                 raw_evidence_pointer_id: outcome.raw_evidence_pointer_id,
                 reason: outcome.reason,
             });
         }
     }
+    return { bySourceAndSession, noUploadReasonBySessionId };
+}
+/**
+ * One row per session, not per file: the same session can be scanned from
+ * several paths, so the best-attributed sighting wins and the most recent one
+ * breaks a tie.
+ */
+function bestCandidatePerSession(candidates) {
     const bestByKey = new Map();
-    for (const candidate of options.candidates) {
+    for (const candidate of candidates) {
         const key = `${candidate.source}:${candidate.session_id}`;
         const existing = bestByKey.get(key);
         if (!existing || rank(candidate.state) > rank(existing.state)) {
@@ -1343,60 +1584,63 @@ export function buildBackfillSessionReport(options) {
             bestByKey.set(key, candidate);
         }
     }
-    return [...bestByKey.values()].map((candidate) => {
-        const upload = uploadByKey.get(`${candidate.source}:${candidate.session_id}`);
+    return bestByKey;
+}
+function sessionAttributionRow(candidate, uploads, now) {
+    return {
+        codex_session_id: candidate.session_id,
+        source: candidate.source,
+        observed_at: 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 } : {}),
+        ...sessionUploadFields(candidate, uploads),
+    };
+}
+/**
+ * The upload half of a report row. Every branch names an outcome: a pointer
+ * when one exists, and otherwise WHY there is none — BLI-2107 for an
+ * attributed session and BLI-3272 for a refused one. Backfill is the path that
+ * revisits old sessions, so a silent branch here would keep rewriting the very
+ * NULL/NULL rows those tickets found.
+ */
+function sessionUploadFields(candidate, uploads) {
+    const upload = uploads.bySourceAndSession.get(`${candidate.source}:${candidate.session_id}`);
+    if (upload) {
         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,
-                }
+            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 }
                 : {}),
-            ...(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),
-                    }),
         };
-    });
+    }
+    const observedReason = uploads.noUploadReasonBySessionId.get(candidate.session_id);
+    const wasUploadable = isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null);
+    return {
+        upload_state: "not_uploaded",
+        upload_reason: observedReason ??
+            (wasUploadable
+                ? NO_UPLOAD_ATTEMPT_RECORDED
+                : notUploadableAttributionStateReason(candidate.reason)),
+    };
 }
 function rank(state) {
     switch (state) {
@@ -1414,16 +1658,35 @@ function rank(state) {
             return 0;
     }
 }
+/**
+ * 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.
+ */
 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) {
+    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);
@@ -1441,8 +1704,7 @@ function durableBackfillCandidateKeys(batch, sync) {
         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") {
+            if (outcome.kind === "codex_jsonl" || outcome.kind === "claude_jsonl") {
                 summary.durableMainCount += 1;
             }
             else if (outcome.kind === "claude_jsonl_sidecar") {
@@ -1451,35 +1713,22 @@ function durableBackfillCandidateKeys(batch, sync) {
         }
         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;
+    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);
+}
+/**
+ * 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.
+ */
 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);
-        }
-    }
+    const durableObjectBySession = indexDurableMainObjectKeys(options.syncResults);
     let recordedCount = 0;
     for (const source of ["codex", "claude_code"]) {
         const filename = source === "claude_code" ? CLAUDE_CURSOR_FILENAME : undefined;
@@ -1490,22 +1739,10 @@ async function recordBackfillDurableSessionPointers(options) {
                 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] = {
-                ...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(),
-            };
+            cursor.sessions[candidate.session_id] = deliveredCursorEntry(prior, candidate, objectKey, options.now);
             changed = true;
             recordedCount += 1;
         }
@@ -1520,6 +1757,42 @@ async function recordBackfillDurableSessionPointers(options) {
         console.error("[backfill] terminal session pointers recorded", JSON.stringify({ count: recordedCount }));
     }
 }
+/** Storage keys for main transcripts that actually landed, keyed by source and session. */
+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;
+}
+/** 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(),
+    };
+}
 function countSessionUploadFailures(sync) {
     return sync.raw_evidence_outcomes.filter((outcome) => Boolean(outcome.codex_session_id) &&
         outcome.upload_state === "upload_failed" &&