omkit 0.0.9 → 0.0.10

package/dist/{core → orchestration/events}/events.d.ts

@@ -18,6 +18,14 @@ export interface Emitter<Events extends object> {
     listen<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
     /** Like {@link Emitter.listen} but auto-unsubscribes after the first delivery (snapshot counts). */
     listenOnce<K extends keyof Events>(key: K, handler: EventHandler<Events[K]>): () => void;
+    /**
+     * Observe **every** live emit on this bus, whatever the key — the cross-cutting
+     * hook the bus itself stays out of. Used by the action engine to log each emit
+     * onto the run timeline (through the action's scoped logger), so the bus is pure
+     * pub/sub and logging is layered on top. Fires only for live emits, not snapshot
+     * replays. Returns an unsubscribe.
+     */
+    onAny(handler: (key: keyof Events, payload: unknown) => void): () => void;
 }
-export declare const events: <Events extends object>(namespace?: string) => Emitter<Events>;
+export declare const events: <Events extends object>(_namespace?: string) => Emitter<Events>;
 export {};

package/dist/{core → orchestration/events}/events.js

@@ -1,29 +1,15 @@
-import { log } from "./log-collector/global.js";
-import { captureSnapshot } from "./output.js";
-export const events = (namespace) => {
+export const events = (_namespace) => {
     const handlers = new Map();
     const snapshots = new Map();
+    const anyHandlers = new Set();
     const emit = (key, ...args) => {
         const payload = args[0];
         snapshots.set(key, payload);
-        // Every emit also lands in the global log, so events share the timeline with
-        // process output and end up in the drained log file. Fields are `·`-delimited
-        // — namespace (the emitting action) · key · payload. String payloads show
-        // inline; richer payloads are no longer dropped — they're written to a
-        // snapshot file and linked (`→ <path>`), so the durable record keeps them.
-        const fields = [namespace, String(key)];
-        if (typeof payload === "string") {
-            fields.push(payload);
-        }
-        else if (payload !== undefined) {
-            const name = `event-${[namespace, String(key)].filter(Boolean).join("-")}`;
-            fields.push(`→ ${captureSnapshot(name, payload).rel}`);
-        }
-        log.append({
-            source: "event",
-            level: "event",
-            message: fields.filter(Boolean).join(" · "),
-        });
+        // Notify the cross-cutting observers first (they log the emit onto the
+        // timeline), then the keyed handlers — the bus does no logging of its own.
+        // Copy so an observer unsubscribing mid-emit doesn't disturb iteration.
+        for (const handler of [...anyHandlers])
+            handler(key, payload);
         const set = handlers.get(key);
         if (!set)
             return;
@@ -57,5 +43,11 @@ export const events = (namespace) => {
         });
         return off;
     };
-    return { emit, listen, listenOnce };
+    const onAny = (handler) => {
+        anyHandlers.add(handler);
+        return () => {
+            anyHandlers.delete(handler);
+        };
+    };
+    return { emit, listen, listenOnce, onAny };
 };

package/dist/orchestration/spin/SpinHost.d.ts

