@bli-cockpit/cli 0.2.30 → 0.2.32

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

package/dist/cursors/raw-evidence-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";
 /**
  * Durable local cursor for raw-evidence harvesting.
  *
@@ -41,7 +42,19 @@ export async function readRawEvidenceCursor(paths, options = {}) {
         const raw = JSON.parse(await fs.readFile(rawEvidenceCursorPath(paths, options.filename), "utf8"));
         return parseCursorState(raw);
     }
-    catch {
+    catch (error) {
+        // An empty cursor is the correct answer before the first sync, and saying
+        // so every 15 minutes would bury the case that matters. A cursor that
+        // exists and cannot be read is a different event entirely: the collector
+        // is about to re-offer every object it already delivered and no line
+        // anywhere says why (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[raw-evidence-cursor] cursor unreadable, starting from empty", JSON.stringify({
+                reason: "cursor_unreadable",
+                cursor_file: options.filename ?? PRIMARY_CURSOR_FILENAME,
+                ...describeError(error),
+            }));
+        }
         return emptyRawEvidenceCursorState();
     }
 }

package/dist/discovery-limits.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, } from "./repo-identity.js";
 import { getCollectorRuntimePaths } from "./local-state.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 const SCHEMA_VERSION = "cockpit-discovery-limits.v1";
 // A depth beyond this is a typo rather than a workspace, and an unbounded walk
 // on a huge tree is its own outage. Same for the repo cap.
@@ -32,7 +33,17 @@ export async function readSavedDiscoveryLimits(homeDir = os.homedir()) {
             max_repos: sanitizeLimit(parsed.max_repos, MAX_ALLOWED_REPOS),
         };
     }
-    catch {
+    catch (error) {
+        // No saved limits is the normal state and stays quiet. A file that exists
+        // and will not parse silently reinstates the shipped defaults, which is
+        // exactly the shape of the outage where depth 3 / 50 repos quietly
+        // undercollected for days — so it gets a line (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[discovery-limits] saved limits unreadable, falling back to defaults", JSON.stringify({
+                reason: "discovery_limits_unreadable",
+                ...describeError(error),
+            }));
+        }
         return {};
     }
 }

package/dist/evidence-upload-client.js

@@ -1,6 +1,7 @@
 import { COMMIT_CRASHED_PLATFORM, RAW_EVIDENCE_UPLOAD_DEFAULT_CHUNK_BYTES, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, RAW_EVIDENCE_UPLOAD_MAX_OBJECTS_PER_BEGIN, RawEvidenceLegacyUploadResponseSchema, RawEvidenceRedactionMetadataSchema, RawEvidenceUploadBeginResponseSchema, RawEvidenceUploadCommitResponseSchema, isPermanentUploadFailure, } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import { describeError } from "./health-detail.js";
 const DEFAULT_MAX_ATTEMPTS = 3;
 const RETRY_DELAY_MS = 250;
 export async function uploadRawEvidenceFilesChunked(options) {
@@ -16,7 +17,16 @@ export async function uploadRawEvidenceFilesChunked(options) {
         try {
             stat = await fs.stat(file.local_path);
         }
-        catch {
+        catch (error) {
+            // `file_read_failed` is a durable ledger label and stays. Beside it: a
+            // staged object that vanished (the GC won a race) and one the process
+            // has no permission to open are the same word and opposite repairs
+            // (BLI-3238).
+            console.error("[evidence-upload] staged object could not be stat'd", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "stat",
+                ...describeError(error),
+            }));
             outcomes.push(failedOutcome(file, "file_read_failed"));
             continue;
         }
@@ -32,7 +42,15 @@ export async function uploadRawEvidenceFilesChunked(options) {
         try {
             bytes = await fs.readFile(file.local_path);
         }
-        catch {
+        catch (error) {
+            // Stat succeeded and the read did not — narrower than the stat failure
+            // above and worth telling apart, so it carries its own stage label.
+            console.error("[evidence-upload] staged object could not be read after a successful stat", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "read",
+                byte_size: stat.size,
+                ...describeError(error),
+            }));
             outcomes.push(failedOutcome(file, "file_read_failed"));
             continue;
         }
@@ -437,7 +455,18 @@ async function requestJson(options, routePath, body) {
                 return { ok: response.ok, status: response.status, body: lastBody };
             }
         }
-        catch {
+        catch (error) {
+            // `status: 0` is this function's word for "no answer came back", and it
+            // travels all the way to the upload ledger without ever saying whether
+            // the request left the machine. This is the exact silence BLI-2528 sat
+            // behind for 57 days; the route is named, the body never is.
+            console.error("[evidence-upload] request failed before a status came back", JSON.stringify({
+                reason: "upload_request_transport_error",
+                route: routePath,
+                attempt,
+                max_attempts: maxAttempts,
+                ...describeError(error),
+            }));
             lastStatus = 0;
             lastBody = null;
         }
@@ -578,7 +607,15 @@ async function readResponseJson(response) {
     }
     catch {
         // The raw text is kept for the caller that wants to show it, never for a
-        // label or a log — it is an unbounded HTML page.
+        // label or a log — it is an unbounded HTML page. Its SHAPE is safe and is
+        // the part that matters: a non-JSON body means something in front of the
+        // dashboard answered instead of it (BLI-3067, BLI-3238).
+        console.error("[evidence-upload] 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 { message: text, [NON_JSON_RESPONSE_BODY_KEY]: "non_json" };
     }
 }

package/dist/health-detail.js

@@ -87,17 +87,126 @@ function localIdentifiers() {
         identifiers.push([os.hostname(), "[host]"]);
     }
     catch {
-        // A host with no resolvable name has nothing to leak.
+        // A host with no resolvable name has nothing to leak. Deliberately silent
+        // (BLI-3238): this runs inside the redactor, so reporting it here would
+        // recurse into the very function that is failing.
     }
     try {
         identifiers.push([os.userInfo().username, "[user]"]);
     }
     catch {
-        // Same: no account name available means none can travel.
+        // Same: no account name available means none can travel, and the same
+        // recursion argument applies.
     }
     // A one- or two-character name would match far too much ordinary text.
     return identifiers.filter(([value]) => value && value.length > 2);
 }
 function literalPattern(value) {
     return new RegExp(value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), "giu");
+}
+/**
+ * Describes a caught error in fields that are safe to log, and never throws
+ * doing it.
+ *
+ * BLI-3238. A bare `catch {}` in the harvester is how collection dies for days
+ * without anyone noticing (BLI-2528: 57 days, one probe away the whole time).
+ * The counter-pressure is that an error message on this machine is not neutral
+ * text — an fs error carries the operator's absolute path, a fetch error
+ * carries a host, and a parse error can carry a fragment of the transcript
+ * being parsed. So:
+ *
+ * - A syscall error (`code` + `syscall`) reports its code and syscall and
+ *   drops the message entirely. `ENOENT: no such file or directory, open
+ *   '/Users/<person>/…'` says nothing `ENOENT open` does not, and the tail is
+ *   pure local identifier.
+ * - Every other message goes through `redactedHealthDetail`, the same
+ *   secret-and-path scrubber the health receipts use before leaving the
+ *   machine, and is capped at `HEALTH_DETAIL_MAX_CHARS`.
+ * - One level of `cause` is unwrapped, because `TypeError: fetch failed` on
+ *   its own names nothing and its cause is the whole answer.
+ */
+export function describeError(error) {
+    if (!(error instanceof Error)) {
+        // `null` and `undefined` are fully described by their name; repeating them
+        // as a detail says nothing twice.
+        const named = error === null || error === undefined;
+        return {
+            error_name: error === null ? "null" : typeof error,
+            ...(named ? {} : detailField(safeString(error))),
+        };
+    }
+    const fields = {
+        error_name: error.name || "Error",
+        ...codeField(error),
+        ...syscallField(error),
+        ...messageField(error),
+    };
+    const cause = error.cause;
+    if (cause instanceof Error) {
+        const causeFields = describeError(cause);
+        if (causeFields.error_name)
+            fields.cause_name = causeFields.error_name;
+        if (causeFields.error_code)
+            fields.cause_code = causeFields.error_code;
+        if (causeFields.error_detail)
+            fields.cause_detail = causeFields.error_detail;
+    }
+    return fields;
+}
+/**
+ * Is this the ordinary "there is nothing there yet" failure?
+ *
+ * Nearly every collector read has a legitimate empty state — no cursor before
+ * the first sync, no config before onboarding, no session before login — and
+ * logging that on every 15-minute tick would bury the failures that matter.
+ * A read that fails for any OTHER reason is the interesting one: a corrupt
+ * cursor and a permission-denied config both read as "first run" today, and
+ * that is the exact shape of BLI-2528.
+ */
+export function isMissingFileFailure(error) {
+    const code = errorCode(error);
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+function codeField(error) {
+    const code = errorCode(error);
+    return code ? { error_code: code } : {};
+}
+function errorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    if (typeof code === "string" && code)
+        return code;
+    if (typeof code === "number")
+        return String(code);
+    return undefined;
+}
+function syscallField(error) {
+    const syscall = error.syscall;
+    return typeof syscall === "string" && syscall ? { error_syscall: syscall } : {};
+}
+/**
+ * The message, or nothing at all when the code and syscall already carry the
+ * whole meaning. Dropping it is not lost information: it is a path.
+ */
+function messageField(error) {
+    const syscall = error.syscall;
+    if (errorCode(error) && typeof syscall === "string" && syscall)
+        return {};
+    return detailField(error.message);
+}
+function detailField(message) {
+    const detail = redactedHealthDetail(message);
+    return detail ? { error_detail: detail } : {};
+}
+/** `String(value)` can itself throw on an exotic object; a describer must not. */
+function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        // Deliberately silent, and the only silence in this module that cannot be
+        // reported: the failure happened inside the reporter.
+        return "";
+    }
 }

