@bli-cockpit/cli 0.2.34 → 0.2.36

package/dist/commands/backfill.js

@@ -7,7 +7,7 @@ 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 { 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";
@@ -56,19 +56,111 @@ export async function runBackfillCommand(command, io) {
     writeHumanBackfillResult(result, io);
     return result.status === "complete" ? 0 : 1;
 }
+/**
+ * The backfill runbook: SCAN what history exists and whether this machine can
+ * even run, PLAN whether to actually proceed (confirmation, dry run), UPLOAD
+ * every batch under the shared collection lock, REPORT the outcome and update
+ * every durable marker. Each stage is a named function below; this function is
+ * only the sequence and the lock lifecycle, which straddles UPLOAD and REPORT
+ * and so stays here rather than being split across them.
+ */
 export async function runBackfill(command, io) {
     const now = new Date();
+    const scanned = await scanBackfillRun(command, io, now);
+    if (scanned.kind === "blocked")
+        return scanned.result;
+    const plan = await planBackfillRun(command, io, scanned);
+    if (plan.kind === "result")
+        return plan.result;
+    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,
+            },
+        };
+    }
+    let collectionLock;
+    try {
+        collectionLock = await acquireSyncLock(paths);
+    }
+    catch (error) {
+        await lock.handle.release();
+        throw error;
+    }
+    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,
+            },
+        };
+    }
+    try {
+        // Backfill and scheduled/manual sync share upload spool and raw-evidence
+        // cursors. Holding the same collection lock makes their read-modify-write
+        // updates serial, while the dedicated backfill lock still prevents two
+        // historical scans from running together.
+        if (scanned.scopedCursor.reset) {
+            await writeBackfillCursor(paths, scanned.cursor);
+        }
+        const upload = await uploadBackfillBatches(command, io, lock, scanned);
+        return await reportBackfillOutcome(command, io, scanned, upload);
+    }
+    finally {
+        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 blockedBackfillResult(command, {
-            now,
-            dashboardUrl: sessionFile.dashboard_url ?? config.dashboard_url,
-            reason: "collector_not_paired",
-            cursor: await readBackfillCursor(paths),
-        });
+        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);
@@ -101,52 +193,43 @@ export async function runBackfill(command, io) {
         pointerlessTerminalSessions,
         now,
     });
-    for (const reason of worktreeDiscovery.incomplete_reasons) {
-        scan.issues.push({
-            reason: `repo_discovery_${reason}`,
-            count: 1,
-            scope: "global",
-        });
-    }
-    scan.issues.sort((a, b) => scanIssuePriority(a.scope) - scanIssuePriority(b.scope) ||
-        a.reason.localeCompare(b.reason));
+    // 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,
     ]);
-    if (guards.counts.get("file_read_failed")) {
-        scan.issues.push({
-            reason: "candidate_file_read_failed",
-            count: guards.counts.get("file_read_failed") ?? 0,
-            scope: "candidate",
-        });
-    }
-    if (guards.counts.get("file_too_large")) {
-        scan.issues.push({
-            reason: "file_too_large",
-            count: guards.counts.get("file_too_large") ?? 0,
-            scope: "candidate",
-        });
-    }
+    addReadOnlyGuardIssues(scan.issues, guards.counts);
     const reasonCounts = reasonCountsFor(scan.candidates, guards.counts, scan.issues);
-    // 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 below excludes it explicitly instead.
     const oversizedCandidateKeys = oversizedBackfillCandidateKeys(scan.candidates);
