omkit 0.0.14 → 0.1.0

package/dist/system/proc.js

@@ -0,0 +1,148 @@
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import { $, usePowerShell } from "zx";
+import { ProcRegistry, winSnapshot } from "./procRegistry.js";
+// zx defaults to bash, absent on a stock Windows box — use PowerShell there.
+if (os.platform() === "win32")
+    usePowerShell();
+/**
+ * Force-kill a process **and its whole tree, synchronously**.
+ *
+ * On POSIX the child is spawned as its own process-group leader (see createProc), so
+ * `kill(-pid)` reaps the whole group in one call — every descendant, re-parented or not.
+ *
+ * On Windows there are no process groups and we can't detach (a console-less child breaks
+ * npm/vite — see createProc), so a mashed Ctrl+C sent to the shared console can make an
+ * intermediate shell (powershell/npm/npx) exit and orphan its real leaf (vite,
+ * chromedriver.exe) before teardown reaps it. `taskkill /F /T` force-kills the live tree
+ * by PID, but a leaf whose intermediate already exited can't be reached via `/T` — that
+ * mash-Ctrl+C orphan is a known Windows edge, mitigated by a port/PID sweep on teardown
+ * rather than by detaching. Best-effort: an already-dead PID is ignored.
+ */
+export const killTree = (pid) => {
+    if (process.platform === "win32") {
+        try {
+            execFileSync("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore" });
+        }
+        catch {
+            // already gone, access denied, or taskkill missing — nothing more to do
+        }
+    }
+    else {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            // already gone
+        }
+    }
+};
+// A single --inspect* flag in NODE_OPTIONS, matched only when it stands alone (so it
+// never eats a prefix like `--inspector-foo`): --inspect / --inspect-brk / --inspect-port
+// / --inspect-publish-uid, each with an optional `=value`.
+const INSPECT_FLAG = /--inspect(?:-brk|-port|-publish-uid)?(?:=\S+)?(?=\s|$)/g;
+// `--require <arg>` whose arg points at VS Code's js-debug auto-attach bootloader.
+const VSCODE_BOOTLOADER_REQUIRE = /--require\s+("[^"]*"|\S+)/g;
+/**
+ * A copy of `env` with the orchestrator's debugger stripped, so a spawned child runs
+ * clean instead of inheriting our inspector. Removes `--inspect*` flags from
+ * `NODE_OPTIONS`, drops VS Code auto-attach's injected bootloader `--require` and its
+ * `VSCODE_INSPECTOR_OPTIONS` handshake, and deletes `NODE_OPTIONS` entirely if nothing
+ * else remains. A legitimate non-debug `--require` and any other options are preserved.
+ * Does not mutate the input.
+ */
+export const debuggerFreeEnv = (env) => {
+    const clean = { ...env };
+    delete clean.VSCODE_INSPECTOR_OPTIONS;
+    const nodeOptions = clean.NODE_OPTIONS;
+    if (nodeOptions !== undefined) {
+        const stripped = nodeOptions
+            .replace(VSCODE_BOOTLOADER_REQUIRE, (whole, arg) => /js-debug|bootloader/i.test(arg) ? "" : whole)
+            .replace(INSPECT_FLAG, "")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (stripped)
+            clean.NODE_OPTIONS = stripped;
+        else
+            delete clean.NODE_OPTIONS;
+    }
+    return clean;
+};
+/**
+ * The run-wide orphan reaper. `createProc` registers each shell it spawns (Windows only);
+ * the ExecutionTree calls `procRegistry.sweep()` at teardown to reap any that a mashed
+ * Ctrl+C orphaned. A no-op in practice off Windows (nothing is tracked there).
+ */
+export const procRegistry = new ProcRegistry(winSnapshot, killTree);
+/**
+ * Build a {@link Proc} bound to a log sink and abort signal. The framework injects
+ * one per action as `ctx.proc`, wired to that action's log and the run's signal, so
+ * actions just describe the command — output streams in, the child dies on teardown.
+ */
+export const createProc = (sink, signal) => (name, opts) => {
+    const { inheritDebugger, ...zxOpts } = opts ?? {};
+    // Children run debugger-free by default: our inspector (a VS Code auto-attach
+    // NODE_OPTIONS, or a plain --inspect) would otherwise be inherited by every child,
+    // spamming "Debugger attached", stalling teardown on "waiting for the debugger to
+    // disconnect" (so ports stay held into the next run), and hiding the real error.
+    // Opt in per-proc with `inheritDebugger`, or globally with OMKIT_INHERIT_DEBUGGER.
+    const inherit = inheritDebugger ?? Boolean(process.env.OMKIT_INHERIT_DEBUGGER);
+    const baseEnv = zxOpts.env ?? process.env;
+    // quiet: the log owns all output; zx must not also echo to the terminal.
+    // detached (POSIX only): give the child its own process group so `killTree` can reap
+    // the whole group atomically with `kill(-pid)`. On POSIX this also isolates it from the
+    // terminal's Ctrl+C (only the foreground group is signalled). We do NOT detach on
+    // Windows: there `detached` means DETACHED_PROCESS (no console), and console commands
+    // like npm/vite then exit immediately with no output — so the Windows Ctrl+C-orphan
+    // edge is handled another way, not by detaching.
+    const $$ = $({
+        quiet: true,
+        detached: process.platform !== "win32",
+        ...zxOpts,
+        env: (inherit ? { ...baseEnv } : debuggerFreeEnv(baseEnv)),
+    });
+    return (pieces, ...args) => {
+        const child = $$(pieces, ...args);
+        const cwd = opts?.cwd ?? process.cwd();
+        sink(name, "event", `${name} · start · ${child.cmd} · in ${cwd}`);
+        void streamLines(child.stdout, (line) => sink(name, "info", line));
+        void streamLines(child.stderr, (line) => sink(name, "error", line));
+        // On Windows (where we can't detach) track this shell's pid, so the run's teardown
+        // sweep can reap a grandchild orphaned by a mashed Ctrl+C — see procRegistry.
+        if (process.platform === "win32" && typeof child.pid === "number") {
+            procRegistry.track(child.pid);
+        }
+        // Kill the child's tree on teardown; unhook once it settles on its own.
+        let finished = false;
+        const onAbort = () => {
+            if (!finished && typeof child.pid === "number")
+                killTree(child.pid);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        const done = () => {
+            finished = true;
+            signal.removeEventListener("abort", onAbort);
+            if (typeof child.pid === "number")
+                procRegistry.untrack(child.pid);
+        };
+        void child.then(done, done);
+        return child;
+    };
+};
+/** Split a byte/string stream into lines, calling `onLine` for each non-empty one. */
+async function streamLines(stream, onLine) {
+    let buffer = "";
+    for await (const chunk of stream) {
+        buffer += String(chunk);
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).replace(/\r$/, "");
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                onLine(line);
+        }
+    }
+    const tail = buffer.replace(/\r$/, "");
+    if (tail)
+        onLine(tail);
+}

