@bli-cockpit/cli 0.2.97 → 0.2.99

package/dist/commands/local.js

@@ -1,5 +1,6 @@
 import { defaultIo, errorMessage, writeLine } from "./cli-io.js";
 import { isLocalHelpRequest, localCommandHelp, rootCommandNames } from "./local-help.js";
+import { beginStage, endStage } from "../crash-guard.js";
 import { describeError } from "../health-detail.js";
 import { reportInstallEventsBestEffort } from "./install-receipts.js";
 import { persistOnboardingRootConfig, resolveOnboardingRootsForCommand, } from "./collection-roots.js";
@@ -33,6 +34,7 @@ import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryLog } from "./memory-log.js";
 import { runMemoryInstall } from "./memory-install.js";
+import { runMemoryStore, runMemoryVerbList } from "./memory-store.js";
 import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
@@ -41,6 +43,7 @@ import { runCal } from "./cal.js";
 import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
+import { runUsage } from "./usage.js";
 import { parseLocalArgs } from "./local-args.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
@@ -76,6 +79,9 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
     // including the scheduled one nobody types into (BLI-2362). Done here so it
     // applies to whichever command carried the flag.
     await rememberDiscoveryLimits(command);
+    // BLI-4110: the outermost stage name, so a crash that escapes every catch
+    // below still says which subcommand was running.
+    beginStage(`command:${command.kind}`);
     try {
         switch (command.kind) {
             case "install":
@@ -148,7 +154,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
             case "memory-log":
                 return await runMemoryLog(command, io);
             case "memory":
+                // BLI-4047: a bare `cockpit memory` says what the noun does. It used
+                // to install; `install` is still one word away and every unattended
+                // caller asks for it by name in code.
+                if (command.action === "help")
+                    return runMemoryVerbList(io, command.json);
                 return await runMemoryInstall(command, io);
+            case "memory-store":
+                return await runMemoryStore(command, io);
             case "clean":
                 return await runClean(command, io);
             case "docs":
@@ -167,6 +180,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runSearch(command, io);
             case "release":
                 return await runRelease(command, io);
+            case "usage":
+                return await runUsage(command, io);
         }
     }
     catch (error) {
@@ -184,6 +199,9 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
         writeLine(io.stderr, errorMessage(error));
         return 1;
     }
