omkit 0.2.1 → 0.4.0

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

@@ -0,0 +1,9 @@
+import { type ReactElement } from "react";
+import type { OmkitClient, Verdict } from "../client/types.ts";
+/** The interactive app: discover → list/search → run → live milestones + prompts. */
+export declare function App({ client, onExit, }: {
+    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. */
+    onExit?: (verdict: Verdict | undefined) => void;
+}): ReactElement;

package/dist/cli/ui/app.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { useApp, useInput } from "ink";
+import { format } from "../../output/milestones.js";
+import { OmList } from "./views/OmList.js";
+import { RunView } from "./views/RunView.js";
+import { Spinner } from "./Spinner.js";
+/** The interactive app: discover → list/search → run → live milestones + prompts. */
+export function App({ client, onExit, }) {
+    const { exit } = useApp();
+    const [oms, setOms] = useState([]);
+    const [session, setSession] = useState(null);
+    const [lines, setLines] = 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);
+    useEffect(() => {
+        let live = true;
+        void client.discover().then((r) => {
+            if (live)
+                setOms(r.oms);
+        });
+        return () => {
+            live = false;
+        };
+    }, [client]);
+    const run = (om) => {
+        const s = client.run(om.file);
+        sessionRef.current = s;
+        s.on("log", (entry) => {
+            const rendered = format(entry);
+            if (rendered)
+                setLines((prev) => [...prev, rendered.text]);
+        });
+        s.on("prompt", (req) => setPrompt(req));
+        s.on("settled", (v) => {
+            setVerdict(v);
+            setPrompt(undefined);
+        });
+        // 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) => {
+            verdictRef.current = v;
+            setVerdict(v);
+            onExit?.(v);
+            exit();
+        });
+        setSession(s);
+    };
+    const answer = (value) => {
+        if (session && prompt)
+            session.answer(prompt.id, value);
+        setPrompt(undefined);
+    };
+    // 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"))
+            return;
+        const s = sessionRef.current;
+        // Nothing running or already settled → quit now.
+        if (!s || verdictRef.current) {
+            onExit?.(verdictRef.current);
+            exit();
+            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)
+            return;
+        tearingRef.current = true;
+        setTearing(true);
+        s.cancel();
+    });
+    if (!session)
+        return _jsx(OmList, { oms: oms, onSelect: run });
+    return (_jsxs(_Fragment, { children: [_jsx(RunView, { lines: lines, 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] }));
+}

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

@@ -0,0 +1,9 @@
+import { type ReactElement } from "react";
+import type { DiscoveredOm } from "../../client/registry.ts";
+/** Case-insensitive substring filter on om names. */
+export declare function filterOms(oms: DiscoveredOm[], query: string): DiscoveredOm[];
+/** A searchable, arrow-navigable list of oms; Enter selects the highlighted one. */
+export declare function OmList({ oms, onSelect, }: {
+    oms: DiscoveredOm[];
+    onSelect: (om: DiscoveredOm) => void;
+}): ReactElement;

package/dist/cli/ui/views/OmList.js

@@ -0,0 +1,36 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+/** Case-insensitive substring filter on om names. */
+export function filterOms(oms, query) {
+    const q = query.toLowerCase();
+    return oms.filter((o) => o.name.toLowerCase().includes(q));
+}
+/** A searchable, arrow-navigable list of oms; Enter selects the highlighted one. */
+export function OmList({ oms, onSelect, }) {
+    const [query, setQuery] = useState("");
+    const [index, setIndex] = useState(0);
+    const filtered = filterOms(oms, query);
+    useInput((input, key) => {
+        if (key.upArrow) {
+            setIndex((i) => Math.max(0, i - 1));
+        }
+        else if (key.downArrow) {
+            setIndex((i) => Math.min(filtered.length - 1, i + 1));
+        }
+        else if (key.return) {
+            const picked = filtered[index];
+            if (picked)
+                onSelect(picked);
+        }
+        else if (key.backspace || key.delete) {
+            setQuery((q) => q.slice(0, -1));
+            setIndex(0);
+        }
+        else if (input && !key.ctrl && !key.meta) {
+            setQuery((q) => q + input);
+            setIndex(0);
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["search: ", query] }), filtered.map((o, i) => (_jsxs(Text, { inverse: i === index, children: [o.name, " ", o.file] }, o.name)))] }));
+}

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

