omkit 0.0.5 → 0.0.7

package/dist/actions/command.js

@@ -22,7 +22,10 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
         // against process.cwd() — exactly the "absolute from where node runs" rule.
         const cwd = path.resolve(options.cwd ?? ".");
         // proc sources the LogsCollector from async context and streams output into it.
-        return proc(options.label ?? name, { cwd, ...(options.env ? { env: options.env } : {}) })(verbatim(cmdOrFile));
+        return proc(options.label ?? name, {
+            cwd,
+            ...(options.env ? { env: options.env } : {}),
+        })(verbatim(cmdOrFile));
     })(); // construct the instance here, so callers get one in a single call
 }
 /**
@@ -76,9 +79,13 @@ const spawnDirect = (logs, signal, name, file, args, options) => {
             // During teardown the abort-kill is why it exited — a clean shutdown, not a
             // fault; let it settle successfully so it isn't recorded as a failure.
             if (signal.aborted || code === 0)
-                resolve();
-            else
-                reject(new Error(`${name} exited with ${code ?? sig}`));
+                return resolve();
+            // Non-zero exit: reject with an error carrying `exitCode`, so the framework
+            // surfaces it on the action's Outcome (`{ ok: false, exitCode }`).
+            const error = Object.assign(new Error(`${name} exited with ${code ?? sig}`), {
+                exitCode: code ?? undefined,
+            });
+            reject(error);
         });
     });
 };

package/dist/actions/tail-log.js

@@ -40,8 +40,6 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
                 logs.append({ source, level, message: line });
         }
     };
-    // Read [pos, size) and feed it. Catches the file being absent (rotated away)
-    // and resets on a shrink (truncation/rotation), so reading self-heals.
     const readDelta = async () => {
         let size;
         try {
@@ -58,11 +56,24 @@ export const tailLog = action("Tail Log").run(async ({ logs, signal }, target, o
             return;
         const handle = await open(file, "r");
         try {
-            const length = size - pos;
-            const buffer = Buffer.alloc(length);
-            await handle.read(buffer, 0, length, pos);
-            pos = size;
-            feed(buffer.toString(encoding));
+            const CHUNK = 64 * 1024;
+            const buffer = Buffer.allocUnsafe(CHUNK);
+            while (pos < size) {
+                const length = Math.min(CHUNK, size - pos);
+                const { bytesRead } = await handle.read(buffer, 0, length, pos);
+                if (bytesRead === 0)
+                    break;
+                pos += bytesRead;
+                // Strip NUL bytes before decoding. Some log rotators on Windows
+                // temporarily expose sparse/preallocated regions filled with 0x00.
+                let out = 0;
+                for (let i = 0; i < bytesRead; i++) {
+                    if (buffer[i] !== 0)
+                        buffer[out++] = buffer[i];
+                }
+                if (out > 0)
+                    feed(buffer.subarray(0, out).toString(encoding));
+            }
         }
         finally {
             await handle.close();

package/dist/core/action.d.ts

@@ -5,6 +5,21 @@ import { type Proc } from "./process.ts";
 export type NoEvents = Record<never, never>;
 /** A value an action's `exec` may return: a result, or a promise of one. */
 export type Awaitable<T> = T | Promise<T>;
+/**
+ * How an action settles. An action **never throws into the spin body** — its
+ * failure is data, not control flow: it completes with `{ ok: false, error }`
+ * instead of rejecting. On success it carries the exec's `value`. `exitCode` is
+ * present when the failure came from a process (see {@link import("../actions/command.ts").command}).
+ * Await it via `instance.done` or `once("done")`; both resolve, never reject.
+ */
+export type Outcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly exitCode?: number;
+};
 /**
  * Lifecycle events the framework emits for every action — on top of whatever it
  * declares via `.emits<…>()`. They make key moments first-class signals (no
@@ -13,9 +28,9 @@ export type Awaitable<T> = T | Promise<T>;
 export interface SystemEvents<Result> {
     /** The action published its imperative handle via `ctx.attach` (fires once). */
     attached: void;
-    /** The run resolved; payload is its result. */
-    done: Result;
-    /** The run rejected; payload is the thrown error. */
+    /** The action settled; payload is its {@link Outcome} (success or failure). Fires once, always. */
+    done: Outcome<Result>;
+    /** The action failed; payload is the thrown error. Fires only on failure (alongside `done`). */
     error: unknown;
 }
 /** The full event map a constructed instance exposes: the declared events plus the system ones. */