package/dist/local-state.js

@@ -9,6 +9,7 @@ import { isSamePath, normalizeCollectionRoots, } from "./root-normalization.js";
 import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
 import { summarizeInstallEventOutbox } from "./spool/install-event-outbox.js";
 import { readRawEvidenceStagingState, summarizeStuckEvidence, } from "./raw-evidence-staging.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 const localCollectorPackage = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 export const LOCAL_COLLECTOR_VERSION = typeof localCollectorPackage.version === "string"
     ? localCollectorPackage.version
@@ -115,7 +116,16 @@ export async function pairLocalCollector(options = {}) {
     const homeDir = options.homeDir ?? os.homedir();
     const paths = getCollectorRuntimePaths(homeDir);
     await ensureRuntimeDirectories(paths);
-    const config = await readLocalCollectorConfig(paths).catch(() => {
+    const config = await readLocalCollectorConfig(paths).catch((error) => {
+        // "Local config missing" is correct when it is absent. A config that
+        // exists and will not parse gets the same sentence and the same useless
+        // advice — run onboard again, which will not fix it (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] collector config present but unreadable, reporting it as missing", JSON.stringify({
+                reason: "config_unreadable",
+                ...describeError(error),
+            }));
+        }
         throw new Error("Local config missing. Run `cockpit onboard` (or `cockpit install`) first, then retry `cockpit login`.");
     });
     const dashboardUrl = normalizeDashboardUrl(options.dashboardUrl ?? config.dashboard_url);
