@bli-cockpit/cli 0.2.98 → 0.2.99

package/dist/cli.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
 import { runCockpitCli } from "./commands/public-root.js";
+import {
+  EXIT_DIED_MID_RUN,
+  installCrashGuard,
+  markCommandReturned,
+} from "./crash-guard.js";
+
+// BLI-4110. Success is EARNED, not assumed — see crash-guard.js. This
+// entry point is GENERATED, so it must mirror src/cli.ts; the packed CLI
+// is the one the fleet runs.
+process.exitCode = EXIT_DIED_MID_RUN;
+installCrashGuard();
 
 const exitCode = await runCockpitCli(process.argv.slice(2));
+
+markCommandReturned();
 process.exitCode = exitCode;

package/dist/commands/doctor.js

@@ -1,3 +1,4 @@
+import { withStage } from "../crash-guard.js";
 import { checkSingleInstallState, fixAuthState, fixRootState, readAuthState, readRootState, } from "./doctor-access.js";
 import { backfillCompletionStepState, checkBackfillState, checkDiskState, checkGcState, checkSyncState, fixBackfillState, fixDiskState, fixGcState, fixSyncState, syncBacklogDrainingVerdict, } from "./doctor-pipeline.js";
 import { checkMcpAnswersState } from "./doctor-mcp.js";
