omkit 0.1.4 → 0.1.6

package/dist/actions/command.d.ts

@@ -1,5 +1,10 @@
 /** Tunes an action built with {@link command}. */
 export interface CommandOptions {
+    /**
+     * Launch `cmdOrFile` directly with these arguments instead of executing it
+     * through a shell. Omit to run the command as a shell command.
+     */
+    args?: readonly string[];
     /** Directory to run in; relative paths resolve against `process.cwd()`. Default ".". */
     cwd?: string;
     /** Full environment for the child (handed as-is, not merged). Omit to inherit. */
@@ -8,9 +13,11 @@ export interface CommandOptions {
     inheritDebugger?: boolean;
 }
 /**
- * Runs an executable directly (without a shell) as an action instance.
+ * Runs a command as an action instance.
  *
- * Output streams into the run's log under `name`; a non-zero exit fails the
- * action; teardown force-kills the process tree.
+ * By default the command is executed through the shell.
+ *
+ * If `options.args` is provided, `cmdOrFile` is treated as an executable and
+ * launched directly without a shell.
  */
-export declare function command(name: string, file: string, args?: readonly string[], options?: CommandOptions): import("../index.ts").ActionInstance<void, import("../core/types.ts").NoEvents, void>;
+export declare function command(name: string, cmdOrFile: string, options?: CommandOptions): import("../index.ts").ActionInstance<import("zx").ProcessOutput, import("../core/types.ts").NoEvents, void> | import("../index.ts").ActionInstance<void, import("../core/types.ts").NoEvents, void>;

package/dist/actions/command.js

@@ -1,43 +1,72 @@
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { action } from "../core/action.js";
-import { killTree, streamLines } from "../system/proc.js";
+import { debuggerFreeEnv, killTree, streamLines } from "../system/proc.js";
 /**
- * Runs an executable directly (without a shell) as an action instance.
+ * Build a zx tagged template that runs `cmd` verbatim.
+ */
+const verbatim = (cmd) => Object.assign([cmd], { raw: [cmd] });
+/**
+ * Runs a command as an action instance.
  *
- * Output streams into the run's log under `name`; a non-zero exit fails the
- * action; teardown force-kills the process tree.
+ * By default the command is executed through the shell.
+ *
+ * If `options.args` is provided, `cmdOrFile` is treated as an executable and
+ * launched directly without a shell.
  */
-export function command(name, file, args = [], options = {}) {
+export function command(name, cmdOrFile, options = {}) {
+    const cwd = path.resolve(options.cwd ?? ".");
+    // Shell command.
+    if (options.args === undefined) {
+        return action(name).run((ctx) => ctx.proc(name, {
+            cwd,
+            ...(options.env && { env: options.env }),
+            ...(options.inheritDebugger && {
+                inheritDebugger: true,
+            }),
+        })(verbatim(cmdOrFile)))();
+    }
+    // Direct executable.
     return action(name).run(async (ctx) => {
-        const cwd = path.resolve(options.cwd ?? ".");
-        const child = spawn(file, args, {
+        const inherit = options.inheritDebugger ?? Boolean(process.env.OMKIT_INHERIT_DEBUGGER);
+        const env = inherit
+            ? (options.env ?? process.env)
+            : debuggerFreeEnv(options.env ?? process.env);
+        const args = options.args ?? [];
+        const child = spawn(cmdOrFile, args, {
             cwd,
-            env: options.env,
+            env,
             detached: process.platform !== "win32",
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
         });
-        console.log(`start · '${file}' ${args.join(" ")} · in ${cwd}`);
-        void streamLines(child.stdout, (line) => console.info(line));
-        void streamLines(child.stderr, (line) => console.error(line));
+        console.log(`${name} · start · '${cmdOrFile}' ${args.join(" ")} · in ${cwd}`);
+        void streamLines(child.stdout, console.info);
+        void streamLines(child.stderr, console.error);
         let finished = false;
         const onAbort = () => {
             if (!finished && child.pid !== undefined) {
                 killTree(child.pid);
             }
         };
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        if (ctx.signal.aborted) {
+            onAbort();
+        }
+        else {
+            ctx.signal.addEventListener("abort", onAbort, { once: true });
+        }
         try {
             await new Promise((resolve, reject) => {
-                child.once("error", reject);
+                child.once("error", (err) => {
+                    reject(new Error(`${name}: ${err.message}`, { cause: err }));
+                });
                 child.once("exit", (code, signal) => {
                     finished = true;
-                    if (code === 0) {
+                    if (ctx.signal.aborted || code === 0) {
                         resolve();
                     }
                     else {
-                        reject(new Error(signal ? `${name} terminated by ${signal}` : `${name} exited with code ${code}`));
+                        reject(Object.assign(new Error(signal ? `${name} terminated by ${signal}` : `${name} exited with code ${code}`), { exitCode: code ?? undefined }));
                     }
                 });
             });

package/dist/core/ActionRun.d.ts

@@ -7,6 +7,8 @@ import type { Exec, InstanceEvents, NodeStatus, Outcome, RunHandle } from "./typ
 export interface NodeInit {
     readonly store: LogStore;
     readonly name: string;
+    /** `file:line` where the action was defined (the `.run(...)` site) — for the log header. */
+    readonly definedAt: string | undefined;
     readonly uuid: string;
     /** `${name}_${shortId}`, or `main` for the root. */
     readonly id: string;
@@ -36,6 +38,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     readonly id: string;
     readonly uuid: string;
     readonly name: string;
+    readonly definedAt: string | undefined;
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: string[];
@@ -62,6 +65,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private attached;
     private observed;
     private refObserved;
+    private cancelLogged;
     private cascadeCancelled;
     constructor(init: NodeInit);
     /** A stable reference for headers/attribution (tags are the accumulated set now). */
@@ -76,6 +80,13 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     tag(name: string): this;
     handleFailure(handler: (error: unknown) => void): this;
     cancel(): void;
+    /**
+     * Log a cancellation milestone on this node (once) and bubble it to the parent, so a
+     * cancellation is visible per-action and up the tree into `main`. Only while the node is
+     * still running — a node that already settled isn't "cancelled" by a later teardown — and
+     * never for the root, whose cancellation is the run-level `tearing down · …` narration.
+     */
+    private noteCancelled;
     /** Run the body inside the error boundary, settling the node. Never rejects. */
     run(exec: Exec<Events, Handle, Result>, args: readonly unknown[]): Promise<void>;
     private context;

package/dist/core/ActionRun.js

@@ -13,6 +13,7 @@ export class ActionRun {
     id;
     uuid;
     name;
+    definedAt;
     path;
     parentId;
     tags = [];
@@ -39,6 +40,7 @@ export class ActionRun {
     attached = false;
     observed = false;
     refObserved = false;
+    cancelLogged = false;
     // Set only by the parent-signal abort listener (an ANCESTOR cancelling this node).
     // Distinguishes a run/ancestor teardown from this node's own subtree-abort on failure,
     // so the unobserved-failure check below isn't fooled by our own controller.abort().
@@ -47,6 +49,7 @@ export class ActionRun {
         this.id = init.id;
         this.uuid = init.uuid;
         this.name = init.name;
+        this.definedAt = init.definedAt;
         this.path = init.path;
         this.parentId = init.parentId;
         this.store = init.store;
@@ -60,6 +63,7 @@ export class ActionRun {
         const parent = init.parentSignal;
         const onAncestorAbort = () => {
             this.cascadeCancelled = true;
+            this.noteCancelled(); // this node is being cancelled by an ancestor's teardown
             this.controller.abort();
         };
         if (parent) {
@@ -135,8 +139,22 @@ export class ActionRun {
         return this;
     }
     cancel() {
+        this.noteCancelled(); // a direct cancel of this activity
         this.controller.abort();
     }
+    /**
+     * Log a cancellation milestone on this node (once) and bubble it to the parent, so a
+     * cancellation is visible per-action and up the tree into `main`. Only while the node is
+     * still running — a node that already settled isn't "cancelled" by a later teardown — and
+     * never for the root, whose cancellation is the run-level `tearing down · …` narration.
+     */
+    noteCancelled() {
+        if (this.cancelLogged || this.parentId === null || this.status !== "running")
+            return;
+        this.cancelLogged = true;
+        this.log("event", "cancel", "cancelled");
+        this.bubble("⊘ cancelled");
+    }
     // ── Execution ──────────────────────────────────────────────────────────────
     /** Run the body inside the error boundary, settling the node. Never rejects. */
     async run(exec, args) {

package/dist/core/ExecutionTree.d.ts

@@ -39,7 +39,7 @@ export declare class ExecutionTree {
     private readonly onSigint;
     private readonly onUncaught;
     private readonly onUnhandled;
-    constructor();
+    constructor(definedAt?: string);
     /** Launch an instance under the ambient current node (or the root). */
     launch(spec: LaunchSpec): ActionRun;
     private append;

package/dist/core/ExecutionTree.js

@@ -62,11 +62,12 @@ export class ExecutionTree {
     // Process hooks — installed at run start, removed at finalize (they must not outlive the run).
     onUncaught = (e) => this.onFatal("uncaughtException", e);
     onUnhandled = (e) => this.onFatal("unhandledRejection", e);
-    constructor() {
+    constructor(definedAt) {
         this.folder.ensure();
         this.root = new ActionRun({
             ...this.nodeDeps(),
             name: "main",
+            definedAt, // where om() was called — the run's script
             uuid: newUuid(),
             id: "main",
             path: "main",
@@ -91,6 +92,7 @@ export class ExecutionTree {
         const node = new ActionRun({
             ...this.nodeDeps(),
             name: spec.name,
+            definedAt: spec.definedAt,
             uuid,
             id,
             path: nodePath,
@@ -102,8 +104,10 @@ export class ExecutionTree {
         });
         parent.children.push(node);
         this.registry.push(node);
-        // Launch reference — the parent's pointer to the child's own (absolute) log.
-        this.append(parent, "child", "launch", `→ ${id} · ${this.logFile(nodePath)}`);
+        // Launch reference — the parent's pointer to the child's own (absolute) log, plus where
+        // the action is defined, so `main` (and any parent) shows each child's script.
+        const defined = spec.definedAt ? ` · defined ${spec.definedAt}` : "";
+        this.append(parent, "child", "launch", `→ ${id} · ${this.logFile(nodePath)}${defined}`);
         for (const t of spec.tags)
             node.tag(t);
         const promise = currentNode.run(node, () => node.run(spec.body, spec.args));
@@ -185,8 +189,9 @@ export class ExecutionTree {
         process.on("uncaughtException", this.onUncaught);
         process.on("unhandledRejection", this.onUnhandled);
         this.streaming = this.rawStream.run(this.store);
-        // Live, curated milestones to the terminal, through the pre-patch writer.
-        this.liveRendering = new LiveRenderer(this.originalLog).run(this.store);
+        // Live, curated milestones to the terminal — a single in-place status line on a TTY.
+        // Straight to process.stdout, which patch-console doesn't intercept (no capture feedback).
+        this.liveRendering = new LiveRenderer(process.stdout).run(this.store);
         const rootPromise = currentNode.run(this.root, () => this.root.run(body, []));
         this.trackNode(rootPromise);
         await rootPromise;
@@ -272,6 +277,7 @@ export class ExecutionTree {
             id: node.id,
             uuid: node.uuid,
             name: node.name,
+            definedAt: node.definedAt,
             path: node.path,
             parentId: node.parentId,
             tags: [...node.tags],

package/dist/core/action.js

@@ -1,5 +1,6 @@
 import { ExecutionTree } from "./ExecutionTree.js";
 import { FolderCache } from "../system/fs/FolderCache.js";
+import { callerSite } from "../foundation/callsite.js";
 /**
  * A constructed-but-not-yet-run action. Inert: it only holds the name, body, args,
  * and any tags buffered before launch. `exec()` hands it to the tree, which creates
@@ -9,11 +10,13 @@ class Instance {
     name;
     body;
     args;
+    definedAt;
     tags = [];
-    constructor(name, body, args) {
+    constructor(name, body, args, definedAt) {
         this.name = name;
         this.body = body;
         this.args = args;
+        this.definedAt = definedAt;
     }
     tag(name) {
         this.tags.push(name);
@@ -37,7 +40,7 @@ class Instance {
             await FolderCache.write(targets, fp);
             return result;
         });
-        const cached = new Instance(this.name, body, innerArgs);
+        const cached = new Instance(this.name, body, innerArgs, this.definedAt);
         cached.tags.push(...this.tags);
         return cached;
     }
@@ -59,8 +62,9 @@ class Builder {
     }
     run(body) {
         const name = this.name;
-        const create = (...args) => new Instance(name, body, args);
-        return Object.assign(create, { actionName: name });
+        const definedAt = callerSite(); // the `.run(...)` call site — where this action lives
+        const create = (...args) => new Instance(name, body, args, definedAt);
+        return Object.assign(create, { actionName: name, definedAt });
     }
 }
 /**

package/dist/core/om.js

@@ -1,4 +1,5 @@
 import { ExecutionTree } from "./ExecutionTree.js";
+import { callerSite } from "../foundation/callsite.js";
 /**
  * Runs a linear orchestration as the root of a fresh {@link ExecutionTree}. The
  * body runs inside the root node's ambient scope, so any `instance.exec()` /
@@ -10,7 +11,7 @@ export function om(body) {
     if (ExecutionTree.current) {
         throw new Error("an om() run is already active in this process");
     }
-    const tree = new ExecutionTree();
+    const tree = new ExecutionTree(callerSite()); // where om() was called — the run's script
     ExecutionTree.current = tree;
     const rootBody = (ctx) => body({
         signal: ctx.signal,

package/dist/core/types.d.ts

@@ -110,6 +110,8 @@ export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
 export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
     (...args: Args): ActionInstance<Result, Events, Handle>;
     readonly actionName: string;
+    /** `file:line` where this action was defined (the `.run(...)` site), for the log header. */
+    readonly definedAt: string | undefined;
 }
 /** Intermediate step from `action(name)`: declare events/handle, then provide the impl. */
 export interface ActionBuilderEvents<Events extends object, Handle = void> {
@@ -125,4 +127,6 @@ export interface LaunchSpec {
     readonly args: readonly unknown[];
     readonly tags: readonly string[];
     readonly body: Exec<object, unknown, unknown>;
+    /** `file:line` where the action was defined; carried onto the node for its log header. */
+    readonly definedAt: string | undefined;
 }

package/dist/foundation/ActionRef.d.ts

@@ -16,3 +16,12 @@ export interface ActionRef {
 }
 /** Render an {@link ActionRef} for a header/reference line: `name · path · [a, b]`. */
 export declare const renderRef: (ref: ActionRef) => string;
+/**
+ * A compact inline label — the action **name with its tags**, `name [a, b]` — used
+ * wherever an action is referenced within a timeline line (a bubbled child milestone,
+ * a live status line) so its tags are always visible right next to the name.
+ */
+export declare const label: (ref: {
+    readonly name: string;
+    readonly tags: readonly string[];
+}) => string;

package/dist/foundation/ActionRef.js

@@ -3,3 +3,9 @@ export const renderRef = (ref) => {
     const tags = ref.tags.length ? ` · [${ref.tags.join(", ")}]` : "";
     return `${ref.name} · ${ref.path}${tags}`;
 };
+/**
+ * A compact inline label — the action **name with its tags**, `name [a, b]` — used
+ * wherever an action is referenced within a timeline line (a bubbled child milestone,
+ * a live status line) so its tags are always visible right next to the name.
+ */
+export const label = (ref) => ref.tags.length ? `${ref.name} [${ref.tags.join(", ")}]` : ref.name;

package/dist/foundation/callsite.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `file:line` of the site that *called* the function invoking `callerSite` — the first stack
+ * frame outside both this module and that caller's module. So `action().run(...)` records
+ * where `.run(...)` was written, and `om(...)` records where the run was launched from. At
+ * runtime that's the built file (e.g. `dist/actions/chrome-page.js`). `undefined` with no stack.
+ */
+export declare const callerSite: () => string | undefined;

package/dist/foundation/callsite.js

@@ -0,0 +1,38 @@
+import { fileURLToPath } from "node:url";
+/** `{ file, line }` from a V8 stack frame — handles `at fn (path:line:col)` and `at path:line:col`. */
+const parseFrame = (frame) => {
+    const paren = frame.match(/\(([^()]+)\)\s*$/);
+    const loc = (paren ? paren[1] : frame.replace(/^\s*at\s+/, "")).trim();
+    const m = loc.match(/^(.+):(\d+):\d+$/) ?? loc.match(/^(.+):(\d+)$/);
+    return m ? { file: m[1], line: m[2] } : undefined;
+};
+const nativePath = (file) => {
+    if (!file.startsWith("file://"))
+        return file;
+    try {
+        return fileURLToPath(file);
+    }
+    catch {
+        return file;
+    }
+};
+/**
+ * `file:line` of the site that *called* the function invoking `callerSite` — the first stack
+ * frame outside both this module and that caller's module. So `action().run(...)` records
+ * where `.run(...)` was written, and `om(...)` records where the run was launched from. At
+ * runtime that's the built file (e.g. `dist/actions/chrome-page.js`). `undefined` with no stack.
+ */
+export const callerSite = () => {
+    const stack = new Error().stack;
+    if (!stack)
+        return undefined;
+    const frames = stack.split("\n").slice(1);
+    const self = parseFrame(frames[0] ?? "")?.file; // this module (callsite)
+    const caller = parseFrame(frames[1] ?? "")?.file; // the module that called us
+    for (const frame of frames) {
+        const at = parseFrame(frame);
+        if (at && at.file !== self && at.file !== caller)
+            return `${nativePath(at.file)}:${at.line}`;
+    }
+    return undefined;
+};

package/dist/output/LiveRenderer.d.ts

@@ -1,13 +1,29 @@
 import type { LogStore } from "./log/LogStore.ts";
+/** The terminal surface the renderer writes to (process.stdout satisfies it). */
+export interface LiveTerminal {
+    write(text: string): unknown;
+    readonly isTTY?: boolean;
+    readonly columns?: number;
+}
 /**
- * Renders a **curated** stream of milestones to the terminal, live — action
- * launches, completions, and errors, plus events, asserts, and snapshots. The bulk
- * output (console lines, proc stdout/stderr) is intentionally *not* shown live; it
- * lives in the per-action `.log` files. Writes through the pre-patch terminal
- * writer (so it can't feed back into console capture).
+ * Renders a **curated** stream of milestones to the terminal, live — action launches,
+ * completions, and errors, plus events, asserts, and snapshots. The bulk output (console
+ * lines, proc stdout/stderr) is intentionally *not* shown live; it lives in the per-action
+ * `.log` files.
+ *
+ * On a TTY it keeps a **single status line**, rewriting it in place as milestones arrive,
+ * so the terminal stays quiet — except lines worth keeping (errors, failures, run
+ * milestones), which are *committed* (printed with a newline) so they persist above the
+ * live line. Piped/redirected output (no TTY) falls back to appending every line, so logs
+ * stay readable. Writes through `process.stdout` directly, which `patch-console` doesn't
+ * intercept, so it can't feed back into console capture.
  */
 export declare class LiveRenderer {
-    private readonly write;
-    constructor(write: (line: string) => void);
+    private readonly term;
+    /** True while a transient status line is on screen (needs clearing or a closing newline). */
+    private pending;
+    /** Tags accumulated per node from `tag` entries, so milestones can show them by the name. */
+    private readonly tagsByNode;
+    constructor(term: LiveTerminal);
     run(store: LogStore): Promise<void>;
 }

package/dist/output/LiveRenderer.js

@@ -1,56 +1,101 @@
+/** Return to column 0 and clear the whole line — the in-place status-line reset. */
+const CLEAR = "\r\x1b[2K";
 /**
- * Renders a **curated** stream of milestones to the terminal, live — action
- * launches, completions, and errors, plus events, asserts, and snapshots. The bulk
- * output (console lines, proc stdout/stderr) is intentionally *not* shown live; it
- * lives in the per-action `.log` files. Writes through the pre-patch terminal
- * writer (so it can't feed back into console capture).
+ * Renders a **curated** stream of milestones to the terminal, live — action launches,
+ * completions, and errors, plus events, asserts, and snapshots. The bulk output (console
+ * lines, proc stdout/stderr) is intentionally *not* shown live; it lives in the per-action
+ * `.log` files.
+ *
+ * On a TTY it keeps a **single status line**, rewriting it in place as milestones arrive,
+ * so the terminal stays quiet — except lines worth keeping (errors, failures, run
+ * milestones), which are *committed* (printed with a newline) so they persist above the
+ * live line. Piped/redirected output (no TTY) falls back to appending every line, so logs
+ * stay readable. Writes through `process.stdout` directly, which `patch-console` doesn't
+ * intercept, so it can't feed back into console capture.
  */
 export class LiveRenderer {
-    write;
-    constructor(write) {
-        this.write = write;
+    term;
+    /** True while a transient status line is on screen (needs clearing or a closing newline). */
+    pending = false;
+    /** Tags accumulated per node from `tag` entries, so milestones can show them by the name. */
+    tagsByNode = new Map();
+    constructor(term) {
+        this.term = term;
     }
     async run(store) {
+        const tty = Boolean(this.term.isTTY);
         for await (const entry of store.subscribe({ replay: true })) {
-            const line = format(entry);
-            if (line !== null)
-                this.write(line);
+            if (entry.level === "tag" && entry.source === "tag") {
+                const list = this.tagsByNode.get(entry.nodeId) ?? [];
+                list.push(entry.message);
+                this.tagsByNode.set(entry.nodeId, list);
+                continue; // tags aren't their own line — they decorate the node's milestones
+            }
+            const rendered = format(entry, this.tagsByNode.get(entry.nodeId));
+            if (rendered === null)
+                continue;
+            if (!tty) {
+                this.term.write(`${rendered.text}\n`); // no TTY: append, one line each
+                continue;
+            }
+            if (rendered.persist) {
+                // Commit a line that must survive: finish the transient line, then print permanently.
+                this.term.write(`${this.pending ? CLEAR : ""}${rendered.text}\n`);
+                this.pending = false;
+            }
+            else {
+                // Transient: overwrite the current status line in place, truncated to fit.
+                this.term.write(`${CLEAR}${truncate(rendered.text, this.term.columns)}`);
+                this.pending = true;
+            }
+        }
+        // Keep the last status line on screen for the summary that follows.
+        if (this.pending) {
+            this.term.write("\n");
+            this.pending = false;
         }
     }
 }
 const firstLine = (message) => message.split("\n", 1)[0] ?? message;
 /** ✓ ok · ⊘ cancelled (a clean stop) · ✗ failed. */
 const doneIcon = (status) => status === "ok" ? "✓" : status === "cancelled" ? "⊘" : "✗";
-/** Map a curated entry to a terminal line, or `null` to drop it from the live view. */
-const format = (e) => {
+/** Truncate to the terminal width so an in-place line never wraps and breaks the `\r`. */
+const truncate = (text, columns) => !columns || text.length < columns ? text : `${text.slice(0, Math.max(0, columns - 1))}…`;
+/** The node's path with its accumulated tags appended: `main/probe_9f3c [ready, gate]`. */
+const named = (path, tags) => tags && tags.length ? `${path} [${tags.join(", ")}]` : path;
+/** Map a curated entry to a terminal line (and whether it persists), or `null` to drop it. */
+const format = (e, tags) => {
     // Action launch — bubbled onto the parent as `→ <childId> · <log>`.
     if (e.level === "child" && e.source === "launch") {
         const child = e.message.replace(/^→\s*/, "").split(" · ")[0];
-        return `▶ ${e.path}/${child}`;
+        return { text: `▶ ${e.path}/${child}`, persist: false };
     }
-    // Lifecycle events: `launched` is already shown via the launch pointer above, so
-    // drop the duplicate; `done · <status>` renders with the status icon.
+    // Lifecycle events: `launched` is already shown via the launch pointer above, so drop
+    // the duplicate; `done · <status>` renders with the status icon — a failure persists.
     if (e.level === "event" && e.source === "lifecycle") {
         if (e.message === "launched")
             return null;
         const status = e.message.replace(/^done · /, "");
-        return `${doneIcon(status)} ${e.path} · ${status}`;
+        return { text: `${doneIcon(status)} ${named(e.path, tags)} · ${status}`, persist: status === "failed" };
     }
-    // Run milestones (started / tearing down / finished).
+    // Run milestones (started / tearing down / finished) — few, and worth keeping.
     if (e.level === "run")
-        return `· ${e.message}`;
-    // An action's *own* failure — not proc stderr (source = proc name), console.error,
-    // or a teardown cancellation (which is a clean stop, not an error).
+        return { text: `· ${e.message}`, persist: true };
+    // An action's *own* failure — not proc stderr, console.error, or a teardown cancellation.
     if (e.level === "error" && e.source === "error") {
-        return `✗ ${e.path} · ${firstLine(e.message)}`;
+        return { text: `✗ ${named(e.path, tags)} · ${firstLine(e.message)}`, persist: true };
     }
+    // A cancellation milestone (⊘) — persist it so it doesn't flash away during teardown.
+    if (e.level === "event" && e.source === "cancel")
+        return { text: `⊘ ${named(e.path, tags)} · ${e.message}`, persist: true };
     // User-emitted events.
     if (e.level === "event")
-        return `⚡ ${e.path} · ${e.message}`;
+        return { text: `⚡ ${named(e.path, tags)} · ${e.message}`, persist: false };
+    // Asserts: a failed one (⊭) persists, a pass is transient.
     if (e.level === "assert")
-        return `  ${e.path} · ${e.message}`;
+        return { text: `  ${named(e.path, tags)} · ${e.message}`, persist: e.message.includes("⊭") };
     if (e.level === "snapshot")
-        return `📸 ${e.path} · ${e.message}`;
+        return { text: `📸 ${named(e.path, tags)} · ${e.message}`, persist: false };
     // Everything else (info / console / proc output / tag / bubbled child events) → files only.
     return null;
 };

package/dist/output/writers/NodeLogWriter.js

@@ -9,22 +9,25 @@ import { entryLine, groupByNode } from "./entryLine.js";
  */
 export async function writeNodeLogs(nodes, entries) {
     const byNode = groupByNode(entries, () => true);
+    const refByNode = new Map(nodes.map((n) => [n.id, n]));
+    const refOf = (id) => refByNode.get(id);
     await Promise.all(nodes.map(async (node) => {
-        const lines = (byNode.get(node.id) ?? []).map(entryLine);
+        const lines = (byNode.get(node.id) ?? []).map((e) => entryLine(e, refOf));
         const body = [...header(node), "", ...lines, ""].join("\n");
         await mkdir(path.dirname(node.logFile), { recursive: true });
         await writeFile(node.logFile, body, "utf8");
     }));
 }
-/** The per-file metadata header: ref, args, start/finish times, duration, status. */
+/** The per-file metadata header: ref, defining script, args, start/finish times, status. */
 const header = (node) => [
     `# ${renderRef(node)}`,
     `#   log:      ${node.logFile}`,
+    node.definedAt ? `#   defined:  ${node.definedAt}` : null,
     `#   args:     ${renderArgs(node.args)}`,
     `#   started:  ${stamp(node.startedAt)}`,
     `#   finished: ${stamp(node.endedAt)} (${node.duration}ms)`,
     `#   status:   ${node.status}`,
-];
+].filter((line) => line !== null);
 const stamp = (ms) => (ms ? new Date(ms).toISOString() : "-");
 const renderArgs = (args) => {
     try {

package/dist/output/writers/RollupWriter.js

@@ -9,6 +9,7 @@ import { entryLine } from "./entryLine.js";
  */
 export async function writeRollup(file, nodes, entries, match, footer) {
     const refByNode = new Map(nodes.map((n) => [n.id, n]));
+    const refOf = (id) => refByNode.get(id);
     const chunks = [];
     let lastNode = null;
     for (const e of entries) {
@@ -21,7 +22,7 @@ export async function writeRollup(file, nodes, entries, match, footer) {
             chunks.push(`# ${ref ? renderRef(ref) : e.path}`);
             lastNode = e.nodeId;
         }
-        chunks.push(entryLine(e));
+        chunks.push(entryLine(e, refOf));
     }
     if (footer)
         chunks.push("", footer);

package/dist/output/writers/entryLine.d.ts

@@ -1,10 +1,14 @@
+import { type ActionRef } from "../../foundation/ActionRef.ts";
 import type { LogEntry } from "../../foundation/LogEntry.ts";
+/** Resolve a node's reference (name + tags) by id, for naming a bubbled child. */
+export type RefOf = (nodeId: string) => ActionRef | undefined;
 /**
  * The shared human-readable row: `[<seq>] <body>`. Only the run-global sequence
  * prefixes the line (date/path live in the file header + `raw.jsonl`). Event,
- * snapshot, and assert lines carry a leading icon; everything else keeps its
- * `source` (proc name, child id, `console`, …).
+ * snapshot, and assert lines carry a leading icon; a **bubbled child milestone** names
+ * the child by its {@link label} (name + tags) via `refOf`; everything else keeps its
+ * `source` (proc name, `console`, …).
  */
-export declare const entryLine: (e: LogEntry) => string;
+export declare const entryLine: (e: LogEntry, refOf?: RefOf) => string;
 /** Group entries by `nodeId` (preserving order), keeping only those that `match`. */
 export declare const groupByNode: (entries: readonly LogEntry[], match: (e: LogEntry) => boolean) => Map<string, LogEntry[]>;

package/dist/output/writers/entryLine.js

@@ -1,14 +1,17 @@
+import { label } from "../../foundation/ActionRef.js";
 /**
  * The shared human-readable row: `[<seq>] <body>`. Only the run-global sequence
  * prefixes the line (date/path live in the file header + `raw.jsonl`). Event,
- * snapshot, and assert lines carry a leading icon; everything else keeps its
- * `source` (proc name, child id, `console`, …).
+ * snapshot, and assert lines carry a leading icon; a **bubbled child milestone** names
+ * the child by its {@link label} (name + tags) via `refOf`; everything else keeps its
+ * `source` (proc name, `console`, …).
  */
-export const entryLine = (e) => `[${e.sequence}] ${bodyOf(e)}`;
-const bodyOf = (e) => {
+export const entryLine = (e, refOf) => `[${e.sequence}] ${bodyOf(e, refOf)}`;
+const bodyOf = (e, refOf) => {
     switch (e.level) {
         case "event":
-            return `⚡ ${e.message}`;
+            // A cancellation milestone reads ⊘; other emitted events keep ⚡.
+            return e.source === "cancel" ? `⊘ ${e.message}` : `⚡ ${e.message}`;
         case "snapshot":
             return `📸 ${e.message}`;
         case "assert":
@@ -20,7 +23,16 @@ const bodyOf = (e) => {
             // An action's *own* failure keeps a ✗; proc stderr / console.error is plain
             // output. (Cancellation no longer logs at this level — it's a clean stop.)
             return e.source === "error" ? `✗ ${e.message}` : `▪ ${e.message}`;
-        // run/done milestones, tags, and bubbled child lines keep their `source` label.
+        case "child": {
+            // A bubbled child milestone carries the child's id as `source`: name it with its
+            // tags (`name [tags]`) so the parent timeline always shows them. The launch
+            // pointer (`source === "launch"`) keeps its `→ id · logfile` message as-is.
+            if (e.source === "launch")
+                return `${e.source} · ${e.message}`;
+            const ref = refOf?.(e.source);
+            return `${ref ? label(ref) : e.source} · ${e.message}`;
+        }
+        // run/done milestones, tags, … keep their `source` label.
         default:
             return `${e.source} · ${e.message}`;
     }

package/dist/output/writers/views.d.ts

@@ -7,6 +7,8 @@ export interface NodeView {
     readonly id: string;
     readonly uuid: string;
     readonly name: string;
+    /** `file:line` where the action was defined (the `.run(...)` site); absent for the root. */
+    readonly definedAt?: string;
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: readonly string[];

package/package.json

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