@@ -0,0 +1,14 @@
+import { type ReactElement } from "react";
+import type { PromptRequest, Verdict } from "../../client/types.ts";
+/** Answer one pending prompt — free-text input, or arrow-navigable choices. */
+export declare function PromptView({ request, onAnswer, }: {
+    request: PromptRequest;
+    onAnswer: (value: string) => void;
+}): ReactElement;
+/** The live run surface: milestone lines, a pending prompt, and the final verdict. */
+export declare function RunView({ lines, prompt, verdict, onAnswer, }: {
+    lines: string[];
+    prompt?: PromptRequest;
+    verdict?: Verdict;
+    onAnswer: (value: string) => void;
+}): ReactElement;

package/dist/cli/ui/views/RunView.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { Box, Text, useInput } from "ink";
+/** Answer one pending prompt — free-text input, or arrow-navigable choices. */
+export function PromptView({ request, onAnswer, }) {
+    const { spec } = request;
+    const choices = spec.choices ?? [];
+    // Refs hold the authoritative value: Ink can deliver several key events before React
+    // re-renders, so the Enter handler must read a ref, not a possibly-stale render closure.
+    // State mirrors the ref only to drive the display.
+    const textRef = useRef("");
+    const indexRef = useRef(0);
+    const [text, setText] = useState("");
+    const [index, setIndex] = useState(0);
+    const onChoiceKey = (key) => {
+        if (key.upArrow) {
+            indexRef.current = Math.max(0, indexRef.current - 1);
+            setIndex(indexRef.current);
+        }
+        else if (key.downArrow) {
+            indexRef.current = Math.min(choices.length - 1, indexRef.current + 1);
+            setIndex(indexRef.current);
+        }
+        else if (key.return) {
+            onAnswer(choices[indexRef.current]?.value ?? spec.default);
+        }
+    };
+    const onInputKey = (input, key) => {
+        if (key.return) {
+            onAnswer(textRef.current === "" ? spec.default : textRef.current);
+        }
+        else if (key.backspace || key.delete) {
+            textRef.current = textRef.current.slice(0, -1);
+            setText(textRef.current);
+        }
+        else if (input && !key.ctrl && !key.meta) {
+            textRef.current += input;
+            setText(textRef.current);
+        }
+    };
+    useInput((input, key) => (spec.kind === "choice" ? onChoiceKey(key) : onInputKey(input, key)));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", paddingX: 1, children: [_jsx(Text, { children: spec.message }), spec.kind === "choice" ? (choices.map((c, i) => (_jsxs(Text, { inverse: i === index, children: [c.value === spec.default ? "* " : "  ", c.label] }, c.value)))) : (_jsxs(Text, { children: ["> ", text] }))] }));
+}
+/** The live run surface: milestone lines, a pending prompt, and the final verdict. */
+export function RunView({ lines, prompt, verdict, onAnswer, }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [lines.map((line, i) => (_jsx(Text, { children: line }, i))), prompt ? _jsx(PromptView, { request: prompt, onAnswer: onAnswer }) : null, verdict ? (_jsxs(Text, { color: verdict.ok ? "green" : "red", children: [verdict.ok ? "✓ ok" : "✗ failed", " \u00B7 ", verdict.folder] })) : null] }));
+}

package/dist/core/ActionRun.d.ts

@@ -2,7 +2,7 @@ import { type EventHandler } from "../foundation/events.ts";
 import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
-import type { Activity, Exec, InstanceEvents, NodeStatus, Outcome } from "./types.ts";
+import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
     readonly store: LogStore;
@@ -61,7 +61,6 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private readonly emitter;
     private readonly settled;
     private readonly handle;
-    private failureHandler;
     private attached;
     private observed;
     private refObserved;
