@modelstatus/cli 0.1.35 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelstatus/cli",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Track which AI models you use, where, and never get surprised by a retirement. Free offline model-health for any repo (mm status), browser sign-in for cloud inventory + alerts.",
   "keywords": [
     "llm",

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { resolveAuth, loadConfig, saveConfig, clearAuth, configFilePath } from "./config.js";
 import { createClient } from "./api.js";
@@ -15,6 +16,73 @@ import { maybeCheckForUpdate } from "./updater.js";
 import { track, maybeAnalyticsNotice } from "./telemetry.js";
 import { BUILD_VERSION } from "./version.js";
 
+// TRUE BACKGROUND SCAN — hidden worker dispatch. MUST be the first executable
+// statement, BEFORE main()/maybeAnalyticsNotice/track/maybeCheckForUpdate: those
+// write to stdout (the analytics notice) and trigger the self-updater, but the
+// worker's stdout MUST be PURE NDJSON. The dynamic import pulls in ONLY
+// filesystem.js + detect/core + registry (no ink, upload, auth, telemetry).
+//
+// argv is env-agnostic: under node argv = [node, /abs/src/index.js, sentinel, …];
+// under the bun-compiled binary argv = [/abs/binary, /$bunfs/…, sentinel, …]. In
+// BOTH the sentinel is at index 2 and worker args at index 3+. (See
+// src/sources/scan-process.js buildSpawnArgs for the matching parent spawn.)
+if (process.argv[2] === "__mm_scan_worker") {
+  const { runWorker } = await import("./sources/scan-worker.js");
+  await runWorker(process.argv.slice(3)); // never returns — calls process.exit
+}
+
+// HIDDEN bench seam (NOT a public command; absent from help). Runs the REAL
+// game loop with a per-frame timestamp tap → stdout NDJSON, AND starts the REAL
+// background scan subprocess (the production self-re-exec) so the SHIPPED binary
+// is measured doing BOTH jobs at once — the exact concurrent path `mm play`
+// drives. Used by test/game-jitter-compiled.test.mjs to gate the bun-compiled
+// artifact (where the runtime, and thus the self-re-exec branch, differs from
+// node). Headless: drives the loop via its _inject IO seams (no TTY needed).
+//   mm __bench_frames --seconds=N --with-scan=DIR [--ndjson]
+if (process.argv[2] === "__bench_frames") {
+  const args = process.argv.slice(3);
+  const getv = (k, d) => { const a = args.find((x) => x.startsWith(`--${k}=`)); return a ? a.slice(k.length + 3) : d; };
+  const seconds = Number(getv("seconds", "4")) || 4;
+  const scanDir = getv("with-scan", null);
+  const now = () => Number(process.hrtime.bigint() / 1000000n);
+  const emit = (o) => process.stdout.write(JSON.stringify(o) + "\n");
+
+  const { runGame } = await import("./tui/game/loop.js");
+  let scan = null;
+  if (scanDir) {
+    const { startScanProcess, isBunRuntime } = await import("./sources/scan-process.js");
+    scan = startScanProcess({ root: scanDir }, {});
+    // Echo the self-re-exec proof: the worker's runtime + spawn argv0, so the
+    // test KNOWS the subprocess path didn't silently fall back to in-process.
+    emit({ t: "reexec", bun: isBunRuntime(), parentExec: process.execPath, childPid: scan.child.pid, childSpawnFile: process.execPath });
+  }
+
+  // Fake IO so the loop runs without a TTY; wrap schedule to timestamp each tick.
+  const writes = [];
+  const out = { columns: 80, rows: 24, isTTY: false, write: (s) => { if (s) writes.push(s.length); return true; }, setRawMode() { return this; }, on() {}, removeListener() {}, resume() {}, pause() {} };
+  const input = { isTTY: false, isRaw: false, setRawMode(v) { this.isRaw = v; return this; }, on() {}, removeListener() {}, resume() {}, pause() {}, write() { return true; } };
+  const seqs = ["\x1b[C", "\x1b[D", " ", "\x1b[A"]; let ki = 0;
+  const drive = setInterval(() => { (input._d || []).forEach((f) => f(Buffer.from(seqs[ki++ % seqs.length]))); }, 45);
+  input.on = (ev, fn) => { if (ev === "data") (input._d ||= []).push(fn); };
+  input.removeListener = (ev, fn) => { if (ev === "data") input._d = (input._d || []).filter((f) => f !== fn); };
+
+  let prev = null;
+  const p = runGame({
+    width: 80, height: 24, scanStore: scan,
+    _inject: {
+      out, inp: input, proc: process, now,
+      schedule: (fn, ms) => setTimeout(() => { const t = now(); if (prev != null) emit({ t: "frame", dtMs: t - prev }); prev = t; fn(); }, ms),
+      cancel: (h) => clearTimeout(h),
+    },
+  });
+  setTimeout(() => { (input._d || []).forEach((f) => f(Buffer.from("q"))); }, seconds * 1000);
+  await p;
+  clearInterval(drive);
+  emit({ t: "done", filesScanned: scan ? scan.stats.filesScanned : 0, candidates: scan ? scan.stats.candidateCount : 0, phase: scan ? scan.stats.phase : "none" });
+  try { scan && scan.abort(); } catch {}
+  process.exit(0);
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
@@ -134,6 +202,49 @@ async function cmdUpgrade(_positional, flags) {
   }
 }
 
+/** `mm play [dir]` — the standalone game: NO Ink, ever. Runs the direct-ANSI
+ * 60Hz loop while a background scan subprocess walks `dir` (its progress feeds
+ * the in-game HUD). Pure terminal, restores cleanly on every exit path. */
+async function cmdPlay(positional, flags) {
+  if (!process.stdout.isTTY) {
+    console.error("`mm play` needs an interactive terminal (a TTY).");
+    process.exit(1);
+  }
+  const dir = path.resolve(positional[1] || flags.dir || ".");
+  const { runGame } = await import("./tui/game/loop.js");
+
+  // Best-effort background scan of `dir` so the HUD shows live progress. We
+  // pre-fetch the signed registry once and hand the worker a cache file so it
+  // skips the network; on any failure the game still plays (scanStore stays in
+  // its error/empty state, which the HUD renders as "scan unavailable").
+  let scanHandle = null;
+  let cacheFile = null;
+  try {
+    const { startScanProcess } = await import("./sources/scan-process.js");
+    try {
+      const { getRegistry } = await import("./registry/fetch.js");
+      const snapshot = await getRegistry({ offline: !!flags.offline }).catch(() => null);
+      if (snapshot) {
+        cacheFile = path.join(os.tmpdir(), `mm-reg-${process.pid}.json`);
+        fs.writeFileSync(cacheFile, JSON.stringify(snapshot));
+      }
+    } catch { /* no cache — worker fetches itself */ }
+    scanHandle = startScanProcess({ root: dir, registryCachePath: cacheFile || undefined }, {});
+  } catch { scanHandle = null; }
+
+  try {
+    await runGame({
+      width: process.stdout.columns || 80,
+      height: process.stdout.rows || 24,
+      level: 1,
+      scanStore: scanHandle,
+    });
+  } finally {
+    try { scanHandle && scanHandle.abort(); } catch { /* ignore */ }
+    try { if (cacheFile) fs.unlinkSync(cacheFile); } catch { /* ignore */ }
+  }
+}
+
 async function launchTui(initialView, flags) {
   // Pass apiKey straight through (may be null). The TUI's Bootstrap wrapper
   // renders an interactive SignIn screen when there's no key, then swaps to
@@ -584,6 +695,7 @@ Usage:
   mm integrations          Manage live integrations (list | enable <id> | disable <id> | env <id> <tag>)
   mm clear                 Delete all tracked usages from your inventory (--all also wipes projects/rules; --yes to skip the prompt)
   mm upgrade               Open Stripe checkout and poll until Pro is active
+  mm play [dir]            Play Donkey Kong while a background scan walks the dir (just for fun)
   mm tui                   Force-launch the TUI (logs you in first if needed)
 
 Scan sources (--sources; default = filesystem + enabled integrations; "all" for everything):
@@ -648,6 +760,7 @@ async function main() {
     else if (cmd === "sources") await cmdSources(positional, flags);
     else if (cmd === "integrations") cmdIntegrations(positional, flags);
     else if (cmd === "clear") await cmdClear(positional, flags);
+    else if (cmd === "play") await cmdPlay(positional, flags);
     else if (cmd === "upgrade") await cmdUpgrade(positional, flags);
     else if (cmd === "tui" || !cmd) await launchTui(positional[1], flags);
     else if (cmd === "help" || flags.help) console.log(HELP);

package/src/sources/scan-process.js

@@ -0,0 +1,238 @@
+/* TRUE BACKGROUND SCAN — PARENT side.
+ *
+ * Spawns the scan as a SEPARATE OS process (self-re-exec of the running runtime
+ * via the hidden `__mm_scan_worker` sentinel; see src/index.js top dispatch +
+ * src/sources/scan-worker.js), readline-parses its NDJSON stdout into a plain
+ * mutable `stats` store, and re-dispatches onto the SAME named-handler shape
+ * scan-runner.js uses ({onCandidate,onProgress,onSkip,onDone,onError}) — so this
+ * is the mechanical swap the scan-runner.js header comment promised, except the
+ * walk now runs in its OWN event loop (no cooperative-yield lag during a game /
+ * heavy IO), and survives an Ink unmount because it's a real subprocess.
+ *
+ * Returned handle mirrors scan-runner.js's {abort,pause,resume,paused} plus a
+ * read-only `stats` getter and the `child` reference. The game HUD reads `stats`
+ * every render and NEVER awaits the scan.
+ *
+ * Dual-runtime spawn (the ONE place runtime matters — both branches verified):
+ *   - Compiled binary (bun --compile): process.execPath IS the binary; re-exec
+ *     it with just the worker args. argv[1] is a virtual /$bunfs path and is NOT
+ *     spawnable, so do NOT prepend it.
+ *   - node / npm: process.execPath is node; prepend process.argv[1] (the real
+ *     absolute src/index.js path) so node loads the entry, which dispatches.
+ */
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+/** True inside the bun-compiled binary, false under node. Defined-in-bun signal. */
+export function isBunRuntime() {
+  return typeof globalThis.Bun !== "undefined" || process.versions.bun != null;
+}
+
+/**
+ * Build the argv passed to spawn() for `process.execPath`.
+ * @param {string[]} workerArgs  ['--root', dir, ...] worker flags (NO sentinel)
+ * @returns {string[]} full spawn argv (sentinel + flags, with argv[1] prepended under node)
+ */
+export function buildSpawnArgs(workerArgs) {
+  const wargs = ["__mm_scan_worker", ...workerArgs];
+  // Compiled binary: re-exec the binary itself (execPath) with just the worker
+  // args. node: execPath is node, so prepend the real entry script (argv[1]).
+  return isBunRuntime() ? wargs : [process.argv[1], ...wargs];
+}
+
+/**
+ * Start a background filesystem scan in a separate OS process.
+ *
+ * @param {object} opts
+ * @param {string} opts.root                dir to walk (required)
+ * @param {string[]} [opts.exclude]         extra ignore patterns (csv-joined for the worker)
+ * @param {object} [opts.env]               extra env merged over process.env for the child
+ * @param {string} [opts.registryCachePath] pre-fetched snapshot JSON path (worker skips the network)
+ *
+ * @param {object} [handlers]
+ * @param {(candidate:object)=>void} [handlers.onCandidate]
+ * @param {(p:object)=>void}         [handlers.onProgress] {filesScanned,dirsSeen,catalogsSkipped,currentDir}
+ * @param {(s:object)=>void}         [handlers.onSkip]     {path,distinct,catalogsSkipped}
+ * @param {(r:object)=>void}         [handlers.onDone]     {candidates,filesScanned,dirsSeen,catalogsSkipped,scannedAt} — suppressed after abort()
+ * @param {(err:Error)=>void}        [handlers.onError]
+ *
+ * @returns {{abort:()=>void, pause:()=>void, resume:()=>void, paused:boolean, stats:object, child:import('node:child_process').ChildProcess}}
+ */
+export function startScanProcess(opts, handlers = {}) {
+  const { root, exclude, env, registryCachePath } = opts || {};
+  const {
+    onCandidate = () => {},
+    onProgress = () => {},
+    onSkip = () => {},
+    onDone = () => {},
+    onError = () => {},
+  } = handlers;
+
+  // Worker flags. Sentinel + argv[1] handling lives in buildSpawnArgs.
+  const workerArgs = ["--root", root];
+  if (exclude && exclude.length) workerArgs.push("--exclude", exclude.join(","));
+  if (registryCachePath) workerArgs.push("--registry-cache", registryCachePath);
+
+  const child = spawn(process.execPath, buildSpawnArgs(workerArgs), {
+    // ignore stdin; PIPE stdout (NDJSON) + stderr (diagnostics). NEVER 'inherit'
+    // — the worker shares no terminal with the game, so its output can't touch
+    // the alt-screen frame.
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, ...(env || {}) },
+    detached: false,
+    windowsHide: true,
+  });
+
+  // The HUD store — a plain mutable object the loop reads each render, read-only.
+  const stats = {
+    phase: "scanning", // scanning | done | error
+    filesScanned: 0,
+    candidateCount: 0,
+    dirsSeen: 0,
+    catalogsSkipped: 0,
+    currentDir: "",
+    scannedAt: null,
+    error: null,
+  };
+
+  let aborted = false;
+  let paused = false;
+  let finalized = false; // exactly-once phase finalization (done/error/exit)
+  let stderrBuf = "";
+
+  function handleLine(line) {
+    if (!line) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return; // drop a malformed / partial-leftover line, never throw
+    }
+    switch (msg.t) {
+      case "prog":
+        // dir-only prog lines carry just dirsSeen; full prog lines carry counts.
+        if (typeof msg.filesScanned === "number") stats.filesScanned = msg.filesScanned;
+        if (typeof msg.dirsSeen === "number") stats.dirsSeen = msg.dirsSeen;
+        if (typeof msg.catalogsSkipped === "number") stats.catalogsSkipped = msg.catalogsSkipped;
+        if (typeof msg.currentDir === "string") stats.currentDir = msg.currentDir;
+        if (!aborted) {
+          onProgress({
+            filesScanned: stats.filesScanned,
+            dirsSeen: stats.dirsSeen,
+            catalogsSkipped: stats.catalogsSkipped,
+            currentDir: stats.currentDir,
+          });
+        }
+        break;
+      case "cand":
+        // COUNTS only on the hot path: the loop never renders cand payloads, so
+        // parse pressure during a game is near-zero. The full Candidate[] is
+        // read once from the done line.
+        stats.candidateCount++;
+        if (!aborted) onCandidate(msg.candidate);
+        break;
+      case "skip":
+        if (typeof msg.catalogsSkipped === "number") stats.catalogsSkipped = msg.catalogsSkipped;
+        if (!aborted) onSkip({ path: msg.path, distinct: msg.distinct, catalogsSkipped: msg.catalogsSkipped });
+        break;
+      case "done":
+        if (finalized) return;
+        finalized = true;
+        stats.phase = "done";
+        stats.filesScanned = msg.filesScanned ?? stats.filesScanned;
+        stats.dirsSeen = msg.dirsSeen ?? stats.dirsSeen;
+        stats.catalogsSkipped = msg.catalogsSkipped ?? stats.catalogsSkipped;
+        stats.candidateCount = (msg.candidates || []).length;
+        stats.scannedAt = msg.scannedAt ?? Date.now();
+        if (!aborted) onDone({
+          candidates: msg.candidates || [],
+          filesScanned: stats.filesScanned,
+          dirsSeen: stats.dirsSeen,
+          catalogsSkipped: stats.catalogsSkipped,
+          scannedAt: stats.scannedAt,
+        });
+        break;
+      case "err":
+        if (finalized) return;
+        finalized = true;
+        stats.phase = "error";
+        stats.error = msg.message || "scan failed";
+        if (!aborted) onError(new Error(stats.error));
+        break;
+      default:
+        break;
+    }
+  }
+
+  const rl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+  rl.on("line", handleLine);
+
+  child.stderr.on("data", (d) => {
+    stderrBuf += d.toString();
+    if (stderrBuf.length > 64_000) stderrBuf = stderrBuf.slice(-64_000); // bound
+  });
+
+  child.on("error", (err) => {
+    // Spawn failure (e.g. execPath missing) — surface unless we asked to die.
+    if (finalized || aborted) return;
+    finalized = true;
+    stats.phase = "error";
+    stats.error = err?.message || "failed to start scan worker";
+    onError(err instanceof Error ? err : new Error(stats.error));
+  });
+
+  child.on("exit", (code, signal) => {
+    // If the child exited without a done/err line and we didn't abort it, treat
+    // a non-zero/signal exit as an error so the HUD doesn't hang on "scanning".
+    if (finalized || aborted) return;
+    if (code === 0) return; // a 0 exit always followed a done line above
+    finalized = true;
+    stats.phase = "error";
+    stats.error = (stderrBuf.trim().split("\n").pop() || `scan worker exited (code ${code}, signal ${signal})`);
+    onError(new Error(stats.error));
+  });
+
+  return {
+    abort() {
+      // Idempotent. Suppresses onDone/onError and kills the child (cross-platform).
+      if (aborted) return;
+      aborted = true;
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* already gone */
+      }
+    },
+    pause() {
+      if (paused) return;
+      paused = true;
+      // SIGSTOP genuinely freezes the child on posix; on win32 it's a no-op on
+      // the process but we still flip the flag so the UI reflects intent.
+      if (process.platform !== "win32") {
+        try {
+          child.kill("SIGSTOP");
+        } catch {
+          /* ignore */
+        }
+      }
+    },
+    resume() {
+      if (!paused) return;
+      paused = false;
+      if (process.platform !== "win32") {
+        try {
+          child.kill("SIGCONT");
+        } catch {
+          /* ignore */
+        }
+      }
+    },
+    get paused() {
+      return paused;
+    },
+    get stats() {
+      return stats;
+    },
+    child,
+  };
+}