@@ -39,18 +54,38 @@ export interface ActionContext<Events extends object, Handle = void> extends Sys
      * one (e.g. CDP) follows the same pattern over `logs`/`signal`.
      */
     readonly proc: Proc;
+    /**
+     * Absolute path to this run's output folder (`logs/<name>/<date>/<time>/`) —
+     * created and shared across the run. Write action artifacts here so they land
+     * beside `run.log`; the same folder is on the `spin` context.
+     */
+    readonly artifactsFolder: string;
 }
 /** A constructed-but-not-yet-run action: what calling an `Action` produces. */
 export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
     readonly name: string;
     readonly args: readonly unknown[];
-    /** Runs the action with the captured args and the injected system services. */
-    readonly start: (system: SystemGlobal) => Promise<Result>;
     /**
-     * Resolves with the handle the action attached via `ctx.attach` (set once). If
-     * the action settles *without* attaching, this never hangs: it resolves
-     * (`undefined` for the default `void` handle) on success, or rejects with the
-     * action's error on failure.
+     * Runs the action with the captured args and the injected system services.
+     * **Resolves with the {@link Outcome}, never rejects** — a failing action is
+     * reported as `{ ok: false, error }`, not a thrown promise, so it can't tear a
+     * caller down. The run reads this to build its verdict.
+     */
+    readonly start: (system: SystemGlobal) => Promise<Outcome<Result>>;
+    /**
+     * The action's {@link Outcome}, as a memoized promise that **never rejects** —
+     * the ergonomic way to await completion in a spin body:
+     * `const r = await nod(x).done; if (!r.ok) …`. Same value as `once("done")`.
+     */
+    readonly done: Promise<Outcome<Result>>;
+    /**
+     * Resolves with the handle the action attached via `ctx.attach` (set once).
+     * Used to thread a handle into another action (`chromePage(driver.ref)`). If
+     * the action settles *without* attaching, this resolves (`undefined` for the
+     * default `void` handle) on success and **rejects on failure** — so, unlike
+     * `done`, awaiting `ref` in a body can throw. It's meant to be consumed as a
+     * constructor arg *inside* another action, where that rejection becomes that
+     * action's failure Outcome. For control flow, await `done`.
      */
     readonly ref: Promise<Handle>;
     /** Subscribe to a declared or system event (`done`/`error`) with a handler. */
