omkit 0.0.1

package/dist/core/log-collector/render.js

@@ -0,0 +1,111 @@
+import { marker } from "../markers.js";
+/**
+ * Levels that render as their own top-level milestone line — marker-prefixed and
+ * never grouped/indented. Everything else is action/proc output, which the
+ * renderer groups under an `[action] <source>` header and indents.
+ */
+const MILESTONE = {
+    run: "run",
+    event: "event",
+    snapshot: "snapshot",
+};
+/**
+ * Builds a stateful renderer that turns raw {@link LogEntry} records into the
+ * pretty, grouped text form. Presentation lives here and nowhere else: the
+ * collector stores raw entries; `writeLog` and `drain` each create a renderer and
+ * feed it the entry stream in order.
+ *
+ * Grouping is decided against the *single merged stream* (the renderer's own
+ * `lastSource`), not per-producer — so interleaved concurrent sources re-header
+ * correctly, which the old per-child grouping got wrong. A milestone line breaks
+ * the current group, so the next action line re-headers.
+ */
+export const createRenderer = () => {
+    let lastSource;
+    return (entry) => {
+        const milestone = MILESTONE[entry.level];
+        if (milestone) {
+            // Reset grouping: after an interjection, the next action line re-headers.
+            lastSource = undefined;
+            return marker(milestone, entry.message);
+        }
+        if (entry.source !== lastSource) {
+            lastSource = entry.source;
+            return `${marker("action", entry.source)}\n\t${entry.message}`;
+        }
+        return `\t${entry.message}`;
+    };
+};
+// ── Collapsing large output runs (batch / file rendering) ───────────────────
+//
+// A *run* is a maximal stretch of consecutive non-milestone entries sharing one
+// `source` — the same grouping `createRenderer` does. When a proc emits a burst
+// (a build's file tree, tsc/vite chatter), that run can be dozens of lines and
+// drowns the durable `run.log`. The batch renderer below collapses an
+// over-threshold run to its head plus a pointer; the full run is off-loaded to a
+// text snapshot by the caller (which owns the filesystem — this stays pure).
+/** Lines of a collapsed run shown inline before the pointer. */
+export const COLLAPSE_HEAD = 5;
+/** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
+export const COLLAPSE_THRESHOLD = 15;
+/**
+ * Segments a full, ordered entry list into {@link DisplayItem}s. Milestones and
+ * runs no longer than `threshold` become `line` items byte-identical to
+ * {@link createRenderer}; a run longer than `threshold` becomes a single
+ * `collapsed` item carrying every line of the run. Pure — no filesystem, no
+ * snapshot writing.
+ */
+export const segmentForFile = (entries, { threshold = COLLAPSE_THRESHOLD } = {}) => {
+    const items = [];
+    // The run currently being accumulated: a same-source stretch of output lines.
+    let run;
+    // Flush the pending run: collapse it if it ran long, else emit grouped lines
+    // exactly as createRenderer would (header on the first line, indent the rest).
+    const flush = () => {
+        if (!run)
+            return;
+        if (run.lines.length > threshold) {
+            items.push({ kind: "collapsed", run: { source: run.source, lines: run.lines } });
+        }
+        else {
+            run.lines.forEach((message, i) => {
+                items.push({
+                    kind: "line",
+                    text: i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`,
+                });
+            });
+        }
+        run = undefined;
+    };
+    for (const entry of entries) {
+        const milestone = MILESTONE[entry.level];
+        if (milestone) {
+            // A milestone breaks the current run, then renders as its own line.
+            flush();
+            items.push({ kind: "line", text: marker(milestone, entry.message) });
+            continue;
+        }
+        if (run && run.source === entry.source) {
+            run.lines.push(entry.message);
+        }
+        else {
+            flush();
+            run = { source: entry.source, lines: [entry.message] };
+        }
+    }
+    flush();
+    return items;
+};
+/**
+ * Renders a {@link CollapsedRun} as its `head` lines under the `▸ <source>`
+ * header, then a single indented `📎` pointer line to the off-loaded snapshot at
+ * `rel` reporting how many lines were hidden. Pure — `rel` is supplied by the
+ * caller after it writes the file.
+ */
+export const renderCollapsed = (run, { head, rel }) => {
+    const shown = run.lines.slice(0, head);
+    const lines = shown.map((message, i) => i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`);
+    const hidden = run.lines.length - shown.length;
+    lines.push(`\t${marker("snapshot", `… +${hidden} more lines → ${rel}`)}`);
+    return lines.join("\n");
+};

package/dist/core/markers.d.ts

@@ -0,0 +1,9 @@
+/** The special "title" log lines that get a distinguishing prefix. */
+export type MarkerKind = "event" | "action" | "run" | "snapshot";
+/**
+ * Prefixes a special log line so it's explicit what it is when scanning the
+ * global log — an emitted event (`[ev]`), an action's title (`[action]`), a run
+ * lifecycle milestone (`[run]`), or a captured state snapshot (`[snapshot]`) —
+ * versus plain output.
+ */
+export declare const marker: (kind: MarkerKind, text: string) => string;

package/dist/core/markers.js

@@ -0,0 +1,13 @@
+const PREFIX = {
+    event: "⚡",
+    action: "▸",
+    run: "●",
+    snapshot: "📎",
+};
+/**
+ * Prefixes a special log line so it's explicit what it is when scanning the
+ * global log — an emitted event (`[ev]`), an action's title (`[action]`), a run
+ * lifecycle milestone (`[run]`), or a captured state snapshot (`[snapshot]`) —
+ * versus plain output.
+ */
+export const marker = (kind, text) => `${PREFIX[kind]} ${text}`;

package/dist/core/output.d.ts

@@ -0,0 +1,55 @@
+import type { LogsCollector } from "./log-collector/LogsCollector.ts";
+/**
+ * Drains the collected log to two files in the run's output folder (the common
+ * `logs/<name>/<date>/<time>/` convention, local time):
+ *
+ * - `run.log` — the pretty, human-scannable rendering: just the message lines.
+ * - `run.jsonl` — the structured, machine-queryable record: one full {@link LogEntry}
+ *   per line (sequence, timestamp, level, source, message), so an agent can filter
+ *   and correlate by origin/level/time instead of parsing prose.
+ *
+ * Returns the `run.log` path (the one surfaced to the terminal).
+ */
+export declare const writeLog: (logs: LogsCollector) => Promise<string>;
+/**
+ * Streams log entries to `run.jsonl` and `run.log` incrementally as they arrive,
+ * so output survives a hard kill or lost SIGINT. Each entry is appended via a
+ * write stream. The subscription ends on teardown (`logs.endOn`), after which
+ * {@link writeLog} overwrites both files with the authoritative final snapshot
+ * (including post-abort entries like "finished"). For dirty exits, whatever was
+ * flushed to disk by the OS is the best available record.
+ */
+export declare const streamLog: (logs: LogsCollector) => Promise<void>;
+/** A written (or in-flight) snapshot file and where to find it. */
+export interface SnapshotRef {
+    /** Absolute path to the snapshot file. */
+    readonly file: string;
+    /** Path relative to cwd — what a log line references. */
+    readonly rel: string;
+    /** Resolves once the file is flushed to disk. */
+    readonly written: Promise<void>;
+}
+/**
+ * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) in the run's
+ * output folder and returns its path — **without** logging a pointer line. The
+ * path is computed synchronously (so callers can reference it in the same tick)
+ * while the write proceeds in the background. Use {@link snapshot} when you also
+ * want a `[snapshot]` line in the timeline; the event bus uses this directly to
+ * link a non-string payload from its own line.
+ */
+export declare const captureSnapshot: (name: string, value: unknown) => SnapshotRef;
+/**
+ * Writes raw text `lines` as a sequenced `.log` snapshot file in the run's output
+ * folder and returns its path refs — the text sibling of {@link captureSnapshot}
+ * (which writes JSON). {@link writeLog} uses it to off-load a collapsed output
+ * run from `run.log`, keeping the burst's full text one click away.
+ */
+export declare const captureText: (name: string, lines: readonly string[]) => SnapshotRef;
+/**
+ * Captures any value as a JSON snapshot file (via {@link captureSnapshot}) and
+ * records a `[snapshot] <name>: <path>` line in the timeline at the point it's
+ * taken. Files are sequenced so repeated snapshots of the same name are kept as a
+ * history rather than overwritten. Callable any time, anywhere in the run;
+ * returns the file path once written.
+ */
+export declare const snapshot: (name: string, value: unknown) => Promise<string>;

package/dist/core/output.js

@@ -0,0 +1,163 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { log } from "./log-collector/global.js";
+import { COLLAPSE_HEAD, createRenderer, renderCollapsed, segmentForFile, } from "./log-collector/render.js";
+const pad = (n, width = 2) => String(n).padStart(width, "0");
+/** The entry script's base name (the run's name), e.g. "tskb-build". */
+const pipelineName = () => {
+    const entry = process.argv[1];
+    return entry ? path.basename(entry, path.extname(entry)) : "pipeline";
+};
+// One output directory per run (one run per process): logs/<name>/<date>/<time>/.
+// Computed once, lazily — so the log file and every snapshot land together, even
+// when a snapshot is taken mid-run before the log is flushed.
+let dir;
+const runDir = () => {
+    if (dir)
+        return dir;
+    const now = new Date();
+    const day = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+    dir = path.join("logs", pipelineName(), day, time);
+    return dir;
+};
+let made;
+const ensureDir = () => (made ??= mkdir(runDir(), { recursive: true }).then(() => { }));
+/** A compact header block for the top of run.log — legend + run identity. */
+const logHeader = () => {
+    const now = new Date();
+    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+    return [
+        `─── ${pipelineName()} · ${date} ${time} ───`,
+        `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output`,
+        "",
+    ].join("\n");
+};
+/**
+ * Drains the collected log to two files in the run's output folder (the common
+ * `logs/<name>/<date>/<time>/` convention, local time):
+ *
+ * - `run.log` — the pretty, human-scannable rendering: just the message lines.
+ * - `run.jsonl` — the structured, machine-queryable record: one full {@link LogEntry}
+ *   per line (sequence, timestamp, level, source, message), so an agent can filter
+ *   and correlate by origin/level/time instead of parsing prose.
+ *
+ * Returns the `run.log` path (the one surfaced to the terminal).
+ */
+export const writeLog = async (logs) => {
+    await ensureDir();
+    const entries = logs.snapshot();
+    // Apply grouping/indentation at write time from the raw entries, so the stored
+    // messages stay presentation-free. Unlike the live `drain`, the final file
+    // collapses large same-source runs: each is off-loaded to a text snapshot and
+    // replaced inline by its head plus a pointer, so one proc's burst can't drown
+    // the timeline. `run.jsonl` below keeps every line, raw.
+    const file = path.join(runDir(), "run.log");
+    const header = logHeader();
+    const writes = [];
+    const parts = segmentForFile(entries).map((item) => {
+        if (item.kind === "line")
+            return item.text;
+        const snap = captureText(`output-${item.run.source}`, item.run.lines);
+        writes.push(snap.written);
+        return renderCollapsed(item.run, { head: COLLAPSE_HEAD, rel: snap.rel });
+    });
+    const pretty = parts.join("\n");
+    await writeFile(file, pretty ? `${header}${pretty}\n` : "", "utf8");
+    // Ensure every off-loaded run is flushed before we report the log is written.
+    await Promise.all(writes);
+    const jsonlFile = path.join(runDir(), "run.jsonl");
+    const jsonl = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    await writeFile(jsonlFile, jsonl ? `${jsonl}\n` : "", "utf8");
+    return file;
+};
+/**
+ * Streams log entries to `run.jsonl` and `run.log` incrementally as they arrive,
+ * so output survives a hard kill or lost SIGINT. Each entry is appended via a
+ * write stream. The subscription ends on teardown (`logs.endOn`), after which
+ * {@link writeLog} overwrites both files with the authoritative final snapshot
+ * (including post-abort entries like "finished"). For dirty exits, whatever was
+ * flushed to disk by the OS is the best available record.
+ */
+export const streamLog = async (logs) => {
+    await ensureDir();
+    const jsonlFile = path.join(runDir(), "run.jsonl");
+    const logFile = path.join(runDir(), "run.log");
+    const jsonl = createWriteStream(jsonlFile);
+    const pretty = createWriteStream(logFile);
+    const render = createRenderer();
+    pretty.write(logHeader() + "\n");
+    try {
+        for await (const entry of logs.subscribe({ replay: true })) {
+            jsonl.write(JSON.stringify(entry) + "\n");
+            pretty.write(render(entry) + "\n");
+        }
+    }
+    finally {
+        jsonl.end();
+        pretty.end();
+    }
+};
+let seq = 0;
+/** Serialize a value for a snapshot file, tolerating circular refs / non-JSON values. */
+const serialize = (value) => {
+    try {
+        // JSON.stringify returns undefined for functions/undefined — fall back to a string.
+        return JSON.stringify(value, null, 2) ?? JSON.stringify(String(value));
+    }
+    catch {
+        // Circular or otherwise non-serializable: keep a best-effort representation
+        // rather than throwing and losing the value entirely.
+        return JSON.stringify(String(value));
+    }
+};
+/**
+ * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) in the run's
+ * output folder and returns its path — **without** logging a pointer line. The
+ * path is computed synchronously (so callers can reference it in the same tick)
+ * while the write proceeds in the background. Use {@link snapshot} when you also
+ * want a `[snapshot]` line in the timeline; the event bus uses this directly to
+ * link a non-string payload from its own line.
+ */
+export const captureSnapshot = (name, value) => {
+    const safe = name.replace(/[^\w.-]+/g, "-");
+    const file = path.join(runDir(), `${safe}-${pad(++seq)}.json`);
+    const written = ensureDir().then(() => writeFile(file, `${serialize(value)}\n`, "utf8"));
+    // Normalize to forward slashes so the reference is portable in the log artifact.
+    const rel = path.relative(process.cwd(), file).replaceAll("\\", "/");
+    return { file, rel, written };
+};
+/**
+ * Writes raw text `lines` as a sequenced `.log` snapshot file in the run's output
+ * folder and returns its path refs — the text sibling of {@link captureSnapshot}
+ * (which writes JSON). {@link writeLog} uses it to off-load a collapsed output
+ * run from `run.log`, keeping the burst's full text one click away.
+ */
+export const captureText = (name, lines) => {
+    const safe = name.replace(/[^\w.-]+/g, "-");
+    const file = path.join(runDir(), `${safe}-${pad(++seq)}.log`);
+    const body = lines.length ? `${lines.join("\n")}\n` : "";
+    const written = ensureDir().then(() => writeFile(file, body, "utf8"));
+    // Normalize to forward slashes so the reference is portable in the log artifact.
+    const rel = path.relative(process.cwd(), file).replaceAll("\\", "/");
+    return { file, rel, written };
+};
+/**
+ * Captures any value as a JSON snapshot file (via {@link captureSnapshot}) and
+ * records a `[snapshot] <name>: <path>` line in the timeline at the point it's
+ * taken. Files are sequenced so repeated snapshots of the same name are kept as a
+ * history rather than overwritten. Callable any time, anywhere in the run;
+ * returns the file path once written.
+ */
+export const snapshot = (name, value) => {
+    const { file, rel, written } = captureSnapshot(name, value);
+    // Record the pointer synchronously, so it sits at the right spot in the timeline.
+    log.append({
+        source: "snapshot",
+        level: "snapshot",
+        message: `${name}: ${rel}`,
+    });
+    return written.then(() => file);
+};

package/dist/core/process.d.ts

@@ -0,0 +1,21 @@
+import { type Options, type ProcessPromise } from "zx";
+import type { Logger } from "./log-collector/LogsCollector.ts";
+/**
+ * Spawns a command (tagged-template, exactly like zx's `$`) and streams the
+ * child's stdout/stderr into a log (stdout as `info`, stderr as `error`) under
+ * the given `name`, killing the child when the bound signal aborts. Returns zx's
+ * `ProcessPromise`, so the caller can await it for the result.
+ *
+ * @example
+ * proc("build-docs", { cwd })`tskb ${pattern} --project ${name}`;
+ */
+export type Proc = (name: string, opts?: Partial<Options>) => (pieces: TemplateStringsArray, ...args: unknown[]) => ProcessPromise;
+/**
+ * Builds a {@link Proc} bound to a specific log sink and abort signal. The action
+ * pipeline injects one per action as `ctx.proc`, wired to that action's logger
+ * and the run's signal — so actions just describe the command, with no ambient
+ * lookup and nothing threaded through. A custom source (e.g. a CDP connection)
+ * follows the same shape: take the action's `logs`/`signal`, push into the log,
+ * and hook teardown.
+ */
+export declare const createProc: (logs: Logger, signal: AbortSignal) => Proc;

package/dist/core/process.js

@@ -0,0 +1,73 @@
+import os from "node:os";
+import { $, kill, usePowerShell } from "zx";
+import { captureSnapshot } from "./output.js";
+// zx defaults to bash, which isn't present on a stock Windows box.
+// Use Windows PowerShell there so zx spawns and quotes for the right shell.
+if (os.platform() === "win32")
+    usePowerShell();
+/**
+ * Builds a {@link Proc} bound to a specific log sink and abort signal. The action
+ * pipeline injects one per action as `ctx.proc`, wired to that action's logger
+ * and the run's signal — so actions just describe the command, with no ambient
+ * lookup and nothing threaded through. A custom source (e.g. a CDP connection)
+ * follows the same shape: take the action's `logs`/`signal`, push into the log,
+ * and hook teardown.
+ */
+export const createProc = (logs, signal) => (name, opts) => {
+    // quiet: zx must not echo the child's output to our terminal — the collector
+    // owns all output (otherwise every line prints twice: raw from zx, formatted
+    // from the drain). Caller opts can still override.
+    const $$ = $({ quiet: true, ...opts });
+    return (pieces, ...args) => {
+        const child = $$(pieces, ...args);
+        // Record the launch on the timeline as an event (the `event` level renders
+        // `[ev]`), under the proc's own `source` so it's filterable by origin in
+        // run.jsonl while still rendering as a milestone. The command zx resolved
+        // rides inline for scanning; the structured args (cmd, cwd, …) are written
+        // to a snapshot file and linked, exactly as the event bus does for a
+        // non-string payload (see events.ts).
+        //
+        // `env` is dropped: passing it to zx means handing the whole environment
+        // (you spread `...process.env` to add one var), so snapshotting it would
+        // write 600+ entries — secrets and tokens included — to logs/ on every
+        // launch. Everything else in opts is kept.
+        const { env: _env, ...safeOpts } = opts ?? {};
+        // Resolve where the child actually runs. zx only records cwd on its child
+        // when one was passed; left unset it falls back to process.cwd() at spawn,
+        // so mirror that here to always log a concrete directory (the `...safeOpts`
+        // spread sits before `cwd` so this resolved value wins even when opts omits
+        // it). This is the "where" that makes a launch line reproducible.
+        const cwd = opts?.cwd ?? process.cwd();
+        const snap = captureSnapshot(`proc-${name}-start`, { cmd: child.cmd, ...safeOpts, cwd });
+        logs.append({
+            source: name,
+            level: "event",
+            message: `${name} · start · ${child.cmd} · in ${cwd} · → ${snap.rel}`,
+        });
+        logs.attach(child.stdout, name, "info");
+        logs.attach(child.stderr, name, "error");
+        // Kill the child's entire process tree on teardown. `child.kill()` (zx's
+        // ProcessPromise method) throws "Too late to kill" when the direct child
+        // has already settled — but grandchildren (vite, tsc, npm scripts) may
+        // still be alive. Using zx's standalone `kill(pid)` bypasses that guard
+        // and does a cross-platform tree kill (taskkill /T /F on Windows,
+        // ps.tree + process-group kill on Unix).
+        let finished = false;
+        const onAbort = () => {
+            if (finished)
+                return;
+            const pid = child.pid;
+            if (pid != null)
+                void kill(pid).catch(() => { });
+        };
+        const markFinished = () => {
+            finished = true;
+            signal.removeEventListener("abort", onAbort);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        // Registered before the caller's own `.then`, so `finished` is set before a
+        // completion handler can fire `cancel()` and abort us.
+        void child.then(markFinished, markFinished);
+        return child;
+    };
+};

package/dist/core/run.d.ts

@@ -0,0 +1,95 @@
+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.
+ */
+export interface ActionFailure {
+    /** The failing action's name. */
+    readonly action: string;
+    /** Whatever it threw or rejected with. */
+    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
+ * single `await` yields the outcome instead of forcing a try/catch on awaiters.
+ */
+export interface RunResult {
+    /** 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:
+ *
+ *   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.
+ * - **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). */
+    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. */
+    readonly signal: AbortSignal;
+    /**
+     * Launch more actions into this same run — same controller, same log. Chainable.
+     *
+     * Throws if the run is no longer `open`: launching into a closing/closed run
+     * 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`).
+     */
+    run(...actions: AnyActionInstance[]): Run;
+    /** 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
+     * chains. Await `.done` for the verdict.
+     */
+    drain(write?: (message: string) => void): Run;
+}
+/**
+ * Starts the run: launches the given actions in parallel under one abort
+ * controller, against the process-wide global log. Returns a {@link Run} — add
+ * more actions on demand with `.run(…)`, observe `.done` for the verdict, stop
+ * with `.cancel()`. An optional leading {@link RunOptions} tunes failure policy.
+ *
+ * **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.
+ *
+ * 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
+ * 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`.
+ */
+export declare function run(...actions: AnyActionInstance[]): Run;
+export declare function run(options: RunOptions, ...actions: AnyActionInstance[]): Run;