@bli-cockpit/cli 0.2.30 → 0.2.32

package/dist/adapters/agent-image-evidence.js

@@ -29,6 +29,10 @@ export async function collectAgentImageEvidenceFromJsonlFile(options) {
             record = JSON.parse(line);
         }
         catch {
+            // Deliberately silent (BLI-3238). Per line of a transcript, and this
+            // scan is looking for image records specifically — a line it cannot
+            // parse is a line that was not going to be one. The transcript's own
+            // adapter already counts parse errors at the session grain.
             continue;
         }
         for (const candidate of imageCandidatesFromRecord(record, {

package/dist/adapters/attribution-core.js

@@ -347,6 +347,10 @@ function fallbackToTranscriptOriginForDeletedRepo(options) {
             return !options.pathExists?.(value);
         }
         catch {
+            // Deliberately silent (BLI-3238). This is an existence PROBE and
+            // failure is the answer: a path we cannot test is a path we cannot
+            // claim is missing, so the candidate is passed over. The scorer is
+            // pure and synchronous by design and has no channel to report on.
             return false;
         }
     }) ?? null;
@@ -386,6 +390,10 @@ function terminalReasonForRecordedPaths(paths, pathExists) {
             return pathExists(value);
         }
         catch {
+            // Deliberately silent (BLI-3238), same probe as above: "cannot test"
+            // folds into "does not exist", which is the conservative direction —
+            // it keeps the older `repo_not_on_disk` label rather than inventing
+            // `cwd_not_a_repo`.
             return false;
         }
     });
@@ -514,6 +522,10 @@ function canonicalExistingAttributionPath(value) {
         return attributionPathApi(value).resolve(realpathSync(value));
     }
     catch {
+        // Deliberately silent (BLI-3238). `realpathSync` is the test for "does
+        // this path resolve to something real?", and `null` — "no canonical form"
+        // — is the answer, not a degradation. Callers already treat a null here
+        // as one more alias that does not apply.
         return null;
     }
 }

package/dist/adapters/car-state.js

