omkit 0.0.8 → 0.0.9

package/dist/core/action.d.ts

@@ -91,12 +91,13 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
     /** Subscribe to a declared or system event (`done`/`error`) with a handler. */
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
     /**
-     * A promise for the next occurrence of an event: resolves with its payload —
-     * or rejects if the action settles first (`error`, or `done` without the
-     * event), so an awaiter never hangs. Use {@link on} for ongoing/handler
-     * subscriptions; `once` is the awaitable, one-value form.
+     * A promise for the next occurrence of an event. It **never rejects**: it
+     * resolves with the event's payload, or with `undefined` if the action settles
+     * (`done`) before the event ever fires — so awaiting it in a spin body can't
+     * throw and can't hang. `once("done")` yields the {@link Outcome}. Use {@link on}
+     * for ongoing/handler subscriptions; `once` is the awaitable, one-value form.
      */
-    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K]>;
+    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     /**
      * Gate this action on its **inputs** — the files/folders it *reads* (its
      * sources), **not** what it produces. `paths` (each a file or a folder) are
@@ -125,6 +126,12 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
  * still excluding non-instances.
  */
 export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
+/**
+ * If `value` is some action instance's `.ref` promise, the instance that owns it
+ * (the producer of that handle); otherwise `undefined`. Used by the run to verify
+ * a `.ref` dependency was launched before the action that consumes it.
+ */
+export declare const producerOfRef: (value: unknown) => AnyActionInstance | undefined;
 /** A callable produced by `action`: invoking it builds an {@link ActionInstance}. */
 export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
     (...args: Args): ActionInstance<Result, Events, Handle>;

package/dist/core/action.js

@@ -2,6 +2,16 @@ import { events } from "./events.js";
 import { createProc } from "./process.js";
 import { fingerprint, read, write, resolvePaths } from "./folder-cache.js";
 import { artifactsFolder } from "./output.js";
