@bli-cockpit/cli 0.2.100 → 0.2.102

package/dist/agent-rules.js

@@ -141,13 +141,14 @@ export function cockpitAgentRulesBlock(options = {}) {
         ? `- Only applies when the current working directory is inside the Tower-onboarded workspace/repo: \`${scopePaths[0]}\`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.`
         : scopePaths.length > 1
             ? `- Only applies when the current working directory is inside one of these Tower-onboarded workspace roots: ${scopePaths.map((scopePath) => `\`${scopePath}\``).join(", ")}. Outside those folders, do not run Tower ticket binding or sync commands for private chats or unrelated repos.`
-            : "- Only applies when the current working directory is inside the workspace/repo that ran `cockpit onboard` or `cockpit agent-rules install`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.";
+            : "- Only applies when the current working directory is inside the workspace/repo that ran `cockpit doctor` or `cockpit agent-rules install`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.";
     return [
         MANAGED_BLOCK_START,
         "## Tower Ticket Binding",
         "",
         scopeLine,
         "- Ticketed work (implement / debug / review / PR / ship): run `cockpit start --ticket <ticket-id> --workspace \"$PWD\"` before the first code edit (the flag is `--ticket`). No ticket ID visible → search Linear first; none exists and the work is ticket-worthy → create a narrow Linear ticket, then bind.",
+        "- If setup or collection needs repair, run `cockpit doctor`. It repairs this machine and prints any remaining action.",
         "- Truly no ticket → say the session stays in general ambient capture; never invent one.",
         "- After the first meaningful checkpoint, run `cockpit sync --workspace \"$PWD\" --json`.",
         "",

package/dist/backfill-lock.js

@@ -54,7 +54,7 @@ export async function inspectBackfillLock(paths, now = new Date()) {
         now.getTime() - record.heartbeat_ms > BACKFILL_LOCK_STALE_TAKEOVER_MS) {
         return { held: false, held_since: null };
     }