@@ -2,6 +2,7 @@ import { SourceScanResultSchema, } from "@bli-cockpit/telemetry-core";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { makeSourceAdapterIdentity, parseTicketIdFromText, } from "./common.js";
+import { describeError, isMissingFileFailure } from "../health-detail.js";
 export async function collectCarState(context) {
     const ticketsDir = path.join(context.repoRoot, ".codex-autorunner", "tickets");
     try {
@@ -41,7 +42,17 @@ export async function collectCarState(context) {
             facts,
         };
     }
-    catch {
+    catch (error) {
+        // `car_not_present` is honest for a repo with no `car/` folder, which is
+        // most of them, so a missing directory stays quiet. It is also what a
+        // malformed ticket file collapses to — and that version silently costs the
+        // repo its ticket binding while reporting the ordinary answer (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[car-state] car folder present but unreadable, reporting it as not present", JSON.stringify({
+                reason: "car_not_present",
+                ...describeError(error),
+            }));
+        }
         const facts = {
             present: false,
             current_ticket: null,

package/dist/adapters/claude-attribution.js

@@ -5,6 +5,7 @@ import { createReadStream, existsSync } from "node:fs";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { describeError } from "../health-detail.js";
 import { SESSION_FILE_UUID_PATTERN, isPathWithin, sanitizeSessionId, scoreSignalsAgainstWorktrees, sessionIdFromFileName, shortHash, } from "./attribution-core.js";
 /**
  * Deterministic Claude Code session JSONL -> repo/worktree attribution.
@@ -89,11 +90,24 @@ async function discoverClaudeSessions(projectsDir, cutoffMs) {
     let sessionStatFailedCount = 0;
     let sidecarDirReadFailedCount = 0;
     let sidecarStatFailedCount = 0;
+    // Same shape as the Codex walk: first reason plus counts, once. Per-file
+    // lines across a store of thousands would be their own silence (BLI-3238).
+    let firstDirectoryFailure = null;
+    let firstStatFailure = null;
     let projectEntries;
     try {
         projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
     }
     catch (error) {
+        // The whole projects root. Absent means Claude Code has never run here;
+        // anything else means every Claude session on this machine is invisible
+        // and the scan still reports a clean zero.
+        if (!isMissingPathError(error)) {
+            console.error("[claude-attribution] Claude projects root unreadable; no sessions can be seen", JSON.stringify({
+                reason: "projects_root_unreadable",
+                ...describeError(error),
+            }));
+        }
         return {
             sessions,
             projectDirsSkipped,
@@ -112,8 +126,10 @@ async function discoverClaudeSessions(projectsDir, cutoffMs) {
             sessionEntries = await fs.readdir(projectDir, { withFileTypes: true });
         }
         catch (error) {
-            if (!isMissingPathError(error))
+            if (!isMissingPathError(error)) {
                 projectDirReadFailedCount += 1;
+                firstDirectoryFailure ??= describeError(error);
+            }
             continue;
         }
         for (const sessionEntry of sessionEntries) {
@@ -126,8 +142,9 @@ async function discoverClaudeSessions(projectsDir, cutoffMs) {
             try {
                 mainStat = await fs.stat(mainFile);
             }
-            catch {
+            catch (error) {
                 sessionStatFailedCount += 1;
+                firstStatFailure ??= describeError(error);
                 continue;
             }
             const sessionUuid = sessionEntry.name.replace(/\.jsonl$/i, "");
@@ -149,6 +166,18 @@ async function discoverClaudeSessions(projectsDir, cutoffMs) {
             });
         }
     }
+    if (projectDirReadFailedCount > 0 || sessionStatFailedCount > 0) {
+        console.error("[claude-attribution] Claude sessions were invisible to the walk", JSON.stringify({
+            reason: "session_discovery_incomplete",
+            project_dir_read_failed_count: projectDirReadFailedCount,
+            session_stat_failed_count: sessionStatFailedCount,
+            found_session_count: sessions.length,
+            ...(firstDirectoryFailure
+                ? { first_directory_failure: firstDirectoryFailure }
+                : {}),
+            ...(firstStatFailure ? { first_stat_failure: firstStatFailure } : {}),
+        }));
+    }
     return {
         sessions,
         projectDirsSkipped,
@@ -164,6 +193,15 @@ async function discoverSidecars(subagentsDir) {
         entries = await fs.readdir(subagentsDir, { withFileTypes: true });
     }
     catch (error) {
+        // Most sessions have no subagents at all, so absent is quiet. Anything
+        // else means the session is collected WITHOUT its subagent transcripts and
+        // nothing downstream can tell that from a session that had none.
+        if (!isMissingPathError(error)) {
+            console.error("[claude-attribution] subagent folder unreadable; sidecars omitted from this session", JSON.stringify({
+                reason: "sidecar_dir_unreadable",
+                ...describeError(error),
+            }));
+        }
         return {
             sidecars: [],
             sidecarsCapped: 0,
@@ -173,6 +211,7 @@ async function discoverSidecars(subagentsDir) {
     }
     const discovered = [];
     let statFailedCount = 0;
+    let firstSidecarStatFailure = null;
     for (const entry of entries) {
         // Only agent transcripts. `*.meta.json` carry operator-authored
         // descriptions and are never harvested (D3).
@@ -186,8 +225,9 @@ async function discoverSidecars(subagentsDir) {
         try {
             stat = await fs.stat(local_path);
         }
-        catch {
+        catch (error) {
             statFailedCount += 1;
+            firstSidecarStatFailure ??= describeError(error);
             continue;
         }
         discovered.push({
@@ -197,6 +237,14 @@ async function discoverSidecars(subagentsDir) {
             byteSize: stat.size,
         });
     }
+    if (statFailedCount > 0) {
+        console.error("[claude-attribution] subagent transcripts skipped", JSON.stringify({
+            reason: "sidecar_stat_failed",
+            stat_failed_count: statFailedCount,
+            found_sidecar_count: discovered.length,
+            ...firstSidecarStatFailure,
+        }));
+    }
     discovered.sort((a, b) => b.mtimeMs - a.mtimeMs);
     const capped = Math.max(0, discovered.length - CLAUDE_SESSION_MAX_SIDECAR_FILES);
     return {
@@ -241,9 +289,16 @@ async function attributeOneSession(session, worktrees, collectionRoots) {
         try {
             streamed = await streamMainSignals(session.mainFile);
         }
-        catch {
+        catch (error) {
             // A read race on one oversized main must not abort the whole scan; honor
-            // the per-file skip contract.
+            // the per-file skip contract. Per session, so worth a line each time:
+            // this is a whole session nobody will ever coach on (BLI-3238).
+            console.error("[claude-attribution] oversized session could not be streamed, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "stream_oversized_main",
+                byte_size: session.mainByteSize,
+                ...describeError(error),
+            }));
             return skippedResult(base, "file_read_failed");
         }
         signals = streamed.signals;
@@ -257,7 +312,13 @@ async function attributeOneSession(session, worktrees, collectionRoots) {
         try {
             raw = await fs.readFile(session.mainFile);
         }
-        catch {
+        catch (error) {
+            console.error("[claude-attribution] session file unreadable, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "read_main",
+                byte_size: session.mainByteSize,
+                ...describeError(error),
+            }));
             return skippedResult(base, "file_read_failed");
         }
         const content = raw.toString("utf8");
@@ -346,7 +407,16 @@ async function collectSidecarDiagnostics(sidecars, worktree) {
         try {
             raw = await fs.readFile(sidecar.local_path);
         }
-        catch {
+        catch (error) {
+            // `file_read_failed` stays on the sidecar row. Beside it: a subagent
+            // transcript that was stat'd successfully seconds ago and now will not
+            // read is a race worth being able to recognise (BLI-3238).
+            console.error("[claude-attribution] subagent transcript unreadable, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "read_sidecar",
+                byte_size: sidecar.byteSize,
+                ...describeError(error),
+            }));
             out.push({ ...entry, skipped_reason: "file_read_failed" });
             continue;
         }
@@ -397,6 +467,10 @@ function createSignalAccumulator() {
                 record = JSON.parse(line);
             }
             catch {
+                // Deliberately silent (BLI-3238), same as the Codex line parser: per
+                // LINE across hundreds of thousands, the last line of a live session
+                // is routinely half-written, the count travels in `parseErrorCount` at
+                // the right grain, and the error would carry transcript text.
                 parseErrorCount += 1;
                 return;
             }

package/dist/adapters/codex-attribution.js

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { normalizeGitOrigin } from "../repo-identity.js";
+import { describeError } from "../health-detail.js";
 import { sanitizeSessionId, scoreSignalsAgainstWorktrees, sessionIdFromFileName, shortHash, } from "./attribution-core.js";
 /**
  * Deterministic Codex session JSONL -> repo/worktree attribution.
@@ -74,6 +75,11 @@ async function discoverCodexJsonlFiles(dir, cutoffMs) {
     const secretPathSkippedCount = 0;
     const stack = Array.isArray(dir) ? [...dir] : [dir];
     const seenFiles = new Set();
+    // The counts already travel in the scan result; what never did is WHY, and
+    // one line per skipped file in a store of thousands would be its own kind of
+    // silence. First reason plus count, logged once (BLI-3238).
+    let firstDirectoryFailure = null;
+    let firstStatFailure = null;
     while (stack.length > 0) {
         const current = stack.pop();
         if (!current)
@@ -83,8 +89,10 @@ async function discoverCodexJsonlFiles(dir, cutoffMs) {
             entries = await fs.readdir(current, { withFileTypes: true });
         }
         catch (error) {
-            if (!isMissingPathError(error))
+            if (!isMissingPathError(error)) {
                 directoryReadFailedCount += 1;
+                firstDirectoryFailure ??= describeError(error);
+            }
             continue;
         }
         for (const entry of entries) {
@@ -99,8 +107,9 @@ async function discoverCodexJsonlFiles(dir, cutoffMs) {
             try {
                 stat = await fs.stat(full);
             }
-            catch {
+            catch (error) {
                 statFailedCount += 1;
+                firstStatFailure ??= describeError(error);
                 continue;
             }
             if (stat.mtimeMs >= cutoffMs) {
@@ -112,6 +121,18 @@ async function discoverCodexJsonlFiles(dir, cutoffMs) {
             }
         }
     }
+    if (directoryReadFailedCount > 0 || statFailedCount > 0) {
+        console.error("[codex-attribution] Codex sessions were invisible to the walk", JSON.stringify({
+            reason: "session_discovery_incomplete",
+            directory_read_failed_count: directoryReadFailedCount,
+            stat_failed_count: statFailedCount,
+            found_file_count: out.length,
+            ...(firstDirectoryFailure
+                ? { first_directory_failure: firstDirectoryFailure }
+                : {}),
+            ...(firstStatFailure ? { first_stat_failure: firstStatFailure } : {}),
+        }));
+    }
     out.sort((a, b) => b.mtimeMs - a.mtimeMs);
     return {
         files: out,
@@ -158,7 +179,15 @@ async function attributeOneSession(file, worktrees, collectionRoots) {
     try {
         read = await readCodexMetadataSignals(file.file);
     }
-    catch {
+    catch (error) {
+        // One skipped session, with `file_read_failed` on its row. Logged per
+        // session because it is per SESSION, not per file in a walk: a session
+        // that cannot be read is a session nobody will ever coach on (BLI-3238).
+        console.error("[codex-attribution] session file unreadable, skipping it", JSON.stringify({
+            reason: "file_read_failed",
+            byte_size: file.byteSize,
+            ...describeError(error),
+        }));
         return skippedResult(base, "file_read_failed");
     }
     base.content_hash_sha256 = read.contentHashSha256;
@@ -268,6 +297,11 @@ function absorbCodexSessionLine(state, line) {
         record = JSON.parse(line);
     }
     catch {
+        // Deliberately silent (BLI-3238). Per LINE, in files with hundreds of
+        // thousands of them, and the last line of a live session is routinely
+        // half-written — this is expected, not a failure. The count travels in
+        // `parseErrorCount` on the scan result, which is the right grain, and the
+        // error object would carry a fragment of the transcript.
         state.parseErrorCount += 1;
         return;
     }

package/dist/adapters/raw-evidence-manifest.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { describeError } from "../health-detail.js";
 import { remoteObjectKey, sha256 } from "./raw-evidence-keys.js";
 export const RAW_EVIDENCE_BUCKET = "ambient-raw-evidence";
 export const RAW_EVIDENCE_RETENTION_MODE = "remote_durable";
@@ -126,7 +127,17 @@ export function manifestDescribesEntries(manifestBytes, entries) {
         return (recorded.length === expected.length &&
             recorded.every((hash, index) => hash === expected[index]));
     }
-    catch {
+    catch (error) {
+        // `false` is the safe answer and is also what a legitimately-stale
+        // manifest returns, so the pack is simply rewritten either way. The
+        // difference is that an unparseable manifest means a pack was written
+        // half-way, which will repeat until someone knows it is happening.
+        console.error("[raw-evidence-manifest] manifest unparseable; treating the pack as not described", JSON.stringify({
+            reason: "manifest_unparseable",
+            byte_size: manifestBytes.byteLength,
+            expected_file_count: entries.length,
+            ...describeError(error),
+        }));
         return false;
     }
 }

package/dist/adapters/raw-evidence-pack-store.js

@@ -14,6 +14,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { makeManifest, manifestDescribesEntries, } from "./raw-evidence-manifest.js";
 import { writeRawEvidenceStagingState, } from "../raw-evidence-staging.js";
+import { describeError } from "../health-detail.js";
 /**
  * Turn the staging directory into the content-keyed pack directory.
  *
@@ -41,9 +42,20 @@ export async function promoteStagedPack(options) {
                 refilledFileCount: 0,
             };
         }
-        catch {
+        catch (error) {
             // A concurrent sync can win the race to the same content-keyed name.
-            // Losing it is fine: the winner staged the identical bytes.
+            // Losing it is fine: the winner staged the identical bytes — and that
+            // race is EEXIST/ENOTEMPTY/EPERM. A rename that fails for any other
+            // reason (no space, cross-device, read-only) also lands here and looks
+            // exactly like the benign race while the pack is never stored
+            // (BLI-3238).
+            if (!isPackRenameRaceError(error)) {
+                console.error("[raw-evidence-pack-store] could not move the staged pack into place", JSON.stringify({
+                    reason: "pack_rename_failed",
+                    pack_id: options.packId,
+                    ...describeError(error),
+                }));
+            }
         }
     }
     const refilledFileCount = await refillMissingPackFiles(evidenceDir, options.entries);
@@ -120,11 +132,24 @@ export async function persistStagingState(stateDir, staging, nowIso) {
     await writeRawEvidenceStagingState(stateDir, staging).catch((error) => {
         console.error("[raw-evidence] staging state write failed", JSON.stringify({
             reason: "staging_state_write_failed",
-            detail: error instanceof Error ? error.name : typeof error,
             staged_count: Object.keys(staging.staged).length,
+            // Was `error.name` alone, which is "Error" for every fs failure
+            // there is. The code is the part that distinguishes them (BLI-3238).
+            ...describeError(error),
         }));
     });
 }
+/**
+ * The codes `rename` produces when the destination already exists — which is
+ * the benign "another sync staged these identical bytes first" outcome. EPERM
+ * is Windows's version of it.
+ */
+function isPackRenameRaceError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM";
+}
 export async function ensurePrivateDir(dir) {
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });
     await chmodPrivate(dir, 0o700);

