@bli-cockpit/cli 0.2.46 → 0.2.47

package/dist/commands/heartbeat.js

@@ -0,0 +1,175 @@
+/**
+ * "I am alive, and these are the folders I may look at." One POST per tick.
+ *
+ * BLI-3551. The dashboard learned a device was alive only when an ambient
+ * envelope arrived, and an envelope only arrives when there was something to
+ * collect. A machine whose operator works entirely outside the approved roots
+ * therefore went silent while working perfectly: 377 ticks in 38 hours without
+ * `last_seen_at` moving once. Dead and quiet looked identical.
+ *
+ * Three deliberate choices:
+ *
+ * - **Not spooled.** The install-events outbox retries for days, which is right
+ *   for a receipt and wrong for a heartbeat: a heartbeat delivered tomorrow is
+ *   a lie about today. A failed send is logged and dropped, and the next tick
+ *   is fifteen minutes away.
+ * - **Never throws, never fails the sync.** Same rule as the self-update tail.
+ * - **Roots travel as labels.** `{ basename, path_sha256 }` — the folder name a
+ *   person recognises plus the stable identity of the normalized absolute path.
+ *   The path itself never leaves the machine, exactly as with `cwd_hash` on the
+ *   session rows.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
+import { describeError } from "../health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+const HEARTBEAT_TIMEOUT_MS = 5_000;
+/**
+ * The label form of one approved root.
+ *
+ * `path.resolve` first so `~/BLI`, `~/BLI/` and `~/BLI/.` are one identity, and
+ * on Windows so `c:\users\…` and `C:\Users\…` do not hash apart — the platform
+ * treats them as the same folder, and two machines pointing at it must compare
+ * equal. Case is folded ONLY on Windows, where the filesystem is
+ * case-insensitive; folding on macOS would merge two genuinely distinct roots.
+ */
+export function collectionRootLabel(root, platform = process.platform) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    const resolved = platform === "win32"
+        ? path.win32.normalize(root).replace(/[\\/]+$/u, "")
+        : path.posix.normalize(root).replace(/\/+$/u, "");
+    const canonical = platform === "win32" ? resolved.toLowerCase() : resolved;
+    const basename = pathApi.basename(resolved) || resolved;
+    return {
+        basename: basename.slice(0, 160),
+        path_sha256: crypto
+            .createHash("sha256")
+            .update(canonical, "utf8")
+            .digest("hex"),
+    };
+}
+/**
+ * The label set for a machine's approved roots, one entry per real folder.
+ *
+ * The collector deliberately keeps CONSENT ALIASES — on macOS an approved
+ * `/var/folders/…` root is held alongside its `/private/var/folders/…`
+ * realpath, so attribution matches either spelling. Both are true, and both
+ * name one folder; a heartbeat that shipped both would make every Mac look like
+ * it had twice the roots it has. Symlinks are resolved before hashing so the
+ * aliases collapse into the one folder they describe, and a path that cannot be
+ * resolved (deleted, or a Windows spelling on a POSIX host) keeps its own
+ * spelling rather than being dropped.
+ */
+export function collectionRootLabels(roots, platform = process.platform, realpath = defaultRealpath) {
+    const byHash = new Map();
+    for (const root of roots) {
+        if (!root.trim())
+            continue;
+        let resolved = root;
+        try {
+            resolved = realpath(root);
+        }
+        catch {
+            // Keep the spelling we were given: a root that is not on disk right now
+            // is still a root this machine is allowed to look at.
+        }
+        const label = collectionRootLabel(resolved, platform);
+        if (!byHash.has(label.path_sha256))
+            byHash.set(label.path_sha256, label);
+    }
+    return [...byHash.values()];
+}
+function defaultRealpath(input) {
+    return fs.realpathSync.native(input);
+}
+export function buildCollectorHeartbeat(options) {
+    const platform = options.platform ?? os.platform();
+    return {
+        schema_version: COLLECTOR_HEARTBEAT_SCHEMA_VERSION,
+        generated_at: (options.now ?? new Date()).toISOString(),
+        collector_version: options.collectorVersion ?? LOCAL_COLLECTOR_VERSION,
+        os_platform: platform,
+        roots: collectionRootLabels(options.roots, platform),
+        last_sync_status: options.facts.status,
+        ...(options.facts.reason ? { last_sync_reason: options.facts.reason } : {}),
+        ...(typeof options.facts.sessionsObserved === "number"
+            ? { sessions_observed: options.facts.sessionsObserved }
+            : {}),
+        ...(typeof options.facts.sessionsOutsideRoot === "number"
+            ? { sessions_outside_root: options.facts.sessionsOutsideRoot }
+            : {}),
+    };
+}
+/**
+ * Sends the heartbeat. Returns whether it landed; never throws.
+ *
+ * Every branch says something (BLI-3551 / the logging contract): a missing
+ * device session, a refusal, a transport failure and the success all get one
+ * line, because "did this machine check in today?" must be answerable from
+ * `sync.err.log` alone when the dashboard says a device is quiet.
+ */
+export async function sendCollectorHeartbeatBestEffort(options) {
+    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",
+        }));
+        return false;
+    }
+    const heartbeat = buildCollectorHeartbeat({
+        roots: options.roots,
+        facts: options.facts,
+        ...(options.now ? { now: options.now } : {}),
+    });
+    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}`,
+            },
+            body: JSON.stringify(heartbeat),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // A heartbeat is not retried, so the reason has to be said once, here.
+            console.error("[heartbeat] the dashboard refused this tick's heartbeat", JSON.stringify({
+                reason: "heartbeat_rejected",
+                http_status: response.status,
+                root_count: heartbeat.roots.length,
+            }));
+            return false;
+        }
+        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,
+        }));
+        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-receipts.js

@@ -14,7 +14,6 @@ import { errorMessage, writeLine } from "./cli-io.js";
 import { describeError, maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
-import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
 import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
 export function addInstallEvent(events, step, status, errorCode, 
 // BLI-2542: the bucket alone cannot be acted on. Callers that hold the reason
@@ -188,24 +187,17 @@ function classifyInstallTelemetryError(error) {
         return "network";
     return "failed";
 }
-export function classifySyncHealthError(error) {
-    const message = errorMessage(error);
-    if (/auth|token|session|unauthorized|forbidden|401|403/iu.test(message)) {
-        return "auth_failed";
-    }
-    if (/fetch|network|enotfound|econnrefused|timeout/iu.test(message)) {
-        return "network_failed";
-    }
-    // Anchored on the code the collector actually throws rather than on loose
-    // vocabulary. The old test matched /collection.root|workspace|repo|worktree/
-    // against the message, so any failure that merely mentioned a repo was filed
-    // as a collection-root failure and the real reason was lost (BLI-2492).
-    if (message.includes(COLLECTION_ROOT_REQUIRED) ||
-        /collection root/iu.test(message)) {
-        return "collection_root_failed";
-    }
-    return "sync_failed";
-}
+/**
+ * The bucket a `sync_complete` receipt carries.
+ *
+ * The implementation moved to `../sync-health-class.js` in BLI-3551 and is
+ * re-exported here because this module's export surface is what `local.ts` and
+ * the tests import. It no longer reads the error's message: matching
+ * `/auth|token|session|…/` against the text filed the sync's own
+ * `session_report_unposted:no_successful_sync` label as `auth_failed` on every
+ * tick of a machine whose credentials were fine.
+ */
+export { classifySyncHealthError, classifySyncFailureRecords, } from "../sync-health-class.js";
 // The bucket above is for aggregation. This is the reason — the actual message,
 // redacted on the machine that produced it, before it ever leaves.
 //

package/dist/commands/install-update.js

@@ -14,7 +14,7 @@ import { defaultExec, defaultInteractiveExec, writeExecOutput, writeLine } from
 import { assertCollectionRootPersisted } from "./collection-roots.js";
 import { addInstallEvent, reportInstallEventsBestEffort } from "./install-receipts.js";
 import { installLocalCollector, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
-import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, rootRejectionExplanation, } from "../onboarding-roots.js";
+import { COLLECTION_ROOT_REQUIRED, CollectionRootRequiredError, missingCollectionRootMessage, normalizeRootsDetailed, rootRejectionExplanation, } from "../onboarding-roots.js";
 export class SelfUpdateError extends Error {
     result;
     eacces;
@@ -75,9 +75,9 @@ function resolveInstallCommandRoots(command) {
         };
     }
     if (detailed.rejected.length > 0) {
-        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(detailed.rejected[0], command)}`);
+        throw new CollectionRootRequiredError(rootRejectionExplanation(detailed.rejected[0], command));
     }
