@modelstatus/cli 0.1.86 → 0.1.87

package/src/sources/index.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { compilePatterns } from "../detect/core.js";
 import { filesystemSource } from "./filesystem.js";
 import { envSource } from "./env.js";
@@ -53,6 +54,13 @@ export function getSource(id) {
   return SOURCES.find((s) => s.id === id) ?? null;
 }
 
+/** The requested ids that match NO registered source (typos). Callers treat
+ * these as an invocation error — `mm ci --sources filesysten` must fail loudly,
+ * never scan nothing and report a green build. */
+export function unknownSourceIds(ids = []) {
+  return (ids || []).filter((id) => !getSource(id));
+}
+
 /** A live integration runs only when enabled in integrations.json OR explicitly
  * named (so a one-off `--sources vercel` works without toggling it on first).
  * The 6 original sources omit `integration` → this never gates them. */
@@ -93,15 +101,31 @@ export async function availability(sourceIds, opts = {}, explicit = new Set()) {
 /** Run a set of sources, returning a flat, de-duplicated Candidate[]. Stays on
  * the cheap path: uses available() (PATH check), never authState() (spawn).
  * `explicit` is the set of ids the caller named verbatim — naming a live
- * integration there overrides the enabled-gate. */
+ * integration there overrides the enabled-gate.
+ *
+ * The returned array also carries a non-enumerable `failures` property:
+ * [{ source, cmd, code, signal, message }] — one entry per vendor-CLI run that
+ * failed during collection (expired creds, unreachable cluster, timeout kill).
+ * Non-enumerable so every existing Candidate[] consumer (map/filter/JSON) is
+ * byte-identical; callers that care (scan/status/ci) read `result.failures`
+ * so an auth failure can never masquerade as a clean scan. */
 export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(), onProgress = null) {
   const compiled = compilePatterns(patterns);
   const ids = sourceIds && sourceIds.length ? sourceIds : ["filesystem"];
   const seen = new Set();
+  const seenFileRefs = new Set();
   const out = [];
+  const failures = [];
+  const root = path.resolve(opts?.root || ".");
   for (const id of ids) {
     const src = getSource(id);
-    if (!src) continue;
+    if (!src) {
+      // Belt-and-braces: callers validate ids up front via unknownSourceIds(),
+      // but a typo that still reaches the collect layer must never be a silent
+      // no-op scan (the old behavior turned `--sources filesysten` green).
+      process.stderr.write(`! unknown source "${id}" — skipped\n`);
+      continue;
+    }
     // Live-integration gate: skip a disabled integration unless explicitly named.
     if (!integrationAllowed(src, id, explicit)) continue;
     if (!(await src.available(opts))) continue;
@@ -110,13 +134,31 @@ export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(
     // and Vercel's authoritative deploy target still wins inside its own collect.
     // onProgress (optional) lets a caller render a live file counter — only the
     // filesystem source emits progress; the rest ignore the extra opt.
-    const srcOpts = src.integration ? { ...opts, env: opts.env || getEnvTag(id), onProgress } : { ...opts, onProgress };
+    // onSourceFailure is the per-source status channel each CLI-backed source
+    // reports failed vendor runs through (see makeCliFailureReporter in shell.js).
+    const srcOpts = {
+      ...(src.integration ? { ...opts, env: opts.env || getEnvTag(id) } : opts),
+      onProgress,
+      onSourceFailure: (f) => failures.push(f),
+    };
     for (const c of await src.collect(srcOpts, compiled)) {
       const key = `${c.model_string}|${c.location_label}`;
       if (seen.has(key)) continue;
       seen.add(key);
+      // Two sources can cover the SAME file line under different locator schemes
+      // (filesystem "supabase/functions/x.ts:1" vs supabase-edge
+      // "supabase-edge://…/x.ts#L1"; likewise .github/workflows). Dedupe by
+      // (model, resolved file, line) — the first source to emit the ref wins.
+      const file = c.file_path || (c.source_type === "file" ? c.source_path : null);
+      if (file && c.source_line != null) {
+        const fkey = `${c.model_string}|${path.resolve(root, file)}:${c.source_line}`;
+        if (seenFileRefs.has(fkey)) continue;
+        seenFileRefs.add(fkey);
+      }
+      delete c.file_path; // internal dedupe hint only — not part of the Candidate shape
       out.push(c);
     }
   }
+  Object.defineProperty(out, "failures", { value: failures, enumerable: false });
   return out;
 }

package/src/sources/k8s.js

@@ -1,4 +1,4 @@
-import { hasCmd, run } from "./shell.js";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { scanConfigEntries, entriesFromKV } from "./configscan.js";
 
 const b64decode = (s) => {
@@ -45,7 +45,11 @@ export const k8sSource = {
     const ctx = opts?.kubeContext ? ["--context", opts.kubeContext] : [];
     const nsArgs = opts?.namespace ? ["-n", opts.namespace] : ["-A"];
     const res = await run("kubectl", ["get", "secrets,configmaps", ...nsArgs, "-o", "json", ...ctx]);
-    if (!res.ok) return [];
+    if (!res.ok) {
+      // Unreachable cluster / expired context must be LOUD, never "no configmaps".
+      makeCliFailureReporter("k8s", "kubectl", opts)(res);
+      return [];
+    }
     return scanConfigEntries(extractK8sEntries(res.stdout), compiled, { sourceType: "k8s" });
   },
 };

package/src/sources/shell.js

@@ -27,23 +27,101 @@ export function fixtureName(cmd, args = []) {
   );
 }
 
