@bli-cockpit/cli 0.2.173 → 0.2.179

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

@@ -5,7 +5,10 @@ const POLL_EVERY_MS = 1_000;
 const DEFAULT_DEPS = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    acquire: acquireSyncLock,
+    // BLI-12872: a catch-up is long by design and scans for minutes without an
+    // upload, so it holds the lock under its own role; doctor never calls a
+    // `backfill` holder stuck, only a scheduled sync that stopped finishing work.
+    acquire: (paths, now) => acquireSyncLock(paths, now, { role: "backfill" }),
     inspect: inspectSyncLock,
 };
 /**

package/dist/commands/doctor-backfill.js

@@ -0,0 +1,160 @@
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { runBackfillCommand } from "./backfill.js";
+import { doctorBackfillBudgetSeconds } from "./doctor-budget.js";
+import { doctorRoots } from "./doctor-access.js";
+import { withCollectionGate } from "./doctor-collection-lock.js";
+import { backfillProgressLine, clock, startProgress, } from "./doctor-progress.js";
+import { backfillCompletionStepState, backfillFixVerdict, jsonField, parseDoctorBackfillJson, } from "./doctor-pipeline-verdicts.js";
+import { asRecord, needsFix, ok } from "./doctor-report.js";
+/**
+ * The `backfill-complete` row: has the catch-up over old sessions finished.
+ * Split out of `doctor-pipeline.ts` (BLI-12872) so that file stays under the
+ * line ratchet; `doctor-pipeline.ts` still re-exports both functions.
+ */
+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");
+}
+/**
+ * Catch up on old sessions, a chunk at a time, inside the run's budget.
+ *
+ * Every chunk asks the collection lock first (`withCollectionGate`): a healthy
+ * sync holding it ends this run with a plain "background sync is running" row,
+ * not a wait, and a stuck one is ended and the chunk runs.
+ */
+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;
+    let remaining = null;
+    const receipt = () => `caught up on ${caughtUp} old sessions in ${chunks} chunk${chunks === 1 ? "" : "s"} over ${clock(Date.now() - started)}`;
+    const unfinished = (code, reason) => ({
+        ...needsFix("backfill-complete", code, `${receipt()}, ${remaining ?? "unknown"} still to go; ${reason}; run \`cockpit doctor\` again to continue`),
+        nextAction: "cockpit doctor",
+    });
+    let lastLine = null;
+    const stopProgress = startProgress((text) => context.io.stderr.write(text), (elapsedMs) => {
+        const snapshot = {
+            caughtUp: live === null ? caughtUp : caughtUp + live.uploaded,
+            remaining: live?.remaining ?? remaining,
+        };
+        console.error("[doctor] backfill-complete progress", JSON.stringify({
+            status: live === null ? "between_chunks" : "running", processed: live?.processed ?? null,
+            uploaded: live === null ? null : caughtUp + live.uploaded,
+            caught_up: snapshot.caughtUp, remaining: snapshot.remaining, chunks, elapsed_seconds: Math.floor(elapsedMs / 1000),
+        }));
+        const line = backfillProgressLine(snapshot, lastLine, elapsedMs);
+        lastLine = snapshot;
+        return line;
+    });
+    try {
+        while (Date.now() < deadline) {
+            const row = await withCollectionGate(context, "backfill-complete", 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 never waits for the collection lock (BLI-12872): the gate
+                    // above looked at it, and a busy answer here is reported, not retried.
+                    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.status === "skipped") {
+                // A running sync (or another catch-up) owns the lock. Doctor does not
+                // wait; it says what this run managed before it stood aside.
+                console.error("[doctor] backfill-complete stood aside", JSON.stringify({ reason: row.code, caught_up: caughtUp, remaining, chunks }));
+                return caughtUp > 0 ? { ...row, message: `${receipt()}; ${row.message}` } : row;
+            }
+            if (row.code === "sync_stuck_not_ended")
+                return row;
+            if (row.code !== "backfill_chunk_pending")
+                return unfinished(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 {
+        stopProgress();
+    }
+}
+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;
+        },
+    };
+}

package/dist/commands/doctor-budget.js

