@bli-cockpit/cli 0.2.30 → 0.2.31

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/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;
 }
@@ -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;
     }
 }
@@ -547,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;
     }
 }

package/dist/commands/install-receipts.js

@@ -11,7 +11,7 @@
  */
 import os from "node:os";
 import { errorMessage, writeLine } from "./cli-io.js";
-import { maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
+import { describeError, maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
 import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
@@ -74,7 +74,17 @@ export async function reportInstallEventsBestEffort(options) {
             })),
         });
     }
-    catch {
+    catch (error) {
+        // The existing operator line survives, and is `--json`-only. This one is
+        // unconditional and carries the reason: the machine has just dropped the
+        // health receipts for a whole command, and a `--json` gate meant the
+        // normal interactive run said nothing at all (BLI-3238).
+        console.error("[install-receipts] could not queue install events; the receipts are lost", JSON.stringify({
+            reason: "local_write_failed",
+            command: options.command,
+            event_count: options.events.length,
+            ...describeError(error),
+        }));
         if (options.json) {
             writeLine(options.io.stderr, "Install event outbox unavailable: local_write_failed");
         }
@@ -112,9 +122,18 @@ export async function reportInstallEventsBestEffort(options) {
                 if (!response.ok) {
                     throw new Error(`http_${response.status}`);
                 }
-                const receipt = (await response
-                    .json()
-                    .catch(() => null));
+                const receipt = (await response.json().catch((error) => {
+                    // This reply carries the server-published `min_cli_version` floor
+                    // (BLI-2678). A body that will not parse means the floor is not
+                    // observed on this tick and the forced-update path silently does
+                    // nothing — while the 2xx above says the receipt landed fine.
+                    console.error("[install-receipts] receipt body unreadable; no min_cli_version observed", JSON.stringify({
+                        reason: "receipt_body_unreadable",
+                        http_status: response.status,
+                        ...describeError(error),
+                    }));
+                    return null;
+                }));
                 if (typeof receipt?.min_cli_version === "string" &&
                     receipt.min_cli_version.trim()) {
                     observedMinCliVersion = receipt.min_cli_version.trim();
@@ -124,10 +143,28 @@ export async function reportInstallEventsBestEffort(options) {
             catch (error) {
                 const failureReason = classifyInstallTelemetryError(error);
                 failures.push(failureReason);
+                // The classified reason is the coarse bucket the outbox row keeps;
+                // beside it, what actually happened. `network_error` covers DNS,
+                // TLS, timeout and abort, and only one of those is worth waking up
+                // for (BLI-3238).
+                console.error("[install-receipts] install event delivery failed, entry kept for retry", JSON.stringify({
+                    reason: failureReason,
+                    outbox_id: entry.outbox_id,
+                    ...describeError(error),
+                }));
                 await recordInstallEventAttemptFailure(paths, entry, {
                     attemptedAt: new Date().toISOString(),
                     failureReason,
-                }).catch(() => undefined);
+                }).catch((writeError) => {
+                    // Double failure: delivery failed AND the retry bookkeeping did.
+                    // The entry stays queued, so nothing is lost, but the attempt
+                    // count stops advancing and the outbox looks stuck for no reason.
+                    console.error("[install-receipts] could not record the delivery failure against the entry", JSON.stringify({
+                        reason: "attempt_bookkeeping_failed",
+                        outbox_id: entry.outbox_id,
+                        ...describeError(writeError),
+                    }));
+                });
             }
             finally {
                 clearTimeout(timeout);

package/dist/commands/install-update.js

@@ -295,7 +295,9 @@ async function findPublicReleaseRoot(startDir) {
         }
         catch {
             // Keep walking: nested packages may be missing package.json or have one
-            // without the release script.
+            // without the release script. Deliberately silent (BLI-3238) — this is
+            // a search, every level that is not the answer fails here, and the
+            // caller reports `null` when the walk finds nothing.
         }
         const parent = path.dirname(current);
         if (parent === current)

package/dist/commands/local-args.js

@@ -739,6 +739,10 @@ function looksLikeServiceRoleSecret(value) {
         return serviceCredentialPayloadPattern().test(payload);
     }
     catch {
+        // Deliberately silent (BLI-3238), and it must stay silent: this is the
+        // "is this argument a service-role JWT?" test, so a value that will not
+        // decode is simply not one. Anything logged here would be a fragment of a
+        // credential.
         return false;
     }
 }

package/dist/commands/local-auth.js

@@ -185,6 +185,15 @@ async function readJsonResponse(response) {
         return JSON.parse(text);
     }
     catch {
+        // OTP path. The text is handed to the caller for the human-facing message
+        // but never logged — it is an unbounded page from whatever answered. The
+        // shape is what says "a proxy replied, not the dashboard" (BLI-3238).
+        console.error("[local-auth] auth reply was not JSON", JSON.stringify({
+            reason: "response_body_not_json",
+            http_status: response.status,
+            byte_size: text.length,
+            content_type: response.headers.get("content-type") ?? "none",
+        }));
         return text;
     }
 }
@@ -260,6 +269,11 @@ export async function readOnboardSessionReuseCandidate(homeDir) {
         return await readLocalCollectorSessionFile(paths);
     }
     catch {
+        // Deliberately silent (BLI-3238). This is the "can we reuse an existing
+        // login?" probe and the fallback below reads the same file through the
+        // looser schema — which reports its own reason when it also fails
+        // (`session_file_unusable` in local-state). Logging here would double
+        // every line for one read.
         return readLocalSessionReference(paths);
     }
 }

package/dist/commands/local.js

@@ -23,6 +23,7 @@
 import path from "node:path";
 import { bufferedWritable, defaultExec, defaultIo, errorMessage, parseCapturedJson, replayCaptured, writeLine, } from "./cli-io.js";
 import { isLocalHelpRequest, localCommandHelp } from "./local-help.js";
+import { describeError, isMissingFileFailure } from "../health-detail.js";
 import { addInstallEvent, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { canReuseOnboardSession, pairLocalCollectorWithAuthFallback, readOnboardSessionReuseCandidate, requestPairingAccessToken, requestPairingAccessTokenDetailed, resolveInteractiveLoginEmail, resolveOnboardEmail, } from "./local-auth.js";
 import { collectionRootConsentAliases, persistOnboardingRootConfig, resolveOnboardingRootsForCommand, } from "./collection-roots.js";
@@ -1372,7 +1373,16 @@ async function runAnalyze(command, io) {
         return syncExitCode === 0 ? 1 : syncExitCode;
     }
     const paths = getCollectorRuntimePaths(command.homeDir);
-    const session = await readLocalCollectorSessionFile(paths).catch(() => {
+    const session = await readLocalCollectorSessionFile(paths).catch((error) => {
+        // "Not signed in" is the right sentence for an absent session file and the
+        // wrong one for a corrupt one, which `cockpit login` will not repair
+        // (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[cockpit-analyze] session file present but unreadable, reporting as not signed in", JSON.stringify({
+                reason: "session_file_unusable",
+                ...describeError(error),
+            }));
+        }
         throw new Error("Cockpit is not signed in. Run `cockpit onboard` or `cockpit login` first.");
     });
     const dashboardUrl = normalizeUrl(command.dashboardUrl ?? session.dashboard_url ?? DEFAULT_DASHBOARD_URL);
