@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/README.md

@@ -29,6 +29,16 @@ Adding workflow files under `.atomic/workflows/` (project scope) or `~/.atomic/a
 }
 ```
 
+Temporary-worktree setup can symlink selected main-root directories into each checkout (the default preserves `node_modules`):
+
+```json
+{
+  "worktree": {
+    "symlinkDirectories": ["node_modules", ".cache"]
+  }
+}
+```
+
 After Atomic is running, use `/workflow reload` or the workflow tool's `reload` action to rescan all workflow sources in process. Additions, edits, renames, deletions, config changes, and package-resource changes become visible immediately to list/get/inputs/help/completion/invocation surfaces. Reload requests are serialized/coalesced and publish a complete replacement registry; an in-flight workflow keeps its original definition while later calls use the new registry. Fatal refresh failures retain the prior registry, and skipped malformed or missing resources are reported with actionable diagnostics while valid siblings remain available.
 
 ### Workflow lifecycle notifications
@@ -201,7 +211,7 @@ export default workflow({
 });
 ```
 
-The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views flatten it into the parent run. In practice it should feel like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported children appear in one expanded parent graph, while implementation-owned child run ids stay hidden from top-level `/workflow status` lists. The child still has a run id internally so the graph can attach to, pause, interrupt, resume, or kill live child stages correctly. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `outputs` on `child.outputs` after those outputs pass their declared runtime type checks.
+The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views flatten it into the parent run. In practice it should feel like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported children appear in one expanded parent graph, while implementation-owned child run ids stay hidden from top-level `/workflow status` lists. The child still has a run id internally so the graph can attach to, pause, interrupt, or resume live child stages correctly. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `outputs` on `child.outputs` after those outputs pass their declared runtime type checks.
 
 For workflows intended to be called as children, declare an `outputs` entry for every non-default field a parent should rely on. `outputs` is only the schema/contract: use normal TypeScript in `run()` to gather values from any stage/task/child workflow and return those keys.
 
@@ -234,7 +244,11 @@ export default workflow({
 Builtin workflows are also callable as modules for reuse:
 
 ```typescript
-import { deepResearchCodebase, goal, openClaudeDesign, ralph } from "@bastani/workflows/builtin";
+import {
+  adversarialVerification, classifyAndAct, deepResearchCodebase,
+  fanOutAndSynthesize, generateAndFilter, goal, loopUntilDone,
+  openClaudeDesign, ralph, tournament,
+} from "@bastani/workflows/builtin";
 import goalWorkflow from "@bastani/workflows/builtin/goal";
 import openClaudeDesignWorkflow from "@bastani/workflows/builtin/open-claude-design";
 ```
@@ -297,13 +311,13 @@ Worktree semantics:
 
 - `gitWorktreeDir` must be used from inside a Git repository. Relative paths resolve from the logical invoking repository root; absolute paths are used as-is.
 - If the requested path exists, it must be an actual Git worktree/checkout root belonging to the invoking repository. The invoking checkout itself, paths nested beneath it, foreign repositories, and existing subdirectories are rejected so writes do not silently land in the main checkout.
-- If the path is missing, the parent directory is created and Git runs `git worktree add --detach <path> <baseBranch>`. `baseBranch` defaults to `HEAD` when omitted. Missing targets whose existing parent resolves through a symlink beneath the invoking checkout are rejected.
+- If the path is missing, the parent directory is created and Git runs `git worktree add --detach <path> <baseBranch>` from the canonical main repository root. `baseBranch` defaults to `HEAD` when omitted. Missing targets whose existing parent resolves through a symlink beneath the invoking checkout are rejected.
 - The default execution cwd preserves the caller's repo-relative cwd inside the worktree. For example, invoking a workflow from `repo/packages/api` with `gitWorktreeDir=../repo-wt` uses `../repo-wt/packages/api` for workflow `ctx.cwd` and stage/task execution.
 - Symlinked repo/worktree paths preserve their logical spelling in the default cwd, matching Codex-style worktree behavior.
 - An explicit absolute `cwd` inside the invoking checkout is remapped to the corresponding worktree path; an absolute `cwd` already inside the selected worktree is preserved. Relative values resolve from the worktree default cwd and cannot escape it. Foreign paths, lexical traversal, and symlink escapes fail before a session starts.
-- Runner-managed relative direct output paths follow that effective worktree cwd and cannot traverse or follow symlinks outside the selected worktree. Explicit absolute outputs and nonblank explicit `chainDir` locations remain caller-selected; blank `chainDir` values are treated as omitted.
+- Relative stage/task outputs follow the effective worktree cwd and cannot traverse or follow symlinks outside the selected worktree. Explicit absolute outputs remain caller-selected.
 
-`worktree: true` is different: it creates temporary isolated worktrees for direct task/parallel/chain execution and cleans them up afterward, including failures before the workflow callback starts. When no task `cwd` is set, temporary isolation starts from the runner invocation cwd; relative task cwd values resolve from that same invocation cwd. Relative direct outputs without a nonblank `chainDir` are persisted under distinct per-task runner-owned temporary artifact directories before cleanup; returned output artifact paths therefore remain readable, including with `outputMode: "file-only"`. Those relative paths cannot traverse or follow symlinks outside their runner-owned output root, and a pre-existing symlink or junction at the trusted artifact root is rejected. It is mutually exclusive with `gitWorktreeDir`, which is intended for named/reusable worktrees that remain available across retries and `/workflow resume`. Durable resume records the original invocation cwd and resolved reusable-worktree metadata, then replays from that original repository context rather than whichever cwd the resumed interactive session currently has. Reusable worktree setup is cached by canonical repository and target identity within a workflow run, independent of equivalent path spelling or `baseBranch`, and the selected checkout identity is revalidated before reuse. Read-only Git repository probes retry a transient timeout once, and slow Git subprocess failures include the exact command, cwd, timeout, elapsed time, exit status/signal, and spawn error details.
+`worktree: true` on an authored `ctx.task(...)` is different: it creates a branch-backed temporary checkout at `<main-root>/.atomic/worktrees/<flattened-name>` using branch `worktree-<flattened-name>` and cleans up both checkout and branch afterward, including failures before the task callback starts. `/` in generated names is flattened to `+`, and creation stays anchored at the canonical main root even when Atomic is launched from a linked worktree. The base ref is an explicit `baseBranch`, then `origin/<default-branch>` (fetched when needed), then `HEAD`. Post-creation setup copies `.atomic/settings.local.json` plus untracked `.atomic/settings.json`, shares the main repository's Husky or populated `.git/hooks` directory through `core.hooksPath`, symlinks configured `worktree.symlinkDirectories`, and copies gitignored files matched by `.worktreeinclude`; tracked checkout content is never overwritten. When no task `cwd` is set, temporary isolation starts from the runner invocation cwd; relative task cwd values resolve from that same invocation cwd. Relative task outputs are persisted under distinct per-task runner-owned temporary artifact directories before cleanup; returned output artifact paths therefore remain readable, including with `outputMode: "file-only"`. Those relative paths cannot traverse or follow symlinks outside their runner-owned output root, and a pre-existing symlink or junction at the trusted artifact root is rejected. It is mutually exclusive with `gitWorktreeDir`, which is intended for named/reusable worktrees that remain available across retries and `/workflow resume`. Durable resume records the original invocation cwd and resolved reusable-worktree metadata, then replays from that original repository context rather than whichever cwd the resumed interactive session currently has. Reusable worktree setup is cached by canonical repository and target identity within a workflow run, independent of equivalent path spelling or `baseBranch`, and the selected checkout identity is revalidated before reuse. Read-only Git repository probes retry a transient timeout once, and slow Git subprocess failures include the exact command, cwd, timeout, elapsed time, exit status/signal, and spawn error details.
 
 Worktrees provide checkout and cwd isolation, not an operating-system security sandbox. A process with permission to mutate arbitrary sibling paths can still race filesystem checks; use a container, VM, or another OS-enforced boundary for untrusted code.
 
@@ -366,16 +380,7 @@ export default workflow({
 });
 ```
 
