@bli-cockpit/cli 0.2.98 → 0.2.100

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,8 @@ import { runCal } from "./cal.js";
 import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
+import { runCareers } from "./careers.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 +80,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 +181,10 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runSearch(command, io);
             case "release":
                 return await runRelease(command, io);
+            case "careers":
+                return await runCareers(command, io);
+            case "usage":
+                return await runUsage(command, io);
         }
     }
     catch (error) {
@@ -192,6 +202,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-file.js

@@ -34,6 +34,10 @@ import { errorMessage } from "./cli-io.js";
  * courtesy check to avoid uploading something the server is certain to refuse,
  * not a second source of truth.
  */
+export function noteAudioMime(name) {
+    const mime = { mp3: "audio/mpeg", m4a: "audio/mp4", wav: "audio/wav", webm: "audio/webm", ogg: "audio/ogg" };
+    return mime[name.split(".").at(-1)?.toLowerCase() ?? ""];
+}
 export const NOTE_FILE_MAX_BYTES = 20 * 1024 * 1024;
 /**
  * Above this, the terminal says it is working before it starts. The route's own
@@ -52,7 +56,7 @@ export function noteFileRefusalSentence(refusal, filePath) {
         case "file_empty":
             return `There is nothing in that file: ${filePath}`;
         case "file_too_big":
-            return "That file is too big to put in as a note — keep it under 20 MB.";
+            return "That file is too big. Audio is limited to 4 MB; other notes to 20 MB.";
         case "looks_like_a_key_file":
             // The same rule the server's gate applies, said the same way: the name is
             // all it takes to decide, and looking inside to be sure would already be
@@ -88,6 +92,9 @@ export async function readNoteFile(filePath) {
     }
     if (size === 0)
         return { ok: false, refusal: "file_empty", detail: "byte_size_0" };
+    if (noteAudioMime(fileName) && size > 4_000_000) {
+        return { ok: false, refusal: "file_too_big", detail: "file_too_large: audio limit is 4 MB (4,000,000 bytes)" };
+    }
     if (size > NOTE_FILE_MAX_BYTES) {
         return { ok: false, refusal: "file_too_big", detail: `byte_size_${size}` };
     }

package/dist/commands/notes-folders.js

@@ -0,0 +1,35 @@
+import { writeLine } from "./cli-io.js";
+import { ask, emit, fail, READ_DEADLINE_MS } from "./notes-door.js";
+export async function runFolderCommand(command, door) {
+    const path = command.folder?.split("/").map(part => part.trim()).join("/");
+    const answer = await ask(door, {
+        path: "/api/notes/folders", method: command.action === "mkdir" ? "POST" : "GET",
+        label: `notes ${command.action}`, timeoutMs: READ_DEADLINE_MS,
+        ...(command.action === "mkdir" ? { body: { path } } : {}),
+    });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    if (command.action === "rmdir" || command.action === "rename") {
+        const folder = body.folders?.find(folder => folder.path === path);
+        if (!folder)
+            return fail(door, "folder_not_found", "That folder could not be found.");
+        const removed = await ask(door, { path: `/api/notes/folders/${encodeURIComponent(folder.id)}`, method: command.action === "rename" ? "PATCH" : "DELETE", label: `notes ${command.action}`, timeoutMs: READ_DEADLINE_MS, ...(command.action === "rename" ? { body: { name: command.name } } : {}) });
+        if (!removed.ok)
+            return fail(door, removed.reason, removed.detail);
+        if (door.json)
+            return emit(door, removed.body);
+        writeLine(door.io.stdout, removed.body.headline);
+        return 0;
+    }
+    if (door.json)
+        return emit(door, body);
+    if (command.action === "mkdir")
+        writeLine(door.io.stdout, body.headline ?? "Folder ready.");
+    else
+        for (const folder of body.folders ?? []) {
+            const label = command.tree ? `${"  ".repeat(folder.path.split("/").length - 1)}${folder.name}` : folder.path;
+            writeLine(door.io.stdout, `${label} (${folder.note_count})`);
+        }
+    return 0;
+}

package/dist/commands/notes-writes.js

@@ -4,7 +4,7 @@
  * `notes.ts`, named in its header.
  */
 import { isInteractiveStdin, readLine, readPipedText, writeLine, yesByDefault } from "./cli-io.js";
-import { NOTE_SLOW_UPLOAD_BYTES, decodeTextBytes, noteFileRefusalSentence, readNoteFile, } from "./notes-file.js";
+import { NOTE_SLOW_UPLOAD_BYTES, noteAudioMime, decodeTextBytes, noteFileRefusalSentence, readNoteFile, } from "./notes-file.js";
 import { ask, emit, fail, sayUpload, errorText, TAG, READ_DEADLINE_MS } from "./notes-door.js";
 /**
  * The upload route's own ceiling is `maxDuration = 300` — reading a note is one
@@ -36,9 +36,11 @@ export async function uploadNotes(command, door) {
             writeLine(door.io.stderr, `Reading ${read.fileName} (${Math.round(read.bytes.byteLength / 1024)} KB). This can take a couple of minutes.`);
         }
         const form = new FormData();
-        form.set("file", new File([new Uint8Array(read.bytes)], read.fileName));
+        form.set("file", new File([new Uint8Array(read.bytes)], read.fileName, { type: noteAudioMime(read.fileName) ?? "" }));
         if (command.exclude)
             form.set("exclusions", command.exclude);
+        if (command.folder)
+            form.set("folder_path", command.folder);
         const answer = await ask(door, {
             path: "/api/notes/upload",
             method: "POST",
@@ -55,7 +57,14 @@ export async function uploadNotes(command, door) {
             continue;
         }
         const body = answer.body;
-        results.push({ path: filePath, ok: body.stored === true, body });
+        if (command.wait && body.noteId && body.transcription?.status === "pending") {
+            body.transcription = await waitForTranscription(door, body.noteId);
+        }
+        if (body.transcription?.status === "failed")
+            worstExit = 1;
+        if (!door.json && body.transcription)
+            writeLine(door.io.stdout, `${body.noteId}: transcription ${body.transcription.status}${body.transcription.reason ? ": " + body.transcription.reason : ""}`);
+        results.push({ path: filePath, ok: body.stored === true && body.transcription?.status !== "failed", body });
         if (body.stored !== true)
             worstExit = 1;
         if (!door.json)
@@ -114,6 +123,8 @@ export async function pasteNote(command, door) {
         form.set("name", command.name);
     if (command.exclude)
         form.set("exclusions", command.exclude);
+    if (command.folder)
+        form.set("folder_path", command.folder);
     // Bytes, not `.length` (BLI-3482). `NOTE_SLOW_UPLOAD_BYTES` is a BYTE
     // threshold, and the file path above already compares `bytes.byteLength`
     // against it; `text.length` counts UTF-16 units, so a note in any non-Latin
@@ -180,6 +191,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",
@@ -188,7 +236,10 @@ export async function moveNote(command, door) {
         timeoutMs: READ_DEADLINE_MS,
         // `--clear-shelf` sends the empty string, which is what the browser's own
         // move box sends when a person empties it.
-        body: { note_id: command.noteId, category: command.clearShelf ? "" : command.to },
+        body: { note_id: command.noteId,
+            ...(command.folder ? { folder_path: command.folder } : {}),
+            ...(command.to || command.clearShelf ? { category: command.clearShelf ? "" : command.to } : {}),
+        },
     });
     if (!answer.ok)
         return fail(door, answer.reason, answer.detail);
@@ -205,4 +256,23 @@ export async function moveNote(command, door) {
     for (const line of body.lines ?? [])
         writeLine(door.io.stdout, line);
     return body.ok === true ? 0 : 1;
+}
+/** Bounded polling of the same note read used by the browser and MCP. */
+async function waitForTranscription(door, noteId) {
+    const deadline = Date.now() + 330_000;
+    for (let attempt = 0; attempt < 110 && Date.now() < deadline; attempt++) {
+        const answer = await ask(door, { path: `/api/notes/library/${encodeURIComponent(noteId)}`,
+            method: "GET", label: "notes transcription", timeoutMs: Math.min(10_000, deadline - Date.now()) });
+        if (!answer.ok)
+            return { status: "failed", reason: answer.reason };
+        const status = answer.body.audio?.transcription_status;
+        if (status === "done")
+            return { status: "done" };
+        if (status?.startsWith("failed:"))
+            return { status: "failed", reason: status.slice(7) };
+        if (status !== "pending")
+            return { status: "failed", reason: "transcription_status_unavailable" };
+        await new Promise((resolve) => setTimeout(resolve, Math.min(3000, Math.max(0, deadline - Date.now()))));
+    }
+    return { status: "failed", reason: "transcription_wait_timeout" };
 }

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,10 @@
  */
 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";
+import { runFolderCommand } from "./notes-folders.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);
@@ -48,6 +49,11 @@ export async function runNotes(command, io) {
         json: command.json,
     };
     switch (command.action) {
+        case "folders":
+        case "mkdir":
+        case "rmdir":
+        case "rename":
+            return runFolderCommand(command, door);
         case "list":
             return listNotes(command, door);
         case "shelves":
@@ -65,5 +71,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.100");
     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);
+    }
+}