-    return { held: true, held_since: record.heartbeat_at };
+    return { held: true, held_since: record.heartbeat_at, pid: record.pid };
 }
 export function backfillLockPath(paths) {
     return path.join(paths.cursors_dir, BACKFILL_LOCK_FILENAME);

package/dist/commands/doctor-access.js

@@ -1,5 +1,7 @@
+import { sendCollectorHeartbeatBestEffort } from "./heartbeat.js";
+import { isInteractiveDoctorFix } from "./doctor-report.js";
 import { describeError } from "../health-detail.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, toSessionReference, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
 import { detectSecondCockpitInstall } from "../second-install.js";
 import { hardStop, needsFix, ok, skipped } from "./doctor-report.js";
@@ -12,6 +14,21 @@ import { hardStop, needsFix, ok, skipped } from "./doctor-report.js";
  * operator decide.
  */
 export async function fixAuthState(context, state) {
+    const renewed = await sendCollectorHeartbeatBestEffort({
+        homeDir: context.command.homeDir,
+        dashboardUrl: context.command.dashboardUrl,
+        roots: await doctorRoots(context),
+        facts: { status: "skipped", reason: "doctor_auth_renewal" },
+        io: context.io,
+    });
+    if (renewed) {
+        context.authVerified = true;
+        const checked = await context.deps.readAuth(context);
+        if (checked.status === "ok")
+            return checked;
+    }
+    if (!isInteractiveDoctorFix(context))
+        return { ...state, nextAction: "cockpit login" };
     const code = await context.deps.runLogin(context).catch((error) => {
         // Exit code 1 with no reason at all is what an operator saw when doctor
         // tried and failed to repair their auth — the same output as a login that
@@ -24,6 +41,7 @@ export async function fixAuthState(context, state) {
     });
     if (code !== 0)
         return state;
+    context.authVerified = true;
     const checked = await context.deps.readAuth(context);
     return checked.status === "ok" ? checked : state;
 }
@@ -42,11 +60,14 @@ export async function fixRootState(context, state) {
     return checked.status === "ok" ? checked : state;
 }
 export async function readAuthState(context) {
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
-    if (session?.session_state === "valid" &&
+    if (session && toSessionReference(session).session_state === "valid" &&
         typeof session.device_token === "string" &&
         session.device_token) {
+        if (!context.command.checkOnly && !context.command.dryRun && !context.authVerified) {
+            return needsFix("authed", "token_validation_required", "checking that the saved device token is accepted");
+        }
         return ok("authed", "device_token_present", "this machine is signed in");
     }
     return hardStop("authed", "pairing_required", [
@@ -58,10 +79,11 @@ export async function readAuthState(context) {
     ].join("\n"));
 }
 export async function readRootState(context) {
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => null);
     const roots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
-    if (roots.length > 0) {
+    const requested = normalizeCollectionRoots(context.command.collectionRoots ?? (context.command.repoRoot ? [context.command.repoRoot] : []));
+    if (roots.length > 0 && requested.every((root) => roots.includes(root))) {
         return {
             ...ok("roots-ok", "saved_roots_present", `saved roots: ${roots.join(", ")}`),
             roots,
@@ -72,7 +94,7 @@ export async function readRootState(context) {
         "What you can do:",
         `  1) Run \`${onboardOneLiner(context.command)}\` to save the workspace roots again.`,
         "  2) If this is the wrong folder, rerun from the BLI workspace or pass `--workspace <path>`.",
-        "  3) There is no `--repair` flag; the onboard-rerun is the repair path.",
+        "  3) Run `cockpit doctor` interactively to choose approved roots.",
     ].join("\n"));
 }
 /**
@@ -107,12 +129,14 @@ export async function checkSingleInstallState(context) {
     ].join("\n"));
 }
 export async function doctorRoots(context) {
+    if (context.command.collectionRoots?.length)
+        return context.command.collectionRoots;
     if (context.command.repoRoot)
         return [context.command.repoRoot];
-    return savedRoots();
+    return savedRoots(context.command.homeDir);
 }
-export async function savedRoots() {
-    const config = await readLocalCollectorConfig(getCollectorRuntimePaths()).catch(() => null);
+export async function savedRoots(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
     return normalizeCollectionRoots(config?.default_repo_paths ?? []);
 }
 function onboardOneLiner(command) {
@@ -120,7 +144,7 @@ function onboardOneLiner(command) {
     const dashboard = command.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
         : ` --dashboard-url ${shellQuote(command.dashboardUrl)}`;
-    return `cockpit onboard --workspace ${shellQuote(workspace)}${dashboard}`;
+    return `cockpit doctor --workspace ${shellQuote(workspace)}${dashboard}`;
 }
 function shellQuote(value) {
     if (value === "$PWD")

package/dist/commands/doctor-lock-wait.js

@@ -0,0 +1,46 @@
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { inspectSyncLock } from "../sync-lock.js";
+const BUSY = new Set(["sync_already_running", "backfill_already_running", "live_sync_paused_during_backfill"]);
+/** Retry the operation itself: its existing exclusive lock acquisition owns the
+ * handoff. Merely observing a free lock never grants permission to collect. */
+export async function withDoctorLockWait(context, run, timing = { now: () => Date.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+    const started = timing.now();
+    const limit = (context.command.lockWaitSeconds ?? 600) * 1000;
+    let nextProgress = 0;
+    let row = await run();
+    while (BUSY.has(row.code)) {
+        const paths = getCollectorRuntimePaths(context.command.homeDir);
+        const sync = await inspectSyncLock(paths);
+        const backfill = await inspectBackfillLock(paths);
+        const owner = backfill.held
+            ? { pid: backfill.pid, heartbeat_at: backfill.held_since }
+            : sync;
+        const elapsed = timing.now() - started;
+        if (elapsed >= limit) {
+            const pid = owner?.pid;
+            let name = "unknown process";
+            if (pid && pid > 0 && context.io.exec) {
+                const result = process.platform === "win32"
+                    ? await context.io.exec("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"])
+                    : await context.io.exec("ps", ["-p", String(pid), "-o", "comm="]);
+                if (result.code === 0 && result.stdout.trim())
+                    name = result.stdout.trim().split("\n")[0] ?? name;
+            }
+            return { ...row, status: "needs_fix", code: "lock_wait_timeout", nextAction: "cockpit doctor --lock-wait 600", message: `Waited ${Math.round(elapsed / 1000)}s for the collection lock; owner pid ${pid ?? "unknown"}, ${name}. Run \`cockpit doctor --lock-wait 600\`.` };
+        }
+        if (elapsed >= nextProgress) {
+            const seconds = Math.floor(elapsed / 1000);
+            console.error(`[doctor] ${row.id} waiting`, JSON.stringify({ reason: row.code, owner_pid: owner?.pid ?? null, heartbeat_at: owner?.heartbeat_at ?? null, elapsed_seconds: seconds }));
+            context.io.stderr.write(`waiting for the background sync to finish, ${Math.floor(seconds / 60)}m${seconds % 60}s\n`);
+            nextProgress = elapsed + 30_000;
+        }
+        await timing.sleep(Math.min(1000, limit - elapsed));
+        // A live heartbeat means there is no point spawning a collector yet.
+        const currentSync = await inspectSyncLock(paths);
+        const currentBackfill = await inspectBackfillLock(paths);
+        if (!currentSync?.held && !currentBackfill.held)
+            row = await run();
+    }
+    return row;
+}

package/dist/commands/doctor-pipeline.js

@@ -1,3 +1,4 @@
+import { withDoctorLockWait } from "./doctor-lock-wait.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectBackfillLock } from "../backfill-lock.js";
@@ -13,7 +14,7 @@ import { runBackfillCommand } from "./backfill.js";
 import { diskRowMessage, mib, redeliveryLine } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
 import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, parseDoctorSyncJson, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";
-import { fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { asRecord, 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
@@ -32,7 +33,7 @@ import { fail, needsFix, ok, skipped } from "./doctor-report.js";
  */
 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);
@@ -46,35 +47,75 @@ 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) {
-    const capture = capturedIo(context.io, !context.command.json);
-    const code = await runBackfillCommand({
-        repoRoot: context.command.repoRoot,
-        all: true,
-        dryRun: false,
-        yes: true,
-        json: true,
-    }, capture.io);
-    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
-        // "complete" vs "complete_with_oversized_skips" (BLI-2727), and this way
-        // the two can never say something different for the same marker.
-        const recheck = await checkBackfillState(context);
-        if (recheck.status === "ok")
-            return recheck;
-        return ok("backfill-complete", "completed", "ran `cockpit backfill --all --yes`");
+    const started = Date.now();
+    const deadline = started + (context.command.backfillBudgetSeconds ?? 900) * 1000;
+    let caughtUp = 0;
+    let remaining = null;
+    const unfinished = (code, reason) => ({
+        ...needsFix("backfill-complete", code, `caught up on ${caughtUp} old sessions this run, ${remaining ?? "unknown"} still to go; ${reason}; run \`cockpit doctor\` again to continue`),
+        nextAction: "cockpit doctor",
+    });
+    const progress = setInterval(() => {
+        const seconds = Math.floor((Date.now() - started) / 1000);
+        context.io.stderr.write(`backfill: ${caughtUp} caught up, ${remaining ?? "unknown"} to go, ${Math.floor(seconds / 60)}m${seconds % 60}s\n`);
+        console.error("[doctor] backfill-complete progress", JSON.stringify({ caught_up: caughtUp, remaining, elapsed_seconds: seconds }));
+    }, 30_000);
+    try {
+        while (Date.now() < deadline) {
+            // Every chunk reacquires the collector's locks. Bound lock waiting by
+            // the overall budget too; never abandon an in-flight cursor write.
+            const chunkContext = { ...context, command: { ...context.command,
+                    lockWaitSeconds: Math.min(context.command.lockWaitSeconds ?? 600, (deadline - Date.now()) / 1000),
+                } };
+            const row = await withDoctorLockWait(chunkContext, async () => {
+                if (Date.now() >= deadline)
+                    return unfinished("backfill_budget_timeout", "backfill time budget reached");
+                const capture = capturedIo(context.io, false);
+                const code = await runBackfillCommand({
+                    homeDir: context.command.homeDir, repoRoot: context.command.repoRoot,
+                    all: true, dryRun: false, yes: true, json: true,
+                }, capture.io);
+                const parsed = parseDoctorBackfillJson(capture.stdout());
+                const counts = asRecord(parsed?.counts);
+                const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+                caughtUp += count(counts?.["backfilled"]) ?? 0;
+                remaining = count(counts?.["remaining"]) ?? remaining;
+                if (code === 0 && parsed?.status === "complete") {
+                    // Reporting totals include permanent caps. Preserve their marker
+                    // note instead of retrying history the collector says is complete.
+                    const checked = await checkBackfillState(context);
+                    return ok("backfill-complete", checked.status === "ok" ? checked.code : "complete", `caught up on ${caughtUp} old sessions this run` + (checked.status === "ok" ? `; ${checked.message}` : ""));
+                }
+                const verdict = backfillFixVerdict(parsed, jsonField(capture.stderr(), "failure_reason"));
+                if (parsed?.status === "partial" &&
+                    (parsed.failure_reason === "deferred_budget_exhausted" || !parsed.failure_reason)) {
+                    return needsFix("backfill-complete", "backfill_chunk_pending", "more history remains");
+                }
+                return { ...verdict, message: typeof parsed?.failure_reason === "string" ? parsed.failure_reason : "backfill failed without a valid completion receipt" };
+            });
+            if (row.status === "ok") {
+                console.error("[doctor] backfill-complete finished", JSON.stringify({ caught_up: caughtUp, remaining, elapsed_seconds: Math.floor((Date.now() - started) / 1000) }));
+                return row;
+            }
+            if (row.code !== "backfill_chunk_pending") {
+                return unfinished(row.code === "lock_wait_timeout" && Date.now() >= deadline ? "backfill_budget_timeout" : row.code, row.message);
+            }
+        }
+        return unfinished("backfill_budget_timeout", "backfill time budget reached");
+    }
+    catch (error) {
+        console.error("[doctor] backfill-complete failed", JSON.stringify({ reason: "backfill_threw", error_name: error instanceof Error ? error.name : "unknown" }));
+        return unfinished("backfill_threw", "backfill failed");
+    }
+    finally {
+        clearInterval(progress);
     }
-    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) {
@@ -83,7 +124,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");
     }
@@ -190,6 +231,9 @@ export async function checkSyncState(context) {
     return needsFix("sync-fresh", "per_root_verification_required", `fresh upload proof is required for ${roots.length} saved root${roots.length === 1 ? "" : "s"}`);
 }
 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");
@@ -203,6 +247,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);
         }
@@ -220,12 +266,10 @@ export async function fixSyncState(context) {
                 owner_alive: standAside.ownerAlive,
                 held_since: standAside.heldSince,
             }));
-            return standAside.ownerAlive
-                ? ok("sync-fresh", standAside.code, "a background sync is running right now and owns the collection lock " +
-                    `(last heartbeat ${standAside.heldSince}); this machine is collecting`)
-                : needsFix("sync-fresh", standAside.code, "sync stood aside for a collection lock whose owner has stopped " +
-                    `reporting (last heartbeat ${standAside.heldSince ?? "unknown"}); ` +
-                    "rerun `cockpit doctor` — the next sync takes the lock over");
+            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);

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