@@ -0,0 +1,105 @@
+import type { AnyActionInstance } from "../action/types.ts";
+import { LogsCollector } from "../../output/log/LogsCollector.ts";
+import { Output } from "../../output/Output.ts";
+import type { SpinResult, SpinState } from "./types.ts";
+/**
+ * A live spin over its own append-only log: constructing one launches the given
+ * actions in parallel under a single abort controller and drives them to a terminal
+ * {@link SpinResult}. Stop it with `.cancel()`, `await` its `.done` for the verdict.
+ *
+ * **A spin owns its world.** Each construction creates its *own* {@link LogsCollector}
+ * and {@link Output} — the run's log, folder, and snapshots — rather than sharing a
+ * process global, so runs don't bleed into each other and a fresh run can be created
+ * in a living process (sequential re-runs, in-process tests). Attach further actions
+ * to a running spin — including event-driven ones — via its `.run(…)` method.
+ *
+ * Each action runs against its own child logger (which headers and indents its
+ * lines into this run's log) and the spin's shared abort signal — both injected
+ * into its context, where the framework also binds a `proc` and the run's `output`
+ * 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. The process-level hooks (SIGINT/uncaught handlers, `exitCode`) are owned by
+ * the run and cleaned at finalize, so they don't outlive it.
+ */
+export declare class SpinHost {
+    /** This run's append-only log — its own store, not a process global. */
+    readonly logs: LogsCollector;
+    /** This run's output subsystem (folder + snapshots + run-log writer), wired to {@link logs}. */
+    readonly output: Output;
+    /** The spin's abort signal — for consumers that want to observe teardown. */
+    readonly signal: AbortSignal;
+    /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
+    readonly done: Promise<SpinResult>;
+    private readonly controller;
+    private phase;
+    /** The current lifecycle state — see {@link SpinState}. */
+    get state(): SpinState;
+    private readonly failures;
+    private readonly inFlight;
+    private readonly launched;
+    private readonly streaming;
+    private readonly onSigint;
+    private readonly onUncaught;
+    private readonly onUnhandled;
+    constructor(...actions: AnyActionInstance[]);
+    /**
+     * Launch more actions into this same spin — same controller, same log. Chainable.
+     *
+     * Throws if the spin is no longer `open`.
+     */
+    run(...more: AnyActionInstance[]): this;
+    /**
+     * Launch `instance` into the spin under an optional `parentPath` (the nodding
+     * action's path, or `undefined` for a top-level nod). The single guarded entry to
+     * launching — `run` (top-level) and an action's own scoped `nod` both route here,
+     * so the "spin is open" check lives in one place.
+     */
+    private nodInto;
+    /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
+    cancel(): void;
+    /**
+     * Live-render the log to the console. Started automatically from the constructor
+     * — every spin drains, with no flag to disable and nothing for the caller to
+     * invoke (for now). A single {@link LogRenderer} applies grouping/indentation as
+     * entries stream by; its state spans the replayed history and live entries as one
+     * continuous stream. The subscription ends itself when the run tears down (the
+     * collector closes it), so this loop simply runs to completion.
+     */
+    private drain;
+    /** Narrate a run-lifecycle milestone into this run's log (renders as a `[run]` line). */
+    private narrate;
+    /**
+     * Move `open → closing`: abort the signal (unwinding procs, waits, and
+     * daemons), narrate the cause once, and stop accepting new actions. Idempotent
+     * — only the first caller transitions; later triggers (a second failure, a
+     * `cancel()` during teardown) are no-ops. This is the *only* path to abort, so
+     * every teardown reason flows through one place.
+     */
+    private beginClosing;
+    /**
+     * 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).
+     */
+    private recordFailure;
+    /**
+     * A throw or rejection that escaped every action's own handling. Without a
+     * handler Node prints it and exits *immediately* — before the run can flush its
+     * log, which leaves a silent, empty log directory and no verdict. So catch it,
+     * log it, fold it into the verdict, and drive teardown so the log still flushes
+     * and the exit code reflects the fault — degrading a stray throw to a recorded
+     * failure instead of a hard crash. Removed at finalize, so it only governs
+     * while this run owns the process.
+     */
+    private onFatal;
+    private launch;
+    /**
+     * Drives the run to `closed`. The loop re-checks `inFlight` because actions can
+     * be added (or daemons can settle on abort) while we await. A synchronous
+     * `.run(…)` from a settling action's lifecycle event lands before that action's
+     * `finally` removes it, so `inFlight` never spuriously hits 0 mid-handoff.
+     */
+    private drive;
+}

package/dist/orchestration/spin/SpinHost.js

