@bli-cockpit/cli 0.2.93 → 0.2.95

package/dist/commands/sync-followups.js

@@ -1,513 +1,32 @@
 /**
  * What the sync tick does AFTER collection's own outcome is decided and
- * reported: keep this machine's CLI current on npm `latest` (BLI-2601), put a
- * broken scheduler registration back (BLI-2721), keep BLI Memory registered
- * with both agent hosts (BLI-3580), re-offer staged evidence that never landed
- * (BLI-3797), and stop the laptop filling up (BLI-3619).
- *
- * Split out of commands/sync.ts (BLI-3578), moved verbatim. They belong
- * together because they share one rule, and it is the reason both are called
- * last: a follow-up may never block, delay or fail collection. Every error path
- * here is swallowed on purpose and reported as its own named receipt — an
- * `update` step, or an autostart repair step — never as a `sync` failure.
- */
-import fs from "node:fs/promises";
-import path from "node:path";
-import { resolveAutostartRoots } from "./autostart-command.js";
-import { installMemoryIntegration, } from "./memory-install.js";
-import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
-import { runSelfUpdate, SelfUpdateError } from "./install-update.js";
-import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { runAutostartSelfHeal, } from "../autostart-self-heal.js";
-import { runStagingPrune } from "../disk-prune.js";
-import { runEvidenceReconcile, } from "../evidence-reconcile-client.js";
-import { runEvidenceRedelivery, } from "../evidence-redelivery.js";
-import { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
-/** How many reconcile batches (of up to 500 hashes each) one sync tick may spend. */
-const RECONCILE_BATCHES_PER_TICK = 1;
-/**
- * BLI-2721: after the tick's collection and self-update are done and
- * reported, repair a broken/legacy autostart registration in place (Windows
- * only — see autostart-self-heal.ts for why macOS is excluded). Every error
- * path is swallowed like the self-update's: heal outcomes are their own
- * receipts, never a sync failure.
- */
-export async function runAutostartSelfHealAfterSync(command, io, dashboardUrl) {
-    let result;
-    try {
-        const rawExec = io.exec;
-        if (!rawExec) {
-            // BLI-3483: this was a bare `return`. On Windows the self-heal is the
-            // only thing that puts a broken scheduler back, so abandoning it here
-            // meant a machine could stop collecting forever and leave no receipt
-            // anywhere — the exact shape the fleet contract forbids. The packed CLI
-            // always supplies a runner (`commands/cli-io.ts`), so this fires only for
-            // an embedder that built its own `io`; it costs one line either way.
-            console.error("[autostart-self-heal] no process runner on this io; the repair could not be attempted", JSON.stringify({
-                reason: "runner_unavailable",
-                platform: process.platform,
-                next_action: "reinstall the CLI (npm i -g @bli-cockpit/cli) and run `cockpit autostart install`",
-            }));
-            result = {
-                status: "skipped",
-                reason: "runner_unavailable",
-                detail: "No process runner available to this CLI invocation; run `cockpit autostart install` by hand.",
-            };
-            await reportAutostartSelfHealOutcome(command, io, dashboardUrl, result);
-            return;
-        }
-        const spawnEnv = envWithNodeRuntimeOnPath(io.env ?? process.env);
-        const exec = (cmd, args, options) => rawExec(cmd, args, { ...options, env: options?.env ?? spawnEnv });
-        result = await runAutostartSelfHeal(getCollectorRuntimePaths(command.homeDir), {
-            homeDir: command.homeDir,
-            repoRoots: await resolveAutostartRoots(command.homeDir, undefined),
-            dashboardUrl: command.dashboardUrl,
-            exec,
-        });
-    }
-    catch (error) {
-        result = {
-            status: "fail",
-            reason: "autostart_self_heal_threw",
-            detail: redactedSyncErrorDetail(error),
-        };
-    }
-    // Steady state (healthy, absent, non-Windows, no roots) and the daily
-    // throttle are silent; an actual repair attempt reports either way.
-    if (!result || result.reason === "repair_throttled_recent_attempt")
-        return;
-    await reportAutostartSelfHealOutcome(command, io, dashboardUrl, result);
-}
-/** One receipt for the repair, whichever branch above produced the outcome. */
-async function reportAutostartSelfHealOutcome(command, io, dashboardUrl, result) {
-    await reportInstallEventsBestEffort({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        command: "sync",
-        events: [
-            {
-                // Windows repairs in place and keeps the name already in the receipts
-                // and the runbook; the macOS path only SCHEDULES a detached repair, so
-                // it reports under its own step (BLI-3553).
-                step: result.step ?? "autostart_repair",
-                status: result.status,
-                ...(result.status === "ok" ? {} : { error_code: result.reason }),
-                ...(result.detail ? { error_detail: result.detail } : {}),
-            },
-        ],
-        json: command.json,
-        io,
-    });
-}
-export const MEMORY_INSTALL_THROTTLE_MARKER = ".last-memory-install";
-const MEMORY_INSTALL_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
-/**
- * BLI-3580: BLI Memory's registration converges on its own.
- *
- * Nobody is going to be asked to install a hook. `do-everything` registers it
- * on the way through, and this puts it back if a host config is edited,
- * replaced, or restored from a machine that never had it — at most once a day,
- * because the steady state is "already current" and re-proving that every
- * fifteen minutes is four file reads a tick for no new information.
- *
- * Same rule as the two follow-ups above: it runs only once collection's own
- * outcome has been decided and reported, it never throws, and its outcome is
- * its own named receipt rather than a sync failure.
- */
-export async function runMemoryInstallAfterSync(command, io, dashboardUrl, options = {}) {
-    const paths = getCollectorRuntimePaths(command.homeDir);
-    const now = options.now ?? new Date();
-    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
-    const lastAttempt = await fs.stat(marker).catch(() => null);
-    if (lastAttempt &&
-        now.getTime() - lastAttempt.mtimeMs < MEMORY_INSTALL_MIN_INTERVAL_MS) {
-        return;
-    }
-    // Written for the ATTEMPT, not the outcome — the same idiom the self-update
-    // and autostart repair use, so a machine that cannot write a host config does
-    // not retry it every fifteen minutes.
-    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
-    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
-    let event;
-    try {
-        const outcome = await installMemoryIntegration({
-            kind: "memory",
-            action: "install",
-            homeDir: command.homeDir,
-            dashboardUrl,
-            dryRun: false,
-            json: command.json,
-        }, io, 
-        // Undefined on the real CLI (no io literal sets it); a test io can
-        // override the bin lookup so `bin_missing` is a fixture rather than a
-        // property of the machine the suite runs on (BLI-3630).
-        io.memoryInstallDeps);
-        event = memoryInstallEvent(outcome);
-    }
-    catch (error) {
-        event = {
-            step: "memory_install",
-            status: "fail",
-            error_code: "memory_install_threw",
-            error_detail: redactedSyncErrorDetail(error),
-        };
-    }
-    await reportInstallEventsBestEffort({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        command: "sync",
-        events: [event],
-        json: command.json,
-        io,
-    });
-}
-/**
- * Target names and reason labels only. A target's `path` names a person's home
- * directory and a `write_failed` detail can carry one, so neither travels: the
- * receipt says `claude_hooks:read_back_mismatch`, which is the part an operator
- * can act on.
- */
-function memoryInstallEvent(outcome) {
-    const detail = [
-        `source=${outcome.config_source}`,
-        ...outcome.targets.map((target) => `${target.target}:${target.status}/${target.reason}`),
-    ].join("; ");
-    if (outcome.status === "failed") {
-        return {
-            step: "memory_install",
-            status: "fail",
-            error_code: outcome.reason,
-            error_detail: detail,
-        };
-    }
-    if (outcome.status === "skipped") {
-        // Nothing was written, on purpose (`no_bin_no_write`). A fleet-wide
-        // `bin_missing` is the receipt that says the server package has not
-        // reached the machines yet — a fact, not a fault.
-        return {
-            step: "memory_install",
-            status: "skipped",
-            error_code: outcome.reason,
-            error_detail: detail,
-        };
-    }
-    return { step: "memory_install", status: "ok", error_detail: detail };
-}
-/**
- * BLI-3619: staged raw evidence Tower has already accepted stops living on the
- * laptop forever.
- *
- * Same shape as the memory install above and for the same reasons: it runs only
- * once collection's own outcome is decided and reported, at most once a day, it
- * cannot throw, and its outcome is its own named receipt rather than a sync
- * failure. A machine that cannot prune is a machine short of disk, and that
- * must never also be a machine that stops collecting.
- *
- * The rule itself is `disk-retention.ts`: only objects the upload ledger
- * vouches for are ever deleted, and anything undelivered is counted, aged and
- * named instead.
- *
- * BLI-3619's second half runs FIRST, every tick, bounded to
- * `RECONCILE_BATCHES_PER_TICK` (one batch of up to 500 hashes): the local
- * ledger's own memory is capped, so a laptop that keeps accumulating
- * `unknown` state needs SOMETHING asking the server on a schedule, not only
- * when a person happens to type `cockpit clean --reconcile`. One batch a tick
- * is not throttled to once a day like the prune below — an `unknown` backlog
- * drains at up to 500 hashes/15 min, and the ordinary case (nothing unknown)
- * costs one cheap local read and no network call at all, so it never competes
- * with collection for the tick's time. A reconcile failure never blocks the
- * prune that follows it.
- *
- * BLI-3797 sits between them: the reconcile has just established which staged
- * objects the SERVER says it never received, so the redelivery drain re-offers
- * exactly those, bounded, before the prune runs and can delete whatever landed.
- * Neither of the two can block the prune, and none of the three can fail a tick.
- */
-export async function runStagingPruneAfterSync(command, io, dashboardUrl, options = {}) {
-    const events = [];
-    const reconciled = await runReconcileFollowUp(command, io, dashboardUrl, options);
-    if (reconciled)
-        events.push(reconcileEvent(reconciled));
-    const redelivered = await runRedeliveryFollowUp(command, io, dashboardUrl, options);
-    if (redelivered)
-        events.push(redeliveryEvent(redelivered));
-    let result;
-    try {
-        result = await runStagingPrune(getCollectorRuntimePaths(command.homeDir), {
-            env: io.env,
-            ...(options.now ? { now: options.now } : {}),
-        });
-    }
-    catch (error) {
-        // runStagingPrune already catches everything it can reach; this is the
-        // last-resort net so a prune crash truly cannot touch the sync result.
-        result = { ...prunedNothing(), reason: "prune_threw", status: "fail" };
-        console.error("[collector prune] the prune follow-up threw", JSON.stringify({
-            reason: "prune_followup_threw",
-            detail: redactedSyncErrorDetail(error),
-        }));
-    }
-    // The daily throttle is the steady state — reporting it would post a receipt
-    // on 95 of every 96 ticks for no new information.
-    if (result.reason !== "throttled_recent_run") {
-        events.push(stagingPruneEvent(result));
-    }
-    if (events.length === 0)
-        return;
-    await reportInstallEventsBestEffort({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        command: "sync",
-        events,
-        json: command.json,
-        io,
-    });
-}
-/**
- * Never throws (`runEvidenceReconcile` already never does); returns `null`
- * for the boring, common case — nothing this tick was `unknown` — so that
- * case costs no receipt either, the same rule the prune's own daily throttle
- * follows above.
- */
-async function runReconcileFollowUp(command, io, dashboardUrl, options) {
-    const result = await runEvidenceReconcile({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        maxBatches: RECONCILE_BATCHES_PER_TICK,
-        fetch: io.fetch,
-        ...(options.now ? { now: options.now } : {}),
-    });
-    return result.reason === "nothing_unknown" ? null : result;
-}
-/**
- * BLI-3797, between the reconcile above and the prune below, and in that order
- * for a reason: reconcile turns `unknown` into a server-backed answer, this
- * re-offers what that answer says never landed, and the prune then deletes
- * whatever this just made durable. Running the drain first would ask the server
- * about hashes it is about to be told the truth about; running it after the
- * prune would leave a tick's worth of freed cap unused.
- *
- * Never throws (`runEvidenceRedelivery` already never does); returns `null` for
- * the boring, common case — nothing on this disk is undelivered — so the steady
- * state costs no receipt, the same rule the reconcile follow-up above and the
- * prune's daily throttle below both follow.
- */
-async function runRedeliveryFollowUp(command, io, dashboardUrl, options) {
-    const result = await runEvidenceRedelivery({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        env: io.env,
-        fetch: io.fetch,
-        ...(options.now ? { now: options.now } : {}),
-    });
-    return result.reason === "nothing_uncommitted" ? null : result;
-}
-/** Counts and byte totals only; no pack id and no hash travels in a receipt. */
-function redeliveryEvent(result) {
-    const detail = [
-        `offered ${result.offered} object(s), ${result.offered_bytes}B, across ${result.packs} pack(s)`,
-        `uploaded ${result.uploaded} (${result.uploaded_bytes}B), reused ${result.reused}, failed ${result.failed}`,
-        `held ${result.held}, deferred ${result.deferred} (${result.deferred_bytes}B)`,
-        result.failure_reasons.length > 0
-            ? `failure_reasons ${result.failure_reasons.join(",")}`
-            : null,
-    ]
-        .filter((part) => Boolean(part))
-        .join("; ");
-    if (result.status === "fail") {
-        return {
-            step: "evidence_redelivery",
-            status: "fail",
-            error_code: result.reason,
-            error_detail: detail,
-        };
-    }
-    if (result.status === "skipped") {
-        return {
-            step: "evidence_redelivery",
-            status: "skipped",
-            error_code: result.reason,
-            error_detail: detail,
-        };
-    }
-    return { step: "evidence_redelivery", status: "ok", error_detail: detail };
-}
-function prunedNothing() {
-    return {
-        status: "skipped",
-        reason: "prune_threw",
-        deleted_files: 0,
-        deleted_bytes: 0,
-        removed_packs: 0,
-        kept_uncommitted: 0,
-        kept_uncommitted_bytes: 0,
-        oldest_uncommitted_age_ms: 0,
-        kept_unknown: 0,
-        kept_unknown_bytes: 0,
-        kept_in_window: 0,
-        cap_bytes: 0,
-        bytes_before: 0,
-        bytes_after: 0,
-        cap_blocked_by_uncommitted: false,
-        cap_blocked_count: 0,
-        failed_deletions: 0,
-    };
-}
-/** Counts and byte totals only; no pack id and no path travels in a receipt. */
-function stagingPruneEvent(result) {
-    const detail = [
-        `freed ${result.deleted_bytes}B in ${result.deleted_files} file(s)`,
-        `held ${result.kept_uncommitted_bytes}B uncommitted`,
-        result.cap_blocked_by_uncommitted
-            ? `staging_cap_blocked_by_uncommitted ${result.cap_blocked_count}`
-            : null,
-        result.failed_deletions > 0
-            ? `failed_deletions ${result.failed_deletions}`
-            : null,
-    ]
-        .filter((part) => Boolean(part))
-        .join("; ");
-    if (result.status === "fail") {
-        return {
-            step: "staging_prune",
-            status: "fail",
-            error_code: result.reason,
-            error_detail: detail,
-        };
-    }
-    if (result.status === "skipped") {
-        return { step: "staging_prune", status: "skipped", error_code: result.reason };
-    }
-    return { step: "staging_prune", status: "ok", error_detail: detail };
-}
-/** Counts only; no hash and no pack id travels in a receipt. */
-function reconcileEvent(result) {
-    const detail = `asked ${result.asked} hash(es) across ${result.batches}/${result.total_batches} batch(es); committed ${result.committed}, not_committed ${result.not_committed}, unknown_to_server ${result.unknown_to_server}, failed_batches ${result.failed_batches}`;
-    if (result.status === "fail") {
-        return { step: "evidence_reconcile", status: "fail", error_code: result.reason, error_detail: detail };
-    }
-    return { step: "evidence_reconcile", status: "ok", error_detail: detail };
-}
-/**
- * BLI-2601: the fleet keeps itself current on npm `latest` without anyone
- * re-running `npm i -g @bli-cockpit/cli` by hand after day 0. This always
- * runs AFTER `runSync` has already decided and reported collection's own
- * outcome above — a stuck or failing self-update can never block or delay
- * collection, and a collection failure never blocks the chance to
- * self-update. Every error path here is swallowed on purpose: a failure is
- * reported as its own named `update` receipt, never surfaced as a `sync`
- * failure or thrown from this function.
- */
-export async function runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion) {
-    let event;
-    try {
-        event = await runScheduledSelfUpdateForSync(command, io, minCliVersion);
-    }
-    catch (error) {
-        // The throttle/probe/install machinery below is defensive already; this
-        // is the last-resort net so an update crash truly cannot touch the sync
-        // result above.
-        event = {
-            step: "update",
-            status: "fail",
-            error_code: "self_update_threw",
-            error_detail: redactedSyncErrorDetail(error),
-        };
-    }
-    if (!event)
-        return;
-    await reportInstallEventsBestEffort({
-        homeDir: command.homeDir,
-        dashboardUrl,
-        command: "update",
-        events: [event],
-        json: command.json,
-        io,
-    });
-}
-async function runScheduledSelfUpdateForSync(command, io, minCliVersion) {
-    const rawExec = io.exec;
-    if (!rawExec) {
-        // Only the real production `defaultIo()` supplies a process runner. A
-        // caller that omitted one gets a silent no-op rather than this reaching
-        // for a real npm binary it was never given — never observed in
-        // production, where `defaultIo()` always sets `exec`.
-        return null;
-    }
-    // Every spawn in the scheduled path carries the running node's bin dir on
-    // PATH — see envWithNodeRuntimeOnPath. Interactive doctor never needed
-    // this; the scheduler's stripped environment does.
-    const spawnEnv = envWithNodeRuntimeOnPath(io.env ?? process.env);
-    const exec = (cmd, args, options) => rawExec(cmd, args, { ...options, env: options?.env ?? spawnEnv });
-    const scheduledIo = { ...io, exec };
-    const paths = getCollectorRuntimePaths(command.homeDir);
-    const result = await runScheduledSelfUpdate(paths, {
-        exec,
-        currentVersion: LOCAL_COLLECTOR_VERSION,
-        install: (tag) => attemptScheduledSelfUpdateInstall(scheduledIo, tag),
-    }, { env: io.env, minVersion: minCliVersion });
-    return scheduledSelfUpdateInstallEvent(result);
-}
-async function attemptScheduledSelfUpdateInstall(io, tag) {
-    try {
-        // Reuses the exact npm-install machinery `cockpit doctor`'s
-        // `fixCliLatest` uses (see doctor.ts:243-280) so there is one place that
-        // knows how to invoke `npm i -g` and classify EACCES. Unlike doctor,
-        // this call never re-execs — see runScheduledSelfUpdate's doc comment.
-        await runSelfUpdate(io, { json: true, tag });
-        return { ok: true };
-    }
-    catch (error) {
-        if (!(error instanceof SelfUpdateError))
-            throw error;
-        return { ok: false, eacces: error.eacces };
-    }
-}
-function scheduledSelfUpdateInstallEvent(result) {
-    // The steady-state "already checked today" case is a pure no-op; reporting
-    // it would post a receipt on ~95 of every 96 sync ticks for no new
-    // information. Only a real attempt (ok, fail, or an explicit disable)
-    // produces a receipt.
-    if (result.reason === "throttled_recent_attempt")
-        return null;
-    // A forced attempt names its trigger in the receipt either way, so the
-    // ledger can tell "converged on the daily cadence" from "the floor pulled
-    // this machine forward" (BLI-2678).
-    const forcedDetail = result.forced && result.min_version
-        ? `forced_min_version ${result.min_version}`
-        : null;
-    if (result.status === "ok") {
-        // BLI-3551: this used to be `update ok` with an empty detail unless the
-        // floor forced it. One machine posted that receipt daily for nine releases
-        // while sitting on 0.2.37, and nobody could tell "already current" from
-        // "installed something" from "npm answered nothing" — three different
-        // situations wearing one word. The success branch names itself now.
-        const okDetail = [
-            forcedDetail,
-            result.reason === "updated" && result.previous_version && result.installed_version
-                ? `installed ${result.previous_version}→${result.installed_version}`
-                : result.reason,
-            result.target_version ? `target ${result.target_version}` : null,
-        ]
-            .filter((part) => Boolean(part))
-            .join("; ");
-        return {
-            step: "update",
-            status: "ok",
-            ...(okDetail ? { error_detail: okDetail } : {}),
-        };
-    }
-    const detail = [
-        forcedDetail,
-        result.target_version ? `target ${result.target_version}` : null,
-        result.installed_version ? `installed ${result.installed_version}` : null,
-    ]
-        .filter((part) => Boolean(part))
-        .join("; ");
-    return {
-        step: "update",
-        status: result.status,
-        error_code: result.reason,
-        ...(detail ? { error_detail: detail } : {}),
-    };
-}
+ * reported. Read the four exports below as the table of contents: each is one
+ * follow-up, each lives in exactly one sibling, and nothing else lives here.
+ *
+ *   keep this CLI current on npm `latest`   sync-followups-self-update.ts
+ *   put a broken scheduler back             sync-followups-autostart.ts
+ *   keep BLI Memory registered              sync-followups-memory.ts
+ *   reconcile, re-offer, then prune staging sync-followups-staging.ts
+ *
+ * They belong together because they share one rule, and it is the reason all
+ * four are called last: a follow-up may never block, delay or fail collection.
+ * Every error path in this family is swallowed on purpose and reported as its
+ * own named receipt — an `update` step, an autostart repair step, a
+ * `memory_install`, an `evidence_reconcile`, an `evidence_redelivery`, a
+ * `staging_prune` — never as a `sync` failure. Three of the four are throttled
+ * to one attempt a day; the reconcile is the exception and says why in its own
+ * file.
+ *
+ * `sync.ts` calls the first three from `convergeAfterTick` and the staging one
+ * on its own line (the throwing arm has never run it). Split out of
+ * commands/sync.ts (BLI-3578), then into the siblings above (BLI-3988); the
+ * fifth follow-up on that call, the memory experience log, was always its own
+ * module (`memory-log.ts`). A new sibling must also join
+ * `scripts/build-public-cli.mjs` `runtimeFiles`, or the repo tests stay green
+ * while the packed CLI breaks, and `sync-followups-lock.test.ts` holds this
+ * family's export surface and every literal it writes.
+ */
+export { runAutostartSelfHealAfterSync } from "./sync-followups-autostart.js";
+export { MEMORY_INSTALL_THROTTLE_MARKER, runMemoryInstallAfterSync, } from "./sync-followups-memory.js";
+export { runScheduledSelfUpdateAfterSync } from "./sync-followups-self-update.js";
+export { runStagingPruneAfterSync } from "./sync-followups-staging.js";