+    finally {
+        endStage(`command:${command.kind}`);
+    }
 }
 async function runDoctorLogin(command, io) {
     return runLogin({

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

@@ -11,13 +11,19 @@
  * 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
+ * ## Which event, and why the detail is on one of them
  *
- * 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.
+ * The PROMPT hook gets the full breakdown. 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.
+ *
+ * BLI-4057 added the other two as a run count and a failure count each. Until
+ * then the fleet heard from one hook of three, so a SAVE hook that had
+ * stopped firing was invisible on every surface: `hooks ok` on the install
+ * receipt, 40 prompt recalls in the counts, and nothing anywhere saying that
+ * no memory had been written in ten days. Two numbers each is the smallest
+ * thing that can say "it ran" and "it ran and could not finish" apart.
  *
  * ## Absent is not zero
  *
@@ -37,8 +43,14 @@ export function readMemoryHookCounts(options) {
     const parsed = parseMemoryHookStats(raw);
     if (!parsed.ok)
         return { counts: null, reason: parsed.reason };
-    const window = summariseMemoryHookWindow(parsed.file, "prompt", {
-        now: options.now ?? new Date(),
+    const at = options.now ?? new Date();
+    const window = summariseMemoryHookWindow(parsed.file, "prompt", { now: at, hours: 24 });
+    // BLI-4057. The same rows, the same function, the other two events — said
+    // out loud in the module header: the file always held all three and only one
+    // of them ever left the machine.
+    const stop = summariseMemoryHookWindow(parsed.file, "stop", { now: at, hours: 24 });
+    const sessionStart = summariseMemoryHookWindow(parsed.file, "session-start", {
+        now: at,
         hours: 24,
     });
     return {
@@ -55,6 +67,15 @@ export function readMemoryHookCounts(options) {
                 : {}),
             hook_skipped_trivial_24h: window.skippedTrivial,
             hook_billing_exhausted_24h: window.billingExhausted,
+            // A lost deadline and a refusal are ONE number for these two, unlike the
+            // prompt hook above: for a recall the difference decides whether to
+            // re-fit a budget or pay a bill, and for a save both mean the same
+            // thing — nothing was written. The prompt hook keeps them apart because
+            // it is the only one whose miss rate is read as a rate.
+            hook_stop_runs_24h: stop.runs,
+            hook_stop_failed_24h: stop.failed + stop.timeouts,
+            hook_session_start_runs_24h: sessionStart.runs,
+            hook_session_start_failed_24h: sessionStart.failed + sessionStart.timeouts,
             // Ticket 3934. Reported as the bin's LOWER bound — the smaller, true
             // claim — and only when something was measured. A machine that recorded
             // no histogram carries no key at all, which the board reads as

package/dist/commands/memory-store.js

@@ -0,0 +1,331 @@
+/**
+ * `cockpit memory search|save|update|forget` — BLI Memory at a terminal
+ * (BLI-4047).
+ *
+ * Memory was the one Tower surface with no command-line door. The browser had
+ * one, the `bli-memory` MCP server had four tools, and a person or a script
+ * had nothing — so a machine without an agent host could not read or write the
+ * store at all, and `cockpit memory` typed on its own registered an MCP server
+ * instead of saying what the noun does. These four verbs are the twins of that
+ * server's four tools.
+ *
+ * **The same doors, never a second store.** `POST /api/memory/{search,save,
+ * update,forget}`, with this machine's collector device token, through
+ * `agent-door.ts` — the identical route the MCP server calls in
+ * `packages/cockpit-memory-mcp/src/server.ts` and the browser calls from
+ * `lib/memory/agent-memories/`. Nothing here talks to Postgres, embeds
+ * anything, or knows what a container alias is; every ranking, redaction and
+ * lifecycle decision stays server-side where its one implementation lives.
+ *
+ * **A refusal keeps the door's own reason label.** `needs_rls_client`,
+ * `unknown_memory`, `already_forgotten`, `already_superseded`,
+ * `needs_container_tag`, `no_match`, `custom_id_conflict`, `search_timed_out`
+ * — printed verbatim by `failAgentDoor`, never rephrased here. A CLI that
+ * invents its own prose for a server's refusal is a CLI whose error messages
+ * lie one release later.
+ *
+ * **The container tag is `@bli-cockpit/memory-mcp`'s, not a second copy.**
+ * `resolveContainerTag` is imported from that package rather than
+ * reimplemented, so a memory saved by `cockpit memory save` lands in exactly
+ * the space the MCP server and the three hooks read from. The scheme is the
+ * vendor plugin's byte for byte and two implementations of it would strand
+ * memories in a space nothing asks about — see that module's header.
+ *
+ * **A body never comes from the command line.** `save`, `update` and
+ * `forget --content-stdin` read stdin (or `--file`). Same discipline as
+ * `cockpit docs create` and `cockpit notes paste`, and for the same reasons:
+ * `ps` shows an argument list, shell history keeps it, and a memory with a
+ * newline in it cannot be quoted correctly anyway.
+ */
+import { resolveContainerTag } from "@bli-cockpit/memory-mcp/dist/container-tag.js";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+const TAG = "[memory cli]";
+const SEARCH_DEADLINE_MS = 60_000;
+/** `--extract` is one model call, sometimes two; the door waits for it when asked to. */
+const WRITE_DEADLINE_MS = 120_000;
+/** The door's own ceiling on a memory (`saveMemoryInput`, 200k characters). */
+const BODY_MAX_CHARS = 200_000;
+/** The door's own ceiling on forget-by-text. */
+const FORGET_MAX_CHARS = 10_000;
+export async function runMemoryStore(command, io) {
+    const door = await openAgentDoor("memory", command, io);
+    switch (command.action) {
+        case "search":
+            return searchMemory(command, door);
+        case "save":
+            return saveMemory(command, door);
+        case "update":
+            return updateMemory(command, door);
+        case "forget":
+            return forgetMemory(command, door);
+    }
+}
+/**
+ * The verb list a bare `cockpit memory` prints (BLI-4047).
+ *
+ * It used to run the installer. Typing a noun to find out what it does is the
+ * single most common thing a person does with a new CLI, and this was the one
+ * command in the collector that answered that by writing five files in a home
+ * directory. Installing is still one word away, and every unattended caller
+ * asks for `install` by name in code.
+ */
+export function runMemoryVerbList(io, json) {
+    if (json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: true,
+            noun: "memory",
+            machine_verbs: ["install", "status"],
+            store_verbs: ["search", "save", "update", "forget"],
+            log_verbs: ["log"],
+        }));
+        return 0;
+    }
+    for (const line of [
+        "cockpit memory — BLI Memory: the store, and this machine's registration.",
+        "",
+        "The store (Tower, over /api/memory/*):",
+        "  cockpit memory search \"<question>\" [--container <tag>] [--limit 1..20] [--no-recent] [--json]",
+        "  cockpit memory save [--container <tag>] [--custom-id <id>] [--extract] [--file <path>] [--json]",
+        "      the memory comes from stdin, or --file; never from the command line",
+        "  cockpit memory update <id> [--file <path>] [--json]        replacement text on stdin",
+        "  cockpit memory forget <id> [--reason <label>] [--json]",
+        "  cockpit memory forget --content-stdin --container <tag> [--reason <label>] [--json]",
+        "",
+        "This machine:",
+        "  cockpit memory install [--dry-run] [--json]   register the MCP server and the three hooks",
+        "  cockpit memory status [--json]                read the stored config back",
+        "",
+        "The experience log:",
+        "  cockpit memory log <win|loss|noise> --store <bli|supermemory|both> \"<reason>\"",
+        "",
+        "Omit --container and this repository's own memory space is used — the same",
+        "space the bli-memory MCP server and its hooks read and write.",
+    ]) {
+        writeLine(io.stdout, line);
+    }
+    return 0;
+}
+/**
+ * This repository's memory space, resolved by the MCP server's own resolver.
+ * `--container` wins; `--workspace` says which directory to derive it from.
+ */
+function containerTagsFor(command) {
+    if (command.containerTags.length > 0)
+        return command.containerTags;
+    return [resolveContainerTag({ cwd: command.workspace ?? process.cwd() }).containerTag];
+}
+async function searchMemory(command, door) {
+    const containerTags = containerTagsFor(command);
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/search",
+        method: "POST",
+        label: "memory search",
+        timeoutMs: SEARCH_DEADLINE_MS,
+        body: {
+            query: command.query,
+            containerTag: containerTags,
+            ...(command.limit === undefined ? {} : { limit: command.limit }),
+            includeProfile: command.includeRecent !== false,
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const results = body.results ?? [];
+    const recent = body.recent ?? [];
+    // Counts and labels only: a memory body never enters a log line.
+    writeLine(door.io.stderr, `${TAG} searched ${JSON.stringify({
+        requested_containers: containerTags.length,
+        searched_containers: body.containerTags?.length ?? containerTags.length,
+        results: results.length,
+        recent: recent.length,
+        dropped_below_floor: body.dropped_below_floor ?? 0,
+        degraded: body.degraded ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    if (results.length === 0) {
+        // The distinction the whole store is built on: silence is not an outage.
+        // A failure took the `!answer.ok` branch above and named itself there.
+        writeLine(door.io.stdout, "No memories matched. The record is silent on this — it does not mean the store is down.");
+    }
+    else {
+        for (const row of results) {
+            writeLine(door.io.stdout, `${similarityLabel(row)}${oneLine(row["memory"])}`);
+            writeLine(door.io.stdout, `    ${String(row["id"] ?? "")}  ${String(row["containerTag"] ?? "")}`);
+        }
+    }
+    if (recent.length > 0) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "Recent context:");
+        for (const row of recent)
+            writeLine(door.io.stdout, `  - ${oneLine(row["preview"] ?? row["memory"])}`);
+    }
+    if (body.degraded) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `This answer is thinner than usual (${body.degraded}) — one search channel did not run.`);
+    }
+    return 0;
+}
+async function saveMemory(command, door) {
+    const containerTag = containerTagsFor(command)[0];
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "There is nothing to save. Pipe the memory in: `echo \"...\" | cockpit memory save`, or pass --file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/save",
+        method: "POST",
+        label: "memory save",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            content: body.text,
+            containerTag,
+            ...(command.customId ? { customId: command.customId } : {}),
+            mode: command.extract ? "extract" : "verbatim",
+            // Same reason the MCP tool sets it: a caller that ASKED for distillation
+            // is waiting for the answer, so take the synchronous branch instead of
+            // the 202 the Stop hook wants.
+            ...(command.extract ? { wait: true } : {}),
+            sourceRef: { kind: "cli" },
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const saved = answer.body;
+    writeLine(door.io.stderr, `${TAG} saved ${JSON.stringify({
+        outcome: saved["outcome"] ?? null,
+        chars: body.text.length,
+        embedded: saved["embedded"] ?? null,
+        embed_skipped_reason: saved["embedSkippedReason"] ?? null,
+        extract: saved["extract"] ?? null,
+        masked_spans: saved["maskedSpans"] ?? 0,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The container the SERVER used, which is the canonical one when this
+    // repository has more than one tag on the shelf; saying the tag we sent
+    // would name a space the row is not in.
+    const landedIn = String(saved["containerTag"] ?? containerTag);
+    writeLine(door.io.stdout, `Memory ${String(saved["outcome"] ?? "created")} in ${landedIn} (id: ${String(saved["id"] ?? "—")}).`);
+    if (saved["embedded"] === false && saved["embedSkippedReason"]) {
+        writeLine(door.io.stdout, `Stored without a search vector (${String(saved["embedSkippedReason"])}): findable by keyword, not yet by meaning.`);
+    }
+    if (saved["extract"] === "fell_back_verbatim") {
+        writeLine(door.io.stdout, `Saved as written; extraction failed (${String(saved["extractFailureReason"] ?? "unknown")}).`);
+    }
+    return 0;
+}
+async function updateMemory(command, door) {
+    const body = await readBody(command, door, BODY_MAX_CHARS, "A memory");
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (!body.text.trim()) {
+        return failAgentDoor(door, TAG, "content_empty", "An update needs replacement text on stdin or --file. To remove a memory, use `cockpit memory forget`.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/update",
+        method: "POST",
+        label: "memory update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { id: command.memoryId, content: body.text },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const updated = answer.body;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({
+        chars: body.text.length,
+        re_embedded: updated["reEmbedded"] ?? null,
+        embed_skipped_reason: updated["embedSkippedReason"] ?? null,
+    })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, `Updated. The new memory is ${String(updated["id"] ?? "")}, and ${String(updated["supersededId"] ?? command.memoryId ?? "")} is kept as its previous version.`);
+    return 0;
+}
+async function forgetMemory(command, door) {
+    let content;
+    if (command.contentStdin) {
+        const body = await readBody(command, door, FORGET_MAX_CHARS, "Text to forget");
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        if (!body.text.trim()) {
+            return failAgentDoor(door, TAG, "needs_id_or_content", "Nothing arrived on stdin to forget.");
+        }
+        content = body.text;
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/memory/forget",
+        method: "POST",
+        label: "memory forget",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.memoryId ? { id: command.memoryId } : {}),
+            ...(content ? { content } : {}),
+            // Only defaulted for a text match, which is the case that would
+            // otherwise sweep every space this caller can read. An id needs none.
+            ...(content ? { containerTag: containerTagsFor(command)[0] } : {}),
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} forgot ${JSON.stringify({ count: result.count ?? 0, by: content ? "content" : "id" })}`);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    // The door answers with WHAT it removed, deliberately: a bare "done" is the
+    // only shape in which "forget X" quietly removing Y goes unnoticed.
+    writeLine(door.io.stdout, result.message ?? `Forgotten (${result.count ?? 0}).`);
+    for (const row of result.forgotten ?? []) {
+        const entry = row;
+        writeLine(door.io.stdout, `  ${String(entry["id"] ?? "")}  ${oneLine(entry["textPreview"])}`);
+    }
+    return 0;
+}
+/** A body from `--file`, else stdin. An interactive terminal yields nothing rather than hanging. */
+async function readBody(command, door, maxChars, what) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(door.io))
+        return { ok: true, text: "" };
+    try {
+        return {
+            ok: true,
+            text: await readPipedText(door.io.stdin, {
+                maxChars,
+                overflowMessage: `${what} is limited to ${maxChars} characters.`,
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "content_too_long",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** `[87%] ` when the row was found by meaning, empty when it was a keyword hit. */
+function similarityLabel(row) {
+    const channels = row["channels"];
+    if (Array.isArray(channels) && !channels.includes("semantic"))
+        return "";
+    const similarity = Number(row["similarity"]);
+    return Number.isFinite(similarity) && similarity >= 0 && similarity <= 1
+        ? `[${Math.round(similarity * 100)}%] `
+        : "";
+}
+/** One terminal line: newlines folded, so a long memory cannot break the listing. */
+function oneLine(value) {
+    return String(value ?? "").replace(/\s+/g, " ").trim();
+}

package/dist/commands/notes-writes.js

@@ -180,6 +180,43 @@ export async function shareNote(command, door) {
     sayUpload(door, body);
     return 0;
 }
+/**
+ * `cockpit notes place <note-id> [--apply]` — BLI-4058.
+ *
+ * Asks Tower where a note belongs and prints the reason. Without `--apply` it
+ * moves nothing: knowing where a note would go and filing it there are two
+ * different acts, and the read-only one is the default because it is the one
+ * somebody types while they are still deciding.
+ */
+export async function placeNote(command, door) {
+    const applying = command.apply === true;
+    const answer = await ask(door, {
+        path: "/api/notes/place",
+        method: "POST",
+        label: applying ? "notes place --apply" : "notes place",
+        timeoutMs: READ_DEADLINE_MS,
+        body: { note_id: command.noteId, apply: applying },
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} place answered ${JSON.stringify({
+        note_id: command.noteId ?? null,
+        ok: body.ok === true,
+        decided_by: body.decidedBy ?? null,
+        applied: body.applied === true,
+        reason: body.reason ?? null,
+    })}`);
+    if (door.json)
+        return emit(door, body, body.ok === true ? 0 : 1);
+    writeLine(door.io.stdout, body.headline ?? "Tower answered without a sentence.");
+    for (const line of body.lines ?? [])
+        writeLine(door.io.stdout, line);
+    if (body.ok === true && !applying) {
+        writeLine(door.io.stdout, "Nothing moved. Add --apply to file it there.");
+    }
+    return body.ok === true ? 0 : 1;
+}
 export async function moveNote(command, door) {
     const answer = await ask(door, {
         path: "/api/notes/move",

package/dist/commands/notes.js

@@ -27,7 +27,7 @@
  * table of contents). Every responsibility lives in a `notes-*.ts` sibling:
  *
  *  - `notes-reads.ts` — the library, shelves list, one note, your own shelf.
- *  - `notes-writes.ts` — upload, paste, share/unshare, move.
+ *  - `notes-writes.ts` — upload, paste, share/unshare, move, place.
  *  - `notes-door.ts` — the one HTTP request, and the shared answer / refusal /
  *    emit / say-* rendering both halves above call.
  *
@@ -35,9 +35,9 @@
  */
 import { loadPairedSession } from "../tower-client.js";
 import { listNotes, listShelves, showNote, showShelf } from "./notes-reads.js";
-import { uploadNotes, pasteNote, shareNote, moveNote } from "./notes-writes.js";
+import { uploadNotes, pasteNote, shareNote, moveNote, placeNote } from "./notes-writes.js";
 export { listNotes, listShelves, showNote, showShelf } from "./notes-reads.js";
-export { uploadNotes, pasteNote, shareNote, moveNote } from "./notes-writes.js";
+export { uploadNotes, pasteNote, shareNote, moveNote, placeNote } from "./notes-writes.js";
 export { ask, emit, fail, sayUpload, sayScope, errorText, TAG, } from "./notes-door.js";
 export async function runNotes(command, io) {
     const session = await loadPairedSession("notes", command.homeDir);
@@ -65,5 +65,7 @@ export async function runNotes(command, io) {
             return shareNote(command, door);
         case "move":
             return moveNote(command, door);
+        case "place":
+            return placeNote(command, door);
     }
 }

package/dist/commands/ops-render.js

@@ -101,7 +101,11 @@ options = {}) {
         // `STALE collector-fleet 11h` was already misread once (BLI-3699) as "the
         // fleet", not "one machine in it", and the name is otherwise buried in
         // `detail` below.
-        const staleName = row.verdict === "stale" && row.staleDeviceName ? ` ${dim(`(${row.staleDeviceName})`)}` : "";
+        // BLI-4057 generalised it from `stale` alone: `memory-hooks` names the
+        // machine whose hooks stopped and reads `failing`, because nothing about
+        // it is late. A row that took the trouble to name a device is naming it
+        // for the reader, whatever word it printed beside it.
+        const staleName = row.staleDeviceName ? ` ${dim(`(${row.staleDeviceName})`)}` : "";
         lines.push(`${verdict} ${id}  ${age}${staleName}  ${dim(intervalWord(row))}`);
         if (row.verdict !== "healthy") {
             // The absence of an age is explained BEFORE the detail, because it is

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

package/dist/commands/usage.js

@@ -0,0 +1,23 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+export async function runUsage(command, io) {
+    const door = await openAgentDoor("usage", command, io);
+    const query = new URLSearchParams({ since: command.since });
+    if (command.until)
+        query.set("until", command.until);
+    if (command.includeAutomated)
+        query.set("include_automated", "1");
+    const answer = await askAgentDoor(door, { path: `/api/usage/people?${query}`, method: "GET", label: "usage people", timeoutMs: 30_000 });
+    if (!answer.ok)
+        return failAgentDoor(door, "[usage]", answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, body);
+    writeLine(io.stdout, "PERSON                 TOKENS       OUTPUT       LIST EQUIVALENT  COVERAGE");
+    for (const row of body.people ?? [])
+        writeLine(io.stdout, `${(row.display_name ?? row.email ?? "Unknown").slice(0, 20).padEnd(20)}  ${String(row.tokens_total).padStart(11)}  ${String(row.output_tokens).padStart(11)}  ${`$${row.api_list_price_equivalent_usd.toFixed(2)}`.padStart(15)}  ${row.sessions_extracted}/${row.sessions_observed}`);
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, body.api_list_price_equivalent_label ?? "API list-price equivalent (not actual spend)");
+    writeLine(io.stdout, `${body.coverage?.sessions_extracted ?? 0} of ${body.coverage?.sessions_observed ?? 0} sessions extracted`);
+    return 0;
+}