@@ -1436,6 +1446,15 @@ async function readAnalyzeApiResponse(response) {
         return value && typeof value === "object" ? value : {};
     }
     catch {
+        // `{}` erases whatever the analyze endpoint said, including its error, and
+        // the operator is left with a job id of `undefined` and no reason. The
+        // body is never logged; its shape is what identifies a proxy reply.
+        console.error("[cockpit-analyze] reply was not JSON", JSON.stringify({
+            reason: "response_body_not_json",
+            http_status: response.status,
+            byte_size: text.length,
+            content_type: response.headers.get("content-type") ?? "none",
+        }));
         return {};
     }
 }

package/dist/commands/public-root.js

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

package/dist/commands/session-sync.js

@@ -6,7 +6,8 @@
 import os from "node:os";
 import path from "node:path";
 import { getCollectorRuntimePaths, readLocalCollectorConfig, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "../local-state.js";
-import { CODEX_SESSION_ATTRIBUTION_STATE_RANK, NO_UPLOAD_ATTEMPT_RECORDED, } from "@bli-cockpit/telemetry-core";
+import { describeError } from "../health-detail.js";
+import { CODEX_SESSION_ATTRIBUTION_STATE_RANK, NO_UPLOAD_ATTEMPT_RECORDED, notUploadableAttributionStateReason, } from "@bli-cockpit/telemetry-core";
 import { flushPendingCodexSessionReports, LocalUploadBlockedError, queueCodexSessionReport, syncLocalAmbientEnvelope, } from "../upload.js";
 import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
@@ -376,8 +377,17 @@ export async function runAttributedWorktreeSync(options) {
         codexCursor.updated_at = now.toISOString();
         await writeRawEvidenceCursor(paths, codexCursor);
     }
-    catch {
-        // Best-effort: stale counts read 0 and observations re-record next sync.
+    catch (error) {
+        // Best-effort: stale counts read 0 and observations re-record next sync —
+        // which is fine ONCE. A cursor write that keeps failing means the sessions
+        // cursor never advances, every sync re-does the same work, and the only
+        // symptom is a stale count that is permanently zero (BLI-3238).
+        console.error("[session-sync] Codex session observations were not recorded", JSON.stringify({
+            reason: "session_cursor_update_failed",
+            source: "codex",
+            session_count: sessions.length,
+            ...describeError(error),
+        }));
     }
     if (claudeEnabled) {
         try {
@@ -398,8 +408,16 @@ export async function runAttributedWorktreeSync(options) {
                 sessionsOnly: true,
             });
         }
-        catch {
-            // Best-effort: a broken Claude cursor must not fail the sync.
+        catch (error) {
+            // Best-effort: a broken Claude cursor must not fail the sync. It must
+            // still say it is broken — otherwise the Claude half of collection
+            // quietly repeats itself forever.
+            console.error("[session-sync] Claude session observations were not recorded", JSON.stringify({
+                reason: "session_cursor_update_failed",
+                source: "claude_code",
+                session_count: sessions.length,
+                ...describeError(error),
+            }));
         }
     }
     const report = hadPendingSessionReports || queuedCurrentSessionReport
@@ -639,7 +657,18 @@ export function buildAgentSessionReport(options) {
                                     ? "sync_incomplete_this_pass"
                                     : NO_UPLOAD_ATTEMPT_RECORDED),
                         }
-                        : {}),
+                        : {
+                            // BLI-3272: the upload policy refused this session's
+                            // attribution state. That refusal used to spread `{}` here, so
+                            // the row landed with upload_state NULL and upload_reason NULL
+                            // — a withhold that named nothing, on 1,256 production
+                            // sessions. It is a decision like any other and it says so.
+                            // Any reason the pipeline did record still wins: it is the more
+                            // specific answer.
+                            upload_state: "not_uploaded",
+                            upload_reason: noUploadReasonByKey.get(key) ??
+                                notUploadableAttributionStateReason(result.reason),
+                        }),
         };
     });
 }