@@ -0,0 +1,303 @@
+import { relative } from "node:path";
+import { producerOfRef } from "../action/action.js";
+import { LogsCollector, ScopedLogger } from "../../output/log/LogsCollector.js";
+import { LogRenderer } from "../../output/log/LogRenderer.js";
+import { Output } from "../../output/Output.js";
+/** The entry script, relative to where node was invoked (so the log says what produced it). */
+const scriptPath = () => {
+    const entry = process.argv[1];
+    return entry ? relative(process.cwd(), entry) : "(unknown)";
+};
+/** A constructed instance is an object carrying a `start` function. */
+const isActionInstance = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.start === "function";
+/** An *uncalled* action: the callable `action(name).run(…)` returns before it's invoked. */
+const isUncalledAction = (value) => typeof value === "function" && typeof value.actionName === "string";
+/**
+ * Guard each launch argument: an action *instance* is required, not the action
+ * itself. Forgetting the trailing `()` is an easy slip (the callable has no
+ * `.start`), and silently treating it as something else would report a false
+ * green — so fail loudly with the fix.
+ */
+function assertInstance(value) {
+    if (isActionInstance(value))
+        return;
+    const hint = isUncalledAction(value)
+        ? ` — that looks like an action that wasn't invoked; construct an instance by calling it: action("…").run(…)()`
+        : "";
+    throw new Error(`run() expects action instances; received ${typeof value}${hint}`);
+}
+/**
+ * A live spin over its own append-only log: constructing one launches the given
+ * actions in parallel under a single abort controller and drives them to a terminal
+ * {@link SpinResult}. Stop it with `.cancel()`, `await` its `.done` for the verdict.
+ *
+ * **A spin owns its world.** Each construction creates its *own* {@link LogsCollector}
+ * and {@link Output} — the run's log, folder, and snapshots — rather than sharing a
+ * process global, so runs don't bleed into each other and a fresh run can be created
+ * in a living process (sequential re-runs, in-process tests). Attach further actions
+ * to a running spin — including event-driven ones — via its `.run(…)` method.
+ *
+ * Each action runs against its own child logger (which headers and indents its
+ * lines into this run's log) and the spin's shared abort signal — both injected
+ * into its context, where the framework also binds a `proc` and the run's `output`
+ * 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. The process-level hooks (SIGINT/uncaught handlers, `exitCode`) are owned by
+ * the run and cleaned at finalize, so they don't outlive it.
+ */
+export class SpinHost {
+    /** This run's append-only log — its own store, not a process global. */
+    logs = new LogsCollector();
+    /** This run's output subsystem (folder + snapshots + run-log writer), wired to {@link logs}. */
+    output = new Output(this.logs);
+    /** The spin's abort signal — for consumers that want to observe teardown. */
+    signal;
+    /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
+    done;
+    controller = new AbortController();
+    // ── Lifecycle state ──────────────────────────────────────────────────────
+    // The single source of truth for "where in its life is this run". Only
+    // `beginClosing` and the finalize step below mutate it, and only forward.
+    // The log stays open through teardown and is closed once at finalize (after the
+    // last entry), so `streamLog` captures the whole run — including lines logged
+    // *during* teardown — and its run.jsonl is complete before `writeLog` reads it.
+    phase = "open";
+    /** The current lifecycle state — see {@link SpinState}. */
+    get state() {
+        return this.phase;
+    }
+    // Genuine failures (not teardown cascade). Frozen into the verdict at close.
+    failures = [];
+    // Every launched action's promise lives here until it settles; the drive loop
+    // empties this set. Daemons keep it non-empty until the controller aborts.
+    inFlight = new Set();
+    // Instances launched so far — used to verify a `.ref` dependency was launched
+    // before the action that consumes its handle.
+    launched = new WeakSet();
+    // The incremental crash-insurance stream; awaited at finalize before writeLog.
+    streaming;
+    // Ctrl-C tears the spin down gracefully through the lifecycle, like cancel().
+    onSigint = () => this.beginClosing("interrupted (SIGINT)");
+    onUncaught = this.onFatal("uncaughtException");
+    onUnhandled = this.onFatal("unhandledRejection");
+    constructor(...actions) {
+        // Validate eagerly so a bad argument throws cleanly before any work begins.
+        for (const instance of actions)
+            assertInstance(instance);
+        this.signal = this.controller.signal;
+        process.once("SIGINT", this.onSigint);
+        process.on("uncaughtException", this.onUncaught);
+        process.on("unhandledRejection", this.onUnhandled);
+        this.narrate(`run started · ${scriptPath()}`);
+        // Start streaming log entries to disk immediately — incremental writes survive
+        // hard kills where the final writeLog never runs. Kept so finalize can await it
+        // *before* writeLog rewrites the same files: otherwise a late flush from this
+        // stream lands past writeLog's truncation and the OS zero-fills the gap (a
+        // multi-MB NUL run in run.log).
+        this.streaming = this.output.runLog.stream(this.logs).catch(() => { });
+        // Live-render the log to the console for the whole run (replay + live). Always
+        // on — the run's terminal output, no flag or call required.
+        this.drain();
+        for (const instance of actions)
+            this.launch(instance, undefined);
+        // Launch before driving: the drive loop breaks on an empty `inFlight`, so it
+        // must not start until the initial actions have populated it.
+        this.done = this.drive();
+        // `done` resolves with the verdict and never rejects; guard anyway so a stray
+        // finalize error can't surface as an unhandled rejection.
+        this.done.catch(() => { });
+    }
+    /**
+     * Launch more actions into this same spin — same controller, same log. Chainable.
+     *
+     * Throws if the spin is no longer `open`.
+     */
+    run(...more) {
+        for (const instance of more)
+            this.nodInto(instance, undefined);
+        return this;
+    }
+    /**
+     * Launch `instance` into the spin under an optional `parentPath` (the nodding
+     * action's path, or `undefined` for a top-level nod). The single guarded entry to
+     * launching — `run` (top-level) and an action's own scoped `nod` both route here,
+     * so the "spin is open" check lives in one place.
+     */
+    nodInto(instance, parentPath) {
+        if (this.phase !== "open") {
+            throw new Error(`spin.run(…) rejected: the spin is "${this.phase}", not "open". Launch actions before ` +
+                `teardown, or from a lifecycle event of an action that is still running.`);
+        }
+        this.launch(instance, parentPath);
+    }
+    /** Begin teardown: abort the signal (killing procs, unblocking waits, stopping daemons). */
+    cancel() {
+        this.beginClosing("cancelled");
+    }
+    /**
+     * Live-render the log to the console. Started automatically from the constructor
+     * — every spin drains, with no flag to disable and nothing for the caller to
+     * invoke (for now). A single {@link LogRenderer} applies grouping/indentation as
+     * entries stream by; its state spans the replayed history and live entries as one
+     * continuous stream. The subscription ends itself when the run tears down (the
+     * collector closes it), so this loop simply runs to completion.
+     */
+    drain() {
+        void (async () => {
+            const renderer = new LogRenderer();
+            for await (const entry of this.logs.subscribe({ replay: true }))
+                console.log(renderer.render(entry));
+        })().catch(() => { });
+    }
+    /** Narrate a run-lifecycle milestone into this run's log (renders as a `[run]` line). */
+    narrate(message) {
+        this.logs.append({ source: "run", level: "run", message });
+    }
+    /**
+     * Move `open → closing`: abort the signal (unwinding procs, waits, and
+     * daemons), narrate the cause once, and stop accepting new actions. Idempotent
+     * — only the first caller transitions; later triggers (a second failure, a
+     * `cancel()` during teardown) are no-ops. This is the *only* path to abort, so
+     * every teardown reason flows through one place.
+     */
+    beginClosing(reason) {
+        if (this.phase !== "open")
+            return;
+        this.phase = "closing";
+        this.narrate(`tearing down · ${reason}`);
+        this.controller.abort();
+    }
+    /**
+     * 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).
+     */
+    recordFailure(action, error) {
+        this.failures.push({ action, error });
+    }
+    /**
+     * A throw or rejection that escaped every action's own handling. Without a
+     * handler Node prints it and exits *immediately* — before the run can flush its
+     * log, which leaves a silent, empty log directory and no verdict. So catch it,
+     * log it, fold it into the verdict, and drive teardown so the log still flushes
+     * and the exit code reflects the fault — degrading a stray throw to a recorded
+     * failure instead of a hard crash. Removed at finalize, so it only governs
+     * while this run owns the process.
+     */
+    onFatal(kind) {
+        return (error) => {
+            this.logs.append({
+                source: kind,
+                level: "error",
+                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 spin's own (mirrors `launch`'s cascade rule); a throw
+            // during unwind is logged but doesn't pollute the verdict. Either way tear
+            // down — unlike an action's own failure, an *uncaught* fatal leaves the
+            // process state undefined, so we always finish and flush.
+            if (!this.controller.signal.aborted)
+                this.failures.push({ action: kind, error });
+            this.beginClosing(kind);
+        };
+    }
+    launch(instance, parentPath) {
+        // A consumer built with another action's `.ref` (e.g. `chromePage(driver.ref)`)
+        // must be launched *after* that producer — otherwise it awaits a handle that
+        // never arrives and the spin hangs silently. Catch it and say how to fix it.
+        for (const arg of instance.args) {
+            const producer = producerOfRef(arg);
+            if (producer && !this.launched.has(producer)) {
+                throw new Error(`${instance.name} was launched before its dependency ${producer.name}: it ` +
+                    `consumes ${producer.name}'s .ref, so nod ${producer.name} first.`);
+            }
+        }
+        this.launched.add(instance);
+        // The action's path: its name for a top-level nod, or `<parent> › <name>` when a
+        // parent action nodded it. Top-level actions keep this run's logger (output
+        // unchanged); a child gets a ScopedLogger so its every line — and its `proc`'s,
+        // and any grandchildren's — is prefixed with this path. Its own `nod` carries
+        // this path down, so scoping composes automatically.
+        const path = parentPath ? `${parentPath} › ${instance.name}` : instance.name;
+        const scoped = parentPath === undefined ? this.logs : new ScopedLogger(this.logs, path);
+        const nod = (child) => {
+            this.nodInto(child, path);
+            return child;
+        };
+        this.narrate(`launch ${path}`);
+        // The action logs into this run's shared store (entries carry their `source`;
+        // grouping is applied at render time) and gets the spin's signal directly; the
+        // framework injects a `proc` and the run's `output` bound to both, so there's no
+        // ambient context. `start()` resolves with the action's Outcome — it never
+        // rejects for the action's own failure — so a failure is handled here as data.
+        const record = (error) => {
+            // Always record the fault in the action's own log, under its path.
+            this.logs.append({
+                source: path,
+                level: "error",
+                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 failure is almost certainly the abort killing the
+            // action (a cascade), not its own fault — so it must not pollute the verdict.
+            if (!this.controller.signal.aborted)
+                this.recordFailure(path, error);
+        };
+        const promise = instance
+            .start({ logs: scoped, signal: this.controller.signal, nod, output: this.output })
+            .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);
+        this.inFlight.add(promise);
+        void promise.finally(() => this.inFlight.delete(promise));
+    }
+    /**
+     * Drives the run to `closed`. The loop re-checks `inFlight` because actions can
+     * be added (or daemons can settle on abort) while we await. A synchronous
+     * `.run(…)` from a settling action's lifecycle event lands before that action's
+     * `finally` removes it, so `inFlight` never spuriously hits 0 mid-handoff.
+     */
+    async drive() {
+        for (;;) {
+            if (this.inFlight.size === 0) {
+                // Nothing left to run. If still open, every action finished on its own —
+                // natural completion; tear down so daemons/listeners unwind uniformly.
+                // If already closing, teardown is simply complete.
+                if (this.phase === "open")
+                    this.beginClosing("completed");
+                break;
+            }
+            await Promise.allSettled([...this.inFlight]);
+        }
+        // ── Finalize (reached exactly once) ──────────────────────────────────────
+        this.phase = "closed";
+        process.off("SIGINT", this.onSigint);
+        process.off("uncaughtException", this.onUncaught);
+        process.off("unhandledRejection", this.onUnhandled);
+        this.narrate("finished");
+        // Close the log now (after the last entry) so `streamLog` drains and finishes
+        // writing the complete run.jsonl, then wait for it to fully close its files —
+        // both so its last flush can't corrupt run.log later, and so run.jsonl is done
+        // before `writeLog` streams it into the final collapsed run.log.
+        this.logs.close();
+        await this.streaming;
+        const file = await this.output.runLog.write();
+        // Direct to the terminal — the file's already written, so this line isn't in it.
+        console.log(LogRenderer.marker("run", `log → ${file}`));
+        const result = { ok: this.failures.length === 0, failures: this.failures };
+        // One process = one run = one verdict; reflect pass/fail in the exit code so
+        // shells and CI see it without parsing the log. Only set it on failure, so a
+        // code a failing action's own handler may have set isn't clobbered to 0.
+        if (!result.ok)
+            process.exitCode = 1;
+        return result;
+    }
+}

package/dist/orchestration/spin/spin.d.ts

@@ -0,0 +1,24 @@
+import type { SpinBody } from "./types.ts";
+/**
+ * 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 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({ 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
+ *   });
+ *
+ * Auto-drains by default;
+ */
+export declare function spin(body: SpinBody): void;

package/dist/orchestration/spin/spin.js

@@ -0,0 +1,56 @@
+import { action } from "../action/action.js";
+import { SpinHost } from "./SpinHost.js";
+/**
+ * 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 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({ 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
+ *   });
+ *
+ * Auto-drains by default;
+ */
+export function spin(body) {
+    // `run(...)` below assigns `host` synchronously, before the action's async body
+    // ever runs — so the closures here capture the spin safely.
+    let hostRun;
+    const hostAction = action("omkit:Spin").run(async (ctx) => {
+        const nod = (instance) => {
+            hostRun.run(instance);
+            return instance;
+        };
+        await body({
+            nod,
+            // TODO: maybe add a reason for cancel ???
+            cancel: () => hostRun.cancel(),
+            signal: ctx.signal,
+            // The host action runs inside the SpinHost, so its ctx already carries the
+            // run's output subsystem — surface the folder and a snapshot convenience to
+            // the body from there rather than reaching for a module singleton.
+            artifactsFolder: ctx.artifactsFolder,
+            snapshot: (name, value) => ctx.output.snapshots.snapshot(name, value),
+        });
+    });
+    const mainSpinAction = hostAction();
+    hostRun = new SpinHost(mainSpinAction);
+    // The body is the orchestrator, not a peer action: if it throws, tear the whole
+    // spin down. Regular action failures only get recorded (they don't stop the
+    // spin), but the orchestrator crashing must end the run — otherwise any daemon
+    // it already nodded keeps the process alive forever on a pipeline bug.
+    void mainSpinAction.done.then((outcome) => {
+        if (!outcome.ok)
+            hostRun.cancel();
+    });
+}

package/dist/orchestration/spin/types.d.ts

@@ -0,0 +1,56 @@
+export type { Nod } from "../action/types.ts";
+import type { Nod } from "../action/types.ts";
+/** What a {@link spin} body receives. */
+export interface SpinContext {
+    /** Launch an action into the spin; returns the instance for awaiting/chaining. */
+    readonly nod: Nod;
+    /**
+     * 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: () => void;
+    /** 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;
+    /**
+     * Capture a JSON snapshot into this run's output folder and drop a `[snapshot]`
+     * line on the timeline — for run-level inputs the log should narrate (a build
+     * config, resolved options). Resolves with the snapshot's relative path. The
+     * run-scoped counterpart to the action `ctx.output.snapshots`.
+     */
+    readonly snapshot: (name: string, value: unknown) => Promise<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>;
+/**
+ * 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 failed with (the Outcome's `error`). */
+    readonly error: unknown;
+}
+/**
+ * The terminal verdict of a spin: did everything that mattered succeed, and if
+ * not, what failed. {@link SpinHost.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 SpinHost}.
+ */
+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[];
+}
+export type SpinState = "open" | "closing" | "closed";

package/dist/orchestration/spin/types.js

@@ -0,0 +1 @@
+export {};

package/dist/output/Output.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "./log/LogsCollector.ts";
+import { RunFolder } from "./folder/RunFolder.ts";
+import { SnapshotStore } from "./snapshot/SnapshotStore.ts";
+import { RunLog } from "./log/RunLog.ts";
+/**
+ * The run's output subsystem — the composition root that owns the per-run folder and
+ * the writers layered on it, and hands them to the rest of the process.
+ *
+ * Each run owns one of these: its {@link SpinHost} constructs an `Output` over the
+ * run's log and threads it to actions as `ctx.output`. Everything that was
+ * module-global in the old `output.ts` (the folder path, the mkdir latch, the
+ * snapshot sequence) now lives inside these three members, reachable as
+ * `output.folder`, `output.snapshots`, `output.runLog` — so callers reach for a named
+ * layer instead of a free function, and the shared state has one owner per run.
+ */
+export declare class Output {
+    /** The per-run directory and artifact drop. */
+    readonly folder: RunFolder;
+    /** Sequenced JSON/text snapshot files + `[snapshot]` timeline lines. */
+    readonly snapshots: SnapshotStore;
+    /** The `run.jsonl` / `run.log` writer. */
+    readonly runLog: RunLog;
+    constructor(logger: Logger);
+}