package/dist/commands/sync-heartbeat.js

@@ -0,0 +1,36 @@
+import { sendCollectorHeartbeatBestEffort, readHeartbeatStagingFacts, } from "./heartbeat.js";
+import { resolveSyncCollectionRoots } from "./sync-roots.js";
+import { describeError } from "../health-detail.js";
+/**
+ * The tick's check-in (BLI-3551).
+ *
+ * Resolving the roots is best-effort on purpose: a machine with NO approved
+ * root is exactly the machine whose silence needs explaining, so it still
+ * checks in — with an empty root list, which is itself the finding.
+ */
+export async function sendSyncHeartbeat(command, io, dashboardUrl, facts) {
+    const roots = await resolveSyncCollectionRoots(command).catch(() => []);
+    // BLI-3797: the backlog figure rides the same check-in as the root labels, so
+    // `cockpit ops` learns about undelivered evidence on the SAME tick that proves
+    // the machine is alive. Best-effort: nulls omit the fields rather than
+    // reporting a zero nobody measured.
+    const staging = await readHeartbeatStagingFacts({
+        homeDir: command.homeDir,
+    }).catch(() => ({ bytes: null, reason: null }));
+    await sendCollectorHeartbeatBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        roots,
+        facts: {
+            ...facts,
+            stagingUncommittedBytes: staging.bytes,
+            stagingUncommittedReason: staging.reason,
+        },
+        io,
+    }).catch((error) => {
+        // The sender already swallows everything it knows about; this is the net
+        // for anything it does not, because a heartbeat must never fail a sync.
+        console.error("[heartbeat] the check-in threw and was dropped", JSON.stringify({ reason: "heartbeat_threw", ...describeError(error) }));
+        return false;
+    });
+}