@bli-cockpit/cli 0.2.237 → 0.2.238

package/dist/commands/doctor-pipeline.js

@@ -182,57 +182,70 @@ async function runSyncRepair(context) {
     // machine the operator already fixed by hand (BLI-2362).
     const discoveryArgs = await savedDiscoveryLimitArgs(context.command.homeDir);
     for (const repoRoot of roots) {
-        const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
-        if (context.command.homeDir)
-            args.push("--home", context.command.homeDir);
-        if (!isDefaultDashboardUrl(context.command.dashboardUrl)) {
-            args.push("--dashboard-url", context.command.dashboardUrl);
-        }
-        // One line every 30 s while doctor's own sync runs; the exec has nothing
-        // to count, so the line says it is still working and for how long.
-        const stopProgress = startProgress((text) => context.io.stderr.write(text), (elapsedMs) => waitingLine("sync", elapsedMs));
-        const result = await Promise.resolve(exec("cockpit", args)).finally(stopProgress);
-        const parsed = parseDoctorSyncJson(result.stdout);
-        const output = `${result.stdout}\n${result.stderr}`;
-        const status = jsonField(output, "status");
-        // BLI-4303, before any verdict: a sync that stood aside for the collection
-        // lock never ran, so neither its exit code nor its missing `uploaded`
-        // receipt says anything about this machine's health.
-        const standAside = syncStandAsideVerdict(parsed, status);
-        if (standAside) {
-            console.error("[cockpit-doctor] sync stood aside for a running collection run", JSON.stringify({
-                reason: standAside.code,
-                owner_alive: standAside.ownerAlive,
-                held_since: standAside.heldSince,
-            }));
-            // The gate (`withCollectionGate`) reads the lock again and turns this
-            // into "background sync is running"; the code only travels to it.
-            return needsFix("sync-fresh", standAside.code, "the sync stood aside for the collection lock");
-        }
-        if (status === "live_sync_paused_during_backfill") {
-            return needsFix("sync-fresh", status, "the sync paused for the historical catch-up");
-        }
-        if (result.code !== 0) {
-            const draining = syncBacklogDrainingVerdict(parsed);
-            if (draining) {
-                return needsFix("sync-fresh", "backlog_draining", `${repoRoot}: still catching up (${draining.remainingObjects} ` +
-                    `file${draining.remainingObjects === 1 ? "" : "s"} left for later this run); ` +
-                    "rerun `cockpit sync` to continue");
-            }
-            return fail("sync-fresh", status ?? "sync_failed", `${repoRoot}: ${syncFailureMessage(parsed, result.code)}`);
-        }
-        if (parsed?.collection_complete === false && typeof parsed.discovery_notice === "string") {
-            console.error("[doctor] partial discovery", JSON.stringify({ reason: "discovery_partial" }));
-            return needsFix("sync-fresh", "discovery_partial", parsed.discovery_notice);
-        }
-        if (status !== "uploaded") {
-            return fail("sync-fresh", status ?? "sync_unverified", `sync did not return an uploaded receipt for ${repoRoot}`);
-        }
+        const problem = await syncOneRoot(context, exec, repoRoot, discoveryArgs);
+        if (problem)
+            return problem;
     }
     return ok("sync-fresh", "synced", roots.length === 1
         ? "ran `cockpit sync` and received an uploaded receipt"
         : `received uploaded receipts for ${roots.length} saved roots`);
 }
