@bli-cockpit/cli 0.2.69 → 0.2.70

package/dist/commands/heartbeat.js

@@ -29,6 +29,7 @@ import { describeError } from "../health-detail.js";
 import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
+import { readMemoryHookCounts } from "./memory-hook-counts.js";
 const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
@@ -123,6 +124,13 @@ export function buildCollectorHeartbeat(options) {
  * reads and a `--print-config` spawn every fifteen minutes to re-prove a state
  * that changes about once a month. The reason is returned rather than logged
  * here so the ONE heartbeat log line carries it.
+ *
+ * BLI-3788: the hook COUNTS are merged in here, on the tick, and deliberately
+ * not baked into the cached receipt. The five words change about monthly; how
+ * often the prompt hook lost its deadline changes every hour, and a number
+ * cached for a day would answer yesterday's question. An install receipt this
+ * machine could not read means no counts either — there is nowhere to put
+ * them — and that case keeps the receipt's own reason.
  */
 export async function readHeartbeatMemoryReceipt(options) {
     const paths = getCollectorRuntimePaths(options.homeDir);
@@ -142,7 +150,20 @@ export async function readHeartbeatMemoryReceipt(options) {
             return parsed.success ? parsed.data : null;
         },
     });
-    return { receipt: result.receipt, reason: result.reason };
+    if (!result.receipt)
+        return { receipt: null, reason: result.reason };
+    const hooks = readMemoryHookCounts({
+        homeDir: options.homeDir ?? os.homedir(),
+        ...(options.now ? { now: options.now } : {}),
+    });
+    return {
+        receipt: {
+            ...result.receipt,
+            ...(hooks.counts ?? {}),
+            hook_stats_reason: hooks.reason,
+        },
+        reason: result.reason,
+    };
 }
 /**
  * Sends the heartbeat. Returns whether it landed; never throws.
@@ -248,6 +269,13 @@ export async function sendCollectorHeartbeatBestEffort(options) {
             // 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,
         }));
         return true;
     }

package/dist/commands/memory-hook-counts.js

@@ -0,0 +1,61 @@
+/**
+ * HOW OFTEN DID THE HOOKS MISS? — the reading half (BLI-3788).
+ *
+ * `bli-memory-mcp` counts every hook run into a counts-only file in this
+ * machine's state directory. This module reads it once a sync tick and hands
+ * the last 24 hours to the heartbeat, where it rides the memory receipt into
+ * `ambient_collector_devices.metadata.memory_install` and out onto `cockpit
+ * ops --memory`.
+ *
+ * Nothing here knows the file's shape: the path, the schema and the windowing
+ * rule are `@bli-cockpit/telemetry-core`'s `memory-hook-stats.ts`, which the
+ * writing package spends too. That is the whole point of putting them there.
+ *
+ * ## Which event, and why only one
+ *
+ * The PROMPT hook. It is the one a person waits on with their sentence typed,
+ * the one whose budget QA tick 18 caught it losing, and the one that runs on
+ * every turn — so it is the only one whose miss rate means anything as a
+ * daily number. The file holds all three; a future gauge that wants
+ * SessionStart or Stop reads the same rows with the same function.
+ *
+ * ## Absent is not zero
+ *
+ * A machine with no file has no counts and says `hook_stats_absent`. A machine
+ * whose file will not parse says `hook_stats_unparseable`. Neither reports
+ * zeroes, because a zero here would read as "the hooks ran and never missed",
+ * which is the exact false green this ticket exists to remove.
+ */
+import fs from "node:fs";
+import { memoryHookStatsFilePath, parseMemoryHookStats, summariseMemoryHookWindow, } from "@bli-cockpit/telemetry-core";
+export function readMemoryHookCounts(options) {
+    const readText = options.readText ?? defaultReadText;
+    const file = memoryHookStatsFilePath(options.homeDir);
+    const raw = readText(file);
+    if (raw === null)
+        return { counts: null, reason: "hook_stats_absent" };
+    const parsed = parseMemoryHookStats(raw);
+    if (!parsed.ok)
+        return { counts: null, reason: parsed.reason };
+    const window = summariseMemoryHookWindow(parsed.file, "prompt", {
+        now: options.now ?? new Date(),
+        hours: 24,
+    });
+    return {
+        counts: {
+            hook_runs_24h: window.runs,
+            hook_timeouts_24h: window.timeouts,
+            hook_printed_24h: window.printed,
+            hook_failed_24h: window.failed,
+        },
+        reason: "ok",
+    };
+}
+function defaultReadText(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/ops-render-memory.js

@@ -70,6 +70,40 @@ export function renderMemoryUsage(memory, dim) {
     }
     return lines;
 }