@@ -454,7 +464,18 @@ export async function readLocalSessionReference(paths, fallback = {}) {
         }
         return LocalUserSessionReferenceSchema.parse(rawSession);
     }
-    catch {
+    catch (error) {
+        // `session_state: "missing"` is correct before login and says so loudly
+        // enough on its own. It is also what a session file that EXISTS but is
+        // corrupt, truncated or unreadable collapses to — a paired machine that
+        // silently reads as never-signed-in, which is indistinguishable in every
+        // downstream receipt (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] session file present but unusable, reading as missing", JSON.stringify({
+                reason: "session_file_unusable",
+                ...describeError(error),
+            }));
+        }
         return LocalUserSessionReferenceSchema.parse({
             operator_id: fallback.operatorId ?? "unknown",
             auth_subject_id: "unknown",
@@ -480,7 +501,17 @@ export async function resolveGitBranch(repoRoot) {
         }
         return head ? `detached:${head.slice(0, 12)}` : "unknown";
     }
-    catch {
+    catch (error) {
+        // A folder that is not a git repo is a legitimate workspace under the
+        // session-first commandment, so a missing `.git` stays quiet. A `.git`
+        // that exists and cannot be read is a different thing: every session
+        // collected from this repo gets branch `unknown` and nothing says why.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] could not read HEAD, branch recorded as unknown", JSON.stringify({
+                reason: "git_head_unreadable",
+                ...describeError(error),
+            }));
+        }
         return "unknown";
     }
 }
