@bli-cockpit/cli 0.2.98 → 0.2.100

package/dist/cli.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
 import { runCockpitCli } from "./commands/public-root.js";
+import {
+  EXIT_DIED_MID_RUN,
+  installCrashGuard,
+  markCommandReturned,
+} from "./crash-guard.js";
+
+// BLI-4110. Success is EARNED, not assumed — see crash-guard.js. This
+// entry point is GENERATED, so it must mirror src/cli.ts; the packed CLI
+// is the one the fleet runs.
+process.exitCode = EXIT_DIED_MID_RUN;
+installCrashGuard();
 
 const exitCode = await runCockpitCli(process.argv.slice(2));
+
+markCommandReturned();
 process.exitCode = exitCode;

package/dist/commands/backfill-checkpoint.js

@@ -77,8 +77,10 @@ export function advanceBackfillCursorThroughResolvedPrefix(options) {
             .sort(compareBackfillCandidates);
         for (const candidate of remaining) {
             const key = candidateCursorKey(candidate);
-            if (options.retryableCandidateKeys.has(key))
+            if (options.retryableCandidateKeys.has(key) &&
+                !options.deterministicSkipCandidateKeys?.has(key)) {
                 break;
+            }
             const resolved = isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null)
                 ? options.durableCandidateKeys.has(key)
                 : true;

package/dist/commands/backfill-issues.js

@@ -2,6 +2,10 @@
  * Everything the scan could not account for cleanly, in one ledger — the
  * module that exists so a session is never silently dropped.
  *
+ * What any of those records MEAN for the run — retryable versus a deliberate
+ * cap, and therefore what blocks completion — lives in the sibling
+ * `backfill-skip-policy.ts`, and every name it owns is re-exported from here.
+ *
  * Scope is the load-bearing distinction. A global issue means discovery may
  * have hidden a session at any mtime, so no source watermark is safe to
  * advance; a candidate issue only stops the contiguous cursor prefix at the
@@ -79,39 +83,6 @@ function scanIssuePriority(scope) {
         return 1;
     return 2;
 }
-export function retryableCandidateKeys(candidates) {
-    return new Set(candidates
-        .filter((candidate) => candidate.reason === "file_read_failed" ||
-        candidate.reason === "repo_not_on_disk" ||
-        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
-            !candidate.worktree) ||
-        Boolean(candidate.claude?.main_file_oversized) ||
-        (candidate.claude?.sidecars_capped ?? 0) > 0 ||
-        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
-            sidecar.skipped_reason === "file_too_large")))
-        .map(candidateCursorKey));
-}
-/**
- * A main session file whose only story is "too large to upload under the
- * current cap" (BLI-2727). This mirrors exactly the two branches in
- * `countReadOnlyGuards` that emit the `file_too_large` reason, so a candidate
- * is in this set if and only if it contributed to that scan issue's count —
- * one predicate, no drift between "why the issue fired" and "which candidate
- * caused it". Deterministic and non-retryable: rerunning backfill cannot
- * resolve it (only a larger cap or a smaller file can), so unlike a transient
- * read failure it must never poison completion or a batch's success.
- */
-export function oversizedBackfillCandidateKeys(candidates) {
-    const keys = new Set();
-    for (const candidate of candidates) {
-        if ((candidate.source === "claude_code" &&
-            candidate.claude?.main_file_oversized) ||
-            candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
-            keys.add(candidateCursorKey(candidate));
-        }
-    }
-    return keys;
-}
 // --- Scan issue ledger --------------------------------------------------
 //
 // `scan.issues` is the running ledger of everything the scan could not
@@ -161,27 +132,6 @@ export function addReadOnlyGuardIssues(issues, guardCounts) {
         });
     }
 }