-    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(command)}`);
+    throw new CollectionRootRequiredError(missingCollectionRootMessage(command));
 }
 export async function runUpdate(command, io) {
     const installEvents = [];

package/dist/commands/local-args.js

@@ -776,6 +776,7 @@ function parseAutostartArgs(args) {
             "--workspace",
             "--dashboard-url",
             "--interval-seconds",
+            "--parent-pid",
             "--json",
         ],
         valueFlags: [
@@ -784,13 +785,17 @@ function parseAutostartArgs(args) {
             "--workspace",
             "--dashboard-url",
             "--interval-seconds",
+            "--parent-pid",
         ],
     });
     if (values.positionals.length > 1) {
         throw new Error("autostart accepts at most one action (install|uninstall|status).");
     }
     const action = values.positionals[0] ?? "install";
-    if (action !== "install" && action !== "uninstall" && action !== "status") {
+    if (action !== "install" &&
+        action !== "uninstall" &&
+        action !== "status" &&
+        action !== "heal-detached") {
         throw new Error("autostart action must be install, uninstall, or status.");
     }
     return {
@@ -800,6 +805,7 @@ function parseAutostartArgs(args) {
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         intervalSeconds: optionalPositiveInteger(values.flags.get("--interval-seconds"), "--interval-seconds") ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS,
+        parentPid: optionalPositiveInteger(values.flags.get("--parent-pid"), "--parent-pid"),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local.js

@@ -9,6 +9,7 @@
  *   local-help.ts        what --help prints, and the recognised command names
  *   cli-io.ts            stdout/stderr/stdin plumbing and the production CliIo
  *   install-receipts.ts  the named step results this machine reports back
+ *   heartbeat.ts         the per-tick "I am alive, and these are my roots"
  *   local-auth.ts        which email, the OTP exchange, pairing with fallback
  *   collection-roots.ts  which folders may be collected, saved and read back
  *   local-discovery.ts   finding git worktrees inside those roots
@@ -36,6 +37,8 @@
  *   settings.ts          `cockpit settings` and `cockpit model`
  *   settings-render.ts   how a settings answer reads in a terminal
  *   team.ts              `cockpit team` — members, invite, role
+ *   autostart-heal.ts    the internal detached one-shot the macOS tick spawns
+ *                        to re-register launchd after the tick itself exits
  *
  * What stays here is orchestration: onboard, login/logout/start, the sync tick,
  * analyze, serve, autostart and agent-rules.
@@ -44,7 +47,8 @@ import path from "node:path";
 import { bufferedWritable, defaultExec, defaultIo, errorMessage, parseCapturedJson, replayCaptured, writeLine, } from "./cli-io.js";
 import { isLocalHelpRequest, localCommandHelp } from "./local-help.js";
 import { describeError, isMissingFileFailure } from "../health-detail.js";
-import { addInstallEvent, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
+import { addInstallEvent, classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { canReuseOnboardSession, pairLocalCollectorWithAuthFallback, readOnboardSessionReuseCandidate, requestPairingAccessToken, requestPairingAccessTokenDetailed, resolveInteractiveLoginEmail, resolveOnboardEmail, } from "./local-auth.js";
 import { collectionRootConsentAliases, persistOnboardingRootConfig, resolveOnboardingRootsForCommand, } from "./collection-roots.js";
 import { discoverCommandWorktrees, rememberDiscoveryLimits } from "./local-discovery.js";
@@ -75,16 +79,19 @@ import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from
 import { DEFAULT_DASHBOARD_URL, ensureLocalCollectorConfig, getCollectorRuntimePaths, inspectLocalCollectorStatus, logoutLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, startLocalWorkContext, } from "../local-state.js";
 import { acquireSyncLock } from "../sync-lock.js";
 import { runAttributedWorktreeSync, } from "./session-sync.js";
-import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, } from "../onboarding-roots.js";
+import { COLLECTION_ROOT_REQUIRED, CollectionRootRequiredError, missingCollectionRootMessage, } from "../onboarding-roots.js";
 import { rawEvidenceDedupSummary, rawEvidenceGcSummary, runRawEvidenceLocalGc, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
 import { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
 import { runAutostartSelfHeal, } from "../autostart-self-heal.js";
+import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
+import { runAutostartHealDetached } from "./autostart-heal.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
 // all import from here. Splitting the file must not move a name off it.
 export { rootCommandNames, localCommandHelp } from "./local-help.js";
-export { classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, SYNC_ERROR_DETAIL_MAX_CHARS, } from "./install-receipts.js";
+export { buildCollectorHeartbeat, collectionRootLabel, collectionRootLabels, sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
+export { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, SYNC_ERROR_DETAIL_MAX_CHARS, } from "./install-receipts.js";
 export { assertCollectionRootPersisted } from "./collection-roots.js";
 export { runSelfUpdate, SelfUpdateError, } from "./install-update.js";
 export async function runLocalCockpitCli(argv, io = defaultIo()) {
@@ -1091,6 +1098,11 @@ async function runStart(command, io) {
 }
 async function runSync(command, io) {
     const paths = getCollectorRuntimePaths(command.homeDir);
+    // BLI-3553, first thing in the tick: cap the scheduler's own logs. Nothing
+    // rotated them before, and two months of a 15-minute tick left 211 MB of
+    // sync.log on the reference Mac. Best-effort by construction — a rotation
+    // problem is its own log line, never a reason collection does not run.
+    await rotateCollectorLogsBestEffort(paths);
     const config = await readLocalCollectorConfig(paths).catch(() => null);
     const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
     const minCliVersionAtStart = await reportInstallEventsBestEffort({
@@ -1103,6 +1115,10 @@ async function runSync(command, io) {
     });
     try {
         const result = await runSyncWithHealthReceipt(command, io);
+        // BLI-3551: every tick checks in, including one that collected nothing.
+        // This is the only writer of `last_seen_at` that does not need an envelope,
+        // so it is what separates a quiet machine from a dead one.
+        await sendSyncHeartbeat(command, io, dashboardUrl, result.heartbeat);
         const minCliVersion = await reportInstallEventsBestEffort({
             homeDir: command.homeDir,
             dashboardUrl,
@@ -1118,6 +1134,14 @@ async function runSync(command, io) {
         return result.exitCode;
     }
     catch (error) {
+        const errorCode = classifySyncHealthError(error);
+        // A machine whose sync THREW is still alive, and that is worth knowing —
+        // a device that stops checking in entirely is a different problem from one
+        // checking in with a failure every fifteen minutes.
+        await sendSyncHeartbeat(command, io, dashboardUrl, {
+            status: "fail",
+            reason: errorCode,
+        });
         const minCliVersion = await reportInstallEventsBestEffort({
             homeDir: command.homeDir,
             dashboardUrl,
@@ -1126,7 +1150,7 @@ async function runSync(command, io) {
                 {
                     step: "sync_complete",
                     status: "fail",
-                    error_code: classifySyncHealthError(error),
+                    error_code: errorCode,
                     error_detail: redactedSyncErrorDetail(error),
                 },
             ],
@@ -1138,6 +1162,28 @@ async function runSync(command, io) {
         throw error;
     }
 }
+/**
+ * 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.
+ */
+async function sendSyncHeartbeat(command, io, dashboardUrl, facts) {
+    const roots = await resolveSyncCollectionRoots(command).catch(() => []);
+    await sendCollectorHeartbeatBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        roots,
+        facts,
+        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;
+    });
+}
 /**
  * BLI-2721: after the tick's collection and self-update are done and
  * reported, repair a broken/legacy autostart registration in place (Windows
@@ -1199,7 +1245,10 @@ async function reportAutostartSelfHealOutcome(command, io, dashboardUrl, result)
         command: "sync",
         events: [
             {
-                step: "autostart_repair",
+                // 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 } : {}),
@@ -1298,10 +1347,24 @@ function scheduledSelfUpdateInstallEvent(result) {
         ? `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",