-Direct helpers and workflow tool direct modes can set task-local fallbacks or a top-level default:
-
-```typescript
-await runParallel([
-  { name: "runtime-review", task: "Review runtime changes", model: "anthropic/claude-sonnet-4" },
-  { name: "quality-review", task: "Review quality risks", fallbackModels: ["openai/gpt-5-mini"] },
-], {
-  fallbackModels: ["github-copilot/gpt-5-mini"],
-});
-```
+Set `model` and `fallbackModels` on the authored stage/task/chain/parallel item that needs them.
 
 When pi exposes its model registry, workflow runs validate user-specified `model` / `fallbackModels` before starting model-backed work and report all unavailable or ambiguous IDs together. Bare model IDs are accepted only when they resolve uniquely or match the current provider; otherwise use `provider/model`. Fallback attempts may send the same prompt/context to a different provider, so choose fallbacks that fit your cost, privacy, and data-handling requirements.
 
@@ -536,24 +541,28 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 | `/workflow <name> --help`             | Print the workflow's input schema                        |
 | `/workflow list`                      | List all registered workflows with descriptions          |
 | `/workflow status [run-id]`           | Show active plus retained terminal/current-session runs, or details for one run |
-| `/workflow connect [run-id]`          | Attach to a workflow run overlay                         |
+| `/workflow connect [run-id]`          | Open a workflow run graph                                |
 | `/workflow attach [run-id] [stage]`   | Open the attach/chat pane for a run or stage             |
 | `/workflow pause [run-id] [stage]`    | Pause a live run or stage                                |
 | `/workflow interrupt [run-id\|--all]` | Pause active/named/all active runs so they can resume    |
