@bli-cockpit/cli 0.2.39 → 0.2.41

package/dist/commands/workbook.js

@@ -14,7 +14,7 @@
  * on the two supported host families; `cockpit workbook tower workbook | less`
  * is the person's decision to make, not this command's.
  */
-import { writeLine, writeRaw } from "./cli-io.js";
+import { colorEnabled, writeLine, writeRaw } from "./cli-io.js";
 import { renderDocText, renderShelf, sectionSlice, } from "./workbook-render.js";
 import { loadPairedSession, towerFailureDetail, towerJsonRequest, } from "../tower-client.js";
 const READ_DEADLINE_MS = 30_000;
@@ -52,6 +52,7 @@ export async function runWorkbook(command, io) {
 // -------------------------------------------------------------------- index
 function writeIndex(command, io, payload, width) {
     const projects = payload.projects ?? [];
+    const styled = colorEnabled(io);
     if (command.project) {
         const found = projects.find((project) => project.slug === command.project);
         if (!found) {
@@ -73,7 +74,7 @@ function writeIndex(command, io, payload, width) {
             writeLine(io.stdout, JSON.stringify({ ok: true, project: found }));
         }
         else {
-            for (const line of renderShelf([found], width))
+            for (const line of renderShelf([found], width, styled))
                 writeLine(io.stdout, line);
         }
         logIndexRead(io, [found]);
@@ -83,7 +84,7 @@ function writeIndex(command, io, payload, width) {
         writeLine(io.stdout, JSON.stringify({ ok: true, projects }));
     }
     else {
-        for (const line of renderShelf(projects, width))
+        for (const line of renderShelf(projects, width, styled))
             writeLine(io.stdout, line);
     }
     logIndexRead(io, projects);
@@ -134,7 +135,8 @@ function writeDoc(command, io, payload, width) {
         writeRaw(io.stdout, selected);
     }
     else {
-        for (const line of renderDocText(payload, selected, width))
+        const lines = renderDocText(payload, selected, width, colorEnabled(io));
+        for (const line of lines)
             writeLine(io.stdout, line);
     }
     writeLine(io.stderr, `[workbook cli] doc read ${JSON.stringify({

package/dist/evidence-upload-client.js

@@ -102,14 +102,39 @@ export async function uploadRawEvidenceFilesChunked(options) {
         // (after retries) covers a new dashboard whose ledger migration has not
         // been applied yet. Both still serve the legacy v1 route.
         if (begin.status === 404 || begin.status >= 500) {
+            // Until BLI-3483 this downgrade abandoned the entire chunked path
+            // without a word, and the comment above named two causes that the fleet
+            // had no way to tell apart — an old dashboard versus an unapplied ledger
+            // migration. This is the BLI-2528 shape exactly: the code knew, the
+            // operator did not. Once per run, because `break` leaves the loop.
+            console.error("[evidence-upload] chunked upload unavailable; falling back to the legacy single-shot route", JSON.stringify({
+                reason: begin.status === 404
+                    ? "begin_route_absent"
+                    : "begin_server_error_after_retries",
+                http_status: begin.status,
+                server_reason: safeFailureDetail(begin.body) ?? "none",
+                objects_in_batch: batch.length,
+                objects_unresolved: loaded.length - resolvedEntries.size,
+            }));
             beginUnavailable = true;
             break;
         }
         if (!begin.ok) {
+            // The server's own `{ reason }` sat unread in this body while the ledger
+            // recorded the transport status and nothing else (BLI-3483); the commit
+            // path has read it since BLI-2528 and this one now does the same.
+            const beginDetail = safeFailureDetail(begin.body);
+            const beginReason = `begin_failed_http_${begin.status}${beginDetail ? `_${beginDetail}` : ""}`;
+            console.error("[evidence-upload] begin refused these objects", JSON.stringify({
+                reason: "begin_rejected",
+                http_status: begin.status,
+                server_reason: beginDetail ?? "none",
+                objects_in_batch: batch.length,
+            }));
             for (const entry of batch) {
-                outcomes.push(failedOutcome(entry.file, `begin_failed_http_${begin.status}`));
+                outcomes.push(failedOutcome(entry.file, beginReason));
                 for (const duplicate of entry.duplicates) {
-                    outcomes.push(failedOutcome(duplicate, `begin_failed_http_${begin.status}`));
+                    outcomes.push(failedOutcome(duplicate, beginReason));
                 }
                 resolvedEntries.add(entry);
             }
@@ -286,7 +311,21 @@ async function uploadOneObject(options, entry, disposition, chunkSizeBytes) {
                 content_base64: chunk.toString("base64"),
             });
             if (!chunkResponse.ok) {
-                return failedOutcome(entry.file, `chunk_${index}_failed_http_${chunkResponse.status}`, uploadedChunks);
+                // Same treatment the commit path has had since BLI-2528: the server's
+                // own reason rides on the label, so `chunk_3_failed_http_413` becomes
+                // `chunk_3_failed_http_413_object_too_large` and the ledger row names
+                // the cause instead of the transport (BLI-3483).
+                const chunkDetail = safeFailureDetail(chunkResponse.body);
+                console.error("[evidence-upload] chunk rejected", JSON.stringify({
+                    reason: "chunk_rejected",
+                    upload_id: disposition.upload_id,
+                    http_status: chunkResponse.status,
+                    server_reason: chunkDetail ?? "none",
+                    chunk_index: index,
+                    chunk_count: entry.chunkCount,
+                    uploaded_chunk_count: uploadedChunks,
+                }));
+                return failedOutcome(entry.file, `chunk_${index}_failed_http_${chunkResponse.status}${chunkDetail ? `_${chunkDetail}` : ""}`, uploadedChunks);
             }
             uploadedChunks += 1;
         }

package/dist/local-state.js

@@ -10,6 +10,7 @@ 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";
+import { serverFailureDetail } from "./upload-http.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
@@ -671,7 +672,7 @@ async function postPairStart(fetchImpl, dashboardUrl, body, accessToken) {
     });
     const parsed = await readResponseJson(response);
     if (!response.ok) {
-        throw new Error(responseErrorMessage(parsed, "Pair request failed"));
+        throw new Error(pairFailureMessage("Pair request failed", response, parsed));
     }
     return parsePairStartResponse(parsed);
 }
@@ -692,7 +693,7 @@ async function pollPairRequest(fetchImpl, dashboardUrl, options) {
         });
         const parsed = await readResponseJson(response);
         if (!response.ok) {
-            throw new Error(responseErrorMessage(parsed, "Pair polling failed"));
+            throw new Error(pairFailureMessage("Pair polling failed", response, parsed));
         }
         const status = readStringField(parsed, "status");
         if (status === "approved") {
@@ -713,6 +714,30 @@ async function pollPairRequest(fetchImpl, dashboardUrl, options) {
     }
     throw new Error("Timed out waiting for dashboard approval. Run `cockpit login` again.");
 }
+/**
+ * What `cockpit login` tells the operator when pairing is refused.
+ *
+ * "Pair request failed" was the whole message — five words, while the status
+ * code sat in hand (BLI-3483). A 401 (this build's token is not accepted), a
+ * 403 (the dashboard knows the device and is refusing it), a 404 (wrong
+ * dashboard URL) and a 502 (something in front of the dashboard answered) are
+ * four different next actions, and the operator could not tell them apart.
+ * `upload.ts` has named its HTTP status since it was written; this is the same
+ * shape. The server's own words come first when it supplied any, and the status
+ * always rides at the end so it is never the thing that got dropped.
+ *
+ * Logged as well as thrown: `cockpit login` failures happen on a machine that
+ * is not collecting yet, so the terminal is the only receipt there is.
+ */
+function pairFailureMessage(fallback, response, body) {
+    const serverWords = responseErrorMessage(body, fallback);
+    console.error("[local-state] pairing request refused", JSON.stringify({
+        reason: fallback === "Pair request failed" ? "pair_start_refused" : "pair_poll_refused",
+        http_status: response.status,
+        server_reason: serverFailureDetail(body) ?? "none",
+    }));
+    return `${serverWords} (HTTP ${response.status})`;
+}
 async function readResponseJson(response) {
     const text = await response.text();
     if (!text)

package/dist/upload-agent-artifacts.js

@@ -12,7 +12,7 @@
  */
 import { AgentImageArtifactReportRequestSchema, } from "@bli-cockpit/telemetry-core";
 import { describeError } from "./health-detail.js";
-import { readResponseJson } from "./upload-http.js";
+import { readResponseJson, serverFailureDetail } from "./upload-http.js";
 export async function reportAgentImageArtifacts(options) {
     const artifacts = agentArtifactsFromEvidence(options);
     if (artifacts.length === 0) {
@@ -37,7 +37,15 @@ export async function reportAgentImageArtifacts(options) {
             },
             body: JSON.stringify(payload),
         });
+        // Both non-2xx branches returned a label and said nothing (BLI-3483). An
+        // image that never gets reported is never redacted and never OCR'd, and
+        // the only place that fact existed was a return value the sync discards.
         if (response.status === 404) {
+            console.error("[agent-artifacts] the dashboard has no agent-artifact route; these images stay unreported", JSON.stringify({
+                reason: "agent_artifact_api_unavailable",
+                http_status: 404,
+                artifact_count: artifacts.length,
+            }));
             return {
                 posted: false,
                 reason: "agent_artifact_api_unavailable",
@@ -45,6 +53,13 @@ export async function reportAgentImageArtifacts(options) {
             };
         }
         if (!response.ok) {
+            const serverReason = serverFailureDetail(await readResponseJson(response));
+            console.error("[agent-artifacts] report refused", JSON.stringify({
+                reason: "report_failed",
+                http_status: response.status,
+                server_reason: serverReason ?? "none",
+                artifact_count: artifacts.length,
+            }));
             return {
                 posted: false,
                 reason: `report_failed_http_${response.status}`,
@@ -55,10 +70,20 @@ export async function reportAgentImageArtifacts(options) {
         const recordedCount = body && typeof body === "object"
             ? Number(body.recorded_count ?? 0)
             : 0;
+        const recorded = Number.isFinite(recordedCount) ? recordedCount : 0;
+        // The success branch too: "some images reported" and "every image
+        // reported" are different facts, and a count that is short of
+        // `artifact_count` is the only warning an operator would ever get.
+        console.error("[agent-artifacts] report recorded", JSON.stringify({
+            reason: "recorded",
+            http_status: response.status,
+            artifact_count: artifacts.length,
+            recorded_count: recorded,
+        }));
         return {
             posted: true,
             reason: "recorded",
-            recorded_count: Number.isFinite(recordedCount) ? recordedCount : 0,
+            recorded_count: recorded,
         };
     }
     catch (error) {

package/dist/upload-failure-reason.js

@@ -0,0 +1,121 @@
+/**
+ * The vocabulary a failed sync is allowed to use, and the bounded cause beside
+ * it.
+ *
+ * Before BLI-3483 the delivery path threw English sentences and the catch in
+ * `upload.ts` copied `error.message` straight into the spool row's
+ * `failure_reason`. Two consequences, both bad:
+ *
+ * - **Unbounded cardinality.** Every distinct server message became a distinct
+ *   "reason", so nothing downstream could count how many machines were failing
+ *   the same way. A reason label is only useful if it is drawn from a closed
+ *   set.
+ * - **Opposite causes wearing one name.** "Ambient ingest returned an incomplete
+ *   durable receipt." was the answer for a proxy that returned its own 200 AND
+ *   for a dashboard that genuinely persisted fewer rows than were sent. The
+ *   first is a network appliance in the way; the second is data loss. Same
+ *   sentence, opposite repairs.
+ *
+ * So a failure now carries two things: a `SyncFailureReason` from the list
+ * below, which is the bucket, and a detail of at most
+ * {@link SYNC_FAILURE_DETAIL_MAX_CHARS} characters, which is the observed cause
+ * — the status, the field that disagreed, the error code. The detail is
+ * redacted with the same scrubber the health receipts use, because a caught
+ * error on this machine can carry an absolute path or a token-shaped fragment.
+ *
+ * Spool rows are local JSON, not database rows, so nothing migrates: a row
+ * written by an older CLI keeps its prose string and still parses and renders,
+ * it simply does not participate in the new buckets.
+ */
+import { describeError, redactedHealthDetail } from "./health-detail.js";
+export const SYNC_FAILURE_REASONS = [
+    /** The request never got an answer: DNS, TLS, a reset, an offline machine. */
+    "ingest_transport_error",
+    /** The ingest route answered and refused the envelope. */
+    "ingest_rejected",
+    /**
+     * Something answered 2xx, but not the ingest route's 202. A proxy, a captive
+     * portal, or a gateway that swallowed the real response.
+     */
+    "ingest_receipt_not_202",
+    /** A 202 from the route whose receipt does not match what was submitted. */
+    "ingest_receipt_incomplete",
+    /** The sync threw before or after delivery — filesystem, cursor, spool. */
+    "sync_failed_local",
+];
+export const SYNC_FAILURE_DETAIL_MAX_CHARS = 250;
+/**
+ * A delivery failure that already knows its own bucket.
+ *
+ * `message` is `reason: detail` so the existing consumers that only ever print
+ * `error.message` — `cockpit status`, the health-receipt classifier — keep
+ * working and get strictly more than they had.
+ */
+export class SyncDeliveryError extends Error {
+    reason;
+    detail;
+    httpStatus;
+    constructor(reason, options = {}) {
+        const detail = boundedFailureDetail(options.detail);
+        super(composeFailureReason(reason, detail), options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "SyncDeliveryError";
+        this.reason = reason;
+        this.detail = detail;
+        this.httpStatus = options.httpStatus ?? null;
+    }
+}
+/**
+ * Redacts, collapses and caps an observed cause.
+ *
+ * `redactedHealthDetail` is the boundary rule for anything that leaves this
+ * machine (secrets, absolute paths, the hostname, the account name); the cap
+ * here is tighter than the health receipt's because this string is also the
+ * spool row a person reads in one terminal line.
+ */
+export function boundedFailureDetail(value) {
+    if (!value)
+        return null;
+    const redacted = redactedHealthDetail(value);
+    if (!redacted)
+        return null;
+    return redacted.length > SYNC_FAILURE_DETAIL_MAX_CHARS
+        ? `${redacted.slice(0, SYNC_FAILURE_DETAIL_MAX_CHARS - 1)}…`
+        : redacted;
+}
+/** The single string the spool row stores: the bucket, then the cause. */
+export function composeFailureReason(reason, detail) {
+    return detail ? `${reason}: ${detail}` : reason;
+}
+/**
+ * Turns anything thrown inside a sync into a bucket plus a cause.
+ *
+ * A `SyncDeliveryError` already decided; everything else is local — a
+ * filesystem error writing the cursor, a spool write, a throw from an adapter —
+ * and is described by its error name, code and syscall rather than by its
+ * message, which is where the paths live.
+ */
+export function classifySyncFailure(error) {
+    if (error instanceof SyncDeliveryError) {
+        return {
+            reason: error.reason,
+            detail: error.detail,
+            failure_reason: composeFailureReason(error.reason, error.detail),
+            http_status: error.httpStatus,
+        };
+    }
+    const described = describeError(error);
+    const parts = [
+        described.error_name,
+        described.error_code,
+        described.error_syscall,
+        described.error_detail,
+        described.cause_code ?? described.cause_name,
+    ].filter((part) => Boolean(part));
+    const detail = boundedFailureDetail(parts.join(" "));
+    return {
+        reason: "sync_failed_local",
+        detail,
+        failure_reason: composeFailureReason("sync_failed_local", detail),
+        http_status: null,
+    };
+}

package/dist/upload-http.js

@@ -6,6 +6,7 @@
  * server sent back without letting a non-JSON body throw, and turn a normal
  * dashboard URL into one that can be concatenated with a path.
  */
+import { boundedFailureDetail } from "./upload-failure-reason.js";
 /**
  * Reads a reply body as JSON, and never throws doing it.
  *
@@ -34,6 +35,33 @@ export async function readResponseJson(response) {
         return { message: text };
     }
 }
+/**
+ * The server's own reason for refusing, as something safe to log.
+ *
+ * The dashboard's error envelopes answer `{ code, message, reason? }`. A
+ * `reason`/`code` that already looks like a label travels verbatim — that is
+ * the bucket the server chose, and reproducing it is how "storage rejected 116
+ * MB" reaches an operator instead of "upload failed" (BLI-2528). Anything else
+ * falls back to the message, redacted and capped, because a proxy's error page
+ * is unbounded and a route's message can carry a path.
+ *
+ * `null` means the body said nothing usable — which is itself worth logging as
+ * `"none"`, since "the server gave no reason" and "we never looked" are
+ * different facts.
+ */
+export function serverFailureDetail(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    for (const key of ["reason", "code"]) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && /^[a-z0-9_:.-]{1,80}$/iu.test(candidate)) {
+            return candidate;
+        }
+    }
+    const message = record["message"] ?? record["error"];
+    return typeof message === "string" ? boundedFailureDetail(message) : null;
+}
 /** The server's own words when it supplied any, otherwise our fallback. */
 export function responseErrorMessage(value, fallback) {
     if (value && typeof value === "object") {

package/dist/upload.js

@@ -7,7 +7,8 @@ import { buildLocalAmbientEnvelope, LocalUploadBlockedError, } from "./upload-en
 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";
+import { isNonEmptyString, readResponseJson, serverFailureDetail, } from "./upload-http.js";
+import { SyncDeliveryError, classifySyncFailure, } from "./upload-failure-reason.js";
 export { LocalUploadBlockedError, buildLocalAmbientEnvelope, } from "./upload-envelope.js";
 export { partitionHeldEvidenceFiles } from "./upload-evidence-delivery.js";
 export { reportAgentImageArtifacts } from "./upload-agent-artifacts.js";
@@ -99,6 +100,17 @@ export async function syncLocalAmbientEnvelope(options = {}) {
             uploadOutcomes,
             attemptedAt,
         });
+        // The success branch logs too. A line that only fires on failure cannot
+        // answer "did anything land at all today?", which is the question that
+        // would have caught BLI-2528 in a week instead of 57 days.
+        console.error("[cockpit-sync] ingest accepted the envelope", JSON.stringify({
+            reason: "ingest_accepted",
+            http_status: response.status,
+            event_count: built.event_count,
+            raw_evidence_file_count: built.raw_evidence_upload_files.length,
+            uploaded_chunk_count: uploadedChunkCount,
+            failed_object_count: uploadOutcomes.filter((outcome) => outcome.upload_state === "upload_failed").length,
+        }));
         return {
             status: "uploaded",
             dashboard_url: built.dashboard_url,
@@ -113,12 +125,26 @@ export async function syncLocalAmbientEnvelope(options = {}) {
         };
     }
     catch (error) {
-        const failureReason = error instanceof Error ? error.message : String(error);
+        // The spool row used to store `error.message` verbatim, so every distinct
+        // server sentence became its own "reason" and nothing could count how many
+        // machines were failing the same way (BLI-3483). It now stores a label from
+        // a closed set plus a bounded, redacted cause.
+        const classified = classifySyncFailure(error);
         // A committed content-addressed object may be shared by concurrent syncs.
         // Never delete it from this error path: an ingest retry can reuse it, while
         // client-side cleanup cannot prove exclusive ownership without racing a
         // second sync that is about to index the same object.
-        const spooledFailureReason = failureReason;
+        const spooledFailureReason = classified.failure_reason;
+        console.error("[cockpit-sync] sync spooled for retry", JSON.stringify({
+            reason: classified.reason,
+            ...(classified.http_status === null
+                ? {}
+                : { http_status: classified.http_status }),
+            ...(classified.detail ? { detail: classified.detail } : {}),
+            event_count: built.event_count,
+            raw_evidence_file_count: built.raw_evidence_upload_files.length,
+            uploaded_chunk_count: uploadedChunkCount,
+        }));
         const entry = await recordUploadFailure(paths, {
             last_attempt_at: attemptedAt,
             dashboard_url: built.dashboard_url,
@@ -182,17 +208,50 @@ async function buildEnvelopeOrRecordBlocker(paths, options, cursorObjects, attem
  * row counts, which is what the receipt check demands.
  */
 async function postEnvelopeToIngest(options) {
-    const response = await options.fetchImpl(`${options.built.dashboard_url}/api/ambient/ingest`, {
-        method: "POST",
-        headers: {
-            "Authorization": `Bearer ${options.built.device_token}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify(options.envelope),
-    });
+    let response;
+    try {
+        response = await options.fetchImpl(`${options.built.dashboard_url}/api/ambient/ingest`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${options.built.device_token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(options.envelope),
+        });
+    }
+    catch (error) {
+        // No status came back at all, so no server-side reason exists to read. The
+        // error's own name and code (`TypeError` / `ENOTFOUND` / `ECONNREFUSED`)
+        // are the whole answer, and they are what separates "this machine is
+        // offline" from "the dashboard refused us" — two words that used to be the
+        // same spool row.
+        const described = describeError(error);
+        console.error("[cockpit-sync] ingest request failed before a status came back", JSON.stringify({ reason: "ingest_transport_error", ...described }));
+        throw new SyncDeliveryError("ingest_transport_error", {
+            detail: [
+                described.error_name,
+                described.error_code,
+                described.cause_code ?? described.cause_name,
+                described.error_detail,
+            ]
+                .filter(Boolean)
+                .join(" "),
+            cause: error,
+        });
+    }
     const responseBody = await readResponseJson(response);
     if (!response.ok) {
-        throw new Error(responseErrorMessage(responseBody, `Ambient ingest failed with HTTP ${response.status}`));
+        const serverReason = serverFailureDetail(responseBody);
+        console.error("[cockpit-sync] ingest refused the envelope", JSON.stringify({
+            reason: "ingest_rejected",
+            http_status: response.status,
+            server_reason: serverReason ?? "none",
+            event_count: options.envelope.events.length,
+        }));
+        throw new SyncDeliveryError("ingest_rejected", {
+            httpStatus: response.status,
+            detail: `http ${response.status}; server reason ${serverReason ?? "none"}`,
+        });
     }
     assertAmbientIngestReceipt(response, responseBody, options.envelope);
     return response;
@@ -275,11 +334,26 @@ async function recordIngestedSyncOutcome(options) {
  *
  * Anything short of a 202 whose counts match the envelope's own totals is
  * treated as no receipt at all — a proxy's 200, a truncated body, or a
- * dashboard that accepted fewer rows than were sent all land here.
+ * dashboard that accepted fewer rows than were sent all land here. They used to
+ * land here under the SAME sentence, which is the BLI-3483 complaint: a
+ * network appliance answering on the dashboard's behalf and a dashboard that
+ * genuinely persisted three of four rows are opposite repairs. They are now two
+ * reasons, and the second one names the field that disagreed and by how much.
  */
 function assertAmbientIngestReceipt(response, value, envelope) {
     if (response.status !== 202 || !value || typeof value !== "object") {
-        throw new Error("Ambient ingest returned an invalid durable receipt.");
+        const detail = response.status !== 202
+            ? `http ${response.status}; the ingest route answers 202, so something in front of it replied`
+            : "202 with a body that is not an object";
+        console.error("[cockpit-sync] ingest answered without a durable receipt", JSON.stringify({
+            reason: "ingest_receipt_not_202",
+            http_status: response.status,
+            body_is_object: Boolean(value) && typeof value === "object",
+        }));
+        throw new SyncDeliveryError("ingest_receipt_not_202", {
+            httpStatus: response.status,
+            detail,
+        });
     }
     const record = value;
     const ingest = record["ingest"] && typeof record["ingest"] === "object"
@@ -288,12 +362,39 @@ function assertAmbientIngestReceipt(response, value, envelope) {
     const expectedFactCount = envelope.events.length;
     const expectedRiskFlagCount = envelope.events.reduce((total, event) => total + event.risk_flags.length, 0);
     const expectedEvidenceRefCount = envelope.events.reduce((total, event) => total + event.raw_evidence_pointers.length, 0);
-    if (record["ok"] !== true ||
-        !ingest ||
-        !isNonEmptyString(ingest["work_session_id"]) ||
-        ingest["fact_count"] !== expectedFactCount ||
-        ingest["risk_flag_count"] !== expectedRiskFlagCount ||
-        ingest["evidence_ref_count"] !== expectedEvidenceRefCount) {
-        throw new Error("Ambient ingest returned an incomplete durable receipt.");
+    const mismatches = [];
+    if (record["ok"] !== true)
+        mismatches.push("ok not true");
+    if (!ingest)
+        mismatches.push("no ingest block");
+    if (ingest && !isNonEmptyString(ingest["work_session_id"])) {
+        mismatches.push("blank work_session_id");
+    }
+    if (ingest) {
+        mismatches.push(...countMismatch("fact_count", ingest["fact_count"], expectedFactCount), ...countMismatch("risk_flag_count", ingest["risk_flag_count"], expectedRiskFlagCount), ...countMismatch("evidence_ref_count", ingest["evidence_ref_count"], expectedEvidenceRefCount));
     }
+    if (mismatches.length === 0)
+        return;
+    console.error("[cockpit-sync] ingest receipt does not match what was submitted", JSON.stringify({
+        reason: "ingest_receipt_incomplete",
+        http_status: response.status,
+        mismatch_count: mismatches.length,
+        mismatches,
+    }));
+    throw new SyncDeliveryError("ingest_receipt_incomplete", {
+        httpStatus: response.status,
+        detail: mismatches.join("; "),
+    });
+}
+/**
+ * `submitted 4, receipt 3` — the sentence that tells partial persistence from a
+ * receipt that never carried the field at all. Counts are numbers this
+ * collector computed and numbers the server echoed; neither is content.
+ */
+function countMismatch(field, received, expected) {
+    if (received === expected)
+        return [];
+    return [
+        `${field} submitted ${expected}, receipt ${typeof received === "number" ? received : "absent"}`,
+    ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "private": false,
   "type": "module",
   "bin": {