-            ...(forcedDetail ? { error_detail: forcedDetail } : {}),
+            ...(okDetail ? { error_detail: okDetail } : {}),
         };
     }
     const detail = [
@@ -1341,6 +1404,10 @@ async function runSyncWithHealthReceipt(command, io) {
                 status: "skipped",
                 error_code: "live_sync_paused_during_backfill",
             },
+            heartbeat: {
+                status: "skipped",
+                reason: "live_sync_paused_during_backfill",
+            },
         };
     }
     // Single-flight: a launchd timer and a manual sync must not interleave the
@@ -1367,14 +1434,28 @@ async function runSyncWithHealthReceipt(command, io) {
                 status: "skipped",
                 error_code: "sync_already_running",
             },
+            heartbeat: { status: "skipped", reason: "sync_already_running" },
         };
     }
     try {
-        const { exitCode, failureReasons } = await runSyncLocked(command, io);
+        const { exitCode, failureReasons, failureRecords, notice, sessionsObserved, sessionsOutsideRoot, } = await runSyncLocked(command, io);
+        const counts = {
+            sessionsObserved,
+            sessionsOutsideRoot,
+        };
         if (exitCode === 0) {
+            // BLI-3551: an `ok` tick can still have something to say. `nothing_in_root`
+            // 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.
             return {
                 exitCode,
-                completion: { step: "sync_complete", status: "ok" },
+                completion: {
+                    step: "sync_complete",
+                    status: "ok",
+                    ...(notice ? { error_detail: notice } : {}),
+                },
+                heartbeat: { status: "ok", reason: notice, ...counts },
             };
         }
         // A sync that fails by exit code says exactly as much as one that throws.
@@ -1382,14 +1463,18 @@ async function runSyncWithHealthReceipt(command, io) {
         // failure rows carried a null detail and the real reason was reachable only
         // by running `cockpit status` on the machine itself (BLI-2526).
         const reasonText = failureReasons.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(failureRecords);
         return {
             exitCode,
             completion: {
                 step: "sync_complete",
                 status: "fail",
-                error_code: classifySyncHealthError(reasonText),
+                error_code: errorCode,
                 error_detail: redactedSyncErrorDetail(reasonText),
             },
+            heartbeat: { status: "fail", reason: errorCode, ...counts },
         };
     }
     finally {
@@ -1407,6 +1492,10 @@ function syncResult(run) {
     return {
         exitCode: run.ok ? 0 : 1,
         failureReasons: run.ok ? [] : run.failure_reasons,
+        failureRecords: run.ok ? [] : run.failure_records,
+        notice: run.notice,
+        sessionsObserved: run.sessions_observed,
+        sessionsOutsideRoot: run.sessions_outside_root,
     };
 }
 /**
@@ -1492,6 +1581,7 @@ async function reportNoWorktreeSync(command, io, run, dedup) {
             mode: "no_worktrees",
             status: collectionRunStatus,
             collection_complete: run.ok,
+            ...(run.notice ? { notice: run.notice } : {}),
             codex_sessions: run.summary,
             raw_evidence_gc: gc,
             raw_evidence_dedup: dedup,
@@ -1499,6 +1589,11 @@ async function reportNoWorktreeSync(command, io, run, dedup) {
         return syncResult(run);
     }
     writeLine(run.ok ? io.stdout : io.stderr, `Tower sync ${collectionRunStatus}: no git worktrees under this root; session scan ran.`);
+    if (run.notice) {
+        // Says out loud what the receipt now says to the dashboard: the sessions
+        // this machine ran were all outside the folders it is allowed to look at.
+        writeLine(io.stdout, `Every session seen this run was outside your approved folders (${run.notice}). Nothing was collected, and nothing is broken.`);
+    }
     writeAgentSessionSummary(io, run.summary);
     if (gc && !gc.skipped)
         writeLine(io.stdout, rawEvidenceGcSummary(gc));
@@ -1558,7 +1653,7 @@ async function resolveSyncCollectionRoots(command) {
     if (savedRoots.length > 0) {
         return collectionRootConsentAliases(savedRoots);
     }
-    throw new Error(`${COLLECTION_ROOT_REQUIRED}: no explicit or saved collection root is available.`);
+    throw new CollectionRootRequiredError(`no explicit or saved collection root is available.`);
 }
 async function runAnalyze(command, io) {
     const syncStdout = [];
@@ -1701,6 +1796,17 @@ async function runServe(command, io) {
     return 0;
 }
 async function runAutostart(command, io) {
+    if (command.action === "heal-detached") {
+        // BLI-3553: the internal one-shot the scheduled macOS tick spawns. It has
+        // its own receipt and its own exit code; nothing else in this function
+        // applies to it.
+        return runAutostartHealDetached({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            parentPid: command.parentPid ?? null,
+            json: command.json,
+        }, io);
+    }
     const exec = io.exec ?? defaultExec();
     const repoRoots = command.action === "install" || command.action === "status"
         ? await resolveAutostartRoots(command.homeDir, command.repoRoot)

package/dist/commands/ops-render.js

@@ -80,6 +80,8 @@ export function renderOpsStatus(payload, dim) {
                 lines.push(dim(`       scheduled by ${row.configFile} (${row.cron ?? "?"})`));
         }
     }
+    if (payload.fleet)
+        lines.push(...renderFleet(payload.fleet, dim));
     const slack = payload.skips?.slack;
     const external = payload.skips?.external;
     if (slack || external) {
@@ -93,6 +95,33 @@ export function renderOpsStatus(payload, dim) {
     }
     return lines;
 }
+/**
+ * The laptops. Red first, because a person reading this at 9am should not have
+ * to scroll past nine healthy machines to find the dead one.
+ */
+export function renderFleet(fleet, dim) {
+    const lines = ["", `FLEET  ${fleet.summary ?? "(no summary)"}`];
+    if (fleet.readError) {
+        lines.push(`  the fleet could not be read (${fleet.readError}); nothing is known about any machine`);
+        return lines;
+    }
+    const devices = fleet.devices ?? [];
+    const rank = (colour) => colour === "red" ? 0 : colour === "amber" ? 1 : 2;
+    const ordered = [...devices].sort((left, right) => rank(left.colour) - rank(right.colour));
+    if (ordered.length === 0) {
+        lines.push(dim("  no live collector device is registered at all"));
+    }
+    for (const device of ordered) {
+        const text = `  ${device.line ?? device.deviceId ?? "(device)"}`;
+        // A healthy machine is dimmed, never dropped: "which laptops are fine" is
+        // the other half of the question, and a list that only shows failures
+        // cannot answer "is everybody else collecting?".
+        lines.push(device.colour === "red" || device.colour === "amber" ? text : dim(text));
+    }
+    if (fleet.noDeviceLine)
+        lines.push(dim(`  ${fleet.noDeviceLine}`));
+    return lines;
+}
 function renderSkipLedger(ledger, dim) {
     const lines = [];
     const name = ledger.relation ?? "skips";

package/dist/commands/ops.js

@@ -78,6 +78,12 @@ async function runOpsStatus(command, io, tower) {
         unhealthy: unhealthy.length,
         unhealthy_ids: unhealthy.map((row) => row.id ?? "?"),
         with_skips: Boolean(command.skips),
+        // The laptops (BLI-3550), counted on the same line: a run that shows a
+        // green board and says nothing about the fleet cannot answer "was
+        // anybody's machine dead this morning?".
+        fleet_devices: payload.fleet?.counts?.devices ?? null,
+        fleet_red: payload.fleet?.counts?.red ?? null,
+        fleet_amber: payload.fleet?.counts?.amber ?? null,
     })}`);
     return unhealthy.length > 0 ? 1 : 0;
 }

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.46");
+    writeLine(io?.stdout ?? process.stdout, "0.2.47");
     return 0;
   }