-| `/workflow kill [run-id\|--all]`      | Kill in-flight workflow runs; killed runs are retained for inspection |
+| `/workflow quit [run-id\|--all]`      | Gracefully pause live workflow runs so they can resume later          |
 | `/workflow resume <run-id>`           | Resume paused work or re-open a run snapshot             |
 | `/workflow reload`                    | Reload discovered workflow resources and package-manifest entries in-process |
 | `/workflow inputs <name>`             | Print the input schema for a workflow                    |
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`). Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts.
 
-Named workflow launches always run as **background tasks** in interactive sessions. Model-launched direct `task`, `tasks`, and `chain` calls must set top-level `async: true` so the chat editor stays free; inspection and control calls are unaffected. Foreground launches are reserved for explicit user requests or technical requirements, with notice before launch. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. While the graph pane is active, vertical wheel/trackpad gestures pan vertically and horizontal gestures pan wide graphs left and right when the terminal reports them, without falling through to the main chat or terminal scrollback. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. Archived read-only stage transcripts show the same copy-mode footer/status, allowing their transcript text to be selected and copied while preserving `esc` close and `ctrl+d` graph navigation. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+Named workflow launches always run as **background tasks** in interactive sessions. Run `/workflow connect <run>` to see agents working and chat with and steer each stage. Foreground launches are reserved for explicit user requests or technical requirements, with notice before launch. Press **F2** to open the same live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. `ctrl+x` is the workflow hierarchy chord: attached stage chats show **ctrl+x return to graph**, while graph surfaces show **ctrl+x leave graph · return to main chat**. Workflow surfaces consume it before configurable editor/tool actions. Composer and prompt drafts survive leaving a stage, and pending custom questions remain pending for reattachment. `ctrl+d` and `q` are not workflow navigation controls; ordinary editor/prompt Ctrl+D behavior and printable prompt `q` remain available. Existing `esc`, `ctrl+c`, and graph `h` close/hide behavior is unchanged. While the graph pane is active, vertical wheel/trackpad gestures pan vertically and horizontal gestures pan wide graphs left and right when the terminal reports them, without falling through to the main chat or terminal scrollback. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. Archived read-only stage transcripts show the same copy-mode footer/status, allowing their transcript text to be selected and copied while preserving `esc` close and `ctrl+x` graph navigation. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
 
-Durable resume preserves both completed and active stage timing. Replayed stage/task/parallel/child checkpoints retain summaries, durations, session/model metadata, and parallel branch parentage in the graph instead of flattening fanout branches into a sequential replay chain. While an LM stage or task is active, repeated durable session checkpoints refresh its pause-adjusted accumulated duration even when the session file is unchanged. Every later `/workflow resume` starts from the latest saved baseline, so repeated process-boundary resumes keep status, graph, stored, and lifecycle durations cumulative while subtracting only pauses from the current process segment.
+Named launches return only after startup admission, while the admitted workflow body and stages remain background work. Pre-body setup failures (including invalid input-bound reusable worktrees) are returned immediately from the original tool call as structured failed results with the concrete error and allocated run id; Atomic does not first claim that the workflow started, and it removes the unadmitted run so corrected inputs can be retried immediately. Failures after admission continue to use normal background status and lifecycle notices.
 
-Durable file state, DBOS metadata/checkpoint envelopes, and JSONL discovery entries use one shared compatibility version. `/workflow resume`, startup notices, completed catalogs, and related listings expose only current-format records. Atomic permanently removes records explicitly identified as incompatible legacy v1 data from file and DBOS storage; after compatibility preparation it also purges matching restored/live snapshots, even when DBOS deletion fails, so selector fallbacks and live resume paths cannot resurrect them. Future, malformed, or unavailable formats are hidden and preserved without overwrite or broad deletion; failed DBOS cleanup stays suppressed and is retried on later discovery.
+Graceful quit is idempotent for already-paused runs and preserves unresolved `ctx.ui` prompts in DBOS. Stable author-callsite-and-composed-nested-scope reservations are created before prompting and released by exact current-format token generation after answer checkpoint, rejection, or abort. Answering while quit/paused cannot advance workflow code until explicit resume.
 
-Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `kill`, `resume`, `reload`, and `inputs`.)
+Workflow durability requires DBOS/Postgres. Atomic configures and launches DBOS lazily on the first workflow action, reuses that process-wide instance, and awaits readiness before durable execution or control. Initialization or persistence failures fail the workflow action; no alternate backend is selected. `DBOS_SYSTEM_DATABASE_URL` selects an existing database when supplied; otherwise Atomic runs DBOS against its own embedded Postgres (npm-distributed binaries, detached `pg_ctl` daemon under `~/.atomic/postgres` on port 5439, shared across sessions and never stopped by Atomic), with DBOS's `dbos-db` Docker container only as a platform fallback. Concurrent Atomic sessions safely share one database: unique per-process executor ids, owner/heartbeat metadata on running workflows, and first-writer-wins claims on contended status transitions prevent double dispatch. Running workflows never appear as resume targets in any session; stale-heartbeat (crashed) ones surface as red `crashed` rows, paused rows render yellow, failed/blocked red, completed green, and the open picker live-updates on local changes plus a bounded cross-session poll.
+
+DBOS is the only durable catalog for resume, completed inspection, deletion, and targeted lookup. Session JSONL files remain chat transcripts only. Atomic reads and writes one current format; prior local workflow state and older DBOS records are not converted or discovered.
+
+Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. The run-level `quit` action targets the selected top-level run or all live top-level runs. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `quit`, `resume`, `reload`, and `inputs`.)
 
 Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, custom prompt identity hash, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node. Arbitrary custom-widget answers cannot be supplied with `workflow send`; focus the `custom` awaiting-input node in the interactive graph instead.
 
@@ -564,14 +573,14 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "description": "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
+  "description": "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; discover with list/get/inputs, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/quit runs, and reload workflow resources. For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
-    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'stages' | 'stage' | 'transcript' | 'send' | 'pause' | 'interrupt' | 'kill' | 'resume' | 'reload'",
-    "runId": "optional run id or unique prefix; control actions default to the active run where safe; use '--all' or all:true for pause/interrupt/kill all",
+    "action": "'run' | 'list' | 'get' | 'inputs' | 'status' | 'stages' | 'stage' | 'transcript' | 'send' | 'pause' | 'interrupt' | 'quit' | 'resume' | 'reload'",
+    "runId": "optional run id or unique prefix; control actions default to the active run where safe; use '--all' or all:true for pause/interrupt/quit all",
     "stageId": "optional stage id, prefix, or name for stage-scoped actions; cannot be combined with all:true",
-    "statusFilter": "optional stages filter: pending/running/awaiting_input/paused/blocked/completed/failed/skipped/all",
+    "statusFilter": "optional filter for stages or the no-runId status run listing: pending/running/awaiting_input/paused/blocked/completed/failed/skipped/cancelled/killed/all; for the status listing, run statuses match directly and awaiting_input selects runs with a pending human prompt",
     "format": "optional agent-facing output format: text or json",
     "limit": "transcript-only explicit maximum number of recent entries; omitted with tail omitted uses the path-only default when sessionFile/transcriptPath exists",
     "tail": "transcript-only explicit last-N entry count; overrides limit for quick recent-context checks",
@@ -582,17 +591,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
     "delivery": "optional send delivery mode: auto, answer, prompt, steer, followUp, or resume; auto prioritizes answer, then resume, steer, followUp",
     "promptId": "optional pending prompt identifier for send/answer",
     "reason": "optional human-readable reload reason",
-    "all": "optional boolean for pause/interrupt/kill all; cannot be combined with stageId",
-    "task": "optional direct task object (name + prompt/task) or root task string for direct chain/parallel runs",
-    "tasks": "optional array of direct task objects (parallel direct run)",
-    "chain": "optional array of direct task objects and/or { parallel: [...] } groups (sequential direct run)",
-    "chainName": "optional label for a direct chain run",
-    "concurrency": "optional parallelism limit for direct tasks/chain",
-    "failFast": "optional fail-fast toggle for direct parallel work",
-    "async": "optional boolean to dispatch a run in the background",
-    "intercom": "optional intercom coordination options",
-    "chainDir": "optional directory for direct chain artifacts",
-    "session/task options": "per-stage overrides also accepted at the top level and on direct task items — schema, model, thinkingLevel, fallbackModels, tools, noTools, customTools, mcp, context, cwd, output, outputMode, reads, worktree, gitWorktreeDir, baseBranch, maxOutput, artifacts, and more"
+    "all": "optional boolean for pause/interrupt/quit all; cannot be combined with stageId"
   }
 }
 ```
