@bli-cockpit/cli 0.2.95 → 0.2.97

package/dist/commands/heartbeat-token.js

@@ -0,0 +1,80 @@
+import { describeError } from "../health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, recordDeviceTokenExpiry, toSessionReference, } from "../local-state.js";
+/**
+ * Read the session and decide whether this tick may check in.
+ *
+ * The check-in goes out while the machine believes it is EXPIRED, as long as it
+ * still holds a device token. That is not a loosening: the SERVER decides
+ * whether a token is accepted, and a collector that refused to knock could
+ * never be let back in. Uploads are unaffected — they still gate on `valid`
+ * (`upload-envelope-build.ts`), so a machine past the grace window spends no
+ * bandwidth on evidence that will be refused.
+ *
+ * Both refusing branches say something, because "the dashboard shows this
+ * machine as quiet" has two very different causes.
+ */
+export async function readHeartbeatSession(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    const state = session ? toSessionReference(session).session_state : "missing";
+    const usable = state === "valid" || state === "expired";
+    if (!session ||
+        !usable ||
+        typeof session.device_token !== "string" ||
+        !session.device_token) {
+        console.error("[heartbeat] no usable device session on this machine; the dashboard will show it as quiet", JSON.stringify({
+            reason: "no_device_session",
+            session_state: state,
+            next_action: "run `cockpit do-everything` to pair this machine again",
+        }));
+        return { usable: false };
+    }
+    if (state === "expired") {
+        console.error("[heartbeat] this machine's session looks expired; checking in anyway so the dashboard can renew it", JSON.stringify({
+            reason: "session_expired_locally",
+            expires_at: session.expires_at ?? null,
+            next_action: "the dashboard renews a token that lapsed inside its 30-day grace window on this call",
+        }));
+    }
+    return { usable: true, session, state: state };
+}
+/**
+ * Record the `token_expires_at` the heartbeat door answered with.
+ *
+ * The LOCAL copy is what decides whether this machine even attempts an upload,
+ * so a machine the server has just renewed would otherwise go on refusing its
+ * own uploads until somebody signed in by hand.
+ *
+ * A body that is not JSON, or that carries no such field, is not an error and
+ * is not logged: an older dashboard answers `{ ok: true }` and a proxy can
+ * answer anything. It simply means "this reply said nothing about the expiry",
+ * and the machine keeps the date it already holds. Best-effort throughout — a
+ * heartbeat never fails a sync.
+ */
+export async function recordHeartbeatTokenExpiry(homeDir, response) {
+    const expiresAt = await readTokenExpiry(response);
+    if (!expiresAt)
+        return;
+    await recordDeviceTokenExpiry({
+        paths: getCollectorRuntimePaths(homeDir),
+        expiresAt,
+    }).catch((error) => {
+        console.error("[heartbeat] the token expiry the dashboard reported was not recorded", JSON.stringify({
+            reason: "token_expiry_writeback_threw",
+            ...describeError(error),
+        }));
+        return null;
+    });
+}
+async function readTokenExpiry(response) {
+    try {
+        const body = (await response.json());
+        if (!body || typeof body !== "object")
+            return null;
+        const value = body["token_expires_at"];
+        return typeof value === "string" && value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/heartbeat.js

@@ -28,7 +28,9 @@ import { readCachedSetupReceipt } from "./setup-receipt.js";
 import { readStagingInventory } from "../disk-usage.js";
 import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
-import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { readHeartbeatSession, recordHeartbeatTokenExpiry, } from "./heartbeat-token.js";
+import { classifySyncHealthError } from "../sync-health-class.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 import { readMemoryHookCounts } from "./memory-hook-counts.js";
 import { readMemoryHookPerformance } from "./memory-hook-performance.js";
@@ -232,18 +234,14 @@ export async function sendCollectorHeartbeatBestEffort(options) {
         }));
         return false;
     }