package/dist/commands/status.js

@@ -16,6 +16,7 @@ import { writeLine } from "./cli-io.js";
 import { displayTicketId, displayWorkLabel, shortSha, stuckEvidenceLine, } from "./collection-report.js";
 import { discoverCommandWorktrees } from "./local-discovery.js";
 import { defaultCodexSessionDirs } from "../adapters/codex-attribution.js";
+import { describeError } from "../health-detail.js";
 import { backfillCompletionCovers, emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { getCollectorRuntimePaths, inspectLocalCollectorStatus, readLocalCollectorConfig, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -204,6 +205,12 @@ async function countClaudeMainFilesBeforeCursor(projectsDir, oldestProcessedMs)
 /** Unreadable folders are skipped rather than failing the walk. */
 async function walkFiles(roots, onFile, shouldStop = () => false) {
     const stack = [...roots];
+    // Counted, then reported once at the end: `cockpit status` is what an
+    // operator reads to decide whether collection is healthy, and a walk that
+    // silently skipped half the store would answer that question wrong
+    // (BLI-3238).
+    let unreadableDirCount = 0;
+    let firstFailure = null;
     while (stack.length > 0 && !shouldStop()) {
         const current = stack.pop();
         if (!current)
@@ -212,7 +219,9 @@ async function walkFiles(roots, onFile, shouldStop = () => false) {
         try {
             entries = await readdir(current, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            unreadableDirCount += 1;
+            firstFailure ??= describeError(error);
             continue;
         }
         for (const entry of entries) {
@@ -227,4 +236,11 @@ async function walkFiles(roots, onFile, shouldStop = () => false) {
             }
         }
     }
+    if (unreadableDirCount > 0) {
+        console.error("[cockpit-status] folders skipped while counting", JSON.stringify({
+            reason: "status_walk_dir_unreadable",
+            unreadable_dir_count: unreadableDirCount,
+            ...firstFailure,
+        }));
+    }
 }

package/dist/cursors/backfill-cursor.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { describeError, isMissingFileFailure } from "../health-detail.js";
 export const BACKFILL_CURSOR_FILENAME = "backfill.json";
 export const BACKFILL_COMPLETION_MARKER_FILENAME = "backfill-complete.json";
 export const BACKFILL_COVERAGE_VERSION = "redacted-session-backfill.v3";
@@ -20,7 +21,17 @@ export async function readBackfillCursor(paths) {
         const raw = JSON.parse(await fs.readFile(backfillCursorPath(paths), "utf8"));
         return parseBackfillCursor(raw);
     }
-    catch {
+    catch (error) {
+        // Missing is the normal pre-backfill state. Present-but-unreadable means
+        // the historical sweep is about to restart from scratch, which looks
+        // identical from the outside and costs a full re-walk (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[backfill-cursor] cursor unreadable, restarting the sweep from empty", JSON.stringify({
+                reason: "backfill_cursor_unreadable",
+                cursor_file: BACKFILL_CURSOR_FILENAME,
+                ...describeError(error),
+            }));
+        }
         return emptyBackfillCursorState();
     }
 }
@@ -36,7 +47,17 @@ export async function readBackfillCompletionMarker(paths) {
         const raw = JSON.parse(await fs.readFile(backfillCompletionMarkerPath(paths), "utf8"));
         return parseBackfillCompletionMarker(raw);
     }
-    catch {
+    catch (error) {
+        // No marker means backfill has not finished, which is the ordinary state.
+        // A marker that cannot be read means a finished backfill will be re-run,
+        // and the machine should say so rather than quietly redo a day of work.
+        if (!isMissingFileFailure(error)) {
+            console.error("[backfill-cursor] completion marker unreadable, treating backfill as unfinished", JSON.stringify({
+                reason: "backfill_marker_unreadable",
+                marker_file: BACKFILL_COMPLETION_MARKER_FILENAME,
+                ...describeError(error),
+            }));
+        }
         return null;
     }
 }