-/** Is `name` an executable on PATH? Pure PATH scan — no shell, no spawn. */
-export function hasCmd(name) {
-  const PATH = process.env.PATH || "";
-  for (const dir of PATH.split(path.delimiter)) {
+/** Windows executable extensions when PATHEXT is unset (matches cmd.exe's own default core). */
+const WIN_DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+/** Resolve `name` to its full path on PATH, or null. POSIX: the original
+ * accessSync(X_OK) probe, unchanged. win32: where.exe semantics — executables
+ * carry extensions (aws.exe, vercel.cmd), so probe name+ext for each PATHEXT
+ * extension. The BARE extensionless name is deliberately NOT probed on win32:
+ * Windows can't spawn it (the npm sh-shim named "vercel" must not shadow
+ * "vercel.cmd"), and X_OK degrades to F_OK there anyway — plain existence is
+ * the probe. `platform` / `env` / `probe` are injectable so the win32 logic is
+ * unit-testable off-Windows. */
+export function whichCmd(name, { platform = process.platform, env = process.env, probe } = {}) {
+  const win = platform === "win32";
+  const joiner = win ? path.win32 : path;
+  const canUse =
+    probe ||
+    ((p) => {
+      try {
+        fs.accessSync(p, win ? fs.constants.F_OK : fs.constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  let candidates = [name];
+  if (win) {
+    const exts = (env.PATHEXT || WIN_DEFAULT_PATHEXT)
+      .split(";")
+      .map((e) => e.trim())
+      .filter((e) => e.startsWith("."));
+    const lower = name.toLowerCase();
+    const alreadyHasExt = exts.some((e) => lower.endsWith(e.toLowerCase()));
+    candidates = alreadyHasExt ? [name] : exts.map((e) => name + e);
+  }
+  for (const dir of String(env.PATH || "").split(win ? ";" : path.delimiter)) {
     if (!dir) continue;
-    try {
-      fs.accessSync(path.join(dir, name), fs.constants.X_OK);
-      return true;
-    } catch {
-      /* keep looking */
+    for (const cand of candidates) {
+      const full = joiner.join(dir, cand);
+      if (canUse(full)) return full;
     }
   }
-  return false;
+  return null;
+}
+
+/** Is `name` an executable on PATH? Pure PATH scan — no shell, no spawn. */
+export function hasCmd(name) {
+  return whichCmd(name) != null;
+}
+
+/** First meaningful line of a failed run's output (stderr → stdout → spawn error). */
+function firstFailLine(res) {
+  for (const blob of [res?.stderr, res?.stdout, res?.errMessage]) {
+    const line = String(blob || "").split(/\r?\n/).find((l) => l.trim());
+    if (line) return line.trim().slice(0, 200);
+  }
+  return "no output";
+}
+
+/** How the run died, for humans: "exit 1", "signal SIGTERM" (timeout kill), or a
+ * spawn-error code like "ENOENT". */
+function exitLabel(res) {
+  if (res?.signal) return `signal ${res.signal}`;
+  if (typeof res?.code === "number") return `exit ${res.code}`;
+  return String(res?.code || "spawn error");
+}
+
+/** Per-source vendor-CLI failure reporter: a failed spawn/exit (expired creds,
+ * unreachable cluster, unlinked project, timeout/maxBuffer kill) must NEVER read
+ * as a clean scan. Writes ONE terse stderr line per distinct failure mode —
+ * "! vercel source: vercel CLI failed (exit 1): <first stderr line>" — so a
+ * per-item loop (one aws call per secret) can't flood, and forwards EVERY
+ * failure to opts.onSourceFailure (collectFrom's per-source status channel).
+ * A missing test fixture (run() under MM_SOURCE_FIXTURE) stays quiet — it
+ * deliberately degrades like a missing CLI, which available() would have gated
+ * out before any spawn. */
+export function makeCliFailureReporter(sourceId, bin, opts) {
+  const seen = new Set();
+  return (res) => {
+    if (process.env.MM_SOURCE_FIXTURE && res?.stderr === "no fixture") return;
+    const label = exitLabel(res);
+    const message = firstFailLine(res);
+    opts?.onSourceFailure?.({ source: sourceId, cmd: bin, code: res?.code ?? null, signal: res?.signal ?? null, message });
+    if (seen.has(label)) return;
+    seen.add(label);
+    process.stderr.write(`! ${sourceId} source: ${bin} CLI failed (${label}): ${message}\n`);
+  };
 }
 
 /** Run a command WITHOUT a shell (execFile → no injection). Read-only by
- * convention. Never throws; resolves { ok, stdout, stderr, code }.
+ * convention. Never throws; resolves { ok, stdout, stderr, code, signal?,
+ * errMessage? } — code is the exit code (a string like "ENOENT" for spawn
+ * errors, null when killed by signal), signal/errMessage carry the how/why of
+ * a non-exit death so failures can be reported precisely. `cwd` (optional)
+ * runs the tool in a specific directory (vercel resolves its project link
+ * from the cwd, so the scan root — not our process cwd — must be it).
  *
  * TEST-ONLY: when process.env.MM_SOURCE_FIXTURE is set (a directory of canned
  * vendor outputs), this REPLAYS a fixture file instead of spawning — so the full
@@ -52,7 +130,7 @@ export function hasCmd(name) {
  * when the env var is unset (prod default), and a missing fixture degrades exactly
  * like a missing CLI ({ok:false, code:127}). It is the symmetric twin of the
  * LLMSTATUS_INTEGRATIONS_FILE / LLMSTATUS_IGNORE_FILE test redirects. */
-export function run(cmd, args, { timeout = 25000, input, maxBuffer = 48 * 1024 * 1024 } = {}) {
+export function run(cmd, args, { timeout = 25000, input, maxBuffer = 48 * 1024 * 1024, cwd } = {}) {
   const fixtureDir = process.env.MM_SOURCE_FIXTURE;
   if (fixtureDir) {
     try {
@@ -62,9 +140,43 @@ export function run(cmd, args, { timeout = 25000, input, maxBuffer = 48 * 1024 *
       return Promise.resolve({ ok: false, stdout: "", stderr: "no fixture", code: 127 });
     }
   }
+  // win32: execFile can spawn .exe/.com directly but NOT .cmd/.bat shims (EINVAL
+  // since the CVE-2024-27980 hardening). Resolve the PATH match up front: real
+  // executables get their absolute path; .cmd/.bat shims (npm-installed vercel/
+  // supabase) go through cmd.exe via shell:true with the path pre-quoted. Args
+  // here are programmatic (subcommands, flags, slugs) — anything shell-unsafe is
+  // refused loudly rather than handed to cmd.exe unescaped.
+  let file = cmd;
+  let shell = false;
+  if (process.platform === "win32" && !/[\\/]/.test(cmd)) {
+    const resolved = whichCmd(cmd);
+    if (resolved) {
+      const ext = path.win32.extname(resolved).toLowerCase();
+      if (ext === ".cmd" || ext === ".bat") {
+        const unsafe = (args || []).find((a) => !/^[A-Za-z0-9_\-./:=@,+]*$/.test(String(a)));
+        if (unsafe !== undefined) {
+          return Promise.resolve({
+            ok: false, stdout: "", code: "EINVAL", signal: null,
+            stderr: `refusing to pass a shell-unsafe argument to a .cmd shim: ${String(unsafe).slice(0, 40)}`,
+          });
+        }
+        file = `"${resolved}"`;
+        shell = true;
+      } else {
+        file = resolved;
+      }
+    }
+  }
   return new Promise((resolve) => {
-    const child = execFile(cmd, args, { timeout, maxBuffer }, (err, stdout, stderr) => {
-      resolve({ ok: !err, stdout: stdout || "", stderr: stderr || "", code: err?.code ?? 0 });
+    const child = execFile(file, args, { timeout, maxBuffer, cwd, shell }, (err, stdout, stderr) => {
+      resolve({
+        ok: !err,
+        stdout: stdout || "",
+        stderr: stderr || "",
+        code: err ? (err.code ?? null) : 0,
+        signal: err?.signal ?? null,
+        errMessage: err ? String(err.message || "").split("\n")[0] : undefined,
+      });
     });
     if (input != null) {
       try {

package/src/sources/sql.js

@@ -1,4 +1,4 @@
-import { hasCmd, run } from "./shell.js";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { detectInLine } from "../detect/core.js";
 import { redactValue } from "../redact.js";
 
@@ -21,7 +21,11 @@ export const sqlSource = {
     // Force read-only so a bad table/DSN can never mutate anything.
     const sql = `SET default_transaction_read_only=on; SELECT * FROM ${table};`;
     const res = await run("psql", [opts.db, "-A", "-t", "-c", sql]);
-    if (!res.ok) return [];
+    if (!res.ok) {
+      // A bad DSN / unreachable DB must be LOUD, never a silent "no rows".
+      makeCliFailureReporter("sql", "psql", opts)(res);
+      return [];
+    }
 
     const out = [];
     const seen = new Set();

package/src/sources/supabase-edge.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { hasCmd, run } from "./shell.js";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { detectInLine } from "../detect/core.js";
 import { redactValue } from "../redact.js";
 import { scanConfigEntries, entriesFromKV } from "./configscan.js";
@@ -68,8 +68,11 @@ export function parseFunctionList(stdout) {
  * locatorBase + compiled (+ optional env override), returns candidates with a
  * #L<n> locator and a redacted, 160-capped snippet. detectInLine returns a Set,
  * iterated with for…of (not .length). The snippet is redactValue'd FIRST then
- * sliced so a secret straddling the 160-char boundary can't leak a half-token. */
-export function scanFunctionBody(text, locatorBase, compiled, env) {
+ * sliced so a secret straddling the 160-char boundary can't leak a half-token.
+ * `filePath` (optional, root-relative) stamps file_path on each candidate — the
+ * collectFrom dedupe hint so a body the filesystem source ALSO walked isn't
+ * double-counted (stripped before candidates leave collectFrom). */
+export function scanFunctionBody(text, locatorBase, compiled, env, filePath) {
   const out = [];
   const seen = new Set();
   String(text || "")
@@ -88,6 +91,7 @@ export function scanFunctionBody(text, locatorBase, compiled, env) {
           source_line: i + 1,
           environment: env || "unknown",
           snippet: redactValue(line.trim()).slice(0, 160),
+          ...(filePath ? { file_path: filePath } : {}),
         });
       }
     });
@@ -134,6 +138,7 @@ export const supabaseEdgeSource = {
   },
   async collect(opts, compiled) {
     const ref = opts?.supabaseProjectRef || "local";
+    const fail = makeCliFailureReporter("supabase-edge", "supabase", opts);
     const out = [];
 
     // (a) Secret NAMES only (never values). Requires the CLI; skipped gracefully
@@ -143,7 +148,8 @@ export const supabaseEdgeSource = {
     if (hasCmd("supabase") || process.env.MM_SOURCE_FIXTURE) {
       const refArg = opts?.supabaseProjectRef ? ["--project-ref", opts.supabaseProjectRef] : [];
       const secrets = await run("supabase", ["secrets", "list", ...refArg]);
-      if (secrets.ok) {
+      if (!secrets.ok) fail(secrets); // logged-out CLI etc. must not read as "no secrets"
+      else {
         for (const name of parseSupabaseSecrets(secrets.stdout)) {
           // NAME as the entry key, EMPTY value → detectInLine runs on the name
           // only; there is no value to leak.
@@ -179,7 +185,15 @@ export const supabaseEdgeSource = {
         } catch {
           continue;
         }
-        out.push(...scanFunctionBody(text, `supabase-edge://${ref}/${slug}/${f}`, compiled, opts?.env));
+        out.push(
+          ...scanFunctionBody(
+            text,
+            `supabase-edge://${ref}/${slug}/${f}`,
+            compiled,
+            opts?.env,
+            path.join("supabase", "functions", slug, f), // collectFrom dedupe hint vs the filesystem walk
+          ),
+        );
       }
     }
     return out;

package/src/sources/vercel.js

@@ -1,4 +1,6 @@
-import { hasCmd, run } from "./shell.js";
+import fs from "node:fs";
+import path from "node:path";
+import { hasCmd, run, makeCliFailureReporter } from "./shell.js";
 import { scanConfigEntries, entriesFromKV } from "./configscan.js";
 
 /** Deployment TARGET → environment. The target is AUTHORITATIVE (Vercel tells us
@@ -32,11 +34,35 @@ export function parseVercelEnvLs(stdout) {
   return rows;
 }
 
+/** The project this directory is LINKED to. `vercel link` writes
+ * .vercel/project.json; newer CLIs record projectName there. null when
+ * unlinked or the name isn't recorded. */
+export function readLinkedProject(root) {
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(root || ".", ".vercel", "project.json"), "utf8"));
+    return j?.projectName || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The "> Environment Variables found for <team>/<project> [123ms]" banner names
+ * the project the CLI ACTUALLY queried — parse it so provenance is real, never
+ * whatever name a flag claimed. */
+export function parseProjectFromBanner(stdout) {
+  const m = /environment variables found for\s+(\S+)/i.exec(String(stdout || ""));
+  if (!m) return null;
+  const who = m[1].replace(/[.,;]+$/, "");
+  return (who.includes("/") ? who.split("/").pop() : who) || null;
+}
+
 /** Vercel project env. LIVE integration: gated on the enabled toggle AND the
  * `vercel` CLI being present (or a VERCEL_TOKEN in the env — the CLI auto-picks
  * it up for non-interactive auth). Lists env-var NAMES only via `vercel env ls`
  * (NEVER `vercel env pull` — that would write plaintext secrets to disk).
- * opts: { vercelProject, vercelTeam }. */
+ * opts: { root, vercelProject, vercelTeam }. The CLI is run in the scan root
+ * and scans the project LINKED there; --vercel-project asserts (not selects)
+ * that project — a mismatch errors instead of mislabeling provenance. */
 export const vercelSource = {
   id: "vercel",
   label: "Vercel project env",
@@ -55,20 +81,52 @@ export const vercelSource = {
   },
   async collect(opts, compiled) {
     const scope = opts?.vercelTeam ? ["--scope", opts.vercelTeam] : [];
-    const project = opts?.vercelProject || "default";
+    const requested = opts?.vercelProject || null;
+    const fail = makeCliFailureReporter("vercel", "vercel", opts);
+    // `vercel env ls` has NO project flag: the CLI queries whatever project the
+    // cwd is LINKED to. So we run it in the scan root and derive the REAL
+    // project from the link file / output banner. --vercel-project is honored
+    // only when it matches that real project — a mismatch (or an unverifiable
+    // project) is an ERROR, never a silently mislabeled result.
+    let project = readLinkedProject(opts?.root);
+    const assertRequestedMatches = () => {
+      if (requested && project && project !== requested) {
+        throw new Error(
+          `--vercel-project "${requested}" doesn't match the project this directory is linked to ("${project}") — ` +
+            `the vercel CLI only scans the linked project. run \`vercel link --project ${requested}\` in the scan root first`,
+        );
+      }
+    };
+    assertRequestedMatches();
     const out = [];
+    let listed = false;
     // One pull per target so the env is authoritative + per-row correct. We ask
     // for NAMES only; `vercel env ls <target>` prints the table without values.
     for (const target of ["production", "preview", "development"]) {
-      const r = await run("vercel", ["env", "ls", target, ...scope]);
-      if (!r.ok) continue;
+      const r = await run("vercel", ["env", "ls", target, ...scope], { cwd: opts?.root });
+      if (!r.ok) {
+        fail(r);
+        continue;
+      }
+      listed = true;
+      project = project || parseProjectFromBanner(r.stdout);
+      assertRequestedMatches();
       for (const { name } of parseVercelEnvLs(r.stdout)) {
         // NAME-only entry: empty value → detectInLine runs on the name only, no
         // value to leak. The TARGET is the authoritative env (overrides everything).
-        const entries = entriesFromKV(name, "", `vercel://${project}/${target}#${name}`, target);
+        // Label fallback: `requested` may appear here before the banner confirms
+        // it — safe, because the post-loop check below throws (discarding these
+        // rows) whenever a requested project was never verified.
+        const entries = entriesFromKV(name, "", `vercel://${project || requested || "default"}/${target}#${name}`, target);
         out.push(...scanConfigEntries(entries, compiled, { sourceType: "vercel", env: TARGET_ENV[target] }));
       }
     }
+    if (requested && listed && !project) {
+      throw new Error(
+        `--vercel-project "${requested}" can't be honored — couldn't confirm which project the vercel CLI queried ` +
+          `(no .vercel/project.json link, no project in the CLI output). run \`vercel link --project ${requested}\` in the scan root first`,
+      );
+    }
     return out;
   },
 };

package/src/telemetry.js

@@ -69,6 +69,27 @@ export function analyticsState() {
   return { on: !!POSTHOG_KEY, reason: POSTHOG_KEY ? "" : "no key baked in" };
 }
 
+/** The vetted command words the `cli_command` event may ever carry. Anything
+ * else in argv[0] — a directory path (`mm ~/client-repo`), a typo, a file —
+ * must NEVER reach PostHog: the privacy promise ("never code, model names, or
+ * paths") includes the path the user points mm at. Keep in sync with the
+ * dispatch in index.js main(). */
+const KNOWN_COMMANDS = new Set([
+  "login", "signup", "logout", "config", "analytics", "scan", "fix", "ci",
+  "status", "sources", "integrations", "clear", "play", "upgrade", "tui",
+  "update", "version", "help",
+]);
+
+/** Sanitize the raw first positional into a telemetry-safe command word:
+ * empty → "tui" (bare `mm`), a known command → itself, an existing directory
+ * (`mm <dir>` launches the TUI on it) → "dir", anything else → "unknown".
+ * `isDir` is injected so this stays pure/testable. */
+export function telemetryCommand(cmd, isDir = () => false) {
+  if (!cmd) return "tui";
+  if (KNOWN_COMMANDS.has(cmd)) return cmd;
+  try { return isDir(cmd) ? "dir" : "unknown"; } catch { return "unknown"; }
+}
+
 /** Fire-and-forget capture. Never throws, never blocks the CLI meaningfully. */
 export function track(event, properties = {}) {
   if (!enabled()) return;

package/src/tui/app.js

@@ -371,9 +371,20 @@ export function App({ apiBase, apiKey, dir, initialView, onSignedIn, fresh }) {
 }
 
 /** Top-level TUI entry — always renders App; auth unlocks tabs in-place. */
-function Bootstrap(props) {
+export function Bootstrap(props) {
   const [apiKey, setApiKey] = React.useState(props.apiKey);
-  return h(App, { ...props, apiKey, onSignedIn: (k) => { track("signed_in"); setApiKey(k); } });
+  return h(App, {
+    ...props,
+    apiKey,
+    onSignedIn: (k) => {
+      track("signed_in");
+      // Keep the module-level controller in sync: a game round-trip remounts
+      // from _opts (captured at runApp time), and a stale null apiKey there
+      // would silently sign the session back out after the game.
+      if (appController._opts) appController._opts = { ...appController._opts, apiKey: k };
+      setApiKey(k);
+    },
+  });
 }
 
 // Module-level controller so a view (the Scan tab) can UNMOUNT the whole Ink
@@ -383,6 +394,22 @@ function Bootstrap(props) {
 export const appController = {
   _instance: null,
   _opts: null,
+  // A game handoff is in flight: the coming unmount is NOT a real quit. Set by
+  // launch.js BEFORE unmount(); cleared by remount() (or endHandoff() when the
+  // game fails to come back). runApp's exit waiter checks it to decide whether
+  // to keep the alt screen + promise alive or treat the unmount as a quit.
+  _handoff: false,
+  _handoffWaiter: null, // runApp's deferred quit-or-rearm check (see runApp)
+  /** Mark the next unmount as a game handoff (a remount will follow). */
+  beginHandoff() { this._handoff = true; },
+  /** End a handoff — normally via remount(); called directly (without a
+   * remount) when the game errored, so runApp treats the unmount as a quit. */
+  endHandoff() {
+    this._handoff = false;
+    const w = this._handoffWaiter;
+    this._handoffWaiter = null;
+    if (w) w();
+  },
   /** Tear down the current Ink tree (releases raw mode + stdin listeners). */
   unmount() {
     try { this._instance && this._instance.unmount(); } catch { /* already gone */ }
@@ -398,6 +425,10 @@ export const appController = {
     // right before this, so by now the terminal reports its stable full height.
     try { process.stdout.write("\x1b[2J\x1b[H"); } catch { /* ignore */ }
     this._instance = render(h(Bootstrap, opts));
+    // launch.js re-entered the alt screen right before remounting — record it so
+    // the final quit's leaveAlt() actually restores the host screen + scrollback.
+    this._inAlt = true;
+    this.endHandoff(); // flush runApp's waiter → it re-arms on the new instance
     return this._instance;
   },
 };
@@ -427,20 +458,31 @@ export function runApp(opts) {
   appController._opts = opts;
   const app = render(h(Bootstrap, opts));
   appController._instance = app;
-  // waitUntilExit resolves when the CURRENT instance unmounts. A Scan-tab game
-  // launch unmounts + remounts, which would resolve this early; so we re-arm on
-  // each remount and only resolve when an instance exits WITHOUT a pending
-  // remount (i.e. a real quit). The `_exiting` flag is set by a clean exit().
+  // waitUntilExit resolves when the CURRENT instance unmounts — including the
+  // deliberate unmount at the start of a game handoff (launch.js), which nulls
+  // _instance and resolves this promise BEFORE the remount happens. So a game
+  // launch must not read as a quit: launch.js sets appController._handoff before
+  // unmounting, and while it's set we park the decision in _handoffWaiter.
+  // remount()/endHandoff() flush the waiter — a remount re-arms on the new
+  // instance; a failed handoff (no remount) falls through to the real-quit path.
   return new Promise((resolve) => {
     const arm = (inst) => {
       inst.waitUntilExit().then(() => {
-        // If a remount happened (a new instance is live and differs), keep waiting.
-        if (appController._instance && appController._instance !== inst) {
-          arm(appController._instance);
-        } else {
-          leaveAlt(); // real quit → restore the host screen + scrollback
-          resolve();
-        }
+        const settle = () => {
+          if (appController._handoff) {
+            // Game round-trip in flight — decide after remount()/endHandoff().
+            appController._handoffWaiter = settle;
+            return;
+          }
+          // If a remount happened (a new instance is live and differs), keep waiting.
+          if (appController._instance && appController._instance !== inst) {
+            arm(appController._instance);
+          } else {
+            leaveAlt(); // real quit → restore the host screen + scrollback
+            resolve();
+          }
+        };
+        settle();
       });
     };
     arm(app);

package/src/tui/game/launch.js

@@ -26,13 +26,15 @@ export async function playGameInTui({ dir, width, height, initialView = "scan",
   if (launching) return;
   launching = true;
   track("game_opened", { game: "donkey_kong", scan_phase: scanPhase });
+  let appController = null; // hoisted so the catch below can end a dangling handoff
   try {
-    const [{ runGame }, { startScanProcess }, { appController }, { writeDiskScan, loadRegistry }] = await Promise.all([
+    const [{ runGame }, { startScanProcess }, app, { writeDiskScan, loadRegistry }] = await Promise.all([
       import("./loop.js"),
       import("../../sources/scan-process.js"),
       import("../app.js"),
       import("../scan-stream.js"),
     ]);
+    appController = app.appController;
 
     // (1) Start a TRUE background scan SUBPROCESS over `dir`. It survives the Ink
     // unmount (separate OS process). Pre-fetch + cache the registry so the worker
@@ -56,6 +58,11 @@ export async function playGameInTui({ dir, width, height, initialView = "scan",
     } catch { handle = null; }
 
     // (2) Unmount the Ink tree (releases raw mode + stdin). Let teardown settle.
+    // beginHandoff FIRST: unmount() resolves ink's exit promise synchronously,
+    // and without the flag runApp's exit waiter would read this as a real quit —
+    // dropping the alt screen mid-game and resolving runApp early (main() then
+    // races the game for stdout). See appController/runApp in ../app.js.
+    appController.beginHandoff();
     appController.unmount();
     await new Promise((r) => setImmediate(r));
 
@@ -90,8 +97,13 @@ export async function playGameInTui({ dir, width, height, initialView = "scan",
     // useTermDims — we no longer poll for it).
     try { process.stdout.write("\x1b[?1049l\x1b[?1049h\x1b[2J\x1b[H"); } catch { /* ignore */ }
     await new Promise((r) => setImmediate(r));
-    appController.remount({ initialView, fresh: false });
+    appController.remount({ initialView, fresh: false }); // remount ends the handoff
   } catch (e) {
+    // The handoff died without a remount (e.g. the game threw). End it so
+    // runApp's parked waiter treats the earlier unmount as a real quit and
+    // restores the host screen instead of waiting forever. No-op when the
+    // error happened before beginHandoff (tree still mounted → toast shows).
+    if (appController) appController.endHandoff();
     if (onError) onError(e); else throw e;
   } finally {
     launching = false;