-    const paths = getCollectorRuntimePaths(options.homeDir);
-    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
-    if (!session ||
-        session.session_state !== "valid" ||
-        typeof session.device_token !== "string" ||
-        !session.device_token) {
-        console.error("[heartbeat] no valid device session on this machine; the dashboard will show it as quiet", JSON.stringify({
-            reason: "no_device_session",
-            next_action: "run `cockpit do-everything` to pair this machine again",
-        }));
+    // BLI-4019. Whether this machine may knock at all, and the two log lines
+    // that go with it, live in `heartbeat-token.ts` — the check-in goes out even
+    // when the local copy says `expired`, because that is the door the server
+    // renews a lapsed token through.
+    const reading = await readHeartbeatSession(options.homeDir);
+    if (!reading.usable)
         return false;
-    }
+    const { session } = reading;
     const memory = await readHeartbeatMemoryReceipt({
         ...(options.homeDir ? { homeDir: options.homeDir } : {}),
         ...(options.now ? { now: options.now } : {}),
@@ -287,13 +285,27 @@ export async function sendCollectorHeartbeatBestEffort(options) {
         });
         if (!response.ok) {
             // A heartbeat is not retried, so the reason has to be said once, here.
+            // BLI-4019: the CLASS comes from `sync-health-class.ts`, the one place
+            // that decides what a failure is — a 401/403 is `auth_failed` and
+            // anything else is not, read off the observed status and never off the
+            // words in a message (BLI-3551's rule).
             console.error("[heartbeat] the dashboard refused this tick's heartbeat", JSON.stringify({
                 reason: "heartbeat_rejected",
+                health_class: classifySyncHealthError({ httpStatus: response.status }),
                 http_status: response.status,
                 root_count: heartbeat.roots.length,
+                ...(response.status === 401 || response.status === 403
+                    ? {
+                        next_action: "past the 30-day grace window this needs `cockpit login` on this machine",
+                    }
+                    : {}),
             }));
             return false;
         }
+        // BLI-4019. The server slides `token_expires_at` out on every call it
+        // authenticates and answers with the result; the sibling records it, so
+        // this machine's own copy follows the server rather than drifting.
+        await recordHeartbeatTokenExpiry(options.homeDir, response);
         console.error("[heartbeat] checked in", JSON.stringify({
             reason: "heartbeat_recorded",
             http_status: response.status,

package/dist/commands/public-root.js

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

package/dist/commands/session-sync-failures.js

@@ -13,6 +13,7 @@
  * without saying why.
  */
 import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
+import { isDeliveryHoldReason } from "./session-sync-hold.js";
 import { sourceScanFailureReason } from "./session-sync-scan.js";
 /**
  * The label used when a sync fails and nothing on the way there said why.
@@ -45,6 +46,15 @@ export function createSyncFailureLedger() {
  * The spooled reason is the most specific thing anyone has, so it leads, and it
  * names the worktree it belongs to — a fleet failure is usually one repo, and
  * "which one" is the first question asked.
+ *
+ * BLI-4022: `delivery_backoff_holding` is the one raw-evidence reason that does
+ * NOT come in here. An object inside its own retry window was withheld on
+ * purpose and will be offered again; filing that as a failed tick is what
+ * painted Ian's Mac mini red on eight consecutive ticks while every session it
+ * collected landed. The hold is still reported — it becomes the tick's named
+ * hold in `session-sync-hold.ts` and rides the same receipt — and a tick that
+ * ALSO failed for a real reason still fails on that reason. Nothing is
+ * silenced; only the verdict changed.
  */
 export function recordWorktreeDeliveryFailures(ledger, outcomes) {
     for (const { worktree, sync } of outcomes) {
@@ -61,12 +71,16 @@ export function recordWorktreeDeliveryFailures(ledger, outcomes) {
                 });
         }
         for (const reason of sync.raw_evidence_failure_reasons ?? []) {
+            if (isDeliveryHoldReason(reason))
+                continue;
             ledger.add({
                 label: "raw_evidence_upload_failed",
                 rendered: `raw_evidence:${reason}`,
             });
         }
         for (const reason of sync.raw_evidence_retry_reasons ?? []) {
+            if (isDeliveryHoldReason(reason))
+                continue;
             ledger.add({
                 label: "raw_evidence_retry_required",
                 rendered: `raw_evidence_retry:${reason}`,

package/dist/commands/session-sync-health.js

@@ -11,6 +11,7 @@
  */
 import { createSyncFailureLedger, recordSourceScanFailures, recordUnexplainedFailure, recordUnpostedSessionReportFailure, recordWorktreeDeliveryFailures, } from "./session-sync-failures.js";
 import { countSessionsNewThisTick, countSessionsPendingUpload, } from "./session-sync-counters.js";
+import { logDeliveryHold, summarizeDeliveryHold } from "./session-sync-hold.js";
 /**
  * Decide whether this tick failed, and record every condition that decided it.
  *
@@ -44,12 +45,20 @@ export function decideSyncHealth(options) {
     if (nothingInRoot !== null && notice) {
         announceNothingInRoot(nothingInRoot, options.collectionRootCount);
     }
+    // BLI-4022. Computed after `ok`, and never allowed to change it: a hold is
+    // what this tick withheld on purpose, not a verdict on the run. It rides an
+    // `ok` receipt as the tick's reason and a failing one beside the reasons that
+    // failed it, so the board can say what is waiting in either case.
+    const hold = summarizeDeliveryHold(outcomes);
+    if (hold && ok)
+        logDeliveryHold(hold);
     const records = ledger.sortedRecords();
     return {
         ok,
         failure_reasons: records.map((record) => record.rendered),
         failure_records: records,
         notice,
+        hold,
         sessions_outside_root: sessionsOutsideRoot,
         sessions_new_this_tick: countSessionsNewThisTick({
             sessions: options.sessions,

package/dist/commands/session-sync-hold.js

@@ -0,0 +1,90 @@
+/**
+ * What this tick is HOLDING, as opposed to what it got wrong (BLI-4022).
+ *
+ * The sibling `session-sync-failures.ts` is the one place a sync writes down
+ * that it FAILED. This is the one place it writes down that it deliberately
+ * withheld something and when it will try again — a different question with a
+ * different answer, kept in a different file so neither can quietly become the
+ * other.
+ *
+ * Deliberately writes no failure label of any kind: `sync-health-class.test.ts`
+ * reads every `session-sync*.ts` sibling and demands that only the failure
+ * ledger writes one, and this file is not it.
+ */
+import { formatDeliveryHoldNotice, } from "../delivery-hold-notice.js";
+import { DELIVERY_BACKOFF_HOLDING_REASON } from "../raw-evidence-staging.js";
+/**
+ * Is this reason a delivery hold rather than a delivery failure?
+ *
+ * Exact match against the label telemetry-core owns — the same discipline the
+ * failure classifier follows. A reason that merely CONTAINS the word "backoff"
+ * is not evidence of anything (BLI-3551's lesson, applied to the other side of
+ * the same fence).
+ */
+export function isDeliveryHoldReason(reason) {
+    return reason === DELIVERY_BACKOFF_HOLDING_REASON;
+}
+/**
+ * Fold every worktree's held objects into one hold for the tick, or null.
+ *
+ * The count is summed because a tick can sync several worktrees and each one
+ * reports its own held objects. The AGE takes the oldest across all of them and
+ * the NEXT ATTEMPT the earliest, because both are promises about the whole
+ * machine: the operator asks "how long has anything been stuck" and "when does
+ * anything move", not "which worktree".
+ *
+ * Returns null when nothing is held, so no caller can announce a hold of
+ * nothing — a status line that appears on every tick is one people stop
+ * reading.
+ */
+export function summarizeDeliveryHold(outcomes) {
+    let objectCount = 0;
+    let oldestFirstFailedAt = null;
+    let nextAttemptAt = null;
+    let lastReason = null;
+    for (const { sync } of outcomes) {
+        const held = sync.raw_evidence_delivery_held_count ?? 0;
+        if (held <= 0)
+            continue;
+        objectCount += held;
+        const first = sync.raw_evidence_held_oldest_failure_at ?? null;
+        if (first && (!oldestFirstFailedAt || first < oldestFirstFailedAt)) {
+            oldestFirstFailedAt = first;
+            // The reason travels WITH the object it belongs to. A reason taken from
+            // one worktree and an age from another would describe no object at all.
+            lastReason = sync.raw_evidence_held_last_reason ?? null;
+        }
+        const next = sync.raw_evidence_held_next_attempt_at ?? null;
+        if (next && (!nextAttemptAt || next < nextAttemptAt))
+            nextAttemptAt = next;
+    }
+    if (objectCount <= 0)
+        return null;
+    const notice = formatDeliveryHoldNotice({
+        objectCount,
+        oldestFirstFailedAt,
+        nextAttemptAt,
+        lastReason,
+    });
+    if (!notice)
+        return null;
+    return { objectCount, oldestFirstFailedAt, nextAttemptAt, lastReason, notice };
+}
+/**
+ * Say out loud, once per tick, that bytes are being withheld on purpose.
+ *
+ * `logEvidenceHeldByBackoff` already names the objects at the moment they are
+ * partitioned off the wire; this is the RUN's line, so the tick that reports
+ * itself as held also explains itself on stderr where launchd captures it.
+ * Counts, instants and reason labels only.
+ */
+export function logDeliveryHold(hold) {
+    console.error("[session-sync] raw evidence held by delivery backoff, nothing else failed", JSON.stringify({
+        reason: hold.notice,
+        object_count: hold.objectCount,
+        oldest_first_failed_at: hold.oldestFirstFailedAt,
+        next_attempt_at: hold.nextAttemptAt,
+        last_reason: hold.lastReason,
+        next_action: "nothing until the next attempt is due; run `cockpit doctor` if it is already past",
+    }));
+}

package/dist/commands/session-sync.js

@@ -25,6 +25,9 @@
  *   class-lock test reads that file (BLI-3551).
  * - `session-sync-health.ts` — the verdict, and the notice a quiet-but-working
  *   machine still emits.
+ * - `session-sync-hold.ts` — what the tick withheld ON PURPOSE and when it will
+ *   try again (BLI-4022), which is a different question from what it got wrong
+ *   and so lives in a different file from the failure ledger.
  * - `session-sync-counters.ts` — the two honest heartbeat counters beside the
  *   raw scan count: sessions new since the last tick's cursor, and sessions
  *   still pending a durable pointer (BLI-3645).
@@ -49,6 +52,7 @@ export { isLiveSyncCollectableAttributionState, liveSyncCursorEntryRequiresRetry
 export { sourceScanFailureReason, sourceScanRetryReason, } from "./session-sync-scan.js";
 export { SYNC_FAILED_WITHOUT_REASON } from "./session-sync-failures.js";
 export { nothingInRootCount } from "./session-sync-health.js";
+export { isDeliveryHoldReason, summarizeDeliveryHold, } from "./session-sync-hold.js";
 /**
  * Shared dual-source sync orchestration for single-repo and parent-folder
  * modes. Codex AND Claude Code sessions are scanned and attributed once across
@@ -126,6 +130,7 @@ export async function runAttributedWorktreeSync(options) {
         failure_reasons: health.failure_reasons,
         failure_records: health.failure_records,
         notice: health.notice,
+        hold: health.hold,
         sessions_observed: sessions.length,
         sessions_outside_root: health.sessions_outside_root,
         sessions_new_this_tick: health.sessions_new_this_tick,

package/dist/commands/setup-receipt-lines.js

@@ -21,6 +21,20 @@ const FIXES = {
     "codex.hooks": "Run `cockpit memory install`.",
     "collector.autostart": "Run `cockpit autostart install`.",
 };
+/**
+ * A fix keyed on the piece's REASON rather than the piece, for the cases where
+ * the same gap has two different next actions (BLI-4019).
+ *
+ * `device` says "run `cockpit login`" for every lapse, and for an expired
+ * session that is now the wrong instruction most of the time: the dashboard
+ * slides a device token's expiry out on every call it authenticates and renews
+ * one that lapsed inside a 30-day grace window, so the ordinary answer is to do
+ * nothing and let the next tick fix it. Telling somebody to sign in again on a
+ * machine that is about to heal itself is how a receipt stops being believed.
+ */
+const REASON_FIXES = {
+    session_expired: "Renews on the next sync tick while inside the 30-day grace window; past it, run `cockpit login`.",
+};
 /** Codex hooks a person switched OFF is a decision, not a fault. */
 const UNSUPPORTED_FIX = "Switched off in your own config; nothing to do.";
 /**
@@ -64,6 +78,9 @@ function fixFor(key, piece) {
     if (piece.status === "skipped") {
         return "Skipped on purpose; nothing to do.";
     }
+    // The reason wins over the piece when it has its own next action.
+    if (piece.reason && REASON_FIXES[piece.reason])
+        return REASON_FIXES[piece.reason];
     return FIXES[key] ?? "Run `cockpit doctor`.";
 }
 function reasonSuffix(piece) {

package/dist/commands/sync-receipt.js

@@ -91,16 +91,25 @@ function standAsideForRunningSync(command, io, heldSince) {
  * is the receipt that separates "this machine is alive and its operator
  * works outside the approved roots" from "this machine is dead", which
  * until now looked identical from the dashboard.
+ *
+ * BLI-4022 added the second thing an `ok` tick can say: `held_backoff:…`, the
+ * objects this tick withheld on purpose and when they may be offered again.
+ * The two can never collide — `nothing_in_root` requires that NO worktree
+ * synced at all (`nothingInRootCount`), and a hold requires a worktree that
+ * did — so one field carries whichever is true, and the notice wins if that
+ * ever stops being the case, because "there was nothing to collect" is the
+ * larger fact about the tick.
  */
-function collectedReceipt(run) {
+export function collectedReceipt(run) {
+    const reason = run.notice ?? run.holdNotice;
     return {
         exitCode: run.exitCode,
         completion: {
             step: "sync_complete",
             status: "ok",
-            ...(run.notice ? { error_detail: run.notice } : {}),
+            ...(reason ? { error_detail: reason } : {}),
         },
-        heartbeat: { status: "ok", reason: run.notice, ...heartbeatCounts(run) },
+        heartbeat: { status: "ok", reason, ...heartbeatCounts(run) },
     };
 }
 /**
@@ -111,8 +120,14 @@ function collectedReceipt(run) {
  * failure rows carried a null detail and the real reason was reachable only
  * by running `cockpit status` on the machine itself (BLI-2526).
  */
-function failedReceipt(run) {
-    const reasonText = run.failureReasons.join("; ");
+export function failedReceipt(run) {
+    // BLI-4022: the hold leads on a failing tick. `error_detail` is bounded, and
+    // an operator reading a red row still has to be able to see what is merely
+    // waiting — otherwise the held objects become invisible the moment anything
+    // else goes wrong, which is the opposite of the fix.
+    const reasonText = [run.holdNotice, ...run.failureReasons]
+        .filter(Boolean)
+        .join("; ");
     // The bucket comes from the records the deciding branches wrote, not from
     // this sentence (BLI-3551). The sentence is still the detail.
     const errorCode = classifySyncFailureRecords(run.failureRecords);

package/dist/commands/sync-report.js

@@ -141,6 +141,9 @@ function syncResult(run) {
         failureReasons: run.ok ? [] : run.failure_reasons,
         failureRecords: run.ok ? [] : run.failure_records,
         notice: run.notice,
+        // BLI-4022: unlike the reasons, the hold survives a successful run — it is
+        // what the tick withheld, not why it failed.
+        holdNotice: run.hold?.notice ?? null,
         sessionsObserved: run.sessions_observed,
         sessionsOutsideRoot: run.sessions_outside_root,
         sessionsNewThisTick: run.sessions_new_this_tick,

package/dist/delivery-hold-notice.js

@@ -0,0 +1,166 @@
+/**
+ * A HOLD is not a FAILURE — and this file is the one place that spells it.
+ *
+ * BLI-4022. `delivery_backoff_holding` means "this object is inside its own
+ * retry window, so this tick did not offer it". Until now that reason went
+ * into the sync's failure ledger like any other, so a machine collecting
+ * perfectly reported `sync_failed` on every tick for as long as the backoff
+ * held: Ian's Mac mini was RED on eight consecutive ticks from
+ * 2026-09-09T00:11Z with the detail
+ * `raw_evidence_retry:delivery_backoff_holding; raw_evidence:delivery_backoff_holding`
+ * while its sessions kept landing and its heartbeat kept moving.
+ *
+ * The honesty is unchanged. A held object IS missing collection and must never
+ * read as clean (that is the rule BLI-3066 bought). What changes is the
+ * OUTCOME: a tick whose only raw-evidence complaint is held objects reports a
+ * named hold instead of a failure, and the hold carries everything an operator
+ * needs to decide whether to care — how many objects, how long the oldest has
+ * been failing, when the next attempt is due, and the object's own last reason.
+ *
+ * ## The grammar
+ *
+ * One token, because it has to survive two narrow channels: the heartbeat's
+ * `last_sync_reason` (`^[a-z0-9_:.-]+$`, 120 chars, no spaces) and the receipt's
+ * `error_detail`. Fields are positional and colon-separated:
+ *
+ *     held_backoff:<count>:<oldest_first_failed_at>:<next_attempt_at>:<last_reason>
+ *     held_backoff:3:2026-08-14T17:38Z:2026-09-09T06:11Z:chunk_10_failed_http_500
+ *
+ * Timestamps are minute precision UTC; `-` stands for a field this machine
+ * could not fill. The last reason is bounded so the whole token fits the
+ * heartbeat's 120 characters — the count and the ages are what a colour is
+ * decided from, so the reason is the field that gives way.
+ *
+ * The collector WRITES the token and the dashboard's fleet board READS it
+ * (`lib/ops/fleet-liveness-device-verdict.ts`, through this package's
+ * `./delivery-hold` export). One grammar, one file: a second copy of this
+ * string is exactly how the collector's word and the server's word drift
+ * apart, which is why `DELIVERY_BACKOFF_HOLDING` itself is aliased from
+ * telemetry-core rather than spelled twice.
+ */
+/** The token's leading word. Greppable in a receipt, a log line or a DM. */
+export const DELIVERY_HOLD_NOTICE_PREFIX = "held_backoff";
+/** The heartbeat's own ceiling for `last_sync_reason`. The token fits inside it. */
+export const DELIVERY_HOLD_NOTICE_MAX_CHARS = 120;
+/**
+ * How long a hold may last before it stops being a wait and becomes a stuck
+ * object.
+ *
+ * The backoff schedule doubles from the scheduler's own 15-minute cadence to a
+ * six-hour ceiling (`EVIDENCE_DELIVERY_BACKOFF_MAX_MS`), so an object held
+ * longer than this has already been offered at least four more times at the
+ * ceiling and been refused every time. Nothing is going to change on its own,
+ * and "next retry at T — nothing to do until then" would be a promise the
+ * machine cannot keep. 24 hours is also the board's own `SILENT_AFTER_HOURS`,
+ * so both clocks agree on when a quiet thing stops being a blip.
+ */
+export const DELIVERY_HOLD_STALE_AFTER_HOURS = 24;
+/** The most characters of an object's own reason label the token may carry. */
+const MAX_HOLD_REASON_CHARS = 64;
+/** A field this machine could not fill. Never omitted — the shape is positional. */
+const ABSENT = "-";
+/**
+ * Render the hold as the single token the heartbeat and the receipt carry.
+ *
+ * Returns null for a hold of nothing, so a caller cannot accidentally announce
+ * a hold that is not happening.
+ */
+export function formatDeliveryHoldNotice(notice) {
+    if (notice.objectCount <= 0)
+        return null;
+    const head = [
+        DELIVERY_HOLD_NOTICE_PREFIX,
+        String(Math.trunc(notice.objectCount)),
+        minuteStamp(notice.oldestFirstFailedAt),
+        minuteStamp(notice.nextAttemptAt),
+    ].join(":");
+    const budget = Math.min(MAX_HOLD_REASON_CHARS, DELIVERY_HOLD_NOTICE_MAX_CHARS - head.length - 1);
+    return `${head}:${reasonWord(notice.lastReason, budget)}`;
+}
+/**
+ * Find a hold token inside anything a receipt carries, and read it back.
+ *
+ * Deliberately a SEARCH, not a whole-string match: on a tick that also failed
+ * for a real reason the token rides beside those reasons in the same
+ * `error_detail`, and the board must still be able to say what is held.
+ */
+export function parseDeliveryHoldNotice(text) {
+    if (!text)
+        return null;
+    // The stamp shape is pinned rather than described by a character class: a
+    // class containing `:` is greedy across the field separator, and a parser
+    // that swallowed one field into the next reported an age of twenty-five
+    // years and a next attempt in 2001.
+    const stamp = String.raw `(?:-|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z)`;
+    const match = new RegExp(`${DELIVERY_HOLD_NOTICE_PREFIX}:(\\d+):(${stamp}):(${stamp}):([a-z0-9_-]+)`, "iu").exec(text);
+    if (!match)
+        return null;
+    const objectCount = Number.parseInt(match[1], 10);
+    if (!Number.isFinite(objectCount) || objectCount <= 0)
+        return null;
+    return {
+        objectCount,
+        oldestFirstFailedAt: readStamp(match[2]),
+        nextAttemptAt: readStamp(match[3]),
+        lastReason: match[4] === ABSENT ? null : match[4],
+    };
+}
+/**
+ * How long the longest-held object has been failing, in hours.
+ *
+ * Null when the token carried no first-failure instant, which is a different
+ * fact from "zero hours" — an unknown age is never treated as a fresh hold.
+ */
+export function deliveryHoldAgeHours(notice, nowIso) {
+    if (!notice.oldestFirstFailedAt)
+        return null;
+    const from = Date.parse(notice.oldestFirstFailedAt);
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(from) || !Number.isFinite(now))
+        return null;
+    return (now - from) / 3_600_000;
+}
+/**
+ * Has this hold stopped being a wait?
+ *
+ * An age this reader could not compute counts as stale on purpose: the whole
+ * point of the amber sentence is the promise "next retry at T", and a hold
+ * whose age is unknown is one nobody can make that promise about.
+ */
+export function isDeliveryHoldStale(notice, nowIso) {
+    const hours = deliveryHoldAgeHours(notice, nowIso);
+    if (hours === null)
+        return true;
+    return hours > DELIVERY_HOLD_STALE_AFTER_HOURS;
+}
+/** `2026-09-09T06:11Z`, or `-` for an instant this machine does not have. */
+function minuteStamp(iso) {
+    if (!iso)
+        return ABSENT;
+    const parsed = Date.parse(iso);
+    if (!Number.isFinite(parsed))
+        return ABSENT;
+    return `${new Date(parsed).toISOString().slice(0, 16)}Z`;
+}
+/** The inverse: a token field back to an ISO instant, or null when absent. */
+function readStamp(field) {
+    if (field === ABSENT)
+        return null;
+    const parsed = Date.parse(field);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+/**
+ * A reason label narrowed to what the token's charset and budget allow.
+ *
+ * Truncation is marked by dropping characters, never by an ellipsis: the
+ * heartbeat's charset has no `…`, and a token the door rejects tells nobody
+ * anything at all.
+ */
+function reasonWord(reason, budget) {
+    if (!reason || budget <= 0)
+        return ABSENT;
+    const safe = reason.replace(/[^a-z0-9_]/giu, "_").replace(/^_+|_+$/gu, "");
+    if (safe.length === 0)
+        return ABSENT;
+    return safe.slice(0, budget);
+}

package/dist/local-state-pairing.js

@@ -7,7 +7,7 @@ import { serverFailureDetail } from "./upload-http.js";
 import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
 import { isMissingFileError, writeJsonFile } from "./local-state-files.js";
 import { defaultDeviceName, LOCAL_COLLECTOR_VERSION, normalizeDashboardUrl, normalizeDeviceName, normalizeOptionalEmail, readLocalCollectorConfig, } from "./local-state-config.js";
-import { toSessionReference } from "./local-state-session.js";
+import { readLocalCollectorSessionFile, toSessionReference, } from "./local-state-session.js";
 /**
  * `cockpit login` — the whole device-pairing handshake, because a machine can
  * collect locally without it but can never upload until the dashboard has
@@ -106,6 +106,46 @@ export async function logoutLocalCollector(options = {}) {
     }
     return { removed, session_file: paths.session_file };
 }
+export async function recordDeviceTokenExpiry(options) {
+    const parsed = Date.parse(options.expiresAt);
+    if (!Number.isFinite(parsed)) {
+        console.error("[local-state] the dashboard's token expiry was not a date; this machine keeps the one it has", JSON.stringify({ reason: "token_expiry_unreadable" }));
+        return { status: "skipped", reason: "token_expiry_unreadable" };
+    }
+    let session;
+    try {
+        session = await readLocalCollectorSessionFile(options.paths);
+    }
+    catch (error) {
+        console.error("[local-state] no readable session file to record the token expiry on", JSON.stringify({
+            reason: "session_file_unreadable",
+            ...describeError(error),
+        }));
+        return { status: "skipped", reason: "session_file_unreadable" };
+    }
+    if (session.expires_at === options.expiresAt) {
+        return { status: "unchanged", expires_at: options.expiresAt };
+    }
+    try {
+        await writeJsonFile(options.paths.session_file, {
+            ...session,
+            expires_at: options.expiresAt,
+        });
+    }
+    catch (error) {
+        console.error("[local-state] the renewed token expiry could not be written; this machine still believes the old one", JSON.stringify({
+            reason: "session_file_write_failed",
+            ...describeError(error),
+        }));
+        return { status: "skipped", reason: "session_file_write_failed" };
+    }
+    console.error("[local-state] recorded the token expiry the dashboard reported", JSON.stringify({
+        reason: "token_expiry_recorded",
+        previous_expires_at: session.expires_at ?? null,
+        expires_at: options.expiresAt,
+    }));
+    return { status: "written", expires_at: options.expiresAt };
+}
 async function postPairStart(fetchImpl, dashboardUrl, body, accessToken) {
     const response = await fetchImpl(`${dashboardUrl}/api/ambient/pair/start`, {
         method: "POST",

package/dist/local-state.js

@@ -37,8 +37,8 @@
  */
 export { getCollectorRuntimePaths } from "./local-state-paths.js";
 export { DEFAULT_DASHBOARD_URL, ensureLocalCollectorConfig, installLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
-export { readLocalCollectorSessionFile, readLocalSessionReference, } from "./local-state-session.js";
-export { logoutLocalCollector, pairLocalCollector, } from "./local-state-pairing.js";
+export { readLocalCollectorSessionFile, readLocalSessionReference, toSessionReference, } from "./local-state-session.js";
+export { logoutLocalCollector, pairLocalCollector, recordDeviceTokenExpiry, } from "./local-state-pairing.js";
 export { PairingCodeError, pairLocalCollectorViaLink, } from "./local-state-pairing-code.js";
 export { resolveGitBranch } from "./local-state-identity.js";
 export { readLocalWorkContext, readLocalWorkContextForRepo, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "./local-state-work-context.js";

package/dist/raw-evidence-staging.js

@@ -25,6 +25,10 @@ import { describeError, isMissingFileFailure } from "./health-detail.js";
  * Metadata only: content hashes, byte sizes, pack ids, pack-relative paths,
  * reason labels, timestamps. Never content, never an absolute path.
  */
+// BLI-4022. The stuck/held summary moved to its own sibling so this file
+// stays under the readability band; it is still importable from here,
+// which is the address every caller already knows.
+export { summarizeStuckEvidence, } from "./raw-evidence-stuck-summary.js";
 export const RAW_EVIDENCE_STAGING_FILENAME = "raw-evidence-staging.json";
 /**
  * Backoff schedule for an object whose delivery keeps failing.
@@ -207,33 +211,6 @@ export function evidenceSourceKey(options) {
             : "unknown";
     return `${options.kind}:${options.sessionId ?? "none"}:${source}`;
 }
-/**
- * What `cockpit status` and the health receipt need in order to be unable to
- * read green while an object has been failing for nine days.
- */
-export function summarizeStuckEvidence(state, now) {
-    const entries = Object.values(state.delivery_attempts);
-    const reasons = new Set();
-    let heldCount = 0;
-    let maxAttempts = 0;
-    let oldest = null;
-    for (const entry of entries) {
-        reasons.add(entry.last_reason);
-        if (Date.parse(entry.next_attempt_at) > now.getTime())
-            heldCount += 1;
-        maxAttempts = Math.max(maxAttempts, entry.attempts);
-        if (!oldest || entry.first_failed_at.localeCompare(oldest) < 0) {
-            oldest = entry.first_failed_at;
-        }
-    }
-    return {
-        stuck_object_count: entries.length,
-        held_object_count: heldCount,
-        max_attempts: maxAttempts,
-        oldest_first_failed_at: oldest,
-        reasons: [...reasons].sort(),
-    };
-}
 /**
  * Pack id derived from CONTENT, never from the clock.
  *

package/dist/raw-evidence-stuck-summary.js

@@ -0,0 +1,60 @@
+/**
+ * "Is anything stuck, and is anything being held right now?" — the two
+ * questions `cockpit status`, the health receipt and the fleet board ask of the
+ * delivery-attempt history, split out of `raw-evidence-staging.ts` (BLI-4022)
+ * so that file stays under the repo's readability band.
+ *
+ * The distinction this file exists to keep: an object with a live failure
+ * history is STUCK, and an object whose next attempt is still in the future is
+ * HELD. Every held object is stuck and most stuck objects are held, but the two
+ * answer different questions — "has anything been failing for nine days" versus
+ * "what did this tick withhold, and when does it try again" — and BLI-4022
+ * needed the second one, which nothing computed.
+ *
+ * Metadata only, like the rest of this family: content hashes, byte sizes,
+ * reason labels, timestamps. Never content, never an absolute path.
+ */
+/**
+ * What `cockpit status` and the health receipt need in order to be unable to
+ * read green while an object has been failing for nine days.
+ */
+export function summarizeStuckEvidence(state, now) {
+    const entries = Object.values(state.delivery_attempts);
+    const reasons = new Set();
+    let heldCount = 0;
+    let maxAttempts = 0;
+    let oldest = null;
+    // The held objects are tracked apart from the stuck ones, because a hold is
+    // judged on what is being withheld NOW and on when it may next be offered —
+    // not on every object that has ever failed here.
+    let heldOldest = null;
+    let heldNextAttemptAt = null;
+    for (const entry of entries) {
+        reasons.add(entry.last_reason);
+        if (Date.parse(entry.next_attempt_at) > now.getTime()) {
+            heldCount += 1;
+            if (!heldOldest ||
+                entry.first_failed_at.localeCompare(heldOldest.first_failed_at) < 0) {
+                heldOldest = entry;
+            }
+            if (!heldNextAttemptAt ||
+                entry.next_attempt_at.localeCompare(heldNextAttemptAt) < 0) {
+                heldNextAttemptAt = entry.next_attempt_at;
+            }
+        }
+        maxAttempts = Math.max(maxAttempts, entry.attempts);
+        if (!oldest || entry.first_failed_at.localeCompare(oldest) < 0) {
+            oldest = entry.first_failed_at;
+        }
+    }
+    return {
+        stuck_object_count: entries.length,
+        held_object_count: heldCount,
+        max_attempts: maxAttempts,
+        oldest_first_failed_at: oldest,
+        reasons: [...reasons].sort(),
+        held_oldest_first_failed_at: heldOldest?.first_failed_at ?? null,
+        held_next_attempt_at: heldNextAttemptAt,
+        held_last_reason: heldOldest?.last_reason ?? null,
+    };
+}

package/dist/upload-envelope-build.js

@@ -60,6 +60,13 @@ async function readPairedCollector(paths) {
         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);
+    // BLI-4019 deliberately did NOT loosen this. The heartbeat now knocks while
+    // the machine believes it is expired — that is the door the server renews it
+    // through — but an UPLOAD stays gated on `valid`, so a machine past the
+    // 30-day grace window never spends bandwidth and staging on evidence the
+    // server will refuse. One tick after the renewal lands, this reads `valid`
+    // again, because the heartbeat writes the server's date back into
+    // `session.json` (`recordDeviceTokenExpiry`).
     if (session.session_state !== "valid") {
         throw new LocalUploadBlockedError("unpaired", session.session_state === "expired"
             ? "Collector session expired. Run `cockpit login` or `cockpit pair` again before `cockpit sync`."

package/dist/upload-evidence-delivery-summary.js

@@ -101,6 +101,12 @@ export function hasRetryableEvidenceGap(facts, outcomes) {
  * backoff is missing collection right now. If it did not land here the sync
  * would read clean while a transcript sat undelivered for nine days, which is
  * the exact shape of BLI-3066.
+ *
+ * BLI-4022 did NOT change that. A hold still queues the retry and still travels
+ * to the status output; what changed is downstream, at the ledger in
+ * `commands/session-sync-failures.ts`, which no longer files it as a FAILED
+ * tick. Retryable and failed are two questions, and answering both with this
+ * one set is what painted a collecting machine red for eight ticks.
  */
 function isRetryableEvidenceSkipReason(reason) {
     if (reason === DELIVERY_BACKOFF_HOLDING_REASON)
@@ -201,5 +207,8 @@ export function summarizeRawEvidenceDelivery(built, outcomes, uploadedChunkCount
         raw_evidence_stuck_object_count: stuck.stuck_object_count,
         raw_evidence_max_delivery_attempts: stuck.max_attempts,
         raw_evidence_oldest_delivery_failure_at: stuck.oldest_first_failed_at,
+        raw_evidence_held_oldest_failure_at: stuck.held_oldest_first_failed_at,
+        raw_evidence_held_next_attempt_at: stuck.held_next_attempt_at,
+        raw_evidence_held_last_reason: stuck.held_last_reason,
     };
 }

package/package.json

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