@bli-cockpit/cli 0.2.237 → 0.2.239

package/dist/commands/docs.js

@@ -27,6 +27,7 @@
  * `document_not_writable`, `title_too_long`, `content_too_long`,
  * `circular_parent`, and so on — never rephrased here.
  */
+import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readDoc } from "./docs-read.js";
@@ -59,6 +60,8 @@ export async function runDocs(command, io) {
             return syncStatusDocs(command, door);
         case "export":
             return exportDoc(command, door);
+        case "mutation-status":
+            return mutationStatusDocs(command, door);
     }
 }
 /** `--parent`, `--query`, `--word`, `--limit`, `--bodies` (BLI-10450) as the door's own query parameters (BLI-3737). */
@@ -248,14 +251,41 @@ async function updateDoc(command, door) {
         && !command.clearParent) {
         return failAgentDoor(door, TAG, "invalid_body", "docs update needs at least one of --title, --visibility, --parent/--clear-parent, or a body on --body-stdin/--file.");
     }
-    const answer = await updateDocument(command, door, resolved.id, bodyMarkdown);
+    // BLI-21298: every save carries a request id, so a lost response can be checked and a retry applies once.
+    const requestId = command.requestId ?? randomUUID();
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await updateDocument(command, door, resolved.id, bodyMarkdown, requestId);
+    if (!answer.ok)
+        return refuseDocsWrite(door, answer, requestId);
+    const { document = {}, mutation } = answer.body;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id, request_id: requestId, revision: mutation?.["revision"] ?? document["revision"] })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document, mutation });
+    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}), revision ${String(mutation?.["revision"] ?? document["revision"] ?? "?")}.`);
+    return 0;
+}
+/** Says where the save stands, then fails with the door's own reason (a conflict names the current revision). */
+function refuseDocsWrite(door, answer, requestId) {
+    const mutation = answer.body?.mutation;
+    writeLine(door.io.stderr, `${TAG} check the save with cockpit docs mutation-status ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+    if (mutation?.current) {
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, current_revision: mutation.current.revision ?? mutation.revision })}`);
+    }
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+/** BLI-21298: reads only your own save receipt. A missing receipt is unknown_check_again, never "nothing changed". */
+async function mutationStatusDocs(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/mutations/${encodeURIComponent(command.docRef ?? "")}`,
+        method: "GET",
+        label: "docs mutation status",
+        timeoutMs: READ_DEADLINE_MS,
+    });
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const document = answer.body.document ?? {};
-    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id })}`);
     if (door.json)
-        return emitAgentDoor(door, { ok: true, document });
-    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}).`);
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, JSON.stringify(answer.body));
     return 0;
 }
 /**
@@ -327,13 +357,15 @@ async function deleteOneDocument(door, ref, id) {
         return { ref, ok: false, reason: answer.reason, detail: answer.detail };
     return { ref, ok: true, id };
 }
-async function updateDocument(command, door, documentId, bodyMarkdown) {
+async function updateDocument(command, door, documentId, bodyMarkdown, requestId) {
     return askAgentDoor(door, {
         path: `/api/docs/documents/${encodeURIComponent(documentId)}`,
         method: "PATCH",
         label: "docs update",
         timeoutMs: WRITE_DEADLINE_MS,
         body: {
+            request_id: requestId,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
             ...(command.title !== undefined ? { title: command.title } : {}),
             ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
             ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),

package/dist/commands/doctor-backfill.js

@@ -36,91 +36,108 @@ export async function checkBackfillState(context) {
  */
 export async function fixBackfillState(context) {
     const started = Date.now();
-    const deadline = started + doctorBackfillBudgetSeconds(context, started) * 1000;
-    let caughtUp = 0;
-    let chunks = 0;
-    let live = null;
-    let remaining = null;
-    const receipt = () => `caught up on ${caughtUp} old sessions in ${chunks} chunk${chunks === 1 ? "" : "s"} over ${clock(Date.now() - started)}`;
-    const unfinished = (code, reason) => ({
-        ...needsFix("backfill-complete", code, `${receipt()}, ${remaining ?? "unknown"} still to go; ${reason}; run \`cockpit doctor\` again to continue`),
+    const run = {
+        started,
+        deadline: started + doctorBackfillBudgetSeconds(context, started) * 1000,
+        caughtUp: 0,
+        chunks: 0,
+        live: null,
+        remaining: null,
+    };
+    const stopProgress = startProgress((text) => context.io.stderr.write(text), progressReporter(run));
+    try {
+        return await catchUpChunkByChunk(context, run);
+    }
+    catch (error) {
+        console.error("[doctor] backfill-complete failed", JSON.stringify({ reason: "backfill_threw", error_name: error instanceof Error ? error.name : "unknown" }));
+        return unfinishedRow(run, "backfill_threw", "backfill failed");
+    }
+    finally {
+        stopProgress();
+    }
+}
+function describeReceipt(run) {
+    return `caught up on ${run.caughtUp} old sessions in ${run.chunks} chunk${run.chunks === 1 ? "" : "s"} over ${clock(Date.now() - run.started)}`;
+}
+function unfinishedRow(run, code, reason) {
+    return {
+        ...needsFix("backfill-complete", code, `${describeReceipt(run)}, ${run.remaining ?? "unknown"} still to go; ${reason}; run \`cockpit doctor\` again to continue`),
         nextAction: "cockpit doctor",
-    });
+    };
+}
+function progressReporter(run) {
     let lastLine = null;
-    const stopProgress = startProgress((text) => context.io.stderr.write(text), (elapsedMs) => {
+    return (elapsedMs) => {
+        const { live } = run;
         const snapshot = {
-            caughtUp: live === null ? caughtUp : caughtUp + live.uploaded,
-            remaining: live?.remaining ?? remaining,
+            caughtUp: live === null ? run.caughtUp : run.caughtUp + live.uploaded,
+            remaining: live?.remaining ?? run.remaining,
         };
         console.error("[doctor] backfill-complete progress", JSON.stringify({
             status: live === null ? "between_chunks" : "running", processed: live?.processed ?? null,
-            uploaded: live === null ? null : caughtUp + live.uploaded,
-            caught_up: snapshot.caughtUp, remaining: snapshot.remaining, chunks, elapsed_seconds: Math.floor(elapsedMs / 1000),
+            uploaded: live === null ? null : run.caughtUp + live.uploaded,
+            caught_up: snapshot.caughtUp, remaining: snapshot.remaining, chunks: run.chunks, elapsed_seconds: Math.floor(elapsedMs / 1000),
         }));
         const line = backfillProgressLine(snapshot, lastLine, elapsedMs);
         lastLine = snapshot;
         return line;
-    });
-    try {
-        while (Date.now() < deadline) {
-            const row = await withCollectionGate(context, "backfill-complete", async () => {
-                if (Date.now() >= deadline)
-                    return unfinished("backfill_budget_timeout", "backfill time budget reached");
-                const capture = capturedIo(context.io, false);
-                live = null;
-                chunks += 1;
-                const code = await runBackfillCommand({
-                    homeDir: context.command.homeDir, repoRoot: context.command.repoRoot,
-                    all: true, dryRun: false, yes: true, json: true,
-                    deadlineMs: deadline,
-                    // Doctor never waits for the collection lock (BLI-12872): the gate
-                    // above looked at it, and a busy answer here is reported, not retried.
-                    syncLockWaitMs: 0,
-                    onProgress: (progress) => { live = progress; },
-                }, capture.io);
-                const parsed = parseDoctorBackfillJson(capture.stdout());
-                const counts = asRecord(parsed?.counts);
-                const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
-                caughtUp += count(counts?.["backfilled"]) ?? 0;
-                remaining = count(counts?.["remaining"]) ?? remaining;
-                live = null;
-                if (code === 0 && parsed?.status === "complete") {
-                    // Reporting totals include permanent caps. Preserve their marker
-                    // note instead of retrying history the collector says is complete.
-                    const checked = await checkBackfillState(context);
-                    return ok("backfill-complete", checked.status === "ok" ? checked.code : "complete", receipt() + (checked.status === "ok" ? `; ${checked.message}` : ""));
-                }
-                const verdict = backfillFixVerdict(parsed, jsonField(capture.stderr(), "failure_reason"));
-                if (parsed?.status === "partial" &&
-                    (parsed.failure_reason === "deferred_budget_exhausted" || !parsed.failure_reason)) {
-                    return needsFix("backfill-complete", "backfill_chunk_pending", "more history remains");
-                }
-                return { ...verdict, message: typeof parsed?.failure_reason === "string" ? parsed.failure_reason : "backfill failed without a valid completion receipt" };
-            });
-            if (row.status === "ok") {
-                console.error("[doctor] backfill-complete finished", JSON.stringify({ caught_up: caughtUp, remaining, chunks, elapsed_seconds: Math.floor((Date.now() - started) / 1000) }));
-                return row;
-            }
-            if (row.status === "skipped") {
-                // A running sync (or another catch-up) owns the lock. Doctor does not
-                // wait; it says what this run managed before it stood aside.
-                console.error("[doctor] backfill-complete stood aside", JSON.stringify({ reason: row.code, caught_up: caughtUp, remaining, chunks }));
-                return caughtUp > 0 ? { ...row, message: `${receipt()}; ${row.message}` } : row;
-            }
-            if (row.code === "sync_stuck_not_ended")
-                return row;
-            if (row.code !== "backfill_chunk_pending")
-                return unfinished(row.code, row.message);
+    };
+}
+async function catchUpChunkByChunk(context, run) {
+    while (Date.now() < run.deadline) {
+        const row = await withCollectionGate(context, "backfill-complete", () => runOneChunk(context, run));
+        if (row.status === "ok") {
+            console.error("[doctor] backfill-complete finished", JSON.stringify({ caught_up: run.caughtUp, remaining: run.remaining, chunks: run.chunks, elapsed_seconds: Math.floor((Date.now() - run.started) / 1000) }));
+            return row;
         }
-        return unfinished("backfill_budget_timeout", "backfill time budget reached");
+        if (row.status === "skipped") {
+            // A running sync (or another catch-up) owns the lock. Doctor does not
+            // wait; it says what this run managed before it stood aside.
+            console.error("[doctor] backfill-complete stood aside", JSON.stringify({ reason: row.code, caught_up: run.caughtUp, remaining: run.remaining, chunks: run.chunks }));
+            return run.caughtUp > 0 ? { ...row, message: `${describeReceipt(run)}; ${row.message}` } : row;
+        }
+        if (row.code === "sync_stuck_not_ended")
+            return row;
+        if (row.code !== "backfill_chunk_pending")
+            return unfinishedRow(run, row.code, row.message);
     }
-    catch (error) {
-        console.error("[doctor] backfill-complete failed", JSON.stringify({ reason: "backfill_threw", error_name: error instanceof Error ? error.name : "unknown" }));
-        return unfinished("backfill_threw", "backfill failed");
+    return unfinishedRow(run, "backfill_budget_timeout", "backfill time budget reached");
+}
+async function runOneChunk(context, run) {
+    if (Date.now() >= run.deadline)
+        return unfinishedRow(run, "backfill_budget_timeout", "backfill time budget reached");
+    const capture = capturedIo(context.io, false);
+    run.live = null;
+    run.chunks += 1;
+    const code = await runBackfillCommand({
+        homeDir: context.command.homeDir, repoRoot: context.command.repoRoot,
+        all: true, dryRun: false, yes: true, json: true,
+        deadlineMs: run.deadline,
+        // Doctor never waits for the collection lock (BLI-12872): the gate
+        // above looked at it, and a busy answer here is reported, not retried.
+        syncLockWaitMs: 0,
+        onProgress: (progress) => { run.live = progress; },
+    }, capture.io);
+    const parsed = parseDoctorBackfillJson(capture.stdout());
+    const counts = asRecord(parsed?.counts);
+    run.caughtUp += nonNegativeCount(counts?.["backfilled"]) ?? 0;
+    run.remaining = nonNegativeCount(counts?.["remaining"]) ?? run.remaining;
+    run.live = null;
+    if (code === 0 && parsed?.status === "complete") {
+        // Reporting totals include permanent caps. Preserve their marker
+        // note instead of retrying history the collector says is complete.
+        const checked = await checkBackfillState(context);
+        return ok("backfill-complete", checked.status === "ok" ? checked.code : "complete", describeReceipt(run) + (checked.status === "ok" ? `; ${checked.message}` : ""));
     }
-    finally {
-        stopProgress();
+    const verdict = backfillFixVerdict(parsed, jsonField(capture.stderr(), "failure_reason"));
+    if (parsed?.status === "partial" &&
+        (parsed.failure_reason === "deferred_budget_exhausted" || !parsed.failure_reason)) {
+        return needsFix("backfill-complete", "backfill_chunk_pending", "more history remains");
     }
+    return { ...verdict, message: typeof parsed?.failure_reason === "string" ? parsed.failure_reason : "backfill failed without a valid completion receipt" };
+}
+function nonNegativeCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
 }
 function capturedIo(io, forward) {
     const stdoutChunks = [];

package/dist/commands/doctor-pipeline.js

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

package/dist/commands/heartbeat-post.js

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

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

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