package/src/sources/scan-worker.js

@@ -0,0 +1,148 @@
+/* TRUE BACKGROUND SCAN — CHILD (worker) side.
+ *
+ * Runs inside a self-re-exec'd OS process: the parent spawns `process.execPath`
+ * with the hidden `__mm_scan_worker` sentinel as argv[2] (see src/index.js top
+ * dispatch + src/sources/scan-process.js). This module is dynamic-imported by
+ * that dispatch, so it pulls in ONLY filesystem.js + detect/core + registry
+ * (NO ink, NO upload, NO auth, NO telemetry, NO updater) — the worker's stdout
+ * must be PURE NDJSON.
+ *
+ * Protocol: one JSON object per line, newline-terminated, FLUSHED. Tags:
+ *   {t:"prog", filesScanned, dirsSeen, catalogsSkipped, currentDir}
+ *   {t:"cand", candidate}
+ *   {t:"skip", path, distinct, catalogsSkipped}
+ *   {t:"done", candidates, filesScanned, dirsSeen, catalogsSkipped, scannedAt}
+ *   {t:"err",  message}
+ *
+ * Lifecycle: SIGTERM -> AbortController.abort() (clean stop). SIGSTOP/SIGCONT
+ * are handled by the OS (pause/resume) and need no listener. The terminal
+ * done/err line is flushed by deferring process.exit into the write callback,
+ * so the parent never loses the final line on exit.
+ */
+import fs from "node:fs";
+import { scanFilesystemStreaming } from "./filesystem.js";
+import { compilePatterns } from "../detect/core.js";
+import { getRegistry } from "../registry/fetch.js";
+
+/** Parse the worker's own argv (process.argv.slice(3)) — light, no parseArgs dep. */
+function parseWorkerArgs(args) {
+  const out = { root: process.cwd(), exclude: [], registryCache: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--root") out.root = args[++i];
+    else if (a === "--exclude") out.exclude = (args[++i] || "").split(",").filter(Boolean);
+    else if (a === "--registry-cache") out.registryCache = args[++i];
+  }
+  return out;
+}
+
+/** Flush-safe NDJSON writer. When `exitCode` is given, exit INSIDE the write
+ * callback so the final line is fully flushed to the pipe before we exit, and
+ * return a never-resolving Promise so the caller's `await` HANGS until that
+ * deferred process.exit fires — this prevents the top-level worker dispatch in
+ * index.js from falling through to main() (which would print HELP) between the
+ * promise resolving and the async exit landing. */
+function makeEmitter() {
+  return function emit(obj, exitCode) {
+    const line = JSON.stringify(obj) + "\n";
+    if (typeof exitCode === "number") {
+      // Defer exit until this write drains — guarantees done/err is delivered.
+      process.stdout.write(line, () => process.exit(exitCode));
+      return new Promise(() => {}); // hang forever; the write cb exits the proc
+    }
+    process.stdout.write(line);
+    return undefined;
+  };
+}
+
+/**
+ * Worker entrypoint. `args` is process.argv.slice(3). Never returns (process.exit).
+ */
+export async function runWorker(args) {
+  const emit = makeEmitter();
+  const { root, exclude, registryCache } = parseWorkerArgs(args);
+
+  // (1) Registry snapshot: prefer the parent's pre-fetched cache file (skips the
+  // network); else fetch + verify ourselves. On total failure (offline, no
+  // cache) emit one err line and exit 1.
+  let snapshot;
+  try {
+    if (registryCache) {
+      snapshot = JSON.parse(fs.readFileSync(registryCache, "utf8"));
+    } else {
+      snapshot = await getRegistry();
+    }
+  } catch (e) {
+    return emit({ t: "err", message: `registry unavailable: ${e?.message ?? e}` }, 1);
+  }
+
+  // (2) Compile detection patterns once.
+  let compiled;
+  try {
+    compiled = compilePatterns(snapshot.detection);
+  } catch (e) {
+    return emit({ t: "err", message: `bad registry snapshot: ${e?.message ?? e}` }, 1);
+  }
+
+  // (7) Abort: parent SIGTERM -> abort the walk so the kill stops cleanly.
+  const ac = new AbortController();
+  process.on("SIGTERM", () => ac.abort());
+
+  // (4) Run the streaming scan, mapping the engine RAW onEvent protocol to NDJSON.
+  // yieldBudgetMs Infinity (count-only): the worker is ALONE in its event loop —
+  // no foreground frame loop to keep ticking — so the walk runs as fast as it
+  // can; the setImmediate-every-40-files yield still fires often enough to flush
+  // stdout + service the abort signal.
+  // Track the latest counters so the `done` line carries accurate finals even
+  // when the last event before completion was a candidate (which has no counts).
+  let filesScanned = 0;
+  let dirsSeen = 0;
+  let catalogsSkipped = 0;
+  try {
+    const candidates = await scanFilesystemStreaming(
+      { root, signal: ac.signal, exclude, env: process.env.MM_ENV, yieldBudgetMs: Infinity },
+      compiled,
+      (ev) => {
+        switch (ev.type) {
+          case "dir":
+            // Fold into a prog line carrying only the running dir count.
+            dirsSeen = ev.dirsSeen;
+            emit({ t: "prog", dirsSeen: ev.dirsSeen });
+            break;
+          case "candidate":
+            emit({ t: "cand", candidate: ev.candidate });
+            break;
+          case "skip":
+            catalogsSkipped = ev.catalogsSkipped;
+            emit({ t: "skip", path: ev.path, distinct: ev.distinct, catalogsSkipped: ev.catalogsSkipped });
+            break;
+          case "progress":
+            filesScanned = ev.filesScanned;
+            dirsSeen = ev.dirsSeen;
+            catalogsSkipped = ev.catalogsSkipped;
+            emit({
+              t: "prog",
+              filesScanned: ev.filesScanned,
+              dirsSeen: ev.dirsSeen,
+              catalogsSkipped: ev.catalogsSkipped,
+              currentDir: ev.currentDir,
+            });
+            break;
+          default:
+            break;
+        }
+      },
+    );
+
+    // (5) Final summary rides the done line — the full Candidate[] so the parent
+    // seeds the Scan view without buffering every cand. Exit 0 in the write cb;
+    // await the hang so the dispatch never falls through to main().
+    await emit(
+      { t: "done", candidates, filesScanned, dirsSeen, catalogsSkipped, scannedAt: Date.now() },
+      0,
+    );
+  } catch (e) {
+    // Aborted walks resolve (return the partial set), so a throw here is real.
+    await emit({ t: "err", message: `${e?.message ?? e}` }, 1);
+  }
+}