+// Maps an instance's `.ref` promise back to the instance that produces it, so the
+// run can catch a consumer launched before (or without) its `.ref` producer —
+// which would otherwise await a handle that never arrives and hang silently.
+const refOwners = new WeakMap();
+/**
+ * If `value` is some action instance's `.ref` promise, the instance that owns it
+ * (the producer of that handle); otherwise `undefined`. Used by the run to verify
+ * a `.ref` dependency was launched before the action that consumes it.
+ */
+export const producerOfRef = (value) => typeof value === "object" && value !== null ? refOwners.get(value) : undefined;
 /** A promise paired with its settlers, for the set-once handle. */
 const deferred = () => {
     let resolve;
@@ -18,15 +28,17 @@ const exitCodeOf = (error) => {
     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
- * error, and if it completes (`done`) without ever emitting `key` it rejects too
- * — so an awaiter can never hang. A retained snapshot resolves it immediately.
+ * A promise for the next emit of `key`. It **never rejects**: it resolves with
+ * the event's payload, or with `undefined` if the action settles (`done` — which
+ * always fires) before `key` ever does. So an awaiter neither hangs nor throws:
+ * a waited-for event that won't come simply yields `undefined`. A retained
+ * snapshot resolves it immediately. (Not used for `key === "done"`, which reads
+ * straight from the settled Outcome.)
  */
-const awaitEvent = (emitter, name, key) => new Promise((resolve, reject) => {
+const awaitEvent = (emitter, key) => new Promise((resolve) => {
     const offs = [];
     let settled = false;
-    // First of [the event | error | done] to fire wins; the rest are unsubscribed.
+    // First of [the event | done] to fire wins; the rest are unsubscribed.
     const settle = (act) => {
         if (settled)
             return;
@@ -35,15 +47,14 @@ const awaitEvent = (emitter, name, key) => new Promise((resolve, reject) => {
             off();
         act();
     };
-    // listenOnce is keyed by E; the system keys (error/done) are always present
-    // on an instance's event map, so reach them through a loosened view.
+    // listenOnce is keyed by E; the system `done` key is always present on an
+    // instance's event map, so reach it through a loosened view.
     const listen = emitter.listenOnce;
     offs.push(listen(key, (payload) => settle(() => resolve(payload))));
-    if (key !== "error") {
-        offs.push(listen("error", (err) => settle(() => reject(err))));
-    }
+    // `done` fires once on any settle (success or failure); if it beats `key`,
+    // the event will never come — resolve `undefined` rather than reject.
     if (key !== "done") {
-        offs.push(listen("done", () => settle(() => reject(new Error(`${name}: settled before "${String(key)}"`)))));
+        offs.push(listen("done", () => settle(() => resolve(undefined))));
     }
     // A retained snapshot fires a listen synchronously during registration; if
     // that already settled us, drop any listeners registered afterwards.
@@ -111,8 +122,8 @@ const build = (name, exec) => {
             }, (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`.
+                // Emit `error` (for `.on("error")` handlers), then settle `done` with
+                // the Outcome — the canonical failure signal that `.done`/`once` read.
                 systemEmit("error", error);
                 settled.resolve(outcome);
                 systemEmit("done", outcome);
@@ -128,10 +139,9 @@ const build = (name, exec) => {
             },
             once(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));
+                // reads straight from the settled promise; other keys race via awaitEvent
+                // (which resolves `undefined` if the action settles before the event).
+                return (key === "done" ? settled.promise : awaitEvent(emitter, 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
@@ -159,6 +169,9 @@ const build = (name, exec) => {
                 })();
             },
         };
+        // Register this instance as the producer of its `.ref`, so the run can catch
+        // a consumer built with this `.ref` that gets launched before this instance.
+        refOwners.set(instance.ref, instance);
         return instance;
     };
     return Object.assign(create, { actionName: name });

package/dist/core/log-collector/LogsCollector.d.ts

@@ -38,6 +38,8 @@ export interface Logger {
 export declare class LogsCollector implements Logger {
     private sequence;
     private readonly history;
+    private readonly maxHistory;
+    private readonly trimHistoryTo;
     private readonly subscribers;
     private ended;
     /**
@@ -50,12 +52,12 @@ export declare class LogsCollector implements Logger {
     /** Raw store: records the line verbatim, source included; presentation is the renderer's job. */
     append(entry: LogInput): void;
     /**
-     * Bind the run's abort signal: when it aborts (teardown), every subscription
-     * ends — each parked or future `for await` returns — so subscribers don't each
-     * have to watch the signal. The collector *is* the world's log and the signal
-     * is the world ending; the log closes with it.
+     * End the log: every subscription returns and no new one is accepted. Called
+     * once at run finalize — *after* the last entry (e.g. `finished`) is appended —
+     * so `streamLog` captures the whole run before its stream closes. Kept separate
+     * from teardown so entries logged *during* teardown still stream/drain live.
      */
-    endOn(signal: AbortSignal): void;
+    close(): void;
     /** EOF for readers: end every live subscription and refuse to register new ones. */
     private closeAll;
     subscribe({ replay }?: SubscribeOptions): AsyncIterable<LogEntry>;

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

@@ -1,7 +1,14 @@
 import { AsyncQueue } from "../helpers/AsyncQueue.js";
 export class LogsCollector {
     sequence = 0;
+    // Recent entries retained in memory, only to replay to late subscribers. The
+    // *complete* record is streamed to run.jsonl on disk, so this is capped — an
+    // indefinite run (dev servers, tailing big logs) must not grow without bound.
     history = [];
+    // Cap and the size we trim back to when it's exceeded (trimming in batches keeps
+    // append amortized O(1) instead of O(n) per line once full).
+    maxHistory = 100_000;
+    trimHistoryTo = 90_000;
     subscribers = new Set();
     // Set once the bound signal aborts: the log has reached EOF for readers.
     ended = false;
@@ -24,22 +31,23 @@ export class LogsCollector {
             timestamp: Date.now(),
         };
         this.history.push(log);
+        // Cap the in-memory history — the durable copy is already on disk (run.jsonl).
+        if (this.history.length > this.maxHistory) {
+            this.history.splice(0, this.history.length - this.trimHistoryTo);
+        }
         for (const subscriber of this.subscribers) {
             // push the log into the queue for every subscriber to receive
             subscriber.push(log);
         }
     }
     /**
-     * Bind the run's abort signal: when it aborts (teardown), every subscription
-     * ends — each parked or future `for await` returns — so subscribers don't each
-     * have to watch the signal. The collector *is* the world's log and the signal
-     * is the world ending; the log closes with it.
+     * End the log: every subscription returns and no new one is accepted. Called
+     * once at run finalize — *after* the last entry (e.g. `finished`) is appended —
+     * so `streamLog` captures the whole run before its stream closes. Kept separate
+     * from teardown so entries logged *during* teardown still stream/drain live.
      */
-    endOn(signal) {
-        if (signal.aborted)
-            this.closeAll();
-        else
-            signal.addEventListener("abort", () => this.closeAll(), { once: true });
+    close() {
+        this.closeAll();
     }
     /** EOF for readers: end every live subscription and refuse to register new ones. */
     closeAll() {

package/dist/core/log-collector/render.d.ts

@@ -38,13 +38,24 @@ export interface SegmentOptions {
     threshold?: number;
 }
 /**
- * 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.
+ * A stateful, **streaming** segmenter: `push` each {@link LogEntry} in order and
+ * it returns the {@link DisplayItem}s that just became final (0, 1, or a whole
+ * flushed run), then `end()` flushes the last pending run. Only the current
+ * same-source run is held in memory, so segmenting a huge log stays bounded —
+ * {@link writeLog} feeds it straight from `run.jsonl` on disk. Output is
+ * byte-identical to {@link segmentForFile}. Pure — no filesystem.
  */
-export declare const segmentForFile: (entries: readonly LogEntry[], { threshold }?: SegmentOptions) => DisplayItem[];
+export declare const createFileSegmenter: ({ threshold }?: SegmentOptions) => {
+    push(entry: LogEntry): DisplayItem[];
+    end(): DisplayItem[];
+};
+/**
+ * Segments a full, ordered entry list into {@link DisplayItem}s (the array form of
+ * {@link createFileSegmenter}). 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.
+ */
+export declare const segmentForFile: (entries: readonly LogEntry[], options?: SegmentOptions) => DisplayItem[];
 /**
  * Renders a {@link CollapsedRun} as its `head` lines under the `▸ <source>`
  * header, then a single indented `📎` pointer line to the off-loaded snapshot at

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

@@ -49,27 +49,27 @@ 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.
+ * A stateful, **streaming** segmenter: `push` each {@link LogEntry} in order and
+ * it returns the {@link DisplayItem}s that just became final (0, 1, or a whole
+ * flushed run), then `end()` flushes the last pending run. Only the current
+ * same-source run is held in memory, so segmenting a huge log stays bounded —
+ * {@link writeLog} feeds it straight from `run.jsonl` on disk. Output is
+ * byte-identical to {@link segmentForFile}. Pure — no filesystem.
  */
-export const segmentForFile = (entries, { threshold = COLLAPSE_THRESHOLD } = {}) => {
-    const items = [];
+export const createFileSegmenter = ({ threshold = COLLAPSE_THRESHOLD } = {}) => {
     // 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 = () => {
+    // Flush the pending run into `out`: collapse it if it ran long, else emit
+    // grouped lines exactly as createRenderer would (header first, indent the rest).
+    const flush = (out) => {
         if (!run)
             return;
         if (run.lines.length > threshold) {
-            items.push({ kind: "collapsed", run: { source: run.source, lines: run.lines } });
+            out.push({ kind: "collapsed", run: { source: run.source, lines: run.lines } });
         }
         else {
             run.lines.forEach((message, i) => {
-                items.push({
+                out.push({
                     kind: "line",
                     text: i === 0 ? `${marker("action", run.source)}\n\t${message}` : `\t${message}`,
                 });
@@ -77,23 +77,44 @@ export const segmentForFile = (entries, { threshold = COLLAPSE_THRESHOLD } = {})
         }
         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 {
+        push(entry) {
+            const out = [];
+            const milestone = MILESTONE[entry.level];
+            if (milestone) {
+                // A milestone breaks the current run, then renders as its own line.
+                flush(out);
+                out.push({ kind: "line", text: marker(milestone, entry.message) });
+                return out;
+            }
+            if (run && run.source === entry.source) {
+                run.lines.push(entry.message);
+            }
+            else {
+                flush(out);
+                run = { source: entry.source, lines: [entry.message] };
+            }
+            return out;
+        },
+        end() {
+            const out = [];
+            flush(out);
+            return out;
+        },
+    };
+};
+/**
+ * Segments a full, ordered entry list into {@link DisplayItem}s (the array form of
+ * {@link createFileSegmenter}). 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.
+ */
+export const segmentForFile = (entries, options = {}) => {
+    const seg = createFileSegmenter(options);
+    const items = [];
+    for (const entry of entries)
+        items.push(...seg.push(entry));
+    items.push(...seg.end());
     return items;
 };
 /**

package/dist/core/output.d.ts

@@ -9,24 +9,28 @@ import type { LogsCollector } from "./log-collector/LogsCollector.ts";
  */
 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):
+ * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
+ * complete record {@link streamLog} wrote), **streaming** it line by line so the
+ * whole run is never held in memory. Grouping/indentation is applied here so the
+ * stored `run.jsonl` stays presentation-free; large same-source runs are collapsed
+ * — off-loaded to a text snapshot and replaced inline by their head plus a pointer
+ * — so one proc's burst can't drown the timeline. `run.jsonl` is left as-is (it's
+ * the full raw record). Returns the `run.log` path (surfaced to the terminal).
  *
- * - `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).
+ * Call only after {@link streamLog} has closed (the run's log is ended), so
+ * `run.jsonl` is complete and no longer being written.
  */
-export declare const writeLog: (logs: LogsCollector) => Promise<string>;
+export declare const writeLog: () => 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.
+ * Streams every log entry to `run.jsonl` (the complete, authoritative record) and
+ * a live `run.log` incrementally as they arrive, so output survives a hard kill or
+ * lost SIGINT. The log is closed once at finalize, after which {@link writeLog}
+ * re-renders `run.log` from `run.jsonl` in collapsed form.
+ *
+ * Subscribes **synchronously, before any `await`** — so a fast synchronous
+ * producer that appends (and trims the in-memory history) before the file setup
+ * finishes still has its entries buffered on the subscription queue rather than
+ * lost. `replay: true` covers anything already logged when this is called.
  */
 export declare const streamLog: (logs: LogsCollector) => Promise<void>;
 /** A written (or in-flight) snapshot file and where to find it. */

package/dist/core/output.js

@@ -1,8 +1,9 @@
-import { createWriteStream, mkdirSync } from "node:fs";
+import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
 import path from "node:path";
 import { log } from "./log-collector/global.js";
-import { COLLAPSE_HEAD, createRenderer, renderCollapsed, segmentForFile, } from "./log-collector/render.js";
+import { COLLAPSE_HEAD, createFileSegmenter, createRenderer, renderCollapsed, } 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 = () => {
@@ -53,52 +54,73 @@ const logHeader = () => {
     ].join("\n");
 };
 /**
- * Drains the collected log to two files in the run's output folder (the common
- * `logs/<name>/<date>/<time>/` convention, local time):
+ * Renders the final, collapsed `run.log` from the authoritative `run.jsonl` (the
+ * complete record {@link streamLog} wrote), **streaming** it line by line so the
+ * whole run is never held in memory. Grouping/indentation is applied here so the
+ * stored `run.jsonl` stays presentation-free; large same-source runs are collapsed
+ * — off-loaded to a text snapshot and replaced inline by their head plus a pointer
+ * — so one proc's burst can't drown the timeline. `run.jsonl` is left as-is (it's
+ * the full raw record). Returns the `run.log` path (surfaced to the terminal).
  *
- * - `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).
+ * Call only after {@link streamLog} has closed (the run's log is ended), so
+ * `run.jsonl` is complete and no longer being written.
  */
-export const writeLog = async (logs) => {
+export const writeLog = async () => {
     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 jsonlFile = path.join(runDir(), "run.jsonl");
     const file = path.join(runDir(), "run.log");
-    const header = logHeader();
+    const out = createWriteStream(file);
+    out.write(logHeader());
+    const seg = createFileSegmenter();
     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");
+    const emit = (item) => {
+        if (item.kind === "line") {
+            out.write(item.text + "\n");
+        }
+        else {
+            const snap = captureText(`output-${item.run.source}`, item.run.lines);
+            writes.push(snap.written);
+            out.write(renderCollapsed(item.run, { head: COLLAPSE_HEAD, rel: snap.rel }) + "\n");
+        }
+    };
+    try {
+        const rl = createInterface({ input: createReadStream(jsonlFile), crlfDelay: Infinity });
+        for await (const line of rl) {
+            if (!line)
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue; // a torn final line (dirty exit) — skip it
+            }
+            for (const item of seg.push(entry))
+                emit(item);
+        }
+    }
+    catch {
+        // run.jsonl missing/unreadable (e.g. a very early crash) — write what we have.
+    }
+    for (const item of seg.end())
+        emit(item);
+    await streamClosed(out); // flush + close run.log before reporting it written
+    await Promise.all(writes); // ensure every off-loaded run is on disk
     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.
+ * Streams every log entry to `run.jsonl` (the complete, authoritative record) and
+ * a live `run.log` incrementally as they arrive, so output survives a hard kill or
+ * lost SIGINT. The log is closed once at finalize, after which {@link writeLog}
+ * re-renders `run.log` from `run.jsonl` in collapsed form.
+ *
+ * Subscribes **synchronously, before any `await`** — so a fast synchronous
+ * producer that appends (and trims the in-memory history) before the file setup
+ * finishes still has its entries buffered on the subscription queue rather than
+ * lost. `replay: true` covers anything already logged when this is called.
  */
 export const streamLog = async (logs) => {
+    const entries = logs.subscribe({ replay: true });
     await ensureDir();
     const jsonlFile = path.join(runDir(), "run.jsonl");
     const logFile = path.join(runDir(), "run.log");
@@ -107,17 +129,18 @@ export const streamLog = async (logs) => {
     const render = createRenderer();
     pretty.write(logHeader() + "\n");
     try {
-        for await (const entry of logs.subscribe({ replay: true })) {
+        for await (const entry of entries) {
             jsonl.write(JSON.stringify(entry) + "\n");
             pretty.write(render(entry) + "\n");
         }
     }
     finally {
         // End AND wait for both streams to fully close before resolving. {@link writeLog}
-        // truncates and rewrites these same files at finalize; if a buffered chunk from
-        // this stream landed *after* that truncation, the OS would zero-fill the gap —
-        // a multi-MB run of NUL bytes in run.log. `run` awaits this promise before
-        // calling `writeLog`, so this writer is guaranteed done before the rewrite.
+        // re-renders run.log at finalize (from this run.jsonl); if a buffered chunk from
+        // this stream landed *after* writeLog truncated run.log, the OS would zero-fill
+        // the gap — a multi-MB run of NUL bytes. `run` awaits this promise before
+        // calling `writeLog`, so this writer is guaranteed done first (and run.jsonl is
+        // complete for writeLog to read).
         await Promise.all([streamClosed(jsonl), streamClosed(pretty)]);
     }
 };

package/dist/core/run.d.ts

@@ -1,4 +1,4 @@
-import type { AnyActionInstance } from "./action.ts";
+import { type AnyActionInstance } from "./action.ts";
 import { log as logs } from "./log-collector/global.ts";
 /**
  * A single action's failure, captured for the spin's verdict. Cascade failures —

package/dist/core/run.js

@@ -1,4 +1,5 @@
 import { relative } from "node:path";
+import { producerOfRef } from "./action.js";
 import { log as logs } from "./log-collector/global.js";
 import { createRenderer } from "./log-collector/render.js";
 import { streamLog, writeLog } from "./output.js";
@@ -61,9 +62,9 @@ export function run(...actions) {
         assertInstance(instance);
     started = true;
     const controller = new AbortController();
-    // The log closes when the run tears down, so every `logs.subscribe(…)` ends on
-    // its own — no subscriber has to watch the signal.
-    logs.endOn(controller.signal);
+    // 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.
     // ── 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.
@@ -131,7 +132,21 @@ export function run(...actions) {
     // stream lands past writeLog's truncation and the OS zero-fills the gap (a
     // multi-MB NUL run in run.log).
     const streaming = streamLog(logs).catch(() => { });
+    // Instances launched so far — used to verify a `.ref` dependency was launched
+    // before the action that consumes its handle.
+    const launched = new WeakSet();
     const launch = (instance) => {
+        // 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 && !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.`);
+            }
+        }
+        launched.add(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 spin's signal directly; the
@@ -187,11 +202,13 @@ export function run(...actions) {
         process.off("uncaughtException", onUncaught);
         process.off("unhandledRejection", onUnhandled);
         narrate("finished");
-        // Wait for the incremental streamer to fully close its files, so its last
-        // flush can't land after writeLog truncates+rewrites them (which would leave
-        // a NUL gap). The log is already closed, so this resolves promptly.
+        // 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.
+        logs.close();
         await streaming;
-        const file = await writeLog(logs);
+        const file = await writeLog();
         // Direct to the terminal — the file's already written, so this line isn't in it.
         console.log(marker("run", `log → ${file}`));
         const result = { ok: failures.length === 0, failures };

package/dist/core/spin.js

@@ -29,7 +29,16 @@ export function spin(a, b) {
             artifactsFolder: artifactsFolder(),
         });
     });
-    host = run(hosted());
+    const hostInstance = hosted();
+    host = run(hostInstance);
+    // 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 hostInstance.done.then((outcome) => {
+        if (!outcome.ok)
+            host.cancel();
+    });
     if (autoDrain)
         startDrain();
     return host;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "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",