viewable-one 0.0.0-stage → 0.12.2

package/glytch.mjs

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+// `glytch` - one name for the whole thing, per ruling 2 of brief 19.
+//
+// A tester used to meet three bin names, PM_SPAWN_RUNNER, Prompting Machine,
+// "the board" and `.glytch/` before running anything. This is the one
+// command. One older bin, `pm-spawn-runner`, stays as an alias so nothing
+// already installed has to move.
+//
+//   glytch init            connect this folder: register it, write .mcp.json,
+//                          register with opencode, install the login daemon,
+//                          and say what this machine has
+//   glytch login           sign in to the hosted board over OAuth, so this
+//                          machine's sessions reach it with no app open
+//   glytch logout          forget the signed-in credential
+//   glytch doctor          one list: every reason a session might not start
+//   glytch forget          unregister this folder (the daemon keeps running)
+//   glytch stop            stop the login daemon (its file stays on disk)
+//   glytch uninstall       one command: every registered project, the login
+//                          daemon, this machine's board grant, ~/.glytch
+//   glytch runner watch    the spawn runner, over every registered folder
+//   glytch mcp             retired (brief 30, W3) - prints where to go instead
+//   glytch --version
+//
+// `login` and `logout` are brief 30's (W2a): the local stdio MCP server is
+// retired, and every agent - this one included - reaches the
+// board through the hosted endpoint from here on
+// (supabase/functions/board-mcp). `login` drives the same OAuth flow the
+// endpoint already serves to claude.ai; see lib/auth.mjs.
+//
+// THE DISPATCHER DOES NOT REIMPLEMENT THE REMAINING OLD BIN. `runner` hands
+// over to spawn-runner.mjs by rewriting argv and importing it, so there is
+// one implementation and no second copy to drift. `mcp` USED TO hand over to
+// the local server the same way; that server is deleted (W3), so `mcp` now
+// just says so. The one place that is not a straight hand-over is `runner watch`
+// with no PM_BOARD_ROOT: that is the multi-root daemon (lib/multiwatch.mjs),
+// because launchd starts it standing nowhere.
+
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { heading, checkSections, summary, homeNotice, wrap, bold, colorEnabled, dim, fail, hint, ok, step, warn, warnRow } from "./lib/cli-output.mjs";
+
+import { login as hostedLogin, logout as hostedLogout } from "./lib/auth.mjs";
+import { detectAgents, detectionLines, execProbe } from "./lib/detect.mjs";
+import { allGreen, doctorRows } from "./lib/doctor.mjs";
+import { loginDaemon, noDaemonInstall } from "./lib/logindaemon.mjs";
+import { makeFileLogger } from "./lib/logs.mjs";
+import { watchRegistered } from "./lib/multiwatch.mjs";
+import { readRegistry, registryPath, removeFolder, touchRegistry } from "./lib/registry.mjs";
+import { settingsFromEnv, newRunnerId, registerAndFindProject } from "./lib/runner.mjs";
+import { syncFolder, syncRegistry } from "./lib/sync.mjs";
+import { waitForRunnerHealth, writeRunnerHealth } from "./lib/runner-health.mjs";
+import { initServiceScript, packageVersion, runUpdate } from "./lib/update.mjs";
+import { initOptions, chooseAgents, readAgentSelection, saveAgentSelection } from "./lib/agent-selection.mjs";
+import { projectMcpServerKey } from "./lib/project-mcp.mjs";
+import { AGENT_CONNECT_HINT, agentLoginStep, personalBoardToken, signInStep } from "./lib/init-connect.mjs";
+import { runUninstall, uninstallOptions } from "./lib/uninstall.mjs";
+
+// THE SAME SENTENCE `SETUP_READY` NAMES (src/folder/runnerSetup.ts). Nothing
+// under bridge/ may import from src/ (nor the reverse - see CLAUDE.md), so
+// this is a second literal rather than a shared import; both sides are
+// pinned by their own test (this package's init-connect.test.mjs and
+// src/folder/runnerSetup.test.ts) so a change to one without the other fails
+// a suite rather than silently drifting. `setupPromptText`'s stop condition
+// - "When it prints that the runner is watching this folder, say
+// 'Connected' and stop" - only ever fires if `init`'s own last lines
+// literally say this (fix 2, 2026-09-19 persona walk: they never did).
+export const RUNNER_WATCHING_LINE = "A runner is watching this folder.";
+
+const say = (line = "") => process.stdout.write(`${line}\n`);
+// BRIEF 31, MOVE 7: the FIRST line is red and the rest is left alone. An
+// error someone pastes into an issue should still be readable, so the colour
+// marks where it starts rather than painting the whole explanation.
+const die = (line) => {
+  const color = colorEnabled({ isTTY: process.stderr.isTTY });
+  const [first, ...restLines] = String(line).split("\n");
+  process.stderr.write([fail(first, { color }), ...restLines].join("\n") + "\n");
+  process.exit(1);
+};
+
+const [command, ...rest] = process.argv.slice(2);
+
+// BRIEF 31, MOVE 7: a function rather than a constant, because the command
+// names are painted and painting is a decision about THIS terminal - a pipe
+// gets plain text, the same rule every other line in this package follows.
+// One example line under the quick start, nothing else: the usage text is a
+// map, not a tutorial.
+function usage() {
+  const color = colorEnabled();
+  const b = (text) => bold(text, { color });
+  return `viewable: connect a project folder to the Viewable board.
+
+  ${b("viewable init")}        Choose one or more coding agents for this project,
+                     register their board connections, sign your computer in,
+                     connect each agent, and set your computer to keep watching
+                     without a terminal open: a LaunchAgent on macOS, a
+                     scheduled task on Windows, a systemd user unit on WSL
+                     and Linux. Safe to run twice.
+                     ${dim("Example: cd ~/Projects/your-project, then viewable init", { color })}
+
+  ${b("viewable init --agents claude,codex")}
+                     Select agents without a prompt (claude, opencode, codex).
+  ${b("viewable init --yes")}  Use saved choices, or all detected agents on first setup.
+  ${b("viewable init --no-login")}
+                     Do not sign your computer in; print the command instead.
+  ${b("viewable init --no-agent-login")}
+                     Do not run each agent's own OAuth verb; print it instead.
+
+  ${b("viewable login")}       Sign in to the hosted board over OAuth: opens a browser,
+                     you approve, the credential lands in ~/.glytch/auth.json.
+                     Every board tool your computer runs reaches the board
+                     through it from here on: no app tab, no token to paste.
+                     \`viewable init\` already signs your computer in if it is not
+                     signed in; this is the command for re-auth.
+
+  ${b("viewable logout")}      Forget the signed-in credential (~/.glytch/auth.json), the
+                     third of the three partial verbs below \`uninstall\`.
+
+  ${b("viewable update")}      Install the latest published version and restart your
+                     computer's connection. Keeps folders and sign-in.
+                     Never runs automatically. Never needs sudo.
+
+  ${b("viewable doctor")}      One list: folder registered, your computer connected and
+                     running, mirror fresh, agents found, Claude Code logged in,
+                     signed in to the board, version against npm. Exits 0
+                     when no checks fail.
+
+  ${b("viewable forget")}      Stop watching this folder, one of the three partial verbs
+                     below \`uninstall\`. Your computer keeps watching the others.
+
+  ${b("viewable stop")}        Stop watching folders. The file it runs from stays on
+                     disk, so \`viewable init\` brings it back without a reinstall.
+                     Another of the three partial verbs below \`uninstall\`.
+
+  ${b("viewable uninstall")}   Remove Viewable, its board grant and everything it wrote:
+                     one command instead of \`forget\`, \`stop\` and \`logout\` run by
+                     hand. Every registered project (or just this one, with
+                     \`--project\`), then the background watcher, the board
+                     sign-in, and ~/.glytch itself. Confirms once; \`--yes\` skips
+                     the prompt, \`--dry-run\` reports what would happen and
+                     changes nothing, \`--keep-login\` leaves your computer signed
+                     in.
+
+  ${b("viewable runner")} ...  The spawn runner (\`pm-spawn-runner\` is the same thing).
+                     \`watch\` with no PM_BOARD_ROOT watches every registered
+                     folder; with it set, it watches that one.
+
+  ${b("viewable mcp")}         Retired (brief 30): the local MCP server is gone. Run
+                     \`viewable init\` and sign in with \`viewable login\` instead:
+                     every agent reaches the board over the hosted endpoint.
+
+  ${b("viewable --version")}
+`;
+}
+
+/** Hand over to the spawn-runner bin, unchanged (its only remaining caller
+ * since `mcp` stopped handing over to the local server, W3). argv is rewritten
+ * first because the script reads process.argv at module scope, which is
+ * exactly what makes this a hand-over rather than a copy. */
+async function handOver(script, args) {
+  // THE IMPORT TAKES THE URL, THE ARGV TAKES THE PATH (2026-09-07, brief 21,
+  // the first windows-latest run). `import()` of a bare absolute path works on
+  // POSIX only by accident of `/` also starting a valid specifier: on Windows
+  // `D:\...\spawn-runner.mjs` is read as the URL scheme `d:` and the ESM
+  // loader refuses it (ERR_UNSUPPORTED_ESM_URL_SCHEME), so `glytch runner` and
+  // `glytch mcp` - both hand-overs, and between them most of what the package
+  // does - died before reaching either script. process.argv still gets the
+  // native path, because that is what both scripts read.
+  const url = new URL(`./${script}`, import.meta.url);
+  process.argv = [process.argv[0], fileURLToPath(url), ...args];
+  await import(url.href);
+}
+
+// A NUMBERED WALK SINCE BRIEF 31 (Moves 1, 2 and 7, 2026-09-12). Four steps,
+// each with its rows under it: choose the agents, connect the project, sign
+// this machine in, connect each agent. The last two used to be printed
+// instructions - "now run glytch login", "now run codex mcp login board" -
+// and printing them was four of the six steps a new machine took. They are
+// actions now; lib/init-connect.mjs is both of them, injectable end to end.
+const INIT_STEPS = 4;
+
+async function init() {
+  const options = initOptions(rest);
+  const color = colorEnabled();
+  const paint = { color };
+  const root = resolve(process.cwd());
+  const checkStartedAt = Date.now();
+  const disabled = noDaemonInstall(process.env);
+  // The service runs the script verification proved, not this process's own
+  // file, which may be a same-version copy about to be deleted (#600). No log:
+  // the PATH diagnostic is noise as init's first line.
+  const service = await initServiceScript();
+  if (!service.ok) { say(service.error); return 1; }
+  const saved = await readAgentSelection(root);
+  say(heading(`Viewable ${packageVersion()} · Project setup`, paint));
+  say(`Folder: ${root}`);
+  for (const line of homeNotice(root, homedir(), paint)) say(line);
+
+  say("");
+  say(step(1, INIT_STEPS, "Choose coding agents", paint));
+  const agents = await detectAgents();
+  const selected = await chooseAgents({ options, saved, found: agents });
+  // Save before registry registration: the daemon can notice a new folder
+  // immediately and must never race init with the legacy all-agents setup.
+  // AN EMPTY SELECTION (fix 3, 2026-09-19: `--yes` with no agent binary on
+  // PATH and no saved choice) is deliberate, not a config to persist -
+  // `saveAgentSelection([])` would write a file `readAgentSelection` then
+  // refuses to read back, since `parseAgentSelection` treats empty as
+  // invalid. Nothing is saved, so the next run tries detection again rather
+  // than remembering "no agents" forever.
+  if (selected.length) await saveAgentSelection(root, selected);
+  say(heading("Installed agents", paint));
+  for (const line of detectionLines(agents)) for (const part of wrap(line, 88, "  ")) say(part);
+  say("");
+  say(`Board connections: ${selected.length ? selected.join(", ") : "none"}`);
+  if (selected.includes("claude") && agents.claude?.found && agents.claude.loggedIn === false) {
+    say("");
+    say("Claude Code is installed but not logged in. Run `claude` once and log in,");
+    say("or a session will fail the moment it spawns.");
+  }
+
+  say("");
+  say(step(2, INIT_STEPS, "Connect this project", paint));
+  const rows = await syncFolder(root, { agents, selectedAgents: selected, exec: execProbe, ensureVersion: true, scriptPath: service.scriptPath, deferRegistry: true });
+  // NO AGENT WAS FOUND TO SELECT (fix 3): a warn row, in the same "Coding
+  // agents" group lib/doctor.mjs's own "coding agents" row lands in
+  // (checkSections' groups keys on "agents"), rather than the throw this
+  // used to be. `warn` because the runner still connects to the board fine
+  // with no agent chosen yet - `rows.every(r => r.ok)` below stays green.
+  if (!selected.length) {
+    rows.push(warnRow("agents", "coding agents", "none", "No coding agent was found on PATH. Install Claude Code, Codex or OpenCode, then run `viewable init --agents <name>` to connect it."));
+  }
+  for (const line of checkSections(rows, paint)) say(line);
+
+  say("");
+  say(step(3, INIT_STEPS, "Sign your computer in", paint));
+  // Both steps print their own rows as they settle - a row is the answer to
+  // the browser window that was just open, and it belongs under it.
+  const machine = await signInStep({ skip: !options.login, log: say, color });
+  // --no-login skips saving credentials, not use of a token already held.
+  // Read once here and reuse it for the agents' own configuration below.
+  const token = await personalBoardToken({ env: process.env });
+  // Restore deliberately before publishing a new local registry entry. A
+  // watcher must not see the folder while the server still wants it removed.
+  if (machine?.status === "ok" || token) {
+    const registered = await registerAndFindProject(root, {
+      ...settingsFromEnv(), runnerId: newRunnerId(), markExtra: () => ({ version: packageVersion() }),
+    }, { readd: true });
+    if (!registered.ok) {
+      say(registered.error);
+      // Keep ordinary setup usable offline, as before. Only a known removal
+      // requires a successful restore before publishing the local folder.
+      if (registered.readdRequired) return 1;
+    }
+  }
+  const registryRow = await syncRegistry(root);
+  rows.unshift(registryRow);
+  for (const line of checkSections([registryRow], paint)) say(line);
+
+  say("");
+  say(step(4, INIT_STEPS, "Connect each agent", paint));
+  const connected = await agentLoginStep({
+    root,
+    selected,
+    agents,
+    exec: execProbe,
+    skip: !options.agentLogin,
+    token,
+    log: say,
+    color,
+  });
+  if (!connected.length) say(dim("  No selected agent is installed on your computer.", paint));
+
+  say("");
+  say(heading("Next steps", paint));
+  const next = (text) => { for (const line of wrap(text, 88, "  ")) say(line); };
+  next("The coding agent is chosen in the app, on the board.");
+  // STEP 4 OWNS SIGN-IN (2026-09-12, reviewing the merged output). This block
+  // used to repeat lib/doctor.mjs's BOARD_SIGN_IN line for every agent step 4
+  // had not finished - which is every agent step 4 already printed the verb
+  // for, as a hint directly under its own row, one screen higher. Two
+  // spellings of the same instruction in one run is one too many, and the
+  // Claude one was long enough that it went out unwrapped. `doctor` still
+  // gives the line later, for a machine that never ran init or skipped it.
+  // Below the version floor the /mcp fallback rides step 4's own row
+  // (lib/init-connect.mjs), which is where it belongs: beside the reason.
+  if (selected.includes("codex")) {
+    next("Codex: trust this project and restart its MCP connection to load the tools.");
+    next("Codex can run board ideas and chat through the runner using your signed-in account.");
+  }
+  if (saved?.some((agent) => !selected.includes(agent))) {
+    next("Previously configured agents were left in place; init and doctor now maintain only this selection.");
+  }
+  say("");
+  // NOT "link the project folder" any more (2026-09-26): a coding run needs
+  // only the project this command just registered; linking the folder in
+  // the app shows its files on the board and nothing else.
+  say(bold("Open the board and run an idea on your coding agent.", paint));
+  say(dim("Linking this folder in the app is optional; it only shows its files on the board.", paint));
+  say("");
+  say(summary(rows, paint));
+  const allOk = rows.every((r) => r.ok);
+  // YOUR COMPUTER HAS TO BE SIGNED IN FOR A RUNNER TO WATCH (#324). A sign-in
+  // that failed, or was skipped for want of a terminal, left the daemon
+  // nothing to reach the board with, so the folder is not watched and the
+  // command exits 1. `--no-login` is a choice (a CI box): it keeps exit 0,
+  // but nothing is watching there either, so the line is not printed.
+  const signedIn = machine?.status === "ok";
+  const signInChosenOff = !options.login && machine?.status === "warn";
+  // FIX 2, THE STOP SENTENCE (2026-09-19 persona walk): `setupPromptText`
+  // (src/folder/runnerSetup.ts) tells the pasting agent to stop once init
+  // "prints that the runner is watching this folder" - a phrase this command
+  // never actually printed. It is the true last line now, and only when
+  // every row landed and your computer is signed in - a failed check is not
+  // a watching runner, and neither is a computer the board cannot reach.
+  let healthy = false;
+  if (allOk && signedIn && !disabled) {
+    // A daemon already watching this folder beats on a registry rewrite.
+    await touchRegistry().catch(() => {});
+    const result = await waitForRunnerHealth({
+      version: packageVersion(), after: checkStartedAt, root, requireStartedAfter: false,
+    });
+    healthy = result.ok;
+    if (healthy) {
+      await writeRunnerHealth({ version: packageVersion(), setupId: process.env.VIEWABLE_SETUP_ID ?? process.env.GLYTCH_SETUP_ID ?? "manual" }, process.env, "cli");
+      say(RUNNER_WATCHING_LINE);
+    } else say(result.error);
+  }
+  // FIX 1B, THE FALLBACK SENTENCE: an agent step 4 could not connect over
+  // the hosted endpoint (no terminal, and 1a either did not apply to it or
+  // did not land) gets ONE more actionable line, un-buried, after
+  // everything else - not the warn row a few screens up that a paste-and-run
+  // agent has no reason to scroll back to.
+  for (const row of connected) {
+    if (row.status === "warn" && row.text === "skipped (no terminal)") {
+      const serverKey = await projectMcpServerKey(root, row.agent);
+      say(AGENT_CONNECT_HINT[row.agent]?.replace(/viewable/g, serverKey) ?? `Sign in to Viewable from ${row.label}.`);
+    }
+  }
+  return allOk && (signInChosenOff || (signedIn && (disabled || healthy))) ? 0 : 1;
+}
+
+// THE PAINT RULE FOR EVERY COMMAND BELOW (brief 31, Move 7): a heading, then
+// the RESULT in green when it landed and yellow when nothing happened, then
+// the plain detail lines. `doctor` keeps its own shape - its rows already are
+// this pattern and they are the pattern the rest was built to match.
+async function login() {
+  const color = colorEnabled();
+  say(heading("Viewable · Sign in", { color }));
+  say(bold("Viewable needs a browser sign-in for your computer.", { color }));
+  const stored = await hostedLogin({ log: (line) => say(hint(line, { color })) });
+  say("");
+  say(ok(`Signed in to ${stored.appUrl}.`, { color }));
+  say(`Board tools on your computer now reach ${stored.mcpUrl}: no app tab, no token to paste.`);
+  say(`Saved to ~/.glytch/auth.json (mode 0600), or GLYTCH_HOME when that is set.`);
+  return 0;
+}
+
+async function logout() {
+  const color = colorEnabled();
+  say(heading("Viewable · Sign out", { color }));
+  const removed = await hostedLogout();
+  say(removed ? ok("Signed out. ~/.glytch/auth.json removed.", { color }) : warn("Not signed in, nothing to remove.", { color }));
+  return 0;
+}
+
+async function forget() {
+  const color = colorEnabled();
+  const root = resolve(process.cwd());
+  say(heading("Viewable · Forget project", { color }));
+  const { removed } = await removeFolder(root);
+  say(
+    removed
+      ? ok(`Forgot ${root}. Your computer keeps watching the ${(await readRegistry()).length} folder(s) left in ${registryPath()}.`, { color })
+      : warn(`${root} was not registered, so there is nothing to forget.`, { color }),
+  );
+  say("Nothing was deleted inside the folder: .mcp.json, .glytch/ and every session it holds are still there.");
+  return 0;
+}
+
+// WHATEVER THIS MACHINE INSTALLS (2026-09-07, brief 21 session 4): a
+// LaunchAgent on macOS, a Task Scheduler onlogon task on Windows, a systemd
+// user unit on WSL and Linux. `stop` used to name launchctl directly.
+async function stop() {
+  const color = colorEnabled();
+  const daemon = loginDaemon();
+  say(heading("Viewable · Stop runner", { color }));
+  const result = await daemon.stop();
+  if (result.unloaded) {
+    say(ok(`Unloaded the ${daemon.rowLabel} (${result.file}).`, { color }));
+    say(`The ${daemon.kind === "launchd" ? "plist" : "file"} stays on disk, so \`viewable init\` starts it again without a reinstall.`);
+    return 0;
+  }
+  say(fail(`Could not unload the ${daemon.rowLabel}: ${result.why}`, { color }));
+  say(`Expected it at ${daemon.filePath()}.`);
+  return 1;
+}
+
+// THE RULING, 2026-09-12: removing glytch, its OAuth grants and
+// everything it wrote must be one straightforward command for any user.
+// Everything the four steps do lives in lib/uninstall.mjs, injectable end to
+// end; this is the thin CLI wiring, same as `init`'s relationship to
+// lib/init-connect.mjs.
+async function uninstall() {
+  const options = uninstallOptions(rest);
+  return runUninstall({ root: resolve(process.cwd()), options, log: say });
+}
+
+async function doctor() {
+  const color = colorEnabled();
+  const root = resolve(process.cwd());
+  say(heading(`Viewable ${packageVersion()} · Health check`, { color }));
+  say(`Folder: ${root}`);
+  for (const line of homeNotice(root, homedir(), { color })) say(line);
+  const rows = await doctorRows(root);
+  for (const line of checkSections(rows, { color })) say(line);
+  say("");
+  const green = allGreen(rows);
+  say(summary(rows, { color }));
+  return green ? 0 : 1;
+}
+
+async function runner(args) {
+  // With PM_BOARD_ROOT set the behaviour is exactly today's, down to the same
+  // process: hand straight over.
+  const explicitRoot = process.env.PM_BOARD_ROOT?.trim();
+  if (args[0] !== "watch" || explicitRoot) {
+    await handOver("spawn-runner.mjs", args);
+    return null;
+  }
+  const settings = { ...settingsFromEnv(), runnerId: newRunnerId() };
+  if (!settings.enabled) {
+    die(
+      "The runner is off.\n\n" +
+        "It has no default-on path and it does not start itself: a session\n" +
+        "uses your own Claude Code or Codex plan, so an absent variable is not consent. Your computer\n" +
+        "turns it on for itself once `viewable init` sets it up; to run one by hand:\n\n" +
+        "  PM_SPAWN_RUNNER=on viewable runner watch\n",
+    );
+  }
+  const log = makeFileLogger();
+  const controller = new AbortController();
+  process.on("SIGINT", () => {
+    log("stopping. Any session already running keeps going; it is a separate process.");
+    controller.abort();
+  });
+  await watchRegistered({ settings, signal: controller.signal, log });
+  return null;
+}
+
+async function main() {
+  switch (command) {
+    case "update": {
+      const result = await runUpdate({ log: say });
+      if (!result.ok) say(result.error);
+      return result.ok ? 0 : 1;
+    }
+    case "init":
+      return init();
+    case "login":
+      return login();
+    case "logout":
+      return logout();
+    case "forget":
+      return forget();
+    case "stop":
+      return stop();
+    case "uninstall":
+      return uninstall();
+    case "doctor":
+      return doctor();
+    case "runner":
+      return runner(rest);
+    case "mcp":
+      // Retired 2026-09-11 (brief 30, W3): the local stdio MCP server this
+      // used to hand over to is deleted. Every agent reaches
+      // the board over the hosted endpoint instead.
+      say(heading("Viewable · mcp (retired)", { color: colorEnabled() }));
+      say(warn("The local board MCP server is retired.", { color: colorEnabled() }));
+      say("Run `viewable init` to connect this folder: it signs your computer in and connects each agent over the hosted endpoint from there.");
+      return 1;
+    case "--version":
+    case "-v":
+    case "version":
+      say(packageVersion());
+      return 0;
+    default:
+      say(usage());
+      return command === undefined || command === "help" || command === "--help" ? 0 : 1;
+  }
+}
+
+// These commands are done producing output the moment `main()` resolves;
+// unlike `runner` they never own the process. But anything a command ran
+// along the way can leave a stream flowing - the arrow-key picker in
+// `init` adds a `data` listener to stdin - and a flowing stream keeps the
+// event loop alive even with picker.mjs's own cleanup in place. Seen for
+// real 2026-09-12: `init` printed "All checks passed." and then hung until
+// Ctrl-C. Belt and braces: flush stdout, then exit explicitly instead of
+// trusting Node to notice there is nothing left to do.
+//
+// P4 (review 2026-09-12): this used to be a hand-maintained set of command
+// names, one more thing to remember to update for every command added
+// after it - and the picker bug above is exactly the kind of thing a
+// forgotten entry would silently bring back for a leaf command nobody
+// thought to add. Every numeric result now exits explicitly; only `runner`
+// watch's null (it owns the process) skips it, with no list to fall out of
+// date.
+main()
+  .then((code) => {
+    // null means "this command owns the process now" - the runner watches
+    // until it is stopped, and the MCP server serves stdio for ever.
+    if (typeof code !== "number") return;
+    if (code !== 0) process.exitCode = code;
+    process.stdout.write("", () => process.exit(code));
+  })
+  .catch((error) => die(error instanceof Error ? error.message : String(error)));