@bli-cockpit/cli 0.2.30 → 0.2.32

package/dist/repo-identity.js

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { containsPath, isCodexWorktreePath } from "./root-normalization.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 const execFileAsync = promisify(execFile);
 const SKIPPED_DIR_NAMES = new Set([
     ".cache",
@@ -352,7 +353,16 @@ async function resolveBranchFromHead(repoRoot) {
         }
         return head ? `detached:${head.slice(0, 12)}` : "unknown";
     }
-    catch {
+    catch (error) {
+        // Not a repo → quiet, that is an ordinary approved folder. A `.git` that
+        // exists and will not read → every session from this worktree is labelled
+        // branch `unknown` and, until BLI-3238, nothing said why.
+        if (!isMissingFileFailure(error)) {
+            console.error("[repo-identity] could not read HEAD, branch recorded as unknown", JSON.stringify({
+                reason: "git_head_unreadable",
+                ...describeError(error),
+            }));
+        }
         return "unknown";
     }
 }
@@ -377,6 +387,10 @@ export function normalizeGitOrigin(rawOrigin) {
         return normalizeOriginParts(url.hostname, url.pathname);
     }
     catch {
+        // Deliberately silent (BLI-3238). `new URL` is being used as the test for
+        // "is this origin URL-shaped?", and a plain path or an unusual remote form
+        // failing to parse IS the answer — the fallback below is the intended
+        // normalization for exactly that case, not a degradation.
         return trimmed
             .replace(/\.git$/i, "")
             .replace(/^\/+|\/+$/g, "")

package/dist/scheduled-self-update.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { describeError } from "./health-detail.js";
 const SELF_UPDATE_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const SELF_UPDATE_THROTTLE_MARKER = ".last-self-update-check";
 /**
@@ -179,7 +180,16 @@ async function probeInstalledCliVersion(exec) {
         const version = parsed.dependencies?.["@bli-cockpit/cli"]?.version;
         return typeof version === "string" && version.trim() ? version.trim() : null;
     }
-    catch {
+    catch (error) {
+        // `null` means "installed version unknown", which suppresses the whole
+        // self-update decision including the BLI-2678 forced-version floor. A
+        // fleet stuck on an old CLI because `npm ls` started printing something
+        // unparseable would look exactly like a fleet that is up to date.
+        console.error("[self-update] could not read the installed CLI version from npm ls", JSON.stringify({
+            reason: "installed_version_unreadable",
+            byte_size: result.stdout.length,
+            ...describeError(error),
+        }));
         return null;
     }
 }
@@ -197,6 +207,9 @@ function parseNpmVersionField(stdout) {
         return typeof parsed === "string" && parsed.trim() ? parsed.trim() : null;
     }
     catch {
+        // Deliberately silent (BLI-3238), same as doctor.ts's copy: the parse is
+        // the test for whether this npm quoted its output, and the unquoted
+        // fallback is the intended handling of the other form.
         return trimmed.replace(/^"|"$/gu, "") || null;
     }
 }

package/dist/spool/install-event-outbox.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 OUTBOX_DIRECTORY = "install-events";
 const MAX_PENDING_ENTRIES = 100;
 const MAX_EVENTS_PER_ENTRY = 40;
@@ -44,12 +45,21 @@ export async function readPendingInstallEventEntries(paths) {
         try {
             const parsed = parseEntry(JSON.parse(await fs.readFile(filePath, "utf8")));
             if (!parsed) {
+                console.error("[install-outbox] discarding an entry that does not match the schema", JSON.stringify({ reason: "outbox_entry_invalid" }));
                 await fs.rm(filePath, { force: true });
                 continue;
             }
             entries.push(parsed);
         }
-        catch {
+        catch (error) {
+            // This branch DELETES a queued receipt. Whatever the reason — truncated
+            // write, bad JSON, no read permission — the machine loses a health event
+            // it was holding for the server, so it says which reason it was before
+            // dropping it (BLI-3238).
+            console.error("[install-outbox] discarding an unreadable entry", JSON.stringify({
+                reason: "outbox_entry_unreadable",
+                ...describeError(error),
+            }));
             await fs.rm(filePath, { force: true }).catch(() => undefined);
         }
     }

package/dist/spool/local-spool.js

@@ -416,6 +416,9 @@ async function fsyncDirectoryBestEffort(directoryPath) {
     catch {
         // Directory fsync is not supported by every host/filesystem (notably some
         // Windows versions). The file itself was fsynced before the atomic rename.
+        // Deliberately silent (BLI-3238): on those hosts this fails on every
+        // single write, so a line here would be pure noise on exactly the
+        // platform the collector most needs readable logs on.
     }
     finally {
         await handle?.close().catch(() => undefined);

package/dist/sync-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";
 /**
  * Single-flight lock for `cockpit sync`. A launchd timer and a manual sync can
  * fire at the same time and interleave the cursor read-modify-write; this lock
@@ -71,10 +72,27 @@ async function tryExclusiveCreate(lockPath, token, now) {
         await handle.close();
         return true;
     }
-    catch {
+    catch (error) {
+        // EEXIST is the whole point of `wx`: another sync holds the lock, and the
+        // caller reports `sync_already_running`. Any OTHER code — no permission on
+        // the cursors directory, a full disk, a read-only volume — produces the
+        // identical false answer, and every sync on the machine then exits saying
+        // another one is running while none ever is (BLI-3238).
+        if (!isLockHeldError(error)) {
+            console.error("[sync-lock] could not create the lock file; reporting the lock as held", JSON.stringify({
+                reason: "sync_lock_create_failed",
+                ...describeError(error),
+            }));
+        }
         return false;
     }
 }
+/** `wx` refusing because the lock exists — the ordinary contended case. */
+function isLockHeldError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === "EEXIST");
+}
 async function writeLock(lockPath, token, now) {
     await fs.writeFile(lockPath, serializeLock(token, now), { mode: 0o600 });
 }
