omkit 0.8.23 → 0.8.25

package/README.md

@@ -83,7 +83,7 @@ om("dev")
 Run it:
 
 ```sh
-npx omkit            # interactive picker: browse, run, watch milestones live
+npx omkit            # interactive shell: pick, run, watch, stop, rerun — until you quit
 npx omkit run dev    # or run one om directly
 ```
 
@@ -116,12 +116,12 @@ om(name: string): OmBuilder
 
 Returns a builder. Chain configuration, then finish with `.run(body)`, which launches the run.
 
-| Method                   | Purpose                                                                                                       |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `.describe({ summary })` | A one-line summary, shown by `omkit ls --describe`, the skill file, MCP and the report.                       |
-| `.args(schema)`          | A zod schema for the run's inputs. **Resolved at runtime**; see below.                                        |
-| `.mcp({ mode? })`        | Expose this om over MCP. `mode` is `"settling"` (default) or `"long-lived"`.                                  |
-| `.run(body)`             | Launch the run. `body(ctx, args?)` receives an [`OmContext`](#contexts) and, after `.args()`, the typed args. |
+| Method                      | Purpose                                                                                                                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.describe({ summary, … })` | A one-line summary, shown by `omkit ls --describe`, the skill file, MCP and the report. Any further props (`owner`, `docsUrl`, `needs: [...]`) are listed under it in the interactive picker and the report. |
+| `.args(schema)`             | A zod schema for the run's inputs. **Resolved at runtime**; see below.                                                                                                                                       |
+| `.mcp({ mode? })`           | Expose this om over MCP. `mode` is `"settling"` (default) or `"long-lived"`.                                                                                                                                 |
+| `.run(body)`                | Launch the run. `body(ctx, args?)` receives an [`OmContext`](#contexts) and, after `.args()`, the typed args.                                                                                                |
 
 `.run()` returns a promise that resolves once the run has torn down and written its record. It never rejects: failures are recorded in the run and set the process exit code. Whatever the body returns is recorded as the run's `value` in `result.json`.
 
@@ -156,14 +156,14 @@ import { action } from "omkit";
 action(name: string): ActionBuilder
 ```
 
-| Method                   | Purpose                                                                               |
-| ------------------------ | ------------------------------------------------------------------------------------- |
-| `.describe({ summary })` | A one-line summary, carried onto every run of this action.                            |
-| `.emits<Events>()`       | Declare the events this action emits, as a type: `{ ready: number; error: string }`.  |
-| `.ref<Handle>()`         | Declare the type of the value this action publishes with `attach`.                    |
-| `.args(schema)`          | Pin `.run`'s argument to a zod schema's type. **Type-level only** in code; see below. |
-| `.mcp({ mode? })`        | Expose this action over MCP as a runnable tool.                                       |
-| `.run(exec)`             | Bind the implementation. Returns an **Action**: a function you call to launch it.     |
+| Method                      | Purpose                                                                                                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `.describe({ summary, … })` | A one-line summary, plus any further props, carried onto every run of this action and listed in the report. |
+| `.emits<Events>()`          | Declare the events this action emits, as a type: `{ ready: number; error: string }`.                        |
+| `.ref<Handle>()`            | Declare the type of the value this action publishes with `attach`.                                          |
+| `.args(schema)`             | Pin `.run`'s argument to a zod schema's type. **Type-level only** in code; see below.                       |
+| `.mcp({ mode? })`           | Expose this action over MCP as a runnable tool.                                                             |
+| `.run(exec)`                | Bind the implementation. Returns an **Action**: a function you call to launch it.                           |
 
 `exec(ctx, ...args)` receives an [`ActionContext`](#contexts) and the arguments the action was called with. Its return value is the activity's result.
 

package/dist/cli/commands/ui.d.ts

@@ -1,8 +1,9 @@
 import type { OmkitClient } from "../../client/index.ts";
 /**
- * Render the interactive Ink app. Ink's own Ctrl+C handling is disabled so the app can tear the
- * run down gracefully first; the final verdict + run-folder path are printed here, after Ink
- * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ * Render the interactive shell, which stays up across runs until the user quits. Ink's own Ctrl+C
+ * handling is disabled so the app can tear a live run down gracefully first. Each run's verdict
+ * and recap block are already in the scrollback by then (the app writes them there as each run
+ * settles), so nothing is reprinted here; the exit code is the last run's verdict.
  *
  * Discovery runs first, before Ink takes the terminal: a fatal config problem throws here and the
  * bin's error boundary turns it into a clean crash rather than an empty list. With no oms to show,

package/dist/cli/commands/ui.js

@@ -4,9 +4,10 @@ import { App } from "../ui/app.js";
 import { renderDiagnostics, withSpinner } from "../ui/Report.js";
 import { reportNoOms } from "./run.js";
 /**
- * Render the interactive Ink app. Ink's own Ctrl+C handling is disabled so the app can tear the
- * run down gracefully first; the final verdict + run-folder path are printed here, after Ink
- * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ * Render the interactive shell, which stays up across runs until the user quits. Ink's own Ctrl+C
+ * handling is disabled so the app can tear a live run down gracefully first. Each run's verdict
+ * and recap block are already in the scrollback by then (the app writes them there as each run
+ * settles), so nothing is reprinted here; the exit code is the last run's verdict.
  *
  * Discovery runs first, before Ink takes the terminal: a fatal config problem throws here and the
  * bin's error boundary turns it into a clean crash rather than an empty list. With no oms to show,
@@ -27,19 +28,12 @@ export async function launchUi(client) {
         });
     }
     let finalVerdict;
-    const app = render(_jsx(App, { client: client, oms: registry.oms, onExit: (v) => (finalVerdict = v) }), {
+    const app = render(_jsx(App, { client: client, oms: registry.oms, warnings: registry.warnings, onExit: (v) => (finalVerdict = v) }), {
         exitOnCtrlC: false,
     });
     void app.waitUntilExit().then(() => {
-        if (finalVerdict) {
-            // Ink erased its frame on unmount; reprint the verdict marker plus the run's recap block
-            // (the same summary a bare run prints) so the pointers to the on-disk record survive.
-            console.log("");
-            console.log(finalVerdict.ok ? "✓ ok" : "✗ failed");
-            for (const line of finalVerdict.summary)
-                console.log(line);
+        if (finalVerdict)
             process.exitCode = finalVerdict.ok ? 0 : 1;
-        }
         // Backstop: the runner disconnects the supervised child so both processes can exit, but if
         // anything (a wedged pipe, a lingering handle) keeps the event loop alive past the grace,
         // force the exit. Unref'd, so it only fires when the process is genuinely stuck — a clean

package/dist/cli/ui/app.d.ts

@@ -1,12 +1,27 @@
 import { type ReactElement } from "react";
 import type { OmkitClient, Verdict } from "../../client/types.ts";
 import type { DiscoveredOm } from "../../client/registry.ts";
-/** The interactive app: discover → list/search → run → live milestones + prompts. */
-export declare function App({ client, onExit, oms: initialOms, }: {
+/**
+ * The interactive shell: pick an om, watch it run, stop it, and come back to the picker for the
+ * next — the process stays up until you quit. Every run is a fresh supervised child, so a rerun
+ * always executes the current code of the om and its actions; only the picker's list comes from
+ * discovery, which is redone in the background each time a run ends.
+ *
+ * The screen is two parts. Above, the scrollback ({@link Scrollback}): each run's header, its
+ * milestones, and its verdict with the recap block a bare run prints — written once, kept by the
+ * terminal. Below, the live part, the only thing redrawn: the picker, or the run box
+ * ({@link RunView}) with the running nodes, a prompt, and the key line.
+ *
+ * Stopping is always a graceful teardown — the child reaps its process tree and reports a verdict
+ * — and nothing here exits or moves on before that verdict. `esc` stops and returns to the
+ * picker; `ctrl+c` stops and then quits, and quits straight away from the picker.
+ */
+export declare function App({ client, onExit, oms: initialOms, warnings: initialWarnings, }: {
     client: OmkitClient;
-    /** Called with the run's verdict (if any) just before Ink unmounts, so the caller can print
-     *  a durable summary — Ink erases its own frame on exit. */
+    /** Called with the last run's verdict (if any) just before Ink unmounts. */
     onExit?: (verdict: Verdict | undefined) => void;
-    /** Oms discovered by the caller (pre-flight). When given, the app skips its own discovery. */
+    /** Oms discovered by the caller (pre-flight). When given, the app skips its own first scan. */
     oms?: DiscoveredOm[];
+    /** Warnings the caller already printed for that scan, so a rediscovery repeats only new ones. */
+    warnings?: readonly string[];
 }): ReactElement;

package/dist/cli/ui/app.js

@@ -1,143 +1,308 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import fs from "node:fs";
+import path from "node:path";
 import { useEffect, useRef, useState } from "react";
-import { useApp, useInput } from "ink";
+import { Box, Text, useApp, useInput } from "ink";
 import { RunModel } from "../../output/RunModel.js";
 import { OmList } from "./views/OmList.js";
-import { RunView } from "./views/RunView.js";
+import { RunView, formatDuration } from "./views/RunView.js";
+import { recapLines, shellLine } from "./views/shellLines.js";
+import { Scrollback } from "./views/Scrollback.js";
 import { Spinner } from "./Spinner.js";
 import { redrawLoop } from "./redrawLoop.js";
+import { openFile } from "./openFile.js";
 /**
  * How often the run screen redraws while the log streams in.
  *
- * An Ink frame costs ~25ms at minimum and grows with the milestone tail, so redrawing per log
- * entry caps the app at roughly 40 entries/second — far under what a build, a test suite, or a
- * dev server emits. The app then falls permanently behind: `settled` is the *last* message on
- * the channel, so it only arrives once every backlogged entry has been drawn, and the run looks
- * hung long after the child has finished. Folding into the model is cheap; drawing is not, so
- * the two run at different rates — and the gap is kept *after* each frame (see {@link redrawLoop}),
+ * An Ink frame costs ~25ms at minimum and grows with what it draws, so redrawing per log entry
+ * caps the app at roughly 40 entries/second — far under what a build, a test suite, or a dev
+ * server emits. The app then falls permanently behind: the verdict is the *last* message on the
+ * channel, so it only arrives once every backlogged entry has been drawn, and the run looks hung
+ * long after the child has finished. Folding into the model is cheap; drawing is not, so the two
+ * run at different rates — and the gap is kept *after* each frame (see {@link redrawLoop}),
  * since a frame slower than this would otherwise leave no time between frames for the log at all.
  */
 const REDRAW_MS = 80;
-/** The interactive app: discover → list/search → run → live milestones + prompts. */
-export function App({ client, onExit, oms: initialOms, }) {
+const sameOm = (a, b) => a.file === b.file && a.name === b.name;
+const clock = (at) => new Date(at).toTimeString().slice(0, 8);
+/**
+ * The interactive shell: pick an om, watch it run, stop it, and come back to the picker for the
+ * next — the process stays up until you quit. Every run is a fresh supervised child, so a rerun
+ * always executes the current code of the om and its actions; only the picker's list comes from
+ * discovery, which is redone in the background each time a run ends.
+ *
+ * The screen is two parts. Above, the scrollback ({@link Scrollback}): each run's header, its
+ * milestones, and its verdict with the recap block a bare run prints — written once, kept by the
+ * terminal. Below, the live part, the only thing redrawn: the picker, or the run box
+ * ({@link RunView}) with the running nodes, a prompt, and the key line.
+ *
+ * Stopping is always a graceful teardown — the child reaps its process tree and reports a verdict
+ * — and nothing here exits or moves on before that verdict. `esc` stops and returns to the
+ * picker; `ctrl+c` stops and then quits, and quits straight away from the picker.
+ */
+export function App({ client, onExit, oms: initialOms, warnings: initialWarnings = [], }) {
     const { exit } = useApp();
     const [oms, setOms] = useState(initialOms ?? []);
-    const [session, setSession] = useState(null);
-    // A per-run RunModel folds the log stream into a capped milestone tail plus a live node summary;
-    // these snapshots are what the view renders. The cap is what keeps a long run from growing forever.
-    const [lines, setLines] = useState([]);
-    const [status, setStatus] = useState();
+    const [discovering, setDiscovering] = useState(false);
+    const [chunks, setChunks] = useState([]);
+    const [current, setCurrent] = useState();
+    const [phase, setPhase] = useState("running");
+    const [upAt, setUpAt] = useState();
+    const [nodes, setNodes] = useState([]);
+    const [summary, setSummary] = useState();
     const [prompt, setPrompt] = useState();
-    const [verdict, setVerdict] = useState();
-    const [tearing, setTearing] = useState(false);
-    // Refs so the Ctrl+C handler always sees the live session/verdict, not a stale render closure.
-    const sessionRef = useRef(null);
-    const verdictRef = useRef(undefined);
-    const tearingRef = useRef(false);
+    const [last, setLast] = useState();
+    const [quitting, setQuitting] = useState(false);
+    // Refs so key handlers and session callbacks see live values, not a stale render closure.
+    const currentRef = useRef(undefined);
+    const phaseRef = useRef("running");
+    const quitRef = useRef(false);
+    const lastRef = useRef(undefined);
+    const omsRef = useRef(initialOms ?? []);
+    const warningsRef = useRef(initialWarnings.join("\n"));
+    const chunkId = useRef(0);
+    const mounted = useRef(true);
     const redrawTimer = useRef(undefined);
+    const say = (lines) => {
+        if (lines.length === 0)
+            return;
+        const chunk = { id: chunkId.current++, lines };
+        setChunks((c) => [...c, chunk]);
+    };
+    const enterPhase = (p) => {
+        phaseRef.current = p;
+        setPhase(p);
+    };
     const stopRedraw = () => {
         redrawTimer.current?.stop();
         redrawTimer.current = undefined;
     };
     // The redraw timer holds the event loop open, so it must not outlive the app — an unmount
     // for any reason other than the run settling would otherwise keep the CLI from exiting.
-    useEffect(() => stopRedraw, []);
-    useEffect(() => {
-        if (initialOms)
-            return; // provided by the caller's pre-flight discovery
-        let live = true;
-        void client.discover().then((r) => {
-            if (live)
-                setOms(r.oms);
+    useEffect(() => () => {
+        mounted.current = false;
+        stopRedraw();
+    }, []);
+    /**
+     * Scan for oms again — after every run, since the om files may have changed while it ran. The
+     * old list stays usable meanwhile, and stays put if the scan fails: a broken edit is reported,
+     * not a reason to empty the picker.
+     */
+    const rediscover = () => {
+        setDiscovering(true);
+        void client
+            .discover()
+            .then((registry) => {
+            if (!mounted.current)
+                return;
+            omsRef.current = registry.oms;
+            setOms(registry.oms);
+            const key = registry.warnings.join("\n");
+            if (key !== warningsRef.current) {
+                warningsRef.current = key;
+                say(registry.warnings.map((w) => ({ text: `⚠ ${w}`, color: "yellow" })));
+            }
+        })
+            .catch((err) => {
+            if (!mounted.current)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            say([{ text: `✗ discovery failed — keeping the previous list: ${message}`, color: "red" }]);
+        })
+            .finally(() => {
+            if (mounted.current)
+                setDiscovering(false);
         });
-        return () => {
-            live = false;
-        };
-    }, [client, initialOms]);
+    };
+    useEffect(() => {
+        if (!initialOms)
+            rediscover();
+        // first scan only; later ones follow runs
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const quit = () => {
+        onExit?.(lastRef.current?.verdict);
+        exit();
+    };
+    /** The run settled: its verdict and recap go to the scrollback, then the picker comes back. */
+    const finish = (cur, v) => {
+        const stopped = phaseRef.current === "stopping";
+        const took = formatDuration(Date.now() - cur.startedAt);
+        const [icon, word, color] = !v.ok
+            ? ["✗", "failed", "red"]
+            : stopped
+                ? ["⊘", "stopped", "yellow"]
+                : ["✓", "ok", "green"];
+        say([
+            { text: `${icon} ${cur.om.name} · ${word} · ${took}`, color, bold: true },
+            ...recapLines(v.summary),
+            { text: " " }, // a blank line before the next run's rule; Ink drops an empty one
+        ]);
+        const done = { om: cur.om, verdict: v };
+        lastRef.current = done;
+        setLast(done);
+        currentRef.current = undefined;
+        setCurrent(undefined);
+        setPrompt(undefined);
+        setNodes([]);
+        setSummary(undefined);
+        setUpAt(undefined);
+        enterPhase("running");
+        if (quitRef.current) {
+            quit();
+            return;
+        }
+        rediscover();
+    };
     const run = (om) => {
+        if (currentRef.current)
+            return;
         const model = new RunModel();
-        const s = client.run(om.file);
-        sessionRef.current = s;
+        const startedAt = Date.now();
+        say([{ text: om.name, bold: true, rule: { right: clock(startedAt) } }]);
+        const session = client.run(om.file);
+        const cur = { om, session, startedAt };
+        currentRef.current = cur;
+        enterPhase("running");
         // Every entry lands in the model immediately; the screen catches up on its own cadence.
         // `dirty` keeps an idle run from redrawing over nothing — see REDRAW_MS for why the two
-        // are separated at all.
+        // are separated at all. Scrollback lines (see shellLine for which entries earn one) wait in
+        // `pending` and reach the scrollback as one chunk per tick.
         let dirty = false;
+        let tearingDown = false;
+        const pending = [];
         const redraw = () => {
             if (!dirty)
                 return;
             dirty = false;
-            setLines(model.milestones());
-            setStatus(model.summary());
+            setNodes(model.nodes());
+            setSummary(model.summary());
+            say(pending.splice(0));
         };
         redrawTimer.current = redrawLoop(redraw, REDRAW_MS);
-        s.on("log", (entry) => {
+        session.on("log", (entry) => {
             model.apply(entry);
+            // the run narrates its own teardown — a stop, or the end of a body that left daemons up
+            if (entry.level === "run" && entry.message.startsWith("tearing down"))
+                tearingDown = true;
+            const line = shellLine(entry, model.node(entry.nodeId), tearingDown);
+            if (line)
+                pending.push(line);
             dirty = true;
         });
         // A prompt blocks the child until it's answered, so it must not wait for the next tick —
         // and the milestones that led to it are the context the question is read in.
-        s.on("prompt", (req) => {
+        session.on("prompt", (req) => {
             redraw();
             setPrompt(req);
         });
         // The child gave up on the prompt (timed out or torn down). Withdraw its box so a stale,
         // unanswerable prompt doesn't linger — but only if it's still the one on screen, so a late
         // withdrawal can't clobber a fresh prompt.
-        s.on("promptDone", (id) => setPrompt((p) => (p?.id === id ? undefined : p)));
-        s.on("settled", (v) => {
-            redraw(); // the run's closing milestones, before its verdict
-            setVerdict(v);
-            setPrompt(undefined);
+        session.on("promptDone", (id) => setPrompt((p) => (p?.id === id ? undefined : p)));
+        // The body returned with something still running: a stack that stays up until stopped.
+        // A body cut short by a stop returns too, and reports `up` on its way down — not a stack up.
+        session.on("up", () => {
+            if (phaseRef.current === "stopping")
+                return;
+            const at = Date.now();
+            pending.push({ text: `  ● up · ${formatDuration(at - startedAt)}`, color: "green" });
+            dirty = true;
+            setUpAt(at);
+            enterPhase("up");
         });
-        // The single exit point. `result` resolves when the run ends — a natural completion (a build
-        // that settles on its own), a teardown after Ctrl+C, or a crash that closes the channel — and
-        // stays pending for a live daemon stack until Ctrl+C. Record the verdict, hand it to the caller
-        // so it can print the durable summary block, and unmount. Without this a self-completing run
-        // would show its verdict line but never exit or render the summary.
-        void s.result.then((v) => {
+        // The single end of a run: a natural completion, a teardown after a stop, or a crash that
+        // closes the channel. A live stack never gets here on its own — only after a stop.
+        void session.result.then((v) => {
             stopRedraw();
+            dirty = true;
             redraw(); // last pass: whatever arrived since the final tick
-            verdictRef.current = v;
-            setVerdict(v);
-            onExit?.(v);
-            exit();
+            if (mounted.current)
+                finish(cur, v);
         });
-        setSession(s);
+        setCurrent(cur);
     };
-    const answer = (value) => {
-        if (session && prompt)
-            session.answer(prompt.id, value);
-        setPrompt(undefined);
+    /** Ask the run to tear down. Idempotent: the child owns the teardown and reports when done. */
+    const stop = (thenQuit) => {
+        const cur = currentRef.current;
+        if (!cur)
+            return;
+        if (thenQuit && !quitRef.current) {
+            quitRef.current = true;
+            setQuitting(true);
+        }
+        if (phaseRef.current === "stopping")
+            return;
+        enterPhase("stopping");
+        cur.session.cancel();
     };
-    // Ctrl+C: in raw mode this is a keystroke, not a signal. Cancel the run and wait for the child
-    // to tear down and report its verdict, then quit — leaving the durable summary to `onExit`.
-    //
-    // Repeated presses are a deliberate no-op (see the `tearing` guard below): the child owns the
-    // teardown and is guaranteed to report `settled` within its grace window, so we let it finish
-    // rather than force-exiting. This mirrors the normal om run, where SIGINT is caught with
-    // `process.on` and smashing Ctrl+C just re-triggers an idempotent teardown — the process never
-    // exits before the tree is reaped. Force-exiting here (the old second-press escape hatch) killed
-    // the parent mid-teardown and orphaned the child's process tree (vite, watchers, Chrome).
-    useInput((input, key) => {
-        if (!(key.ctrl && input === "c"))
+    const rerun = () => {
+        const prev = lastRef.current;
+        if (!prev)
             return;
-        const s = sessionRef.current;
-        // Nothing running or already settled → quit now.
-        if (!s || verdictRef.current) {
-            onExit?.(verdictRef.current);
-            exit();
+        // Rerun what discovery still finds; the run itself reads the current code either way.
+        const om = omsRef.current.find((o) => sameOm(o, prev.om));
+        if (!om) {
+            say([{ text: `⚠ ${prev.om.name} is no longer discovered — not rerunning`, color: "yellow" }]);
             return;
         }
-        // Already tearing down → ignore. The child is reaping its tree and will report `settled` (or
-        // the channel closes and resolves a failed verdict); either way `result` resolves and the
-        // handler wired in `run()` records the verdict and unmounts. Just request the teardown here.
-        if (tearingRef.current)
+        run(om);
+    };
+    const openReport = () => {
+        const folder = lastRef.current?.verdict.folder;
+        const file = folder ? path.join(folder, "report.html") : undefined;
+        if (!file || !fs.existsSync(file)) {
+            say([{ text: "⚠ the last run wrote no report.html", color: "yellow" }]);
+            return;
+        }
+        openFile(file).then(() => say([{ text: `↗ ${file}`, dim: true }]), (err) => say([
+            {
+                text: `✗ could not open ${file}: ${err instanceof Error ? err.message : String(err)}`,
+                color: "red",
+            },
+        ]));
+    };
+    // In raw mode Ctrl+C is a keystroke, not a signal. During a run every stop key only *requests*
+    // the teardown: repeated presses are a deliberate no-op, and nothing exits before the child has
+    // reaped its tree and reported — force-exiting mid-teardown would orphan its process tree
+    // (vite, watchers, Chrome). This mirrors a bare om run, where SIGINT re-triggers an idempotent
+    // teardown and the process never exits before the tree is reaped.
+    useInput((input, key) => {
+        const running = currentRef.current !== undefined;
+        if (key.ctrl && input === "c") {
+            if (running)
+                stop(true);
+            else
+                quit();
+            return;
+        }
+        if (running) {
+            // with a prompt up, esc belongs to the prompt (it clears a choice search)
+            if (key.escape && !prompt)
+                stop(false);
             return;
-        tearingRef.current = true;
-        setTearing(true);
-        s.cancel();
+        }
+        if (key.ctrl && input === "r")
+            rerun();
+        else if (key.ctrl && input === "o")
+            openReport();
     });
-    if (!session)
-        return _jsx(OmList, { oms: oms, onSelect: run });
-    return (_jsxs(_Fragment, { children: [_jsx(RunView, { lines: lines, status: status, prompt: prompt, verdict: verdict, onAnswer: answer }), !verdict && tearing ? _jsx(Spinner, { label: "tearing down\u2026 (stopping the run cleanly)" }) : null, !verdict && !tearing && !prompt ? _jsx(Spinner, { label: "running\u2026" }) : null] }));
+    const hint = current
+        ? phase === "stopping"
+            ? `stopping cleanly — waiting for the run to tear down${quitting ? ", then quitting" : ""}`
+            : prompt
+                ? "enter answer · ctrl+c stop and quit"
+                : "esc stop · ctrl+c stop and quit"
+        : [
+            "↑↓ move · enter run",
+            last ? `ctrl+r rerun ${last.om.name} · ctrl+o report` : "",
+            "ctrl+c quit",
+        ]
+            .filter(Boolean)
+            .join(" · ");
+    return (_jsxs(_Fragment, { children: [_jsx(Scrollback, { chunks: chunks }), current ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(RunView, { name: current.om.name, phase: phase, startedAt: current.startedAt, upAt: upAt, nodes: nodes, summary: summary, prompt: prompt, onAnswer: (value) => {
+                            if (prompt)
+                                current.session.answer(prompt.id, value);
+                            setPrompt(undefined);
+                        } }), _jsx(Text, { dimColor: true, children: hint })] })) : (_jsx(OmList, { oms: oms, onSelect: run, hint: hint, status: discovering ? _jsx(Spinner, { label: "rediscovering\u2026" }) : undefined }))] }));
 }

package/dist/cli/ui/openFile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Open `file` with the OS's default handler (a browser, for `report.html`) without waiting on it.
+ * Resolves once the opener has launched, or rejects with why it couldn't — a Linux box without
+ * `xdg-open`, say — so the caller can say so instead of the key press doing nothing.
+ */
+export declare function openFile(file: string): Promise<void>;

package/dist/cli/ui/openFile.js

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+/**
+ * Open `file` with the OS's default handler (a browser, for `report.html`) without waiting on it.
+ * Resolves once the opener has launched, or rejects with why it couldn't — a Linux box without
+ * `xdg-open`, say — so the caller can say so instead of the key press doing nothing.
+ */
+export function openFile(file) {
+    const [cmd, args] = process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", file]]
+        : process.platform === "darwin"
+            ? ["open", [file]]
+            : ["xdg-open", [file]];
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}

package/dist/cli/ui/views/OmList.d.ts

@@ -1,4 +1,4 @@
-import { type ReactElement } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { DiscoveredOm } from "../../../client/registry.ts";
 /**
  * The picker: a searchable, arrow-navigable list of oms; Enter runs the highlighted one.
@@ -10,8 +10,15 @@ import type { DiscoveredOm } from "../../../client/registry.ts";
  * Rows are ordered by {@link byNesting} from the working directory — the same root the paths
  * are rendered from, so the oms nearest the top of the project come first, deeper ones after,
  * and any shown as an absolute path last.
+ *
+ * `status` goes on the header line (the shell's "rediscovering…"), and `hint` replaces the key
+ * line under the list, for a caller that binds more keys than the list does.
  */
-export declare function OmList({ oms, onSelect, }: {
+export declare function OmList({ oms, onSelect, status, hint, }: {
     oms: DiscoveredOm[];
     onSelect: (om: DiscoveredOm) => void;
+    status?: ReactNode;
+    hint?: string;
 }): ReactElement;
+/** A description key as a label: `docsUrl` / `docs-url` / `docs_url` → `Docs url`. */
+export declare function labelOf(key: string): string;