@@ -1,17 +1,21 @@
 /**
  * BLI-11101: `cockpit doctor --json` answers within one bounded budget.
  *
- * A person at a terminal gets the long defaults (a 900-second catch-up and a
- * 600-second wait for the collection lock) with progress every 30 seconds. An
- * agent or script calling `--json` gets one answer: on Edward's Mac the long
- * defaults ran past 9.5 minutes behind the 15-minute scheduled sync, and a
- * caller that times out learns nothing. So `--json` without `--lock-wait` or
- * `--backfill-budget` runs every repair under one deadline measured from the
- * start of the run, and a repair that does not fit says so by name instead of
- * queueing. Passing either flag opts back into the long run.
+ * A person at a terminal gets the long default (a 900-second catch-up) with
+ * progress every 30 seconds. An agent or script calling `--json` gets one
+ * answer: on Edward's Mac the long defaults ran past 9.5 minutes behind the
+ * 15-minute scheduled sync, and a caller that times out learns nothing. So
+ * `--json` without `--lock-wait` or `--backfill-budget` runs every repair under
+ * one deadline measured from the start of the run, and a repair that does not
+ * fit says so by name instead of queueing. Passing either flag opts back into
+ * the long run.
+ *
+ * BLI-12872: doctor no longer WAITS for the collection lock at all (it looks,
+ * and a running sync is reported, `doctor-collection-lock.ts`), so
+ * `--lock-wait` is accepted for the scripts that still pass it and changes
+ * nothing except opting out of the `--json` deadline.
  */
 export const DOCTOR_JSON_BUDGET_SECONDS = 45;