@@ -108,6 +126,11 @@ async function readLock(lockPath) {
         };
     }
     catch {
+        // Deliberately silent (BLI-3238). This read is the "is anyone holding it?"
+        // probe: no lock file, a half-written one, a lock being removed underneath
+        // us — every one of those means "not held", which is the answer the caller
+        // wants and acts on correctly. Failure IS the result here. The failing
+        // ACQUIRE above is the branch that owns the reporting.
         return null;
     }
 }

package/dist/upload-agent-artifacts.js

@@ -11,6 +11,7 @@
  * throwing.
  */
 import { AgentImageArtifactReportRequestSchema, } from "@bli-cockpit/telemetry-core";
+import { describeError } from "./health-detail.js";
 import { readResponseJson } from "./upload-http.js";
 export async function reportAgentImageArtifacts(options) {
     const artifacts = agentArtifactsFromEvidence(options);
@@ -60,7 +61,16 @@ export async function reportAgentImageArtifacts(options) {
             recorded_count: Number.isFinite(recordedCount) ? recordedCount : 0,
         };
     }
-    catch {
+    catch (error) {
+        // The label stays `report_network_error` — it is the wire contract. What
+        // it never carried is WHICH network error, and DNS failure, TLS refusal,
+        // a proxy reset and a body that would not serialize are four different
+        // repairs wearing one name (BLI-3238).
+        console.error("[agent-artifacts] report request failed before a status came back", JSON.stringify({
+            reason: "report_network_error",
+            artifact_count: artifacts.length,
+            ...describeError(error),
+        }));
         return { posted: false, reason: "report_network_error", recorded_count: 0 };
     }
 }

package/dist/upload-envelope.js

