@bli-cockpit/cli 0.2.99 → 0.2.101

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;
+}

package/dist/commands/doctor-pipeline.js

@@ -1,9 +1,9 @@
+import { withDoctorLockWait } from "./doctor-lock-wait.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectBackfillLock } from "../backfill-lock.js";
-import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
-import { describeError } from "../health-detail.js";
 import { runStagingPrune } from "../disk-prune.js";
 import { retentionOptionsFromEnv } from "../disk-retention.js";
 import { readDiskFootprint } from "../disk-usage.js";
@@ -13,7 +13,8 @@ import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.
 import { runBackfillCommand } from "./backfill.js";
 import { diskRowMessage, mib, redeliveryLine } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
-import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, parseDoctorSyncJson, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";
+import { fail, needsFix, ok, skipped } from "./doctor-report.js";
 /**
  * The `backfill-complete`, `gc-checked`, `disk-bounded`, and `sync-fresh`
  * check family: does the collection pipeline itself have everything it
@@ -22,33 +23,17 @@ import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
  * is committed, disk-bounded reads per-file against the upload ledger
  * (BLI-3619), and sync-fresh is the one check whose "fix" is a live proof
  * (`cockpit sync`) rather than a local computation.
- */
-const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
-/**
- * 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: a marker whose only outstanding entries are deterministic
- * oversized-file skips is still a completed backfill — it reads green with a
- * named note, never a red `needs_fix`/`fail`, so an unliftable file cap never
- * reads as "backfill never completed" on repeat doctor runs.
+ * This module is the half that TOUCHES the machine: it runs the catch-up,
+ * prunes the disk, execs a sync. The verdicts those steps reach — what a
+ * completion marker proves, what a stand-aside receipt means, when an
+ * unfinished backfill is busy rather than broken — are pure functions in
+ * `doctor-pipeline-verdicts.ts`, and every one of them is re-exported from
+ * here so callers keep one address.
  */