package/dist/adapters/raw-evidence-sanitize.js

@@ -1,5 +1,7 @@
-import { containsSecretLikeContent, redactSecretLikeContent, } from "@bli-cockpit/telemetry-core";
+import { containsSecretLikeContent, redactSecretLikeContent, scannedCleanRedactionMetadata, } from "@bli-cockpit/telemetry-core";
 import { sha256 } from "./raw-evidence-keys.js";
+import { describeError } from "../health-detail.js";
+/** BLI-3238: a crashed redactor has to say so; see the catch below. */
 export function sanitizeTextEvidenceForUpload(options) {
     const originalBytes = options.originalBytes ?? Buffer.from(options.text, "utf8");
     // Deliberately outside the try: the content guard is the cheap check that
@@ -35,9 +37,25 @@ export function sanitizeTextEvidenceForUpload(options) {
                 redactionResult,
             });
         }
-        return { status: "clean", bytes: originalBytes };
+        return {
+            status: "clean",
+            bytes: originalBytes,
+            redaction: scannedCleanRedactionMetadata(originalBytes),
+        };
     }
-    catch {
+    catch (error) {
+        // The redactor itself crashed. The stub below is the safe answer — a
+        // placeholder goes up instead of unredacted bytes — but it is also
+        // indistinguishable downstream from a file that was legitimately masked,
+        // so a systematic redactor bug would look like a machine that simply
+        // writes a lot of secrets. Never the text, never the field values: name,
+        // code and size only (BLI-3238).
+        console.error("[raw-evidence-sanitize] redaction crashed; uploading a stub instead of the content", JSON.stringify({
+            reason: "redaction_crashed",
+            byte_size: originalBytes.byteLength,
+            redacted_field_count: options.redactedFields.length,
+            ...describeError(error),
+        }));
         return stubForCrashedRedaction({
             text: options.text,
             originalBytes,

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,