@@ -24,6 +24,7 @@ import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorCo
 import { runLocalSourceCollectors } from "./adapters/local-sources.js";
 import { defaultCodexSessionDirs, } from "./adapters/codex-attribution.js";
 import { normalizeDashboardUrl } from "./upload-http.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
 export class LocalUploadBlockedError extends Error {
     blocker;
     retry_hint;
@@ -40,7 +41,16 @@ export async function buildLocalAmbientEnvelope(options = {}) {
     const collector = await readPairedCollector(paths);
     const { config, sessionFile, session } = collector;
     const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
-    const activeContext = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => {
+    const activeContext = await readLocalWorkContextForRepo(paths, repoRoot).catch((error) => {
+        // The operator is told "run `cockpit start`", which is right when the file
+        // is simply absent and wrong when it exists and will not parse — the same
+        // advice, forever, on a machine that has already run it (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] work context present but unreadable, reporting it as missing", JSON.stringify({
+                reason: "missing_context",
+                ...describeError(error),
+            }));
+        }
         throw new LocalUploadBlockedError("missing_context", "Active work context missing. Run `cockpit start --workspace \"$PWD\"` before `cockpit sync`.", "cockpit start --workspace \"$PWD\"");
     });
     const repoLabel = safeRepoLabel(activeContext.repo_label ?? repoRoot);
