@bli-cockpit/cli 0.2.29 → 0.2.31

package/dist/adapters/raw-evidence.js

@@ -7,6 +7,7 @@ import { makeSourceAdapterIdentity, } from "./common.js";
 import { collectAgentImageEvidenceFromJsonlFile, } from "./agent-image-evidence.js";
 import { defaultCodexSessionDirs, } from "./codex-attribution.js";
 import { isLiveRawEvidenceSyncAttribution } from "../raw-evidence-attribution-policy.js";
+import { describeError } from "../health-detail.js";
 import { contentKeyedRawEvidencePackId, DELIVERY_BACKOFF_BYPASS_REASON, DELIVERY_BACKOFF_HOLDING_REASON, deliveryBackoffApplies, evidenceSourceKey, heldSourceKeys, readRawEvidenceStagingState, recordStagedObject, resolveStagedObject, } from "../raw-evidence-staging.js";
 import { isSecretLikePath, safeKeySegment, sha256, shortHash, } from "./raw-evidence-keys.js";
 import { sanitizeTextEvidenceForUpload } from "./raw-evidence-sanitize.js";
@@ -868,7 +869,10 @@ async function collectOneEvidenceFile(collection, options) {
         }));
     }
     const evidenceBytes = sanitized.bytes;
+    // Both branches carry a record now (BLI-3277), so "was anything replaced?" is
+    // the status, never the presence of `redaction`.
     const redaction = sanitized.redaction;