package/dist/system/procRegistry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * One process in a snapshot: its id, its parent's id, and an opaque identity token
+ * (its creation time) that distinguishes a live process from a later reuse of its pid.
+ */
+export interface ProcInfo {
+    pid: number;
+    ppid: number;
+    id: string;
+}
+/** Takes a snapshot of every live process. Injected so it's swappable + unit-testable. */
+export type Snapshot = () => ProcInfo[];
+/**
+ * A safety net for the Windows Ctrl+C-orphan edge (see {@link import("./proc.ts").killTree}).
+ * We only ever spawn a *shell*, so `killTree` on the shell's pid can miss a re-parented
+ * grandchild (vite, chromedriver) when a mashed Ctrl+C kills the intermediate first.
+ *
+ * This registry closes that gap: it polls the process table while a tracked root's tree is
+ * intact and **accumulates the descendant pids** (with their identity). On teardown, `sweep`
+ * force-kills every recorded descendant that is *still alive with the same identity* — so an
+ * orphan is reaped even after it re-parented, while a since-reused pid (identity changed) or
+ * a cleanly-exited pid is left alone. Roots themselves stay `killTree`'s job.
+ *
+ * Pure and platform-agnostic; the caller decides when it applies (POSIX reaps via the process
+ * group, so `proc.ts` only tracks on Windows).
+ */
+export declare class ProcRegistry {
+    private readonly snapshot;
+    private readonly kill;
+    private readonly intervalMs;
+    private readonly roots;
+    private readonly known;
+    private timer;
+    constructor(snapshot: Snapshot, kill: (pid: number) => void, intervalMs?: number);
+    /** Start tracking a spawned root (shell) pid; begins polling if not already. */
+    track(pid: number): void;
+    /** Stop tracking a root that settled on its own. Already-recorded descendants are kept. */
+    untrack(pid: number): void;
+    /** One poll tick: record every current descendant of every tracked root. */
+    poll(): void;
+    /**
+     * Teardown sweep: kill every recorded descendant still alive under its original identity.
+     * Stops polling and clears state, so it's safe to call once at finalize.
+     */
+    sweep(): void;
+    private stop;
+}
+/**
+ * Default Windows snapshot: one `Get-CimInstance Win32_Process` call, projected to
+ * `{ pid, ppid, id }` where `id` is the process creation time (ticks) — stable per process,
+ * different across a pid reuse. Best-effort: any failure yields an empty snapshot.
+ */
+export declare const winSnapshot: Snapshot;