-export const DEFAULT_LOCK_WAIT_SECONDS = 600;
 export const DEFAULT_BACKFILL_BUDGET_SECONDS = 900;
 /** A repair that execs a whole sync or catch-up chunk is not started with less than this left. */
 export const SLOW_FIX_MIN_SECONDS = {
@@ -31,14 +35,7 @@ function remainingSeconds(context, now) {
         return null;
     return Math.max(0, (context.deadlineMs - now) / 1000);
 }
-/** How long a repair may wait for the collection lock. */
-export function doctorLockWaitSeconds(context, now = Date.now()) {
-    if (context.command.lockWaitSeconds !== undefined)
-        return context.command.lockWaitSeconds;
-    const remaining = remainingSeconds(context, now);
-    return remaining === null ? DEFAULT_LOCK_WAIT_SECONDS : Math.min(DEFAULT_LOCK_WAIT_SECONDS, remaining);
-}
-/** How long the catch-up repair may run, lock waiting included. */
+/** How long the catch-up repair may run. */
 export function doctorBackfillBudgetSeconds(context, now = Date.now()) {
     if (context.command.backfillBudgetSeconds !== undefined)
         return context.command.backfillBudgetSeconds;

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

@@ -0,0 +1,201 @@
+/**
+ * Doctor and the collection lock (BLI-12872): look, never wait.
+ *
+ * The 15-minute sync holds the collection lock for as long as it is working,
+ * and on a machine with a backlog that is most of the time. Doctor used to wait
+ * for it (up to 10 minutes, 40 progress lines) and then end with two rows that
+ * told the person to run `cockpit doctor`, which is not a human action. A
+ * running sync is the machine doing its job, so the rule now is:
+ *
+ *   free      run the repair; the operation's own exclusive acquire owns the
+ *             handoff, so merely seeing a free lock never grants anything
+ *   running   report "background sync is running (started 7m ago)" and finish
+ *   stale     the heartbeat stopped: end the wedged process if one is left,
+ *             clear its lock, run the repair
+ *   stuck     alive but finished no work for 15 minutes (`sync-lock-holder.ts`
+ *             says what progress means): end it, clear its lock, run the repair
+ *
+ * Every branch logs its verdict and reason, ids and durations only. Ending a
+ * process is the one destructive act here, so it is verified three ways first:
+ * the pid must still exist, it must be a `node` or `cockpit` process (a pid the
+ * OS recycled for something else is left alone), and the lock being cleared
+ * must still carry the token that was inspected.
+ */
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { inspectSyncLock, removeSyncLockIfOwnedBy } from "../sync-lock.js";
+import { classifySyncHolder, formatSpan, runningWords, } from "../sync-lock-holder.js";
+import { isCollectionBusyReason } from "./doctor-pipeline-verdicts.js";
+import { needsFix, skipped } from "./doctor-report.js";
+const REAL_TIMING = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/** How long a polite end request gets before the process is forced. */
+const GRACE_MS = 5_000;
+const FORCE_WAIT_MS = 3_000;
+const POLL_MS = 500;
+/**
+ * Look at who holds the collection lock and act on it; never waits.
+ * `mayEnd: false` is a read-only peek: a stale or stuck holder is reported as
+ * open and left exactly as it was.
+ */
+export async function readCollectionGate(context, timing = REAL_TIMING, options = {}) {
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
+    const backfill = await inspectBackfillLock(paths, new Date(timing.now()));
+    if (backfill.held) {
+        console.error("[doctor] another catch-up run holds its lock; doctor does not wait", JSON.stringify({ reason: "backfill_lock_held", owner_pid: backfill.pid ?? null }));
+        return { kind: "running", words: runningWords({ role: "backfill", running_ms: null }) };
+    }
+    const verdict = classifySyncHolder(await inspectSyncLock(paths, timing.now()), timing.now());
+    if (verdict.kind === "free") {
+        console.error("[doctor] collection lock is free", JSON.stringify({ reason: "lock_free" }));
+        return { kind: "open" };
+    }
+    if (verdict.kind === "running") {
+        console.error("[doctor] background sync is healthy; doctor does not wait", JSON.stringify({ reason: "holder_running", ...holderFields(verdict) }));
+        return { kind: "running", words: runningWords(verdict) };
+    }
+    const reason = verdict.kind === "stale" ? "heartbeat_stale" : "no_progress_for_15m";
+    if (options.mayEnd === false) {
+        console.error("[doctor] collection lock holder is not running well; a peek leaves it alone", JSON.stringify({ reason, ...holderFields(verdict) }));
+        return { kind: "open" };
+    }
+    const outcome = await endHolder(context, verdict, reason, timing);
+    if (outcome !== "not_ended")
+        return { kind: "open" };
+    return { kind: "stuck_unended", pid: verdict.pid, idleMs: verdict.idle_ms };
+}
+/**
+ * Run `run` once the lock says it may, and turn a busy answer into a plain
+ * "background sync is running" row instead of a wait. At most two runs: one
+ * for a tick that started between the read and the run, never a loop.
+ */
+export async function withCollectionGate(context, id, run, timing = REAL_TIMING) {
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+        const gate = await readCollectionGate(context, timing);
+        if (gate.kind !== "open")
+            return gateRow(id, gate);
+        const row = await run();
+        if (!isCollectionBusyReason(row.code))
+            return row;
+        console.error("[doctor] the repair stood aside for a lock that was open a moment ago", JSON.stringify({ row: id, reason: row.code, attempt }));
+    }
+    const last = await readCollectionGate(context, timing);
+    return last.kind === "open"
+        ? skipped(id, "sync_running", `${runningWords({ role: "sync", running_ms: null })}${waitsNote(id)}`)
+        : gateRow(id, last);
+}
+/** The row a gate that is not open becomes. Never a row that needs doctor run again. */
+export function gateRow(id, gate) {
+    if (gate.kind === "running") {
+        return skipped(id, "sync_running", `${gate.words}${waitsNote(id)}`);
+    }
+    const who = gate.pid === null ? "a background sync" : `a background sync (process ${gate.pid})`;
+    const idle = gate.idleMs === null ? "" : ` for ${formatSpan(gate.idleMs)}`;
+    return {
+        ...needsFix(id, "sync_stuck_not_ended", `${who} has made no progress${idle} and could not be ended`),
+        nextAction: `End ${gate.pid === null ? "the stuck node process" : `process ${gate.pid}`} in Activity Monitor (Task Manager on Windows); the next background sync starts fresh.`,
+    };
+}
+/** The catch-up row also says its own work is parked, not lost. */
+function waitsNote(id) {
+    return id === "backfill-complete" ? "; the old-session catch-up waits until it is idle" : "";
+}
+/**
+ * End a holder doctor has decided is stale or stuck, then clear its lock.
+ * `ended` and `gone` and `reused_pid` all leave the lock cleared; only
+ * `not_ended` (the process would not die, or could not be verified) leaves it.
+ */
+async function endHolder(context, holder, reason, timing) {
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
+    const refuse = (why) => {
+        console.error("[doctor] could not end the lock holder; leaving its lock alone", JSON.stringify({ reason: why, takeover_reason: reason, ...holderFields(holder) }));
+        return "not_ended";
+    };
+    const clear = async (outcome, signal) => {
+        const removed = await removeSyncLockIfOwnedBy(paths, holder.token);
+        console.error("[doctor] took over the collection lock", JSON.stringify({ reason, outcome, signal, lock_removed: removed, ...holderFields(holder) }));
+        context.io.stderr.write(holder.kind === "stuck"
+            ? `ended a background sync that made no progress for ${formatSpan(holder.idle_ms ?? 0)}\n`
+            : "cleared a background sync that had stopped responding\n");
+        return outcome;
+    };
+    if (holder.pid === null) {
+        return holder.kind === "stale" ? clear("gone", null) : refuse("holder_pid_unknown");
+    }
+    const exec = context.io.exec;
+    if (!exec)
+        return refuse("no_process_runner");
+    const probe = await probeProcess(exec, holder.pid);
+    if (!probe.alive)
+        return clear("gone", null);
+    if (!probe.isCockpit) {
+        // The OS recycled the pid: the holder is gone and this is someone else's.
+        console.error("[doctor] lock holder pid now belongs to another program; leaving it running", JSON.stringify({ reason: "holder_pid_reused", takeover_reason: reason, ...holderFields(holder) }));
+        await removeSyncLockIfOwnedBy(paths, holder.token);
+        return "reused_pid";
+    }
+    const signal = await endProcess(exec, holder.pid, timing);
+    return signal === null ? refuse("process_would_not_end") : clear("ended", signal);
+}
+/** The log fields for a holder: a pid, a role and durations; never the token. */
+function holderFields(holder) {
+    return {
+        owner_pid: holder.pid,
+        owner_role: holder.role,
+        heartbeat_age_ms: holder.heartbeat_age_ms,
+        running_ms: holder.running_ms,
+        idle_ms: holder.idle_ms,
+    };
+}
+/** Ask politely (POSIX), wait, then force. Windows has no polite signal for a console app. */
+async function endProcess(exec, pid, timing) {
+    const windows = process.platform === "win32";
+    if (!windows) {
+        await exec("kill", ["-TERM", String(pid)]);
+        if (await goneWithin(exec, pid, GRACE_MS, timing))
+            return "SIGTERM";
+        await exec("kill", ["-KILL", String(pid)]);
+        return (await goneWithin(exec, pid, FORCE_WAIT_MS, timing)) ? "SIGKILL" : null;
+    }
+    await exec("taskkill", ["/PID", String(pid), "/T", "/F"]);
+    return (await goneWithin(exec, pid, FORCE_WAIT_MS, timing)) ? "taskkill" : null;
+}
+async function goneWithin(exec, pid, ms, timing) {
+    const deadline = timing.now() + ms;
+    for (;;) {
+        if (!(await probeProcess(exec, pid)).alive)
+            return true;
+        if (timing.now() >= deadline)
+            return false;
+        await timing.sleep(POLL_MS);
+    }
+}
+/** Is the pid alive, and is it a node or cockpit process? Unverifiable counts as alive and not ours. */
+async function probeProcess(exec, pid) {
+    try {
+        if (process.platform === "win32") {
+            const result = await exec("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"]);
+            const row = result.stdout.split("\n").map((line) => line.trim()).find((line) => line.startsWith('"'));
+            const fields = row?.split('","').map((field) => field.replaceAll('"', "")) ?? [];
+            if (fields[1] !== String(pid))
+                return { alive: false, isCockpit: false };
+            return { alive: true, isCockpit: isCockpitProcessName(fields[0] ?? "") };
+        }
+        const result = await exec("ps", ["-p", String(pid), "-o", "comm="]);
+        const name = result.stdout.trim().split("\n")[0] ?? "";
+        if (result.code !== 0 || !name)
+            return { alive: false, isCockpit: false };
+        return { alive: true, isCockpit: isCockpitProcessName(name) };
+    }
+    catch (error) {
+        console.error("[doctor] could not look up the lock holder's process", JSON.stringify({ reason: "process_probe_failed", error_name: error instanceof Error ? error.name : "unknown" }));
+        return { alive: true, isCockpit: false };
+    }
+}
+/** `node`, `node.exe`, `cockpit`, `cockpit.cmd`, with or without a directory in front. */
+export function isCockpitProcessName(name) {
+    const base = name.trim().split(/[\\/]/u).pop() ?? "";
+    return /^(node|cockpit)(\.exe|\.cmd)?$/iu.test(base);
+}