package/dist/commands/doctor-update.js

@@ -1,3 +1,4 @@
+import { isSemverBelow } from "../scheduled-self-update.js";
 import { DEFAULT_DASHBOARD_URL, LOCAL_COLLECTOR_VERSION } from "../local-state.js";
 import { createInteractiveExecRunner } from "../process-runner.js";
 import { asRecord, fail, needsFix, ok } from "./doctor-report.js";
@@ -11,7 +12,7 @@ export async function checkCliLatest(context) {
     if (!latest) {
         return needsFix("cli-latest", "latest_version_unknown", `could not confirm npm latest; will run npm install for ${LOCAL_COLLECTOR_VERSION}`);
     }
-    if (latest === LOCAL_COLLECTOR_VERSION) {
+    if (latest === LOCAL_COLLECTOR_VERSION || (!context.command.updateTag && /^\d+\.\d+\.\d+$/u.test(latest) && !isSemverBelow(LOCAL_COLLECTOR_VERSION, latest))) {
         return ok("cli-latest", "already_latest", `current ${LOCAL_COLLECTOR_VERSION}`);
     }
     return needsFix("cli-latest", "stale_cli", `current ${LOCAL_COLLECTOR_VERSION}; npm latest ${latest}`);
@@ -28,7 +29,7 @@ export async function fixCliLatest(context, state) {
     }
     if (context.io.env["COCKPIT_DOCTOR_REEXEC"] === "1") {
         if (state.code === "stale_cli") {
-            return fail("cli-latest", "stale_after_self_update", "self-update ran but this process still reports the old CLI version; rerun `cockpit do-everything`.");
+            return fail("cli-latest", "stale_after_self_update", "self-update ran but this process still reports the old CLI version; rerun `cockpit doctor`.");
         }
         return ok("cli-latest", "updated_reexec_guarded", "self-update ran; re-exec guard already set, continuing.");
     }
@@ -67,9 +68,21 @@ function parseNpmVersion(stdout) {
     }
 }
 export function reexecDoctor(command, io) {
-    const args = ["do-everything"];
-    if (command.repoRoot)
-        args.push("--workspace", command.repoRoot);
+    const args = ["doctor"];
+    if (command.homeDir)
+        args.push("--home", command.homeDir);
+    if (command.backfillBudgetSeconds)
+        args.push("--backfill-budget", String(command.backfillBudgetSeconds));
+    if (command.lockWaitSeconds)
+        args.push("--lock-wait", String(command.lockWaitSeconds));
+    if (command.allowHomeRoot)
+        args.push("--allow-home-root");
+    if (command.maxDepth)
+        args.push("--max-depth", String(command.maxDepth));
+    if (command.maxRepos)
+        args.push("--max-repos", String(command.maxRepos));
+    for (const root of command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []))
+        args.push("--workspace", root);
     if (command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
         args.push("--dashboard-url", command.dashboardUrl);
     }

package/dist/commands/doctor.js

@@ -1,11 +1,14 @@
+import { LOCAL_COLLECTOR_VERSION } from "../local-state.js";
+import { isSemverBelow } from "../scheduled-self-update.js";
+import { describeError } from "../health-detail.js";
 import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
 import { backfillCompletionStepState, backfillFixVerdict, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline.js";
 import { checkMcpAnswersState } from "./doctor-mcp.js";
 import { checkMemoryDaemonState } from "./doctor-memory-daemon.js";
-import { checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
-import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, } from "./doctor-report.js";
-import { refreshSetupReceipt } from "./setup-receipt.js";
+import { checkDoctorAgentRules, fixDoctorAgentRules, checkAutostartState, checkMemoryState, fixAutostartState, fixMemoryState, } from "./doctor-registration.js";
+import { dryRunPreview, isInteractiveDoctorFix, maybeReportDoctorEvents, writeDoctorOutput, doctorNeedsPerson, } from "./doctor-report.js";
+import { buildSetupReceipt, refreshSetupReceipt } from "./setup-receipt.js";
 import { checkCliLatest, fixCliLatest, latestCliVersionFromNpm, reexecDoctor, } from "./doctor-update.js";
 export async function runDoctor(command, io, hooks, overrides = {}) {
     const deps = { ...defaultDoctorDeps(hooks), ...overrides };
@@ -14,58 +17,93 @@ export async function runDoctor(command, io, hooks, overrides = {}) {
 export async function runDoctorWithDeps(command, io, deps) {
     const context = { command, io, deps };
     const rows = [];
+    const repairs = [];
+    const diagnoseOnly = command.dryRun || command.checkOnly;
+    const diagnosed = new Map();
     for (const invariant of doctorInvariants()) {
-        const checked = await withStage(`doctor:check:${invariant.id}`, () => invariant.check(context));
-        if (checked.status === "ok" || checked.status === "skipped") {
-            rows.push(checked);
-            continue;
+        try {
+            diagnosed.set(invariant.id, await withStage(`doctor:check:${invariant.id}`, () => invariant.check(context)));
         }
-        if (command.dryRun && invariant.fix) {
-            rows.push(dryRunPreview(checked));
-            continue;
+        catch (error) {
+            console.error(`[doctor] ${invariant.id} diagnosis_failed`, JSON.stringify({ reason: "check_threw", ...describeError(error) }));
+            diagnosed.set(invariant.id, { id: invariant.id, status: "fail", code: "check_threw", message: "Run `cockpit doctor` to retry this check." });
         }
-        const canFix = Boolean(invariant.fix) &&
-            (!invariant.requiresInteractiveFix || isInteractiveDoctorFix(context));
-        if (!canFix || !invariant.fix) {
-            rows.push(withoutAFix(checked));
-            if (checked.hardStop)
-                break;
-            continue;
+    }
+    for (const invariant of doctorInvariants()) {
+        let row;
+        try {
+            row = diagnosed.get(invariant.id);
+            const needsCollection = ["backfill-complete", "sync-fresh"].includes(invariant.id);
+            const prerequisitesReady = !needsCollection || rows.filter((prior) => prior.id === "authed" || prior.id === "roots-ok").every((prior) => prior.status === "ok");
+            const canFix = !diagnoseOnly && prerequisitesReady && invariant.fix &&
+                (!invariant.requiresInteractiveFix || isInteractiveDoctorFix(context) || Boolean(command.collectionRoots?.length));
+            if (row.status !== "ok" && row.status !== "skipped" && canFix && invariant.fix) {
+                row = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, row));
+                repairs.push({ step: invariant.id, outcome: row.status === "ok" ? "repaired" : "needs_person", reason: row.code });
+                // The replacement process owns the one final receipt, including JSON.
+                if (row.reexecExitCode !== undefined)
+                    return row.reexecExitCode;
+                row = { ...row, fixed: row.status === "ok" };
+            }
+            else {
+                repairs.push({ step: invariant.id, outcome: diagnoseOnly ? "check_only" : row.status === "ok" ? "already_ok" : row.status === "skipped" ? "not_needed" : "needs_person", reason: row.code });
+                if (command.dryRun && invariant.fix && row.status !== "ok" && row.status !== "skipped")
+                    row = dryRunPreview(row);
+            }
         }
-        // BLI-4110: named so a crash inside a repair says WHICH repair. The
-        // 2026-09-09 incident printed a bare `read ENOTCONN` stack and the only
-        // way to place it was the log line that happened to precede it.
-        const fixed = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, checked));
-        rows.push({ ...fixed, fixed: fixed.status !== "fail" });
-        if (fixed.hardStop)
-            break;
-        if (fixed.reexecExitCode !== undefined) {
-            await maybeReportDoctorEvents(context, rows);
-            writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
-            return fixed.reexecExitCode;
+        catch (error) {
+            console.error(`[doctor] ${invariant.id} failed`, JSON.stringify({ reason: "step_threw", ...describeError(error) }));
+            row = { id: invariant.id, status: "fail", code: "step_threw", message: "The step could not finish. Run `cockpit doctor`." };
+            repairs.push({ step: invariant.id, outcome: "needs_person", reason: row.code });
         }
+        console.error(`[doctor] ${invariant.id} ${row.status}`, JSON.stringify({ reason: row.code, repaired: row.fixed ?? false }));
+        rows.push(row);
     }
-    await maybeReportDoctorEvents(context, rows);
-    // Doctor is the surface a person opens when something is wrong, so it
-    // re-READS the machine rather than quoting a cache — and caching what it
-    // read is what keeps the 15-minute heartbeat from paying for the probe.
-    writeDoctorOutput(command, io, rows, await deps.readSetupReceipt(context));
-    return rows.some((row) => row.status === "fail" || row.hardStop) ? 1 : 0;
-}
-/**
- * What a broken row looks like when nothing can repair it from here.
- *
- * A check that says `needs_fix` and has no fix is still `needs_fix` — the
- * person is being told what to do. A check that says `fail` KEEPS that word
- * (BLI-3804): it used to be quietly rewritten to `needs_fix`, which turned the
- * run green and, because `doctor-report.ts` maps every non-`fail` row to `ok`
- * in the install-event ledger, threw the reason label away on the way to the
- * fleet as well. `hardStop` is untouched and still ends the walk.
- */
-function withoutAFix(checked) {
-    if (checked.hardStop || checked.status === "fail")
-        return checked;
-    return { ...checked, status: "needs_fix" };
+    // Re-read host state after repairs. Sync is proven by its upload receipts;
+    // re-running its diagnostic would always request a new upload by design.
+    if (!diagnoseOnly) {
+        for (const invariant of doctorInvariants()) {
+            if (["cli-latest", "authed", "roots-ok", "backfill-complete", "sync-fresh", "gc-checked", "disk-bounded"].includes(invariant.id))
+                continue;
+            const index = rows.findIndex((row) => row.id === invariant.id);
+            if (rows[index]?.status === "fail")
+                continue;
+            try {
+                const checked = await invariant.check(context);
+                rows[index] = { ...checked, fixed: rows[index]?.fixed && checked.status === "ok" };
+                console.error(`[doctor] ${invariant.id} verified`, JSON.stringify({ reason: checked.code, status: checked.status }));
+                if (checked.status === "needs_fix" || checked.status === "fail") {
+                    const repair = repairs.find((entry) => entry.step === invariant.id);
+                    if (repair) {
+                        repair.outcome = "needs_person";
+                        repair.reason = checked.code;
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`[doctor] ${invariant.id} recheck_failed`, JSON.stringify({ reason: "recheck_threw", ...describeError(error) }));
+                rows[index] = { id: invariant.id, status: "fail", code: "recheck_threw", message: "Run `cockpit doctor` to retry the host check." };
+            }
+        }
+    }
+    const floor = await maybeReportDoctorEvents(context, rows);
+    if (floor && isSemverBelow(LOCAL_COLLECTOR_VERSION, floor)) {
+        const index = rows.findIndex((row) => row.id === "cli-latest");
+        rows[index] = { id: "cli-latest", status: "needs_fix", code: "below_fleet_floor", message: `This process is below the fleet floor ${floor}. Run \`cockpit doctor\` to update.`, nextAction: "cockpit doctor" };
+        console.error("[doctor] cli-latest below_fleet_floor", JSON.stringify({ reason: "below_fleet_floor", current_version: LOCAL_COLLECTOR_VERSION, minimum_version: floor }));
+    }
+    let receipt = null;
+    if (!command.dryRun) {
+        try {
+            receipt = await deps.readSetupReceipt(context);
+        }
+        catch (error) {
+            console.error("[doctor] setup_receipt failed", JSON.stringify({ reason: "receipt_read_threw", ...describeError(error) }));
+            rows.push({ id: "memory-registered", status: "needs_fix", code: "receipt_read_threw", message: "Run `cockpit doctor` to read the final setup receipt." });
+        }
+    }
+    writeDoctorOutput(command, io, rows, receipt, repairs);
+    return doctorNeedsPerson(rows, receipt).length === 0 ? 0 : 1;
 }
 function doctorInvariants() {
     return [
@@ -74,7 +112,6 @@ function doctorInvariants() {
             id: "authed",
             check: (context) => context.deps.readAuth(context),
             fix: fixAuthState,
-            requiresInteractiveFix: true,
         },
         {
             id: "roots-ok",
@@ -99,6 +136,7 @@ function doctorInvariants() {
             check: (context) => context.deps.checkMemory(context),
             fix: (context, _state) => context.deps.fixMemory(context),
         },
+        { id: "agent-rules", check: (context) => context.deps.checkAgentRules(context), fix: (context) => context.deps.fixAgentRules(context) },
         // BLI-3804. Right after the registration row, because it asks the second
         // half of the same question: `memory-registered` proves the entry exists
         // and names a bin, this one proves the server behind it starts, speaks the
@@ -122,6 +160,11 @@ function doctorInvariants() {
             check: (context) => context.deps.checkBackfill(context),
             fix: (context, _state) => context.deps.fixBackfill(context),
         },
+        {
+            id: "sync-fresh",
+            check: (context) => context.deps.checkSync(context),
+            fix: (context, _state) => context.deps.fixSync(context),
+        },
         {
             id: "gc-checked",
             check: (context) => context.deps.checkGc(context),
@@ -136,15 +179,12 @@ function doctorInvariants() {
             check: (context) => context.deps.checkDisk(context),
             fix: (context, _state) => context.deps.fixDisk(context),
         },
-        {
-            id: "sync-fresh",
-            check: (context) => context.deps.checkSync(context),
-            fix: (context, _state) => context.deps.fixSync(context),
-        },
     ];
 }
 function defaultDoctorDeps(hooks) {
     return {
+        checkAgentRules: checkDoctorAgentRules,
+        fixAgentRules: fixDoctorAgentRules,
         latestCliVersion: latestCliVersionFromNpm,
         selfUpdate: hooks.selfUpdate,
         reexecDoctor: reexecDoctor,
@@ -168,7 +208,7 @@ function defaultDoctorDeps(hooks) {
         fixDisk: fixDiskState,
         checkSync: checkSyncState,
         fixSync: fixSyncState,
-        readSetupReceipt: (context) => refreshSetupReceipt(context.io, {
+        readSetupReceipt: (context) => (context.command.checkOnly ? buildSetupReceipt : refreshSetupReceipt)(context.io, {
             ...(context.command.homeDir ? { homeDir: context.command.homeDir } : {}),
             ...(context.command.dashboardUrl
                 ? { dashboardUrl: context.command.dashboardUrl }

package/dist/commands/local-args-collector-setup.js

@@ -98,6 +98,10 @@ export function parseDoctorArgs(alias, args) {
             "--dashboard-url",
             "--update-tag",
             "--dry-run",
+            "--check",
+            "--no-repair",
+            "--lock-wait",
+            "--backfill-budget",
             "--json",
             "--allow-home-root",
             "--max-depth",
@@ -113,6 +117,8 @@ export function parseDoctorArgs(alias, args) {
             "--timeout-ms",
         ],
         valueFlags: [
+            "--lock-wait",
+            "--backfill-budget",
             "--home",
             "--repo",
             "--workspace",
@@ -135,6 +141,9 @@ export function parseDoctorArgs(alias, args) {
     }
     return {
         kind: "doctor",
+        checkOnly: values.booleans.has("--check") || values.booleans.has("--no-repair"),
+        backfillBudgetSeconds: optionalPositiveInteger(values.flags.get("--backfill-budget"), "--backfill-budget") ?? 900,
+        lockWaitSeconds: optionalPositiveInteger(values.flags.get("--lock-wait"), "--lock-wait") ?? 600,
         alias,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),

package/dist/commands/local-args-tower-usage.js

@@ -1,8 +1,8 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
 export function parseUsageArgs(args) {
-    const values = parseNamedArgs(args, { allowedFlags: ["--since", "--until", "--include-automated", "--home", "--dashboard-url", "--json"], valueFlags: ["--since", "--until", "--home", "--dashboard-url"] });
+    const values = parseNamedArgs(args, { allowedFlags: ["--since", "--until", "--include-automated", "--detail", "--home", "--dashboard-url", "--json"], valueFlags: ["--since", "--until", "--home", "--dashboard-url"] });
     const action = values.positionals[0] ?? "people";
     if (action !== "people" || values.positionals.length > 1)
         throw new Error("usage takes one verb: people.");
-    return { kind: "usage", action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
+    return { kind: "usage", action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), detail: values.booleans.has("--detail"), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
 }

package/dist/commands/local-help-commands-tower.js

@@ -143,12 +143,13 @@ export const TOWER_COMMAND_HELP = [
     [
         "usage",
         [
-            "Usage: cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--json]",
+            "Usage: cockpit usage people [--since <n>d|<n>h|<iso>] [--detail] [--until <iso>] [--include-automated] [--json]",
             "",
             "Claude Code and Codex usage per person: sessions observed and extracted, tokens (total, output,",
             "and the input / cache split when the row carries it), and an API list-price equivalent that is",
             "labelled as such and is never actual spend. A super_admin sees everyone; a member sees their own row.",
-            "--since takes 7d, 30d, 90d or an ISO timestamp; --until an ISO timestamp (default now).",
+            "--since takes <n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp; --until an ISO timestamp (default now).",
+            "--detail adds Output, Input, Cache read and Cache creation. Counts use K/M/B; dollars are rounded.",
             "--include-automated adds harness, subagent and scheduled sessions, which are excluded by default.",
             "It presses the same door as the /usage page and the usage_people MCP tool (GET /api/usage/people).",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",

package/dist/commands/local-help-commands.js

@@ -71,30 +71,43 @@ export function localSubcommandHelp(command) {
         [
             "do-everything",
             [
-                "Usage: cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
+                "Usage: cockpit do-everything [--workspace <path>] [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
                 "",
-                "Gets this machine fully set up, whether it is brand new, already set up, or handed down: latest CLI, sign-in and collection-root recovery when needed, saved folders, background sync, catching up on old sessions, cleaning up old files, and one fresh upload.",
-                "`cockpit fix` is an alias.",
-                "Maintainers only: use `--update-tag next` so self-update and re-exec stay on the prerelease candidate.",
-                "--dry-run shows what it would do without changing anything.",
+                "Diagnose, repair, and verify this machine. doctor, do-everything, and fix run the same job.",
+                "Repairs CLI, background sync, sign-in, roots, memory and hooks, agent rules, catch-up, uploads, and cleanup.",
+                "--check or --no-repair diagnoses without repairs. --dry-run previews repairs.",
+                "--backfill-budget defaults to 900 seconds; catch-up repeats chunks until complete, with progress every 30 seconds.",
+                "--lock-wait defaults to 600 seconds; progress prints every 30 seconds.",
+                "--json includes steps, repairs, and needs_person. Exit 0 means nothing needs you.",
+                "Maintainers: --update-tag next keeps self-update on the prerelease candidate.",
             ],
         ],
         [
             "fix",
             [
-                "Usage: cockpit fix [same flags as cockpit do-everything]",
+                "Usage: cockpit fix [--workspace <path>] [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
                 "",
-                "Alias for `cockpit do-everything`.",
+                "Diagnose, repair, and verify this machine. doctor, do-everything, and fix run the same job.",
+                "Repairs CLI, background sync, sign-in, roots, memory and hooks, agent rules, catch-up, uploads, and cleanup.",
+                "--check or --no-repair diagnoses without repairs. --dry-run previews repairs.",
+                "--backfill-budget defaults to 900 seconds; catch-up repeats chunks until complete, with progress every 30 seconds.",
+                "--lock-wait defaults to 600 seconds; progress prints every 30 seconds.",
+                "--json includes steps, repairs, and needs_person. Exit 0 means nothing needs you.",
+                "Maintainers: --update-tag next keeps self-update on the prerelease candidate.",
             ],
         ],
         [
             "doctor",
             [
-                "Usage: cockpit doctor [same flags as cockpit do-everything]",
+                "Usage: cockpit doctor [--workspace <path>] [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
                 "",
-                "Alias for `cockpit do-everything`. It checks this machine row by row —",
-                "CLI version, sign-in, saved folders, background sync, backfill, disk — and",
-                "fixes each row it can. `--dry-run` prints the diagnosis and changes nothing.",
+                "Diagnose, repair, and verify this machine. doctor, do-everything, and fix run the same job.",
+                "Repairs CLI, background sync, sign-in, roots, memory and hooks, agent rules, catch-up, uploads, and cleanup.",
+                "--check or --no-repair diagnoses without repairs. --dry-run previews repairs.",
+                "--backfill-budget defaults to 900 seconds; catch-up repeats chunks until complete, with progress every 30 seconds.",
+                "--lock-wait defaults to 600 seconds; progress prints every 30 seconds.",
+                "--json includes steps, repairs, and needs_person. Exit 0 means nothing needs you.",
+                "Maintainers: --update-tag next keeps self-update on the prerelease candidate.",
             ],
         ],
         [

package/dist/commands/local-help.js

@@ -64,7 +64,7 @@ export function localCommandHelp(command) {
         "  cockpit upgrade [same flags as update]",
         "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
         "  cockpit fix [same flags as do-everything]",
-        "  cockpit doctor [same flags as do-everything]",
+        "  cockpit doctor [--check | --no-repair] [--lock-wait <seconds>] [--backfill-budget <seconds>] [--json]",
         "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
         "  cockpit login [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit pair [--pair <code>] [--no-browser] [--legacy-pair] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",

package/dist/commands/local.js

@@ -209,6 +209,7 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
 async function runDoctorLogin(command, io) {
     return runLogin({
         kind: "login",
+        homeDir: command.homeDir,
         dashboardUrl: command.dashboardUrl,
         json: command.json,
         noAuth: false,

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.100");
+    writeLine(io?.stdout ?? process.stdout, "0.2.102");
     return 0;
   }
 
@@ -40,12 +40,12 @@ function cockpitHelp() {
     localCommandHelp(),
     "",
     "Install: `npm install -g @bli-cockpit/cli@latest`.",
-    "Fix everything: run `cockpit do-everything` to update, verify auth/roots, refresh autostart, backfill, GC, and sync.",
+    "Fix everything: run `cockpit doctor`. `do-everything` and `fix` are exact aliases; --check diagnoses without repairs.",
     "Update: run `cockpit update` to refresh the global CLI and rerun onboarding checks.",
     "Intern path: run `cockpit onboard`; it confirms a `/BLI` collection root before syncing.",
     "Headless/reused laptop path: `cockpit onboard --email <email> --workspace ~/BLI`.",
-    "Already onboarded: run `cockpit update` from anywhere to refresh pairing, roots, agent rules, autostart, and sync.",
-    "Agent setup: `cockpit onboard` refreshes AGENTS.md/CLAUDE.md rules; use `cockpit agent-rules install --workspace ~/BLI` for repair.",
+    "Already onboarded: run `cockpit doctor` from anywhere to repair and verify this machine.",
+    "Agent setup: `cockpit doctor` installs and verifies AGENTS.md/CLAUDE.md rules.",
     "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
     "Manual collector path: `install`, `login`, `start [--ticket <id>] [--topic <label>] [--intent <intent>] [--phase <phase>]`, `sync`, `status`, `agent-rules`.",
     "Maintainer release path: merge to main, publish to `next` with `cockpit release`, canary Windows plus Apple Silicon, then deliberately promote that exact version to `latest`.",

package/dist/commands/usage-format.js

@@ -0,0 +1,18 @@
+/** Compact counts for human-facing usage tables. JSON keeps the original numbers. */
+export function formatCount(value) {
+    if (value === null)
+        return "Unavailable";
+    // Promote rounded values at unit boundaries instead of printing 1000K or 1000M.
+    if (value >= 999_950_000)
+        return `${Number((value / 1_000_000_000).toFixed(1))}B`;
+    if (value >= 999_500)
+        return `${Number((value / 1_000_000).toFixed(1))}M`;
+    if (value >= 1_000)
+        return `${Math.round(value / 1_000)}K`;
+    return String(value);
+}
+export function formatUsageDollars(value) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency", currency: "USD", maximumFractionDigits: 0,
+    }).format(value);
+}

package/dist/commands/usage.js

@@ -1,3 +1,4 @@
+import { formatCount, formatUsageDollars } from "./usage-format.js";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 export async function runUsage(command, io) {
@@ -13,9 +14,18 @@ export async function runUsage(command, io) {
     const body = answer.body;
     if (door.json)
         return emitAgentDoor(door, body);
-    writeLine(io.stdout, "PERSON                 TOKENS       OUTPUT       LIST EQUIVALENT  COVERAGE");
-    for (const row of body.people ?? [])
-        writeLine(io.stdout, `${(row.display_name ?? row.email ?? "Unknown").slice(0, 20).padEnd(20)}  ${String(row.tokens_total).padStart(11)}  ${String(row.output_tokens).padStart(11)}  ${`$${row.api_list_price_equivalent_usd.toFixed(2)}`.padStart(15)}  ${row.sessions_extracted}/${row.sessions_observed}`);
+    const widths = [20, 8, 15, 12, 10, 10, 12, 14];
+    const printRow = (cells) => writeLine(io.stdout, cells.map((cell, index) => index === 0 ? cell.padEnd(widths[index]) : cell.padStart(widths[index])).join("  ").trimEnd());
+    printRow(["Person", "Tokens", "List equivalent", "Coverage", ...(command.detail ? ["Output", "Input", "Cache read", "Cache creation"] : [])]);
+    for (const row of body.people ?? []) {
+        printRow([
+            (row.display_name ?? row.email ?? "Unknown").slice(0, 20),
+            formatCount(row.tokens_total),
+            formatUsageDollars(row.api_list_price_equivalent_usd),
+            `${row.sessions_extracted}/${row.sessions_observed}`,
+            ...(command.detail ? [row.output_tokens, row.input_tokens, row.cache_read_input_tokens, row.cache_creation_input_tokens].map(formatCount) : []),
+        ]);
+    }
     writeLine(io.stdout, "");
     writeLine(io.stdout, body.api_list_price_equivalent_label ?? "API list-price equivalent (not actual spend)");
     writeLine(io.stdout, `${body.coverage?.sessions_extracted ?? 0} of ${body.coverage?.sessions_observed ?? 0} sessions extracted`);

package/dist/scheduled-self-update.js

@@ -146,7 +146,7 @@ function parseSemverTriple(value) {
         return null;
     return [Number(match[1]), Number(match[2]), Number(match[3])];
 }
-function isSemverBelow(left, right) {
+export function isSemverBelow(left, right) {
     const parsedLeft = parseSemverTriple(left);
     const parsedRight = parseSemverTriple(right);
     if (!parsedLeft || !parsedRight)

package/dist/sync-lock.js

@@ -142,4 +142,9 @@ async function readLock(lockPath) {
         // ACQUIRE above is the branch that owns the reporting.
         return null;
     }
+}
+/** Read owner metadata without acquiring or disturbing the collection lock. */
+export async function inspectSyncLock(paths) {
+    const record = await readLock(path.join(paths.state_dir, LOCK_FILENAME));
+    return record ? { pid: record.pid, heartbeat_at: record.heartbeat_at, held: Date.now() - record.heartbeat_ms <= STALE_TAKEOVER_MS } : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.100",
+  "version": "0.2.102",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.26",
-    "@bli-cockpit/mcp": "0.1.31",
+    "@bli-cockpit/mcp": "0.1.32",
     "@bli-cockpit/telemetry-core": "0.1.43"
   }
 }