@bli-cockpit/cli 0.2.94 → 0.2.96

package/dist/commands/heartbeat-token.js

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

package/dist/commands/heartbeat.js

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

package/dist/commands/public-root.js

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

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

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

package/dist/commands/sync-followups-autostart.js

@@ -0,0 +1,99 @@
+import { resolveAutostartRoots } from "./autostart-command.js";
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { runAutostartSelfHeal, } from "../autostart-self-heal.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+/**
+ * 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) {
+            sayNoProcessRunner();
+            await reportAutostartSelfHealOutcome(command, io, dashboardUrl, runnerUnavailableOutcome());
+            return;
+        }
+        result = await repairAutostartRegistration(command, io, rawExec);
+    }
+    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);
+}
+/**
+ * Attempt the repair with a runner that can find node.
+ *
+ * Every spawn in the scheduled path carries the running node's bin dir on
+ * PATH (`envWithNodeRuntimeOnPath`); the scheduler's stripped environment
+ * needs it. Returns null when there was nothing to repair.
+ */
+async function repairAutostartRegistration(command, io, rawExec) {
+    const spawnEnv = envWithNodeRuntimeOnPath(io.env ?? process.env);
+    const exec = (cmd, args, options) => rawExec(cmd, args, { ...options, env: options?.env ?? spawnEnv });
+    return runAutostartSelfHeal(getCollectorRuntimePaths(command.homeDir), {
+        homeDir: command.homeDir,
+        repoRoots: await resolveAutostartRoots(command.homeDir, undefined),
+        dashboardUrl: command.dashboardUrl,
+        exec,
+    });
+}
+/**
+ * Say out loud that the repair was never attempted.
+ *
+ * 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.
+ */
+function sayNoProcessRunner() {
+    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`",
+    }));
+}
+/** The same fact as a receipt, so the fleet table can see it too. */
+function runnerUnavailableOutcome() {
+    return {
+        status: "skipped",
+        reason: "runner_unavailable",
+        detail: "No process runner available to this CLI invocation; run `cockpit autostart install` by hand.",
+    };
+}
+/** 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,
+    });
+}

package/dist/commands/sync-followups-memory.js

@@ -0,0 +1,123 @@
+/**
+ * Follow-up three: keep BLI Memory registered with both agent hosts (BLI-3580).
+ *
+ * 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 other follow-ups: 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.
+ *
+ * Split out of `sync-followups.ts` (BLI-3988). The registration itself, and
+ * every target it writes, are `./memory-install.ts`.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { installMemoryIntegration, } from "./memory-install.js";
+import { getCollectorRuntimePaths, } from "../local-state.js";
+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, once a day.
+ *
+ * The daily cadence and the swallowed error paths are the whole contract; see
+ * this module's header for why each of them is what it is.
+ */
+export async function runMemoryInstallAfterSync(command, io, dashboardUrl, options = {}) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const now = options.now ?? new Date();
+    if (await triedWithinTheLastDay(paths, now))
+        return;
+    await markInstallAttempted(paths, now);
+    const event = await installMemoryOrSayWhyNot(command, io, dashboardUrl);
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [event],
+        json: command.json,
+        io,
+    });
+}
+/** Has this machine already had its one attempt today? */
+async function triedWithinTheLastDay(paths, now) {
+    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
+    const lastAttempt = await fs.stat(marker).catch(() => null);
+    if (!lastAttempt)
+        return false;
+    return now.getTime() - lastAttempt.mtimeMs < MEMORY_INSTALL_MIN_INTERVAL_MS;
+}
+/**
+ * Spend today's attempt before making it.
+ *
+ * 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.
+ */
+async function markInstallAttempted(paths, now) {
+    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
+}
+/** The registration attempt, as a receipt either way; it cannot throw. */
+async function installMemoryOrSayWhyNot(command, io, dashboardUrl) {
+    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);
+        return memoryInstallEvent(outcome);
+    }
+    catch (error) {
+        return {
+            step: "memory_install",
+            status: "fail",
+            error_code: "memory_install_threw",
+            error_detail: redactedSyncErrorDetail(error),
+        };
+    }
+}
+/**
+ * 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 };
+}

package/dist/commands/sync-followups-self-update.js

@@ -0,0 +1,127 @@
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { runSelfUpdate, SelfUpdateError } from "./install-update.js";
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
+/**
+ * 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 } : {}),
+    };
+}