oh-my-workflow 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,491 @@
+---
+name: oh-my-workflow
+description: Use when a task decomposes into multiple coding-agent CLI calls (claude -p / codex exec) that should run as one structured, schema-gated, journaled workflow — fan-out search, verify-vote, pipeline, or loop-until-dry. Teaches you to author a plain-JS omw script, run it with `omw run`, read the JSONL journal, and repair your own script from structured failures.
+---
+
+# oh-my-workflow (omw)
+
+You write a **plain-JS orchestration script**. Its nodes are whole coding-agent
+CLIs you already pay for (`claude -p`, `codex exec`). omw is the thin glue: it
+runs your script, schema-gates each node's output, and journals every step — so
+you can read your own failure and fix your own script. (What's "deterministic" is
+scoped below — the engine's guarantees and `--agent fake`, not your script.)
+
+The runtime gives your script exactly **five hooks** (`agent` / `pipeline` /
+`parallel` / `phase` / `log`). That is the entire surface. There is no DSL to
+learn; everything else is ordinary JavaScript control flow.
+
+## When to use this
+
+Reach for omw when a task is a **multi-step pipeline over agent calls** that
+benefits from structure you'd otherwise hand-roll:
+
+- **Fan-out**: run N independent agent calls concurrently, collect results.
+- **Verify / vote**: produce a finding, then have K independent agents judge it.
+- **Pipeline**: each item flows scope → search → verify → synthesize independently.
+- **Loop-until-dry**: keep spawning finders until a round returns nothing new.
+
+You want: bounded concurrency, schema-validated node output with automatic
+node-level retry, a replayable journal, and a `null`-on-failure contract so one
+bad node never crashes the run.
+
+**Don't** use omw for a single agent call, or for work that needs a sandbox
+(omw deliberately has none — your script is trusted code), or where a node is a
+single raw LLM API call (that's LangGraph/Mastra territory; an omw node is a
+*whole coding agent*).
+
+## The 30-second free demo (no API key)
+
+```sh
+git clone <repo-url> && cd oh-my-workflow   # repo not yet public; fill in the URL
+bun install
+bun src/cli/omw.ts run examples/deep-research --agent fake
+# → {"confirmed":[…],"summary":{…}}     exit 0 · no key · no cost · `--agent fake` is deterministic
+```
+
+`--agent fake` is a built-in deterministic adapter: it runs the full spine
+(fan-out + pipeline + a scripted schema-fail→self-repair + a scripted
+timeout→drop) and prints one result JSON. Add `--pretty` to see the phase/fan-out
+tree on stderr. Swap `--agent claude` once you've run `claude login`.
+
+> Once published this is `bunx oh-my-workflow run …`; today run the bin directly
+> from a clone as shown above.
+
+---
+
+## The 5 hooks (the entire API)
+
+Your script is a module that **default-exports** `async (rt, args) => result`.
+`rt` is the runtime; `args` is whatever `--args '{…}'` passed (parsed JSON).
+The returned value is serialized to stdout as the run's single result JSON.
+
+```ts
+export default async function (rt, args) {
+  // rt.agent / rt.pipeline / rt.parallel / rt.phase / rt.log
+  return { /* whatever you want on stdout */ };
+}
+```
+
+### `rt.agent(prompt, opts?) => Promise<result | null>`
+
+Runs one coding-agent CLI node. **Never throws.** A terminal failure resolves to
+`null` (and is journaled with a failure `kind`). This is the load-bearing
+**null-contract** — build on it with `filter(Boolean)` and abstain quorums.
+
+```ts
+const out = await rt.agent("SCOPE the question into topics", {
+  schema: { type: "object", required: ["topics"], properties: { topics: { type: "array" } } },
+  label: "scope",        // shows in the journal / --pretty tree
+  phase: "Scope",        // overrides the ambient phase() for this call
+  model: "smart",        // tier alias or raw model string, passed to the adapter
+  timeoutMs: 120_000,    // kill the subprocess after this; failure kind = "timeout"
+  cwd: "/path/to/repo",  // run the agent in this directory
+  maxRetries: 2,         // schema-gate retries (default 2 → up to 3 attempts)
+});
+```
+
+- **With `schema`**: omw extracts JSON from the node's text, validates it with
+  ajv, and on a mismatch **re-prompts the same node** with the validation errors
+  (in-session via the adapter's resume if available, else fresh + error appended)
+  up to `maxRetries` times. On success `agent()` returns the **validated object**.
+  On exhaustion it returns `null`. **You never see schema noise** — only the
+  structured outcome. The schema is plain JSON Schema.
+- **Without `schema`**: one shot; returns the raw text string, or `null` on
+  adapter failure.
+
+### `rt.parallel(thunks) => Promise<any[]>` — barrier
+
+Runs thunks concurrently, awaits **all** of them. A thunk that throws (or whose
+agent fails) becomes `null` in the result array — the call itself never rejects.
+**`.filter(Boolean)` before using results.** Use only when you need every result
+together (dedup, count, cross-comparison).
+
+```ts
+const results = (await rt.parallel(
+  topics.map((t) => () => rt.agent(`SEARCH ${t}`, { schema: S, label: `search:${t}` })),
+)).filter(Boolean);
+```
+
+### `rt.pipeline(items, ...stages) => Promise<any[]>` — no barrier (default)
+
+Runs each item through **all** stages independently. Item A can be in stage 3
+while item B is still in stage 1 — wall-clock is the slowest single chain, not
+the sum of slowest-per-stage. Each stage receives `(prev, item, index)`. A stage
+that throws drops that item to `null` (skips its remaining stages). This is the
+default for multi-stage work; only use `parallel` as a barrier when a stage
+genuinely needs the whole previous result set at once.
+
+```ts
+const verified = (await rt.pipeline(
+  found,
+  async (f) => {
+    const v = await rt.agent(`VERIFY ${JSON.stringify(f)}`, { schema: V });
+    return v ? { ...f, ...v } : null;     // null → dropped by the filter below
+  },
+)).filter(Boolean);
+```
+
+### `rt.phase(title)` and `rt.log(msg)`
+
+`phase` groups subsequent `agent()` calls under a heading in the journal and the
+`--pretty` tree. `log` emits a narration line. Both are side-channel only — they
+never touch stdout.
+
+### Concurrency
+
+The runtime bounds concurrency **at the `agent()` boundary** (default 4, set with
+`--concurrency N`). `parallel`/`pipeline` themselves don't take a slot, so you can
+pass hundreds of items — only ~N agent subprocesses run at once; the rest queue.
+
+---
+
+## Pattern templates (copy-paste, then adapt)
+
+### Fan-out (barrier)
+
+```ts
+export default async function (rt, args) {
+  rt.phase("Search");
+  const hits = (await rt.parallel(
+    args.queries.map((q) => () => rt.agent(`SEARCH: ${q}`, { schema: HIT, label: `q:${q}` })),
+  )).filter(Boolean);
+  return { hits, count: hits.length };
+}
+```
+
+### Verify-vote with an **abstain quorum**
+
+A node that fails returns `null`, i.e. it **abstains** — it does not vote "no".
+Count only real verdicts, and require a quorum of *cast* votes so an all-abstain
+finding doesn't silently survive.
+
+```ts
+async function survives(rt, claim) {
+  const votes = (await rt.parallel(
+    [1, 2, 3].map(() => () =>
+      rt.agent(`Try to REFUTE this claim. Default to refuted=true if unsure: ${claim}`, {
+        schema: { type: "object", required: ["refuted"], properties: { refuted: { type: "boolean" } } },
+      })),
+  )).filter(Boolean);                       // drop abstainers (null)
+  if (votes.length < 2) return false;       // quorum: need ≥2 cast votes
+  return votes.filter((v) => !v.refuted).length >= 2;
+}
+```
+
+**Fresh context is the point — not self-critique.** Each `rt.agent()` call is a
+brand-new `claude -p` subprocess with no memory of the producer's turn, so a
+verify-vote node judges the claim cold. That is the structural form of Anthropic's
+own guidance for its most capable model: *"Separate, fresh-context verifier
+subagents tend to outperform self-critique"* ([Fable 5 prompting
+guide](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)).
+omw gets it for free — **as long as you keep verification a separate `agent()`
+call.** Do **not** verify by feeding the result back into the producer's own
+session: the schema-gate's in-session self-repair (the `--resume` / `followUp`
+path) deliberately *reuses* the producer's context to fix output **format**, which
+is the exact opposite of fresh-context verification. Use self-repair to make a
+node's JSON valid; use a new `agent()` to judge whether the *content* is true.
+(A **cross-CLI** verifier — a different agent CLI than the producer, so a shared
+memorized shortcut can't survive both — is a natural extension but **not a feature
+today**: omw binds one adapter per run, so per-node verifier selection is future
+work. Verify with fresh same-CLI nodes for now.)
+
+### Gate on evidence, not intent
+
+The schema gate can only check the *shape* of what a node returns — so for an
+**action-producing** node (one that builds, runs, edits, or fetches), make the
+schema **`required` the evidence the action leaves behind** (an exit code, a test
+count, a file path, the observed output), not just a plan or a `rationale`
+string. A frontier model can fabricate status ("I'll now run the tests…") with no
+tool call behind it; if "I did X" prose satisfies your gate, the gate verifies
+nothing. Requiring the artifact makes an intent string fail validation — the node
+must actually produce the proof:
+
+```ts
+// ✗ intent-only — "I ran the build" text passes this gate
+const weak = { type: "object", required: ["summary"], properties: { summary: { type: "string" } } };
+
+// ✓ evidence-bearing — the node must surface what the action actually produced
+const strong = {
+  type: "object",
+  required: ["command", "exitCode", "testsPassed", "output"],
+  properties: {
+    command: { type: "string" },
+    exitCode: { type: "number" },
+    testsPassed: { type: "number" },
+    output: { type: "string" },           // the observed tail, not a claim about it
+  },
+};
+const built = await rt.agent("Run the build and the test suite. Report the command, its exit code, the number of passing tests, and the tail of the output.", { schema: strong });
+```
+
+**Executable-evidence verify node** — combine this with fresh-context verification:
+a separate node *runs what the producer built and observes the result* before the
+finding is accepted, rather than judging the producer's description of it.
+
+```ts
+const verified = (await rt.pipeline(
+  artifacts,
+  async (a) => {
+    // a.path was written by an upstream node; this fresh node runs it and reports facts.
+    const v = await rt.agent(
+      `Run \`${a.runCmd}\` in ${a.path}. Report exitCode and the output tail. Do not fix anything — only observe and report.`,
+      { schema: { type: "object", required: ["exitCode", "output"], properties: { exitCode: { type: "number" }, output: { type: "string" } } } },
+    );
+    return v && (v as { exitCode: number }).exitCode === 0 ? { ...a, ...(v as object) } : null;
+  },
+)).filter(Boolean);                         // anything that didn't run clean abstains
+```
+
+### Pipeline (no barrier)
+
+```ts
+const out = (await rt.pipeline(
+  items,
+  (item) => rt.agent(`ANALYZE ${item.id}`, { schema: A, label: `analyze:${item.id}` }),
+  (analysis, item) => (analysis ? rt.agent(`SUMMARIZE ${item.id}: ${JSON.stringify(analysis)}`, { schema: S }) : null),
+)).filter(Boolean);
+```
+
+### Loop-until-dry
+
+For unknown-size discovery: keep going until K consecutive rounds find nothing new.
+
+```ts
+const seen = new Set(); const found = []; let dry = 0;
+while (dry < 2) {
+  const round = (await rt.parallel(
+    FINDERS.map((f) => () => rt.agent(f.prompt, { schema: BUG })),
+  )).filter(Boolean);
+  const fresh = round.filter((b) => !seen.has(b.key));
+  if (fresh.length === 0) { dry++; continue; }
+  dry = 0; fresh.forEach((b) => seen.add(b.key)); found.push(...fresh);
+}
+```
+
+---
+
+## The run → journal → fix loop (this is the UX)
+
+```sh
+bun src/cli/omw.ts run my-workflow.ts --agent claude --args '{"q":"…"}'
+```
+
+- **stdout** = the result JSON, one blob. Pipe it, parse it.
+- **journal** = `.omw/<runId>.jsonl`, one event per line. This is where you read
+  *why* a node failed and repair your script.
+- **`--pretty`** = a phase/fan-out tree on **stderr** (never stdout).
+
+### Exit codes
+
+| code | meaning | where the detail is |
+|---|---|---|
+| `0` | run completed (node failures are absorbed by the null-contract) | stdout = result JSON |
+| `1` | **script error** — your JS threw, or syntax/load failure | stderr: `{"error":"script_error"\|"load_failed",…}` |
+| `2` | usage error (bad flags) | stderr: usage line |
+| `3` | adapter CLI not on PATH | stderr: `{"error":"adapter_missing","install_hint":…}` |
+
+Exit `1` means **your script** threw (an `agent()` returning `null` does *not*
+throw — only your own code does). Exit `0` with fewer results than expected means
+nodes failed and were filtered — read the journal.
+
+### Reading a journal
+
+The events are `run_start · phase · agent_start · attempt · agent_end · log ·
+run_end`. A self-repair looks like this (excerpt from a real fake run, `ts`
+fields elided — `search:a` returns invalid JSON, gets re-prompted, recovers):
+
+```jsonl
+{"ev":"agent_start","call":2,"label":"search:a","phase":"Search","adapter":"fake","promptHash":"sha256:…","optsHash":"sha256:…"}
+{"ev":"attempt","call":2,"n":1,"kind":"schema_violation","errors":["/ must have required property 'topic'","/ must have required property 'hits'"],"rawText":"{\"oops\":1}"}
+{"ev":"attempt","call":2,"n":2,"kind":"ok"}
+{"ev":"agent_end","call":2,"ok":true,"result":{"topic":"a","hits":3},"durationMs":0}
+```
+
+A terminal failure carries the **kind** so you know what to fix:
+
+```jsonl
+{"ev":"agent_end","call":3,"ok":false,"kind":"timeout","durationMs":0}
+```
+
+Failure `kind`s on `agent_end`:
+
+- **adapter**: `timeout` · `nonzero_exit` · `spawn_failure` (the CLI itself failed)
+- **`refusal`**: the model **declined** the task (a safety/decline outcome — HTTP
+  200, `stop_reason:"refusal"` — not a crash). Detected by the `claude` adapter;
+  N/A for `codex` (no distinct refusal signal → it stays `nonzero_exit`). Kept
+  separate so an abstain-quorum can treat **declined ≠ failed**: a node that
+  *can't* answer and a node that *won't* are different signals, and the journaled
+  kind makes *why* a null happened auditable. It still abstains (resolves to
+  `null`, dropped by `filter(Boolean)`) — `refusal` is a journaled outcome, never
+  a thrown error or a silent pass.
+- **gate**: `no_json` · `schema_violation` (the node never produced valid JSON in
+  `maxRetries+1` attempts — `rawText` is journaled so you can see what it said)
+- **`internal_error`**: a bug in omw or your schema (e.g. an invalid JSON Schema
+  that won't compile) — distinct from a flaky node, so you don't misdiagnose.
+
+`omw replay .omw/<runId>.jsonl [--json]` reconstructs the tree / a stats summary
+from a journal — a read-only **fixture replay** (reading back what a run
+recorded). For *live* resume (re-running nodes whose key changed, reusing the
+cached ones), use `omw run <wf> --resume <journal>` — see Scope below.
+
+`omw validate <wf> [--json]` is a pre-flight that loads the module and lints a
+`fake` fixture for the silent-degradation traps (top-level `responses`, a string
+`match`, no rules+default) **without spawning agents** — exit 0 clean, 1 on a
+load/fixture problem. And a node that throws an `internal_error` (e.g. a JSON
+Schema that won't compile) no longer hides behind the null-contract: the run
+escalates to **exit 4** (the partial result still prints to stdout, and a
+`{"error":"internal_error_nodes","calls":[…]}` line goes to stderr), so an author
+bug reads differently from a flaky node abstaining.
+
+---
+
+## Conventions (follow these)
+
+1. **Build on the null-contract.** `agent()` returns `null`, never throws.
+   `.filter(Boolean)` after every `parallel`/`pipeline`. For votes, require a
+   quorum of *cast* (non-null) results so all-abstain can't pass.
+2. **Always pass a `schema` when you need structured data.** The gate's
+   self-repair is the one genuine differentiator — use it instead of parsing
+   prose yourself. Keep schemas tight (`required` + types).
+3. **Stay deterministic.** Don't branch the *shape* of the run on `Date.now()` /
+   `Math.random()` / wall-clock. The resume key is `(callIndex, promptHash,
+   optsHash)` (the journaled field is `call`); if a re-run's `agent()` call order shifts, every key shifts and
+   resume breaks. Vary content by index, not by randomness. (omw can't *enforce*
+   this — no sandbox — so it's a convention you keep; enforcement is v2.)
+4. **stdout is for the machine.** Return your result; use `rt.log` / `--pretty`
+   for humans. Never `console.log` to stdout from a workflow.
+5. **Ship a `fake` fixture for your example.** Export `const fake` alongside your
+   default export so `--agent fake` runs deterministically with no key. The shape:
+
+   ```ts
+   export const fake = {
+     // Each rule's `match` is a PREDICATE FUNCTION over the prompt (not a string/regex).
+     // `responses` is a cursor that advances per invocation and sticks on the last —
+     // so [invalidJSON, validJSON] models a schema self-repair, and a single
+     // { fail } models a hard failure. A FakeResponse is { text } (a raw JSON
+     // STRING the gate then extracts + validates) or { fail, stderr }.
+     rules: [
+       { match: (p) => p.includes("SCOPE"), responses: [{ text: '{"topics":["a","b"]}' }] },
+       { match: (p) => p.includes("SEARCH a"),
+         responses: [{ text: '{"oops":1}', sessionId: "sa" }, { text: '{"topic":"a","hits":3}' }] }, // self-repair
+       { match: (p) => p.includes("SEARCH b"), responses: [{ fail: "timeout" }] },                    // dropped
+     ],
+     default: { text: "{}" }, // returned when no rule matches — keep it valid so unmatched nodes don't crash
+   };
+   ```
+
+   Common mistake: a top-level `responses` array (instead of `rules`) or a string
+   `match` is silently ignored — every node then returns `default` and the demo
+   degenerates to an empty result. See `examples/deep-research/workflow.ts` for a
+   full working fixture.
+
+---
+
+## Adapters
+
+A node is a coding agent driven through its **headless prompt→result CLI**. Only
+agents that expose such a CLI can be nodes.
+
+| adapter | status | invoke | structured out | in-session follow-up |
+|---|---|---|---|---|
+| **fake** | built-in, free, deterministic | in-process fixtures | as scripted | yes (fixture) |
+| **claude** | **full** (live-verified, claude 2.1.177) | `claude -p <p> --output-format json` | parse `.result` | `--resume` |
+| **codex** | **experimental** (live-verified, codex 0.137.0) | `codex exec --json -s workspace-write` | last `agent_message` from JSONL | `exec resume` |
+| **pi** | planned | `pi --print` | stdout | — |
+| **kiro** | **not a fit** | — | — | — |
+
+> The "in-session follow-up" column is the adapter flag the **schema gate** uses to
+> re-prompt a node in the same session — *not* run-level resume. Run-level resume
+> (skipping unchanged nodes across separate runs) is **v2**; see Honest scope below.
+
+- **claude** renames its envelope onto omw's contract (`session_id→sessionId`,
+  `total_cost_usd→costUsd`, `duration_ms→durationMs`; `is_error`/non-success
+  `subtype` → `ok:false`).
+- **codex** is experimental: it has **no cost field** (tokens only, so `costUsd`
+  stays undefined), and its JSONL can include malformed lines under MCP
+  (openai/codex#15451) — omw tolerates them line-by-line and fails *actionably*
+  (surfacing the reason) rather than returning empty. Default sandbox is
+  `workspace-write`.
+- **pi** isn't wired yet (not installed locally → `--agent pi` returns exit 3
+  with an install hint). It's a planned experimental adapter.
+- **kiro is excluded on purpose**: its CLI is a VS-Code-based IDE launcher (open
+  files, diffs, extensions), with no headless prompt→result interface — so it
+  can't be an omw node. The bar for an adapter is a real headless execution CLI.
+
+Missing CLI → exit 3 with `install_hint`. Run `--agent fake` any time for the
+free path.
+
+---
+
+## Honest scope — what omw resembles, and what it doesn't
+
+omw externalizes a pattern Claude Code uses internally for dynamic workflows
+("the model authors a deterministic orchestration script on the fly"). It is a
+**faithful reconstruction of that pattern as OSS**, not a decompiled copy and not
+a first/best/moat claim. Where it lands honestly:
+
+| | who writes the script | where it runs | a node is | agent-agnostic |
+|---|---|---|---|---|
+| Bernstein, pi-builder | a human, ahead of time | external | varies | — |
+| sub-agents-skills | per-turn routing (no standing script) | in-harness | a subagent | no |
+| Claude Code Workflow | the model, on the fly | sealed sandbox | a subagent (one in-harness agent) | no (Claude only) |
+| **oh-my-workflow** | **the model, on the fly (taught by this skill)** | **external** | **a whole coding-agent CLI** | **yes (claude/codex/…)** |
+
+No single shipped project does all three of *(a) host-agent-authored on the fly +
+(b) executed externally via reusable agent CLIs + (c) agent-agnostic*. omw is the
+reference implementation of that **2-of-3 intersection** — plus the schema-gate
+self-repair loop, which is the one piece a "subprocess + for-loop" doesn't have.
+
+### Resemblance ledger (vs the CC dynamic-workflow surface)
+
+**✅ Genuinely the same idea** — model-authored plain-JS orchestration; the
+5-hook shape (`agent`/`pipeline`/`parallel`/`phase`/`log`); `null`-resolution +
+`filter(Boolean)`; schema-forced structured output; a step-by-step journal;
+resume key `(callIndex, promptHash, optsHash)` (frozen and **proven byte-stable**
+across re-runs); **live resume** via `omw run --resume <journal>` — a **per-node
+key match** (cached nodes skip the adapter, `agent_end{cached:true}`; nodes whose
+key changed re-run; verified end-to-end on `--agent fake`).
+
+> One honest altitude difference even here: a CC Workflow node is a single
+> in-harness subagent; an **omw node is a whole external coding-agent CLI**
+> subprocess. Same orchestration shape, heavier nodes.
+
+**🟡 Designed-but-scoped** —
+- *Determinism enforcement*: CC throws on `Date.now`/`Math.random`; omw treats it
+  as a **convention** (no sandbox), so live resume holds **only for workflows that
+  keep it**. A guard that *enforces* it in resume mode is v2.
+- *Resume is per-node, not dependency-aware*: it matches `(callIndex, promptHash,
+  optsHash)`, so an upstream edit invalidates a downstream node **only if** that
+  output is threaded into the downstream prompt/opts. This is deliberate — it
+  preserves **parallel/pipeline sibling cache** (independent fan-out nodes aren't
+  forced live just because an earlier sibling changed). **The trap**: an omw node
+  is a whole coding-agent CLI that works on the **filesystem**, so "node 1 writes
+  files, node 2 reads them" is the *normal* coding-agent idiom — not an exotic
+  anti-pattern — and that channel is invisible to the key. Edit node 1 → on resume
+  it re-runs and writes different files, but node 2 **hits its cache and serves a
+  summary of the old files** (silently stale). Remedies: (a) re-run fresh (drop
+  `--resume`) when an upstream's filesystem effects changed, or (b) thread a
+  content digest of the changed files into the downstream prompt so its hash moves.
+  An opt-in `--strict-resume` (prefix truncation: force every node after the first
+  key MISS live — correct cascade for *linear* workflows, but over-invalidates
+  *parallel* siblings) and a dependency-aware cascade are both **v2** candidates;
+  per-node stays the default precisely because it keeps the parallel cache.
+
+**❌ Not implemented (CC Workflow has these; omw v1 does not)** — `budget`
+(token-target loops), nested `workflow()` (running another workflow inline), a
+`meta`/`phases` declaration block, `opts.agentType` (custom subagent types),
+`opts.effort`, `run_in_background`, and `isolation: 'worktree'`. Don't write
+scripts that assume these.
+
+---
+
+## Quick reference
+
+- Module: `export default async (rt, args) => result` · optional `export const fake`.
+- Path resolves a directory to `workflow.ts` / `workflow.js` / `index.ts` / `index.js`.
+- `omw run <wf> --agent <fake|claude|codex|pi> [--args JSON] [--concurrency N] [--resume <journal.jsonl>] [--pretty]`
+- `omw replay <journal.jsonl> [--json]`
+- `omw validate <wf> [--json]` — pre-flight: load + fake-fixture lint, no agents spawned.
+- exit codes: `0` ok · `1` script/load error · `2` usage · `3` adapter missing · `4` completed but a node hit `internal_error` (author bug; result still on stdout).
+- stdout = result JSON · journal = `.omw/<runId>.jsonl` · `--pretty` tree = stderr.
+- `agent()` never throws → `filter(Boolean)`; quorum of cast votes for verify-vote.

package/src/adapters/claude.ts

@@ -0,0 +1,146 @@
+// The claude adapter: a node is a whole `claude -p` run, not a single LLM call.
+// It shells out to `claude -p <prompt> --output-format json`, parses the single
+// JSON result object, and renames claude's snake_case fields onto our AgentResult
+// contract (session_id→sessionId, total_cost_usd→costUsd, duration_ms→durationMs;
+// is_error/subtype collapse to ok:false). followUp uses `--resume <sessionId>` to
+// continue the same session for schema-gate self-repair.
+//
+// Spawn is injected so the parse/argv logic is tested without a subprocess or an
+// API call; the default spawn uses Bun.spawn and is exercised live under OMW_LIVE.
+
+import type { AgentPort, AgentResult, InvokeRequest } from "./types";
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** Map a parsed `claude -p --output-format json` payload onto AgentResult. A
+ *  non-"result" type, is_error, or a non-success subtype all collapse to a
+ *  terminal failure with the subtype + model message surfaced for the journal. */
+export function parseClaudeResult(raw: unknown): AgentResult {
+  const j = raw as Record<string, unknown> | null;
+  const durationMs = Number(j?.duration_ms) || 0;
+
+  // A safety/decline refusal (stop_reason "refusal") is a journaled DECLINE — not
+  // a crash, and not a real answer. Classify it FIRST, before the is_error/subtype
+  // envelope checks, so a decline that arrives as subtype:"success" isn't mistaken
+  // for an empty success. Carrier per the API docs is stop_reason; subtype is
+  // matched defensively. The decline category (stop_details.category) is journaled
+  // so the reason stays auditable. Not yet verified against a live CLI refusal.
+  if (j?.stop_reason === "refusal" || j?.subtype === "refusal") {
+    const detail = typeof j?.result === "string" ? j.result : "";
+    const sd = j?.stop_details as { category?: unknown } | undefined;
+    const category = typeof sd?.category === "string" ? sd.category : "";
+    return {
+      ok: false,
+      kind: "refusal",
+      stderr: `refusal${category ? `(${category})` : ""}: ${detail}`.trim(),
+      meta: { durationMs },
+    };
+  }
+
+  if (!j || j.type !== "result" || j.is_error === true || j.subtype !== "success") {
+    const subtype = (j?.subtype ?? j?.type ?? "unknown") as string;
+    const detail = typeof j?.result === "string" ? j.result : "";
+    return { ok: false, kind: "nonzero_exit", stderr: `${subtype}: ${detail}`.trim(), meta: { durationMs } };
+  }
+
+  return {
+    ok: true,
+    text: String(j.result ?? ""),
+    meta: {
+      durationMs,
+      sessionId: j.session_id as string | undefined,
+      costUsd: j.total_cost_usd as number | undefined,
+    },
+  };
+}
+
+export type ClaudeSpawnResult = { code: number; stdout: string; stderr: string; timedOut?: boolean };
+export type ClaudeSpawn = (
+  args: string[],
+  opts?: { cwd?: string; timeoutMs?: number },
+) => Promise<ClaudeSpawnResult>;
+
+export type ClaudeAdapterDeps = {
+  spawn?: ClaudeSpawn;
+  /** Binary name/path; defaults to "claude" on PATH. */
+  bin?: string;
+};
+
+/** Default spawn over Bun.spawn. Kills the child after timeoutMs and flags it so
+ *  the result maps to a `timeout` kind rather than a generic nonzero exit. */
+function defaultSpawn(bin: string): ClaudeSpawn {
+  return async (args, opts) => {
+    const proc = Bun.spawn([bin, ...args], {
+      cwd: opts?.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (opts?.timeoutMs && opts.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill();
+      }, opts.timeoutMs);
+    }
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    if (timer) clearTimeout(timer);
+    return { code, stdout, stderr, timedOut };
+  };
+}
+
+export function makeClaudeAdapter(deps: ClaudeAdapterDeps = {}): AgentPort {
+  const spawn = deps.spawn ?? defaultSpawn(deps.bin ?? "claude");
+
+  async function run(args: string[], cwd?: string, timeoutMs?: number): Promise<AgentResult> {
+    let res: ClaudeSpawnResult;
+    try {
+      res = await spawn(args, { cwd, timeoutMs });
+    } catch (e) {
+      // A throw at the spawn boundary IS an adapter failure (e.g. ENOENT).
+      return { ok: false, kind: "spawn_failure", stderr: errMsg(e), meta: { durationMs: 0 } };
+    }
+
+    if (res.timedOut) {
+      return { ok: false, kind: "timeout", stderr: res.stderr || `timed out after ${timeoutMs}ms`, meta: { durationMs: 0 } };
+    }
+    if (res.code !== 0) {
+      return {
+        ok: false,
+        kind: "nonzero_exit",
+        stderr: res.stderr || res.stdout || `claude exited ${res.code}`,
+        meta: { durationMs: 0 },
+      };
+    }
+
+    let json: unknown;
+    try {
+      json = JSON.parse(res.stdout);
+    } catch {
+      return {
+        ok: false,
+        kind: "nonzero_exit",
+        stderr: `unparseable claude output: ${res.stdout.slice(0, 200)}`,
+        meta: { durationMs: 0 },
+      };
+    }
+    return parseClaudeResult(json);
+  }
+
+  return {
+    name: "claude",
+    invoke(req: InvokeRequest): Promise<AgentResult> {
+      const args = ["-p", req.prompt, "--output-format", "json"];
+      if (req.model) args.push("--model", req.model);
+      return run(args, req.cwd, req.timeoutMs);
+    },
+    followUp(sessionId: string, prompt: string): Promise<AgentResult> {
+      const args = ["-p", prompt, "--resume", sessionId, "--output-format", "json"];
+      return run(args);
+    },
+  };
+}