-    // 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` 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",
-    ]);
-    const blockingScanIssues = (issues) => issues.filter((issue) => !OVERSIZED_SCAN_ISSUE_REASONS.has(issue.reason));
+    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, {
@@ -159,29 +242,16 @@ export async function runBackfill(command, io) {
         const confirmed = await confirmAllBackfill(io);
         if (!confirmed) {
             return {
-                ...baseBackfillResult(command, {
-                    now,
-                    dashboardUrl,
-                    sources,
-                    window,
-                    cursor,
-                    scan,
-                    reasonCounts,
-                }),
-                status: "blocked",
-                counts: {
-                    ...baseBackfillResult(command, {
-                        now,
-                        dashboardUrl,
-                        sources,
-                        window,
-                        cursor,
-                        scan,
-                        reasonCounts,
-                    }).counts,
-                    remaining: scan.candidates.length,
+                kind: "result",
+                result: {
+                    ...baseBackfillResult(command, backfillResultBaseArgs(ctx)),
+                    status: "blocked",
+                    counts: {
+                        ...baseBackfillResult(command, backfillResultBaseArgs(ctx)).counts,
+                        remaining: scan.candidates.length,
+                    },
+                    failure_reason: "confirmation_declined",
                 },
-                failure_reason: "confirmation_declined",
             };
         }
     }
@@ -195,363 +265,313 @@ export async function runBackfill(command, io) {
             });
         }
         return {
-            ...baseBackfillResult(command, {
-                now,
-                dashboardUrl,
-                sources,
-                window,
-                cursor,
-                scan,
-                reasonCounts,
-            }),
-            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 }
-                : {}),
-        };
-    }
-    const lock = await acquireBackfillLock(paths, now);
-    if (!lock.acquired) {
-        return {
-            ...baseBackfillResult(command, {
-                now,
-                dashboardUrl,
-                sources,
-                window,
-                cursor,
-                scan,
-                reasonCounts,
-            }),
-            status: "blocked",
-            retry_command: retryCommand,
-            failure_reason: "backfill_already_running",
-            blocked_at: {
-                what: "backfill lock held",
-                batch_index: 0,
-                batch_total: 0,
-                done: 0,
-                total: scan.candidates.length,
-            },
-        };
-    }
-    let collectionLock;
-    try {
-        collectionLock = await acquireSyncLock(paths);
-    }
-    catch (error) {
-        await lock.handle.release();
-        throw error;
-    }
-    if (!collectionLock.acquired) {
-        await lock.handle.release();
-        return {
-            ...baseBackfillResult(command, {
-                now,
-                dashboardUrl,
-                sources,
-                window,
-                cursor,
-                scan,
-                reasonCounts,
-            }),
-            status: "blocked",
-            retry_command: retryCommand,
-            failure_reason: "sync_already_running",
-            blocked_at: {
-                what: "sync collection lock held",
-                batch_index: 0,
-                batch_total: 0,
-                done: 0,
-                total: scan.candidates.length,
+            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 }
+                    : {}),
             },
         };
     }
-    try {
-        // Backfill and scheduled/manual sync share upload spool and raw-evidence
-        // cursors. Holding the same collection lock makes their read-modify-write
-        // updates serial, while the dedicated backfill lock still prevents two
-        // historical scans from running together.
-        if (scopedCursor.reset) {
-            await writeBackfillCursor(paths, cursor);
+    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;
         }
-        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;
-            // 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.
-            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;
-            }
+        else {
+            consecutiveFailures = 0;
         }
-        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) {
+        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: "session report failed",
-                batch_index: completedBatches,
+                what: "raw evidence budget exhausted",
+                batch_index: index + 1,
                 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);
+            failureReason = "deferred_budget_exhausted";
+            break;
         }
-        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;
+        if (consecutiveFailures >= BACKFILL_MAX_CONSECUTIVE_FAILURES) {
+            blockedAt = {
+                what: "consecutive upload failures",
+                batch_index: index + 1,
+                batch_total: batches.length,
+                done,
+                total: uploadable.length,
+            };
             failureReason =
-                blockingIssues[0]?.reason ??
-                    (unresolvedUploadableBlocking > 0
+                sync.status === "spooled"
+                    ? sync.failure_reason
+                    : missingDurableMain > 0
                         ? "durable_session_pointer_missing"
-                        : retryableCandidateReason ?? "backfill_incomplete");
+                        : "upload_failed";
+            break;
         }
-        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, {
-                now,
-                dashboardUrl,
-                sources,
-                window,
-                cursor,
-                scan,
-                reasonCounts,
-            }),
-            status,
-            retry_command: retryCommand,
-            counts: {
-                ...baseBackfillResult(command, {
-                    now,
-                    dashboardUrl,
-                    sources,
-                    window,
-                    cursor,
-                    scan,
-                    reasonCounts,
-                }).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,
+    }
+    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,
+        });
     }
-    finally {
-        await collectionLock.handle.release();
-        await lock.handle.release();
+    // 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 [
@@ -951,6 +971,71 @@ function oversizedBackfillCandidateKeys(candidates) {
     }
     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) {