+    const wasRedacted = sanitized.status === "redacted";
     const contentHash = sha256(evidenceBytes);
     if (collection.skipContentHashes.has(contentHash)) {
         collection.reused.push({
@@ -900,7 +904,7 @@ async function collectOneEvidenceFile(collection, options) {
         localPath: staged.local_path,
         relativePath,
         mediaType: options.mediaType,
-        redactedSummary: redaction
+        redactedSummary: wasRedacted
             ? `${options.redactedSummary} Secret-like values were deterministically redacted before upload.`
             : options.redactedSummary,
         redaction,
@@ -923,7 +927,16 @@ async function readEvidenceFileWithinCap(filePath, maxFileBytes) {
         try {
             stat = await fs.stat(filePath);
         }
-        catch {
+        catch (error) {
+            // The caller turns this into the `file_read_failed` skip label, which is
+            // the one label an operator can do nothing with. The file was discovered
+            // moments ago, so a failure here is a rotated session, a permission
+            // problem or a dead symlink — three different answers (BLI-3238).
+            console.error("[raw-evidence] evidence file could not be stat'd", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "stat",
+                ...describeError(error),
+            }));
             return { status: "read_failed" };
         }
         if (stat.size > maxFileBytes)
@@ -933,7 +946,12 @@ async function readEvidenceFileWithinCap(filePath, maxFileBytes) {
     try {
         bytes = await fs.readFile(filePath);
     }
-    catch {
+    catch (error) {
+        console.error("[raw-evidence] evidence file could not be read", JSON.stringify({
+            reason: "file_read_failed",
+            stage: "read",
+            ...describeError(error),
+        }));
         return { status: "read_failed" };
     }
     if (maxFileBytes && bytes.byteLength > maxFileBytes) {
@@ -999,7 +1017,16 @@ async function collectGitDiffFiles(collection, repoRoot) {
         try {
             diff = await runGitDiff(target.args, repoRoot);
         }
-        catch {
+        catch (error) {
+            // `git_diff_failed` is the skip label and stays. It covers git not being
+            // installed, the folder not being a repo, a locked index and a diff that
+            // exceeded the child-process buffer — and the diff is half the evidence
+            // for what someone actually changed, so losing it quietly matters.
+            console.error("[raw-evidence] git diff failed", JSON.stringify({
+                reason: "git_diff_failed",
+                diff_target: target.label,
+                ...describeError(error),
+            }));
             collection.skipped.push({
                 kind: "git_diff",
                 label: target.label,
@@ -1050,6 +1077,7 @@ async function stageOneGitDiff(collection, target) {
     }
     const raw = sanitized.bytes;
     const redaction = sanitized.redaction;
+    const wasRedacted = sanitized.status === "redacted";
     const contentHash = sha256(raw);
     if (collection.skipContentHashes.has(contentHash)) {
         collection.reused.push({
@@ -1093,7 +1121,7 @@ async function stageOneGitDiff(collection, target) {
         sourceKey: diffSourceKey,
         mediaType: "text/x-diff",
         redactedSummary: gitDiffSummary(target.label, {
-            redacted: Boolean(redaction),
+            redacted: wasRedacted,
             truncated: target.truncated,
         }),
         redaction,
@@ -1124,6 +1152,11 @@ async function walkJsonlFiles(dir, cutoffMs) {
     const out = [];
     const stack = Array.isArray(dir) ? [...dir] : [dir];
     const seen = new Set();
+    // Counted rather than logged per directory: a wide walk can hit many, and
+    // the useful signal is "N directories in the session store were skipped and
+    // here is the first reason", not N near-identical lines (BLI-3238).
+    let unreadableDirCount = 0;
+    let firstUnreadableDir = null;
     while (stack.length > 0) {
         const current = stack.pop();
         if (!current || isSecretLikePath(current))
@@ -1132,7 +1165,11 @@ async function walkJsonlFiles(dir, cutoffMs) {
         try {
             entries = await fs.readdir(current, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            // A directory that cannot be listed hides every session under it, and
+            // the walk's only visible effect is a smaller file count.
+            unreadableDirCount += 1;
+            firstUnreadableDir ??= describeError(error);
             continue;
         }
         for (const entry of entries) {
@@ -1155,6 +1192,14 @@ async function walkJsonlFiles(dir, cutoffMs) {
             out.push({ file: full, mtimeMs: stat.mtimeMs });
         }
     }
+    if (unreadableDirCount > 0) {
+        console.error("[raw-evidence] session-store directories skipped during the walk", JSON.stringify({
+            reason: "session_dir_unreadable",
+            unreadable_dir_count: unreadableDirCount,
+            found_file_count: out.length,
+            ...firstUnreadableDir,
+        }));
+    }
     out.sort((a, b) => b.mtimeMs - a.mtimeMs);
     return out.map((entry) => entry.file);
 }

package/dist/agent-rules.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 const MANAGED_BLOCK_START = "<!-- BLI_COCKPIT_AGENT_RULES:START -->";
 const MANAGED_BLOCK_END = "<!-- BLI_COCKPIT_AGENT_RULES:END -->";
 export async function installCodexAgentRules(options = {}) {
@@ -25,7 +26,18 @@ async function installAgentRulesForHost(host, options = {}) {
     try {
         existing = await readFile(rulesFile, "utf8");
     }
-    catch {
+    catch (error) {
+        // No rules file yet is the ordinary first install. A file that exists and
+        // will not read is treated as absent, and the write that follows would
+        // OVERWRITE it with a fresh block — so the reason is on the record before
+        // that happens (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[agent-rules] existing rules file unreadable, treating the host as uninstalled", JSON.stringify({
+                reason: "agent_rules_unreadable",
+                host,
+                ...describeError(error),
+            }));
+        }
         existed = false;
     }
     const prepared = prepareManagedBlockInstall(existing, block, scopePaths);
@@ -57,7 +69,16 @@ async function uninstallAgentRulesForHost(host, options = {}) {
     try {
         existing = await readFile(rulesFile, "utf8");
     }
-    catch {
+    catch (error) {
+        // `missing` is honest when the file is genuinely absent. When it exists
+        // and cannot be read, uninstall reports success having removed nothing.
+        if (!isMissingFileFailure(error)) {
+            console.error("[agent-rules] rules file unreadable, reporting nothing to uninstall", JSON.stringify({
+                reason: "agent_rules_unreadable",
+                host,
+                ...describeError(error),
+            }));
+        }
         return agentRulesResult(host, rulesFile, "missing", block, "missing");
     }
     const next = removeManagedBlock(existing);
@@ -91,7 +112,17 @@ async function inspectAgentRulesForHost(host, options = {}) {
     try {
         existing = await readFile(rulesFile, "utf8");
     }
-    catch {
+    catch (error) {
+        // `installed: false` is what an operator's doctor run sees. Absent is the
+        // truthful version of that; unreadable is a different problem wearing the
+        // same answer, and re-running the install would not fix it.
+        if (!isMissingFileFailure(error)) {
+            console.error("[agent-rules] rules file unreadable, reporting the host as not installed", JSON.stringify({
+                reason: "agent_rules_unreadable",
+                host,
+                ...describeError(error),
+            }));
+        }
         return {
             ...agentRulesResult(host, rulesFile, "missing", block, "missing"),
             installed: false,

package/dist/autostart.js

@@ -131,6 +131,9 @@ export async function uninstallAutostartAgent(options) {
     if (!(await fileExists(plistPath))) {
         return { status: "absent", label: AUTOSTART_LABEL, plist_path: plistPath };
     }
+    // Same reasoning as the install path above: an agent that was never loaded
+    // makes unload fail harmlessly, and the plist is removed either way, so the
+    // error is deliberately ignored (BLI-3238).
     await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
     await rm(plistPath, { force: true });
     return { status: "uninstalled", label: AUTOSTART_LABEL, plist_path: plistPath };

package/dist/backfill-lock.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { describeError } from "./health-detail.js";
 const BACKFILL_LOCK_FILENAME = "backfill.lock";
 const HEARTBEAT_INTERVAL_MS = 30_000;
 export const BACKFILL_LOCK_STALE_TAKEOVER_MS = 5 * 60_000;
@@ -65,10 +66,26 @@ async function tryExclusiveCreate(lockPath, token, now) {
         await handle.close();
         return true;
     }
-    catch {
+    catch (error) {
+        // Same trap as sync-lock: EEXIST means another backfill holds it, and
+        // anything else (permissions, full disk, read-only volume) is reported as
+        // the identical "already running" and would keep the historical sweep from
+        // ever starting, permanently and silently (BLI-3238).
+        if (!isBackfillLockHeldError(error)) {
+            console.error("[backfill-lock] could not create the lock file; reporting the lock as held", JSON.stringify({
+                reason: "backfill_lock_create_failed",
+                ...describeError(error),
+            }));
+        }
         return false;
     }
 }
+/** `wx` refusing because the lock exists — the ordinary contended case. */
+function isBackfillLockHeldError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "EEXIST");
+}
 async function writeBackfillLock(lockPath, token, now) {
     await fs.writeFile(lockPath, serializeBackfillLock(token, now), {
         mode: 0o600,
@@ -103,6 +120,10 @@ async function readBackfillLockRecord(lockPath) {
         };
     }
     catch {
+        // Deliberately silent (BLI-3238), same reasoning as sync-lock's reader:
+        // this is the "is anyone holding it?" probe, and every way it can fail
+        // means "not held", which is the answer the caller acts on. The failing
+        // ACQUIRE above owns the reporting.
         return null;
     }
 }

package/dist/commands/backfill.js

@@ -1,8 +1,9 @@
-import { NO_UPLOAD_ATTEMPT_RECORDED, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { NO_UPLOAD_ATTEMPT_RECORDED, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, notUploadableAttributionStateReason } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { describeError } from "../health-detail.js";
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
 import { defaultCodexSessionDirs, scanAndAttributeCodexSessions } from "../adapters/codex-attribution.js";
 import { RAW_EVIDENCE_DEFAULT_BYTE_BUDGET, RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET } from "../adapters/raw-evidence.js";
@@ -984,6 +985,10 @@ function isMissingFsError(error) {
 async function countReadOnlyGuards(candidates) {
     const counts = new Map();
     const retryableCandidateKeys = new Set();
+    // Aggregated: this runs over the whole archived history, so a per-candidate
+    // line could be thousands. The count already travels; the reason did not
+    // (BLI-3238).
+    let firstReadFailure = null;
     for (const candidate of candidates) {
         if (candidate.reason === "repo_not_on_disk") {
             increment(counts, "repo_not_on_disk");
@@ -1004,11 +1009,21 @@ async function countReadOnlyGuards(candidates) {
         try {
             await fs.readFile(candidate.file_path);
         }
-        catch {
+        catch (error) {
             increment(counts, "file_read_failed");
+            firstReadFailure ??= describeError(error);
             retryableCandidateKeys.add(candidateCursorKey(candidate));
         }
     }
+    const readFailedCount = counts.get("file_read_failed") ?? 0;
+    if (readFailedCount > 0) {
+        console.error("[cockpit-backfill] archived sessions could not be read", JSON.stringify({
+            reason: "file_read_failed",
+            read_failed_count: readFailedCount,
+            candidate_count: candidates.length,
+            ...firstReadFailure,
+        }));
+    }
     return {
         counts,
         retryable_candidate_keys: retryableCandidateKeys,
@@ -1128,13 +1143,23 @@ async function ensureBackfillReportContext(options) {
         await readLocalWorkContextForRepo(options.paths, repoRoot);
     }
     catch {
-        // Context creation is best-effort here. postCodexSessionReport converts a
-        // remaining local-context failure into a retryable report reason.
+        // Reading it can legitimately fail — there is no context yet, which is
+        // precisely why the next line creates one. That read is a probe and stays
+        // silent; the CREATE is the branch that has to speak (BLI-3238).
         await startLocalWorkContext({
             homeDir: options.homeDir,
             repoRoot,
             branch: representative?.branch,
-        }).catch(() => undefined);
+        }).catch((error) => {
+            // Context creation is best-effort here: postCodexSessionReport converts
+            // a remaining local-context failure into a retryable report reason. But
+            // that reason is `collector_not_ready`, which points the operator at
+            // setup rather than at whatever actually failed here.
+            console.error("[cockpit-backfill] could not start a local work context for the batch", JSON.stringify({
+                reason: "work_context_start_failed",
+                ...describeError(error),
+            }));
+        });
     }
     return { repoRoot };
 }
@@ -1188,7 +1213,8 @@ async function syncBackfillBatch(options) {
         throw error;
     }
 }
-function buildBackfillSessionReport(options) {
+/** Exported for the BLI-3272 regression test; not part of the CLI surface. */
+export function buildBackfillSessionReport(options) {
     const uploadByKey = new Map();
     // BLI-2107: an outcome that names a failure but has no pointer used to be
     // dropped on the floor here, taking its reason with it.
@@ -1275,7 +1301,15 @@ function buildBackfillSessionReport(options) {
                         upload_reason: noUploadReasonBySessionId.get(candidate.session_id) ??
                             NO_UPLOAD_ATTEMPT_RECORDED,
                     }
-                    : {}),
+                    : {
+                        // BLI-3272: and the refused-attribution branch says why too. Same
+                        // NULL/NULL hole as live sync, same fix — backfill is the path
+                        // that revisits old sessions, so leaving it silent would keep
+                        // rewriting the very rows this ticket found.
+                        upload_state: "not_uploaded",
+                        upload_reason: noUploadReasonBySessionId.get(candidate.session_id) ??
+                            notUploadableAttributionStateReason(candidate.reason),
+                    }),
         };
     });
 }

package/dist/commands/cli-io.js

@@ -67,6 +67,9 @@ export function parseCapturedJson(chunks) {
         return JSON.parse(text);
     }
     catch {
+        // Deliberately silent (BLI-3238). The parse IS the question this function
+        // asks — "did the nested command print JSON or human text?" — and both
+        // answers are valid; the caller replays the raw text when it is not JSON.
         return text;
     }
 }

package/dist/commands/collection-report.js

@@ -4,7 +4,7 @@ export function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
 export function displayTicketId(ticketId) {
-    return ticketId ?? "general ambient";
+    return ticketId ?? "none (general work)";
 }
 export function displayWorkLabel(status) {
     if (status.work_label && status.work_id)
@@ -12,13 +12,16 @@ export function displayWorkLabel(status) {
     return status.work_label ?? status.work_id ?? "no active work context";
 }
 function sourceFunnelLine(label, counts) {
-    const readFailures = counts.read_failures > 0 ? `, read_failures ${counts.read_failures}` : "";
-    return `${label} sessions: attributed ${counts.attributed}, fallback ${counts.attributed_fallback}, ambiguous ${counts.ambiguous}, unattributed ${counts.unattributed}, skipped ${counts.skipped}, stale ${counts.stale}${readFailures}`;
+    // Same counters, plain words. Every counter still prints, including the ones
+    // that are zero: a funnel that hides a bucket cannot show where sessions go.
+    const readFailures = counts.read_failures > 0 ? `, ${counts.read_failures} could not be read` : "";
+    return `${label} sessions: ${counts.attributed} matched to a repo, ${counts.attributed_fallback} by best guess, ${counts.ambiguous} unclear which repo, ${counts.unattributed} could not be matched, ${counts.stale} too old, ${counts.skipped} skipped${readFailures}`;
 }
 function attributionReportLine(summary) {
+    // The parenthesised value is the machine reason label and never changes.
     return summary.report_posted
-        ? "Attribution report: recorded"
-        : `Attribution report: skipped (${summary.report_reason})`;
+        ? "Session report: saved"
+        : `Session report: skipped (${summary.report_reason})`;
 }
 /**
  * One funnel line per source, an anomaly diagnostics line only when something
@@ -41,30 +44,31 @@ function claudeDiagnosticsLine(summary) {
     const claude = summary.claude;
     const parts = [];
     if (claude.sidecars_skipped)
-        parts.push(`sidecars_skipped ${claude.sidecars_skipped}`);
+        parts.push(`${claude.sidecars_skipped} helper sessions skipped`);
     if (claude.sidecars_capped)
-        parts.push(`sidecars_capped ${claude.sidecars_capped}`);
+        parts.push(`${claude.sidecars_capped} helper sessions cut short`);
     if (claude.sidecars_failed)
-        parts.push(`sidecars_failed ${claude.sidecars_failed}`);
+        parts.push(`${claude.sidecars_failed} helper sessions could not be read`);
     if (claude.mains_oversized)
-        parts.push(`mains_oversized ${claude.mains_oversized}`);
+        parts.push(`${claude.mains_oversized} sessions too big`);
     if (claude.oversized_lines_skipped)
-        parts.push(`oversized_lines_skipped ${claude.oversized_lines_skipped}`);
+        parts.push(`${claude.oversized_lines_skipped} oversized lines skipped`);
     if (claude.project_dirs_skipped)
-        parts.push(`project_dirs_skipped ${claude.project_dirs_skipped}`);
+        parts.push(`${claude.project_dirs_skipped} folders skipped`);
     if (claude.sessions_schema_drift)
-        parts.push(`schema_drift ${claude.sessions_schema_drift}`);
+        parts.push(`${claude.sessions_schema_drift} sessions in an unexpected format`);
     if (claude.growth_damped)
-        parts.push(`growth_damped ${claude.growth_damped}`);
+        parts.push(`${claude.growth_damped} fast-growing sessions slowed down`);
     if (claude.first_run_backfill)
-        parts.push("first_run_backfill");
+        parts.push("first run, catching up on history");
     if (summary.files_deferred_byte_budget)
-        parts.push(`deferred_byte_budget ${summary.files_deferred_byte_budget}`);
+        parts.push(`${summary.files_deferred_byte_budget} files held back, size limit`);
     if (summary.files_deferred_object_budget)
-        parts.push(`deferred_object_budget ${summary.files_deferred_object_budget}`);
-    return parts.length > 0 ? `Claude diagnostics: ${parts.join(", ")}` : null;
+        parts.push(`${summary.files_deferred_object_budget} files held back, file-count limit`);
+    return parts.length > 0 ? `Claude problems: ${parts.join(", ")}` : null;
 }
 export function rawEvidenceSyncLine(sync) {
+    // The reason lists themselves are machine labels and stay verbatim.
     const failures = sync.raw_evidence_failure_reasons.length > 0
         ? ` failures: ${sync.raw_evidence_failure_reasons.join(",")}`
         : "";
@@ -75,15 +79,15 @@ export function rawEvidenceSyncLine(sync) {
     // Neither used to appear anywhere, which is how a 1,030-attempt loop stayed
     // invisible (BLI-3066).
     const held = sync.raw_evidence_delivery_held_count > 0
-        ? ` held: ${sync.raw_evidence_delivery_held_count}`
+        ? `, ${sync.raw_evidence_delivery_held_count} waiting`
         : "";
     const stuck = sync.raw_evidence_stuck_object_count > 0
-        ? ` stuck: ${sync.raw_evidence_stuck_object_count} (worst ${sync.raw_evidence_max_delivery_attempts} attempt(s) since ${sync.raw_evidence_oldest_delivery_failure_at ?? "unknown"})`
+        ? `, ${sync.raw_evidence_stuck_object_count} stuck (${sync.raw_evidence_max_delivery_attempts} tries since ${sync.raw_evidence_oldest_delivery_failure_at ?? "unknown"})`
         : "";
-    return `Raw evidence: uploaded ${sync.raw_evidence_uploaded_object_count} object(s) in ${sync.raw_evidence_uploaded_chunk_count} chunk(s), reused ${sync.raw_evidence_reused_count}, failed ${sync.raw_evidence_failed_count}${held}${stuck}${failures}${retries}`;
+    return `Files: ${sync.raw_evidence_uploaded_object_count} uploaded, ${sync.raw_evidence_reused_count} already there, ${sync.raw_evidence_failed_count} failed${held}${stuck}${failures}${retries}`;
 }
 export function cursorStatusLine(sync) {
-    return `Cursor: ${sync.cursor_tracked_object_count} durable object(s) tracked`;
+    return `Tracked so far: ${sync.cursor_tracked_object_count} uploaded item(s)`;
 }
 /**
  * One line that cannot say "fine" while an object has never been accepted.

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { autostartStatus, installAutostartAgent } from "../autostart.js";
 import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
-import { redactedHealthDetail } from "../health-detail.js";
+import { describeError, redactedHealthDetail } from "../health-detail.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
@@ -146,14 +146,32 @@ async function fixCliLatest(context, state) {
     };
 }
 async function fixAuthState(context, state) {
-    const code = await context.deps.runLogin(context).catch(() => 1);
+    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
+        // ran and was declined (BLI-3238).
+        console.error("[cockpit-doctor] login repair threw", JSON.stringify({
+            reason: "auth_repair_failed",
+            ...describeError(error),
+        }));
+        return 1;
+    });
     if (code !== 0)
         return state;
     const checked = await context.deps.readAuth(context);
     return checked.status === "ok" ? checked : state;
 }
 async function fixRootState(context, state) {
-    await context.deps.resolveAndSaveRoots(context).catch(() => undefined);
+    await context.deps.resolveAndSaveRoots(context).catch((error) => {
+        // Roots ARE the collection boundary. If saving them throws and nothing
+        // says so, the machine converges to "no approved root" and collects
+        // nothing — a green-looking doctor run over an empty boundary, which is
+        // the failure mode this whole ticket exists for.
+        console.error("[cockpit-doctor] collection roots could not be resolved or saved", JSON.stringify({
+            reason: "roots_repair_failed",
+            ...describeError(error),
+        }));
+    });
     const checked = await context.deps.readRoots(context);
     return checked.status === "ok" ? checked : state;
 }
@@ -175,7 +193,7 @@ async function readAuthState(context) {
     if (session?.session_state === "valid" &&
         typeof session.device_token === "string" &&
         session.device_token) {
-        return ok("authed", "device_token_present", "device token present");
+        return ok("authed", "device_token_present", "this machine is signed in");
     }
     return hardStop("authed", "pairing_required", [
         "device is not signed in.",
@@ -216,12 +234,12 @@ async function checkAutostartState(context) {
         exec,
     });
     if (result.status === "loaded") {
-        return ok("autostart-alive", "already_installed", "autostart scheduler loaded");
+        return ok("autostart-alive", "already_installed", "background sync is running");
     }
     if (result.status === "unsupported") {
         return skipped("autostart-alive", "unsupported", result.message ?? "unsupported");
     }
-    return needsFix("autostart-alive", result.status === "not_loaded" ? "not_loaded" : "absent", "autostart is not loaded");
+    return needsFix("autostart-alive", result.status === "not_loaded" ? "not_loaded" : "absent", "background sync is not running");
 }
 async function fixAutostartState(context) {
     const exec = context.io.exec;
@@ -241,7 +259,7 @@ async function fixAutostartState(context) {
     if (result.loaded === false) {
         return fail("autostart-alive", "autostart_load_failed", result.message ?? "operating-system scheduler load failed");
     }
-    return ok("autostart-alive", "installed", "autostart installed and loaded");
+    return ok("autostart-alive", "installed", "background sync installed and running");
 }
 /**
  * Pure so it can be unit-tested without touching the real machine's home
@@ -261,10 +279,10 @@ export function backfillCompletionStepState(marker, roots) {
     }
     const oversized = marker?.oversized_skips;
     if (oversized && oversized.count > 0) {
-        return ok("backfill-complete", "complete_with_oversized_skips", `backfill completion covers the current saved roots and both session sources ` +
-            `(complete_with_oversized_skips · ${oversized.count} file${oversized.count === 1 ? "" : "s"} over the upload cap)`);
+        return ok("backfill-complete", "complete_with_oversized_skips", `caught up on old Codex and Claude sessions in every saved folder ` +
+            `(complete_with_oversized_skips · ${oversized.count} file${oversized.count === 1 ? "" : "s"} too big to upload)`);
     }
-    return ok("backfill-complete", "complete", "backfill completion covers the current saved roots and both session sources");
+    return ok("backfill-complete", "complete", "caught up on old Codex and Claude sessions in every saved folder");
 }
 async function checkBackfillState(context) {
     const paths = getCollectorRuntimePaths();
@@ -275,10 +293,10 @@ async function checkBackfillState(context) {
         return covered;
     const lock = await inspectBackfillLock(paths);
     if (lock.held) {
-        return needsFix("backfill-complete", "backfill_already_running", `backfill completion is not yet proven; another run holds the lock since ${lock.held_since ?? "unknown"}`);
+        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", "backfill completion marker missing");
+    return needsFix("backfill-complete", cursor.updated_at ? "partial" : "never_run", "the catch-up over your old sessions has not finished");
 }
 async function fixBackfillState(context) {
     const capture = capturedIo(context.io, !context.command.json);
@@ -308,20 +326,20 @@ async function fixBackfillState(context) {
 }
 async function checkGcState(context) {
     if (context.io.env["COCKPIT_DISABLE_GC"] === "1") {
-        return skipped("gc-checked", "skipped_disabled", "raw-evidence GC disabled");
+        return skipped("gc-checked", "skipped_disabled", "cleanup is switched off");
     }
     const paths = getCollectorRuntimePaths();
     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) {
-        return skipped("gc-checked", "skipped_throttled", "raw-evidence GC ran within 24h");
+        return skipped("gc-checked", "skipped_throttled", "cleanup already ran today");
     }
-    return needsFix("gc-checked", "due", "raw-evidence GC is due");
+    return needsFix("gc-checked", "due", "cleanup is due");
 }
 async function fixGcState(context) {
     const result = await runRawEvidenceLocalGc(getCollectorRuntimePaths(), context.io.env);
     if (result.skipped) {
-        return skipped("gc-checked", "skipped_throttled", "raw-evidence GC skipped");
+        return skipped("gc-checked", "skipped_throttled", "cleanup already ran today");
     }
     if (result.removed_dirs === 0) {
         return ok("gc-checked", "nothing_eligible", rawEvidenceGcSummary(result));
@@ -350,7 +368,16 @@ function parseDoctorSyncJson(stdout) {
         const parsed = JSON.parse(stdout.trim());
         return parsed && typeof parsed === "object" ? parsed : null;
     }
-    catch {
+    catch (error) {
+        // `null` sends doctor back to its regex field-scrape, quietly losing the
+        // BLI-2728 disambiguation. Something wrote to stdout that was not the one
+        // JSON document the contract promises — a stray console.log in the
+        // collector would do exactly this and look like nothing at all.
+        console.error("[cockpit-doctor] sync --json stdout was not one JSON document", JSON.stringify({
+            reason: "sync_json_unparseable",
+            byte_size: stdout.length,
+            ...describeError(error),
+        }));
         return null;
     }
 }
@@ -422,8 +449,8 @@ async function fixSyncState(context) {
         if (result.code !== 0) {
             const draining = syncBacklogDrainingVerdict(parsed);
             if (draining) {
-                return needsFix("sync-fresh", "backlog_draining", `${repoRoot}: raw-evidence backlog is still draining (${draining.remainingObjects} ` +
-                    `object${draining.remainingObjects === 1 ? "" : "s"} deferred this tick); ` +
+                return needsFix("sync-fresh", "backlog_draining", `${repoRoot}: still catching up (${draining.remainingObjects} ` +
+                    `file${draining.remainingObjects === 1 ? "" : "s"} left for later this run); ` +
                     "rerun `cockpit sync` to continue");
             }
             return fail("sync-fresh", status ?? "sync_failed", `sync failed for ${repoRoot}`);
@@ -464,9 +491,11 @@ function writeDoctorOutput(command, io, rows) {
         return;
     }
     writeLine(io.stdout, command.dryRun ? "Cockpit doctor dry-run" : "Cockpit doctor");
-    writeLine(io.stdout, "state step                 code                    result");
+    // The machine `code` stays in `--json`; a human reading the table wants the
+    // 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)} ${row.code.padEnd(23)} ${oneLine(row.message)}`);
+        writeLine(io.stdout, `${doctorMark(row)} ${row.id.padEnd(20)} ${oneLine(row.message)}`);
     }
     const explanations = rows.filter((row) => (row.hardStop || row.status === "fail") && row.message.includes("\n"));
     for (const row of explanations) {
@@ -545,6 +574,10 @@ function parseNpmVersion(stdout) {
         return typeof parsed === "string" && parsed.trim() ? parsed.trim() : null;
     }
     catch {
+        // Deliberately silent (BLI-3238). `npm view ... version` prints a bare
+        // `1.2.3` without `--json` and a quoted `"1.2.3"` with it; the parse is
+        // the test for which one this npm produced, and the unquoted fallback is
+        // the intended handling of the other form, not a failure.
         return trimmed.replace(/^"|"$/gu, "") || null;
     }
 }