@bli-cockpit/cli 0.2.174 → 0.2.180

package/dist/commands/doctor-pipeline.js

@@ -1,7 +1,4 @@
-import { withDoctorLockWait } from "./doctor-lock-wait.js";
-import { doctorBackfillBudgetSeconds, doctorLockWaitSeconds } from "./doctor-budget.js";
-import { inspectBackfillLock } from "../backfill-lock.js";
-import { readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { withCollectionGate } from "./doctor-collection-lock.js";
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
 import { runStagingPrune } from "../disk-prune.js";
 import { retentionOptionsFromEnv } from "../disk-retention.js";
@@ -10,11 +7,11 @@ import { readDiskFootprint } from "../disk-usage.js";
 import { runEvidenceRedelivery } from "../evidence-redelivery.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "../local-state.js";
 import { runRawEvidenceLocalGc, rawEvidenceGcSummary } from "../raw-evidence-gc.js";
-import { runBackfillCommand } from "./backfill.js";
 import { FOOTPRINT_NEEDS_FIX_BYTES, stagingPausedWords, diskRowMessage, footprintHolder, footprintTotalBytes, mib, redeliveryLine, } from "./doctor-disk-words.js";
 import { doctorRoots } from "./doctor-access.js";
-import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, parseDoctorSyncJson, syncFailureMessage, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";
-import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
+import { startProgress, waitingLine } from "./doctor-progress.js";
+import { jsonField, parseDoctorSyncJson, syncFailureMessage, 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
@@ -29,108 +26,9 @@ import { asRecord, fail, needsFix, ok, skipped } from "./doctor-report.js";
  * 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.
+ * here so callers keep one address. The catch-up row itself moved to
+ * `doctor-backfill.ts` (BLI-12872) and is re-exported below as well.
  */
-export async function checkBackfillState(context) {
-    const paths = getCollectorRuntimePaths(context.command.homeDir);
-    const roots = await doctorRoots(context);
-    const marker = await readBackfillCompletionMarker(paths);
-    const covered = backfillCompletionStepState(marker, roots);
-    if (covered)
-        return covered;
-    const lock = await inspectBackfillLock(paths);
-    if (lock.held) {
-        return needsFix("backfill-complete", "backfill_already_running", `another catch-up run is still going, and this one has not finished yet (running since ${lock.held_since ?? "unknown"})`);
-    }
-    const cursor = await readBackfillCursor(paths);
-    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 started = Date.now();
-    const deadline = started + doctorBackfillBudgetSeconds(context, started) * 1000;
-    let caughtUp = 0;
-    let chunks = 0;
-    let live = null;
-    const elapsed = () => {
-        const seconds = Math.floor((Date.now() - started) / 1000);
-        return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
-    };
-    const receipt = () => `caught up on ${caughtUp} old sessions in ${chunks} chunk${chunks === 1 ? "" : "s"} over ${elapsed()}`;
-    let remaining = null;
-    const unfinished = (code, reason) => ({
-        ...needsFix("backfill-complete", code, `${receipt()}, ${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);
-        const uploaded = live === null ? null : caughtUp + live.uploaded;
-        context.io.stderr.write(live === null
-            ? `backfill: starting, ${elapsed()}\n`
-            : `backfill: ${uploaded} caught up, ${live.processed} processed in this chunk, ${live.remaining} to go, ${elapsed()}\n`);
-        console.error("[doctor] backfill-complete progress", JSON.stringify({
-            status: live === null ? "starting" : "running", processed: live?.processed ?? null,
-            uploaded, caught_up: uploaded, remaining: live?.remaining ?? null,
-            chunks, 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(doctorLockWaitSeconds(context), (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);
-                live = null;
-                chunks += 1;
-                const code = await runBackfillCommand({
-                    homeDir: context.command.homeDir, repoRoot: context.command.repoRoot,
-                    all: true, dryRun: false, yes: true, json: true,
-                    deadlineMs: deadline,
-                    // Doctor's own `withDoctorLockWait` owns the waiting (BLI-11091).
-                    syncLockWaitMs: 0,
-                    onProgress: (progress) => { live = progress; },
-                }, 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;
-                live = null;
-                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", receipt() + (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, chunks, 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);
-    }
-}
 export async function checkGcState(context) {
     if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
         return skipped("gc-checked", "skipped_disabled", "cleanup is switched off");
@@ -253,42 +151,6 @@ export async function fixDiskState(context) {
     // Unaccepted evidence still occupies the cap. Keep the disk row actionable.
     return needsFix("disk-bounded", "staging_cap_blocked_by_uncommitted", `freed ${mib(pruned.deleted_bytes)} MB; ${message}; ${pruned.cap_blocked_count} object(s) the upload ledger cannot vouch for are holding the rest; ${redelivered}; or \`cockpit clean --all-committed\` to drop every accepted copy now`);
 }
-function capturedIo(io, forward) {
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    return {
-        io: {
-            ...io,
-            stdout: captureStream(io.stdout, stdoutChunks, forward),
-            stderr: captureStream(io.stderr, stderrChunks, forward),
-        },
-        stdout: () => stdoutChunks.join(""),
-        stderr: () => stderrChunks.join(""),
-    };
-}
-function captureStream(target, chunks, forward) {
-    return {
-        write(chunk, encoding, callback) {
-            const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
-            chunks.push(text);
-            if (forward) {
-                if (typeof encoding === "function") {
-                    target.write(chunk, encoding);
-                }
-                else {
-                    target.write(chunk, encoding, callback);
-                }
-            }
-            else if (typeof encoding === "function") {
-                encoding();
-            }
-            else {
-                callback?.();
-            }
-            return true;
-        },
-    };
-}
 export async function checkSyncState(context) {
     const roots = await doctorRoots(context);
     if (roots.length === 0) {
@@ -299,8 +161,13 @@ 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"}`);
 }
+/**
+ * The `sync-fresh` repair. Looks at the collection lock first and never waits
+ * for it (BLI-12872): a running background sync is reported as exactly that,
+ * and a stuck one is ended before doctor's own sync runs.
+ */
 export async function fixSyncState(context) {
-    return withDoctorLockWait(context, () => runSyncRepair(context));
+    return withCollectionGate(context, "sync-fresh", () => runSyncRepair(context));
 }
 async function runSyncRepair(context) {
     const exec = context.io.exec;
@@ -321,7 +188,10 @@ async function runSyncRepair(context) {
         if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
             args.push("--dashboard-url", context.command.dashboardUrl);
         }
-        const result = await exec("cockpit", args);
+        // One line every 30 s while doctor's own sync runs; the exec has nothing
+        // to count, so the line says it is still working and for how long.
+        const stopProgress = startProgress((text) => context.io.stderr.write(text), (elapsedMs) => waitingLine("sync", elapsedMs));
+        const result = await Promise.resolve(exec("cockpit", args)).finally(stopProgress);
         const parsed = parseDoctorSyncJson(result.stdout);
         const output = `${result.stdout}\n${result.stderr}`;
         const status = jsonField(output, "status");
@@ -335,10 +205,12 @@ async function runSyncRepair(context) {
                 owner_alive: standAside.ownerAlive,
                 held_since: standAside.heldSince,
             }));
-            return needsFix("sync-fresh", standAside.code, "waiting for the collection lock");
+            // The gate (`withCollectionGate`) reads the lock again and turns this
+            // into "background sync is running"; the code only travels to it.
+            return needsFix("sync-fresh", standAside.code, "the sync stood aside for the collection lock");
         }
         if (status === "live_sync_paused_during_backfill") {
-            return needsFix("sync-fresh", status, "waiting for historical catch-up");
+            return needsFix("sync-fresh", status, "the sync paused for the historical catch-up");
         }
         if (result.code !== 0) {
             const draining = syncBacklogDrainingVerdict(parsed);
@@ -347,7 +219,7 @@ async function runSyncRepair(context) {
                     `file${draining.remainingObjects === 1 ? "" : "s"} left for later this run); ` +
                     "rerun `cockpit sync` to continue");
             }
-            return fail("sync-fresh", status ?? "sync_failed", `${repoRoot}: ${syncFailureMessage(parsed)}`);
+            return fail("sync-fresh", status ?? "sync_failed", `${repoRoot}: ${syncFailureMessage(parsed, result.code)}`);
         }
         if (parsed?.collection_complete === false && typeof parsed.discovery_notice === "string") {
             console.error("[doctor] partial discovery", JSON.stringify({ reason: "discovery_partial" }));
@@ -364,4 +236,5 @@ async function runSyncRepair(context) {
 // 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 { checkBackfillState, fixBackfillState } from "./doctor-backfill.js";
 export { backfillCompletionStepState, backfillFixVerdict, isCollectionBusyReason, syncBacklogDrainingVerdict, syncStandAsideVerdict, } from "./doctor-pipeline-verdicts.js";

package/dist/commands/doctor-progress.js

@@ -0,0 +1,54 @@
+/**
+ * The one progress line `cockpit doctor` prints while a long repair runs
+ * (BLI-12872).
+ *
+ * Until now two writers shared stderr: the lock wait's "waiting for the
+ * background sync to finish" and the catch-up's "backfill: starting", and a
+ * 13-minute run printed that pair alternately about 40 times, which says
+ * nothing. Doctor no longer waits on a lock, so one writer is left, and its
+ * rule is: at most one line every 30 seconds, and each line says what CHANGED
+ * since the last one, or that nothing did.
+ *
+ * Counts and elapsed time only; never a path, an id or a session name.
+ */
+export const PROGRESS_EVERY_MS = 30_000;
+/** "5m00s" for a progress line: seconds matter here, unlike a lock's age. */
+export function clock(ms) {
+    const seconds = Math.floor(ms / 1000);
+    return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+/**
+ * The line for this tick. `last` is what the previous line reported (null for
+ * the first line), so the sentence is always a difference, never a repeat.
+ */
+export function backfillProgressLine(now, last, elapsedMs) {
+    if (now.remaining === null) {
+        return `backfill: reading your old sessions, ${clock(elapsedMs)}`;
+    }
+    const counts = `${now.caughtUp} caught up, ${now.remaining} to go`;
+    if (last === null || last.remaining === null) {
+        return `backfill: ${counts}, ${clock(elapsedMs)}`;
+    }
+    const gained = now.caughtUp - last.caughtUp;
+    if (gained <= 0 && now.remaining === last.remaining) {
+        return `backfill: no change in the last 30s (${counts}), ${clock(elapsedMs)}`;
+    }
+    return `backfill: +${Math.max(0, gained)} caught up in the last 30s (${counts}), ${clock(elapsedMs)}`;
+}
+/** The line for a repair that is one long command with nothing to count (`sync`). */
+export function waitingLine(what, elapsedMs) {
+    return `${what}: still working, ${clock(elapsedMs)} so far`;
+}
+/**
+ * Print `describe(elapsedMs)` every 30 seconds until stopped. The timer never
+ * keeps the process alive. Returns the stop function.
+ */
+export function startProgress(write, describe, options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const started = now();
+    const timer = (options.setIntervalImpl ?? setInterval)(() => {
+        write(`${describe(now() - started)}\n`);
+    }, PROGRESS_EVERY_MS);
+    timer.unref?.();
+    return () => (options.clearIntervalImpl ?? clearInterval)(timer);
+}

package/dist/commands/doctor-report.js

@@ -157,7 +157,8 @@ export function repairReceiptLines(repairs) {
         return [];
     return [
         "Repairs (before -> after):",
-        ...ran.map((repair) => `  ${repair.after?.startsWith("ok:") ? "fixed" : "still needs you"} ${repair.step}: ${repair.before_message ?? ""} -> ${repair.after_message ?? ""}`.replaceAll("—", ";")),
+        // BLI-12872: a row left "skipped" is a background sync doing the work; it is in progress, not waiting on a person.
+        ...ran.map((repair) => `  ${repair.after?.startsWith("ok:") ? "fixed" : repair.after?.startsWith("skipped:") ? "in progress" : "still needs you"} ${repair.step}: ${repair.before_message ?? ""} -> ${repair.after_message ?? ""}`.replaceAll("—", ";")),
     ];
 }
 export function doctorNeedsPerson(rows, receipt) {

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { describeError } from "../health-detail.js";
 import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, readRootsCoverWork, 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 { gateRow, readCollectionGate } from "./doctor-collection-lock.js";
 import { checkMcpAnswersState, fixMcpAnswersState } from "./doctor-mcp.js";
 import { budgetSpentRow, doctorRunDeadline, DOCTOR_JSON_BUDGET_SECONDS } from "./doctor-budget.js";
 import { checkMemoryDaemonState } from "./doctor-memory-daemon.js";
@@ -49,15 +50,22 @@ export async function runDoctorWithDeps(command, io, deps) {
             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));
-            const spent = row.status !== "ok" && row.status !== "skipped" && canFix ? budgetSpentRow(context, row) : null;
+            let spent = row.status !== "ok" && row.status !== "skipped" && canFix ? budgetSpentRow(context, row) : null;
+            if (spent && needsCollection) {
+                // BLI-12872: a running sync is the answer even when the budget is spent; looking costs nothing.
+                const gate = await readCollectionGate(context, undefined, { mayEnd: false });
+                if (gate.kind === "running")
+                    spent = gateRow(invariant.id, gate);
+            }
             if (spent) {
                 row = spent;
-                repairs.push({ step: invariant.id, outcome: "needs_person", reason: row.code });
+                repairs.push({ step: invariant.id, outcome: row.status === "skipped" ? "not_needed" : "needs_person", reason: row.code });
             }
             else if (row.status !== "ok" && row.status !== "skipped" && canFix && invariant.fix) {
                 attempted.add(invariant.id);
                 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 });
+                // BLI-12872: a skipped row after a fix is a sync already doing the work, not a person's job.
+                repairs.push({ step: invariant.id, outcome: row.status === "ok" ? "repaired" : row.status === "skipped" ? "not_needed" : "needs_person", reason: row.code });
                 // The replacement process owns the one final receipt, including JSON.
                 if (row.reexecExitCode !== undefined)
                     return row.reexecExitCode;

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

@@ -0,0 +1,38 @@
+/**
+ * `cockpit brain` argument parsing (BLI-12859).
+ *
+ *   cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--json]
+ *
+ * Tower's incident queue: per project, how many incidents are open, being worked, waiting on a
+ * person, fixed, not actionable or cleared, the newest ones with their Tower issue, and the last
+ * 7 days of verdicts. It reads `GET /api/brain/incidents` with this machine's device token.
+ */
+import { LOG_PROJECT_PATTERN } from "@bli-cockpit/telemetry-core/log-digest";
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+/** The statuses the queue's door accepts for `--show`; the migration's CHECK constraint is the other copy. */
+export const BRAIN_SHOW_STATUSES = ["open", "running", "needs_human", "fixed", "not_actionable", "cleared"];
+export function parseBrainArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--project", "--show", "--home", "--dashboard-url", "--json"],
+        valueFlags: ["--project", "--show", "--home", "--dashboard-url"],
+    });
+    const action = values.positionals[0];
+    if (action !== "status" || values.positionals.length > 1) {
+        throw new Error("brain takes one verb: `status`. Example: `cockpit brain status` or `cockpit brain status --project pearl-portal`.");
+    }
+    const project = optionalNonEmpty(values.flags.get("--project"));
+    if (project && !LOG_PROJECT_PATTERN.test(project))
+        throw new Error("--project wants a registry project id like pearl-portal (`cockpit logs --list` names them).");
+    const show = optionalNonEmpty(values.flags.get("--show"));
+    if (show && !BRAIN_SHOW_STATUSES.includes(show))
+        throw new Error(`--show wants one of ${BRAIN_SHOW_STATUSES.join(", ")}.`);
+    return {
+        kind: "brain",
+        action: "status",
+        ...(project ? { project } : {}),
+        ...(show ? { show } : {}),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}

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

@@ -39,5 +39,6 @@ export { parseMailArgs } from "./local-args-tower-mail.js";
 export { parseCalArgs } from "./local-args-tower-cal.js";
 export { parseUsageArgs } from "./local-args-tower-usage.js";
 export { parseLogsArgs } from "./local-args-tower-logs.js";
+export { parseBrainArgs } from "./local-args-tower-brain.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';

package/dist/commands/local-args.js

@@ -18,7 +18,7 @@
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseLogsArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseLogsArgs, parseBrainArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -135,6 +135,8 @@ export function parseLocalArgs(argv) {
             return parseUsageArgs(argv.slice(1));
         case "logs":
             return parseLogsArgs(argv.slice(1));
+        case "brain":
+            return parseBrainArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-command-shapes-brain.js

@@ -0,0 +1,5 @@
+/**
+ * `cockpit brain` command shape (BLI-12859), beside `local-command-shapes-logs.ts` for the same
+ * reason: `local-command-shapes.ts` sits at the readability ceiling.
+ */
+export {};

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

@@ -44,6 +44,23 @@ export const TOWER_OPS_COMMAND_HELP = [
             "The bli-tower MCP server has the twin: logs_digest.",
         ],
     ],
+    [
+        "brain",
+        [
+            "Usage: cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
+            "",
+            "Tower's incident queue. Every 15 minutes the log-digest cron turns each recurring problem in a project's logs (classes",
+            "our_bug, config_drift, capacity, unknown) into ONE incident with ONE Tower issue; a repeat adds to its count, never a twin.",
+            "A template quiet for 24 hours is marked cleared. This prints, per project, how many incidents are open, being worked,",
+            "waiting on a person, fixed, not actionable or cleared, the newest ones in the --show status (default open) with their Tower",
+            "issue, how often each was seen and what it said, and the last 7 days of verdicts. Needs only this machine's Tower login.",
+            "--project <id>   one project (`cockpit logs --list` names them).",
+            "--show <status>  list the newest incidents in that status instead of open.",
+            "--json writes one object to stdout: { ok, generated_at, projects[{ project, counts, incidents[], verdicts_7d }], totals, coverage, text };",
+            "a refusal is { ok: false, error, detail } and exits 1 (unknown_project, invalid_status, stored_read_failed, not_paired, ...).",
+            "Teaching: docs/architecture/tower-brain.md. The bli-tower MCP server has the twin: brain_status.",
+        ],
+    ],
     [
         "github",
         [

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

@@ -94,7 +94,7 @@ export function localSubcommandHelp(command) {
                 "roots-cover-work is informational: it names how many sessions are inside vs. outside saved roots (all already uploaded, outside ones labelled) and gives cockpit roots add commands for widening a root's redacted transcript content. It never needs a fix.",
                 "--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.",
+                "Doctor never waits for the background sync: a running sync is reported as running (with how long ago it started) and doctor finishes; a sync that stopped responding or made no progress for 15 minutes is ended and doctor carries on. --lock-wait is accepted and changes nothing. Progress prints at most every 30 seconds and says what changed.",
                 "--json without either flag answers within 45 seconds; a repair that does not fit reads doctor_budget_spent.",
                 "--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

@@ -79,6 +79,7 @@ export const rootCommandNames = new Set([
     "rename",
     "usage",
     "logs",
+    "brain",
     ...SURFACE_ALIASES.keys(),
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
@@ -134,6 +135,7 @@ export function localCommandHelp(command) {
         "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|followup <id> [--record-sent-at <iso>]|interview <id> <--at <iso>|--clear>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false> --followup-enabled <true|false> --followup-after-days <n> --takehome-window-hours <n>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
         "  cockpit rename [list|resolve <id> --scope <page|everywhere|undo>] [--dashboard-url <url>] [--json]",
         "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
+        "  cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/local.js

@@ -50,6 +50,7 @@ import { runCareers } from "./careers.js";
 import { runRename } from "./rename-scope.js";
 import { runUsage } from "./usage.js";
 import { runLogs } from "./logs.js";
+import { runBrain } from "./brain.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
@@ -245,6 +246,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runUsage(command, io);
             case "logs":
                 return await runLogs(command, io);
+            case "brain":
+                return await runBrain(command, io);
         }
     }
     catch (error) {

package/dist/commands/logs-stored.js

@@ -46,7 +46,7 @@ export async function runStoredLogs(command, io, options) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(io.stderr, `${TAG} stored digest read ${JSON.stringify({ project: body.project, windows: body.windows, windows_ok: body.windows_ok, refusals: body.refusals.length, fallback: Boolean(options.fallbackReason) })}`);
+    writeLine(io.stderr, `${TAG} stored digest read ${JSON.stringify({ project: body.project, windows: body.windows, windows_ok: body.windows_ok, refusals: body.refusals.length, still_refusing: body.still_refusing?.length ?? null, not_wired: body.not_wired?.length ?? null, fallback: Boolean(options.fallbackReason) })}`);
     if (command.json)
         return emitAgentDoor(door, options.fallbackReason ? { ...body, fallback_from: options.fallbackReason } : body);
     if (options.fallbackReason)

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.174");
+    writeLine(io?.stdout ?? process.stdout, "0.2.180");
     return 0;
   }
 

package/dist/commands/status.js

@@ -80,7 +80,7 @@ async function writeMultiRepoStatus(command, io, backfillCursor, setupReceipt, w
     writeLine(io.stdout, `Old sessions: ${backfillCursorLine(backfillCursor)}`);
     writeLine(io.stdout, await statusDiskLine(command.homeDir));
     for (const status of statuses) {
-        writeLine(io.stdout, `- ${status.repo_label ?? status.repo}/${status.worktree_label ?? "worktree"} · ${status.branch} · head:${shortSha(status.head_sha)} · ${status.upload_state}`);
+        writeLine(io.stdout, `- ${status.repo_label ?? status.repo}/${status.worktree_label ?? "worktree"} · ${status.branch} · head:${shortSha(status.head_sha)} · ${uploadsLine(status.upload_state)}`);
     }
     writeConnectedBlock(io, setupReceipt);
     return 0;

package/dist/commands/sync-run.js

@@ -7,6 +7,7 @@ import { healStubsDuringTick } from "./sync-stub-heal.js";
 import { backfillWaitingCheck } from "./sync-yield.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { rawEvidenceDedupSummary, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
+import { noteSyncProgress } from "../sync-lock.js";
 /**
  * Collect everything this tick may collect, then report it.
  *
@@ -25,6 +26,7 @@ export async function runSyncLocked(command, io) {
     if (!dedup.skipped && dedup.removed_dirs > 0) {
         writeLine(io.stdout, rawEvidenceDedupSummary(dedup));
     }
+    noteSyncProgress(); // BLI-12872: the sweep finished; the lock's progress mark
     let discoveryNotice = null;
     const worktrees = await discoverCommandWorktrees(collectionRoots, {
         maxDepth: command.maxDepth,
@@ -33,6 +35,7 @@ export async function runSyncLocked(command, io) {
         allowEmpty: true,
         onPartial: (notice) => { discoveryNotice = notice; },
     }, io);
+    noteSyncProgress(); // BLI-12872: discovery finished
     const run = await runAttributedWorktreeSync({
         homeDir: command.homeDir,
         dashboardUrl: command.dashboardUrl,

package/dist/commands/sync-yield.js

@@ -15,6 +15,7 @@
  * worktree's upload, which is why each one logs its own elapsed time.
  */
 import { inspectBackfillLock } from "../backfill-lock.js";
+import { noteSyncProgress } from "../sync-lock.js";
 /** The waiter's flag: the backfill lock is held while its owner waits for ours. */
 export function backfillWaitingCheck(paths, inspect = inspectBackfillLock) {
     return async () => {
@@ -50,6 +51,9 @@ export async function runYieldingAtBoundaries(options) {
         const itemStarted = now();
         const result = await options.runOne(item);
         results.push(result);
+        // BLI-12872: a finished worktree is the lock's progress mark, what keeps a
+        // long tick from being called stuck while it keeps working.
+        noteSyncProgress();
         console.error("[session-sync] worktree synced", JSON.stringify({
             index: index + 1,
             total: options.items.length,