@@ -82,7 +117,7 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
 }
 /**
  * Any constructed instance, whatever its result, events, or handle. The launch
- * surface ({@link ActionInstance}-takers like `run` and `Run.run`) accepts this
+ * surface ({@link ActionInstance}-takers like `run` and `Spin.run`) accepts this
  * so handle-bearing actions — those declaring `.ref<H>()` — can be launched: the
  * bare `ActionInstance` pins the handle to `void`, so an instance whose `ref` is
  * a `Promise<Page>` (not `Promise<void>`) would otherwise be rejected. `unknown`

package/dist/core/action.js

@@ -1,6 +1,7 @@
 import { events } from "./events.js";
 import { createProc } from "./process.js";
 import { fingerprint, read, write, resolvePaths } from "./folder-cache.js";
+import { artifactsFolder } from "./output.js";
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -11,6 +12,11 @@ const deferred = () => {
     });
     return { promise, resolve, reject };
 };
+/** Duck-type an exit code off a thrown error (zx's ProcessOutput, command's exit error). */
+const exitCodeOf = (error) => {
+    const code = error?.exitCode;
+    return typeof code === "number" ? code : undefined;
+};
 /**
  * A promise for the next emit of `key`. It races the event against the
  * instance's terminal events: if the action errors first it rejects with that
@@ -74,35 +80,58 @@ const build = (name, exec) => {
         // handled so a settle-time rejection on such an instance doesn't surface as an
         // unhandled rejection. Real awaiters of `ref` still receive the rejection.
         void handle.promise.catch(() => { });
+        // The action's Outcome as a set-once promise. `start` resolves it (success or
+        // failure); `instance.done` / `once("done")` read it. It never rejects.
+        const settled = deferred();
         const instance = {
             name,
             args,
             ref: handle.promise,
+            done: settled.promise,
             start: (system) => 
             // `Promise.resolve().then` normalizes a sync result and routes a sync
             // throw to the `error` path, so exec may be sync or async.
             Promise.resolve()
-                .then(() => exec({ ...system, emit, attach, proc: createProc(system.logs, system.signal) }, ...args))
+                .then(() => exec({
+                ...system,
+                emit,
+                attach,
+                proc: createProc(system.logs, system.signal),
+                artifactsFolder: artifactsFolder(),
+            }, ...args))
                 .then((result) => {
-                systemEmit("done", result);
+                const outcome = { ok: true, value: result };
+                settled.resolve(outcome);
+                systemEmit("done", outcome);
                 // Settle `ref` if the action finished without attaching, so awaiters
                 // resolve (with `undefined` for the default void handle) rather than
                 // hang. Idempotent — a no-op when a handle was already attached.
                 handle.resolve(undefined);
-                return result;
+                return outcome;
             }, (error) => {
+                const exitCode = exitCodeOf(error);
+                const outcome = exitCode === undefined ? { ok: false, error } : { ok: false, error, exitCode };
+                // `error` first, so a pending `once(<declaredEvent>)` rejects on it
+                // (settled before its event) rather than resolving on `done`.
                 systemEmit("error", error);
+                settled.resolve(outcome);
+                systemEmit("done", outcome);
                 // The action failed, so its handle will never arrive — reject `ref`
                 // with the same error instead of leaving awaiters hung. No-op if a
                 // handle was already attached before the failure.
                 handle.reject(error);
-                throw error;
+                // Resolve (never rethrow): failure is the Outcome, not a rejection.
+                return outcome;
             }),
             on(key, handler) {
                 emitter.listen(key, handler);
             },
             once(key) {
-                return awaitEvent(emitter, name, key);
+                // `done` always fires with the Outcome and never "fails" the await, so it
+                // reads straight from the settled promise; other keys race via awaitEvent.
+                return (key === "done"
+                    ? settled.promise
+                    : awaitEvent(emitter, name, key));
             },
             // Wrap this instance in a fresh one (reusing the engine for its own
             // emitter/ref/on/once) that fingerprints `paths` and either skips or
@@ -120,9 +149,13 @@ const build = (name, exec) => {
                         ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
                         return undefined;
                     }
-                    const result = await instance.start({ logs: ctx.logs, signal: ctx.signal });
-                    await write(targets, fp); // only on success — a throw above skips this
-                    return result;
+                    const outcome = await instance.start({ logs: ctx.logs, signal: ctx.signal });
+                    // Re-throw the inner failure so the wrapper fails too (the framework
+                    // re-wraps it into this wrapper's own Outcome); only record on success.
+                    if (!outcome.ok)
+                        throw outcome.error;
+                    await write(targets, fp);
+                    return outcome.value;
                 })();
             },
         };

package/dist/core/output.d.ts

@@ -1,4 +1,13 @@
 import type { LogsCollector } from "./log-collector/LogsCollector.ts";
+/**
+ * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
+ * own **artifacts** into the same per-run folder (one folder per run; one run per
+ * process). The folder is created on first access — synchronously, so a caller
+ * can write into it in the same tick — and the path is absolute so it's safe to
+ * hand to a child process with a different cwd.
+ */
+export declare const artifactsFolder: () => string;
 /**
  * Drains the collected log to two files in the run's output folder (the common
  * `logs/<name>/<date>/<time>/` convention, local time):

package/dist/core/output.js

@@ -1,4 +1,4 @@
-import { createWriteStream } from "node:fs";
+import { createWriteStream, mkdirSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { log } from "./log-collector/global.js";
@@ -24,6 +24,23 @@ const runDir = () => {
 };
 let made;
 const ensureDir = () => (made ??= mkdir(runDir(), { recursive: true }).then(() => { }));
+let ensuredSync = false;
+/**
+ * Absolute path to this run's output folder — `logs/<name>/<date>/<time>/`, where
+ * `run.log`, `run.jsonl`, and snapshots live. Exposed so actions can drop their
+ * own **artifacts** into the same per-run folder (one folder per run; one run per
+ * process). The folder is created on first access — synchronously, so a caller
+ * can write into it in the same tick — and the path is absolute so it's safe to
+ * hand to a child process with a different cwd.
+ */
+export const artifactsFolder = () => {
+    const abs = path.resolve(runDir());
+    if (!ensuredSync) {
+        mkdirSync(abs, { recursive: true });
+        ensuredSync = true;
+    }
+    return abs;
+};
 /** A compact header block for the top of run.log — legend + run identity. */
 const logHeader = () => {
     const now = new Date();

package/dist/core/run.d.ts

@@ -1,95 +1,88 @@
 import type { AnyActionInstance } from "./action.ts";
 import { log as logs } from "./log-collector/global.ts";
 /**
- * A single action's failure, captured for the run's verdict. Cascade failures —
- * actions that reject only because teardown killed them — are deliberately
- * excluded (see `launch`'s catch), so this records genuine faults, not fallout.
+ * A single action's failure, captured for the spin's verdict. Cascade failures —
+ * actions that settled `{ ok: false }` only because teardown aborted them — are
+ * deliberately excluded (see `launch`'s outcome handling), so this records
+ * genuine faults, not fallout.
  */
 export interface ActionFailure {
     /** The failing action's name. */
     readonly action: string;
-    /** Whatever it threw or rejected with. */
+    /** Whatever it failed with (the Outcome's `error`). */
     readonly error: unknown;
 }
 /**
- * The terminal verdict of a run: did everything that mattered succeed, and if
- * not, what failed. {@link Run.done} resolves (never rejects) with this, so a
+ * The terminal verdict of a spin: did everything that mattered succeed, and if
+ * not, what failed. {@link Spin.done} resolves (never rejects) with this, so a
  * single `await` yields the outcome instead of forcing a try/catch on awaiters.
+ * A failing action is *recorded* here (so `ok` is false and the exit code is 1)
+ * but does **not** tear the spin down — see {@link Spin}.
  */
-export interface RunResult {
+export interface SpinResult {
     /** True when no genuine failure was recorded. */
     readonly ok: boolean;
     /** The genuine failures, in the order they surfaced. Empty when `ok`. */
     readonly failures: readonly ActionFailure[];
 }
 /**
- * The run's lifecycle. It only ever moves forward:
+ * The spin's lifecycle. It only ever moves forward:
  *
  *   open ──▶ closing ──▶ closed
  *
  * - **open** — launching and running actions; `.run(…)` is accepted.
- * - **closing** — teardown has begun (cancel, first failure, Ctrl-C, or natural
- *   completion). The signal is aborted, in-flight actions are unwinding, and new
- *   `.run(…)` is refused.
+ * - **closing** — teardown has begun (cancel, Ctrl-C, natural completion, or an
+ *   uncaught fatal). The signal is aborted, in-flight actions are unwinding, and
+ *   new `.run(…)` is refused. Note: a failing *action* does not begin teardown.
  * - **closed** — everything has settled, the log is flushed, the verdict is final.
  */
-export type RunState = "open" | "closing" | "closed";
-/** Tunes a run's failure policy. */
-export interface RunOptions {
-    /**
-     * Abort the whole run the moment the first genuine failure surfaces
-     * (default `true`). Set `false` to let every action finish and collect all
-     * failures into the verdict — useful when you want the complete picture of
-     * what broke rather than just the first cause.
-     */
-    readonly failFast?: boolean;
-}
-/** A live run: a set of actions sharing one abort controller and the global log. */
-export interface Run {
-    /** The shared global log (output + events for everything in this run). */
+export type SpinState = "open" | "closing" | "closed";
+/** A live spin: a set of actions sharing one abort controller and the global log. */
+export interface Spin {
+    /** The shared global log (output + events for everything in this spin). */
     readonly logs: typeof logs;
-    /** The current lifecycle state — see {@link RunState}. */
-    readonly state: RunState;
-    /** Settles once the run reaches `closed`, carrying the terminal {@link RunResult}. */
-    readonly done: Promise<RunResult>;
-    /** The run's abort signal — for consumers that want to observe teardown. */
+    /** The current lifecycle state — see {@link SpinState}. */
+    readonly state: SpinState;
+    /** Settles once the spin reaches `closed`, carrying the terminal {@link SpinResult}. */
+    readonly done: Promise<SpinResult>;
+    /** The spin's abort signal — for consumers that want to observe teardown. */
     readonly signal: AbortSignal;
     /**
-     * Launch more actions into this same run — same controller, same log. Chainable.
+     * Launch more actions into this same spin — same controller, same log. Chainable.
      *
-     * Throws if the run is no longer `open`: launching into a closing/closed run
+     * Throws if the spin is no longer `open`: launching into a closing/closed spin
      * would bind the actions to an already-aborted signal, so they'd start and
      * immediately unwind, silently doing nothing. Launch before teardown, or from
      * a lifecycle event of an action that is still running (those fire while the
-     * run is still `open`).
+     * spin is still `open`).
      */
-    run(...actions: AnyActionInstance[]): Run;
+    run(...actions: AnyActionInstance[]): Spin;
     /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
     cancel(): void;
     /**
      * Start streaming the global log live to a writer (console by default) in the
-     * background; it stops on its own when the run settles. Returns the run, so it
+     * background; it stops on its own when the spin settles. Returns the spin, so it
      * chains. Await `.done` for the verdict.
      */
-    drain(write?: (message: string) => void): Run;
+    drain(write?: (message: string) => void): Spin;
 }
 /**
- * Starts the run: launches the given actions in parallel under one abort
- * controller, against the process-wide global log. Returns a {@link Run} — add
+ * Starts the spin: launches the given actions in parallel under one abort
+ * controller, against the process-wide global log. Returns a {@link Spin} — add
  * more actions on demand with `.run(…)`, observe `.done` for the verdict, stop
- * with `.cancel()`. An optional leading {@link RunOptions} tunes failure policy.
+ * with `.cancel()`.
  *
- * **Callable once per process.** A run *is* the world being modelled, and there's
- * one global log per world; a second `run(…)` would silently share that log, so
- * it throws instead. Attach further actions — including event-driven ones — to
- * the returned {@link Run} via its `.run(…)` method, not by calling this again.
+ * **Callable once per process.** A spin *is* the world being modelled, and there's
+ * one global log per world; a second call would silently share that log, so it
+ * throws instead. Attach further actions — including event-driven ones — to the
+ * returned {@link Spin} via its `.run(…)` method, not by calling this again.
  *
  * Each action runs against its own child logger (which headers and indents its
- * lines into the global log) and the run's shared abort signal — both injected
+ * lines into the global log) and the spin's shared abort signal — both injected
  * into its context, where the framework also binds a `proc` to them so child
- * processes stream into the right log and die on teardown. On Ctrl-C, `.cancel()`,
- * the first failure (under fail-fast), or natural completion, the run transitions
- * through {@link RunState} to `closed`.
+ * processes stream into the right log and die on teardown. A **failing action
+ * never tears the spin down** — its `{ ok: false }` outcome is recorded in the
+ * verdict (and sets exit code 1) and the spin keeps running. Teardown to `closed`
+ * happens only on Ctrl-C, `.cancel()`, natural completion, or an uncaught fatal.
  */
-export declare function run(...actions: AnyActionInstance[]): Run;
-export declare function run(options: RunOptions, ...actions: AnyActionInstance[]): Run;
+export declare function run(...actions: AnyActionInstance[]): Spin;

package/dist/core/run.js

@@ -3,7 +3,7 @@ import { log as logs } from "./log-collector/global.js";
 import { createRenderer } from "./log-collector/render.js";
 import { streamLog, writeLog } from "./output.js";
 import { marker } from "./markers.js";
-/** One run per process — a single world over the one global log. See {@link run}. */
+/** One spin per process — a single world over the one global log. See {@link run}. */
 let started = false;
 /** Narrate a run-lifecycle milestone into the global log (renders as a `[run]` line). */
 const narrate = (message) => logs.append({ source: "run", level: "run", message });
@@ -32,19 +32,29 @@ function assertInstance(value) {
         : "";
     throw new Error(`run() expects action instances; received ${typeof value}${hint}`);
 }
-export function run(...args) {
+/**
+ * Starts the spin: launches the given actions in parallel under one abort
+ * controller, against the process-wide global log. Returns a {@link Spin} — add
+ * more actions on demand with `.run(…)`, observe `.done` for the verdict, stop
+ * with `.cancel()`.
+ *
+ * **Callable once per process.** A spin *is* the world being modelled, and there's
+ * one global log per world; a second call would silently share that log, so it
+ * throws instead. Attach further actions — including event-driven ones — to the
+ * returned {@link Spin} via its `.run(…)` method, not by calling this again.
+ *
+ * Each action runs against its own child logger (which headers and indents its
+ * lines into the global log) and the spin's shared abort signal — both injected
+ * into its context, where the framework also binds a `proc` to them so child
+ * processes stream into the right log and die on teardown. A **failing action
+ * never tears the spin down** — its `{ ok: false }` outcome is recorded in the
+ * verdict (and sets exit code 1) and the spin keeps running. Teardown to `closed`
+ * happens only on Ctrl-C, `.cancel()`, natural completion, or an uncaught fatal.
+ */
+export function run(...actions) {
     if (started) {
         throw new Error("run() may only be called once per process — attach more actions to the existing run with its .run(…) method.");
     }
-    // Peel an optional leading options bag off the variadic actions, keeping the
-    // bare `run(...actions)` call form working unchanged. Options are a plain
-    // object (no `.start`); a *function* first arg is never options — it's an
-    // uncalled action, which `assertInstance` below reports clearly.
-    const first = args[0];
-    const hasOptions = first !== undefined && !isActionInstance(first) && typeof first !== "function";
-    const options = hasOptions ? first : {};
-    const actions = (hasOptions ? args.slice(1) : args);
-    const failFast = options.failFast ?? true;
     // Validate eagerly, before the one-run latch flips, so a bad argument throws
     // cleanly and leaves the process's single run slot still usable.
     for (const instance of actions)
@@ -77,13 +87,15 @@ export function run(...args) {
         narrate(`tearing down · ${reason}`);
         controller.abort();
     };
-    /** Record a genuine fault and, under fail-fast, kick off teardown. */
+    /**
+     * Record a genuine fault in the verdict. It does **not** tear the spin down — a
+     * failing action is data, and the spin keeps running (only Ctrl-C / cancel /
+     * completion / an uncaught fatal close it).
+     */
     const recordFailure = (action, error) => {
         failures.push({ action, error });
-        if (failFast)
-            beginClosing(`failed: ${action}`);
     };
-    // Ctrl-C tears the run down gracefully through the lifecycle, like cancel().
+    // Ctrl-C tears the spin down gracefully through the lifecycle, like cancel().
     const onSigint = () => beginClosing("interrupted (SIGINT)");
     process.once("SIGINT", onSigint);
     // A throw or rejection that escaped every action's own handling. Without a
@@ -100,10 +112,10 @@ export function run(...args) {
             message: error instanceof Error ? (error.stack ?? error.message) : String(error),
         });
         // Genuine fault vs. teardown fallout: only one that surfaces *before* the
-        // signal aborts is the run's own (mirrors `launch`'s cascade rule); a throw
+        // signal aborts is the spin's own (mirrors `launch`'s cascade rule); a throw
         // during unwind is logged but doesn't pollute the verdict. Either way tear
-        // down — an uncaught fault leaves the process state undefined, so we always
-        // finish and flush, even under `failFast: false`.
+        // down — unlike an action's own failure, an *uncaught* fatal leaves the
+        // process state undefined, so we always finish and flush.
         if (!controller.signal.aborted)
             failures.push({ action: kind, error });
         beginClosing(kind);
@@ -119,9 +131,11 @@ export function run(...args) {
     const launch = (instance) => {
         narrate(`launch ${instance.name}`);
         // The action logs into the one shared store (entries carry their `source`;
-        // grouping is applied at render time) and gets the run's signal directly; the
+        // grouping is applied at render time) and gets the spin's signal directly; the
         // framework injects a `proc` bound to both, so there's no ambient context.
-        const promise = instance.start({ logs, signal: controller.signal }).catch((error) => {
+        // `start()` resolves with the action's Outcome — it never rejects for the
+        // action's own failure — so a failure is handled here as data, not a throw.
+        const record = (error) => {
             // Always record the fault in the action's own log, under its name.
             logs.append({
                 source: instance.name,
@@ -129,13 +143,20 @@ export function run(...args) {
                 message: error instanceof Error ? (error.stack ?? error.message) : String(error),
             });
             // Genuine failure vs. teardown fallout: if the signal was already aborted
-            // when this surfaced, the rejection is almost certainly the abort killing
-            // the action (a cascade), not its own fault — so it must not pollute the
-            // verdict. The *first* real error is caught here before `recordFailure`
-            // triggers the abort, so `signal.aborted` is still false for it.
+            // when this surfaced, the failure is almost certainly the abort killing the
+            // action (a cascade), not its own fault — so it must not pollute the verdict.
             if (!controller.signal.aborted)
                 recordFailure(instance.name, error);
-        });
+        };
+        const promise = instance
+            .start({ logs, signal: controller.signal })
+            .then((outcome) => {
+            if (!outcome.ok)
+                record(outcome.error);
+        })
+            // Defensive: `start()` shouldn't reject, but if the framework itself throws,
+            // treat it as a fault rather than losing it to an unhandled rejection.
+            .catch(record);
         inFlight.add(promise);
         void promise.finally(() => inFlight.delete(promise));
     };
@@ -198,7 +219,7 @@ export function run(...args) {
         signal: controller.signal,
         run(...more) {
             if (state !== "open") {
-                throw new Error(`run.run(…) rejected: the run is "${state}", not "open". Launch actions before ` +
+                throw new Error(`spin.run(…) rejected: the spin is "${state}", not "open". Launch actions before ` +
                     `teardown, or from a lifecycle event of an action that is still running.`);
             }
             for (const instance of more)

package/dist/core/spin.d.ts

@@ -1,13 +1,16 @@
 import { type AnyActionInstance } from "./action.ts";
-import { type Run, type RunOptions } from "./run.ts";
+import { type Spin } from "./run.ts";
 /**
- * Launch an action into the spin's run and get the same instance back, so you
- * can `await` its `.done` / `.ref` or subscribe with `.on` / `.once`. A nod is
- * how the body waves an action in.
+ * Launch an action into the spin and get the same instance back, so you can
+ * `await` its `.done` (its {@link import("./action.ts").Outcome} — resolves with
+ * `{ ok, value } | { ok, error }`, **never throws**), its `.ref` (the attached
+ * handle; rejects on failure, so it's for data deps consumed inside other
+ * actions), or subscribe with `.on` / `.once`. A nod is how the body waves an
+ * action in.
  */
 export type Nod = <I extends AnyActionInstance>(instance: I) => I;
-/** Tunes a {@link spin} — the run's options plus how it drains. */
-export interface SpinOptions extends RunOptions {
+/** Tunes a {@link spin} — currently just how it drains. */
+export interface SpinOptions {
     /**
      * Stream the log to the console automatically from the start. Default `true`.
      * Set `false` when you need to drain later via {@link SpinContext.drain} —
@@ -17,42 +20,53 @@ export interface SpinOptions extends RunOptions {
 }
 /** What a {@link spin} body receives. */
 export interface SpinContext {
-    /** Launch an action into the run; returns the instance for awaiting/chaining. */
+    /** Launch an action into the spin; returns the instance for awaiting/chaining. */
     readonly nod: Nod;
     /**
-     * Start streaming the run's log to the console now. Only needed when the spin
+     * Start streaming the spin's log to the console now. Only needed when the spin
      * was created with `drain: false`; idempotent, so it's safe to call regardless.
      */
-    readonly drain: Run["drain"];
+    readonly drain: Spin["drain"];
     /**
-     * Tear the run down (abort the signal, stopping daemons). Use it to end a run
+     * Tear the spin down (abort the signal, stopping daemons). Use it to end a spin
      * whose work is finished but which is held open by a daemon — e.g. once a
      * one-shot build completes while a watcher is still running.
      */
-    readonly cancel: Run["cancel"];
-    /** The run's abort signal — honor it to stop early. */
+    readonly cancel: Spin["cancel"];
+    /** The spin's abort signal — honor it to stop early. */
     readonly signal: AbortSignal;
+    /**
+     * Absolute path to this spin's output folder (`logs/<name>/<date>/<time>/`),
+     * created up front. Hand it to actions (or use `ctx.artifactsFolder` inside
+     * one) to write artifacts beside `run.log`.
+     */
+    readonly artifactsFolder: string;
 }
 /** The body of a {@link spin}: any (async) function — it isn't named or wrapped by you. */
 export type SpinBody = (ctx: SpinContext) => void | Promise<void>;
 /**
- * Runs a linear orchestration. You pass a plain (async) function; tswm hosts it
+ * Runs a linear orchestration. You pass a plain (async) function; omkit hosts it
  * in a single in-flight action and hands it a {@link Nod}. Because that host
- * stays in-flight while your body `await`s, the run never idles shut between
- * steps — so you write `await` / `if` control flow instead of nested `done`
- * callbacks. When the body returns, the daemons it nodded in keep the run alive
- * until teardown.
+ * stays in-flight while your body `await`s, the spin never idles shut between
+ * steps — so you write `await` / `if` control flow instead of nested callbacks.
+ * When the body returns, the daemons it nodded in keep the spin alive until
+ * teardown.
+ *
+ * A failing action **never throws into the body** — `await nod(x).done` yields an
+ * {@link import("./action.ts").Outcome} you inspect, and the spin keeps going
+ * (the failure is recorded in the verdict and sets exit code 1):
  *
- *   spin({ failFast: false }, async ({ nod }) => {
- *     if ((await nod(prompt({ … })).done) === "yes") await nod(test).done;
- *     nod(devServer);                                 // fire-and-forget daemon
+ *   spin({ drain: false }, async ({ nod }) => {
+ *     const ans = await nod(prompt({ … })).done;       // Outcome — never throws
+ *     if (ans.ok && ans.value === "yes") await nod(test).done;
+ *     nod(devServer);                                   // fire-and-forget daemon
  *     const chrome = nod(chromedriver({ … }));
- *     nod(chromePage(chrome.ref));                    // data deps via .ref
+ *     nod(chromePage(chrome.ref));                      // data deps via .ref
  *   });
  *
  * Auto-drains by default; pass `drain: false` and call `ctx.drain()` yourself to
  * stream the log only from a chosen point (e.g. after a `prompt`). Returns the
- * {@link Run}, so `.done` is available on it too.
+ * {@link Spin} — `await` its `.done` for the verdict.
  */
-export declare function spin(body: SpinBody): Run;
-export declare function spin(options: SpinOptions, body: SpinBody): Run;
+export declare function spin(body: SpinBody): Spin;
+export declare function spin(options: SpinOptions, body: SpinBody): Spin;

package/dist/core/spin.js

@@ -1,10 +1,11 @@
 import { action } from "./action.js";
 import { run } from "./run.js";
+import { artifactsFolder } from "./output.js";
 export function spin(a, b) {
     const [options, body] = typeof a === "function" ? [{}, a] : [a, b];
-    const { drain: autoDrain = true, ...runOptions } = options;
+    const { drain: autoDrain = true } = options;
     // `run(...)` below assigns `host` synchronously, before the action's async body
-    // ever runs — so the closures here capture the run safely.
+    // ever runs — so the closures here capture the spin safely.
     let host;
     // One-shot drain: auto-drain and a manual ctx.drain() can't double-subscribe.
     let drained = false;
@@ -20,9 +21,15 @@ export function spin(a, b) {
             host.run(instance);
             return instance;
         };
-        await body({ nod, drain: startDrain, cancel: () => host.cancel(), signal });
+        await body({
+            nod,
+            drain: startDrain,
+            cancel: () => host.cancel(),
+            signal,
+            artifactsFolder: artifactsFolder(),
+        });
     });
-    host = run(runOptions, hosted());
+    host = run(hosted());
     if (autoDrain)
         startDrain();
     return host;

package/dist/index.d.ts

@@ -9,9 +9,9 @@
  * renderer, marker prefixing) are intentionally not exported.
  */
 export { action } from "./core/action.ts";
-export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, } from "./core/action.ts";
+export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, Outcome, } from "./core/action.ts";
 export { run } from "./core/run.ts";
-export type { Run, RunResult, RunOptions, RunState, ActionFailure } from "./core/run.ts";
+export type { Spin, SpinResult, SpinState, ActionFailure } from "./core/run.ts";
 export { spin } from "./core/spin.ts";
 export type { Nod, SpinOptions, SpinContext, SpinBody } from "./core/spin.ts";
 export { events } from "./core/events.ts";
@@ -23,4 +23,5 @@ export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./core/log-c
 export { log } from "./core/log-collector/global.ts";
 export { snapshot, captureSnapshot } from "./core/output.ts";
 export type { SnapshotRef } from "./core/output.ts";
+export { artifactsFolder } from "./core/output.ts";
 export { fingerprint, cacheDir } from "./core/folder-cache.ts";

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 // ── Actions ────────────────────────────────────────────────────────────────
 export { action } from "./core/action.js";
-// ── Runs ───────────────────────────────────────────────────────────────────
+// ── Spin (the run handle) ────────────────────────────────────────────────────
 export { run } from "./core/run.js";
 // ── Spin (linear orchestration) ──────────────────────────────────────────────
 export { spin } from "./core/spin.js";
@@ -23,6 +23,10 @@ export { LogsCollector } from "./core/log-collector/LogsCollector.js";
 export { log } from "./core/log-collector/global.js";
 // ── Snapshots ──────────────────────────────────────────────────────────────
 export { snapshot, captureSnapshot } from "./core/output.js";
+// ── Artifacts ────────────────────────────────────────────────────────────────
+// This run's output folder (absolute) — also on the `spin`/action `ctx`. Import
+// it directly for artifact-writing helpers that aren't inside an action.
+export { artifactsFolder } from "./core/output.js";
 // ── Folder cache ─────────────────────────────────────────────────────────────
 // Backs the `.withCache(...inputs)` method on instances (fingerprints an
 // action's input files/folders, not its outputs); exported for scripts that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",