omkit 0.2.2 → 0.4.1

package/README.md

@@ -1,5 +1,8 @@
 # omkit
 
+[![npm version](https://badge.fury.io/js/omkit.svg)](https://www.npmjs.com/package/omkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 **The operational-model kit.** _Humans orchestrate. Runs narrate. AI assistants follow along._
 
 A tiny runtime for the workflows _around_ your code — start servers, wait for health checks, build, watch, drive a browser, read state back, and tear it all down together. You write the orchestration as ordinary TypeScript; the run **narrates itself** into a structured, on-disk record — what launched, what came up, what attached, what failed, what the world actually looked like — that an AI assistant can read instead of guessing from terminal scrollback. Where [tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer (what your system **is**), `omkit` is the _operational_ one (what it's **doing right now**).
@@ -14,22 +17,23 @@ Now hand that same script to an AI assistant. It has it even worse: interleaved
 
 ```ts
 import { om } from "omkit";
-import { command, healthcheck, chromePage } from "omkit/actions";
-
-// Define once. `command` names the action after the command; calling it launches.
-const api = command("npm run dev", { cwd: "api" });
-const web = command("npm run dev", { cwd: "web" });
+import { command, healthcheck, browser, chromePage } from "omkit/actions";
 
 om("dev", async () => {
-  api().tag("api"); // start both dev servers as daemons…
-  web().tag("web");
+  // `command` names the action after the command and launches it — a normal action call.
+  command("npm run dev", { cwd: "api" }).tag("api"); // start both dev servers as daemons…
+  command("npm run dev", { cwd: "web" }).tag("web");
 
   // …wait until the app actually serves (not just "process started")…
-  const up = await healthcheck({ url: "http://localhost:3000" }).result;
-  if (!up.ok) return; // gave up — the servers stay up so you can debug them
-
-  // …then open it in a real browser and hand the live page downstream — typed, not scraped.
-  const page = chromePage("app", "localhost:9222", { url: "http://localhost:3000" });
+  try {
+    await healthcheck({ url: "http://localhost:3000" }).result;
+  } catch {
+    return; // never came up — the servers stay up so you can debug them
+  }
+
+  // …then launch a real browser and hand its live page downstream — typed, not scraped.
+  const chrome = browser({ headless: false }); // a visible Chromium, closed on teardown
+  const page = chromePage("app", chrome.ref, { url: "http://localhost:3000" });
   console.log(`opened ${(await page.ref).url()}`);
 
   console.log("stack is up — press Ctrl+C to stop");
@@ -41,12 +45,13 @@ om("dev", async () => {
 ```
                       om()
                        │
-      ┌────────────────┼────────────────┐
-      ▼                ▼                 ▼
-   command          healthcheck      chromePage
-  api · web           (gate)           │ .ref  → live Page
-  (daemons)                            ▼
-                                  your smoke test
+      ┌───────────┬────┴──────┬──────────────────┐
+      ▼           ▼           ▼                   ▼
+   command    healthcheck  browser  ──ref──▶  chromePage
+  api · web     (gate)     (launch)           .ref → live Page
+  (daemons)                                         │
+                                                    ▼
+                                            your smoke test
 ```
 
 ## Who it's for
@@ -69,11 +74,11 @@ const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 const activity = build(); // calling launches; returns the live Activity
 ```
 
-`om(name, async (ctx) => …)` hosts the orchestration as the root of a run. The name plus the file it's defined in identify the run — logs land in `logs/<name>-<hash8>/…`, so same-named oms in different files never share a folder. You write ordinary `await` / `if` / loops / variables; the Activities you launch keep running in parallel, and because the body stays in-flight while you `await`, the run never idles shut between steps. Config chained on an Activity before your first `await` (like `withCache`) applies before its body runs. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
+`om(name, async (ctx) => …)` hosts the orchestration as the root of a run. The name plus the file it's defined in identify the run — logs land in `logs/<name>-<hash8>/…`, so same-named oms in different files never share a folder. You write ordinary `await` / `if` / loops / variables; the Activities you launch keep running in parallel, and because the body stays in-flight while you `await`, the run never idles shut between steps. Config chained synchronously on an Activity right after launching it (like `withCache`) applies before its body runs — the body commits one microtask later, so chain it in the same tick, before you `await`. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
 
 ### Typed capabilities
 
-An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor scraped from a log: a typed runtime handoff, so steps chain without globals or string-parsing.
+An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor scraped from a log: a typed runtime handoff, so steps chain without globals or string-parsing. The first `attach` wins; later ones are ignored. Unlike `.result`, `.ref` **rejects** on failure or cancellation — a consumer waiting on a capability that never arrives fails instead of hanging — and an action that publishes nothing still resolves its `.ref` with `undefined` on success, so awaiting it never wedges.
 
 ```ts
 const server = action("server")
@@ -92,32 +97,34 @@ om("migrate", async () => {
 });
 ```
 
-### Outcomes — a result that doesn't throw
+### Results — one promise that rejects on failure
 
-Every Activity settles to a typed **`Outcome`**, read via `activity.result`, which **never throws**. Operational failures are values you inspect, not exceptions you catch:
+An Activity's **`.result`** resolves the value on success and **rejects** on failure — the same reject-on-failure shape as `.ref` and `.once`. A failure you want to branch on is a `try/catch`; one you want to note without stopping is a `.catch`. Reading `.result` also _observes_ the Activity (see teardown), so a handled failure doesn't tear the run down:
 
 ```ts
-type Outcome<T> = { ok: true; value: T } | { ok: false; error: unknown };
-
-const tests = await command("npm test")().result;
-if (!tests.ok) {
-  // red tests are an expected outcome here — decide what to do, don't crash
+try {
+  await command("npm test").result; // resolves on green, throws on red
+} catch (err) {
+  // red tests are an expected outcome here — decide what to do
 }
+
+// …or handle it inline, without stopping:
+await command("npm test").result.catch((err) => report(err));
 ```
 
-Awaiting `.result` also _observes_ the Activity (see teardown). A cancelled Activity resolves `{ ok: false, error: CancelledError }`.
+A cancelled Activity rejects with `CancelledError` — `isCancelled(err)` tells an intentional stop apart from a real fault.
 
 ### Failure & teardown
 
-omkit uses **structured supervision**: a failure that **nobody is watching** tears the whole run down and marks it failed. An Activity is "watched" if — before it fails — you awaited its `.result` (or `.ref`), added an `on("error")` listener, or attached `.handleFailure`.
+omkit uses **structured supervision**: a failure that **nobody is watching** tears the whole run down and marks it failed. An Activity is "watched" if — before it fails — you awaited its `.result`/`.ref`/`.once`, attached a `.result.catch`, or added an `on("error")` listener.
 
-- **Await it** (`await task().result`) → the failure is yours to inspect as `{ ok: false }`; the run stays green.
+- **Await it** (`await task().result`) → a failure throws at the `await`, in your body; wrap it in `try/catch` to branch. The run stays green because you observed it.
 - **Fire-and-forget it** (`task()`, never awaited) → an unobserved crash tears the run down. This is the guardrail for daemons: a dev server that dies fails the run instead of leaving it wedged.
-- **`.handleFailure(fn)`** → own a fire-and-forget Activity's failure: `fn(error)` runs instead of tearing down.
+- **`.result.catch(fn)`** → own a fire-and-forget Activity's failure: reading `.result` observes it, and `fn(error)` runs instead of tearing the run down (it also fires on cancel — guard with `isCancelled` if that matters).
 
 ```ts
-web().tag("web"); // if the web daemon crashes, the run tears down — you'll know
-flakyBackgroundJob().handleFailure((e) => console.warn("job failed, carrying on", e));
+command("npm run dev", { cwd: "web" }).tag("web"); // if it crashes, the run tears down — you'll know
+flakyBackgroundJob().result.catch((e) => console.warn("job failed, carrying on", e));
 ```
 
 **Ctrl+C** and **`ctx.cancel()`** tear everything down gracefully — procs are killed, waits unblock, the log is always written. And **success is keep-alive**: when your `om` body returns, the daemons it started keep running until Ctrl+C or `cancel()`, so wiring things up doesn't kill the servers you just started.
@@ -148,7 +155,7 @@ const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 
 om("build", async () => {
   const out = await build().withCache(`${process.cwd()}/src`).result;
-  if (out.ok && out.value === undefined) console.log("no changes — skipped the build");
+  if (out === undefined) console.log("no changes — skipped the build");
 });
 ```
 
@@ -164,13 +171,16 @@ om("watch", async () => {
 });
 ```
 
-**Gate a deploy on green tests.** Observe the outcome and branch — no try/catch:
+**Gate a deploy on green tests.** A red test rejects at the `await`; catch it to branch:
 
 ```ts
 om("ship", async () => {
-  const tests = await command("npm test")().result;
-  if (!tests.ok) return; // red → stop; the run stays green because you observed it
-  await command("./deploy.sh")().result;
+  try {
+    await command("npm test").result; // resolves on green, throws on red
+  } catch {
+    return; // red → stop; the run stays green because you observed the failure
+  }
+  await command("./deploy.sh").result;
 });
 ```
 
@@ -187,7 +197,7 @@ om("deploy", async () => {
     default: "no",
     timeoutMs: 10_000, // no answer in 10s → "no"
   }).result;
-  if (answer.ok && answer.value === "yes") await command("./deploy.sh")().result;
+  if (answer === "yes") await command("./deploy.sh").result;
 });
 ```
 
@@ -196,8 +206,8 @@ om("deploy", async () => {
 An Activity exposes its declared events plus the lifecycle ones (`done`, `error`, `attached`):
 
 - **`activity.on(event, handler)`** — subscribe to every emit.
-- **`activity.once(event)`** — a **promise** for the next emit; resolves `undefined` if the Activity settles first, so an `await` never hangs. A retained snapshot (like `healthy`) is replayed immediately even if you subscribe late.
-- **`activity.once("done")`** is the exception — it awaits the outcome itself: resolves the result on success, **rejects** on failure or cancellation (and observes the failure). That makes `await step().once("done")` a hard gate: a failed step throws at the `await`, in your body, instead of letting the orchestration sail past it. Use `.result` when a failure is an outcome you want to branch on rather than a stop.
+- **`activity.once(event)`** — a **promise** for the next emit. Resolves the payload when it fires; if the Activity settles first it resolves `undefined` on success and **rejects** on failure/cancel — so a gate on an event surfaces a failure instead of hanging. A retained snapshot (like `healthy`) is replayed immediately even if you subscribe late.
+- **`activity.once("done")`** is the outcome itself — identical to `.result` (resolve the value, reject on failure). `await step().once("done")` and `await step().result` are the same hard gate.
 
 ```ts
 const probe = healthcheck({ url: "http://localhost:3000" });
@@ -208,13 +218,26 @@ probe.on("healthy", (r) => console.log(`up after ${r.attempts} tries`));
 
 Reusable actions built on the core engine. For anything beyond these, drop down to `action(...).run(...)`.
 
-- **`command`** — define a shell-command action, named after the command; output streams to the log, killed on teardown.
+- **`command`** — run a shell command (or, with `args`, an executable) as an action named after it; output streams to the log, killed on teardown.
 - **`watch`** / **`watchDir`** — watch a file or directory for changes (survives wipe + recreate).
 - **`untilLog`** — gate on the first log entry matching a predicate.
 - **`tailLog`** — tail a file another process writes, folding its lines into the combined log.
 - **`healthcheck`** — poll a URL/port until the status (and optionally body) matches.
 - **`prompt`** — ask the terminal for input or a choice, with a timeout that falls back to a default; the answer is its handle.
-- **`chromePage`** — attach to Chrome over CDP — or to an existing Playwright `Page`/`Browser`/`Context`, including Electron windows — and expose the live `Page` as a handle.
+- **`browser`** — launch a Chromium browser with Playwright and expose the live `Browser` as a handle (defaults to the installed Chrome); closed on teardown. Feed its `.ref` to `chromePage`.
+- **`chromePage`** — attach to Chrome over CDP, or to an existing Playwright `Page`/`Browser`/`Context` (including a `browser` handle or an Electron window), and expose the live `Page` as a handle.
+
+## CLI
+
+Point the `omkit` bin at a project — a `tsconfig.omkit.json` that lists your `oms/` and `actions/` — and it discovers, typechecks, and runs them. (Override the config path with `--tsconfig`.)
+
+- **`omkit init`** — scaffold a starter project: `tsconfig.omkit.json`, a sample `oms/dev.ts`, and `actions/hello.ts`.
+- **`omkit run`** — with no argument, open the interactive picker: browse and search your oms, run one, and watch its milestones stream live — answering any `prompt` in-console. A bare `omkit` does the same (`run` is the default command).
+- **`omkit run <om>`** — run one om directly by name or file path, inheriting the terminal.
+- **`omkit ls`** — list the discovered oms and actions.
+- **`omkit check`** — typecheck the project (`tsc --noEmit`) and report diagnostics.
+
+Each run is supervised in its own child process and narrated to a run folder (see above), whether you launch it from the picker or with `run <om>`.
 
 ## Install
 

package/dist/actions/browser.d.ts

@@ -0,0 +1,28 @@
+import { type Browser } from "playwright-core";
+export type { Browser } from "playwright-core";
+export interface BrowserOptions {
+    /** Run without a visible window. Default false — the browser is visible. */
+    headless?: boolean;
+    /**
+     * Which Chromium to launch. Defaults to the installed Google Chrome (`"chrome"`):
+     * playwright-core ships no bundled browser, so a channel (or {@link executablePath})
+     * is what lets `launch` succeed without a separate `playwright install`. Pass an
+     * empty string to use a bundled Chromium instead.
+     */
+    channel?: string;
+    /** Absolute path to a browser executable, overriding {@link channel}. */
+    executablePath?: string;
+    /** Extra flags for the browser process (e.g. `"--start-maximized"`). */
+    args?: string[];
+}
+/**
+ * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
+ * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
+ * so teardown closes it. Replaces the external chromedriver/WebDriver dance.
+ *
+ * Daemon-shaped: launch + attach, stay alive until the run's `signal` aborts, then close
+ * the browser (bounded by a short race, so a wedged `close()` can't stall teardown).
+ */
+export declare const browser: import("../index.ts").Action<[opts?: BrowserOptions | undefined], void, import("../core/types.ts").NoEvents, Browser>;

package/dist/actions/browser.js

@@ -0,0 +1,36 @@
+import { chromium } from "playwright-core";
+import { action } from "../core/action.js";
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
+ * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
+ * so teardown closes it. Replaces the external chromedriver/WebDriver dance.
+ *
+ * Daemon-shaped: launch + attach, stay alive until the run's `signal` aborts, then close
+ * the browser (bounded by a short race, so a wedged `close()` can't stall teardown).
+ */
+export const browser = action("browser")
+    .ref()
+    .run(async ({ signal, attach }, opts = {}) => {
+    const { headless = false, channel = "chrome", executablePath, args } = opts;
+    const launchOpts = { headless, args };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    else if (channel)
+        launchOpts.channel = channel;
+    const launched = await chromium.launch(launchOpts);
+    console.log(`launched ${executablePath || channel || "chromium"}${headless ? " (headless)" : ""}`);
+    attach(launched); // resolves instance.ref → the live Browser
+    // Daemon: hold the browser open until teardown, then close it (it's ours to close).
+    return new Promise((resolveRun) => {
+        const stop = () => {
+            void Promise.race([launched.close(), delay(2000)]).finally(resolveRun);
+        };
+        if (signal.aborted)
+            stop();
+        else
+            signal.addEventListener("abort", stop, { once: true });
+    });
+});

package/dist/actions/command.d.ts

@@ -13,12 +13,16 @@ export interface CommandOptions {
     inheritDebugger?: boolean;
 }
 /**
- * Defines a command action, named after the command itself (add a semantic label with
- * `.tag(...)`). Call the returned action to launch it.
- *
- * By default the command is executed through the shell.
+ * The action name a command runs under: the shell string itself, or `file arg1 arg2`
+ * for the direct-exec form. Exposed so the naming rule stays independently checkable.
+ */
+export declare function commandName(cmdOrFile: string, options?: CommandOptions): string;
+/**
+ * Launches a command as an action, named after the command itself (add a semantic label
+ * with `.tag(...)`), and returns the live instance — a normal action call, no extra `()`.
+ * Must run inside an `om(...)` body, like any other action.
  *
- * If `options.args` is provided, `cmdOrFile` is treated as an executable and
- * launched directly without a shell.
+ * By default the command is executed through the shell. If `options.args` is provided,
+ * `cmdOrFile` is treated as an executable and launched directly without a shell.
  */
-export declare function command(cmdOrFile: string, options?: CommandOptions): import("../index.ts").Action<[], import("zx").ProcessOutput, import("../core/types.ts").NoEvents, void> | import("../index.ts").Action<[], void, import("../core/types.ts").NoEvents, void>;
+export declare function command(cmdOrFile: string, options?: CommandOptions): import("../index.ts").Activity<import("zx").ProcessOutput, import("../core/types.ts").NoEvents, void> | import("../index.ts").Activity<void, import("../core/types.ts").NoEvents, void>;

package/dist/actions/command.js

@@ -7,29 +7,35 @@ import { debuggerFreeEnv, killTree, streamLines } from "../system/proc.js";
  */
 const verbatim = (cmd) => Object.assign([cmd], { raw: [cmd] });
 /**
- * Defines a command action, named after the command itself (add a semantic label with
- * `.tag(...)`). Call the returned action to launch it.
- *
- * By default the command is executed through the shell.
+ * The action name a command runs under: the shell string itself, or `file arg1 arg2`
+ * for the direct-exec form. Exposed so the naming rule stays independently checkable.
+ */
+export function commandName(cmdOrFile, options = {}) {
+    return options.args === undefined ? cmdOrFile : [cmdOrFile, ...options.args].join(" ");
+}
+/**
+ * Launches a command as an action, named after the command itself (add a semantic label
+ * with `.tag(...)`), and returns the live instance — a normal action call, no extra `()`.
+ * Must run inside an `om(...)` body, like any other action.
  *
- * If `options.args` is provided, `cmdOrFile` is treated as an executable and
- * launched directly without a shell.
+ * By default the command is executed through the shell. If `options.args` is provided,
+ * `cmdOrFile` is treated as an executable and launched directly without a shell.
  */
 export function command(cmdOrFile, options = {}) {
     const cwd = path.resolve(options.cwd ?? ".");
+    const name = commandName(cmdOrFile, options);
     // Shell command — the command string is the action (and proc) name.
     if (options.args === undefined) {
-        return action(cmdOrFile).run((ctx) => ctx.proc(cmdOrFile, {
+        return action(name).run((ctx) => ctx.proc(cmdOrFile, {
             cwd,
             ...(options.env && { env: options.env }),
             ...(options.inheritDebugger && {
                 inheritDebugger: true,
             }),
-        })(verbatim(cmdOrFile)));
+        })(verbatim(cmdOrFile)))();
     }
     // Direct executable — the file plus its args form the action name.
     const args = options.args;
-    const name = [cmdOrFile, ...args].join(" ");
     return action(name).run(async (ctx) => {
         const inherit = options.inheritDebugger;
         const env = inherit
@@ -77,5 +83,5 @@ export function command(cmdOrFile, options = {}) {
             finished = true;
             ctx.signal.removeEventListener("abort", onAbort);
         }
-    });
+    })();
 }

package/dist/actions/index.d.ts

@@ -18,3 +18,5 @@ export { prompt } from "./prompt.ts";
 export type { PromptOptions, InputPromptOptions, ChoicePromptOptions, PromptChoice, PromptVia, PromptEvents, } from "./prompt.ts";
 export { chromePage } from "./chrome-page.ts";
 export type { ChromePageOptions, ChromePageEvents, ChromePageSource, Page, Browser, BrowserContext, } from "./chrome-page.ts";
+export { browser } from "./browser.ts";
+export type { BrowserOptions } from "./browser.ts";

package/dist/actions/index.js

@@ -10,3 +10,4 @@ export { watchDir } from "./watch-dir.js";
 export { tailLog } from "./tail-log.js";
 export { prompt } from "./prompt.js";
 export { chromePage } from "./chrome-page.js";
+export { browser } from "./browser.js";

package/dist/actions/prompt.js

@@ -1,6 +1,39 @@
 import { createInterface } from "node:readline/promises";
 import { action } from "../core/action.js";
+import { activeSupervisor } from "../core/interaction.js";
 const asChoices = (choices) => choices.map((c) => (typeof c === "string" ? { label: c, value: c } : c));
+/** Route the request over the supervisor channel, resolving the raw answer against the choices. */
+async function askSupervisor(supervisor, ctx, waitSignal) {
+    const { opts, message, defaultValue, resolveRaw } = ctx;
+    const spec = {
+        kind: opts.kind === "choice" ? "choice" : "input",
+        message,
+        default: defaultValue,
+        ...(opts.kind === "choice" ? { choices: asChoices(opts.choices) } : {}),
+    };
+    const answer = await supervisor.request(spec, waitSignal);
+    const resolved = resolveRaw(answer.value);
+    if (resolved === undefined)
+        return { value: defaultValue, via: "default" };
+    return { value: resolved, via: answer.via ?? "input" };
+}
+/** Read the answer straight from the terminal (the bare, unsupervised path). */
+async function askTerminal(query, resolveRaw, defaultValue, waitSignal) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const raw = (await rl.question(query, { signal: waitSignal })).trim();
+        if (raw === "")
+            return { value: defaultValue, via: "default" };
+        const resolved = resolveRaw(raw);
+        if (resolved !== undefined)
+            return { value: resolved, via: "input" };
+        console.log(`invalid answer "${raw}", using default`);
+        return { value: defaultValue, via: "default" };
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * Asks the terminal a question — free-text **input** or a **choice** — and resolves
  * with the answer, which it also attaches as the handle (`prompt(...).ref` feeds
@@ -47,25 +80,19 @@ export const prompt = action("prompt")
     emit("prompt", message);
     const onTimeout = new AbortController();
     const timer = finite ? setTimeout(() => onTimeout.abort(), timeoutMs) : undefined;
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const waitSignal = AbortSignal.any([signal, onTimeout.signal]);
     let value = defaultValue;
     let via = "default";
+    const supervisor = activeSupervisor();
     try {
-        const raw = (await rl.question(query, { signal: AbortSignal.any([signal, onTimeout.signal]) })).trim();
-        if (raw === "") {
-            via = "default";
-        }
-        else {
-            const resolved = resolveRaw(raw);
-            if (resolved !== undefined) {
-                value = resolved;
-                via = "input";
-            }
-            else {
-                console.log(`invalid answer "${raw}", using default`);
-                via = "default";
-            }
-        }
+        // Supervised: hand off to whoever owns the terminal (Ink app / MCP client). Bare: read
+        // the terminal directly. Either way the child keeps the timeout via `waitSignal`, so a
+        // silent supervisor (or nobody) can't wedge the run.
+        const outcome = supervisor
+            ? await askSupervisor(supervisor, { opts, message, defaultValue, resolveRaw }, waitSignal)
+            : await askTerminal(query, resolveRaw, defaultValue, waitSignal);
+        value = outcome.value;
+        via = outcome.via;
     }
     catch {
         via = onTimeout.signal.aborted ? "timeout" : "default";
@@ -73,7 +100,6 @@ export const prompt = action("prompt")
     finally {
         if (timer)
             clearTimeout(timer);
-        rl.close();
     }
     console.log(via === "timeout" ? `timed out → ${value}` : `${value} (${via})`);
     attach(value); // resolves instance.ref → the answer

package/dist/cli/client/channel.d.ts

@@ -0,0 +1,14 @@
+import type { ChildMessage, SupervisorMessage } from "../../core/interaction.ts";
+import type { RunSession } from "./types.ts";
+/** The minimal duplex the channel needs — satisfied by a real ChildProcess or a fake. */
+export interface Transport {
+    send(message: SupervisorMessage): void;
+    onMessage(handler: (message: ChildMessage) => void): void;
+    onClose(handler: (code: number | null) => void): void;
+}
+/**
+ * Turn a child transport into a {@link RunSession}: fan `log`/`prompt` child messages out to
+ * handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down the wire. A
+ * close before `settled` resolves a failed verdict so `result` never hangs.
+ */
+export declare function createChannel(transport: Transport): RunSession;

package/dist/cli/client/channel.js

@@ -0,0 +1,48 @@
+/**
+ * Turn a child transport into a {@link RunSession}: fan `log`/`prompt` child messages out to
+ * handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down the wire. A
+ * close before `settled` resolves a failed verdict so `result` never hangs.
+ */
+export function createChannel(transport) {
+    const handlers = {
+        log: [],
+        prompt: [],
+        settled: [],
+    };
+    let settled = false;
+    let resolveResult;
+    const result = new Promise((resolve) => (resolveResult = resolve));
+    transport.onMessage((message) => {
+        if (message.kind === "log") {
+            for (const h of handlers.log)
+                h(message.entry);
+        }
+        else if (message.kind === "prompt") {
+            for (const h of handlers.prompt)
+                h({ id: message.id, spec: message.spec });
+        }
+        else if (message.kind === "settled") {
+            settled = true;
+            const verdict = { ok: message.ok, folder: message.folder, summary: message.summary };
+            for (const h of handlers.settled)
+                h(verdict);
+            resolveResult(verdict);
+        }
+    });
+    transport.onClose(() => {
+        if (!settled)
+            resolveResult({ ok: false, folder: "", summary: [] });
+    });
+    return {
+        on(event, handler) {
+            handlers[event].push(handler);
+        },
+        answer(id, value, via = "input") {
+            transport.send({ kind: "answer", id, value, via });
+        },
+        cancel() {
+            transport.send({ kind: "cancel" });
+        },
+        result,
+    };
+}

package/dist/cli/client/check.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from "./types.ts";
+/** Typecheck the project (`tsc --noEmit`) and return per-file diagnostics. */
+export declare function runCheck(tsconfigPath: string): Diagnostic[];

package/dist/cli/client/check.js

@@ -0,0 +1,32 @@
+import ts from "typescript";
+import path from "node:path";
+/** Typecheck the project (`tsc --noEmit`) and return per-file diagnostics. */
+export function runCheck(tsconfigPath) {
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error) {
+        return [{ file: tsconfigPath, line: 0, message: msg(configFile.error) }];
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.resolve(path.dirname(tsconfigPath)));
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: { ...parsed.options, noEmit: true },
+    });
+    const canonical = (f) => ts.sys.useCaseSensitiveFileNames ? path.normalize(f) : path.normalize(f).toLowerCase();
+    const fileSet = new Set(parsed.fileNames.map((f) => canonical(f)));
+    const out = [];
+    for (const sf of program.getSourceFiles()) {
+        if (!fileSet.has(canonical(sf.fileName)))
+            continue;
+        for (const d of [
+            ...program.getSyntacticDiagnostics(sf),
+            ...program.getSemanticDiagnostics(sf),
+        ]) {
+            const line = d.start !== undefined ? sf.getLineAndCharacterOfPosition(d.start).line + 1 : 0;
+            out.push({ file: sf.fileName, line, message: msg(d) });
+        }
+    }
+    return out;
+}
+function msg(d) {
+    return ts.flattenDiagnosticMessageText(d.messageText, "\n");
+}

package/dist/cli/client/discovery.d.ts

@@ -0,0 +1,8 @@
+import type { Registry } from "./registry.ts";
+/**
+ * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
+ * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
+ * project stays useful), but a **fatal config problem** — a missing, unparseable, or invalid
+ * tsconfig — throws, so the CLI crashes visibly instead of silently returning an empty project.
+ */
+export declare function discover(tsconfigPath: string): Registry;