@@ -499,13 +530,30 @@ async function ensureRuntimeDirectories(paths) {
     await fs.mkdir(paths.cursors_dir, { recursive: true, mode: 0o700 });
     await fs.mkdir(paths.work_contexts_dir, { recursive: true, mode: 0o700 });
     if (process.platform !== "win32") {
-        await Promise.all([
-            fs.chmod(paths.config_dir, 0o700).catch(() => undefined),
-            fs.chmod(paths.state_dir, 0o700).catch(() => undefined),
-            fs.chmod(paths.spool_dir, 0o700).catch(() => undefined),
-            fs.chmod(paths.cursors_dir, 0o700).catch(() => undefined),
-            fs.chmod(paths.work_contexts_dir, 0o700).catch(() => undefined),
-        ]);
+        // The `mode` above only applies to directories this call CREATES, so these
+        // chmods are what actually tightens a directory that already existed with
+        // looser bits. Failing means the operator's device token and cursors stay
+        // world-readable — non-fatal, deliberately, but not something to find out
+        // about never (BLI-3238). Reported by directory name only, never a path.
+        const tightened = [
+            ["config_dir", fs.chmod(paths.config_dir, 0o700)],
+            ["state_dir", fs.chmod(paths.state_dir, 0o700)],
+            ["spool_dir", fs.chmod(paths.spool_dir, 0o700)],
+            ["cursors_dir", fs.chmod(paths.cursors_dir, 0o700)],
+            ["work_contexts_dir", fs.chmod(paths.work_contexts_dir, 0o700)],
+        ];
+        await Promise.all(tightened.map(async ([name, work]) => {
+            try {
+                await work;
+            }
+            catch (error) {
+                console.error("[local-state] could not restrict a runtime directory to owner-only", JSON.stringify({
+                    reason: "runtime_dir_chmod_failed",
+                    directory: name,
+                    ...describeError(error),
+                }));
+            }
+        }));
     }
 }
 function workContextFile(paths, worktreeFingerprint) {
@@ -545,8 +593,38 @@ function stableWorkContextId(input) {
 function sha256(value) {
     return crypto.createHash("sha256").update(value, "utf8").digest("hex");
 }
+/**
+ * The one reader behind the config file, the session file and every work
+ * context — and therefore the one place worth reporting from.
+ *
+ * Roughly twenty call sites swallow this to `null` or a default with
+ * `.catch(() => null)`, each of them asking a reasonable question ("is this
+ * machine set up?") to which "no" is a legitimate answer. What none of them
+ * could distinguish is "no, nothing is there" from "yes, and it is corrupt or
+ * unreadable" — so the distinction is drawn HERE, once, rather than in twenty
+ * places where it would be twenty chances to forget (BLI-3238).
+ *
+ * The error still propagates unchanged; callers keep whatever they decided.
+ */
 async function readJsonFile(filePath) {
-    return JSON.parse(await fs.readFile(filePath, "utf8"));
+    try {
+        return JSON.parse(await fs.readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        // Absent is the ordinary pre-onboarding state on every one of these files
+        // and stays quiet; anything else means state exists and cannot be used.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] a collector state file exists but could not be read", JSON.stringify({
+                reason: "state_file_unreadable",
+                // Which file, without the path: the basename of these is a fixed
+                // vocabulary (`config.json`, `session.json`, a work-context
+                // fingerprint) and carries no repo or operator name.
+                state_file: path.basename(filePath),
+                ...describeError(error),
+            }));
+        }
+        throw error;
+    }
 }
 async function writeJsonFile(filePath, value) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -643,6 +721,15 @@ async function readResponseJson(response) {
         return JSON.parse(text);
     }
     catch {
+        // Pairing path. A captive portal or a proxy answering with HTML is the
+        // classic reason `cockpit login` fails on a new machine and the operator
+        // sees only "pair request failed". The body is never logged; its shape is.
+        console.error("[local-state] pairing 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 { message: text };
     }
 }