-export function backfillCompletionStepState(marker, roots) {
-    if (!backfillCompletionCovers(marker, roots, ["codex", "claude_code"])) {
-        return null;
-    }
-    const oversized = marker?.oversized_skips;
-    if (oversized && oversized.count > 0) {
-        return ok("backfill-complete", "complete_with_oversized_skips", `caught up on old Codex and Claude sessions in every saved folder ` +
-            `(complete_with_oversized_skips · ${oversized.count} file${oversized.count === 1 ? "" : "s"} too big to upload)`);
-    }
-    return ok("backfill-complete", "complete", "caught up on old Codex and Claude sessions in every saved folder");
-}
+const GC_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export async function checkBackfillState(context) {
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const roots = await doctorRoots(context);
     const marker = await readBackfillCompletionMarker(paths);
     const covered = backfillCompletionStepState(marker, roots);
@@ -62,15 +47,20 @@ export async function checkBackfillState(context) {
     return needsFix("backfill-complete", cursor.updated_at ? "partial" : "never_run", "the catch-up over your old sessions has not finished");
 }
 export async function fixBackfillState(context) {
+    return withDoctorLockWait(context, () => runBackfillRepair(context));
+}
+async function runBackfillRepair(context) {
     const capture = capturedIo(context.io, !context.command.json);
     const code = await runBackfillCommand({
+        homeDir: context.command.homeDir,
         repoRoot: context.command.repoRoot,
         all: true,
         dryRun: false,
         yes: true,
         json: true,
     }, capture.io);
-    const output = capture.stdout() + "\n" + capture.stderr();
+    const stdout = capture.stdout();
+    const output = `${stdout}\n${capture.stderr()}`;
     if (code === 0) {
         // Re-read the marker this run just wrote instead of hand-rolling a second
         // message: `checkBackfillState`'s pure core already knows how to say
@@ -79,19 +69,17 @@ export async function fixBackfillState(context) {
         const recheck = await checkBackfillState(context);
         if (recheck.status === "ok")
             return recheck;
-        return ok("backfill-complete", "completed", "ran `cockpit backfill --all --yes`");
+        return recheck;
     }
-    const reason = jsonField(output, "failure_reason");
-    if (reason === "backfill_already_running") {
-        return fail("backfill-complete", "backfill_already_running", "backfill lock is still held and no scope-valid completion marker exists");
-    }
-    return fail("backfill-complete", reason ?? "backfill_failed", "backfill did not complete");
+    const verdict = backfillFixVerdict(parseDoctorBackfillJson(stdout), jsonField(output, "failure_reason"));
+    console.error("[cockpit-doctor] catch-up run did not finish", JSON.stringify({ reason: verdict.code, row_status: verdict.status, exit_code: code }));
+    return verdict;
 }
 export async function checkGcState(context) {
     if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
         return skipped("gc-checked", "skipped_disabled", "cleanup is switched off");
     }
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const marker = path.join(paths.state_dir, ".last-raw-evidence-gc");
     const info = await fs.stat(marker).catch(() => null);
     if (info && Date.now() - info.mtimeMs < GC_MIN_INTERVAL_MS) {
@@ -100,7 +88,7 @@ export async function checkGcState(context) {
     return needsFix("gc-checked", "due", "cleanup is due");
 }
 export async function fixGcState(context) {
-    const result = await runRawEvidenceLocalGc(getCollectorRuntimePaths(), context.io.env);
+    const result = await runRawEvidenceLocalGc(getCollectorRuntimePaths(context.command.homeDir), context.io.env);
     if (result.skipped) {
         return skipped("gc-checked", "skipped_throttled", "cleanup already ran today");
     }
@@ -196,11 +184,6 @@ function captureStream(target, chunks, forward) {
         },
     };
 }
-function jsonField(output, field) {
-    const escaped = field.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-    const match = output.match(new RegExp(`"${escaped}"\\s*:\\s*"([^"]+)"`, "u"));
-    return match?.[1] ?? null;
-}
 export async function checkSyncState(context) {
     const roots = await doctorRoots(context);
     if (roots.length === 0) {
@@ -211,76 +194,10 @@ export async function checkSyncState(context) {
     // and only turns green from those command receipts.
     return needsFix("sync-fresh", "per_root_verification_required", `fresh upload proof is required for ${roots.length} saved root${roots.length === 1 ? "" : "s"}`);
 }
-/**
- * `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).
- */
-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;
-}
-function positiveNumberOrZero(value) {
-    return typeof value === "number" && Number.isFinite(value) && value > 0
-        ? value
-        : 0;
-}
 export async function fixSyncState(context) {
+    return withDoctorLockWait(context, () => runSyncRepair(context));
+}
+async function runSyncRepair(context) {
     const exec = context.io.exec;
     if (!exec)
         return fail("sync-fresh", "runner_unavailable", "sync runner unavailable");
@@ -294,6 +211,8 @@ export async function fixSyncState(context) {
     const discoveryArgs = await savedDiscoveryLimitArgs(context.command.homeDir);
     for (const repoRoot of roots) {
         const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
+        if (context.command.homeDir)
+            args.push("--home", context.command.homeDir);
         if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
             args.push("--dashboard-url", context.command.dashboardUrl);
         }
@@ -301,6 +220,21 @@ export async function fixSyncState(context) {
         const parsed = parseDoctorSyncJson(result.stdout);
         const output = `${result.stdout}\n${result.stderr}`;
         const status = jsonField(output, "status");
+        // BLI-4303, before any verdict: a sync that stood aside for the collection
+        // lock never ran, so neither its exit code nor its missing `uploaded`
+        // receipt says anything about this machine's health.
+        const standAside = syncStandAsideVerdict(parsed, status);
+        if (standAside) {
+            console.error("[cockpit-doctor] sync stood aside for a running collection run", JSON.stringify({
+                reason: standAside.code,
+                owner_alive: standAside.ownerAlive,
+                held_since: standAside.heldSince,
+            }));
+            return needsFix("sync-fresh", standAside.code, "waiting for the collection lock");
+        }
+        if (status === "live_sync_paused_during_backfill") {
+            return needsFix("sync-fresh", status, "waiting for historical catch-up");
+        }
         if (result.code !== 0) {
             const draining = syncBacklogDrainingVerdict(parsed);
             if (draining) {
@@ -317,4 +251,8 @@ export async function fixSyncState(context) {
     return ok("sync-fresh", "synced", roots.length === 1
         ? "ran `cockpit sync` and received an uploaded receipt"
         : `received uploaded receipts for ${roots.length} saved roots`);
-}
+}
+// Re-exported so `doctor.ts`, the doctor tests and every other caller keep
+// importing these from `./doctor-pipeline.js` regardless of which sibling
+// computes them.
+export { backfillCompletionStepState, backfillFixVerdict, isCollectionBusyReason, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";

package/dist/commands/doctor-registration.js

@@ -1,3 +1,5 @@
+import { inspectAgentRules, installAgentRules } from "../agent-rules.js";
+import { doctorRoots } from "./doctor-access.js";
 import { installAutostartAgent } from "../autostart.js";
 import { fail, needsFix, ok, skipped } from "./doctor-report.js";
 import { autostartDoctorStatus, autostartRegistrationRoots, readAutostartRegistration, } from "./autostart-reading.js";
@@ -38,6 +40,8 @@ export async function fixAutostartState(context) {
     // fix that registers a different boundary than the check inspected would
     // leave the row red forever (BLI-3793).
     const roots = await autostartRegistrationRoots(context.command.homeDir, context.command.repoRoot);
+    if (roots.length === 0)
+        return needsFix("autostart-alive", "no_roots", "Run `cockpit doctor` to choose approved collection roots first.");
     const result = await installAutostartAgent({
         ...(roots[0] ? { repoRoot: roots[0] } : {}),
         repoRoots: roots,
@@ -67,7 +71,13 @@ export async function checkMemoryState(context) {
     return memoryStepState(outcome, "check");
 }
 export async function fixMemoryState(context) {
-    const outcome = await installMemoryIntegration(memoryCommandFor(context), context.io);
+    let outcome = await installMemoryIntegration(memoryCommandFor(context), context.io);
+    if (!outcome.bin_found) {
+        // The public CLI declares the memory and Tower MCP packages as dependencies.
+        // Reinstall through the existing updater to restore missing package files.
+        await context.deps.selfUpdate(context.io, { json: true, tag: context.command.updateTag });
+        outcome = await installMemoryIntegration(memoryCommandFor(context), context.io);
+    }
     return memoryStepState(outcome, "fix");
 }
 function memoryCommandFor(context) {
@@ -95,7 +105,18 @@ function memoryStepState(outcome, phase) {
         return needsFix("memory-registered", "registration_incomplete", `BLI Memory is not registered with ${pending.map((target) => target.target).join(", ")}`);
     }
     if (!outcome.bin_found) {
-        return skipped("memory-registered", "bin_missing", "bli-memory-mcp is not on this machine yet; nothing was written and the next run will try again");
+        return needsFix("memory-registered", "bin_missing", "bli-memory-mcp is not on this machine yet; nothing was written and the next run will try again");
     }
     return ok("memory-registered", phase === "fix" ? "installed" : "already_installed", "BLI Memory is registered with both agent hosts");
+}
+export async function checkDoctorAgentRules(context) {
+    const result = await inspectAgentRules({ homeDir: context.command.homeDir, scopePaths: await doctorRoots(context) });
+    return result.installed ? ok("agent-rules", "installed", "agent rules are installed for both hosts") : needsFix("agent-rules", "missing", "run `cockpit agent-rules install`");
+}
+export async function fixDoctorAgentRules(context) {
+    const roots = await doctorRoots(context);
+    if (roots.length === 0)
+        return needsFix("agent-rules", "no_roots", "Run `cockpit doctor` to choose approved roots first.");
+    await installAgentRules({ homeDir: context.command.homeDir, scopePaths: roots });
+    return checkDoctorAgentRules(context);
 }

package/dist/commands/doctor-report.js

@@ -1,3 +1,4 @@
+import { setupReceiptPieces } from "@bli-cockpit/telemetry-core";
 import { redactedHealthDetail } from "../health-detail.js";
 import { setupReceiptBlock } from "./setup-receipt-lines.js";
 export function ok(id, code, message) {
@@ -28,9 +29,9 @@ export function isInteractiveDoctorFix(context) {
     return !context.command.json && Boolean(context.io.stdin.isTTY);
 }
 export async function maybeReportDoctorEvents(context, rows) {
-    if (context.command.dryRun)
-        return;
-    await context.deps.reportInstallEvents({
+    if (context.command.dryRun || context.command.checkOnly)
+        return null;
+    return context.deps.reportInstallEvents({
         dashboardUrl: context.command.dashboardUrl,
         command: "doctor",
         events: rows.map(doctorEvent),
@@ -40,14 +41,17 @@ export async function maybeReportDoctorEvents(context, rows) {
 }
 export function writeDoctorOutput(command, io, rows, 
 /** BLI-3731. Absent means it could not be read; doctor says so rather than nothing. */
-setupReceipt) {
+setupReceipt, repairs = []) {
+    const needsPerson = doctorNeedsPerson(rows, setupReceipt);
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({
-            status: rows.some((row) => row.status === "fail" || row.hardStop)
+            status: needsPerson.length > 0
                 ? "blocked"
                 : "pass",
             dry_run: command.dryRun,
             steps: rows,
+            repairs,
+            needs_person: needsPerson,
             setup_receipt: setupReceipt?.receipt ?? null,
             memory_install: setupReceipt?.memory ?? null,
         }, null, 2));
@@ -58,13 +62,13 @@ setupReceipt) {
     // sentence, not the label (BLI-3194).
     writeLine(io.stdout, "state step                 result");
     for (const row of rows) {
-        writeLine(io.stdout, `${doctorMark(row)} ${row.id.padEnd(20)} ${oneLine(row.message)}`);
+        writeLine(io.stdout, `${doctorMark(row)} ${row.id.padEnd(20)} ${oneLine(row.message).replaceAll("—", ";")}`);
     }
     const explanations = rows.filter((row) => (row.hardStop || row.status === "fail") && row.message.includes("\n"));
     for (const row of explanations) {
         writeLine(io.stderr, "");
         writeLine(io.stderr, `${row.id}:`);
-        writeLine(io.stderr, row.message);
+        writeLine(io.stderr, row.message.replaceAll("—", ";"));
     }
     // BLI-3731. The invariant table says whether collection is healthy; this
     // says whether the machine is CONNECTED — the browser sign-in, the device
@@ -75,11 +79,14 @@ setupReceipt) {
     for (const line of setupReceipt
         ? setupReceiptBlock(setupReceipt, { indent: "  " })
         : ["  unknown — this machine could not be read this run."]) {
-        writeLine(io.stdout, line);
+        writeLine(io.stdout, line.replaceAll("—", ";"));
     }
+    writeLine(io.stdout, needsPerson.length === 0 ? "Everything is fixed." : `${needsPerson.length} things still need you:`);
+    for (const item of needsPerson)
+        writeLine(io.stdout, `  ${item.step}: ${item.action}`);
 }
 function doctorEvent(row) {
-    const status = row.status === "fail" || row.hardStop
+    const status = row.status === "fail" || row.status === "needs_fix" || row.hardStop
         ? "fail"
         : row.status === "skipped"
             ? "skipped"
@@ -124,4 +131,36 @@ export function asRecord(value) {
 }
 export function writeLine(stream, text) {
     stream.write(`${text}\n`);
+}
+export function doctorNeedsPerson(rows, receipt) {
+    const defaults = {
+        "cli-latest": "npm install -g @bli-cockpit/cli@latest",
+        "authed": "cockpit login",
+        "roots-ok": "cockpit doctor",
+        "single-install": "Run npm uninstall -g @bli-cockpit/cli with the Node installation that owns the extra CLI listed above.",
+        "autostart-alive": "cockpit autostart install",
+        "memory-registered": "cockpit memory install",
+        "agent-rules": "cockpit agent-rules install",
+        "mcp-answers": "cockpit doctor",
+        "memory-daemon": "cockpit memory install",
+        "backfill-complete": "cockpit backfill --all --yes",
+        "sync-fresh": "cockpit sync --json",
+        "gc-checked": "cockpit doctor",
+        "disk-bounded": "cockpit clean --all-committed",
+    };
+    const items = rows.filter((row) => row.status === "fail" || row.status === "needs_fix" || row.hardStop).map((row) => ({
+        step: row.id, reason: row.code,
+        action: row.nextAction ?? row.message.match(/`([^`]+)`/u)?.[1] ?? defaults[row.id],
+    }));
+    if (receipt) {
+        for (const { key, piece } of setupReceiptPieces(receipt.receipt, receipt.memory)) {
+            if (piece.status === "ok" || piece.status === "skipped" || piece.status === "unsupported")
+                continue;
+            const step = key === "device" || key === "browser" ? "authed" : key === "collector.autostart" ? "autostart-alive" : "memory-registered";
+            if (piece.status !== "needs_trust" && items.some((item) => item.step === step))
+                continue;
+            items.push({ step: key, reason: piece.reason ?? piece.status, action: piece.status === "needs_trust" ? "Open Codex and run /hooks to trust the installed hooks." : defaults[step] });
+        }
+    }
+    return items;
 }