@@ -600,7 +599,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 - **`renderCall`** — renders a compact workflow call summary in the chat scroll.
 - **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
 - **`transcript`** — path-only by default when a transcript file exists: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Default text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus a `lazyReadPrompt`, with `entries: not inlined` so transcript bodies and tool outputs stay out of model context. Passing explicit `tail` or `limit` opts into a bounded inline preview for quick context checks. If no transcript path is available, the action falls back to a bounded preview of up to 5 recent entries with a `fallbackNote`. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies only to inlined snapshot previews or no-path fallback previews; live session transcripts may not expose tool output.
-- **`send`** — answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. Follow-ups to completed or failed stages reuse retained `sessionFile` metadata when available so the conversation resumes from the archived stage transcript instead of starting empty; if no session metadata was retained, the follow-up is refused instead of silently resetting. Arbitrary `ctx.ui.custom<T>` widget prompts require the interactive workflow graph and return a clear unsupported message when targeted through `send`. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
+- **`send`** — answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. Follow-ups to eligible terminal agent stages revive an interactive **post-mortem chat** through the shared resolver: on a live-handle miss the stage's retained `sessionFile` is validated (existing, readable, context-bearing) and reopened as a detached, single-flight handle so the message is delivered as a conversational follow-up appended in place — the same path used by `/workflow attach`, restored/replayed durable snapshots, and completed-workflow inspection — without resuming, retrying, or re-dispatching workflow execution. If no valid retained session exists, the follow-up is refused (`No live handle for stage.`) instead of silently resetting or exposing a handle-less non-terminal session. Arbitrary `ctx.ui.custom<T>` widget prompts require the interactive workflow graph and return a clear unsupported message when targeted through `send`. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
 - **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
 
 ### F2 keyboard shortcut
