omkit 0.1.5 → 0.1.7

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,21 +9,35 @@ 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}`,
+    ...(node.parentId === null ? legend : []), // the run's root log (main.log) only
+].filter((line) => line !== null);
+/** A compact reading guide, printed once on the root log so an agent can follow the run. */
+const legend = [
+    "#",
+    "# ── legend ──────────────────────────────────────────────────────────",
+    "#   [n]              global sequence — the merge/order key across every .log",
+    "#   indented rows    a child action's milestones, bubbled up here",
+    "#   name [tags]      the action and its tags   ·   defined …  where its code lives",
+    "#   launch · → ….log a child started — open that file for its full output",
+    "#   ⚡ event   ✓ done ok   ⊘ cancelled   ✗ failed   ⊨/⊭ assert pass/fail   📸 snapshot   ▪ output",
 ];
 const stamp = (ms) => (ms ? new Date(ms).toISOString() : "-");
 const renderArgs = (args) => {

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,21 @@
+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) => {
+    // Bubbled child rows are nested a level in — the whole row, `[seq]` included.
+    const indent = e.level === "child" ? "    " : "";
+    return `${indent}[${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 +27,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 line (indented at the row level by `entryLine`). The launch pointer
+            // (`source === "launch"`) keeps its `→ id · logfile` message; a milestone names the
+            // child by its label (name + tags) via `refOf`.
+            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.5",
+  "version": "0.1.7",
   "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",