+/**
+ * The hook half: one line per machine, the server's own words.
+ *
+ * A machine that reports NO counts is printed too, dimmed and named. It is the
+ * whole point: "no measurement" and "no misses" are different facts, and the
+ * only reason this section exists is that they used to be indistinguishable.
+ */
+export function renderMemoryHooks(hooks, dim) {
+    const lines = ["", `HOOKS   ${hooks.summary ?? "(no summary)"}`];
+    if (hooks.readError) {
+        lines.push(`  the devices could not be read (${hooks.readError}); nothing is known about whether recalls are arriving`);
+        return lines;
+    }
+    const devices = hooks.devices ?? [];
+    if (devices.length === 0) {
+        lines.push(dim("  no live collector device to report on"));
+        return lines;
+    }
+    // Worst first: the machine losing recalls is the one somebody acts on, and a
+    // machine that reports nothing sinks below both — it is a rollout gap, not a
+    // failure.
+    const ranked = [...devices].sort((left, right) => {
+        const leftKnown = typeof left.runs === "number" ? 0 : 1;
+        const rightKnown = typeof right.runs === "number" ? 0 : 1;
+        if (leftKnown !== rightKnown)
+            return leftKnown - rightKnown;
+        return (right.timeouts ?? 0) - (left.timeouts ?? 0);
+    });
+    for (const device of ranked) {
+        const line = `  ${device.line ?? `${device.displayName ?? "?"}: (no line)`}`;
+        lines.push((device.timeouts ?? 0) > 0 ? line : dim(line));
+    }
+    return lines;
+}
 /** The two sources that mean a PERSON's agent used memory. Never the import. */
 function agentSaves(counts) {
     return (counts?.mcp ?? 0) + (counts?.stop_hook ?? 0);

package/dist/commands/ops-render.js

@@ -12,7 +12,7 @@
  * artifact does and does not prove — because that is exactly the moment
  * somebody is about to conclude something from it.
  */
-export { renderMemoryUsage } from "./ops-render-memory.js";
+export { renderMemoryHooks, renderMemoryUsage } from "./ops-render-memory.js";
 /** The word a person reads. Short, fixed width, and never a bare colour. */
 export function verdictWord(verdict) {
     switch (verdict) {

package/dist/commands/ops.js

@@ -25,7 +25,7 @@
  */
 import { colorEnabled, dim, writeLine } from "./cli-io.js";
 import { renderOpsStatus } from "./ops-render.js";
-import { renderMemoryUsage, } from "./ops-render-memory.js";
+import { renderMemoryHooks, renderMemoryUsage, } from "./ops-render-memory.js";
 import { asRecord, callTower, openTower, writeCommandFailure } from "./tower-command.js";
 /**
  * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
@@ -79,7 +79,7 @@ async function runOpsStatus(command, io, tower) {
         // BLI-3762: a job that ran and wrote less than it owed is not healthy.
         row.verdict === "degraded");
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify(memory ? { ...payload, memory: memory.section } : payload));
+        writeLine(io.stdout, JSON.stringify(memory ? { ...payload, memory: memory.section, hooks: memory.hooks } : payload));
     }
     else {
         const styled = colorEnabled(io);
@@ -91,7 +91,16 @@ async function runOpsStatus(command, io, tower) {
                 writeLine(io.stdout, line);
             }
         }
-        else if (memory) {
+        // BLI-3788. Printed whenever the door sent it, including when the usage
+        // half could not be read: "are the recalls arriving" and "is anybody
+        // saving" are two questions, and one being unreadable does not silence
+        // the other.
+        if (memory?.hooks) {
+            for (const line of renderMemoryHooks(memory.hooks, (text) => dim(text, styled))) {
+                writeLine(io.stdout, line);
+            }
+        }
+        if (memory && !memory.section) {
             // Never a silent gap where a section was asked for: the reason the gauge
             // could not be read is printed where the gauge would have been.
             writeLine(io.stdout, "");
@@ -119,6 +128,12 @@ async function runOpsStatus(command, io, tower) {
         memory_agent_saves: memory?.section
             ? (memory.section.counts?.mcp ?? 0) + (memory.section.counts?.stop_hook ?? 0)
             : null,
+        // BLI-3788: whether the per-turn recalls arrived, on the same line. A
+        // null here is "this dashboard does not report it yet", never zero
+        // misses.
+        memory_hook_runs_24h: memory?.hooks?.totals?.runs ?? null,
+        memory_hook_timeouts_24h: memory?.hooks?.totals?.timeouts ?? null,
+        memory_hook_devices_reporting: memory?.hooks?.reporting ?? null,
     })}`);
     return unhealthy.length > 0 ? 1 : 0;
 }
@@ -144,12 +159,15 @@ async function readMemoryUsage(command, io, tower) {
             reason: result.reason,
             http_status: result.httpStatus ?? null,
         })}`);
-        return { section: null, reason: result.reason };
+        return { section: null, hooks: null, reason: result.reason };
     }
     const body = asRecord(result.body);
+    // BLI-3788: the hook counts ride the same answer, and their absence is a
+    // fact about the SERVER's version rather than about this fleet — an older
+    // dashboard sends no `hooks` key, and printing nothing is right there.
     if (!body.memory)
-        return { section: null, reason: "memory_section_absent" };
-    return { section: body.memory, reason: "ok" };
+        return { section: null, hooks: body.hooks ?? null, reason: "memory_section_absent" };
+    return { section: body.memory, hooks: body.hooks ?? null, reason: "ok" };
 }
 async function runOpsRecompile(command, io, tower) {
     const person = command.person ?? "";

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.69",
+  "version": "0.2.70",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.9",
-    "@bli-cockpit/mcp": "0.1.10",
-    "@bli-cockpit/telemetry-core": "0.1.30"
+    "@bli-cockpit/memory-mcp": "0.1.10",
+    "@bli-cockpit/mcp": "0.1.11",
+    "@bli-cockpit/telemetry-core": "0.1.31"
   }
 }