@bli-cockpit/cli 0.2.95 → 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.95");
+    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/local-state-pairing.js

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

package/dist/local-state.js

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

package/dist/upload-envelope-build.js

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

package/package.json

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