-// BLI-2727: a deterministic, labeled oversized skip must never poison
-// completion — it is a permanent, non-retryable fact about the file, not an
-// in-flight problem a rerun can fix. `scan.issues`/`retryable_candidate_keys`
-// still carry it (so it's never silently dropped from reporting); every
-// completion-gating computation excludes it explicitly instead, by filtering
-// through `blockingScanIssues` below.
-//
-// Two scan issues describe the exact same oversized-main candidates:
-// `backfillScanIssues` pushes the Claude-specific `claude_main_file_too_large`
-// (from `claude?.main_file_oversized`) and `countReadOnlyGuards` (via
-// `addReadOnlyGuardIssues` above) separately pushes the source-agnostic
-// `file_too_large` (same predicate as `oversizedBackfillCandidateKeys`, so
-// this list can never drift from it). Both must be excluded from
-// completion-gating together.
-const OVERSIZED_SCAN_ISSUE_REASONS = new Set([
-    "file_too_large",
-    "claude_main_file_too_large",
-]);
-export function blockingScanIssues(issues) {
-    return issues.filter((issue) => !OVERSIZED_SCAN_ISSUE_REASONS.has(issue.reason));
-}
 async function countUnreadableClaudeSidecarDirs(candidates) {
     let unreadable = 0;
     for (const candidate of candidates) {
@@ -262,4 +212,7 @@ export async function countReadOnlyGuards(candidates) {
 }
 export function increment(counts, key) {
     counts.set(key, (counts.get(key) ?? 0) + 1);
-}
+}
+// Re-exported so every caller keeps importing the skip policy from
+// `./backfill-issues.js` regardless of which sibling decides it.
+export { blockingScanIssues, cappedSidecarCount, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, } from "./backfill-skip-policy.js";

package/dist/commands/backfill-report.js

@@ -4,7 +4,7 @@ import { readLocalWorkContextForRepo, startLocalWorkContext, } from "../local-st
 import { postCodexSessionReport, } from "../upload.js";
 import { candidateCursorKey } from "./backfill-candidates.js";
 import { advanceBackfillCursorThroughResolvedPrefix, recordBackfillDurableSessionPointers, } from "./backfill-checkpoint.js";
-import { blockingScanIssues } from "./backfill-issues.js";
+import { blockingScanIssues, cappedSidecarCount } from "./backfill-issues.js";
 import { backfillResultBaseArgs, baseBackfillResult, emptyReport, } from "./backfill-result.js";
 import { buildBackfillSessionReport } from "./backfill-session-report.js";
 /**
@@ -111,7 +111,7 @@ function sessionReportFailureReason(posted) {
  * past a session the server never recorded can never be walked back.
  */
 async function checkpointResolvedBackfillProgress(ctx, upload) {
-    const { paths, scan, cursor, now } = ctx;
+    const { paths, scan, cursor, now, deterministicSkipCandidateKeys } = ctx;
     if (upload.durableCandidateKeys.size > 0) {
         await recordBackfillDurableSessionPointers({
             paths,
@@ -125,6 +125,10 @@ async function checkpointResolvedBackfillProgress(ctx, upload) {
         candidates: scan.candidates,
         durableCandidateKeys: upload.durableCandidateKeys,
         retryableCandidateKeys: scan.retryable_candidate_keys,
+        // BLI-4303: a permanent cap must not stop the prefix either, or the cursor
+        // stalls at the first sidecar-capped session for good and every later run
+        // re-walks the same history.
+        deterministicSkipCandidateKeys,
         discoveryComplete: !scan.issues.some((issue) => issue.scope === "global"),
         now,
     });
@@ -141,13 +145,13 @@ async function checkpointResolvedBackfillProgress(ctx, upload) {
  * that no rerun can resolve and completion must not wait on forever.
  */
 function summarizeBackfillCompletion(options) {
-    const { scan, oversizedCandidateKeys } = options.ctx;
+    const { scan, deterministicSkipCandidateKeys } = options.ctx;
     const { upload, posted } = options;
     const unresolvedUploadableKeys = new Set(upload.uploadable
         .filter((candidate) => !upload.durableCandidateKeys.has(candidateCursorKey(candidate)))
         .map(candidateCursorKey));
-    const unresolvedUploadableBlocking = [...unresolvedUploadableKeys].filter((key) => !oversizedCandidateKeys.has(key)).length;
-    const unresolvedRetryableBlocking = [...scan.retryable_candidate_keys].filter((key) => !oversizedCandidateKeys.has(key)).length;
+    const unresolvedUploadableBlocking = [...unresolvedUploadableKeys].filter((key) => !deterministicSkipCandidateKeys.has(key)).length;
+    const unresolvedRetryableBlocking = [...scan.retryable_candidate_keys].filter((key) => !deterministicSkipCandidateKeys.has(key)).length;
     const remaining = countRemainingHistory({
         scan,
         unresolvedUploadableKeys,
@@ -164,7 +168,7 @@ function summarizeBackfillCompletion(options) {
     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;
+            !deterministicSkipCandidateKeys.has(candidateCursorKey(candidate)))?.reason;
         failureReason =
             blockingIssues[0]?.reason ??
                 (unresolvedUploadableBlocking > 0
@@ -211,6 +215,7 @@ function countRemainingHistory(options) {
  */
 async function writeAllHistoryCompletionMarker(ctx) {
     const { paths, cursor, sources, scopedCursor, scan, oversizedCandidateKeys, now } = ctx;
+    const cappedSidecars = cappedSidecarCount(scan.candidates);
     recordBackfillScanCoverage(cursor, sources, now, now);
     await writeBackfillCursor(paths, cursor);
     const oversizedCandidates = scan.candidates.filter((candidate) => oversizedCandidateKeys.has(candidateCursorKey(candidate)));
@@ -231,6 +236,17 @@ async function writeAllHistoryCompletionMarker(ctx) {
                 },
             }
             : {}),
+        // BLI-4303: additive on the same schema version, so an older marker simply
+        // omits it. A cap that is now excused from completion has to be visible
+        // wherever completion is claimed.
+        ...(cappedSidecars > 0
+            ? {
+                sidecar_cap_skips: {
+                    reason: "claude_sidecar_limit_applied",
+                    count: cappedSidecars,
+                },
+            }
+            : {}),
     });
 }
 /** The `--json` payload: every stage's numbers merged onto the scan's baseline. */

package/dist/commands/backfill-scan.js

@@ -16,7 +16,7 @@ import { emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCu
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
-import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
+import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
 import { reasonCountsFor } from "./backfill-reasons.js";
 import { blockedBackfillResult } from "./backfill-result.js";
 import { resolveBackfillScope } from "./backfill-scope.js";
@@ -73,6 +73,7 @@ export async function scanBackfillRun(command, io, now) {
         scan,
         reasonCounts,
         oversizedCandidateKeys: oversizedBackfillCandidateKeys(scan.candidates),
+        deterministicSkipCandidateKeys: deterministicSkipCandidateKeys(scan.candidates),
     };
 }
 /**

package/dist/commands/backfill-skip-policy.js

@@ -0,0 +1,134 @@
+/**
+ * Which candidates a rerun could actually resolve, and which are a cap.
+ *
+ * The sibling ledger (`backfill-issues.ts`) records everything the scan could
+ * not account for; this module answers the only question the rest of the run
+ * asks about those records: does the thing block completion, or is it a
+ * permanent fact about the file that no rerun can change. The distinction is
+ * load-bearing in three places at once — completion, the cursor's contiguous
+ * prefix, and whether a batch counts as failed — so it has one owner.
+ *
+ *   retryableCandidateKeys           a rerun still owes this session something
+ *   oversizedBackfillCandidateKeys   the file is past the upload cap (BLI-2727)
+ *   deterministicSkipCandidateKeys   oversized, or sidecar-capped and nothing
+ *                                    else wrong with it (BLI-4303)
+ *   blockingScanIssues               the ledger minus the deliberate caps
+ *   cappedSidecarCount               what the sidecar cap left behind
+ *
+ * Every name here is re-exported from `./backfill-issues.js`, the address its
+ * callers already know.
+ */
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { candidateCursorKey } from "./backfill-candidates.js";
+export function retryableCandidateKeys(candidates) {
+    return new Set(candidates
+        .filter((candidate) => candidate.reason === "file_read_failed" ||
+        candidate.reason === "repo_not_on_disk" ||
+        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+            !candidate.worktree) ||
+        Boolean(candidate.claude?.main_file_oversized) ||
+        (candidate.claude?.sidecars_capped ?? 0) > 0 ||
+        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
+            sidecar.skipped_reason === "file_too_large")))
+        .map(candidateCursorKey));
+}
+/**
+ * A main session file whose only story is "too large to upload under the
+ * current cap" (BLI-2727). This mirrors exactly the two branches in
+ * `countReadOnlyGuards` that emit the `file_too_large` reason, so a candidate
+ * is in this set if and only if it contributed to that scan issue's count —
+ * one predicate, no drift between "why the issue fired" and "which candidate
+ * caused it". Deterministic and non-retryable: rerunning backfill cannot
+ * resolve it (only a larger cap or a smaller file can), so unlike a transient
+ * read failure it must never poison completion or a batch's success.
+ */
+export function oversizedBackfillCandidateKeys(candidates) {
+    const keys = new Set();
+    for (const candidate of candidates) {
+        if ((candidate.source === "claude_code" &&
+            candidate.claude?.main_file_oversized) ||
+            candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+            keys.add(candidateCursorKey(candidate));
+        }
+    }
+    return keys;
+}
+// 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.
+//
+// BLI-4303 adds the third member of the same class, and it is the one that
+// kept the reference Mac's `backfill-complete` row red forever:
+// `claude_sidecar_limit_applied` counts helper transcripts past
+// `CLAUDE_SESSION_MAX_SIDECAR_FILES`, a fixed constant. It is exactly as
+// permanent as an oversized file — no rerun can produce the 41st sidecar of a
+// session whose cap is 40 — yet it gated completion, so the all-history
+// marker could never be written on a machine that uses subagents heavily
+// (513 capped sidecars there). A cap is a collection boundary, not a failure;
+// raising it is a separate decision, and until then it is a labeled fact that
+// travels in the marker and in what doctor says.
+const DETERMINISTIC_SKIP_SCAN_ISSUE_REASONS = new Set([
+    "file_too_large",
+    "claude_main_file_too_large",
+    "claude_sidecar_limit_applied",
+]);
+export function blockingScanIssues(issues) {
+    return issues.filter((issue) => !DETERMINISTIC_SKIP_SCAN_ISSUE_REASONS.has(issue.reason));
+}
+/**
+ * How many helper transcripts this run left behind purely because of the
+ * per-session sidecar cap (BLI-4303). Metadata only — a count, no paths — and
+ * it is what the completion marker and doctor's green row say out loud so an
+ * excused skip is never a silent one.
+ */
+export function cappedSidecarCount(candidates) {
+    return candidates.reduce((total, candidate) => total + (candidate.claude?.sidecars_capped ?? 0), 0);
+}
+/**
+ * Candidates whose ONLY unfinished business is a cap this collector applies on
+ * purpose (BLI-4303): the oversized-main set above, plus a session that hit the
+ * per-session sidecar cap and has nothing else wrong with it.
+ *
+ * The second half carries a condition the first does not, deliberately: a
+ * sidecar-capped session still uploads its main transcript, so it can and must
+ * earn a durable pointer. If anything ELSE about it is retryable — an
+ * unreadable file, a repo that is not on disk, an uploadable state with no
+ * worktree, a sidecar that could not be read — it is not excused, because then
+ * a rerun genuinely has work to do on it.
+ */
+export function deterministicSkipCandidateKeys(candidates) {
+    const keys = oversizedBackfillCandidateKeys(candidates);
+    for (const candidate of candidates) {
+        if (!isSidecarCapOnlyCandidate(candidate))
+            continue;
+        keys.add(candidateCursorKey(candidate));
+    }
+    return keys;
+}
+function isSidecarCapOnlyCandidate(candidate) {
+    const cappedSidecars = candidate.claude?.sidecars_capped ?? 0;
+    const oversizedSidecars = Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_too_large"));
+    if (cappedSidecars === 0 && !oversizedSidecars)
+        return false;
+    return !hasRetryableProblem(candidate);
+}
+/** The parts of `retryableCandidateKeys` a rerun could actually resolve. */
+function hasRetryableProblem(candidate) {
+    return (candidate.reason === "file_read_failed" ||
+        candidate.reason === "repo_not_on_disk" ||
+        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+            !candidate.worktree) ||
+        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed")));
+}

package/dist/commands/careers.js

@@ -0,0 +1,16 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from './agent-door.js';
+export async function runCareers(command, io) {
+    const door = await openAgentDoor('careers', command, io);
+    const query = new URLSearchParams();
+    if (command.role)
+        query.set('role', command.role);
+    if (command.minScore !== undefined)
+        query.set('min_score', String(command.minScore));
+    if (command.since)
+        query.set('since', command.since);
+    const path = command.action === 'list' ? `/api/careers/applications?${query}` : `/api/careers/applications/${encodeURIComponent(command.id)}${command.action === 'rescreen' ? '/rescreen' : ''}`;
+    const answer = await askAgentDoor(door, { path, method: command.action === 'rescreen' ? 'POST' : 'GET', label: `careers ${command.action}`, timeoutMs: 60_000 });
+    if (!answer.ok)
+        return failAgentDoor(door, '[careers]', answer.reason, answer.detail);
+    return emitAgentDoor(door, answer.body);
+}

package/dist/commands/doctor-pipeline-verdicts.js

@@ -0,0 +1,238 @@
+/**
+ * The pure verdicts the pipeline rows compute, and nothing else.
+ *
+ * `doctor-pipeline.ts` is the four checks that TOUCH the machine (run the
+ * catch-up, prune the disk, exec a sync). Everything here is the opposite: a
+ * function that takes a receipt or a marker someone else read and answers
+ * "what does that mean for the row". They live apart so each verdict can be
+ * unit-tested against a payload recorded off a real machine, with no exec, no
+ * filesystem and no home directory.
+ *
+ * Read it as four answers:
+ *
+ *   isCollectionBusyReason        another run owns the lock; nothing is broken
+ *   backfillCompletionStepState   what an all-history marker proves
+ *   backfillFixVerdict            busy vs progress vs actually broken
+ *   syncBacklogDrainingVerdict    a backlog draining is not a failed tick
+ *   syncStandAsideVerdict         is the lock's owner still alive
+ *
+ * Every name here is re-exported from `./doctor-pipeline.js`, the address its
+ * callers already know.
+ */
+import { backfillCompletionCovers } from "../cursors/backfill-cursor.js";
+import { describeError } from "../health-detail.js";
+import { SYNC_LOCK_STALE_TAKEOVER_MS } from "../sync-lock.js";
+import { asRecord, fail, needsFix, ok } from "./doctor-report.js";
+/**
+ * BLI-4303: the reasons a collection command stood aside because ANOTHER
+ * collection run already owned the machine's single collection lock.
+ *
+ * `backfill` reports them as `failure_reason`, `sync` as its top-level
+ * `status`; both exit 0 and both say `retryable: true`. On a machine whose
+ * launchd job also watches `~/.claude/projects` and `~/.codex/sessions`, a tick
+ * is in flight most of the time an agent is working — the reference Mac held
+ * the lock in 76 of 89 samples over three minutes — so doctor's own repair
+ * almost always met a running sync and called it a failure. A busy machine is
+ * the collector working, never a machine to repair: these produce a named
+ * non-red row and the next run proves the receipt.
+ */
+const COLLECTION_BUSY_REASONS = new Set([
+    // `cockpit sync` stood aside for another sync.
+    "sync_already_running",
+    // `cockpit sync` stood aside for a running backfill.
+    "live_sync_paused_during_backfill",
+    // `cockpit backfill` stood aside for another backfill.
+    "backfill_already_running",
+]);
+export function isCollectionBusyReason(reason) {
+    return typeof reason === "string" && COLLECTION_BUSY_REASONS.has(reason);
+}
+/**
+ * Pure so it can be unit-tested without touching the real machine's home
+ * directory (`getCollectorRuntimePaths()` defaults to `os.homedir()` and
+ * doctor never threads `--home` through the backfill steps). Returns `null`
+ * when the marker does not cover the roots/sources — the caller falls
+ * through to the lock/never-run diagnosis in that case.
+ *
+ * BLI-2727/BLI-4303: a marker whose only outstanding entries are deterministic
+ * skips (files over the upload cap, helper transcripts over the per-session
+ * sidecar cap) is still a completed backfill. It reads green with a named
+ * note, never a red `needs_fix`/`fail`, so a cap nobody can lift from here
+ * never reads as "backfill never completed" on repeat doctor runs.
+ */
+export function backfillCompletionStepState(marker, roots) {
+    if (!backfillCompletionCovers(marker, roots, ["codex", "claude_code"])) {
+        return null;
+    }
+    const caughtUp = "caught up on old Codex and Claude sessions in every saved folder";
+    const oversized = marker?.oversized_skips;
+    const sidecarCaps = marker?.sidecar_cap_skips;
+    const notes = [];
+    if (oversized && oversized.count > 0) {
+        notes.push(`${oversized.count} file${oversized.count === 1 ? "" : "s"} too big to upload`);
+    }
+    // BLI-4303: a cap is named, never silent. It no longer blocks completion, so
+    // the green row is the only place a person would ever learn it fired.
+    if (sidecarCaps && sidecarCaps.count > 0) {
+        notes.push(`${sidecarCaps.count} helper transcript${sidecarCaps.count === 1 ? "" : "s"} past the per-session cap`);
+    }
+    if (notes.length === 0)
+        return ok("backfill-complete", "complete", caughtUp);
+    const code = oversized && sidecarCaps
+        ? "complete_with_capped_skips"
+        : oversized
+            ? "complete_with_oversized_skips"
+            : "complete_with_sidecar_caps";
+    return ok("backfill-complete", code, `${caughtUp} (${code} · ${notes.join(", ")})`);
+}
+/**
+ * `cockpit backfill --json` prints exactly one JSON document to stdout. Parsed
+ * rather than field-scraped for the same reason sync is (BLI-2728): `counts`
+ * and `batches` both carry a `failed`, and a regex cannot tell them apart.
+ */
+export function parseDoctorBackfillJson(stdout) {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (error) {
+        console.error("[cockpit-doctor] backfill --json stdout was not one JSON document", JSON.stringify({
+            reason: "backfill_json_unparseable",
+            byte_size: stdout.length,
+            ...describeError(error),
+        }));
+        return null;
+    }
+}
+/**
+ * BLI-4303: what a backfill that did not reach `complete` means for the row.
+ *
+ * Three different machines used to read `❌ backfill did not complete`, and
+ * only one of them was broken:
+ *
+ *   busy      another collection run owned the lock, so this one never started
+ *   progress  it uploaded history and left more of it for the next run
+ *   broken    it could not do the work — auth, the server, a read failure
+ *
+ * Only the third is a `fail`. The first two are `needs_fix`, which is the same
+ * word `checkBackfillState` already uses for an unfinished catch-up: the fix
+ * side had been the only place that called an unfinished backfill a failure.
+ * Pure so the three verdicts are testable off a recorded `--json` payload.
+ */
+export function backfillFixVerdict(parsed, scrapedReason) {
+    const reason = (typeof parsed?.failure_reason === "string" ? parsed.failure_reason : null) ??
+        scrapedReason;
+    if (isCollectionBusyReason(reason)) {
+        return needsFix("backfill-complete", reason ?? "collection_busy", "another collection run is using your sessions right now, so the catch-up " +
+            "stood aside; it runs on the next `cockpit doctor` or `cockpit backfill --all --yes`");
+    }
+    const counts = asRecord(parsed?.counts);
+    const batches = asRecord(parsed?.batches);
+    const backfilled = positiveNumberOrZero(counts?.["backfilled"]);
+    const remaining = positiveNumberOrZero(counts?.["remaining"]);
+    const completedBatches = positiveNumberOrZero(batches?.["completed"]);
+    if (backfilled > 0 || completedBatches > 0) {
+        return needsFix("backfill-complete", reason ?? "backfill_incomplete", `caught up on ${backfilled} old session${backfilled === 1 ? "" : "s"} this run` +
+            (remaining > 0 ? `, ${remaining} still to go` : "") +
+            "; run `cockpit backfill --all --yes` again to continue");
+    }
+    return fail("backfill-complete", reason ?? "backfill_failed", "backfill did not complete");
+}
+export function jsonField(output, field) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const match = output.match(new RegExp(`"${escaped}"\\s*:\\s*"([^"]+)"`, "u"));
+    return match?.[1] ?? null;
+}
+/**
+ * `cockpit sync --json` prints exactly one JSON document to stdout (stderr is
+ * for human text; see AGENTS.md logging conventions), so this is a real parse
+ * rather than the doctor module's usual regex field-scrape — which cannot
+ * disambiguate same-named fields nested under `codex_sessions.codex` vs
+ * `codex_sessions.claude` (BLI-2728).
+ */
+export function parseDoctorSyncJson(stdout) {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (error) {
+        // `null` sends doctor back to its regex field-scrape, quietly losing the
+        // BLI-2728 disambiguation. Something wrote to stdout that was not the one
+        // JSON document the contract promises — a stray console.log in the
+        // collector would do exactly this and look like nothing at all.
+        console.error("[cockpit-doctor] sync --json stdout was not one JSON document", JSON.stringify({
+            reason: "sync_json_unparseable",
+            byte_size: stdout.length,
+            ...describeError(error),
+        }));
+        return null;
+    }
+}
+/**
+ * BLI-2728: a tick that only deferred objects past the per-tick raw-evidence
+ * object budget (`RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET`, adapters/raw-evidence.ts)
+ * is a backlog that is draining, not a failure — `attributedSyncRunStatus`
+ * marks the run not-fully-`ok` (so `cockpit sync` exits non-zero and doctor's
+ * exec sees `code !== 0`) purely because objects remain queued, with the
+ * per-repo upload itself still having succeeded. A genuine failure (auth,
+ * server rejection, network, a real upload_failed outcome, an unposted
+ * session report) must still read red — this only fires when NOTHING else in
+ * the tick's own summary looks wrong. Pure so it is unit-testable without a
+ * live exec/fs harness; the remaining-object count is read straight from the
+ * tick's own summary, never recomputed.
+ */
+export function syncBacklogDrainingVerdict(parsed) {
+    if (!parsed)
+        return null;
+    const deferredObjects = positiveNumberOrZero(parsed.raw_evidence_deferred_object_budget);
+    if (deferredObjects <= 0)
+        return null;
+    const deferredBytes = positiveNumberOrZero(parsed.raw_evidence_deferred_byte_budget);
+    const failedCount = positiveNumberOrZero(parsed.raw_evidence_failed_count);
+    const retryReasons = Array.isArray(parsed.raw_evidence_retry_reasons)
+        ? parsed.raw_evidence_retry_reasons.length
+        : 0;
+    const sessions = asRecord(parsed.codex_sessions);
+    const reportPosted = sessions?.["report_posted"];
+    const codexReadFailures = positiveNumberOrZero(asRecord(sessions?.["codex"])?.["read_failures"]);
+    const claudeSessions = asRecord(sessions?.["claude"]);
+    const claudeReadFailures = positiveNumberOrZero(claudeSessions?.["read_failures"]);
+    const claudeSidecarsFailed = positiveNumberOrZero(claudeSessions?.["sidecars_failed"]);
+    const onlyDeferredObjectBudget = deferredBytes === 0 &&
+        failedCount === 0 &&
+        retryReasons === 0 &&
+        reportPosted === true &&
+        codexReadFailures === 0 &&
+        claudeReadFailures === 0 &&
+        claudeSidecarsFailed === 0;
+    return onlyDeferredObjectBudget ? { remainingObjects: deferredObjects } : null;
+}
+/**
+ * BLI-4303: a sync that stood aside for whoever already owns the collection
+ * lock, and whether that owner is still alive.
+ *
+ * The receipt's `held_since` is the holder's last heartbeat, refreshed every
+ * 30 s by the running process itself, and a lock whose heartbeat goes older
+ * than `SYNC_LOCK_STALE_TAKEOVER_MS` is taken over by the next sync. So a
+ * heartbeat inside that window is a live collection run and the honest answer
+ * for the row is "this machine is collecting"; a heartbeat outside it (or none
+ * at all, which is what a lock file this machine could not create looks like —
+ * see `sync-lock.ts`) is a machine that owes a person a look.
+ *
+ * Pure so both verdicts are testable off a recorded receipt.
+ */
+export function syncStandAsideVerdict(parsed, status, now = new Date()) {
+    const code = (typeof parsed?.status === "string" ? parsed.status : null) ?? status;
+    if (!isCollectionBusyReason(code))
+        return null;
+    const heldSince = typeof parsed?.held_since === "string" ? parsed.held_since : null;
+    const heartbeatMs = heldSince ? Date.parse(heldSince) : Number.NaN;
+    const ownerAlive = Number.isFinite(heartbeatMs) &&
+        now.getTime() - heartbeatMs <= SYNC_LOCK_STALE_TAKEOVER_MS;
+    return { code: code, heldSince, ownerAlive };
+}
+function positiveNumberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : 0;
+}