+function buildSyncArgs(context, repoRoot, discoveryArgs) {
+    const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
+    if (context.command.homeDir)
+        args.push("--home", context.command.homeDir);
+    if (!isDefaultDashboardUrl(context.command.dashboardUrl)) {
+        args.push("--dashboard-url", context.command.dashboardUrl);
+    }
+    return args;
+}
+/** Runs doctor's own sync for one root; returns the failing row, or null when an uploaded receipt came back. */
+async function syncOneRoot(context, exec, repoRoot, discoveryArgs) {
+    const args = buildSyncArgs(context, repoRoot, discoveryArgs);
+    // One line every 30 s while doctor's own sync runs; the exec has nothing
+    // to count, so the line says it is still working and for how long.
+    const stopProgress = startProgress((text) => context.io.stderr.write(text), (elapsedMs) => waitingLine("sync", elapsedMs));
+    const result = await Promise.resolve(exec("cockpit", args)).finally(stopProgress);
+    const output = `${result.stdout}\n${result.stderr}`;
+    return judgeSyncResult(repoRoot, result.code, parseDoctorSyncJson(result.stdout), jsonField(output, "status"));
+}
+/** The failing row for one root's finished sync, or null when it returned an uploaded receipt. */
+function judgeSyncResult(repoRoot, exitCode, parsed, status) {
+    // BLI-4303, before any verdict: a sync that stood aside for the collection
+    // lock never ran, so neither its exit code nor its missing `uploaded`
+    // receipt says anything about this machine's health.
+    const standAside = syncStandAsideVerdict(parsed, status);
+    if (standAside) {
+        console.error("[cockpit-doctor] sync stood aside for a running collection run", JSON.stringify({
+            reason: standAside.code,
+            owner_alive: standAside.ownerAlive,
+            held_since: standAside.heldSince,
+        }));
+        // The gate (`withCollectionGate`) reads the lock again and turns this
+        // into "background sync is running"; the code only travels to it.
+        return needsFix("sync-fresh", standAside.code, "the sync stood aside for the collection lock");
+    }
+    if (status === "live_sync_paused_during_backfill") {
+        return needsFix("sync-fresh", status, "the sync paused for the historical catch-up");
+    }
+    if (exitCode !== 0) {
+        const draining = syncBacklogDrainingVerdict(parsed);
+        if (draining) {
+            return needsFix("sync-fresh", "backlog_draining", `${repoRoot}: still catching up (${draining.remainingObjects} ` +
+                `file${draining.remainingObjects === 1 ? "" : "s"} left for later this run); ` +
+                "rerun `cockpit sync` to continue");
+        }
+        return fail("sync-fresh", status ?? "sync_failed", `${repoRoot}: ${syncFailureMessage(parsed, exitCode)}`);
+    }
+    if (parsed?.collection_complete === false && typeof parsed.discovery_notice === "string") {
+        console.error("[doctor] partial discovery", JSON.stringify({ reason: "discovery_partial" }));
+        return needsFix("sync-fresh", "discovery_partial", parsed.discovery_notice);
+    }
+    if (status !== "uploaded") {
+        return fail("sync-fresh", status ?? "sync_unverified", `sync did not return an uploaded receipt for ${repoRoot}`);
+    }
+    return null;
+}
 // Re-exported so `doctor.ts`, the doctor tests and every other caller keep
 // importing these from `./doctor-pipeline.js` regardless of which sibling
 // computes them.

package/dist/commands/heartbeat-post.js