@@ -132,10 +142,27 @@ export async function buildLocalAmbientEnvelope(options = {}) {
  * with no next step is what turns a five-second fix into a support thread.
  */
 async function readPairedCollector(paths) {
-    const config = await readLocalCollectorConfig(paths).catch(() => {
+    const config = await readLocalCollectorConfig(paths).catch((error) => {
+        // `not_installed` tells the operator to reinstall the CLI. That is the
+        // wrong instruction for a config that exists and is corrupt, and there was
+        // no way to tell which one this machine hit.
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] collector config present but unreadable, reporting it as not installed", JSON.stringify({
+                reason: "not_installed",
+                ...describeError(error),
+            }));
+        }
         throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit do-everything` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit do-everything");
     });
-    const sessionFile = await readLocalCollectorSessionFile(paths).catch(() => {
+    const sessionFile = await readLocalCollectorSessionFile(paths).catch((error) => {
+        // Same trap on the pairing half: `unpaired` sends the operator to
+        // `cockpit login`, which does not fix an unreadable session file.
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] session file present but unreadable, reporting the machine as unpaired", JSON.stringify({
+                reason: "unpaired",
+                ...describeError(error),
+            }));
+        }
         throw new LocalUploadBlockedError("unpaired", "No paired collector session found. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
     });
     const session = await readLocalSessionReference(paths);

package/dist/upload-http.js

@@ -21,6 +21,16 @@ export async function readResponseJson(response) {
         return JSON.parse(text);
     }
     catch {
+        // The text itself is never logged: a proxy error page is unbounded and can
+        // carry anything. The shape is the useful part — an HTML body under a 200
+        // means something in front of the dashboard answered instead of it, which
+        // reads downstream as an ordinary upload failure (BLI-3238).
+        console.error("[cockpit-http] 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/upload-session-reports.js

@@ -27,6 +27,7 @@ import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorCo
 import { readLocalUploadSpoolState, recordPendingSessionReport, recordSessionReportFailure, recordSessionReportSuccess, } from "./spool/local-spool.js";
 import { makeCollectorProvenance, makeUploadWorkContext, safeRepoLabel, } from "./upload-envelope.js";
 import { normalizeDashboardUrl, readResponseJson } from "./upload-http.js";
+import { describeError } from "./health-detail.js";
 /** Attempts per chunk, and the linear 250ms-per-attempt backoff between them. */
 const DEFAULT_REPORT_ATTEMPTS = 3;
 const REPORT_RETRY_BACKOFF_STEP_MS = 250;
@@ -73,7 +74,19 @@ export async function postCodexSessionReport(options) {
             sessions: options.sessions,
         });
     }
-    catch {
+    catch (error) {
+        // `collector_not_ready` covers this whole block — config read, session
+        // read, work-context read AND the report request itself. The label is
+        // kept (it is what the receipt contract carries) but it is broader than
+        // its name suggests: a network failure inside `reportCodexSessionAttributions`
+        // also lands here and reads as "this machine is not set up". The detail is
+        // now the only way to tell those apart. Flagged, not reclassified —
+        // narrowing the label is a contract change (BLI-3238).
+        console.error("[session-reports] could not report session attributions", JSON.stringify({
+            reason: "collector_not_ready",
+            session_count: options.sessions.length,
+            ...describeError(error),
+        }));
         return emptyCodexSessionReportResult("collector_not_ready");
     }
 }
@@ -125,7 +138,15 @@ export async function flushPendingCodexSessionReports(options) {
             readLocalSessionReference(paths),
         ]);
     }
-    catch {
+    catch (error) {
+        // This marks every queued report as failed. The count is what makes it
+        // worth a line: an unreadable session file here strands N reports at once
+        // and the only visible trace is a spool that stops draining (BLI-3238).
+        console.error("[session-reports] session file unreadable, failing the pending reports", JSON.stringify({
+            reason: "collector_not_ready",
+            pending_report_count: state.pending_session_reports.length,
+            ...describeError(error),
+        }));
         return await failPendingSessionReports(paths, state.pending_session_reports, attemptedAt, "collector_not_ready");
     }
     if (session.session_state !== "valid") {
@@ -311,7 +332,19 @@ async function postCodexSessionAttributionChunk(options) {
                 }
             }
         }
-        catch {
+        catch (error) {
+            // Logged per attempt, on purpose: the interesting failure is the one
+            // that repeats. Three identical ECONNRESETs and one DNS failure followed
+            // by two resets are different stories, and `report_network_error` alone
+            // tells neither (BLI-3238).
+            console.error("[session-reports] report attempt failed before a status came back", JSON.stringify({
+                reason: "report_network_error",
+                attempt,
+                max_attempts: maxAttempts,
+                batch_index: options.batchIndex,
+                session_count: options.sessions.length,
+                ...describeError(error),
+            }));
             lastStatus = null;
             lastFailureReason = "report_network_error";
         }

package/dist/upload.js

@@ -6,6 +6,7 @@ import { recordUploadBlocked, recordUploadFailure, recordUploadSuccess, } from "
 import { buildLocalAmbientEnvelope, LocalUploadBlockedError, } from "./upload-envelope.js";
 import { applyRawEvidenceUploadOutcomes, hasRetryableEvidenceGap, logEvidenceBackoffBypassed, logEvidenceHeldByBackoff, logPermanentlyRejectedEvidence, partitionHeldEvidenceFiles, permanentEvidenceFailureReason, persistDeliveryAttempts, retrySourcesForFailedSync, retryableEvidenceGapReason, summarizeRawEvidenceDelivery, } from "./upload-evidence-delivery.js";
 import { reportAgentImageArtifacts } from "./upload-agent-artifacts.js";
+import { describeError } from "./health-detail.js";
 import { isNonEmptyString, readResponseJson, responseErrorMessage, } from "./upload-http.js";
 export { LocalUploadBlockedError, buildLocalAmbientEnvelope, } from "./upload-envelope.js";
 export { partitionHeldEvidenceFiles } from "./upload-evidence-delivery.js";
@@ -76,11 +77,21 @@ export async function syncLocalAmbientEnvelope(options = {}) {
             outcomes: uploadOutcomes,
             reused: built.raw_evidence_facts?.reused ?? [],
             cursorObjects: cursor.objects,
-        }).catch(() => ({
-            posted: false,
-            reason: "agent_artifact_report_local_error",
-            recorded_count: 0,
-        }));
+        }).catch((error) => {
+            // The whole point of `agent_artifact_report_local_error` is that it is
+            // NOT the network error the reporter already labels itself — it is a
+            // throw from our own code on the way in. That distinction is only
+            // useful if the throw says what it was (BLI-3238).
+            console.error("[cockpit-sync] agent image artifact report threw locally", JSON.stringify({
+                reason: "agent_artifact_report_local_error",
+                ...describeError(error),
+            }));
+            return {
+                posted: false,
+                reason: "agent_artifact_report_local_error",
+                recorded_count: 0,
+            };
+        });
         await recordIngestedSyncOutcome({
             paths,
             options,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "private": false,
   "type": "module",
   "bin": {
@@ -26,6 +26,6 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.22"
+    "@bli-cockpit/telemetry-core": "0.1.24"
   }
 }