@bli-cockpit/cli 0.2.97 → 0.2.99

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.97",
+  "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.28",
-    "@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"
   }
 }