@@ -75,14 +74,13 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     toRef(): ActionRef;
     /** This node's abort signal — handed to the exec as `ctx.signal`. */
     get signal(): AbortSignal;
-    get result(): Promise<Outcome<Result>>;
+    get result(): Promise<Result>;
     /** The attached handle; rejects on failure/cancel. */
     get ref(): Promise<Handle>;
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     tag(name: string): this;
     withCache(...paths: string[]): Activity<Result | undefined, Events, Handle>;
-    handleFailure(handler: (error: unknown) => void): this;
     cancel(): void;
     /**
      * Log a cancellation milestone on this node (once) and bubble it to the parent, so a

package/dist/core/ActionRun.js

@@ -37,7 +37,6 @@ export class ActionRun {
     emitter = events();
     settled = defer();
     handle = defer();
-    failureHandler;
     attached = false;
     observed = false;
     refObserved = false;
@@ -95,7 +94,10 @@ export class ActionRun {
     // ── Run handle surface ─────────────────────────────────────────────────────
     get result() {
         this.observed = true;
-        return this.settled.promise.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+        // The outcome itself: resolves the value, rejects with the error (CancelledError on cancel).
+        // Reading it marks the failure observed, so a `.result.catch(fn)` handles a fire-and-forget
+        // crash without tearing the run down.
+        return this.settled.promise;
     }
     /** The attached handle; rejects on failure/cancel. */
     get ref() {
@@ -111,22 +113,27 @@ export class ActionRun {
         this.emitter.listen(key, handler);
     }
     once(key) {
-        if (key === "error")
-            this.observed = true;
-        if (key === "done") {
-            return this.settled.promise.then((v) => v, () => undefined);
-        }
-        return new Promise((resolve) => {
+        // `done` is the outcome itself — identical to `.result` (resolve the value, reject on failure).
+        if (key === "done")
+            return this.result;
+        // Awaiting an event observes the activity: resolve the payload when it fires, but if the
+        // activity settles first, resolve `undefined` on success and **reject** on failure/cancel —
+        // so an event gate surfaces a failure instead of hanging (or, for `error`, hand back the error).
+        this.observed = true;
+        return new Promise((resolve, reject) => {
             let done = false;
-            const settle = (v) => {
-                if (!done) {
-                    done = true;
-                    resolve(v);
-                }
-            };
-            const doneKey = "done";
-            this.emitter.listenOnce(key, (p) => settle(p));
-            this.emitter.listenOnce(doneKey, () => settle(undefined));
+            const win = () => (done ? false : (done = true));
+            this.emitter.listenOnce(key, (p) => {
+                if (win())
+                    resolve(p);
+            });
+            this.settled.promise.then(() => {
+                if (win())
+                    resolve(undefined);
+            }, (error) => {
+                if (win())
+                    key === "error" ? resolve(error) : reject(error);
+            });
         });
     }
     tag(name) {
@@ -146,16 +153,6 @@ export class ActionRun {
             this.armedExec = cacheGate(inner, targets);
         return this;
     }
-    handleFailure(handler) {
-        this.failureHandler = handler;
-        this.observed = true;
-        // Attached after an `await` on a body that has already failed: deliver the
-        // already-recorded failure now (it won't fail again). Cancellation is status
-        // "cancelled", not "failed", so a cancelled node never runs the handler.
-        if (this.status === "failed")
-            handler(this.error);
-        return this;
-    }
     cancel() {
         this.noteCancelled(); // a direct cancel of this activity
         this.controller.abort();
@@ -291,11 +288,9 @@ export class ActionRun {
         // signal.aborted, which is why the check below uses `cascadeCancelled`, not
         // `signal.aborted`, to tell an unhandled fault from a run/ancestor teardown.
         this.controller.abort();
-        // A registered handler owns a fire-and-forget failure (side effect only; not on cancel).
-        this.failureHandler?.(error);
-        // If, one microtask on, no one is positioned to receive this error (no `.result`/`.ref`
-        // read, no `on("error")`) and we weren't caught in an ancestor's teardown, it's
-        // unhandled — tell the tree to tear the run down and record the fault.
+        // If, one microtask on, no one is positioned to receive this error (no `.result`/`.ref`/
+        // `.once` read, no `on("error")`, no `.result.catch`) and we weren't caught in an ancestor's
+        // teardown, it's unhandled — tell the tree to tear the run down and record the fault.
         // `sysEmit("error")` above already ran, so a live error handler has set `observed`.
         queueMicrotask(() => {
             const observed = this.observed || (this.refObserved && !this.attached);

package/dist/core/ExecutionTree.d.ts

@@ -28,6 +28,7 @@ export declare class ExecutionTree {
     private readonly originalLog;
     private streaming;
     private liveRendering;
+    private forwarding;
     private assertionsPassed;
     private assertionsFailed;
     private readonly faults;

package/dist/core/ExecutionTree.js

@@ -15,6 +15,7 @@ import { writeResult } from "../output/writers/ResultWriter.js";
 import { ActionRun } from "./ActionRun.js";
 import { procRegistry } from "../system/proc.js";
 import { currentNode } from "./context.js";
+import { activeSupervisor } from "./interaction.js";
 /**
  * The run: a module singleton that owns the log store, the run folder, the node
  * registry, and the process-wide teardown. `launch` creates a child node under the
@@ -47,6 +48,7 @@ export class ExecutionTree {
     originalLog = console.log.bind(console);
     streaming;
     liveRendering;
+    forwarding;
     assertionsPassed = 0;
     assertionsFailed = 0;
     faults = [];
@@ -202,9 +204,21 @@ export class ExecutionTree {
         process.on("uncaughtException", this.onUncaught);
         process.on("unhandledRejection", this.onUnhandled);
         this.streaming = this.rawStream.run(this.store);
-        // Live, curated milestones to the terminal — a single in-place status line on a TTY.
-        // Straight to process.stdout, which patch-console doesn't intercept (no capture feedback).
-        this.liveRendering = new LiveRenderer(process.stdout).run(this.store);
+        const supervisor = activeSupervisor();
+        if (supervisor) {
+            // Supervised: the supervisor owns the terminal. Forward every entry up the channel
+            // instead of rendering, and tear down on its cancel request.
+            supervisor.onCancel(() => this.cancel());
+            this.forwarding = (async () => {
+                for await (const entry of this.store.subscribe({ replay: true }))
+                    supervisor.log(entry);
+            })();
+        }
+        else {
+            // Bare: live, curated milestones to the terminal — a single in-place status line on a TTY.
+            // Straight to process.stdout, which patch-console doesn't intercept (no capture feedback).
+            this.liveRendering = new LiveRenderer(process.stdout).run(this.store);
+        }
         const rootPromise = currentNode.run(this.root, () => this.root.run(body, []));
         this.trackNode(rootPromise);
         await rootPromise;
@@ -252,6 +266,7 @@ export class ExecutionTree {
         this.store.close();
         await this.streaming;
         await this.liveRendering;
+        await this.forwarding;
         const flat = this.registry.map((node) => this.nodeView(node));
         const entries = this.store.entries();
         const at = (name) => path.join(this.folder.path(), name);
@@ -269,7 +284,13 @@ export class ExecutionTree {
         process.off("unhandledRejection", this.onUnhandled);
         this.consoleCapture.uninstall();
         ExecutionTree.current = null;
-        this.printSummary(summary);
+        const supervisor = activeSupervisor();
+        // Forward the same recap block the bare run prints to its terminal, so a supervising
+        // frontend (the ink console) can show it verbatim — see printSummary.
+        if (supervisor)
+            supervisor.settled(this.verdictOk(), this.folder.path(), summary);
+        else
+            this.printSummary(summary);
         if (!this.verdictOk())
             process.exitCode = 1;
     }

package/dist/core/interaction.d.ts

@@ -0,0 +1,63 @@
+import type { LogEntry } from "../foundation/LogEntry.ts";
+/**
+ * A normalized prompt request the supervisor renders. The `prompt` action builds it;
+ * `interaction.ts` treats it as an opaque payload (no dependency on the action layer,
+ * so there is no core→actions import cycle).
+ */
+export interface PromptSpec {
+    kind: "input" | "choice";
+    message: string;
+    default: string;
+    choices?: {
+        label: string;
+        value: string;
+    }[];
+}
+export type ChildMessage = {
+    kind: "prompt";
+    id: string;
+    spec: PromptSpec;
+} | {
+    kind: "log";
+    entry: LogEntry;
+} | {
+    kind: "settled";
+    ok: boolean;
+    folder: string;
+    summary: string[];
+};
+export type AnswerMessage = {
+    kind: "answer";
+    id: string;
+    value: string;
+    via: string;
+};
+export type SupervisorMessage = AnswerMessage | {
+    kind: "cancel";
+};
+type Send = (message: ChildMessage) => void;
+type OnMessage = (handler: (message: SupervisorMessage) => void) => void;
+/**
+ * The child-side handle to an out-of-process supervisor. Sends prompt requests, live log
+ * entries, and the final verdict up the channel; resolves prompts when the matching answer
+ * comes back; and invokes a cancel handler on a `cancel` message. Purely a transport — it
+ * decides nothing (the child keeps its own prompt timeout; see the `prompt` action).
+ */
+export declare class Supervisor {
+    private readonly send;
+    private seq;
+    private readonly pending;
+    private cancelHandler;
+    constructor(send: Send, onMessage: OnMessage);
+    request(spec: PromptSpec, signal: AbortSignal): Promise<AnswerMessage>;
+    log(entry: LogEntry): void;
+    settled(ok: boolean, folder: string, summary: string[]): void;
+    onCancel(handler: () => void): void;
+}
+/** Build a supervisor over an arbitrary channel — used in tests and by {@link detect}. */
+export declare function createSupervisor(send: Send, onMessage: OnMessage): Supervisor;
+/** The active supervisor, or `null` when running bare. */
+export declare function activeSupervisor(): Supervisor | null;
+/** Test seam: override the active supervisor (pass `null` to restore bare mode). */
+export declare function installSupervisor(supervisor: Supervisor | null): void;
+export {};

package/dist/core/interaction.js

@@ -0,0 +1,82 @@
+/**
+ * The child-side handle to an out-of-process supervisor. Sends prompt requests, live log
+ * entries, and the final verdict up the channel; resolves prompts when the matching answer
+ * comes back; and invokes a cancel handler on a `cancel` message. Purely a transport — it
+ * decides nothing (the child keeps its own prompt timeout; see the `prompt` action).
+ */
+export class Supervisor {
+    send;
+    seq = 0;
+    pending = new Map();
+    cancelHandler;
+    constructor(send, onMessage) {
+        this.send = send;
+        onMessage((message) => {
+            if (message.kind === "answer") {
+                const resolve = this.pending.get(message.id);
+                if (resolve) {
+                    this.pending.delete(message.id);
+                    resolve(message);
+                }
+            }
+            else if (message.kind === "cancel") {
+                this.cancelHandler?.();
+            }
+        });
+    }
+    request(spec, signal) {
+        const id = `p${++this.seq}`;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.pending.delete(id);
+                reject(new Error("prompt aborted"));
+            };
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.pending.set(id, (answer) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(answer);
+            });
+            this.send({ kind: "prompt", id, spec });
+        });
+    }
+    log(entry) {
+        this.send({ kind: "log", entry });
+    }
+    settled(ok, folder, summary) {
+        this.send({ kind: "settled", ok, folder, summary });
+    }
+    onCancel(handler) {
+        this.cancelHandler = handler;
+    }
+}
+/** Build a supervisor over an arbitrary channel — used in tests and by {@link detect}. */
+export function createSupervisor(send, onMessage) {
+    return new Supervisor(send, onMessage);
+}
+/**
+ * The real supervisor when this process was `fork`ed with an IPC channel and marked
+ * supervised (`OMKIT_SUPERVISED=1`), else `null`. Detected once at import.
+ */
+function detect() {
+    const supervised = process.env.OMKIT_SUPERVISED === "1" && typeof process.send === "function";
+    // Read the flag once, then clear it from the environment so any subprocess this run spawns
+    // (a shell command, a nested `npm test`, …) does not inherit it and spuriously enter
+    // supervised mode. Each omkit child's status is set explicitly by whoever forks it.
+    delete process.env.OMKIT_SUPERVISED;
+    if (!supervised)
+        return null;
+    const send = (message) => void process.send(message);
+    const onMessage = (handler) => process.on("message", (m) => handler(m));
+    return createSupervisor(send, onMessage);
+}
+let current = detect();
+/** The active supervisor, or `null` when running bare. */
+export function activeSupervisor() {
+    return current;
+}
+/** Test seam: override the active supervisor (pass `null` to restore bare mode). */
+export function installSupervisor(supervisor) {
+    current = supervisor;
+}

package/dist/core/step.js

@@ -7,11 +7,6 @@ import { action } from "./action.js";
  * units use `action(...)`.
  */
 export function step(name, fn) {
-    return action(name)
-        .run(fn)()
-        .result.then((r) => {
-        if (!r.ok)
-            throw r.error;
-        return r.value;
-    });
+    // `.result` already resolves the value and rejects on failure/cancel — exactly step's contract.
+    return action(name).run(fn)().result;
 }

package/dist/core/types.d.ts

@@ -5,14 +5,6 @@ import type { Proc } from "../system/proc.ts";
 export type Awaitable<T> = T | Promise<T>;
 /** An action that declares no events. */
 export type NoEvents = Record<never, never>;
-/** An activity's terminal outcome: a value on success, an error on failure/cancel. Never thrown. */
-export type Outcome<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: unknown;
-};
 /** A node's lifecycle state, mirrored into `result.json`. */
 export type NodeStatus = "running" | "ok" | "failed" | "cancelled";
 /**
@@ -73,8 +65,12 @@ export interface OmContext {
  */
 export interface Activity<Result = unknown, Events extends object = NoEvents, Handle = void> {
     readonly id: string;
-    /** The terminal outcome; always resolves (never rejects). Reading it observes the failure. */
-    readonly result: Promise<Outcome<Result>>;
+    /**
+     * The terminal outcome: resolves the value on success, **rejects** with the action's error on
+     * failure (or `CancelledError` on cancel). Reading it observes the activity — a handled failure,
+     * so it won't tear the run down. For fire-and-forget handling, `activity.result.catch(fn)`.
+     */
+    readonly result: Promise<Result>;
     /** The attached handle; rejects on failure/cancel. */
     readonly ref: Promise<Handle>;
     /**
@@ -84,15 +80,14 @@ export interface Activity<Result = unknown, Events extends object = NoEvents, Ha
      * after the launching call; calling it once the body has started throws.
      */
     withCache(...paths: string[]): Activity<Result | undefined, Events, Handle>;
-    /**
-     * Handle a fire-and-forget activity's failure: attach a handler so a crash runs it
-     * instead of tearing the run down. Observes the failure; chainable; attach in the
-     * same tick as the launching call. Not called on cancellation.
-     */
-    handleFailure(handler: (error: unknown) => void): this;
     /** Subscribe to every emit of a declared/system event (`done`/`error`/`attached`). */
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
-    /** Next emit of `key`; resolves `undefined` if the node settles first (never rejects). */
+    /**
+     * Await the next emit of `key`. Resolves the event's payload when it fires; if the activity
+     * settles first, resolves `undefined` on success and **rejects** on failure/cancellation — so a
+     * gate on an event surfaces a failure instead of hanging or sailing past it. Observes the
+     * activity. `once("done")` is the outcome itself — identical to `.result`.
+     */
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     /** Tag this run; chainable. */
     tag(name: string): this;

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { om } from "./core/om.ts";
 export { action } from "./core/action.ts";
 export { step } from "./core/step.ts";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
-export type { Action, Activity, ActionContext, OmContext, Outcome } from "./core/types.ts";
+export type { Action, Activity, ActionContext, OmContext } from "./core/types.ts";