omkit 0.1.8 → 0.2.1

package/README.md

@@ -1,124 +1,195 @@
 # omkit
 
-**The operational-model kit.** _Typed actions. One run. One log._
+**The operational-model kit.** _Humans orchestrate. Runs narrate. AI assistants follow along._
 
-A tiny runtime for the workflows _around_ your code — build, watch, spawn, probe, drive a browser, read state back, and tear it all down together. Where [tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer, `omkit` is the _operational_ one: the running, typed model of your system in motion.
+A tiny runtime for the workflows _around_ your code — start servers, wait for health checks, build, watch, drive a browser, read state back, and tear it all down together. You write the orchestration as ordinary TypeScript; the run **narrates itself** into a structured, on-disk record — what launched, what came up, what attached, what failed, what the world actually looked like — that an AI assistant can read instead of guessing from terminal scrollback. Where [tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer (what your system **is**), `omkit` is the _operational_ one (what it's **doing right now**).
 
 ## The problem
 
-Real developer workflows aren't linear. They start processes, wait for health checks, connect a browser, read state back, watch files, react to events — and shut everything down as one. Most teams glue this together with shell scripts, npm scripts, and ad-hoc Node, and get back a pile of opaque process output.
+You know the script. Start the API, start the web server, wait until they're _actually_ serving, open the app, maybe run a smoke check — then Ctrl+C and hope everything shut down. Most of us glue this together with `concurrently`, `wait-on`, a shell script, and a pile of opaque interleaved output. When it breaks, you're grepping stdout to find out which process died.
 
-`omkit` models the workflow instead. Each step is a typed **action** running inside one runtime. Actions don't share globals — they hand each other typed runtime **capabilities** (a port, a client, a live browser page) and emit typed **events**, all onto one log. So a running system exposes structured handoffs and observations, which makes it observable, reproducible, and scriptable.
+Now hand that same script to an AI assistant. It has it even worse: interleaved stdout is all it can see, so it _infers_ — "the server probably started", "the build likely passed" — and acts on guesses. The productivity you wanted from the assistant leaks away into re-running things, misreading logs, and asserting success that never happened.
+
+`omkit` models the workflow instead. Each step is a typed **action** in one run. Actions don't share globals — they hand each other typed **capabilities** (a port, a client, a live browser page), emit typed **events**, and land on **one log**. Bring the whole thing down together, and get a structured record of what happened — one a human can skim and an assistant can verify against.
 
 ```ts
 import { om } from "omkit";
 import { command, healthcheck, chromePage } from "omkit/actions";
 
-om(async () => {
-  command("api", "npm run dev:api").exec().tag("api:daemon"); // start a daemon…
+// Define once. `command` names the action after the command; calling it launches.
+const api = command("npm run dev", { cwd: "api" });
+const web = command("npm run dev", { cwd: "web" });
+
+om("dev", async () => {
+  api().tag("api"); // start both dev servers as daemons…
+  web().tag("web");
 
-  const ready = await healthcheck({ port: 3000 }).exec().result; // …gate on it…
-  if (!ready.ok) return;
+  // …wait until the app actually serves (not just "process started")…
+  const up = await healthcheck({ url: "http://localhost:3000" }).result;
+  if (!up.ok) return; // gave up — the servers stay up so you can debug them
 
-  // …then hand the live page downstream — typed, not scraped from a log.
-  const page = chromePage("app", "localhost:9222", { url: "http://localhost:3000" }).exec();
-  await inspect(page.ref); // whatever drives the app receives the live Page
+  // …then open it in a real browser and hand the live page downstream — typed, not scraped.
+  const page = chromePage("app", "localhost:9222", { url: "http://localhost:3000" });
+  console.log(`opened ${(await page.ref).url()}`);
 
-  console.log("up — press Ctrl+C to stop");
+  console.log("stack is up — press Ctrl+C to stop");
 });
 ```
 
-`page.ref` isn't a URL scraped from stdout — it's a typed capability the next step receives and drives. Few workflow tools pass anything but strings between steps.
+`page.ref` isn't a URL scraped from stdout — it's the live Playwright `Page`, typed, that the next step drives directly. Few workflow tools pass anything but strings between steps.
 
 ```
                       om()
                        │
-        ┌──────────────┼──────────────┐
-        ▼              ▼              ▼
-     command       healthcheck    chromePage
-    (daemon)         (gate)          │ .ref
-                                     ▼
-                                 your driver
+      ┌────────────────┼────────────────┐
+      ▼                ▼                 ▼
+   command          healthcheck      chromePage
+  api · web           (gate)           │ .ref  → live Page
+  (daemons)                            ▼
+                                  your smoke test
 ```
 
+## Who it's for
+
+- **Humans orchestrate.** Pipelines are ordinary TypeScript — `await`, `if`, loops, variables — not YAML, not a DSL. Define an action once; launch it by calling it.
+- **AI assistants follow runs.** The run folder (`result.json`, `raw.jsonl`, per-action logs, snapshots) is a machine-readable account of what really happened — an assistant can verify outcomes, cite evidence, and pick up where a run left off.
+- **Together, faster.** You express intent; the run records ground truth; the assistant acts on the record instead of re-running things to guess. Fewer cycles lost to "did that actually work?".
+
 ## Core concepts
 
 ### Actions & Activities
 
-An **Action** is an immutable description of work — named, typed, optionally declaring events and an imperative handle. An **Activity** is a live execution of one, created synchronously by `.exec()`. Everything _before_ `exec()` configures the Action; everything _after_ configures or observes the Activity.
+An **Action** is a named, typed description of work. **Calling it launches** it and returns a live **Activity** — the handle you configure (`withCache`, `tag`) and observe (`result`, `ref`, events).
 
 ```ts
 import { action } from "omkit";
 
-const Build = action("Build").run(({ proc }) => proc("tsc")`tsc -b`);
+const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 
-const activity = Build().exec(); // launch; returns the live Activity
+const activity = build(); // calling launches; returns the live Activity
 ```
 
-`om(async (ctx) => …)` hosts a linear orchestration as the root of a run. You write normal `await` / `if` / loops / variables; the Activities you launch keep running in parallel. Because the body stays in-flight while you `await`, the run never idles shut between steps. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
+`om(name, async (ctx) => …)` hosts the orchestration as the root of a run. The name plus the file it's defined in identify the run — logs land in `logs/<name>-<hash8>/…`, so same-named oms in different files never share a folder. You write ordinary `await` / `if` / loops / variables; the Activities you launch keep running in parallel, and because the body stays in-flight while you `await`, the run never idles shut between steps. Config chained on an Activity before your first `await` (like `withCache`) applies before its body runs. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
 
 ### Typed capabilities
 
-An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor: a typed runtime handoff, so actions chain without globals or string-scraping.
+An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor scraped from a log: a typed runtime handoff, so steps chain without globals or string-parsing.
 
 ```ts
-const Server = action("Server")
-  .ref<number>()
+const server = action("server")
+  .ref<number>() // this action publishes a port
   .run(async ({ attach, signal }) => {
-    attach(await listen()); // publish the capability…
-    await until(signal); // …and stay alive until teardown
+    const port = await listen(); // start listening…
+    attach(port); // …publish the port to downstream actions…
+    await until(signal); // …and stay up until teardown
   });
 
-const Probe = action("Probe").run((_ctx, port: Promise<number>) => drive(port));
+const migrate = action("migrate").run((_ctx, port: Promise<number>) => runMigrations(port));
 
-om(async () => {
-  const server = Server().exec();
-  Probe(server.ref).exec(); // Probe receives Server's port, typed
+om("migrate", async () => {
+  const s = server();
+  migrate(s.ref); // migrate receives the port the moment the server attaches it — typed
 });
 ```
 
 ### Outcomes — a result that doesn't throw
 
-Every Activity settles to a typed **`Outcome`**, read via `activity.result` — which **never throws**:
+Every Activity settles to a typed **`Outcome`**, read via `activity.result`, which **never throws**. Operational failures are values you inspect, not exceptions you catch:
 
 ```ts
 type Outcome<T> = { ok: true; value: T } | { ok: false; error: unknown };
 
-const r = await runTests().exec().result;
-if (!r.ok) {
-  // an expected, operational failure — inspect it and carry on
+const tests = await command("npm test")().result;
+if (!tests.ok) {
+  // red tests are an expected outcome here — decide what to do, don't crash
 }
 ```
 
-Awaiting `.result` also _observes_ the Activity (see teardown, below). A cancelled Activity resolves `{ ok: false, error: CancelledError }`.
+Awaiting `.result` also _observes_ the Activity (see teardown). A cancelled Activity resolves `{ ok: false, error: CancelledError }`.
 
 ### Failure & teardown
 
-omkit uses **structured supervision**: a failure that **nobody is watching** tears the whole run down and marks it failed. An Activity is "watched" if — before it fails — you awaited its `.result` (or `.ref`), attached an `on("error")` listener, or attached `.handleFailure`.
+omkit uses **structured supervision**: a failure that **nobody is watching** tears the whole run down and marks it failed. An Activity is "watched" if — before it fails — you awaited its `.result` (or `.ref`), added an `on("error")` listener, or attached `.handleFailure`.
 
-- **Await it** (`await x.exec().result`) → the failure is yours to inspect as `{ ok: false }`; the run stays green.
-- **Fire-and-forget it** (`x.exec()`, never awaited) → an unobserved failure tears the run down. This is the guardrail for daemons: a crashed daemon fails the run instead of leaving it wedged.
+- **Await it** (`await task().result`) → the failure is yours to inspect as `{ ok: false }`; the run stays green.
+- **Fire-and-forget it** (`task()`, never awaited) → an unobserved crash tears the run down. This is the guardrail for daemons: a dev server that dies fails the run instead of leaving it wedged.
 - **`.handleFailure(fn)`** → own a fire-and-forget Activity's failure: `fn(error)` runs instead of tearing down.
 
 ```ts
-watchDir(".build").exec().tag("watch:daemon"); // crash here → run tears down
-someFlakyDaemon()
-  .exec()
-  .handleFailure((e) => log(e)); // …unless you own it
+web().tag("web"); // if the web daemon crashes, the run tears down — you'll know
+flakyBackgroundJob().handleFailure((e) => console.warn("job failed, carrying on", e));
 ```
 
-**Ctrl+C** and **`ctx.cancel()`** tear everything down gracefully — the log is always written. And **success is keep-alive**: when your `om` body returns, daemons it launched keep running until Ctrl+C or `cancel()`, so a body that finishes wiring things up doesn't kill the servers it started.
+**Ctrl+C** and **`ctx.cancel()`** tear everything down gracefully — procs are killed, waits unblock, the log is always written. And **success is keep-alive**: when your `om` body returns, the daemons it started keep running until Ctrl+C or `cancel()`, so wiring things up doesn't kill the servers you just started.
 
-### One log, on disk
+### One log, on disk — a run an assistant can follow
 
-Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline**. It streams live to the terminal (curated milestones) and is written to a per-run folder:
+Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline** — streamed live to the terminal (curated milestones) and written to a per-run folder:
 
 - `result.json` — the run's tree, per-node status, and verdict.
 - `raw.jsonl` — every entry, machine-readable.
-- `main.log` + one `.log` per node — the human-readable timelines.
+- `main.log` + one `.log` per action — the human-readable timelines.
 - `events.log` / `asserts.log` / `snapshots.log` — cross-cutting rollups.
 
-`ctx` also gives each action `assert(...)` (tallies into the verdict) and `snapshot(name, value)` (captures JSON state to the run folder) — so a run is an inspectable artifact, not just exit codes.
+`ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict) and `snapshot(name, value)` (captures JSON state to the run folder) — so a run is an inspectable artifact, not just an exit code.
+
+Run folders have a **stable identity**: `logs/<name>-<hash8>/<date>/<time>/`, keyed by the om's name and the file that defines it. An assistant (or a script) can always find "the latest `tskb-dev` run" without parsing scrollback, diff two runs of the same pipeline, or answer questions with evidence instead of inference: _did the server actually pass its healthcheck? which process died first? what config did the build run with?_ It's all in the folder — attributed per action, timestamped, with a verdict.
+
+### Observing the real world, not assuming it
+
+The batteries are built around **ground truth**. `healthcheck` gates on the service actually answering, not on "process started". `chromePage` hands downstream steps a live browser page — real DOM, real network — so a smoke check inspects the app a user would see. `snapshot` freezes the inputs and state a run saw, and `assert` turns observations into a tallied verdict. For a human, that means less babysitting; for an AI assistant, it means the run folder **is** its view of the world — it follows what happened rather than imagining it.
+
+## Common recipes
+
+**Skip work that's already done.** `withCache` fingerprints inputs and skips the body when nothing changed since the last successful run (a hit resolves `undefined`):
+
+```ts
+const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
+
+om("build", async () => {
+  const out = await build().withCache(`${process.cwd()}/src`).result;
+  if (out.ok && out.value === undefined) console.log("no changes — skipped the build");
+});
+```
+
+**Watch and react.** Launch a watcher, subscribe to its events, and let the run stay alive:
+
+```ts
+import { watchDir } from "omkit/actions";
+
+om("watch", async () => {
+  const watcher = watchDir("src").tag("watch");
+  watcher.on("update", (file) => console.log(`changed: ${file}`));
+  // body returns, but the watcher keeps the run alive until Ctrl+C
+});
+```
+
+**Gate a deploy on green tests.** Observe the outcome and branch — no try/catch:
+
+```ts
+om("ship", async () => {
+  const tests = await command("npm test")().result;
+  if (!tests.ok) return; // red → stop; the run stays green because you observed it
+  await command("./deploy.sh")().result;
+});
+```
+
+**Keep a human in the loop.** `prompt` asks the terminal and falls back to a default when unattended, so it never blocks CI or an agent-driven run:
+
+```ts
+import { prompt } from "omkit/actions";
+
+om("deploy", async () => {
+  const answer = await prompt({
+    kind: "choice",
+    message: "Deploy to production?",
+    choices: ["no", "yes"],
+    default: "no",
+    timeoutMs: 10_000, // no answer in 10s → "no"
+  }).result;
+  if (answer.ok && answer.value === "yes") await command("./deploy.sh")().result;
+});
+```
 
 ## Events
 
@@ -128,7 +199,7 @@ An Activity exposes its declared events plus the lifecycle ones (`done`, `error`
 - **`activity.once(event)`** — a **promise** for the next emit; resolves `undefined` if the Activity settles first, so an `await` never hangs. A retained snapshot (like `healthy`) is replayed immediately even if you subscribe late.
 
 ```ts
-const probe = healthcheck({ port: 3000 }).exec();
+const probe = healthcheck({ url: "http://localhost:3000" });
 probe.on("healthy", (r) => console.log(`up after ${r.attempts} tries`));
 ```
 
@@ -136,7 +207,7 @@ probe.on("healthy", (r) => console.log(`up after ${r.attempts} tries`));
 
 Reusable actions built on the core engine. For anything beyond these, drop down to `action(...).run(...)`.
 
-- **`command`** — run a shell command; output streams to the log, killed on teardown.
+- **`command`** — define a shell-command action, named after the command; output streams to the log, killed on teardown.
 - **`watch`** / **`watchDir`** — watch a file or directory for changes (survives wipe + recreate).
 - **`untilLog`** — gate on the first log entry matching a predicate.
 - **`tailLog`** — tail a file another process writes, folding its lines into the combined log.

package/dist/actions/command.d.ts

@@ -13,11 +13,12 @@ export interface CommandOptions {
     inheritDebugger?: boolean;
 }
 /**
- * Runs a command as an action instance.
+ * Defines a command action, named after the command itself (add a semantic label with
+ * `.tag(...)`). Call the returned action to launch it.
  *
  * 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, 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>;
+export declare function command(cmdOrFile: string, options?: CommandOptions): import("../index.ts").Action<[], import("zx").ProcessOutput, import("../core/types.ts").NoEvents, void> | import("../index.ts").Action<[], void, import("../core/types.ts").NoEvents, void>;

package/dist/actions/command.js

@@ -7,32 +7,34 @@ import { debuggerFreeEnv, killTree, streamLines } from "../system/proc.js";
  */
 const verbatim = (cmd) => Object.assign([cmd], { raw: [cmd] });
 /**
- * Runs a command as an action instance.
+ * Defines a command action, named after the command itself (add a semantic label with
+ * `.tag(...)`). Call the returned action to launch it.
  *
  * 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, cmdOrFile, options = {}) {
+export function command(cmdOrFile, options = {}) {
     const cwd = path.resolve(options.cwd ?? ".");
-    // Shell command.
+    // Shell command — the command string is the action (and proc) name.
     if (options.args === undefined) {
-        return action(name).run((ctx) => ctx.proc(name, {
+        return action(cmdOrFile).run((ctx) => ctx.proc(cmdOrFile, {
             cwd,
             ...(options.env && { env: options.env }),
             ...(options.inheritDebugger && {
                 inheritDebugger: true,
             }),
-        })(verbatim(cmdOrFile)))();
+        })(verbatim(cmdOrFile)));
     }
-    // Direct executable.
+    // Direct executable — the file plus its args form the action name.
+    const args = options.args;
+    const name = [cmdOrFile, ...args].join(" ");
     return action(name).run(async (ctx) => {
-        const inherit = options.inheritDebugger ?? Boolean(process.env.OMKIT_INHERIT_DEBUGGER);
+        const inherit = options.inheritDebugger;
         const env = inherit
             ? (options.env ?? process.env)
             : debuggerFreeEnv(options.env ?? process.env);
-        const args = options.args ?? [];
         const child = spawn(cmdOrFile, args, {
             cwd,
             env,
@@ -75,5 +77,5 @@ export function command(name, cmdOrFile, options = {}) {
             finished = true;
             ctx.signal.removeEventListener("abort", onAbort);
         }
-    })();
+    });
 }

package/dist/core/ActionRun.d.ts

@@ -2,7 +2,7 @@ import { type EventHandler } from "../foundation/events.ts";
 import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
-import type { Exec, InstanceEvents, NodeStatus, Outcome, RunHandle } from "./types.ts";
+import type { Activity, Exec, InstanceEvents, NodeStatus, Outcome } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
     readonly store: LogStore;
@@ -34,7 +34,7 @@ export interface NodeInit {
  * `run(exec, args)` executes the body inside the error boundary and settles the
  * node; it never throws (the failure is delivered through `.result`).
  */
-export declare class ActionRun<Result = unknown, Events extends object = object, Handle = unknown> implements RunHandle<Result, Events, Handle> {
+export declare class ActionRun<Result = unknown, Events extends object = object, Handle = unknown> implements Activity<Result, Events, Handle> {
     readonly id: string;
     readonly uuid: string;
     readonly name: string;
@@ -66,6 +66,9 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private observed;
     private refObserved;
     private cancelLogged;
+    private armedExec;
+    private armedArgs;
+    private committed;
     private cascadeCancelled;
     constructor(init: NodeInit);
     /** A stable reference for headers/attribution (tags are the accumulated set now). */
@@ -78,6 +81,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     tag(name: string): this;
+    withCache(...paths: string[]): Activity<Result | undefined, Events, Handle>;
     handleFailure(handler: (error: unknown) => void): this;
     cancel(): void;
     /**
@@ -87,6 +91,13 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
      * never for the root, whose cancellation is the run-level `tearing down · …` narration.
      */
     private noteCancelled;
+    /**
+     * Arm the node with its body + args. The body is not run here — {@link commit} runs it
+     * one microtask later, leaving a window in which `withCache` can still wrap it.
+     */
+    arm(exec: Exec<Events, Handle, Result>, args: readonly unknown[]): void;
+    /** Run the armed body once (idempotent). Called on a microtask after the launching call. */
+    commit(): Promise<void>;
     /** 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

@@ -3,6 +3,7 @@ import { events } from "../foundation/events.js";
 import { CancelledError } from "../foundation/CancelledError.js";
 import { renderValue } from "../foundation/format.js";
 import { createProc } from "../system/proc.js";
+import { FolderCache } from "../system/fs/FolderCache.js";
 /**
  * One node in the {@link ExecutionTree}: its identity, tags, timing, and terminal
  * state, plus the run handle (`result`/`ref`/`once`/`tag`/`cancel`). Self-contained —
@@ -41,6 +42,11 @@ export class ActionRun {
     observed = false;
     refObserved = false;
     cancelLogged = false;
+    // The armed body + args, set at launch and run once by `commit()` on a microtask — the
+    // window during which `withCache` may still wrap the body. `committed` closes that window.
+    armedExec;
+    armedArgs = [];
+    committed = 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().
@@ -97,9 +103,9 @@ export class ActionRun {
         return this.handle.promise;
     }
     on(key, handler) {
-        // A late `on("error")` (e.g. attached after a synchronously-throwing body already
-        // failed inline during `.exec()`) still receives the failure: the emitter snapshots
-        // the last "error" payload and replays it to a new listener.
+        // A late `on("error")` (e.g. attached after an `await`, once the body has already
+        // failed) still receives the failure: the emitter snapshots the last "error" payload
+        // and replays it to a new listener.
         if (key === "error")
             this.observed = true;
         this.emitter.listen(key, handler);
@@ -128,12 +134,24 @@ export class ActionRun {
         this.log("tag", "tag", name);
         return this;
     }
+    withCache(...paths) {
+        if (this.committed) {
+            throw new Error("withCache: already launched — chain it before the first await");
+        }
+        // Validate + canonicalize eagerly (fails fast on a relative path), then wrap the armed
+        // body so a fingerprint hit skips it. Applied before `commit()` runs the body.
+        const targets = FolderCache.resolvePaths(paths);
+        const inner = this.armedExec;
+        if (inner)
+            this.armedExec = cacheGate(inner, targets);
+        return this;
+    }
     handleFailure(handler) {
         this.failureHandler = handler;
         this.observed = true;
-        // A synchronously-throwing body fails inline during `.exec()`, before this attaches:
-        // deliver the already-recorded failure now (it won't fail again). Cancellation is
-        // status "cancelled", not "failed", so a cancelled node never runs the handler.
+        // Attached after an `await` on a body that has already failed: deliver the
+        // already-recorded failure now (it won't fail again). Cancellation is status
+        // "cancelled", not "failed", so a cancelled node never runs the handler.
         if (this.status === "failed")
             handler(this.error);
         return this;
@@ -156,11 +174,36 @@ export class ActionRun {
         this.bubble("⊘ cancelled");
     }
     // ── Execution ──────────────────────────────────────────────────────────────
+    /**
+     * Arm the node with its body + args. The body is not run here — {@link commit} runs it
+     * one microtask later, leaving a window in which `withCache` can still wrap it.
+     */
+    arm(exec, args) {
+        this.armedExec = exec;
+        this.armedArgs = args;
+    }
+    /** Run the armed body once (idempotent). Called on a microtask after the launching call. */
+    commit() {
+        if (this.committed)
+            return Promise.resolve();
+        this.committed = true;
+        const exec = this.armedExec;
+        this.armedExec = undefined;
+        return exec ? this.run(exec, this.armedArgs) : Promise.resolve();
+    }
     /** Run the body inside the error boundary, settling the node. Never rejects. */
     async run(exec, args) {
         this.args = args;
         this.startedAt = Date.now();
         this.lifecycle("launched");
+        // Cancelled before the body could start — the run tore down between the launching call
+        // and this microtask. Record a clean stop without invoking the body, so a daemon that
+        // only listens for `abort` (its listener would never fire, the abort having already
+        // happened) can't wedge teardown.
+        if (this.controller.signal.aborted) {
+            this.fail(new CancelledError());
+            return;
+        }
         try {
             const result = await exec(this.context(), ...args);
             this.succeed(result);
@@ -282,3 +325,18 @@ export class ActionRun {
 }
 const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);
 const firstLine = (message) => message.split("\n", 1)[0] ?? message;
+/**
+ * Wrap an exec so it skips (returns `undefined`, logging `cached, skipping`) when the
+ * input `targets` are unchanged since the last successful run, else runs the inner body
+ * and records the fresh fingerprint. Backs {@link ActionRun.withCache}.
+ */
+const cacheGate = (inner, targets) => (async (ctx, ...args) => {
+    const fp = await FolderCache.fingerprint(targets);
+    if ((await FolderCache.read(targets)) === fp) {
+        console.log("cached, skipping");
+        return undefined;
+    }
+    const result = await inner(ctx, ...args);
+    await FolderCache.write(targets, fp);
+    return result;
+});

package/dist/core/ExecutionTree.d.ts

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

package/dist/core/ExecutionTree.js

@@ -1,6 +1,7 @@
 import path from "node:path";
-import { newUuid, makeId } from "../foundation/ids.js";
+import { newUuid, makeId, omHash } from "../foundation/ids.js";
 import { fsSafe } from "../foundation/fsSafe.js";
+import { siteFile } from "../foundation/callsite.js";
 import { defer } from "../foundation/Deferred.js";
 import { LogStore } from "../output/log/LogStore.js";
 import { RunFolder } from "../output/folder/RunFolder.js";
@@ -36,11 +37,11 @@ export class ExecutionTree {
         ExecutionTree.current = null;
     }
     store = new LogStore();
-    folder = new RunFolder();
+    folder;
     root;
     rawStream;
     consoleCapture;
-    snapshotStore = new SnapshotStore(this.folder);
+    snapshotStore;
     registry = [];
     unsettled = new Set();
     originalLog = console.log.bind(console);
@@ -62,7 +63,11 @@ 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(definedAt) {
+    constructor(name, definedAt) {
+        // The run's identity: its name + where om() is written (not how it was launched),
+        // so same-named oms in different files get distinct log folders.
+        this.folder = new RunFolder(name, omHash(name, siteFile(definedAt)));
+        this.snapshotStore = new SnapshotStore(this.folder);
         this.folder.ensure();
         this.root = new ActionRun({
             ...this.nodeDeps(),
@@ -110,8 +115,16 @@ export class ExecutionTree {
         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));
-        this.trackNode(promise);
+        // Arm the body now, but commit it on a microtask: this lets `withCache`/`tag` chained on
+        // the returned handle (before the caller's first await) apply before the body starts.
+        // The tracked promise is registered synchronously (so `drive()` waits on it), and the
+        // microtask is scheduled unconditionally so a fire-and-forget launch still commits.
+        node.arm(spec.body, spec.args);
+        const settled = defer();
+        this.trackNode(settled.promise);
+        queueMicrotask(() => {
+            void currentNode.run(node, () => node.commit()).then(() => settled.resolve());
+        });
         return node;
     }
     append(node, level, source, message) {

package/dist/core/action.d.ts

@@ -1,6 +1,7 @@
 import type { ActionBuilderEvents, NoEvents } from "./types.ts";
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`).
+ * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * to launch it.
  */
 export declare function action(name: string): ActionBuilderEvents<NoEvents, void>;

package/dist/core/action.js

@@ -1,54 +1,11 @@
 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
- * the node under the ambient current action and runs it.
+ * The builder returned by `action(name)`: declare events (`.emits<…>()`) and/or an
+ * imperative handle (`.ref<…>()`), then bind the impl with `.run(…)`. `.run` returns a
+ * callable {@link Action} — **invoking it launches** the action under the ambient current
+ * node and returns the live {@link Activity}, on which `withCache`/`tag`/… chain.
  */
-class Instance {
-    name;
-    body;
-    args;
-    definedAt;
-    tags = [];
-    constructor(name, body, args, definedAt) {
-        this.name = name;
-        this.body = body;
-        this.args = args;
-        this.definedAt = definedAt;
-    }
-    tag(name) {
-        this.tags.push(name);
-        return this;
-    }
-    withCache(...paths) {
-        // Validate + canonicalize eagerly here (fails fast on a relative path).
-        const targets = FolderCache.resolvePaths(paths);
-        const innerBody = this.body;
-        const innerArgs = this.args;
-        // Wrap in a fresh instance that keeps this action's name/tags and, at run time,
-        // fingerprints the inputs — skipping (return undefined) on a hit, else running
-        // the inner body and recording the fingerprint on success.
-        const body = (async (ctx, ...args) => {
-            const fp = await FolderCache.fingerprint(targets);
-            if ((await FolderCache.read(targets)) === fp) {
-                console.log("cached, skipping");
-                return undefined;
-            }
-            const result = (await innerBody(ctx, ...args));
-            await FolderCache.write(targets, fp);
-            return result;
-        });
-        const cached = new Instance(this.name, body, innerArgs, this.definedAt);
-        cached.tags.push(...this.tags);
-        return cached;
-    }
-    exec() {
-        return ExecutionTree.require().launch(this);
-    }
-}
-/** The builder returned by `action(name)`: declare events/handle, then bind the impl. */
 class Builder {
     name;
     constructor(name) {
@@ -63,13 +20,18 @@ class Builder {
     run(body) {
         const name = this.name;
         const definedAt = callerSite(); // the `.run(...)` call site — where this action lives
-        const create = (...args) => new Instance(name, body, args, definedAt);
+        const exec = body;
+        const create = (...args) => {
+            const spec = { name, args, tags: [], body: exec, definedAt };
+            return ExecutionTree.require().launch(spec);
+        };
         return Object.assign(create, { actionName: name, definedAt });
     }
 }
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`).
+ * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * to launch it.
  */
 export function action(name) {
     return new Builder(name);

package/dist/core/context.d.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ActionRun } from "./ActionRun.ts";
 /**
- * Holds the **current node** for the duration of an exec. Read by
- * `instance.exec()` (to find its parent) and by console capture (to attribute a
- * `console.*` line) — the single ambient mechanism that replaces `nod` and makes
- * scoping compose without threading anything by hand.
+ * Holds the **current node** for the duration of an exec. Read when an action is
+ * launched (to find its parent) and by console capture (to attribute a `console.*`
+ * line) — the single ambient mechanism that replaces `nod` and makes scoping
+ * compose without threading anything by hand.
  */
 export declare const currentNode: AsyncLocalStorage<ActionRun<unknown, object, unknown>>;

package/dist/core/context.js

@@ -1,8 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 /**
- * Holds the **current node** for the duration of an exec. Read by
- * `instance.exec()` (to find its parent) and by console capture (to attribute a
- * `console.*` line) — the single ambient mechanism that replaces `nod` and makes
- * scoping compose without threading anything by hand.
+ * Holds the **current node** for the duration of an exec. Read when an action is
+ * launched (to find its parent) and by console capture (to attribute a `console.*`
+ * line) — the single ambient mechanism that replaces `nod` and makes scoping
+ * compose without threading anything by hand.
  */
 export const currentNode = new AsyncLocalStorage();

package/dist/core/om.d.ts

@@ -1,9 +1,11 @@
 import type { Awaitable, OmContext } from "./types.ts";
 /**
  * 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()` /
- * `step(...)` / `console.*` it reaches attributes correctly. Resolves once the run
- * has torn down and produced its artifacts; never rejects (failures are recorded in
- * the tree and set the exit code).
+ * required `name` plus the absolute path of the file calling `om()` form the run's
+ * identity — its log folder is `logs/<name>-<hash8>/…`, so same-named oms defined
+ * in different files never share a folder. The body runs inside the root node's
+ * ambient scope, so any action call / `step(...)` / `console.*` it reaches
+ * attributes correctly. Resolves once the run has torn down and produced its
+ * artifacts; never rejects (failures are recorded in the tree and set the exit code).
  */
-export declare function om(body: (ctx: OmContext) => Awaitable<void>): Promise<void>;
+export declare function om(name: string, body: (ctx: OmContext) => Awaitable<void>): Promise<void>;

package/dist/core/om.js

@@ -2,16 +2,21 @@ 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()` /
- * `step(...)` / `console.*` it reaches attributes correctly. Resolves once the run
- * has torn down and produced its artifacts; never rejects (failures are recorded in
- * the tree and set the exit code).
+ * required `name` plus the absolute path of the file calling `om()` form the run's
+ * identity — its log folder is `logs/<name>-<hash8>/…`, so same-named oms defined
+ * in different files never share a folder. The body runs inside the root node's
+ * ambient scope, so any action call / `step(...)` / `console.*` it reaches
+ * attributes correctly. Resolves once the run has torn down and produced its
+ * artifacts; never rejects (failures are recorded in the tree and set the exit code).
  */
-export function om(body) {
+export function om(name, body) {
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new Error("om(name, body) requires a non-empty name — it identifies the run in logs/");
+    }
     if (ExecutionTree.current) {
         throw new Error("an om() run is already active in this process");
     }
-    const tree = new ExecutionTree(callerSite()); // where om() was called — the run's script
+    const tree = new ExecutionTree(name, callerSite()); // callerSite: where om() was called — the run's script
     ExecutionTree.current = tree;
     const rootBody = (ctx) => body({
         signal: ctx.signal,

package/dist/core/step.js

@@ -9,7 +9,6 @@ import { action } from "./action.js";
 export function step(name, fn) {
     return action(name)
         .run(fn)()
-        .exec()
         .result.then((r) => {
         if (!r.ok)
             throw r.error;

package/dist/core/types.d.ts

@@ -65,19 +65,29 @@ export interface OmContext {
     readonly artifactsFolder: string;
 }
 /**
- * A launched action: the live node's awaitable/observable surface. `.result` always
- * resolves an {@link Outcome} (never throws); `.ref` rejects on failure/cancel.
+ * A launched action: the live node's awaitable/observable surface, returned by
+ * **invoking an {@link Action}**. `.result` always resolves an {@link Outcome} (never
+ * throws); `.ref` rejects on failure/cancel. The body is committed one microtask after
+ * the launching call, so pre-body config (`withCache`) chained before the first `await`
+ * still applies.
  */
-export interface RunHandle<Result = unknown, Events extends object = NoEvents, Handle = void> {
+export interface Activity<Result = unknown, Events extends object = NoEvents, Handle = void> {
     readonly id: string;
     /** The terminal outcome; always resolves (never rejects). Reading it observes the failure. */
     readonly result: Promise<Outcome<Result>>;
     /** The attached handle; rejects on failure/cancel. */
     readonly ref: Promise<Handle>;
+    /**
+     * Gate this activity on its **input** files/folders (absolute paths): skip running the
+     * body when they're unchanged since the last successful run (a hit resolves `undefined`
+     * and logs `cached, skipping`). **Pre-body only** — chain it before the first `await`
+     * after the launching call; calling it once the body has started throws.
+     */
+    withCache(...paths: string[]): Activity<Result | undefined, Events, Handle>;
     /**
      * Handle a fire-and-forget activity's failure: attach a handler so a crash runs it
      * instead of tearing the run down. Observes the failure; chainable; attach in the
-     * same tick as `.exec()`. Not called on cancellation.
+     * same tick as the launching call. Not called on cancellation.
      */
     handleFailure(handler: (error: unknown) => void): this;
     /** Subscribe to every emit of a declared/system event (`done`/`error`/`attached`). */
@@ -89,26 +99,9 @@ export interface RunHandle<Result = unknown, Events extends object = NoEvents, H
     /** Abort this node and its subtree. */
     cancel(): void;
 }
-/** A constructed-but-not-yet-run action: what calling an `Action` produces. */
-export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
-    readonly name: string;
-    readonly args: readonly unknown[];
-    /** Buffer a tag before launch; applied onto the node at creation. Chainable. */
-    tag(name: string): this;
-    /**
-     * Gate this action on its **input** files/folders (absolute paths): skip running
-     * when they're unchanged since the last successful run (a hit resolves
-     * `undefined` and logs `cached, skipping`). Chain before launching.
-     */
-    withCache(...paths: string[]): ActionInstance<Result | undefined, Events, Handle>;
-    /** Launch under the ambient current node; returns the live {@link RunHandle}. */
-    exec(): RunHandle<Result, Events, Handle>;
-}
-/** Any constructed instance, whatever its result/events/handle. */
-export type AnyActionInstance = ActionInstance<unknown, object, unknown>;
-/** A callable produced by `action`: invoking it builds an {@link ActionInstance}. */
+/** A callable produced by `action`: **invoking it launches** the action and returns the live {@link Activity}. */
 export interface Action<Args extends unknown[], Result, Events extends object = NoEvents, Handle = void> {
-    (...args: Args): ActionInstance<Result, Events, Handle>;
+    (...args: Args): Activity<Result, Events, Handle>;
     readonly actionName: string;
     /** `file:line` where this action was defined (the `.run(...)` site), for the log header. */
     readonly definedAt: string | undefined;

package/dist/foundation/callsite.d.ts

@@ -4,4 +4,9 @@
  * 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.
  */
+/**
+ * The file part of a `file:line` site — the run-identity input (the line is dropped
+ * so moving a call within its file doesn't change the run's identity).
+ */
+export declare const siteFile: (site: string | undefined) => string | undefined;
 export declare const callerSite: () => string | undefined;

package/dist/foundation/callsite.js

@@ -22,6 +22,11 @@ const nativePath = (file) => {
  * 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.
  */
+/**
+ * The file part of a `file:line` site — the run-identity input (the line is dropped
+ * so moving a call within its file doesn't change the run's identity).
+ */
+export const siteFile = (site) => site?.replace(/:\d+$/, "");
 export const callerSite = () => {
     const stack = new Error().stack;
     if (!stack)

package/dist/foundation/ids.d.ts

@@ -7,3 +7,11 @@ export declare const shortId: (uuid: string) => string;
  * plain name (`main`) and skips this.
  */
 export declare const makeId: (name: string, uuid: string) => string;
+/**
+ * A run's stable identity: first 8 hex of sha256 over the defining file's absolute
+ * path + the om name. Same file + name ⇒ same hash on every run; the same name
+ * defined in two different files diverges (consumers may define oms in same-named
+ * files across folders). With no file (no stack), the name alone still hashes
+ * deterministically.
+ */
+export declare const omHash: (name: string, file?: string) => string;

package/dist/foundation/ids.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 /** A fresh v4 uuid for a node. */
 export const newUuid = () => randomUUID();
 /** The short form used in ids/paths — first 8 hex of the uuid. */
@@ -8,3 +8,14 @@ export const shortId = (uuid) => uuid.slice(0, 8);
  * plain name (`main`) and skips this.
  */
 export const makeId = (name, uuid) => `${name}_${shortId(uuid)}`;
+/**
+ * A run's stable identity: first 8 hex of sha256 over the defining file's absolute
+ * path + the om name. Same file + name ⇒ same hash on every run; the same name
+ * defined in two different files diverges (consumers may define oms in same-named
+ * files across folders). With no file (no stack), the name alone still hashes
+ * deterministically.
+ */
+export const omHash = (name, file) => createHash("sha256")
+    .update(`${file ?? ""}\0${name}`)
+    .digest("hex")
+    .slice(0, 8);

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * omkit (refactored core) — the ExecutionTree model.
  *
- * A curated public surface. `om(body)` runs a linear orchestration as the root of
- * one run; `action(...)` defines typed units you launch with `.exec()`;
+ * A curated public surface. `om(name, body)` runs a linear orchestration as the root of
+ * one run; `action(...)` defines typed units you launch by **calling** them;
  * `step(name, fn)` is the inline anonymous action. The run's introspectable output
  * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree
  * engine itself is internal and intentionally not exported.
@@ -11,4 +11,4 @@ export { om } from "./core/om.ts";
 export { action } from "./core/action.ts";
 export { step } from "./core/step.ts";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
-export type { Action, ActionInstance, ActionContext, OmContext, RunHandle, Outcome, } from "./core/types.ts";
+export type { Action, Activity, ActionContext, OmContext, Outcome } from "./core/types.ts";

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * omkit (refactored core) — the ExecutionTree model.
  *
- * A curated public surface. `om(body)` runs a linear orchestration as the root of
- * one run; `action(...)` defines typed units you launch with `.exec()`;
+ * A curated public surface. `om(name, body)` runs a linear orchestration as the root of
+ * one run; `action(...)` defines typed units you launch by **calling** them;
  * `step(name, fn)` is the inline anonymous action. The run's introspectable output
  * is the on-disk `result.json` / `raw.jsonl` / `.log` files — the ExecutionTree
  * engine itself is internal and intentionally not exported.

package/dist/output/LiveRenderer.js

@@ -76,7 +76,10 @@ const format = (e, tags) => {
         if (e.message === "launched")
             return null;
         const status = e.message.replace(/^done · /, "");
-        return { text: `${doneIcon(status)} ${named(e.path, tags)} · ${status}`, persist: status === "failed" };
+        return {
+            text: `${doneIcon(status)} ${named(e.path, tags)} · ${status}`,
+            persist: status === "failed",
+        };
     }
     // Run milestones (started / tearing down / finished) — few, and worth keeping.
     if (e.level === "run")

package/dist/output/folder/RunFolder.d.ts

@@ -1,13 +1,16 @@
 /**
- * Owns this run's single output directory — `logs/<name>/<date>/<time>/` — where
- * `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all live.
- * The path is computed once, lazily, and always returned absolute so links written
- * into logs resolve regardless of cwd.
+ * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
+ * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
+ * live. The path is computed once, lazily, and always returned absolute so links
+ * written into logs resolve regardless of cwd.
  */
 export declare class RunFolder {
+    private readonly runName;
+    private readonly hash;
     private dir;
     private ensured;
-    /** The entry script's base name — the run's folder name. */
+    constructor(runName: string, hash: string);
+    /** `<name>-<hash8>` — the run's folder name, unique per (defining file, name). */
     name(): string;
     /** The absolute run directory, computed once and created on first access. */
     path(): string;

package/dist/output/folder/RunFolder.js

@@ -1,19 +1,25 @@
 import { mkdirSync } from "node:fs";
 import path from "node:path";
 import { ymd, hms } from "../../foundation/format.js";
+import { fsSafe } from "../../foundation/fsSafe.js";
 /**
- * Owns this run's single output directory — `logs/<name>/<date>/<time>/` — where
- * `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all live.
- * The path is computed once, lazily, and always returned absolute so links written
- * into logs resolve regardless of cwd.
+ * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
+ * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
+ * live. The path is computed once, lazily, and always returned absolute so links
+ * written into logs resolve regardless of cwd.
  */
 export class RunFolder {
+    runName;
+    hash;
     dir;
     ensured = false;
-    /** The entry script's base name — the run's folder name. */
+    constructor(runName, hash) {
+        this.runName = runName;
+        this.hash = hash;
+    }
+    /** `<name>-<hash8>` — the run's folder name, unique per (defining file, name). */
     name() {
-        const entry = process.argv[1];
-        return entry ? path.basename(entry, path.extname(entry)) : "om";
+        return `${fsSafe(this.runName)}-${this.hash}`;
     }
     /** The absolute run directory, computed once and created on first access. */
     path() {

package/package.json

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