@@ -14,7 +15,7 @@ export async function runDoctorWithDeps(command, io, deps) {
     const context = { command, io, deps };
     const rows = [];
     for (const invariant of doctorInvariants()) {
-        const checked = await invariant.check(context);
+        const checked = await withStage(`doctor:check:${invariant.id}`, () => invariant.check(context));
         if (checked.status === "ok" || checked.status === "skipped") {
             rows.push(checked);
             continue;
@@ -31,7 +32,10 @@ export async function runDoctorWithDeps(command, io, deps) {
                 break;
             continue;
         }
-        const fixed = await invariant.fix(context, checked);
+        // BLI-4110: named so a crash inside a repair says WHICH repair. The
+        // 2026-09-09 incident printed a bare `read ENOTCONN` stack and the only
+        // way to place it was the log line that happened to precede it.
+        const fixed = await withStage(`doctor:fix:${invariant.id}`, () => invariant.fix(context, checked));
         rows.push({ ...fixed, fixed: fixed.status !== "fail" });
         if (fixed.hardStop)
             break;

package/dist/commands/local-args-tower-admin.js

@@ -14,9 +14,17 @@ import { isTeamDeviceRevokeReasonLabel, TEAM_DEVICE_REVOKE_REASON_LABELS, } from
 /** The shortest prefix `cockpit scout start` will resolve. Below this, ids collide. */
 export const SCOUT_MIN_PREFIX_LENGTH = 6;
 /**
- * `cockpit scout [--days <n>]` reads the board; `cockpit scout start|dismiss|undo
- * <id>` moves one card. Positional shape modelled on `autostart`: an optional
- * action word first, then what it acts on.
+ * `cockpit scout [board] [--days <n>]` reads the board; `cockpit scout
+ * start|dismiss|undo <id>` moves one card. Positional shape modelled on
+ * `autostart`: an optional action word first, then what it acts on.
+ *
+ * `board` is spellable as well as implied (BLI-4048). The parsed command has
+ * always carried `action: "board"`, the MCP twin has always been `scout_board`,
+ * and three documents printed `cockpit scout board` under a "CLI verb" heading
+ * while the parser answered "scout action must be start, dismiss, or undo" —
+ * the promise was older than the refusal. Every sibling noun (`ops status`,
+ * `slack coverage`, `notes list`) lets a person name the read it defaults to,
+ * so scout does too, and the word costs one branch.
  */
 export function parseScoutArgs(args) {
     const values = parseNamedArgs(args, {
@@ -24,7 +32,7 @@ export function parseScoutArgs(args) {
         valueFlags: ["--home", "--dashboard-url", "--days"],
     });
     if (values.positionals.length > 2) {
-        throw new Error("scout accepts at most an action (start|dismiss|undo) and one experiment id.");
+        throw new Error("scout accepts at most an action (board|start|dismiss|undo) and one experiment id.");
     }
     const [rawAction, rawRef] = values.positionals;
     const base = {
@@ -33,10 +41,13 @@ export function parseScoutArgs(args) {
         days: optionalPositiveInteger(values.flags.get("--days"), "--days"),
         json: values.booleans.has("--json"),
     };
-    if (!rawAction)
+    if (!rawAction || rawAction === "board") {
+        if (rawRef)
+            throw new Error("scout board reads the whole board; it takes no experiment id.");
         return { kind: "scout", action: "board", ...base };
+    }
     if (rawAction !== "start" && rawAction !== "dismiss" && rawAction !== "undo") {
-        throw new Error("scout action must be start, dismiss, or undo.");
+        throw new Error("scout action must be board, start, dismiss, or undo.");
     }
     const experimentRef = optionalNonEmpty(rawRef);
     if (!experimentRef) {

package/dist/commands/local-args-tower-pages.js

@@ -162,6 +162,7 @@ const NOTES_ACTIONS = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 /** Actions whose first positional is the note it acts on. */
 const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
@@ -169,6 +170,7 @@ const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
     "share",
     "unshare",
     "move",
+    "place",
 ]);
 export function parseNotesArgs(args) {
     const values = parseNamedArgs(args, {
@@ -180,6 +182,7 @@ export function parseNotesArgs(args) {
             "--exclude",
             "--to",
             "--clear-shelf",
+            "--apply",
             "--series",
             "--kind",
             "--since",
@@ -207,7 +210,7 @@ export function parseNotesArgs(args) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!NOTES_ACTIONS.has(action)) {
-        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, or move.`);
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, move, or place.`);
     }
     const rest = values.positionals.slice(first === undefined ? 0 : 1);
     const json = values.booleans.has("--json");
@@ -259,6 +262,8 @@ export function parseNotesArgs(args) {
         exclude: optionalNonEmpty(values.flags.get("--exclude")),
         ...(to ? { to } : {}),
         ...(clearShelf ? { clearShelf } : {}),
+        // BLI-4058. `place` says where a note belongs; only `--apply` moves it.
+        ...(values.booleans.has("--apply") ? { apply: true } : {}),
         series: optionalNonEmpty(values.flags.get("--series")),
         meetingKind: optionalNonEmpty(values.flags.get("--kind")),
         since: optionalNonEmpty(values.flags.get("--since")),

package/dist/commands/local-args-tower-usage.js

@@ -0,0 +1,8 @@
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export function parseUsageArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ["--since", "--until", "--include-automated", "--home", "--dashboard-url", "--json"], valueFlags: ["--since", "--until", "--home", "--dashboard-url"] });
+    const action = values.positionals[0] ?? "people";
+    if (action !== "people" || values.positionals.length > 1)
+        throw new Error("usage takes one verb: people.");
+    return { kind: "usage", action: "people", since: optionalNonEmpty(values.flags.get("--since")) ?? "30d", until: optionalNonEmpty(values.flags.get("--until")), includeAutomated: values.booleans.has("--include-automated"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), json: values.booleans.has("--json") };
+}

package/dist/commands/local-args-tower.js

@@ -35,4 +35,5 @@ export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-to
 export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
 export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
-export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseCalArgs } from "./local-args-tower-cal.js";
+export { parseUsageArgs } from "./local-args-tower-usage.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -115,6 +115,8 @@ export function parseLocalArgs(argv) {
             return parseSearchArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
+        case "usage":
+            return parseUsageArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-help-commands-tower.js

@@ -11,6 +11,15 @@
  * Every string moved verbatim. Help output is what an intern pastes back when
  * something breaks, so it is a user-visible contract like any other.
  */
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
+/**
+ * The corpora `cockpit search` can name, spelled the way `--kind` takes them.
+ * Read off `SEARCH_KINDS` rather than typed out: the help string said five for
+ * the two months `mail` and `cal` were searchable, so a person was told the
+ * door was narrower than it is (BLI-4048).
+ */
+const SEARCH_KIND_LIST = SEARCH_KINDS.join(",");
+const SEARCH_CORPORA_COUNT = SEARCH_KINDS.length;
 /** One entry per Tower noun, in the order `cockpit --help` lists them. */
 export const TOWER_COMMAND_HELP = [
     [
@@ -130,12 +139,27 @@ export const TOWER_COMMAND_HELP = [
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],
     ],
+    [
+        "usage",
+        [
+            "Usage: cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--json]",
+            "",
+            "Claude Code and Codex usage per person: sessions observed and extracted, tokens (total, output,",
+            "and the input / cache split when the row carries it), and an API list-price equivalent that is",
+            "labelled as such and is never actual spend. A super_admin sees everyone; a member sees their own row.",
+            "--since takes 7d, 30d, 90d or an ISO timestamp; --until an ISO timestamp (default now).",
+            "--include-automated adds harness, subagent and scheduled sessions, which are excluded by default.",
+            "It presses the same door as the /usage page and the usage_people MCP tool (GET /api/usage/people).",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+        ],
+    ],
     [
         "search",
         [
-            'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
+            `Usage: cockpit search "<words>" [--kind ${SEARCH_KIND_LIST}] [--limit <n>] [--json]`,
             "",
-            "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
+            `One bar over ${SEARCH_CORPORA_COUNT} corpora: documents, messages, issues, meeting notes, mail, calendar`,
+            "events and memory.",
             "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
             "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
             "",
@@ -144,12 +168,14 @@ export const TOWER_COMMAND_HELP = [
             "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
             "websearch parser, which shrugs at anything a person can type instead of raising.",
             "",
-            "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
+            `--kind narrows to one or more corpora, comma separated: ${SEARCH_KIND_LIST}.`,
+            `Omit it and all ${SEARCH_CORPORA_COUNT} are searched.`,
             "--limit caps the number of results (default 20, maximum 50).",
             "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
             "",
-            "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
-            "own database session, so a document or a channel you cannot open is not in the list.",
+            `Every result is scoped by what YOU may read: ${SEARCH_CORPORA_COUNT - 1} of the ${SEARCH_CORPORA_COUNT} corpora are`,
+            "searched on your own database session, so a document or a channel you cannot open is not in",
+            "the list; memory runs on the service role behind the memory doors' own gate.",
             "",
             "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
             "those are different facts and folding them together would let a broken search read as silence.",

package/dist/commands/local-help-commands.js

@@ -305,12 +305,14 @@ export function localSubcommandHelp(command) {
         [
             "scout",
             [
-                "Usage: cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the same Scout board the Tower page shows, in the same words: the standing",
                 "watch line, the cards waiting on a decision, and the raw signal watch underneath.",
                 "This is the board itself. To ask a QUESTION about it — what it means, whether it is",
                 "worth doing here — use `cockpit jarvis`, whose readScout tool reads the same rows.",
+                "`cockpit scout board` and a bare `cockpit scout` are the same command; the MCP twin",
+                "is `scout_board` on the bli-tower server, over the same GET /api/cockpit/scout door.",
                 "--days <n> widens or narrows the window (1 to 90; the board defaults to 14).",
                 "Reading follows the Scout page audience setting, so whoever can open /scout can run this.",
                 "start, dismiss, and undo move one card and are super_admin actions on every surface;",
@@ -461,6 +463,7 @@ export function localSubcommandHelp(command) {
                 "share <id> [--yes] — let everyone signed in read the statements that are safe to share. Asks first in a terminal; --yes is required without one, and --json implies --yes.",
                 "unshare <id> — take it back. Never asks: it only ever narrows who can read.",
                 "move <id> (--to \"<shelf>\"|--clear-shelf) — put it on a different shelf, or take the shelf off.",
+                "place <id> [--apply] — say which shelf this note belongs on and why, from the meeting it is part of, who was in the room and its own name. Moves nothing without --apply, and never overrules a shelf somebody typed.",
                 "A large note is read by a model on the server and can take a couple of minutes; the terminal says so before it waits.",
                 "--json writes one machine-readable object to stdout; every reason, receipt and progress line stays on stderr.",
                 "Sharing and moving need a signed-in session the database can see. If this deployment cannot mint one, they are refused as needs_signed_in_session rather than done with no permission check — and reads say when they came back narrower than the browser's.",

package/dist/commands/local-help.js

@@ -8,6 +8,7 @@
  * user-visible contract like any other.
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { SEARCH_KINDS } from "./local-args-tower-search.js";
 import { localSubcommandHelp } from "./local-help-commands.js";
 export const rootCommandNames = new Set([
     "onboard",
@@ -51,6 +52,7 @@ export const rootCommandNames = new Set([
     "project",
     "search",
     "release",
+    "usage",
 ]);
 export function localCommandHelp(command) {
     if (command)
@@ -72,7 +74,7 @@ export function localCommandHelp(command) {
         "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--date <YYYY-MM-DD>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--trace <id|last>] [--dashboard-url <url>] [--json [--show-approval-code]]",
         "  cockpit model [show|set <provider:model>] [--json]",
         "  cockpit models [list|show <provider:model>|compare <provider:model> <provider:model> [...]] [--highlight] [--dashboard-url <url>] [--json]",
-        "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit scout [board|start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
         "  cockpit ops [status [--job <id>] [--skips] [--memory] [--models] | recompile --person <email|name|id> [--dry-run]] [--dashboard-url <url>] [--json]",
         "  cockpit slack [coverage [--workspace bli|blue_pearl] [--stale-only] | read [--person <p>] [--channel <c>] [--query <text>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>]] [--json]",
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | cli-floor [<version>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
@@ -81,7 +83,7 @@ export function localCommandHelp(command) {
         "  cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
         "  cockpit brief status [--who <person>] [--render] [--dashboard-url <url>] [--json]",
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
-        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
+        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>|place <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--apply] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
@@ -96,8 +98,9 @@ export function localCommandHelp(command) {
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
         "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
-        "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
+        `  cockpit search "<words>" [--kind ${SEARCH_KINDS.join(",")}] [--limit <n>] [--dashboard-url <url>] [--json]`,
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+        "  cockpit usage people [--since 30d|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");

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";
@@ -42,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
@@ -77,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":
@@ -175,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) {
@@ -192,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/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.98");
+    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;
+}

package/dist/crash-guard.js

@@ -0,0 +1,167 @@
+/**
+ * A run that dies must not be able to say it worked (BLI-4110).
+ *
+ * On 2026-09-09 `cockpit do-everything` on the founder's Windows box reached
+ * "windows task repair converged", printed `Error: read ENOTCONN` from
+ * `child_process.spawn`, and **exited 0**. That is the worse half of that
+ * incident. A repair that fails loudly gets looked at; a repair that dies
+ * while claiming success stops anybody looking at all, and that machine had
+ * not delivered a session in 29 days.
+ *
+ * **What was measured** (Node 22.20, win32), because the fix depends entirely
+ * on which shapes can produce a zero:
+ *
+ * | shape | exit code |
+ * | -- | -- |
+ * | `throw` from a `setImmediate` after `process.exitCode = 0` | 1 |
+ * | an unhandled promise rejection | 1 |
+ * | an `error` event on an inherited stdio stream | 1 |
+ * | a `throw` inside a `process.on("exit")` handler | **0** |
+ *
+ * Node's own defaults are honest about every asynchronous crash. The zero can
+ * only come from the window where OUR code is the last thing holding the exit
+ * code — and `cli.ts` held it in the most optimistic way available:
+ *
+ *     const exitCode = await runCockpitCli(argv);
+ *     process.exitCode = exitCode;
+ *
+ * `process.exitCode` starts at 0. So *anything* that prevents that assignment
+ * from being reached, or that runs after it, reports success by default.
+ * Success was the resting state and had to be disproved.
+ *
+ * **The fix inverts that: success must be earned.** The entry point sets a
+ * non-zero code BEFORE doing any work, and only a command that actually
+ * returned is allowed to lower it. Nothing here has to enumerate the ways a
+ * run can die, which matters because the specific `read ENOTCONN` path has not
+ * been reproduced off that machine — see `docs/runbooks/` and the ticket. A
+ * guard that depends on correctly predicting the crash is a guard that works
+ * on the crashes you already knew about.
+ *
+ * The guard only ever RAISES a zero. It can never turn a real failure into a
+ * success, and it never overwrites a code a command chose.
+ */
+/**
+ * Distinct from 1 on purpose. `1` is "this ran and the answer is no"; 70 is
+ * "this never finished, so there is no answer". A scheduled task's log can
+ * then tell a failed repair from an abandoned one without parsing prose.
+ */
+export const EXIT_DIED_MID_RUN = 70;
+/** Stages nest — the subcommand, then the invariant running inside it. */
+const openStages = [];
+let commandReturned = false;
+let installed = false;
+export function beginStage(stage) {
+    openStages.push(stage);
+}
+/**
+ * Closes the innermost stage. Takes the name so an unbalanced pair is visible:
+ * closing a stage that is not the open one would make a later crash blame the
+ * wrong stage, which is worse than naming none.
+ */
+export function endStage(stage) {
+    const top = openStages[openStages.length - 1];
+    if (top !== stage) {
+        console.error("[cockpit-cli] stage mismatch", JSON.stringify({ reason: "stage_mismatch", closing: stage, open: top ?? null }));
+        return;
+    }
+    openStages.pop();
+}
+/** The innermost stage still running, or null. Naming only — never a verdict. */
+export function openStage() {
+    return openStages[openStages.length - 1] ?? null;
+}
+/**
+ * Called by the entry point when the command function actually returned a
+ * code. This is the ONE fact the guard trusts: not "did a stage close", not
+ * "were there failures", but "did control come back".
+ */
+export function markCommandReturned() {
+    commandReturned = true;
+}
+/** Test seam — the guard is process-global, so a suite must reset it. */
+export function resetCrashGuardForTest() {
+    openStages.length = 0;
+    commandReturned = false;
+    installed = false;
+}
+/**
+ * Error facts that are safe to log: names and codes, never a message. An error
+ * message routinely carries a path under somebody's home directory, and this
+ * line is read off a fleet-visible log.
+ */
+function describeCrash(error) {
+    if (!(error instanceof Error)) {
+        return { error_name: typeof error, error_code: null, error_syscall: null };
+    }
+    const record = error;
+    return {
+        error_name: error.name,
+        error_code: record.code ?? null,
+        error_syscall: record.syscall ?? null,
+    };
+}
+/**
+ * Installs the guard. Idempotent — the entry point is also imported by tests.
+ *
+ * `uncaughtExceptionMonitor`, not `uncaughtException`, and the difference is
+ * the whole safety argument: the monitor OBSERVES and lets Node's default
+ * handling proceed, so the stack trace still prints and the process still
+ * dies. Registering `uncaughtException` would SUPPRESS the default, leaving
+ * this guard to re-implement crashing correctly — which is precisely how a
+ * safety net becomes the thing that swallows the error. Since Node 15 an
+ * unhandled rejection is raised as an uncaught exception by default, so the
+ * monitor names those too without a second listener.
+ */
+export function installCrashGuard(options = {}) {
+    const target = options.process ?? process;
+    if (installed)
+        return;
+    installed = true;
+    target.on("uncaughtExceptionMonitor", (error) => {
+        console.error("[cockpit-cli] crashed", JSON.stringify({
+            reason: "uncaught_exception",
+            stage: openStage(),
+            ...describeCrash(error),
+        }));
+    });
+    target.on("exit", () => {
+        if (commandReturned)
+            return;
+        // `EXIT_DIED_MID_RUN` has to be in this set, and leaving it out made this
+        // whole branch dead code in the shipped binary: `cli.ts` presets 70 BEFORE
+        // any work, so by the time `exit` fires the code is 70 (quiet death) or 1
+        // (Node overwrote it on an uncaught exception) and never 0. The exit CODE
+        // was right; the line that names the stage never printed once. Caught in
+        // review by transcribing this file plus `cli.ts` and running every death
+        // shape — not by the unit test, which passed only because it hand-set 0,
+        // a state the entry point cannot reach.
+        if (target.exitCode !== 0 &&
+            target.exitCode !== undefined &&
+            target.exitCode !== EXIT_DIED_MID_RUN) {
+            return;
+        }
+        console.error("[cockpit-cli] died mid-run", JSON.stringify({
+            reason: "died_mid_run",
+            stage: openStage(),
+            corrected_exit_code: EXIT_DIED_MID_RUN,
+        }));
+        target.exitCode = EXIT_DIED_MID_RUN;
+    });
+}
+/**
+ * Runs `body` as a named stage so a crash inside it can say where it was.
+ *
+ * The `finally` closes the stage on both paths on purpose: a stage that THREW
+ * is finished, and its exception is already travelling to somebody who will
+ * set a real exit code. Naming is all this does — the exit-code decision rests
+ * on `markCommandReturned`, never on whether a stage happens to be open.
+ */
+export async function withStage(stage, body) {
+    beginStage(stage);
+    try {
+        return await body();
+    }
+    finally {
+        endStage(stage);
+    }
+}

package/dist/process-runner.js

@@ -49,6 +49,34 @@ export function createCapturedExecRunner(options = {}) {
         });
     });
 }
+/**
+ * Which stdio a re-exec may inherit (BLI-4110).
+ *
+ * `stdio: "inherit"` hands the child all three of the parent's handles. Under
+ * the Windows Task Scheduler — and any other non-interactive host — the
+ * parent's stdin is not a console: it can be a pipe nobody is writing to, or a
+ * socket that was never connected, and reading it raises `read ENOTCONN` from
+ * inside `child_process.spawn`. That is the error `cockpit do-everything`
+ * printed on the founder's box on 2026-09-09, from `reexecDoctor`, in a
+ * non-interactive shell.
+ *
+ * **stdout and stderr are still inherited, always.** They are what makes a
+ * scheduled run's output land in the log a person later reads, and dropping
+ * them to fix stdin would trade a crash for a silence — which is the failure
+ * this whole ticket is about.
+ *
+ * **stdin is inherited only when there is a console to read from.** A
+ * re-execed `do-everything` under a scheduler has nothing to type at it; the
+ * handle was pure liability. `"ignore"` gives the child a real, closed stdin
+ * rather than a broken one, so a child that does read it gets EOF instead of
+ * an error.
+ *
+ * Pure and exported so both host families are testable without a real TTY,
+ * per the supported-fleet contract in AGENTS.md.
+ */
+export function interactiveStdio(input) {
+    return [input.stdinIsTty === true ? "inherit" : "ignore", "inherit", "inherit"];
+}
 export function createInteractiveExecRunner(options = {}) {
     return (command, args, runOptions) => new Promise((resolve) => {
         const env = runOptions?.env ?? options.env ?? process.env;
@@ -56,8 +84,9 @@ export function createInteractiveExecRunner(options = {}) {
             platform: options.platform,
             env,
         });
+        const stdio = interactiveStdio({ stdinIsTty: process.stdin.isTTY });
         const child = spawn(invocation.command, invocation.args, {
-            stdio: "inherit",
+            stdio,
             env,
             windowsVerbatimArguments: invocation.windowsVerbatimArguments,
         });
@@ -66,6 +95,15 @@ export function createInteractiveExecRunner(options = {}) {
             if (settled)
                 return;
             settled = true;
+            // Named, because a spawn that never started and a child that ran and
+            // failed both used to arrive here as a bare code 1. Metadata only.
+            const record = error;
+            console.error("[process-runner] spawn failed", JSON.stringify({
+                reason: "spawn_failed",
+                error_code: record.code ?? null,
+                error_syscall: record.syscall ?? null,
+                stdin: stdio[0],
+            }));
             resolve({ code: 1, stdout: "", stderr: error.message });
         });
         child.on("close", (code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.98",
+  "version": "0.2.99",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,11 +24,11 @@
     "pretypecheck": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "node ../../scripts/build-workspace-dep.mjs @bli-cockpit/cli",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.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"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.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.25",
-    "@bli-cockpit/mcp": "0.1.29",
-    "@bli-cockpit/telemetry-core": "0.1.42"
+    "@bli-cockpit/memory-mcp": "0.1.26",
+    "@bli-cockpit/mcp": "0.1.30",
+    "@bli-cockpit/telemetry-core": "0.1.43"
   }
 }