package/dist/commands/doctor-disk-words.js

@@ -1,6 +1,34 @@
 export function days(ms) {
     return (ms / 86_400_000).toFixed(1);
 }
+/**
+ * Why evidence on this disk has not landed, in words (BLI-12872). The labels
+ * stay in `--json`, the log and the heartbeat; a person reads the sentence.
+ */
+export function uncommittedReasonWords(reason) {
+    switch (reason) {
+        case "reconciled_unknown_to_server":
+            return "the server was asked and has never received them";
+        case "reconciled_not_committed":
+            return "the server knows of them but has not accepted them";
+        case "absent_from_ledger":
+            return "this laptop has no record that the server accepted them";
+        default:
+            return reason.replaceAll("_", " ");
+    }
+}
+/** The same for objects the server refused outright (terminal). */
+export function terminalReasonWords(reason) {
+    if (reason === "storage_rejected_object_too_large" || /_failed_http_413/u.test(reason))
+        return "too large for storage";
+    if (reason === "storage_rejected_media_type")
+        return "a file type storage refuses";
+    if (reason === "secret_guard_rejected")
+        return "held back by the secret guard";
+    if (reason === "staging_missing_after_restage" || reason.startsWith("staging_restage_failed"))
+        return "the staged copy could not be rebuilt";
+    return reason.replaceAll("_", " ").replaceAll(":", " ");
+}
 /**
  * What the drain did, in the sentence a person reads (BLI-3797).
  *
@@ -93,7 +121,10 @@ export function footprintLine(footprint) {
         `state ${mib(footprint.state.state_bytes + footprint.spool_bytes)} MB`,
     ];
     if (footprint.state.other_bytes > 0) {
-        parts.push(`unrecognised ${mib(footprint.state.other_bytes)} MB`);
+        // BLI-12872: 108 MB sat here unnamed. Tower never deletes these and never
+        // leaves them anonymous: the biggest are named so somebody can register them.
+        const named = footprint.state.other_largest.map((entry) => `${entry.name} ${mib(entry.bytes)} MB`).join(", ");
+        parts.push(`unrecognised ${mib(footprint.state.other_bytes)} MB${named ? ` (largest: ${named}; Tower never deletes these)` : ""}`);
     }
     parts.push(lastPrunePhrase(footprint));
     return parts.join(", ");
@@ -135,11 +166,11 @@ export function diskRowMessage(footprint, capBytes) {
     // `reconciled_unknown_to_server` on 234 objects whose oldest was 45 days old,
     // which is a different problem from a delivery that failed this morning.
     if (staging.terminal_count) {
-        parts.push(`${staging.terminal_count} terminal object(s), ${mib(staging.terminal_bytes ?? 0)} MB excluded from cap; reclaimable with \`cockpit clean\`: ${Object.keys(staging.terminal_reasons ?? {}).join(", ")}`);
+        parts.push(`${staging.terminal_count} terminal object(s), ${mib(staging.terminal_bytes ?? 0)} MB excluded from cap; reclaimable with \`cockpit clean\`: ${Object.keys(staging.terminal_reasons ?? {}).map(terminalReasonWords).join(", ")}`);
     }
     const dominant = staging.dominant_uncommitted_reason;
     if (dominant) {
-        parts.push(`oldest undelivered ${days(dominant.oldest_disk_age_ms)}d; biggest reason ${dominant.reason} on ${dominant.count} object(s), ${mib(dominant.bytes)} MB`);
+        parts.push(`oldest undelivered ${days(dominant.oldest_disk_age_ms)}d; biggest reason: ${uncommittedReasonWords(dominant.reason)} (${dominant.count} object(s), ${mib(dominant.bytes)} MB)`);
     }
     // BLI-3619's second half: "unknown" means the local ledger's own capped
     // memory cannot say, never that delivery failed — and the one command that

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

@@ -238,13 +238,23 @@ function positiveNumberOrZero(value) {
         ? value
         : 0;
 }
-/** Names only the sync receipt's recorded causes. Missing evidence names itself. */
-export function syncFailureMessage(parsed) {
+/**
+ * Names only the sync receipt's recorded causes. Missing evidence is said in
+ * words, never as a label (BLI-12872): on 2026-10-07 a person read
+ * `sync_failure_receipt_missing` as the whole answer. A sync that exited with
+ * no recorded reason did not tell us why, so the sentence says that and names
+ * the one thing a person can do to see it: run the sync themselves.
+ */
+export function syncFailureMessage(parsed, exitCode) {
     const reasons = typeof parsed?.failure_reason === "string"
         ? [parsed.failure_reason]
         : Array.isArray(parsed?.failure_reasons)
             ? parsed.failure_reasons.filter((value) => typeof value === "string" && value.length > 0)
             : [];
-    const reason = reasons.join("; ") || "sync_failure_receipt_missing";
+    if (reasons.length === 0) {
+        console.error("[cockpit-doctor] sync failed and left no recorded reason", JSON.stringify({ reason: "sync_failure_receipt_missing", exit_code: exitCode ?? null, parsed_receipt: parsed !== null }));
+        return `the sync stopped${exitCode === undefined ? "" : ` (exit code ${exitCode})`} without saying why; run \`cockpit sync\` to watch it and read what it prints`;
+    }
+    const reason = reasons.join("; ");
     return /staging_cap/u.test(reason) ? `${reason}; see disk-bounded and run \`cockpit clean --dry-run\`` : reason;
 }