package/dist/onboarding-roots.js

@@ -294,6 +294,9 @@ function canonicalPath(input, pathApi = path, realpath = realpathSync) {
         return pathApi.resolve(realpath(resolved));
     }
     catch {
+        // Deliberately silent (BLI-3238), per the comment above: a path that does
+        // not exist yet is the ordinary input here, and the lexical resolve is the
+        // documented behavior for it, not a fallback after a failure.
         return resolved;
     }
 }

package/dist/raw-evidence-attribution-policy.js

@@ -3,6 +3,13 @@
  * fallback that produced a worktree identity. Session-first terminal labels
  * are uploadable only when attribution attached an approved-root synthetic
  * workspace; the label stays terminal and no repository provenance is invented.
+ *
+ * A `false` answer is a decision, and every caller that builds a session row
+ * MUST record it as one — `upload_state: "not_uploaded"` plus
+ * `notUploadableAttributionStateReason(<attribution reason>)` from
+ * `@bli-cockpit/telemetry-core`. Spreading `{}` on this branch is what put 1,256
+ * production sessions in `ambient_codex_sessions` with a NULL upload_state and a
+ * NULL upload_reason (BLI-3272): withheld, and silent about it.
  */
 export function isRawEvidenceUploadableAttributionState(state, hasApprovedWorkspace = false) {
     return (state === "attributed" ||

package/dist/raw-evidence-gc.js

@@ -227,6 +227,11 @@ async function packContentFingerprint(dir) {
             .digest("hex");
     }
     catch {
+        // Deliberately silent (BLI-3238) — and it is the one silence here that is
+        // already reported. `null` means "not fingerprintable", the dedup sweep
+        // counts every one of them as `unfingerprintable_dirs`, and that count is
+        // logged on EVERY sweep including the clean one. A line per pack would
+        // add nothing the sweep does not already say.
         return null;
     }
 }

package/dist/raw-evidence-staging.js

@@ -2,6 +2,7 @@ import { DELIVERY_BACKOFF_HOLDING } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 /**
  * Durable local state for raw-evidence STAGING and DELIVERY ATTEMPTS.
  *
@@ -67,7 +68,17 @@ export async function readRawEvidenceStagingState(stateDir) {
         const raw = JSON.parse(await fs.readFile(rawEvidenceStagingStatePath(stateDir), "utf8"));
         return parseStagingState(raw);
     }
-    catch {
+    catch (error) {
+        // Empty is right before the first staged pack. Unreadable is not: this
+        // file carries the delivery-attempt history, so losing it silently resets
+        // every backoff window and re-offers objects the server already refused
+        // (BLI-3066 is what that costs; BLI-3238 is why it now says so).
+        if (!isMissingFileFailure(error)) {
+            console.error("[raw-evidence-staging] staging state unreadable, delivery history reset", JSON.stringify({
+                reason: "staging_state_unreadable",
+                ...describeError(error),
+            }));
+        }
         return emptyRawEvidenceStagingState();
     }
 }