@@ -0,0 +1,116 @@
+/**
+ * Posting one heartbeat and recording what the dashboard said back.
+ *
+ * Split out of `heartbeat.ts` so that file stays a table of contents: it
+ * decides WHETHER and WHAT to send (dev-build gate, session, receipts, the
+ * payload); this file does the single HTTP exchange and says, on one stderr
+ * line each, whether it landed, was refused or never arrived.
+ */
+import { memoryInstallGaps } from "@bli-cockpit/telemetry-core";
+import { describeError } from "../health-detail.js";
+import { classifySyncHealthError } from "../sync-health-class.js";
+import { noteHeartbeatRefusal, recordHeartbeatPendingToken, recordHeartbeatTokenExpiry, TOKEN_ROTATION_HEADER, } from "./heartbeat-token.js";
+import { noteDoctorRequest } from "./sync-doctor-request.js";
+const HEARTBEAT_TIMEOUT_MS = 5_000;
+export async function postHeartbeat(options, deviceToken, heartbeat, memory) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+    try {
+        const response = await options.io.fetch(`${options.dashboardUrl}/api/ambient/heartbeat`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${deviceToken}`,
+                // BLI-17994. "I store a renewed token if you send one": the dashboard
+                // only rotates for a collector that says so.
+                [TOKEN_ROTATION_HEADER]: "1",
+            },
+            body: JSON.stringify(heartbeat),
+            signal: controller.signal,
+        });
+        noteHeartbeatRefusal(response.ok ? null : response.status);
+        if (!response.ok) {
+            await logHeartbeatRefused(response, heartbeat);
+            return false;
+        }
+        await recordAcceptedHeartbeat(options, response, heartbeat, memory);
+        return true;
+    }
+    catch (error) {
+        console.error("[heartbeat] could not reach the dashboard this tick", JSON.stringify({
+            reason: "heartbeat_transport_failed",
+            root_count: heartbeat.roots.length,
+            ...describeError(error),
+        }));
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 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).
+ * BLI-17994. The door names why it refused (`device_token_expired`,
+ * `device_token_replaced`) in a `reason` field; say it here rather than
+ * leaving a bare status.
+ */
+async function logHeartbeatRefused(response, heartbeat) {
+    const refusal = await Promise.resolve().then(() => response.clone().json()).catch(() => null);
+    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,
+        ...(typeof refusal?.["reason"] === "string" ? { server_reason: refusal["reason"] } : {}),
+        ...(response.status === 401 || response.status === 403
+            ? {
+                next_action: "this token expired, was replaced or was revoked: run `cockpit doctor` to pair this machine again",
+            }
+            : {}),
+    }));
+}
+async function recordAcceptedHeartbeat(options, response, heartbeat, memory) {
+    // The reply carries `token_expires_at` (and a `pending_device_token` when
+    // the token was near its end); the sibling records both, so this machine's
+    // own copy follows the server rather than drifting.
+    const reply = await response.clone().json().catch(() => null);
+    noteDoctorRequest(reply?.device_action);
+    // BLI-17994. Store a pending successor if the door handed one out (the
+    // date does not move: a pending token has not been used), then the date the
+    // door reports, which moves only when this request promoted a token.
+    await recordHeartbeatPendingToken(options.homeDir, reply);
+    await recordHeartbeatTokenExpiry(options.homeDir, response);
+    console.error("[heartbeat] checked in", JSON.stringify({
+        reason: "heartbeat_recorded",
+        http_status: response.status,
+        root_count: heartbeat.roots.length,
+        sync_status: heartbeat.last_sync_status,
+        sync_reason: heartbeat.last_sync_reason ?? null,
+        sessions_observed: heartbeat.sessions_observed ?? null,
+        sessions_outside_root: heartbeat.sessions_outside_root ?? null,
+        sessions_new_this_tick: heartbeat.sessions_new_this_tick ?? null,
+        sessions_pending_upload: heartbeat.sessions_pending_upload ?? null,
+        // BLI-3729. Both branches: a tick that reports no receipt says WHY,
+        // and a tick that reports one says whether memory is fully on. "Is BLI
+        // Memory switched on for this machine?" is now answerable from
+        // sync.err.log alone.
+        memory_receipt: memory.reason,
+        memory_gaps: memory.receipt ? memoryInstallGaps(memory.receipt) : null,
+        // BLI-3788. The hooks are registered (above) AND they either worked or
+        // did not (here). A prompt hook that misses its deadline prints
+        // nothing to the person, so these counts are the only trace one leaves
+        // on this machine; `null` means no counter file, never zero misses.
+        memory_hook_runs_24h: memory.receipt?.hook_runs_24h ?? null,
+        memory_hook_timeouts_24h: memory.receipt?.hook_timeouts_24h ?? null,
+        memory_hook_stats: memory.receipt?.hook_stats_reason ?? null,
+        // BLI-3884. Which route answered those recalls. `null` on a machine
+        // whose memory-mcp does not name one yet — never zero, which would
+        // read as "the daemon answered none".
+        memory_hook_via_daemon_24h: memory.receipt?.hook_via_daemon_24h ?? null,
+        memory_hook_via_direct_24h: memory.receipt?.hook_via_direct_24h ?? null,
+    }));
+}

package/dist/commands/heartbeat-token-lock.js

@@ -50,48 +50,61 @@ export async function acquireTokenRotationLock(homeDir, options = {}) {
         return unlocked("state_dir_unavailable", error, started);
     }
     for (;;) {
-        try {
-            const handle = await fs.open(lockPath, "wx", 0o600);
-            await handle.writeFile(`${JSON.stringify({ pid: process.pid, owner, at_ms: Date.now() })}\n`);
-            await handle.close();
-            const waited = Date.now() - started;
-            if (waited > pollMs) {
-                console.error("[heartbeat] waited for another heartbeat to finish its token exchange", JSON.stringify({ reason: "token_lock_acquired_after_wait", waited_ms: waited }));
-            }
-            return {
-                acquired: true,
-                waited_ms: waited,
-                mode: "held",
-                release: async () => {
-                    // Only remove a lock that is still ours: a holder that was taken over
-                    // as stale must not delete its successor's lock.
-                    const current = await readOwner(lockPath);
-                    if (current === owner)
-                        await fs.rm(lockPath, { force: true }).catch(() => undefined);
-                },
-            };
-        }
-        catch (error) {
-            if (error?.code !== "EEXIST") {
-                return unlocked("lock_file_unwritable", error, started);
-            }
-        }
+        const created = await tryCreateLock({ lockPath, owner, started, pollMs });
+        if (created !== "held_by_someone_else")
+            return created;
         const heldAt = await readHeldAt(lockPath);
         if (heldAt === "gone")
             continue; // released between our create and our read: try again at once
         if (Date.now() - heldAt > staleMs) {
-            // A holder that died: take the lock over.
-            console.error("[heartbeat] removing a stale token-exchange lock", JSON.stringify({ reason: "token_lock_stale_taken_over", age_ms: Date.now() - heldAt }));
-            await fs.rm(lockPath, { force: true }).catch(() => undefined);
+            await takeOverStaleLock(lockPath, heldAt);
             continue;
         }
-        if (Date.now() - started >= waitMs) {
-            console.error("[heartbeat] another heartbeat is still exchanging the device token; skipping this tick's check-in", JSON.stringify({ reason: "token_lock_busy", waited_ms: Date.now() - started, next_action: "the next tick checks in" }));
-            return { acquired: false, waited_ms: Date.now() - started };
-        }
+        if (Date.now() - started >= waitMs)
+            return giveUpWaiting(started);
         await new Promise((resolve) => setTimeout(resolve, pollMs));
     }
 }
+/** Creates the lock file; "held_by_someone_else" means it already exists, anything else unwritable falls back to unlocked. */
+async function tryCreateLock(attempt) {
+    const { lockPath, owner, started, pollMs } = attempt;
+    try {
+        const handle = await fs.open(lockPath, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify({ pid: process.pid, owner, at_ms: Date.now() })}\n`);
+        await handle.close();
+        const waited = Date.now() - started;
+        if (waited > pollMs) {
+            console.error("[heartbeat] waited for another heartbeat to finish its token exchange", JSON.stringify({ reason: "token_lock_acquired_after_wait", waited_ms: waited }));
+        }
+        return {
+            acquired: true,
+            waited_ms: waited,
+            mode: "held",
+            release: async () => {
+                // Only remove a lock that is still ours: a holder that was taken over
+                // as stale must not delete its successor's lock.
+                const current = await readOwner(lockPath);
+                if (current === owner)
+                    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+            },
+        };
+    }
+    catch (error) {
+        if (error?.code !== "EEXIST") {
+            return unlocked("lock_file_unwritable", error, started);
+        }
+        return "held_by_someone_else";
+    }
+}
+/** A holder that died: remove its lock so the next create wins. */
+async function takeOverStaleLock(lockPath, heldAt) {
+    console.error("[heartbeat] removing a stale token-exchange lock", JSON.stringify({ reason: "token_lock_stale_taken_over", age_ms: Date.now() - heldAt }));
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+}
+function giveUpWaiting(started) {
+    console.error("[heartbeat] another heartbeat is still exchanging the device token; skipping this tick's check-in", JSON.stringify({ reason: "token_lock_busy", waited_ms: Date.now() - started, next_action: "the next tick checks in" }));
+    return { acquired: false, waited_ms: Date.now() - started };
+}
 /** Run `work` under the lock; `skipped` is the answer when the lock stays held past the wait. */
 export async function withTokenRotationLock(homeDir, options, skipped, work) {
     const lock = await acquireTokenRotationLock(homeDir, options);

package/dist/commands/heartbeat.js

@@ -19,25 +19,23 @@
  *   The path itself never leaves the machine, exactly as with `cwd_hash` on the
  *   session rows.
  */
-import { noteDoctorRequest } from "./sync-doctor-request.js";
 import crypto from "node:crypto";
 import { collectAgentSetup } from "./agent-setup.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, memoryInstallGaps, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
+import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, MemoryInstallReceiptSchema, setupReceiptGaps, } from "@bli-cockpit/telemetry-core";
 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, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { noteHeartbeatRefusal, readHeartbeatSession, recordHeartbeatTokenExpiry, recordHeartbeatPendingToken, TOKEN_ROTATION_HEADER, } from "./heartbeat-token.js";