@@ -637,7 +636,7 @@ export default workflow({
 });
 ```
 
-The `workflow` tool still supports direct one-off `task`, `tasks`, and `chain` modes for agent-initiated orchestration. Those direct modes are runtime tool inputs, not workflow definition files.
+The `workflow` tool accepts named workflow execution (`workflow` plus `inputs`), discovery, inspection, messaging, run control, and reload. Author stage graphs with `ctx.task`, `ctx.chain`, and `ctx.parallel` inside workflow definitions.
 
 For large handoffs, prefer artifact paths over prompt injection: write stage output to `output`, set `outputMode: "file-only"` when the parent only needs the path, pass paths with `reads`, and instruct downstream agents explicitly with wording like `Read the file at <path>...`. Reserve `previous`/`{previous}` for compact summaries; avoid passing full session histories, all prior stage outputs, or every review round directly into the next model prompt. In review loops, save JSON review artifacts and pass only the latest review-round artifact, with a ledger or index file linking older rounds when needed.
 
@@ -649,6 +648,45 @@ To inspect a workflow's input schema inside pi, use `/workflow inputs <name>` or
 
 ## Builtin workflows
 
+### Six composable pattern workflows
+
+The six common patterns ship as full builtins and are discoverable/runnable by name:
+
+| Workflow | Graph and use | Inputs (defaults) | Parent-consumable outputs |
+|---|---|---|---|
+| `classify-and-act` | structured classifier → deterministic action; HIL fallback for low confidence | `prompt`; `categories` (3 defaults), `confidence_threshold=0.75` | result, category/confidence, classification/action paths |
+| `fan-out-and-synthesize` | partition → bounded artifact fan-out → evidence synthesis barrier | `prompt`; `max_branches=4`, `max_concurrency=4` | result, partitions, branch/synthesis/manifest paths |
+| `adversarial-verification` | worker → fresh rubric verifiers → reducer → bounded repair | `task`; `verifier_count=3`, `max_repairs=2` | result, approval, repairs, candidate/review/verifier paths |
+| `generate-and-filter` | candidate fan-out → dedupe/filter → optional judge → shortlist | `prompt`; `num_candidates=8`, `shortlist_size=3`, `use_judge=true`, `max_concurrency=4` | result, shortlist and candidate/filter/judge/final/manifest paths |
+| `tournament` | independent attempts → order-balanced pairwise judges → bracket reducer | `prompt`; `num_attempts=4`, `max_concurrency=4` | result, winner, attempt/judge/bracket paths |
+| `loop-until-done` | durable ledger → iteration/evaluator loop → complete or inspectable exhaustion | `prompt`; `max_iterations=5` | result/status, ledger, iteration/evaluation paths, remaining work |
+
+All six are exported from `@bastani/workflows/builtin` as definitions (`classifyAndAct`, `fanOutAndSynthesize`, `adversarialVerification`, `generateAndFilter`, `tournament`, and `loopUntilDone`). Import and nest them through `ctx.workflow(definition, { inputs, stageName })`; nested calls respect `maxDepth`. Prefer composition over copying their prompts or graphs: children contribute their stages, dedicated prompts, gates, artifacts, HIL nodes, and declared outputs to the expanded parent graph.
+
+A migration parent can nest all three definitions: fan out the fix pass, independently verify the produced patch set, then run a bounded evidence loop until the repository tests pass:
+
+```ts
+import { adversarialVerification, fanOutAndSynthesize, loopUntilDone } from "@bastani/workflows/builtin";
+
+const fixes = await ctx.workflow(fanOutAndSynthesize, {
+  inputs: { prompt: "Fix every migration call site", max_branches: 6 },
+  stageName: "migration fixes",
+});
+const verification = await ctx.workflow(adversarialVerification, {
+  inputs: { task: `Verify every patch listed by ${fixes.outputs.manifest_path}` },
+  stageName: "verify migration patches",
+});
+const convergence = await ctx.workflow(loopUntilDone, {
+  inputs: {
+    prompt: `Run the migration test suite and repair remaining failures. Start from ${fixes.outputs.manifest_path}; respect the verification decision at ${verification.outputs.review_report_path}.`,
+    max_iterations: 5,
+  },
+  stageName: "loop while migration tests fail",
+});
+```
+
+The parent can consume `fixes.outputs`, `verification.outputs`, and `convergence.outputs` directly, and can repeat the verification child per patch when its own typed input lists individual patch artifacts.
+
 ### `deep-research-codebase`
 
 Scout + research-history chain → two parallel specialist waves → aggregator. Ideal for deep investigation of a codebase topic across locator, pattern, analyzer, and ecosystem angles.

package/dist/builtin/workflows/ambient.d.ts

@@ -15,16 +15,41 @@ declare module "@bastani/workflows/builtin" {
 	export * from "@bastani/atomic/workflows/builtin";
 }
 
+declare module "@bastani/workflows/builtin/adversarial-verification" {
+	export * from "@bastani/atomic/workflows/builtin/adversarial-verification";
+	export { default } from "@bastani/atomic/workflows/builtin/adversarial-verification";
+}
+
+declare module "@bastani/workflows/builtin/classify-and-act" {
+	export * from "@bastani/atomic/workflows/builtin/classify-and-act";
+	export { default } from "@bastani/atomic/workflows/builtin/classify-and-act";
+}
+
 declare module "@bastani/workflows/builtin/deep-research-codebase" {
 	export * from "@bastani/atomic/workflows/builtin/deep-research-codebase";
 	export { default } from "@bastani/atomic/workflows/builtin/deep-research-codebase";
 }
 
+declare module "@bastani/workflows/builtin/fan-out-and-synthesize" {
+	export * from "@bastani/atomic/workflows/builtin/fan-out-and-synthesize";
+	export { default } from "@bastani/atomic/workflows/builtin/fan-out-and-synthesize";
+}
+
+declare module "@bastani/workflows/builtin/generate-and-filter" {
+	export * from "@bastani/atomic/workflows/builtin/generate-and-filter";
+	export { default } from "@bastani/atomic/workflows/builtin/generate-and-filter";
+}
+
 declare module "@bastani/workflows/builtin/goal" {
 	export * from "@bastani/atomic/workflows/builtin/goal";
 	export { default } from "@bastani/atomic/workflows/builtin/goal";
 }
 
+declare module "@bastani/workflows/builtin/loop-until-done" {
+	export * from "@bastani/atomic/workflows/builtin/loop-until-done";
+	export { default } from "@bastani/atomic/workflows/builtin/loop-until-done";
+}
+
 declare module "@bastani/workflows/builtin/open-claude-design" {
 	export * from "@bastani/atomic/workflows/builtin/open-claude-design";
 	export { default } from "@bastani/atomic/workflows/builtin/open-claude-design";
@@ -34,3 +59,8 @@ declare module "@bastani/workflows/builtin/ralph" {
 	export * from "@bastani/atomic/workflows/builtin/ralph";
 	export { default } from "@bastani/atomic/workflows/builtin/ralph";
 }
+
+declare module "@bastani/workflows/builtin/tournament" {
+	export * from "@bastani/atomic/workflows/builtin/tournament";
+	export { default } from "@bastani/atomic/workflows/builtin/tournament";
+}

package/dist/builtin/workflows/builtin/adversarial-verification-prompts.ts

@@ -0,0 +1,15 @@
+export function renderWorkerPrompt(task: string): string {
+  return `<role>\nYou produce a candidate solution for independent verification.\n</role>\n\n<objective>\n${task}\n</objective>\n\n<requirements>\nComplete the task, preserve concrete evidence, and state every validation performed. Do not claim success without observable support.\n</requirements>\n\n<output_format>\nA self-contained candidate with actions taken, evidence, validation, and remaining risks.\n</output_format>`;
+}
+
+export function renderVerifierPrompt(task: string, candidatePath: string, rubricPath: string): string {
+  return `<role>\nYou are an independent adversarial verifier. Find blockers; do not rewrite the candidate.\n</role>\n\n<objective>\nVerify the candidate against the task and rubric. Task: ${task}\n</objective>\n\n<artifacts>\nRead the complete candidate at ${candidatePath} and rubric at ${rubricPath}.\n</artifacts>\n\n<requirements>\nTest important claims where practical. A pass requires concrete evidence for every rubric item. Report precise blocking findings; absence of evidence is not evidence of correctness.\n</requirements>\n\n<output_format>\nCall structured_output with verdict (pass or fail), evidence, and blocking_findings.\n</output_format>`;
+}
+
+export function renderReducerPrompt(task: string, candidatePath: string, verifierPaths: readonly string[], repairsCompleted: number, maxRepairs: number): string {
+  return `<role>\nYou reduce independent verification reports into one deterministic next action.\n</role>\n\n<objective>\nDecide whether the candidate for ${task} is accepted, rejected, or needs repair.\n</objective>\n\n<artifacts>\nCandidate: ${candidatePath}\nVerifier reports: ${verifierPaths.join(", ")}\n</artifacts>\n\n<decision_rules>\nAccept only when all material rubric requirements have pass evidence. Request repair when findings are actionable and repair budget remains (${repairsCompleted}/${maxRepairs}). Reject when evidence proves the candidate cannot satisfy the task or the repair budget is exhausted. Preserve unresolved blockers verbatim.\n</decision_rules>\n\n<output_format>\nCall structured_output with decision (accept, reject, or repair), rationale, and remaining_work.\n</output_format>`;
+}
+
+export function renderRepairPrompt(task: string, candidatePath: string, reviewPath: string): string {
+  return `<role>\nYou repair a candidate using independent blocking findings.\n</role>\n\n<objective>\nRepair the candidate for: ${task}\n</objective>\n\n<artifacts>\nRead the current candidate at ${candidatePath} and reducer report at ${reviewPath}.\n</artifacts>\n\n<requirements>\nAddress every actionable blocker, rerun relevant validation, and retain valid prior work. Do not dismiss a finding without contrary evidence.\n</requirements>\n\n<output_format>\nA complete replacement candidate with repair summary, evidence, validation, and remaining risks.\n</output_format>`;
+}

package/dist/builtin/workflows/builtin/adversarial-verification-runner.ts

@@ -0,0 +1,93 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type, type Static } from "typebox";
+import type { WorkflowRunContext, WorkflowSerializableValue } from "../src/shared/types.js";
+import { renderReducerPrompt, renderRepairPrompt, renderVerifierPrompt, renderWorkerPrompt } from "./adversarial-verification-prompts.js";
+import { stableArtifactRoot } from "./pattern-artifact-root.js";
+
+const verifierSchema = Type.Object({
+  verdict: Type.Union([Type.Literal("pass"), Type.Literal("fail")]),
+  evidence: Type.Array(Type.String()),
+  blocking_findings: Type.Array(Type.String()),
+}, { additionalProperties: false });
+const reducerSchema = Type.Object({
+  decision: Type.Union([Type.Literal("accept"), Type.Literal("reject"), Type.Literal("repair")]),
+  rationale: Type.String(),
+  remaining_work: Type.Array(Type.String()),
+}, { additionalProperties: false });
+
+type VerifierDecision = Static<typeof verifierSchema>;
+type ReducerDecision = Static<typeof reducerSchema>;
+type Inputs = { readonly task: string; readonly verifier_count: number; readonly max_repairs: number } & Record<string, WorkflowSerializableValue>;
+export type AdversarialVerificationResult = {
+  readonly result: string;
+  readonly approved: boolean;
+  readonly repairs_completed: number;
+  readonly candidate_path: string;
+  readonly review_report_path: string;
+  readonly verifier_artifact_paths: string[];
+  readonly artifact_dir: string;
+  readonly remaining_work: string[];
+};
+
+function structured<T extends WorkflowSerializableValue>(value: WorkflowSerializableValue | undefined, guard: (candidate: WorkflowSerializableValue) => candidate is T): T | undefined {
+  return value !== undefined && guard(value) ? value : undefined;
+}
+function isRecord(value: WorkflowSerializableValue): value is Record<string, WorkflowSerializableValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isVerifier(value: WorkflowSerializableValue): value is VerifierDecision {
+  return isRecord(value) && (value.verdict === "pass" || value.verdict === "fail") && Array.isArray(value.evidence) && value.evidence.every((item) => typeof item === "string") && Array.isArray(value.blocking_findings) && value.blocking_findings.every((item) => typeof item === "string");
+}
+function isReducer(value: WorkflowSerializableValue): value is ReducerDecision {
+  return isRecord(value) && (value.decision === "accept" || value.decision === "reject" || value.decision === "repair") && typeof value.rationale === "string" && Array.isArray(value.remaining_work) && value.remaining_work.every((item) => typeof item === "string");
+}
+
+export async function runAdversarialVerification(ctx: WorkflowRunContext<Inputs>): Promise<AdversarialVerificationResult> {
+  const root = await stableArtifactRoot(ctx, "adversarial-verification");
+  const rubricPath = join(root, "rubric.md");
+  const candidatePath = join(root, "candidate.md");
+  await writeFile(rubricPath, ["# Verification rubric", "- The candidate satisfies the literal task.", "- Important claims cite observable evidence.", "- Relevant validation is executed and reported.", "- No blocking correctness, safety, or completeness gap remains."].join("\n"));
+  await ctx.task("worker", { prompt: renderWorkerPrompt(ctx.inputs.task), context: "fresh", output: candidatePath, outputMode: "file-only" });
+
+  let repairsCompleted = 0;
+  let reviewReportPath!: string;
+  let verifierArtifactPaths: string[] = [];
+  let decision: ReducerDecision = { decision: "reject", rationale: "No valid reducer decision was produced.", remaining_work: ["Reducer did not return a valid structured decision."] };
+  for (;;) {
+    verifierArtifactPaths = Array.from({ length: ctx.inputs.verifier_count }, (_, index) => join(root, `verification-${repairsCompleted}-${index + 1}.json`));
+    const reports = await ctx.parallel(verifierArtifactPaths.map((path, index) => ({
+      name: `verifier-${repairsCompleted}-${index + 1}`,
+      prompt: renderVerifierPrompt(ctx.inputs.task, candidatePath, rubricPath),
+      context: "fresh" as const,
+      reads: [candidatePath, rubricPath],
+      schema: verifierSchema,
+      output: path,
+      outputMode: "file-only" as const,
+    })), { concurrency: Math.min(ctx.inputs.verifier_count, 4), failFast: false });
+    const validReports = reports.map((report) => structured(report.structured, isVerifier)).filter((report): report is VerifierDecision => report !== undefined);
+    const allVerifiersPassed = validReports.length === ctx.inputs.verifier_count && validReports.every((report) => report.verdict === "pass");
+    await writeFile(join(root, `verification-summary-${repairsCompleted}.json`), JSON.stringify(validReports, null, 2));
+    reviewReportPath = join(root, `review-${repairsCompleted}.json`);
+    const reduced = await ctx.task(`reducer-${repairsCompleted}`, {
+      prompt: renderReducerPrompt(ctx.inputs.task, candidatePath, verifierArtifactPaths, repairsCompleted, ctx.inputs.max_repairs),
+      context: "fresh", reads: [candidatePath, rubricPath, ...verifierArtifactPaths], schema: reducerSchema,
+      output: reviewReportPath, outputMode: "file-only",
+    });
+    decision = structured(reduced.structured, isReducer) ?? decision;
+    if (decision.decision === "accept" && !allVerifiersPassed) {
+      const remaining = validReports.flatMap((report) => report.blocking_findings);
+      decision = repairsCompleted < ctx.inputs.max_repairs
+        ? { decision: "repair", rationale: "Independent verification did not unanimously pass.", remaining_work: remaining }
+        : { decision: "reject", rationale: "Independent verification did not pass before the repair bound was exhausted.", remaining_work: remaining };
+    }
+    if (decision.decision === "repair" && repairsCompleted >= ctx.inputs.max_repairs) {
+      decision = { ...decision, decision: "reject", rationale: `${decision.rationale} Repair bound exhausted.` };
+    }
+    if (decision.decision !== "repair") break;
+    repairsCompleted += 1;
+    await ctx.task(`repair-${repairsCompleted}`, { prompt: renderRepairPrompt(ctx.inputs.task, candidatePath, reviewReportPath), context: "fresh", reads: [candidatePath, reviewReportPath], output: candidatePath, outputMode: "file-only" });
+  }
+  const approved = decision.decision === "accept";
+  return { result: decision.rationale, approved, repairs_completed: repairsCompleted, candidate_path: candidatePath, review_report_path: reviewReportPath, verifier_artifact_paths: verifierArtifactPaths, artifact_dir: root, remaining_work: approved ? [] : decision.remaining_work };
+}

package/dist/builtin/workflows/builtin/adversarial-verification.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+export type AdversarialVerificationInputs = WorkflowInputValues & { readonly task: string; readonly verifier_count: number; readonly max_repairs: number };
+export type AdversarialVerificationRunInputs = WorkflowInputValues & { readonly task: string; readonly verifier_count?: number; readonly max_repairs?: number };
+export type AdversarialVerificationOutputs = WorkflowOutputValues & {
+  readonly result: string; readonly approved: boolean; readonly repairs_completed: number;
+  readonly candidate_path: string; readonly review_report_path: string;
+  readonly verifier_artifact_paths: string[]; readonly artifact_dir: string; readonly remaining_work: string[];
+};
+export type AdversarialVerificationDefinition = WorkflowDefinition<AdversarialVerificationInputs, AdversarialVerificationOutputs, AdversarialVerificationRunInputs>;
+declare const workflow: AdversarialVerificationDefinition;
+export default workflow;

package/dist/builtin/workflows/builtin/adversarial-verification.ts

@@ -0,0 +1,24 @@
+import { Type } from "typebox";
+import { workflow } from "../src/authoring/workflow.js";
+import { runAdversarialVerification } from "./adversarial-verification-runner.js";
+
+export default workflow({
+  name: "adversarial-verification",
+  description: "Produce a candidate, challenge it with fresh-context rubric-based verifiers, and reduce their evidence through a bounded repair loop.",
+  inputs: {
+    task: Type.String({ description: "Task whose candidate result must be independently verified." }),
+    verifier_count: Type.Integer({ minimum: 1, maximum: 5, default: 3, description: "Number of independent verifiers per review round." }),
+    max_repairs: Type.Integer({ minimum: 0, maximum: 5, default: 2, description: "Maximum candidate repair rounds before rejection." }),
+  },
+  outputs: {
+    result: Type.String({ description: "Final reducer rationale." }),
+    approved: Type.Boolean({ description: "Whether verification accepted the candidate." }),
+    repairs_completed: Type.Integer({ description: "Number of repair rounds performed." }),
+    candidate_path: Type.String({ description: "Path to the final candidate artifact." }),
+    review_report_path: Type.String({ description: "Path to the final reducer report." }),
+    verifier_artifact_paths: Type.Array(Type.String(), { description: "Paths to final-round verifier reports." }),
+    artifact_dir: Type.String({ description: "Directory containing run artifacts." }),
+    remaining_work: Type.Array(Type.String(), { description: "Unresolved blocking findings when not approved." }),
+  },
+  run: runAdversarialVerification,
+});

package/dist/builtin/workflows/builtin/classify-and-act-prompts.ts

@@ -0,0 +1,11 @@
+export function classifierPrompt(prompt: string, categories: readonly string[]): string {
+  return `<role>\nYou route a task to exactly one declared action category.\n</role>\n\n<objective>\nClassify this task: ${prompt}\n</objective>\n\n<categories>\n${categories.map((category) => `- ${category}`).join("\n")}\n</categories>\n\n<requirements>\nChoose a category verbatim from the list. Base confidence on concrete wording in the task. Use low confidence when the task is ambiguous or spans categories. Provide a concise evidence-based rationale. Return only the structured result requested by the schema.\n</requirements>`;
+}
+
+export function actionPrompt(input: {
+  readonly prompt: string;
+  readonly category: string;
+  readonly classificationPath: string;
+}): string {
+  return `<role>\nYou are the isolated action agent for category "${input.category}".\n</role>\n\n<objective>\n${input.prompt}\n</objective>\n\n<evidence>\nRead the classification artifact at ${input.classificationPath}. Use only relevant evidence available to this stage; do not assume access to classifier conversation context.\n</evidence>\n\n<success_criteria>\nComplete the requested action for this category, distinguish verified facts from assumptions, and report concrete evidence, validation, and remaining risks.\n</success_criteria>\n\n<output_format>\nMarkdown with Outcome, Evidence, Validation, and Remaining risks headings.\n</output_format>`;
+}

package/dist/builtin/workflows/builtin/classify-and-act-runner.ts

@@ -0,0 +1,110 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "typebox";
+import type { WorkflowRunContext, WorkflowSerializableValue } from "../src/shared/types.js";
+import { actionPrompt, classifierPrompt } from "./classify-and-act-prompts.js";
+import { stableArtifactRoot } from "./pattern-artifact-root.js";
+
+export const classificationSchema = Type.Object({
+  category: Type.String({ description: "One category copied verbatim from the supplied list." }),
+  confidence: Type.Number({ minimum: 0, maximum: 1 }),
+  rationale: Type.String(),
+}, { additionalProperties: false });
+
+type Inputs = {
+  readonly prompt: string;
+  readonly categories: readonly string[];
+  readonly confidence_threshold: number;
+} & Record<string, WorkflowSerializableValue>;
+
+export type ClassifyAndActResult = {
+  readonly result: string;
+  readonly category: string;
+  readonly confidence: number;
+  readonly action: string;
+  readonly classification_path: string;
+  readonly action_path: string;
+  readonly artifact_dir: string;
+};
+
+function safeName(value: string): string {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return normalized || "fallback";
+}
+function actionTools(category: string): readonly string[] {
+  const normalized = category.toLowerCase();
+  if (normalized.includes("implement") || normalized.includes("fix") || normalized.includes("code")) {
+    return ["read", "edit", "write", "bash"];
+  }
+  if (normalized.includes("research")) return ["read", "web_search", "fetch_content"];
+  return ["read"];
+}
+
+
+async function artifactText(path: string, fallback: string): Promise<string> {
+  try { return await readFile(path, "utf8"); } catch { return fallback; }
+}
+
+/**
+ * Resolve a low-confidence or unlisted classification. Interactive runs ask the
+ * user; headless/non-interactive runs (where ctx.ui rejects) deterministically
+ * fall back to the exact proposed category when it is listed, else the first
+ * configured category, so the workflow still produces its declared outputs.
+ */
+async function resolveFallbackCategory(
+  ctx: WorkflowRunContext<Inputs>,
+  exactCategory: string | undefined,
+): Promise<{ category: string; fallbackMode: "interactive_select" | "deterministic" }> {
+  try {
+    const category = await ctx.ui.select("Classification is uncertain. Choose the action category.", ctx.inputs.categories);
+    return { category, fallbackMode: "interactive_select" };
+  } catch {
+    return { category: exactCategory ?? ctx.inputs.categories[0]!, fallbackMode: "deterministic" };
+  }
+}
+
+export async function runClassifyAndAct(ctx: WorkflowRunContext<Inputs>): Promise<ClassifyAndActResult> {
+  const artifactDir = await stableArtifactRoot(ctx, "classify-and-act");
+  const classified = await ctx.task("classifier", {
+    prompt: classifierPrompt(ctx.inputs.prompt, ctx.inputs.categories),
+    schema: classificationSchema,
+    context: "fresh",
+    tools: [],
+  });
+  const value = classified.structured;
+  const proposedCategory = typeof value === "object" && value !== null && "category" in value
+    ? String(value.category) : "";
+  const confidenceValue = typeof value === "object" && value !== null && "confidence" in value
+    ? value.confidence : 0;
+  const confidence = typeof confidenceValue === "number" && Number.isFinite(confidenceValue)
+    ? Math.max(0, Math.min(1, confidenceValue)) : 0;
+  const rationale = typeof value === "object" && value !== null && "rationale" in value
+    ? String(value.rationale) : "Classifier did not provide a usable structured rationale.";
+  const exactCategory = ctx.inputs.categories.find((category) => category === proposedCategory);
+  const needsFallback = exactCategory === undefined || confidence < ctx.inputs.confidence_threshold;
+  const fallback = needsFallback ? await resolveFallbackCategory(ctx, exactCategory) : undefined;
+  const category = fallback?.category ?? exactCategory!;
+
+  const classificationPath = join(artifactDir, "classification.json");
+  await writeFile(classificationPath, JSON.stringify({
+    proposed_category: proposedCategory,
+    selected_category: category,
+    confidence,
+    threshold: ctx.inputs.confidence_threshold,
+    rationale,
+    fallback_used: needsFallback,
+    fallback_mode: fallback?.fallbackMode ?? "none",
+  }, null, 2));
+
+  const actionPath = join(artifactDir, `action-${safeName(category)}.md`);
+  const action = await ctx.task(`action-${safeName(category)}`, {
+    tools: actionTools(category),
+    prompt: actionPrompt({ prompt: ctx.inputs.prompt, category, classificationPath }),
+    context: "fresh",
+    reads: [classificationPath],
+    output: actionPath,
+    outputMode: "file-only",
+  });
+  const result = await artifactText(actionPath, action.text);
+  return { result, category, confidence, action: action.stageName, classification_path: classificationPath, action_path: actionPath, artifact_dir: artifactDir };
+}

package/dist/builtin/workflows/builtin/classify-and-act.d.ts

@@ -0,0 +1,24 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type ClassifyAndActWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly categories: string[];
+  readonly confidence_threshold: number;
+};
+export type ClassifyAndActWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly categories?: string[];
+  readonly confidence_threshold?: number;
+};
+export type ClassifyAndActWorkflowOutputs = WorkflowOutputValues & {
+  readonly result: string;
+  readonly category: string;
+  readonly confidence: number;
+  readonly action: string;
+  readonly classification_path: string;
+  readonly action_path: string;
+  readonly artifact_dir: string;
+};
+export type ClassifyAndActWorkflowDefinition = WorkflowDefinition<ClassifyAndActWorkflowInputs, ClassifyAndActWorkflowOutputs, ClassifyAndActWorkflowRunInputs>;
+declare const definition: ClassifyAndActWorkflowDefinition;
+export default definition;