package/src/tui/app.js

@@ -219,7 +219,46 @@ function Bootstrap(props) {
   return h(App, { ...props, apiKey, onSignedIn: (k) => { track("signed_in"); setApiKey(k); } });
 }
 
+// Module-level controller so a view (the Scan tab) can UNMOUNT the whole Ink
+// tree, run the direct-ANSI game loop (which owns its own raw mode + alt screen),
+// then REMOUNT a fresh tree at a chosen tab. The game subprocess scan survives
+// the unmount because it's a separate OS process, independent of Ink's lifecycle.
+export const appController = {
+  _instance: null,
+  _opts: null,
+  /** Tear down the current Ink tree (releases raw mode + stdin listeners). */
+  unmount() {
+    try { this._instance && this._instance.unmount(); } catch { /* already gone */ }
+    this._instance = null;
+  },
+  /** Mount a fresh Ink tree, merging the base opts with `next` (e.g. a tab). */
+  remount(next = {}) {
+    const opts = { ...(this._opts || {}), ...next };
+    this._opts = opts;
+    this._instance = render(h(Bootstrap, opts));
+    return this._instance;
+  },
+};
+
 export function runApp(opts) {
+  appController._opts = opts;
   const app = render(h(Bootstrap, opts));
-  return app.waitUntilExit();
+  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().
+  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 {
+          resolve();
+        }
+      });
+    };
+    arm(app);
+  });
 }