+import { postHeartbeat } from "./heartbeat-post.js";
+import { readHeartbeatSession } from "./heartbeat-token.js";
 import { withTokenRotationLock } from "./heartbeat-token-lock.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";
-const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
  *
@@ -226,23 +224,8 @@ export async function sendCollectorHeartbeatBestEffort(options) {
     return withTokenRotationLock(options.homeDir, options.lock, false, () => sendCollectorHeartbeatLocked(options));
 }
 async function sendCollectorHeartbeatLocked(options) {
-    // BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
-    // device row, so an agent's worktree could keep a genuinely dead machine
-    // looking alive to the BLI-3550 reader.
-    const suppression = shouldSuppressFleetReceipts({
-        dashboardUrl: options.dashboardUrl,
-        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
-    });
-    if (suppression.suppressed) {
-        console.error("[heartbeat] dev build; this tick is not checking in with the fleet", JSON.stringify({
-            reason: "receipt_suppressed:dev_build",
-            detected_by: suppression.reason,
-            root_count: options.roots.length,
-            sync_status: options.facts.status,
-            fix: "set COCKPIT_DEV=0 to heartbeat from a checkout deliberately",
-        }));
+    if (isDevBuildSuppressed(options))
         return false;
-    }
     // 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
@@ -255,12 +238,46 @@ async function sendCollectorHeartbeatLocked(options) {
         ...(options.homeDir ? { homeDir: options.homeDir } : {}),
         ...(options.now ? { now: options.now } : {}),
     }).catch(() => ({ receipt: null, reason: "receipt_read_threw" }));