package/dist/system/procRegistry.js

@@ -0,0 +1,117 @@
+import { execFileSync } from "node:child_process";
+/**
+ * A safety net for the Windows Ctrl+C-orphan edge (see {@link import("./proc.ts").killTree}).
+ * We only ever spawn a *shell*, so `killTree` on the shell's pid can miss a re-parented
+ * grandchild (vite, chromedriver) when a mashed Ctrl+C kills the intermediate first.
+ *
+ * This registry closes that gap: it polls the process table while a tracked root's tree is
+ * intact and **accumulates the descendant pids** (with their identity). On teardown, `sweep`
+ * force-kills every recorded descendant that is *still alive with the same identity* — so an
+ * orphan is reaped even after it re-parented, while a since-reused pid (identity changed) or
+ * a cleanly-exited pid is left alone. Roots themselves stay `killTree`'s job.
+ *
+ * Pure and platform-agnostic; the caller decides when it applies (POSIX reaps via the process
+ * group, so `proc.ts` only tracks on Windows).
+ */
+export class ProcRegistry {
+    snapshot;
+    kill;
+    intervalMs;
+    roots = new Set();
+    known = new Map(); // descendant pid → identity, accumulated
+    timer;
+    constructor(snapshot, kill, 
+    // A snapshot costs ~½s (powershell startup), and daemon leaves are long-lived and stable,
+    // so poll unhurriedly — a mashed Ctrl+C always lands well after the platform is up, by
+    // which point the leaves have been recorded. Swap `winSnapshot` for a faster backend
+    // (wmic / a native process-list) if this churn ever matters.
+    intervalMs = 5000) {
+        this.snapshot = snapshot;
+        this.kill = kill;
+        this.intervalMs = intervalMs;
+    }
+    /** Start tracking a spawned root (shell) pid; begins polling if not already. */
+    track(pid) {
+        this.roots.add(pid);
+        if (!this.timer) {
+            this.timer = setInterval(() => this.poll(), this.intervalMs);
+            this.timer.unref?.();
+        }
+    }
+    /** Stop tracking a root that settled on its own. Already-recorded descendants are kept. */
+    untrack(pid) {
+        this.roots.delete(pid);
+        if (this.roots.size === 0)
+            this.stop();
+    }
+    /** One poll tick: record every current descendant of every tracked root. */
+    poll() {
+        if (this.roots.size === 0)
+            return;
+        const byParent = new Map();
+        for (const p of this.snapshot()) {
+            const siblings = byParent.get(p.ppid);
+            if (siblings)
+                siblings.push(p);
+            else
+                byParent.set(p.ppid, [p]);
+        }
+        const stack = [...this.roots];
+        const seen = new Set();
+        while (stack.length > 0) {
+            const parent = stack.pop();
+            for (const child of byParent.get(parent) ?? []) {
+                if (seen.has(child.pid))
+                    continue;
+                seen.add(child.pid);
+                this.known.set(child.pid, child.id);
+                stack.push(child.pid);
+            }
+        }
+    }
+    /**
+     * Teardown sweep: kill every recorded descendant still alive under its original identity.
+     * Stops polling and clears state, so it's safe to call once at finalize.
+     */
+    sweep() {
+        this.stop();
+        if (this.known.size === 0) {
+            this.roots.clear();
+            return;
+        }
+        const current = new Map(this.snapshot().map((p) => [p.pid, p.id]));
+        for (const [pid, id] of this.known) {
+            if (current.get(pid) === id)
+                this.kill(pid);
+        }
+        this.known.clear();
+        this.roots.clear();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+}
+/**
+ * Default Windows snapshot: one `Get-CimInstance Win32_Process` call, projected to
+ * `{ pid, ppid, id }` where `id` is the process creation time (ticks) — stable per process,
+ * different across a pid reuse. Best-effort: any failure yields an empty snapshot.
+ */
+export const winSnapshot = () => {
+    try {
+        const out = execFileSync("powershell", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,@{n='I';e={ if ($_.CreationDate) { $_.CreationDate.Ticks } else { 0 } }} | ConvertTo-Json -Compress",
+        ], { encoding: "utf8", windowsHide: true, maxBuffer: 32 * 1024 * 1024 });
+        const parsed = JSON.parse(out);
+        const rows = Array.isArray(parsed) ? parsed : [parsed];
+        return rows.map((r) => ({ pid: r.ProcessId, ppid: r.ParentProcessId, id: String(r.I) }));
+    }
+    catch {
+        return [];
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "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",
@@ -24,6 +24,7 @@
     "dev": "tsc --watch",
     "clean": "rimraf dist",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "author": "Dimitar Mihaylov",
@@ -48,6 +49,7 @@
     "developer-tools"
   ],
   "dependencies": {
+    "patch-console": "^2.0.0",
     "playwright-core": "^1.49.0",
     "zx": "^8.8.5"
   },

package/dist/orchestration/action/action.d.ts

@@ -1,23 +0,0 @@
-import type { ActionBuilder, AnyActionInstance, NoEvents } from "./types.ts";
-/**
- * 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;
-/**
- * Defines an action. Always returns a builder; provide the implementation via
- * `.run(…)`, optionally after declaring events and/or a handle:
- *
- *   action("Build").run(async (ctx, opts) => { … })       // no declared events / handle
- *   action("Watch")                                       // typed events + handle
- *     .emits<{ create: string }>()
- *     .ref<{ rescan(): void }>()
- *     .run((ctx, opts) => { ctx.emit(…); ctx.attach(…); … })
- *
- * `.run(…)` yields a callable that, when invoked, constructs an
- * {@link ActionInstance} (deferred — the run executes it). Instances expose
- * chainable `.on` / `.once` (declared events plus `done`/`error`); the attached
- * handle is awaited via `instance.ref`.
- */
-export declare function action(name: string): ActionBuilder<NoEvents, void>;

package/dist/orchestration/action/action.js

@@ -1,256 +0,0 @@
-import { events } from "../events/events.js";
-import { createProc } from "../../system/process/process.js";
-import { FolderCache } from "../../system/fs/FolderCache.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 constructed-but-not-yet-run action — everything a single launch needs, in one
- * object: its own event bus, its set-once handle (`ref`) and Outcome (`done`), and
- * the `start` that runs the impl and settles them. Self-contained: `start()`
- * resolves with the {@link Outcome} and **never rejects** (a failing action is
- * data, not a throw), so a launcher just awaits `.done`.
- */
-class ActionRun {
-    name;
-    args;
-    /** The attached handle, awaited via `.ref` (settled by `attach`, or by `start` on settle). */
-    ref;
-    /** The action's Outcome — resolves (never rejects) once it settles. */
-    done;
-    exec;
-    // The bus covers declared + system events; `ctx.emit` is narrowed to the declared
-    // ones, while the framework emits attached/done/error through the same bus.
-    emitter;
-    handle;
-    settled;
-    attached = false;
-    constructor(name, exec, args) {
-        this.name = name;
-        this.exec = exec;
-        this.args = args;
-        this.emitter = events(name);
-        this.handle = ActionRun.defer();
-        this.settled = ActionRun.defer();
-        this.ref = this.handle.promise;
-        this.done = this.settled.promise;
-        // Most actions have a `void` handle and no one awaits `ref`; mark the promise
-        // handled so a settle-time rejection on such an instance doesn't surface as an
-        // unhandled rejection. Real awaiters of `ref` still receive the rejection.
-        void this.handle.promise.catch(() => { });
-        // 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(this.ref, this);
-    }
-    start(system) {
-        // `ctx.emit` is the declared-events view of the same bus.
-        const emit = this.emitter.emit;
-        // The bus is pure pub/sub; logging each emit onto the timeline is layered here,
-        // through this action's *scoped* logger — so an emit's line inherits the action's
-        // path (`parent › child › event`) just like its other output, and the bus stays
-        // free of any global. Registered once per run of this instance.
-        this.emitter.onAny((key, payload) => ActionRun.logEmit(system, this.name, String(key), payload));
-        // `Promise.resolve().then` normalizes a sync result and routes a sync throw to
-        // the `error` path, so exec may be sync or async.
-        return Promise.resolve()
-            .then(() => this.exec({
-            ...system,
-            emit,
-            attach: (value) => this.attach(value),
-            proc: createProc(system.logs, system.signal, system.output.snapshots),
-            artifactsFolder: system.output.folder.artifacts(),
-            snapshot: (name, value) => system.output.snapshots.snapshot(name, value),
-        }, ...this.args))
-            .then((result) => {
-            const outcome = { ok: true, value: result };
-            this.settled.resolve(outcome);
-            this.systemEmit("done", outcome);
-            // Settle `ref` if the action finished without attaching, so awaiters
-            // resolve (with `undefined` for the default void handle) rather than
-            // hang. Idempotent — a no-op when a handle was already attached.
-            this.handle.resolve(undefined);
-            return outcome;
-        }, (error) => {
-            const exitCode = ActionRun.exitCodeOf(error);
-            const outcome = exitCode === undefined ? { ok: false, error } : { ok: false, error, exitCode };
-            // Emit `error` (for `.on("error")` handlers), then settle `done` with the
-            // Outcome — the canonical failure signal that `.done`/`once` read.
-            this.systemEmit("error", error);
-            this.settled.resolve(outcome);
-            this.systemEmit("done", outcome);
-            // The action failed, so its handle will never arrive — reject `ref` with
-            // the same error instead of leaving awaiters hung. No-op if already attached.
-            this.handle.reject(error);
-            // Resolve (never rethrow): failure is the Outcome, not a rejection.
-            return outcome;
-        });
-    }
-    on(key, handler) {
-        this.emitter.listen(key, handler);
-    }
-    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 (which
-        // resolves `undefined` if the action settles before the event).
-        return (key === "done" ? this.settled.promise : ActionRun.awaitEvent(this.emitter, key));
-    }
-    withCache(...paths) {
-        // Validate + canonicalize eagerly here (at the call site), not lazily inside the
-        // run — a relative path fails fast where it's written, and the resolved paths
-        // give a stable cache key regardless of spelling.
-        const targets = FolderCache.resolvePaths(paths);
-        const { name } = this;
-        // Wrap this instance in a fresh one (reusing the engine for its own
-        // emitter/ref/on/once) that fingerprints `paths` and either skips or
-        // runs+records. The wrapper keeps this action's `name`, so log lines and the
-        // `launch <name>` line are unchanged; it forwards its injected logs/signal
-        // straight into this inner instance's `start`.
-        return action(name).run(async (ctx) => {
-            const fp = await FolderCache.fingerprint(targets);
-            if ((await FolderCache.read(targets)) === fp) {
-                ctx.logs.append({ source: name, level: "info", message: "cached, skipping" });
-                return undefined;
-            }
-            const outcome = await this.start({
-                logs: ctx.logs,
-                signal: ctx.signal,
-                nod: ctx.nod,
-                output: ctx.output,
-                assert: ctx.assert,
-            });
-            // Re-throw the inner failure so the wrapper fails too (the framework re-wraps
-            // it into this wrapper's own Outcome); only record on success.
-            if (!outcome.ok)
-                throw outcome.error;
-            await FolderCache.write(targets, fp);
-            return outcome.value;
-        })();
-    }
-    /** One-time lifecycle moment: resolve `ref` and emit `attached`. Guarded (second attach no-ops). */
-    attach(value) {
-        if (this.attached)
-            return;
-        this.attached = true;
-        this.handle.resolve(value);
-        this.systemEmit("attached");
-    }
-    /** The framework's own emits (loosely typed — sidesteps EmitArgs for void results). */
-    systemEmit(key, payload) {
-        this.emitter.emit(key, payload);
-    }
-    static defer() {
-        let resolve;
-        let reject;
-        const promise = new Promise((res, rej) => {
-            resolve = res;
-            reject = rej;
-        });
-        return { promise, resolve, reject };
-    }
-    /** Duck-type an exit code off a thrown error (zx's ProcessOutput, command's exit error). */
-    static exitCodeOf(error) {
-        const code = error?.exitCode;
-        return typeof code === "number" ? code : undefined;
-    }
-    /**
-     * Log one emit onto the run timeline, through the action's scoped `logs` so the
-     * line carries its path. Fields are `·`-delimited — action name · key · payload.
-     * A string payload rides inline; a richer one is written to a snapshot file and
-     * linked (`→ <rel>`) so the durable record keeps it without bloating the line.
-     * This is the sole place emits become log lines — the bus itself does no logging.
-     */
-    static logEmit(system, name, key, payload) {
-        const fields = [name, key];
-        if (typeof payload === "string") {
-            fields.push(payload);
-        }
-        else if (payload !== undefined) {
-            fields.push(`→ ${system.output.snapshots.captureJson(`event-${name}-${key}`, payload).rel}`);
-        }
-        system.logs.append({ source: "event", level: "event", message: fields.join(" · ") });
-    }
-    /**
-     * 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. A retained snapshot resolves it
-     * immediately. (Not used for `key === "done"`, which reads the settled Outcome.)
-     */
-    static awaitEvent(emitter, key) {
-        return new Promise((resolve) => {
-            const offs = [];
-            let settled = false;
-            // First of [the event | done] to fire wins; the rest are unsubscribed.
-            const settle = (act) => {
-                if (settled)
-                    return;
-                settled = true;
-                for (const off of offs)
-                    off();
-                act();
-            };
-            // 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))));
-            // `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(() => resolve(undefined))));
-            }
-            // A retained snapshot fires a listen synchronously during registration; if
-            // that already settled us, drop any listeners registered afterwards.
-            if (settled)
-                for (const off of offs)
-                    off();
-        });
-    }
-}
-/**
- * The step between `action(name)` and an {@link Action}: declare typed events
- * and/or an imperative handle (phantom type transitions — each returns a builder
- * carrying the same `name`), then `run(exec)` to bind the implementation.
- */
-class Builder {
-    name;
-    constructor(name) {
-        this.name = name;
-    }
-    emits() {
-        return new Builder(this.name);
-    }
-    ref() {
-        return new Builder(this.name);
-    }
-    run(exec) {
-        const { name } = this;
-        // Invoking the returned callable constructs a fresh instance (deferred — the run
-        // executes it). Each call is its own {@link ActionRun}.
-        const create = (...args) => new ActionRun(name, exec, args);
-        return Object.assign(create, { actionName: name });
-    }
-}
-/**
- * Defines an action. Always returns a builder; provide the implementation via
- * `.run(…)`, optionally after declaring events and/or a handle:
- *
- *   action("Build").run(async (ctx, opts) => { … })       // no declared events / handle
- *   action("Watch")                                       // typed events + handle
- *     .emits<{ create: string }>()
- *     .ref<{ rescan(): void }>()
- *     .run((ctx, opts) => { ctx.emit(…); ctx.attach(…); … })
- *
- * `.run(…)` yields a callable that, when invoked, constructs an
- * {@link ActionInstance} (deferred — the run executes it). Instances expose
- * chainable `.on` / `.once` (declared events plus `done`/`error`); the attached
- * handle is awaited via `instance.ref`.
- */
-export function action(name) {
-    return new Builder(name);
-}