-    // BLI-3731. Read the CACHE, never re-probe: computing the receipt costs five
-    // file reads and a `--print-config` spawn, and these facts change about
-    // monthly. `cockpit memory install`, `onboard` and `doctor` refresh it; a
-    // tick only carries it. Both branches say something, because "the ops board
-    // shows no receipt for this machine" has two very different causes.
     const setupReceipt = await readCachedSetupReceipt(options.homeDir, options.now ?? new Date());
+    logSetupReceiptCarried(setupReceipt);
+    const heartbeat = buildCollectorHeartbeat({
+        roots: options.roots,
+        facts: options.facts,
+        setupReceipt: setupReceipt ? { ...setupReceipt, agent_setup: await collectAgentSetup(options.homeDir ?? os.homedir()) } : null,
+        ...(options.now ? { now: options.now } : {}),
+        memoryInstall: memory.receipt,
+    });
+    return postHeartbeat(options, session.device_token, heartbeat, memory);
+}
+/**
+ * BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
+ * device row, so an agent's worktree could keep a genuinely dead machine
+ * looking alive to the BLI-3550 reader.
+ */
+function isDevBuildSuppressed(options) {
+    const suppression = shouldSuppressFleetReceipts({
+        dashboardUrl: options.dashboardUrl,
+        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
+    });
+    if (!suppression.suppressed)
+        return false;
+    console.error("[heartbeat] dev build; this tick is not checking in with the fleet", JSON.stringify({
+        reason: "receipt_suppressed:dev_build",
+        detected_by: suppression.reason,
+        root_count: options.roots.length,
+        sync_status: options.facts.status,
+        fix: "set COCKPIT_DEV=0 to heartbeat from a checkout deliberately",
+    }));
+    return true;
+}
+/**
+ * BLI-3731. Read the CACHE, never re-probe: computing the receipt costs five
+ * file reads and a `--print-config` spawn, and these facts change about
+ * monthly. `cockpit memory install`, `onboard` and `doctor` refresh it; a
+ * tick only carries it. Both branches say something, because "the ops board
+ * shows no receipt for this machine" has two very different causes.
+ */
+function logSetupReceiptCarried(setupReceipt) {
     console.error(setupReceipt
         ? "[heartbeat] carrying this machine's setup receipt"
         : "[heartbeat] no usable setup receipt to carry; the ops board keeps the last one it has", JSON.stringify(setupReceipt
@@ -273,103 +290,4 @@ async function sendCollectorHeartbeatLocked(options) {
             reason: "setup_receipt_absent_or_stale",
             next_action: "run `cockpit doctor` to refresh it",
         }));
-    const heartbeat = buildCollectorHeartbeat({
-        roots: options.roots,
-        facts: options.facts,
-        setupReceipt: setupReceipt ? { ...setupReceipt, agent_setup: await collectAgentSetup(options.homeDir ?? os.homedir()) } : null,
-        ...(options.now ? { now: options.now } : {}),
-        memoryInstall: memory.receipt,
-    });
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
-    try {
-        const response = await options.io.fetch(`${options.dashboardUrl}/api/ambient/heartbeat`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${session.device_token}`,
-                // BLI-17994. "I store a renewed token if you send one": the dashboard
-                // only rotates for a collector that says so.
-                [TOKEN_ROTATION_HEADER]: "1",
-            },
-            body: JSON.stringify(heartbeat),
-            signal: controller.signal,
-        });
-        noteHeartbeatRefusal(response.ok ? null : response.status);
-        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).
-            // BLI-17994. The door names why it refused (`device_token_expired`,
-            // `device_token_replaced`) in a `reason` field; say it here rather than
-            // leaving a bare status.
-            const refusal = await Promise.resolve().then(() => response.clone().json()).catch(() => null);
-            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,
-                ...(typeof refusal?.["reason"] === "string" ? { server_reason: refusal["reason"] } : {}),
-                ...(response.status === 401 || response.status === 403
-                    ? {
-                        next_action: "this token expired, was replaced or was revoked: run `cockpit doctor` to pair this machine again",
-                    }
-                    : {}),
-            }));
-            return false;
-        }
-        // The reply carries `token_expires_at` (and a `pending_device_token` when
-        // the token was near its end); the sibling records both, so this machine's
-        // own copy follows the server rather than drifting.
-        const reply = await response.clone().json().catch(() => null);
-        noteDoctorRequest(reply?.device_action);
-        // BLI-17994. Store a pending successor if the door handed one out (the
-        // date does not move: a pending token has not been used), then the date the
-        // door reports, which moves only when this request promoted a token.
-        await recordHeartbeatPendingToken(options.homeDir, reply);
-        await recordHeartbeatTokenExpiry(options.homeDir, response);
-        console.error("[heartbeat] checked in", JSON.stringify({
-            reason: "heartbeat_recorded",
-            http_status: response.status,
-            root_count: heartbeat.roots.length,
-            sync_status: heartbeat.last_sync_status,
-            sync_reason: heartbeat.last_sync_reason ?? null,
-            sessions_observed: heartbeat.sessions_observed ?? null,
-            sessions_outside_root: heartbeat.sessions_outside_root ?? null,
-            sessions_new_this_tick: heartbeat.sessions_new_this_tick ?? null,
-            sessions_pending_upload: heartbeat.sessions_pending_upload ?? null,
-            // BLI-3729. Both branches: a tick that reports no receipt says WHY,
-            // and a tick that reports one says whether memory is fully on. "Is BLI
-            // Memory switched on for this machine?" is now answerable from
-            // sync.err.log alone.
-            memory_receipt: memory.reason,
-            memory_gaps: memory.receipt ? memoryInstallGaps(memory.receipt) : null,
-            // BLI-3788. The hooks are registered (above) AND they either worked or
-            // did not (here). A prompt hook that misses its deadline prints
-            // nothing to the person, so these counts are the only trace one leaves
-            // on this machine; `null` means no counter file, never zero misses.
-            memory_hook_runs_24h: memory.receipt?.hook_runs_24h ?? null,
-            memory_hook_timeouts_24h: memory.receipt?.hook_timeouts_24h ?? null,
-            memory_hook_stats: memory.receipt?.hook_stats_reason ?? null,
-            // BLI-3884. Which route answered those recalls. `null` on a machine
-            // whose memory-mcp does not name one yet — never zero, which would
-            // read as "the daemon answered none".
-            memory_hook_via_daemon_24h: memory.receipt?.hook_via_daemon_24h ?? null,
-            memory_hook_via_direct_24h: memory.receipt?.hook_via_direct_24h ?? null,
-        }));
-        return true;
-    }
-    catch (error) {
-        console.error("[heartbeat] could not reach the dashboard this tick", JSON.stringify({
-            reason: "heartbeat_transport_failed",
-            root_count: heartbeat.roots.length,
-            ...describeError(error),
-        }));
-        return false;
-    }
-    finally {
-        clearTimeout(timeout);
-    }
 }

package/dist/commands/install-update.js

@@ -102,21 +102,7 @@ export async function runUpdate(command, io) {
         addInstallEvent(installEvents, "npm_install", "fail", error.eacces
             ? "npm_install_eacces"
             : "npm_install_failed");
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                status: "blocked",
-                step: "npm_install",
-                command: `npm ${selfUpdateInstallArgs().join(" ")}`,
-                exit_code: error.result.code,
-            }, null, 2));
-        }
-        else {
-            writeLine(io.stderr, "BLOCKED: npm install failed; Tower CLI was not refreshed.");
-            if (error.eacces) {
-                writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
-                writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
-            }
-        }
+        writeSelfUpdateBlocked(command, io, error);
         return finish(error.result.code || 1);
     }
     addInstallEvent(installEvents, "npm_install", "ok");
@@ -131,6 +117,22 @@ export async function runUpdate(command, io) {
     addInstallEvent(installEvents, "onboard_rerun", onboard.code === 0 ? "ok" : "fail", onboard.code === 0 ? undefined : updateOnboardFailureCode(onboard));
     return finish(onboard.code);
 }
+function writeSelfUpdateBlocked(command, io, error) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "blocked",
+            step: "npm_install",
+            command: `npm ${selfUpdateInstallArgs().join(" ")}`,
+            exit_code: error.result.code,
+        }, null, 2));
+        return;
+    }
+    writeLine(io.stderr, "BLOCKED: npm install failed; Tower CLI was not refreshed.");
+    if (error.eacces) {
+        writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
+        writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
+    }
+}
 export async function runSelfUpdate(io, options = {}) {
     const exec = io.exec ?? defaultExec();
     const tag = options.tag ?? "latest";

package/dist/commands/issue-show.js

@@ -91,40 +91,39 @@ export async function showIssue(command, door) {
         results.push(await fetchOneIssue(door, ref));
     // BLI-10450: one directory call for the whole batch, never one per issue.
     const directory = await resolveAssigneeDirectory(door, results.filter((result) => result.ok).map((result) => result.issue.assignee_id));
-    // A single ref keeps the pre-BLI-10450 shape and failure path exactly.
-    if (refs.length === 1) {
-        const [result] = results;
-        if (!result || !result.ok) {
-            return failAgentDoor(door, TAG, result?.reason ?? "issue_not_found_or_unreadable", result?.detail ?? "That issue does not exist, or you cannot read it.");
-        }
-        if (door.json) {
-            return emitAgentDoor(door, {
-                ok: true,
-                issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
-                comments: result.comments,
-                ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
-                ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
-            });
-        }
-        renderOneIssue(door, result, directory);
-        return 0;
+    if (refs.length === 1)
+        return reportSingleIssue(door, results[0], directory);
+    return reportSeveralIssues(door, results, directory);
+}
+/** The JSON body for one issue that was read: the issue, its comments and any Linear link. */
+function readIssueJson(result, directory) {
+    return {
+        issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
+        comments: result.comments,
+        ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
+        ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
+    };
+}
+// A single ref keeps the pre-BLI-10450 shape and failure path exactly.
+function reportSingleIssue(door, result, directory) {
+    if (!result || !result.ok) {
+        return failAgentDoor(door, TAG, result?.reason ?? "issue_not_found_or_unreadable", result?.detail ?? "That issue does not exist, or you cannot read it.");
     }
-    // Several refs: `{ ok, issues: [...] }`, one entry per ref in the order
-    // given, each carrying `ref` so a caller can match an answer back to what
-    // it asked for. One bad id never loses the rest of the batch.
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...readIssueJson(result, directory) });
+    renderOneIssue(door, result, directory);
+    return 0;
+}
+// Several refs: `{ ok, issues: [...] }`, one entry per ref in the order
+// given, each carrying `ref` so a caller can match an answer back to what
+// it asked for. One bad id never loses the rest of the batch.
+function reportSeveralIssues(door, results, directory) {
     const failed = results.filter((result) => !result.ok);
     if (door.json) {
         return emitAgentDoor(door, {
             ok: failed.length === 0,
             issues: results.map((result) => result.ok
-                ? {
-                    ref: result.ref,
-                    ok: true,
-                    issue: withSizeLabel(withAssigneeIdentity(result.issue, directory)),
-                    comments: result.comments,
-                    ...(result.linearTicketId ? { linear_ticket_id: result.linearTicketId } : {}),
-                    ...(result.commentsUnreadReason ? { comments_unread_reason: result.commentsUnreadReason } : {}),
-                }
+                ? { ref: result.ref, ok: true, ...readIssueJson(result, directory) }
                 : { ref: result.ref, ok: false, error: result.reason, detail: result.detail }),
         }, failed.length === 0 ? 0 : 1);
     }