@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,133 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.11-alpha.9] - 2026-08-01
+
+### Added
+
+- Added per-node cancellation to `ctx.tool`. Every callback now receives a `WorkflowToolContext` (`{ signal }`) derived from a per-invocation `AbortController` combined with the run signal, so a run abort still cascades to every node while one node can be aborted alone. All retries of a call share that one signal, and existing zero-argument callbacks keep compiling and running unchanged. `WorkflowToolContext` is exported from the authoring surface ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Added tool nodes as addressable abort targets for `workflow({ action: "quit"|"interrupt", runId, stageId })`. A node resolves by expanded id, local `tool:<argsHash>` id, or tool name with the same exact-then-unique precedence and ambiguity diagnostics stages get. Aborting one node marks it `cancelled` and leaves sibling stages and tool nodes running; tool nodes stay non-attachable, so this adds abort, not chat. The result reports the node outcome and the run separately — `status: "cancelled"` with the observed `workflowStatus` — instead of claiming the run was paused. `pause` on a tool node is now rejected explicitly instead of resolving to nothing ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+
+### Changed
+
+- Declared `handlesCtrlC` on every workflow surface mounted through `ctx.ui.custom()` — the graph pane (which hosts stage chat, prompt cards, and the inline form) and the inputs picker. In isolated interactive sessions the terminal host now closes an undeclared remote component on the first Ctrl+C, so the declaration is what keeps `ctrl+c Skip`, `ctrl+c Close`, and picker cancel working.
+- Documented deterministic delivery timing for workflow stage messages. `steer` (and `auto` against a streaming stage) is consumed after the current assistant response finishes its whole tool batch and before the next model request — never between two tool calls of the same response; `followUp` is consumed only when the agent would otherwise stop. Each queue is FIFO in admission order, and steering keeps priority over an earlier-submitted follow-up, so there is no global FIFO across the two queues ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+
+### Fixed
+
+- Fixed `open-claude-design` converting a failed `user-feedback-*` stage into design approval (the [#1499](https://github.com/bastani-inc/atomic/issues/1499) catch-then-approve path). A rejected feedback stage — provider errors, model-fallback exhaustion, broken session forks — now propagates and fails the run instead of silently setting `approved_for_export` and exporting an unreviewed design. Resolved results are unchanged: a stage that runs and reports no meaningful notes, including degraded manual/headless display paths, still legitimately reads as approval, and browser/tooling trouble continues to resolve gracefully rather than reject (playwright-cli auto-install, the early browser exit, and the stage's degradation contract are unaffected) ([#2123](https://github.com/bastani-inc/atomic/issues/2123)).
+- Fixed `open-claude-design` embedding unbounded research context inline in single stage prompts, the same single-message overflow class as the [#1499](https://github.com/bastani-inc/atomic/issues/1499) `413 request_too_large`. The composed project design context now persists to `<artifact_dir>/design-context.md` and the curated references brief always persists to `<artifact_dir>/references.md` (with the no-references fallback when discovery is skipped); `reference-discovery` reads the design context, and the generate and exporter stages read both files via `reads` with explicit read-the-file instructions instead of inline `design_system`/`reference_inspiration` embeds. The joined research results are no longer injected as `previous` payloads into `generate-1` or `reference-discovery`. Because the files are required stage inputs, a failed write no longer passes silently: the run exits `blocked` through `ctx.exit` with the artifact paths surfaced (or propagates the error when `ctx.exit` is unavailable) instead of dispatching stages against nonexistent context. Deliberately small inline payloads are unchanged: verbatim-threaded user annotations (the #1464 guardrail) and the word-capped prior design summary ([#2121](https://github.com/bastani-inc/atomic/issues/2121)).
+- Fixed `open-claude-design` blocking on browser live review while reporting `running`, leaving the user with no input affordance. Each refinement round now raises a deterministic run-level `ctx.ui` prompt before its `user-feedback-*` stage starts, so the needs-attention badge fires and the prompt names the preview path and `file://` URL; choosing the skip option accepts the current design and proceeds to export. Only the executor's unavailable-UI rejection (headless mode or a missing UI adapter) degrades to running the review directly; any other gate failure — interruption, a failed durable checkpoint — propagates and stops the run. The feedback-stage prompt additionally instructs the agent to print the live `http://` review URL before starting any long-poll wait, so the URL is visible at the top of the stage output when attaching mid-run ([#2060](https://github.com/bastani-inc/atomic/issues/2060)).
+- Hardened the bundled `impeccable` live-mode scripts against four CodeQL security findings, preserving behavior for all valid inputs: live-edit session ids now fall back to `crypto.getRandomValues` instead of `Math.random` outside secure contexts (`js/insecure-randomness`); the live server clamps the client-supplied poll timeout to the 10-minute default ceiling (`js/resource-exhaustion`); `live-accept` escapes the `--variant` value before splicing it into a `RegExp` (`js/regex-injection`); and manual-edit evidence decodes `&amp;` last so crafted input cannot be double-unescaped (`js/double-escaping`).
+- Fixed worktree setup hooks being reported as failed when they never read their stdin. The hook's JSON input is written to its stdin, but nothing requires a hook to consume it; a hook that exited before that write flushed made `spawnSync` report `EPIPE` and the whole worktree creation was torn down, even though the hook had run to completion and its stdout was captured in full. The child's exit status and output are now authoritative, so only a spawn that never produced a status is treated as a hook failure. Timeouts and every other spawn error stay fatal as before. This race was lost far more often on loaded machines, making it look intermittent.
+- Fixed graceful quit ignoring in-flight `ctx.tool` calls. A run whose only in-flight work was a durable tool node reported `No controllable stages on run <id>; the run remains active` and left the callback running with no way to stop it. Quit now counts running tool nodes as controllable work; after stage pauses acknowledge it closes the root-shared tool-admission boundary, so a call admitted during that wait is still included and none can start afterwards — not even while the durable write is in flight. It then aborts the complete root/nested set, waits a bounded interval for settlement, and only then records the durable paused/resumable transition, so quit is again an exact durability boundary rather than a pause declared while a callback is still mutating the world. A call attempted after the close is refused with the graceful-quit signal and never runs. A callback that ignores its signal is abandoned instead of pinning quit, and the result reports cancelled and abandoned calls by owning `{runId, nodeId}` identity, so two nested children sharing one local node id stay distinguishable ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed resume after quitting an unfinished `ctx.tool` call. A cancelled call now writes no replayable checkpoint and no `return_failure` outcome, so a cancellation can never replay as data; under `failureMode: "return"` it keeps exactly one inspection-only `tool-failure:` record, which stays out of the replay cache. Resume recomputes the same ordinal and `argsHash` and re-executes exactly that callback at the same `tool:<argsHash>` node, while completed sibling tools still replay from cache. A late value returned by an abandoned callback is discarded before persistence ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed a quit-time hole where workflow code that caught the tool cancellation could still publish a completed run over quit's paused record: the executor now suspends whenever its own tool work was aborted or refused by a whole-run quit, whichever path the author's code takes afterwards. A catch may clean up, but it is not an opt-out; targeted node abort remains the way to abort one call and keep a run going ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed resume adopting the stale executor after a callback was abandoned. Quit now detaches that background job, so resume relaunches a fresh executor under the same workflow id and actually re-runs the unfinished call instead of flipping the run to running with nothing driving it. Job and cancellation cleanup are identity-conditional and tool-node store writes are generation-owned, so a late zombie callback can neither evict the replacement's registrations nor mutate its graph node, and registering a second job for one live run id is now a loud error instead of silent double dispatch ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed a quit whose durable paused transition failed or was refused leaving the run reported as running with nothing running it. Aborting an in-flight `ctx.tool` call commits its executor to suspending, so quit now records the local pause whatever the durable write does; only the resumable promise follows the durable outcome, and the reported error names the durable failure and what it left behind instead of just failing. The run stays controllable, so a retried `/workflow quit` re-attempts the transition and upgrades the pause to resumable — previously the tool handles were already gone, so the retry answered `No controllable stages on run <id>` and the run could never be quit, resumed, or ended ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed a typed message in an attached workflow stage chat being demoted to a follow-up. When the chat read the stage as idle while workflow message admission still owned the retiring turn, Enter fell through to the unspecified-delivery default and landed at the end of the turn instead of at the next steering boundary, so mid-run correction did not work. Typed Enter now names steering explicitly, matching normal session steering. The choice is scoped to one submission — it travels with the submitting key through the chat host — so a slow in-flight Ctrl+F cannot make a later Enter a follow-up. Ctrl+F still queues a follow-up, a genuinely idle stage still starts a fresh turn, and the authored `stage.sendUserMessage()` default is unchanged ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed queued steering and follow-up rows disappearing when you left a stage. The queue lives on the stage session, but its display lived in the chat pane that detach destroys, so reattaching showed nothing even though the messages were still queued. The stage handle now keeps its own projection of the session's `queue_update` snapshots for its whole lifetime, and reattaching rehydrates the pending rows from it. Because the projection is fed by the events rather than by a concrete Atomic `AgentSession`, a stage backed by a custom `AgentSessionAdapter` keeps its rows too ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed a queued stage message being invisible from the workflow graph. A stage node with pending queued messages now shows a `✉ N queued` badge read from that same handle projection, so a message queued before detaching stays visible without reattaching. The badge claims the node's dim metadata row, or the redundant `waiting for response` row on an awaiting-input node so its `↵ enter to respond` hint survives. Nested child stages resolve to their real run and stage identity, tool nodes are never asked, card geometry is unchanged, and no queue state enters a store snapshot ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed a stage session that arrives already holding queued messages showing an empty queue. A session announces its queue by event, so a queue that exists before this stage's listeners are bound to that session was announced to nobody: a retiring stage session hands its pending messages to the session replacing it, and a retained session reopened for post-mortem chat is restored with whatever it was holding. Both published that queue while the handle's projection was attached to nothing, so the badge read zero and a reattached chat redrew no rows even though the messages were still pending. Attaching a session now replays the one snapshot its listeners missed, read from the session itself; every later change still arrives as an ordinary `queue_update`, and a runtime that does not expose its queues is unaffected ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed Ctrl+F losing its follow-up intent on a stage handle that predates the delivery-aware send. The compatibility path submitted the message as an ordinary prompt, so a follow-up typed while the stage streamed a retiring turn was admitted with prompt delivery instead of waiting in the follow-up queue. Ctrl+F now reaches the follow-up queue exactly while the stage streams, and still starts a turn on a genuinely idle stage — matching what the delivery-aware path does, rather than parking text no turn would consume ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+
+## [0.9.11-alpha.6] - 2026-07-28
+
+### Added
+
+- Added opt-in `ctx.tool(..., { failureMode: "return" })` outcomes for checks that may fail during repair flows. Exhausted callback failures now preserve bounded, best-effort redacted `exitCode`, `stdout`, and `stderr` as typed durable data; replay returns the same outcome without rerunning the callback; failed tool nodes remain truthful while explicit downstream repair and bounded reruns continue; and default failures, cancellation, admission errors, and storage faults still throw ([#1993](https://github.com/bastani-inc/atomic/issues/1993)).
+- Re-added the built-in Goal and Ralph workflows, including their typed composition exports, command metadata, focused tests, and user-facing docs.
+- Added a run-contract discipline to every builtin workflow. Only the user may change a run's contract: mid-run steering, follow-ups, and resume text are authoritative amendments, while agents may never widen the contract themselves. A new steering propagation contract requires each stage to restate the amendments it received under a `Contract amendments received` heading in its handoff, keep them separate from its own observations, treat inherited amendments as contract clauses rather than out-of-scope work, and resolve ambiguity through `intercom` before implementing. Every bundled workflow wraps its run context once through `withSteeringPropagationContext` (exported from `@bastani/workflows/builtin/steering-context`), so `ctx.task`, `ctx.chain`, and `ctx.parallel` prompts carry the contract automatically and a stage added later inherits it. Without propagation an implementer builds to an amended contract while reviewers still score the launch contract and mark the added work as unrequested scope.
+- Added a scope discipline contract to builtin implementation stages: freeze the acceptance criteria before writing code, stop when they pass, trace every addition to a criterion, keep a deferred list instead of a growing diff, prefer the smallest diff that satisfies the contract, and report the contract, per-criterion evidence, and deferred items at the end.
+- Added a draft handoff for `ralph` runs that exhaust their review budget. When `create_pr` is enabled and the loop ends without unanimous approval, the run now opens a provider-native draft pull request that reproduces every unresolved blocking finding with priority, objective alignment, and cited `file:line`, states the iteration count, and requests no reviewers. Previously the branch was left unpushed with no handoff. Runs without `create_pr` still never touch a pull request, approved or not.
+- Added workflow-authoring guidance so, after creating and reloading a custom workflow, Atomic reports `Custom workflow created. You can inspect its code at: <workflow-folder-path>` only for newly created custom workflows, explicitly excluding builtin and pre-existing workflows ([#1978](https://github.com/bastani-inc/atomic/issues/1978)).
+
+### Removed
+
+- Removed the parenthesized context-window authoring token from workflow model strings. `(1m)`, `(1.1m)`, `(936k)`, and the generic `(long)` marker are no longer parsed from `model` / `fallbackModels` entries, and the `contextWindow` / `contextWindowStrict` stage options are gone. Builtin workflow model policies now use plain ids such as `github-copilot/claude-opus-4.8:high`, and every stage session uses its model's catalog context window.
+
+### Changed
+
+- Cleaned up workflow overlay status chrome. The orchestrator pane no longer echoes the host `MCP: <n>/<n> servers` count in its statusline, and attaching to a stage no longer adds a `pi-workflows/<workflow>/<stage>` tag next to the footer statuses in stage chat. Other extension statuses, such as async subagent progress, still render in the orchestrator statusline.
+- Changed workflow stage chat to render Atomic's exact one-cell `∀` with a pronounced, theme-aware dark → accent → bright/bold → accent → dark luminance ramp at 88ms and the ordinary one-row working geometry, while preserving `NO_COLOR` weight activity, reduced-motion static accent styling, blocked/prompt chrome suppression, composer space, and factual-state precedence.
+- Workflow invocations now assign a stable, non-`default` Intercom group from the persistent top-level run identity and apply it to every Intercom-capable stage by default. Nested workflows, model fallback, pause/resume, durable replay, and subagent inheritance retain the group; separate runs remain isolated; explicit stage/task/parallel groups (including `"default"`) still override it; and stages without Intercom access remain ungrouped. Workflow authors no longer need to mint and thread group names manually ([#1999](https://github.com/bastani-inc/atomic/issues/1999)).
+- Strengthened workflow-authoring prompts and docs to require every dynamically materialized execution topology to remain a DAG, reject self-edges and ancestor back-edges before launch, unroll bounded loops into distinct tracked work, distinguish discovery diagnostics from runtime/replay/DBOS topology validation, and require topology sketches for branches, loops, and nested workflow boundaries ([#2012](https://github.com/bastani-inc/atomic/issues/2012)).
+- Changed model-visible workflow routing to triage multi-item implementation queues before launch, run independent items as bounded concurrent top-level workflows with separate worktrees and root failure boundaries, preserve ordered composition for real dependencies and clusters, and report per-item run/worktree/branch/results ([#2010](https://github.com/bastani-inc/atomic/issues/2010)).
+- Adopted Claude Opus 5 as the primary model for the Ralph prompt-engineer, orchestrator, and reviewer-A stages, the Goal orchestrator and reviewer stages, and the Open Claude Design chain, with `github-copilot/claude-opus-5` and `openrouter/anthropic/claude-opus-5` mirrors added to every affected chain. Ralph's research and reviewer-B chains keep their GPT-5.6 primaries and gain Opus 5 fallbacks. Anthropic candidates now list the direct `anthropic/...` entry ahead of its `github-copilot/...` mirror, and `claude-fable-5` gains its missing Copilot mirror. Goal's orchestrator remains an exact local copy of Ralph's.
+- Reworked the shipped Goal, Ralph, Open Claude Design, and six pattern-workflow stage prompts for GPT-5.6, Claude Opus 5, and Claude Fable 5. Prompts now put artifacts before the final query, use explicit output and stop contracts, ground status claims in current tool evidence, damp unnecessary delegation, and request commands, observed results, and file:line evidence instead of internal reasoning; shared reviewer, acceptance, E2E/QA-video, and `stop_review_loop` derivation rules now have canonical definitions. This reduces repetition and avoids Claude Fable 5 `reasoning_extraction` refusals that could force model fallback while preserving schemas, convergence semantics, and exports.
+- Rewrote the bundled `prompt-engineer` skill and its three progressive-disclosure references for current GPT-5.6, Claude Opus 5, and Claude Fable 5 behavior, reducing them from 864 to 396 lines. Removed response-prefilling guidance that errors on Claude 4.6+, visible chain-of-thought as a primary technique, and generic self-check loops; added a delete-first optimization workflow, model-family guidance, agentic prompt structure, tool routing, adaptive-thinking effort and response-length controls, query-last long-context ordering, delegation damping, grounded reporting, and the Fable 5 `reasoning_extraction` hazard.
+
+### Fixed
+
+- Fixed the Ralph research stage destroying its own research artifact. The stage prompt told the agent to write the run's research file while the stage also declared that same path as its runner-owned `output`, so the runner overwrote the authored report with the stage's final chat message once the stage ended. Because `reads` passes a path rather than file content, the orchestrator and both reviewers then read a short pointer stub instead of the findings, and each loop re-derived context the research stage had already paid for. Research stages now return the full report as their final message and are explicitly told not to write the artifact path themselves; skill-owned notes under `research/docs/` and `research/web/` are unaffected.
+- Fixed the Classify-and-act, Fan-out-and-synthesize, Generate-and-filter, Loop-until-done, and Tournament workflows returning a whole terminal artifact into the calling session's context window. The first three set `outputMode: "file-only"` to keep the parent result compact and then read the saved file back with `readFile` before returning it, cancelling the saving; the last two declared `output` without `outputMode: "file-only"`, so the runner returned the full report text alongside the saved-file reference. Each `result` output is now the compact artifact reference, and the existing `action_path`, `synthesis_path`, `final_path`, and `result_path` outputs carry the full report for callers that want it. Passing file references rather than content is now the documented default for stage handoffs and workflow outputs alike.
+- Fixed admitted durable `ctx.tool(...)` callback and command failures being misclassified as killed/cancelled when no run cancellation won, including cancellation-shaped errors and wrappers with nested process evidence. First-event arbitration now preserves the first observed failure error and node even for concurrent same-value errors. Once the workflow body settles, an ordinary failure winner closes tool admission and cancels non-cooperative sibling nodes without needing an external kill; cancellation-first races still end killed. Failed resumable roots remain on the execution-resume path and win direct same-ID collisions with completed read-only history. Awaited and unawaited failures, concise nested command errors, root metadata, and selected tool links survive session and fresh DBOS inspection without becoming replay cache hits. Named interactive launches emit one failed lifecycle card and hidden reconciliation turn; prompt-start retries and restores reuse the card's atomic recovery marker, while status inspection and repeated startup binding do not duplicate it. Failed physical session appends now roll back partial single-entry and initial-batch writes to the exact prior file state, preventing malformed JSONL tails, duplicate IDs, phantom parents, and lost retry entries after reopen ([#2021](https://github.com/bastani-inc/atomic/issues/2021)).
+- Fixed durable nested `ctx.workflow(...)` resume and completed hydration across fresh processes. Atomic now persists an awaited, input-bound boundary-start identity before child dispatch, reuses stable boundary/child ids across reversed parallel ordering, keeps identical calls distinct by ordinal, scopes child checkpoint reads symmetrically at every nesting depth, and preserves source stage ids/order/parents/status and exact owner targets. Active and completed topology, boundary lifecycle transitions, and child results are validated atomically before cache/control/child dispatch; stale, aliased, cyclic, poisoned, or nonreciprocal records fail closed without repair execution. Completed child work and `ctx.tool(...)` effects remain exactly once, completed graphs remain root-catalog-only/read-only, retained child chat stays detached from execution, and ambiguous local stage ids or names no longer route to the first match.
+- Fixed workflow-supplied working-indicator palettes to quantize through Atomic's detected terminal color mode, preserving the intended phase progression in 256-color and conhost-like environments instead of forcing truecolor output.
+- Fixed controlled workflow pauses allowing queued or late-arriving work and continuation to run after a stage was visibly paused. Atomic's native session now establishes a synchronous raw queue hold before one serialized abort boundary; repeated pause and early resume share that boundary, abort failure rollback is explicitly observed and retried, and the existing resume action releases preserved steering, follow-up, duplicate, custom, async, and user-message entries exactly once. Clearing the final item never opens the gate. Existing custom adapters remain compatible without the optional native queue-pause methods and retain fallback abort/suspension behavior, including deferring runner-admitted public deliveries until resume. Fallback replacement installs an acyclic retirement forwarding fence before atomically moving raw/display/protected ownership source-first within each queue kind, serializes source and replacement interrupts through the live owner, clears the source, and leaves the target paused. Completed post-mortem stage chat resumes only its retained conversation queue on the next ordinary submission and never changes terminal workflow state ([#1983](https://github.com/bastani-inc/atomic/issues/1983)).
+- Fixed `ctx.tool()` calls durably completing side effects before a late empty-stage rejection. Tools now create ordered, inspectable, non-chat graph nodes with live, failed, completed, cancelled, and cached states; root completion waits for every admitted tool and promotes the first observed admitted failure left by a fulfilled body, while ordinary body rejections keep their exact error and link the selected matching failed tool when available; tool-only workflows complete normally; durable replay reconstructs and migrates topology without repeating callbacks; and completed tool-only runs open read-only without appearing stale or treating inspection as a new lifecycle transition. Terminal publication now atomically closes tool admission after admitted settlement continuations drain, so retained post-terminal calls reject before callbacks, retries, nodes, or checkpoints; rejected legacy child-topology annotation writes remain best-effort cache hits, do not poison DBOS flush, and retry on later replay; top-level status/session projections include nested tools with rewritten graph identity and explicit ownership; and completed retained-session stages remain chat-openable while tool nodes stay non-chat ([#1991](https://github.com/bastani-inc/atomic/issues/1991)).
+- Fixed live and restored nested `ctx.workflow()` graphs flattening valid child stages without preserving the authored composition topology. Hidden import boundaries now connect every boundary parent to every child root and every child terminal to downstream parent stages regardless of snapshot order; recursive one-level and deeper composition preserves sibling, sequential, parallel, and repeated child workflows; and boundaries with invalid, missing, empty, stale, mismatched, or recursively unusable child graphs, plus failed or skipped boundaries, retain the boundary summary rather than flattening an unrelated run. Duplicate child-local stage IDs and names keep distinct virtual IDs and exact owning `{runId, stageId}` targets across attach, messaging, pause, interrupt, resume, inspection, selection, and post-mortem chat, while nested runs remain excluded from top-level listings and ordinary workflow graph behavior is unchanged.
+- Fixed retained terminal stage chats dropping the Working indicator after Enter and before the follow-up agent turn started; the indicator now remains visible and animated throughout prompt attachment and processing without reviving stale terminal activity ([#1982](https://github.com/bastani-inc/atomic/issues/1982)).
+- Fixed programmatic `workflow send` reopening retained stage conversations after the authoritative root workflow had terminated. Completed, failed, skipped, cancelled, killed, and terminal-blocked roots now return a structured `WORKFLOW_TERMINAL` failure before stage or nested-owner resolution, prompt inspection, session probing/revival, handle lookup, admission, or delivery. Atomic rechecks the shared terminal authority at final synchronous SDK admission, including after awaited retained-session creation and paused or isolated-session resume setup; unsafe legacy handle delivery has no fallback. Terminal publication promptly unregisters and disposes an unclaimed provisional handle without waiting for hung session creation, late-created sessions are disposed, and handle replacement revokes stale admission while settling every provisional lease against one disposal. Prompt, model, tool, file, transcript, and workflow-snapshot side effects remain blocked. Live idle/streaming sends, pending-input answers, and explicit paused/interrupted resume remain available, while `/workflow attach` and Intercom can claim the retained handle and keep their explicit post-mortem chat paths ([#2009](https://github.com/bastani-inc/atomic/issues/2009)).
+
+### Removed
+
+- Removed Cursor model fallbacks and Cursor-branded Impeccable harness compatibility from shipped workflows and skills ([#1994](https://github.com/bastani-inc/atomic/issues/1994)).
+- Removed the built-in `deep-research-codebase` workflow.
+
+## [0.9.11-alpha.5] - 2026-07-23
+
+### Changed
+
+- Strengthened the existing Goal and Ralph reviewer prompts with a conditional contract-probe playbook for exact external-consumer APIs, build/feature matrices, schema optionality, state transitions, configuration precedence, low-level feature-flag independence, and permissive inputs. Reviewers now record independent probe outcomes in existing evidence fields and withhold approval when a material literal clause remains unverified, without changing reviewer counts, schemas, or convergence semantics. ([#1973](https://github.com/bastani-inc/atomic/issues/1973))
+- Strengthened model-visible workflow routing guidance with a pre-launch requirement/risk/evidence coverage pass, a one-launch composition commitment, concrete graph-selection signals, and bounded skeptical-reviewer loops whose model-selected probes are executed authoritatively through durable `ctx.tool(...)` verifier gates rather than model self-report ([#1974](https://github.com/bastani-inc/atomic/issues/1974)).
+- Changed the builtin Goal execution stage from a direct worker into a Ralph-style sub-agent orchestrator. Goal now runs `orchestrator-N` stages that track and delegate implementation, validation, documentation, and follow-up repairs through the `subagent` tool; writes `orchestrator-receipt.md`; forks later turns from the prior orchestrator session; and uses a locally contained copy of Ralph's exact xhigh orchestrator model and fallback chain while retaining Goal's ledger, reviewer, reducer, and optional final PR flow.
+- Reordered Goal's reviewer fallbacks so GPT-5.6 is tried before Kimi K3 within both the leading direct-provider group and the OpenRouter group, while retaining Claude Fable 5 as primary and preserving each group's position in the full chain.
+
+## [0.9.11-alpha.4] - 2026-07-23
+
+### Added
+
+- Added the opt-in `autoAttach` workflow-definition field, which opens the graph overlay when an interactive top-level named workflow is launched through `/workflow <name>` or the registered `workflow` tool without changing headless launches, nested workflow composition, or the existing input-form launch path.
+- `WorkflowRunContext` now optionally exposes the host session's model catalog as `ctx.models` (including `currentModel`, the user-selected session model, and `listModels()`). Custom workflow definitions can use it to select stage models from the live catalog; the field is absent when the host provides no catalog, and builtin workflow model chains are unchanged.
+
+### Changed
+
+- Workflow prompt guidance now instructs agents to give each workflow invocation its own intercom group by default — unless the user requests otherwise — by minting one invocation-scoped literal group name inside the workflow's `run` function (e.g. `"myflow-" + randomUUID()`) and passing it via the `group` option on each stage, task, or parallel step that should share it; `group: true`/`"auto"` mints one shared UUID group per `ctx.parallel(...)` set but a fresh UUID per non-parallel stage. This keeps stage and subagent intercom chatter isolated from the parent chat and other concurrent runs, since ungrouped sessions all share the `"default"` group; subagent inheritance, capability gating, and cross-group `contact_supervisor` escalation are unchanged.
+- Attached workflow stage chats now match the main interactive footer by showing the home-shortened current folder with its cached, live-updating Git branch and by mirroring current extension status lines such as MCP connectivity, using the workflow chat theme without replacing the existing hierarchy and copy-mode hints.
+- The builtin `goal` and `ralph` workflow descriptions and their `objective`/`prompt`/`create_pr` input descriptions now instruct launching agents that when a delegated task includes submitting a pull request (or MR/review), that final action must be stripped from the objective/prompt text and requested via `create_pr=true` instead when preparing the workflow inputs. This keeps PR creation an explicitly authorized final-stage action rather than embedded task text that intermediate stages are told to ignore.
+- Goal worker and Ralph orchestrator prompts now carry an explicit worktree-discipline contract: all work happens in the invoking checkout (or the run's explicitly configured worktree), stages never create additional git worktrees, clones, or repository copies unless the user's task explicitly requests them, and work discovered stranded outside the invoking checkout must be brought back in before continuing. The `git_worktree_dir` input descriptions state the same rule for launching agents.
+- Goal and Ralph reviewer prompts now include a code-delta presence and integrity contract: before trusting receipts or stage summaries, reviewers must prove the code delta actually exists in the review checkout using the repository's version-control tooling (for git: `git worktree list`, `git status`, and a baseline diff), treat claimed-but-absent work as a blocking finding instead of approving over an empty or unrelated delta, treat uncommitted work at claimed readiness as remaining work unless the objective forbids committing, and flag any modification, rename, or deletion of pre-existing test files or test functions as a finding requiring explicit justification.
+- Goal worker prompts now require committing work in the current checkout with a descriptive message before claiming readiness for review — verifying a clean working tree with the repository's version-control status command and reporting the commit identifier in the receipt — unless the objective or acceptance criteria explicitly forbid committing. Delivery verification stays with reviewers and prompts (version-control-agnostic) rather than a hardcoded git gate in the runner.
+
+### Fixed
+
+- Fixed host-session replacement (`/new`, `/resume`, `/fork`, `/reload`) leaving the process-global DBOS executor stopped so every subsequent workflow run in the same Atomic process failed at its first durable checkpoint with `` `DBOS.launch()` must be called before running workflows ``. The DBOS executor lifetime is now process-scoped: process-preserving session boundaries flush pending durable writes but keep the executor launched, and SDK shutdown is reserved for actual process exit (`quit`/`beforeExit`), which still flushes and shuts down exactly once. Defense in depth: the durable-backend factory revalidates its memoized backend against the current DBOS lifecycle generation and never hands out a stopped backend (post-shutdown initialization fails loudly instead of silently degrading to a non-durable backend), the extension runtime no longer caches a permanently resolved readiness promise across lifecycle generations, and root workflow registration is durably flushed before startup admission so a stopped or unhealthy backend fails before workflow code executes any side effects. ([#1957](https://github.com/bastani-inc/atomic/issues/1957))
+
+## [0.9.11-alpha.2] - 2026-07-21
+
+### Fixed
+
+- Fixed fresh-process workflow resume and completed-run inspection losing nested child-workflow and parallel stage hierarchy. DBOS stage checkpoints now retain owning-run and boundary topology, replay restores source parentage and child runs, graceful quit persists exact sub-30-second stage timing, completed runs persist and display accumulated run duration, and project-local workflows reloaded during a chat are rediscovered from their original invocation directory. The `/workflow resume` and `/workflows` picker rows also no longer display the redundant `N prompts` segment.
+
+## [0.9.11-alpha.1] - 2026-07-20
+
+### Added
+
+- Embedded DBOS Postgres now works when Atomic runs as root on Linux (containers, CI sandboxes, eval harnesses): PostgreSQL refuses UID 0, so Atomic resolves an unprivileged system account (`postgres`, `nobody`, or `daemon`), keeps the cluster under `/var/lib/atomic-postgres` (a root home directory is untraversable for that account), and runs `initdb`/`pg_ctl` with dropped privileges. When the embedded binaries sit under an untraversable prefix (for example a root-owned `~/.nvm` global install), the Postgres runtime is copied into the cluster directory once and reused.
+
+### Changed
+
+- Updated workflow-creation guidance to prefer `ctx.tool(...)` for workflow-owned side effects, connecting durable cached results to safe resume while distinguishing pure TypeScript computation and agent-stage internals ([#1923](https://github.com/bastani-inc/atomic/issues/1923)).
+- Clarified the built-in `deep-research-codebase` discovery guidance so agents reserve the heavy workflow for tasks requiring comprehensive whole-repository context ([#1925](https://github.com/bastani-inc/atomic/issues/1925)).
+- When no durable backend can be provisioned at all (no `DBOS_SYSTEM_DATABASE_URL`, embedded Postgres unavailable, and no Docker), workflows now degrade to a process-local in-memory backend with a loud non-durable warning instead of failing every workflow action. Degraded runs execute normally but do not survive the process, so `/workflow resume` after exit has nothing to restore; DBOS query and write failures on a provisioned backend still fail the workflow action.
+
+### Fixed
+
+- Fixed `workflow({ action: "resume", runId })` returning `Run not found` for eligible durably paused workflows after session-local run state was cleared. Explicit tool resume now resolves exact IDs and unique or ambiguous prefixes through the authoritative DBOS catalog before refusing the target, preserves original workflow IDs and checkpoint replay, and surfaces resource or durable lookup failures without making ordinary status listing hydrate durable history. ([#1924](https://github.com/bastani-inc/atomic/issues/1924))
+- Fixed session teardown crashing the process (exit code 1) after DBOS durability provisioning had failed: `shutdownDbos` re-awaited the memoized rejected configuration promise and rethrew the original provisioning error out of session dispose and the `beforeExit` hook, turning otherwise-successful `--print` runs into nonzero exits (surfacing as `NonZeroAgentExitCodeError` in eval harnesses). Shutdown is now a no-op for a backend that never reached readiness, and genuine teardown failures are logged instead of thrown.
+
+
 ## [0.9.10] - 2026-07-20
 
 ### Breaking Changes

package/dist/builtin/workflows/README.md

@@ -54,7 +54,7 @@ Workflow lifecycle notices are enabled by default. They send steer prompts into
 }
 ```
 
-Set `enabled` to `false` to disable all lifecycle notices, or narrow `notifyOn` to a non-empty list of selected events. Completion, failure, and blocked lifecycle notices are emitted for top-level workflow runs, use steer delivery, and wake an idle model so the lifecycle update enters the model context when it happens. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. Awaiting-input states are tracked for dedupe/restore, but workflows do not enqueue main-chat `/workflow connect` cards for them; prompt state remains visible through workflow status/connect surfaces, avoiding stale actionable cards if a prompt resolves while the main chat is streaming.
+Set `enabled` to `false` to disable all lifecycle notices, or narrow `notifyOn` to a non-empty list of selected events. Completion, failure, and blocked lifecycle notices are emitted for top-level workflow runs, use steer delivery, and wake an idle model so the lifecycle update enters the model context when it happens. When a fulfilled workflow body leaves admitted tool failures, the engine promotes the first admission and persists that exact tool origin for the failed notice. Ordinary body rejections retain their original error and failed graph nodes without claiming a tool origin because transparent native promises do not expose the source promise; this prevents a caught tool rejection from being misattributed when body code later throws the same object or primitive. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. Awaiting-input states are tracked for dedupe/restore, but workflows do not enqueue main-chat `/workflow connect` cards for them; prompt state remains visible through workflow status/connect surfaces, avoiding stale actionable cards if a prompt resolves while the main chat is streaming.
 
 When a stage human-in-the-loop prompt is answered from the workflow TUI/stage chat, workflows also emits a separate display-only `workflows:hil-answer-notice` custom message. It records the answer for user-visible audit, but it does not wake the main agent, enter LLM context, or authorize answering later workflow prompts. Answers sent by the main-chat `workflow` tool do not emit this notice because the tool result already tells the main agent what happened.
 
@@ -62,6 +62,24 @@ When a stage human-in-the-loop prompt is answered from the workflow TUI/stage ch
 
 ## Authoring API
 
+### Dynamic topology is DAG-only
+
+Atomic `workflow({ run })` definitions are imperative, dynamic TypeScript. Discovery loads modules and validates imports and definition shape, but it does not compile every `run` path into a complete graph or prove acyclicity. Runtime inputs, branches, loops, external data, model or human output, helpers, and nested workflows determine the materialized topology during execution.
+
+**Cyclic workflow graphs are unsupported. Authors and coding agents MUST NOT create a self-edge or a dependency edge from the current frontier to an existing ancestor. Every materialized execution topology must remain a DAG. Redesign or stop before launch if a cycle cannot be removed.**
+
+Sketch branches, loops, and nested boundaries before launch. Bounded loops must create distinct tracked work per iteration with stable identity and call order; never reopen an ancestor beneath its downstream work. Compose children through `ctx.workflow(...)` boundaries rather than recursive `run` invocation. Keep retained-session follow-up that creates no dependency work as activity, not a back-edge.
+
+Execution, replay, and DBOS hydration are the authoritative topology-validation points. Runtime topology changes should add incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace these checks.
+
+### Workflow-owned side effects
+
+Prefer `ctx.tool(name, args, fn)` for workflow-owned TypeScript operations with side effects, including filesystem writes, network mutations, external API actions, and similar deterministic operations orchestrated directly by the workflow definition. Each invocation creates a non-chat, non-attachable durable graph node before `fn` runs; it may appear before, between, after, or without model stages. Atomic durably caches a completed call's serializable result, so resume returns that result without rerunning `fn` or repeating the side effect. Tool-only workflows are valid tracked execution, while a normal return with no stage, child, tool, or explicit exit remains invalid. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately. The executor closes tool admission before publishing any terminal outcome; calling a retained `ctx.tool` function afterward returns a rejected native promise and creates no callback, retry, graph node, or checkpoint.
+
+Checks that may fail as part of a repair loop can opt into `failureMode: "return"`. That overload returns a typed `{ ok: true, value, attempts, cached } | { ok: false, error, attempts, cached }` outcome after configured retries. Failure details preserve exposed `exitCode`, `stdout`, and `stderr`; persisted text is best-effort secret-redacted and limited to 16 KiB per field. A recoverable failure keeps its tool node failed but lets author code continue. Replay returns the same durable outcome with `cached: true` and does not rerun the callback. Cancellation and storage faults still throw. Atomic never injects this evidence into a later prompt: pass the needed fields to a repair stage or artifact explicitly, and use distinct serializable arguments for each bounded rerun.
+
+New tool checkpoints retain stable graph identity, invocation order, parents, and timing. A current-format checkpoint created before tool topology was added still replays safely: its cached output remains authoritative and the callback is never rerun. Root inspection derives deterministic fallback identity/order from checkpoint identity and record order; replay inside a child attempts to append topology metadata with the current child/boundary ownership without replacing the original output checkpoint. That additive migration write is best-effort: a storage rejection leaves the live replay cached in its inferred child, does not poison a later durable flush, and is retried by a later replay. Until one retry succeeds, a fresh completed inspection can only show the legacy record through the deterministic root fallback with topology unavailable; historical child ownership cannot be reconstructed from the old record alone. Fresh completed inspection reconstructs available tool topology but does not persist a workflow's declared root output; that existing limitation is separate from live `run()` output and graph correctness.
+
 ### Example 1 — Single task
 
 ```typescript
@@ -182,36 +200,43 @@ Prefer regular TypeScript module imports for reusable child workflows: import th
 ```typescript
 import { workflow } from "@bastani/workflows";
 import { Type } from "typebox";
-import goal from "@bastani/workflows/builtin/goal";
-import sharedResearch from "./shared-research.js";
+import { adversarialVerification, fanOutAndSynthesize } from "@bastani/workflows/builtin";
 
 export default workflow({
-  name: "research-and-synthesize",
-  description: "Run shared research, implement from it, then synthesize the result.",
-  inputs: {
-    topic: Type.String(),
-  },
+  name: "research-and-verify",
+  description: "Map repository slices, synthesize cited evidence, then verify the report.",
+  inputs: { topic: Type.String() },
   outputs: {
-    final: Type.String({ description: "Synthesis of the child research and implementation." }),
+    report_path: Type.String(),
+    approved: Type.Boolean(),
   },
   run: async (ctx) => {
-    const child = await ctx.workflow(sharedResearch, {
-      inputs: { topic: ctx.inputs.topic },
+    const research = await ctx.workflow(fanOutAndSynthesize, {
+      inputs: {
+        prompt: `Partition repository research for: ${ctx.inputs.topic}. Save cited findings per slice and synthesize conflicts.`,
+        max_branches: 6,
+      },
     });
+    if (research.exited) return ctx.exit({ status: research.status, reason: research.exitReason ?? "research stopped early" });
 
-    const implementation = await ctx.workflow(goal, {
-      inputs: { objective: `Implement improvements based on: ${String(child.outputs.summary)}` },
+    const verification = await ctx.workflow(adversarialVerification, {
+      inputs: { task: `Verify the cited report at ${research.outputs.synthesis_path}` },
     });
+    if (verification.exited) return ctx.exit({ status: verification.status, reason: verification.exitReason ?? "verification stopped early" });
 
-    const final = await ctx.task("synthesize", {
-      prompt: `Synthesize this research and implementation:\n\n${String(child.outputs.summary)}\n\n${String(implementation.outputs.result)}`,
-    });
-    return { final: final.text };
+    return {
+      report_path: research.outputs.synthesis_path,
+      approved: verification.outputs.approved,
+    };
   },
 });
 ```
 
-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.
+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 recursively replace that boundary with a valid, non-empty child graph whose run reciprocally identifies the parent run and boundary stage. Every boundary parent connects to every child root, and every child terminal connects to each downstream dependent. Repeated or sibling children keep distinct virtual node ids and exact `{ runId, stageId }` control targets even when local stage ids or names collide, so attach, send, pause, interrupt, resume, stage selection, and post-mortem chat reach the true owning run and stage. Implementation-owned child runs stay out of top-level `/workflow status` lists.
+
+For durable runs, Atomic writes and awaits a versioned boundary-start identity before child code can run. That record fixes the boundary id, child run id, owning root/parent, source order and parents, replay scope, alias, workflow, and a deterministic fingerprint of the child definition plus exact validated inputs across pause, process restart, cached replay, and completed inspection. Distinct-input parallel calls therefore keep their own cache even when restart reverses dispatch order; repeated identical calls share the fingerprint but retain a per-invocation ordinal. A completed child boundary and its `ctx.tool` side effects replay exactly once from the root's scoped checkpoints; only incomplete work continues.
+
+If no valid child graph can stand in for the boundary—including a failed or skipped boundary, a missing or empty child graph, stale or mismatched ownership metadata, or a recursive link that cannot produce a valid expansion—the expanded graph keeps the boundary summary instead of flattening an unrelated or invalid child. Exact expanded ids resolve first; a local id, prefix, or stage name is accepted only when it identifies one visible stage. 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.
 
@@ -245,11 +270,19 @@ Builtin workflows are also callable as modules for reuse:
 
 ```typescript
 import {
-  adversarialVerification, classifyAndAct, deepResearchCodebase,
-  fanOutAndSynthesize, generateAndFilter, goal, loopUntilDone,
-  openClaudeDesign, ralph, tournament,
+  adversarialVerification,
+  classifyAndAct,
+  fanOutAndSynthesize,
+  generateAndFilter,
+  goal,
+  loopUntilDone,
+  openClaudeDesign,
+  ralph,
+  tournament,
 } from "@bastani/workflows/builtin";
+import fanOutAndSynthesizeWorkflow from "@bastani/workflows/builtin/fan-out-and-synthesize";
 import goalWorkflow from "@bastani/workflows/builtin/goal";
+import ralphWorkflow from "@bastani/workflows/builtin/ralph";
 import openClaudeDesignWorkflow from "@bastani/workflows/builtin/open-claude-design";
 ```
 
@@ -542,7 +575,7 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 | `/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]`          | Open a workflow run graph                                |
-| `/workflow attach [run-id] [stage]`   | Open the attach/chat pane for a run or stage             |
+| `/workflow attach [run-id] [stage]`   | Open live stage chat or explicit terminal post-mortem chat |
 | `/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 quit [run-id\|--all]`      | Gracefully pause live workflow runs so they can resume later          |
@@ -554,17 +587,19 @@ Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-p
 
 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.
 
+Typing into an attached stage chat and pressing Enter steers: the message is consumed after the current assistant response finishes its tool batch and before the next model request, matching normal session steering. Ctrl+F queues a follow-up, consumed only when the agent would otherwise stop. Queued entries belong to the stage session rather than the pane, so leaving the stage and reattaching restores the pending `Steering:` / `Follow-up:` rows, and a detached stage node carries a `✉ N queued` badge in the graph.
+
 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.
 
-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.
+Graceful quit is idempotent for already-paused runs and preserves unresolved `ctx.ui` prompts in DBOS. Pausing or interrupting a stage also holds every queued steering and follow-up item in place: no queued turn, late context-bearing delivery, or workflow continuation starts while the stage is paused, and the existing `resume` action releases the items once in their existing per-queue order without queue release itself starting a provider turn. 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.
 
 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.
+DBOS is the only durable catalog for resume, completed inspection, deletion, and targeted lookup. Session JSONL files remain chat transcripts only. Atomic reads one current durable format and does not convert prior local state or pre-current DBOS records. A completed current-format child checkpoint created before boundary-start or invocation-fingerprint identity existed is shown only when its child checkpoints reciprocally prove the same root, parent run, boundary, child owner, and scope. Active checkpoints without a provable invocation fingerprint, and malformed, duplicate, stale, nonreciprocal, mixed, aliased, cyclic, orphaned, or unsupported topology, fail closed before cache exposure or child/control dispatch: Atomic does not invent a child link or execute child code to repair it.
 
-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`.)
+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. After a fresh process starts, active and completed graphs retain source stage ids, order, parent edges, lifecycle status, boundary ownership, and exact `{ runId, stageId }` control targets. The `workflow` tool's `stages`, `stage`, `transcript`, `pause`, `interrupt`, and `resume` actions route a uniquely identified visible child stage to that nested owner; `send` uses the same routing only while the root is nonterminal, and ambiguous local ids or names are rejected. Run-level `quit` still targets the selected top-level run or all live top-level runs. Completed graph inspection is read-only even when no stage transcript remains. `/workflow attach <root-run> <nested-stage>` remains the explicit user-driven path for retained post-mortem chat and routes to the true child owner without resuming or mutating execution. Programmatic `workflow send` rejects terminal roots before nested-owner routing or session probing. (`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.
+Raw stage-chat prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a raw stage-chat 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. Durable `ctx.ui` responses are separate DBOS checkpoints: resume returns those cached responses without asking again, and graph-backed UI re-materializes the answered prompt node from metadata. 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.
 
 ### `workflow` tool (LLM-callable)
 
@@ -573,11 +608,11 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "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.",
+  "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; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, send prompt answers or steering only while the root workflow is nonterminal, 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. Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.",
   "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' | 'quit' | 'resume' | 'reload'",
+    "action": "'run' | 'list' | 'get' | 'inputs' | 'models' | '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 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",
@@ -599,8 +634,9 @@ 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 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.
+- **`send`** — operates only while the authoritative root workflow is nonterminal. It 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. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or starts/queues the eligible live turn. Terminal `completed`, `failed`, `skipped`, `cancelled`, `killed`, and terminal `blocked` roots fail closed with `status: "failed"`, `code: "WORKFLOW_TERMINAL"`, `delivery: "rejected"`, the requested root id/status, and guidance to start a new workflow (or proceed inline only for small, deterministic, low-risk work). The preflight guard rejects already-terminal roots before stage resolution, nested-owner routing, prompt inspection, retained-session probing/revival, handle lookup, message admission, or delivery selection, so it creates no session/handle/model/tool/file work, appends no transcript, answers no input, and mutates no workflow/stage snapshot. Missing or malformed retained sessions receive the same error without probing. A second check against the same shared authority runs at final synchronous SDK admission: if a live root terminates while retained-session creation is pending, Atomic rejects the send, disposes its unclaimed provisional session/handle, and starts no prompt, model, tool/file, transcript, or workflow-state work. Concurrent explicit `/workflow attach` or Intercom claims remain independent. Use `/workflow attach <run-id> <stage>` as the user-driven post-mortem path; that chat can append to a valid retained session but never resumes or changes workflow execution state.
 - **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
+- **`models`** — returns safe model-catalog metadata from the configured registry. Each entry contains `provider` (e.g. `openai`), `id` (e.g. `gpt-4`), `fullId` (e.g. `openai/gpt-4`), `isCurrent` (whether this is the active model), and `availableThinkingLevels`, canonically derived from the registry model's `reasoning` and `thinkingLevelMap` metadata. The result is a configured-auth snapshot: it shows which models are present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. No secrets, tokens, or authentication details are returned.
 
 ### F2 keyboard shortcut
 
@@ -642,6 +678,8 @@ For large handoffs, prefer artifact paths over prompt injection: write stage out
 
 Workflow stage sessions follow Atomic SDK directory defaults: `DefaultResourceLoader` is initialized with the project `cwd` and the Atomic default `~/.atomic/agent` directory, while legacy `.pi` paths remain readable where the SDK supports multiple config directories. A stage-supplied `agentDir` is treated as an explicit user override; a stage-supplied `resourceLoader` owns discovery, with `cwd`/`agentDir` left for session naming and tool path resolution.
 
+Custom `AgentSessionAdapter` runtimes may optionally expose `queuedMessagesPaused`, `pauseQueuedMessages()`, and `resumeQueuedMessages()` on public `StageSessionRuntime`. Existing adapters that omit them retain the prior fallback pause behavior: the active call is aborted and runner-admitted public deliveries stay deferred until explicit resume. When both methods are present, Atomic uses the stronger native hold so raw queued steer/follow-up work is gated before abort settles and released without starting a provider turn. Atomic's official runtime implements this optional capability.
+
 To inspect a workflow's input schema inside pi, use `/workflow inputs <name>` or `/workflow <name> --help`.
 
 ---
@@ -687,73 +725,48 @@ const convergence = await ctx.workflow(loopUntilDone, {
 
 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`
+### Repository-wide research
 
-Scout + research-history chain → two parallel specialist waves → aggregator. Ideal for deep investigation of a codebase topic across locator, pattern, analyzer, and ecosystem angles.
+For broad repository uncertainty, compose `fan-out-and-synthesize` with a partition prompt that produces distinct subsystem slices, writes each branch to an artifact, and requires the synthesis barrier to cite concrete paths and resolve conflicting findings. Use `/skill:research-codebase` when one focused subsystem or question is enough.
 
 ```text
-/workflow deep-research-codebase prompt="How does session persistence work?"
+/workflow fan-out-and-synthesize prompt="Partition session persistence by subsystem, save cited findings per branch, and synthesize the end-to-end flow"
 ```
 
-| Input             | Type     | Required | Default | Description                                               |
-| ----------------- | -------- | -------- | ------- | --------------------------------------------------------- |
-| `prompt`          | `text`   | ✓        | —       | Research question or topic to investigate.                |
-| `max_partitions`  | `number` | —        | `100`   | Maximum number of codebase partitions to explore.         |
-| `max_concurrency` | `number` | —        | `100`   | Maximum number of workflow stages to run concurrently.    |
-
-Final Markdown research documents are written to dated `research/` paths relative to the current working directory, with a numeric suffix if needed to avoid overwriting an existing document. Hidden run artifacts are written under `research/.deep-research-<run-id>/`.
+### Task-specific implementation and review
 
-Child workflow outputs: `result`, `findings`, `research_doc_path`, `artifact_dir`, `manifest_path`, `partitions`, `explorer_count`, `specialist_count`, `max_concurrency`, and `history`.
+Domain-specific implementation should use a custom worker → fresh verifier → reducer graph when no installed pattern covers the complete contract. Keep literal acceptance criteria visible to each reviewer, execute deterministic checks through workflow-owned tools, consolidate evidence-backed findings into bounded repair rounds, and stop on explicit approval, blocked evidence, or iteration exhaustion. Keep PR/MR creation, release, deployment, and publication as separately authorized post-approval actions.
 
 ### `goal`
 
-Goal Runner workflow: initialize a persisted goal ledger with a per-run goal id, immutable `acceptance_criteria`, and lifecycle events, render goal-continuation context, run bounded worker LM turns, append receipts, run three independent reviewers with objective-alignment findings and clause-by-clause requirements traceability, let a TypeScript reducer decide `complete`, `continue`, `blocked`, or `needs_human`, and optionally run a final-stage PR handoff after approval. All three reviewers start in clean, non-forked contexts like Ralph's reviewers and use Ralph's exact `reviewer-a` model chain, led by Claude Fable 5. At review start, every concurrent reviewer checks Intercom, discovers sibling reviewers in the same run, communicates its validation plan, and coordinates ownership and serialization of expensive, lock-prone, or conflicting shared-checkout/shared-environment commands. Reviewers announce coordinated check starts and finishes, release claimed resources, and share reusable execution evidence while still independently inspecting the patch and producing their own verdicts. Workers begin from an observable acceptance/contract matrix derived from the literal objective/acceptance criteria and are prompted to model states, transitions, and invariants explicitly for stateful work; each review round's findings are consolidated into a deduplicated cross-reviewer batch (`consolidated_findings` in the round artifact) that the next worker turn repairs together, with durable regression evidence required for reproduced findings. Reviewers independently derive adversarial checks from the literal contract before relying on the worker receipt or worker-authored tests. Workers and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios; they must assume credentials/auth/environment access exists until concrete checks plus an actual app/flow launch attempt prove otherwise, and skipped E2E must cite exact attempted commands and observed failure output. Reviewers also look for any QA E2E video referenced by the ledger or receipt and inspect the actual video before treating it as proof. Token budget behavior is intentionally excluded. Goal skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation after Goal reaches `complete` within the turn budget.
-
-Resource release is itself a coordinated update: after releasing a claim, the reviewer explicitly notifies its siblings through Intercom rather than treating release as a silent local action.
+Goal runs a bounded autonomous implementation loop with a durable objective ledger, immutable acceptance criteria, sub-agent orchestration receipts, parallel reviewers, and a deterministic reducer. It returns `complete`, `blocked`, or `needs_human`; set `create_pr=true` only to authorize the final PR/MR/review stage after approval.
 
 ```text
-/workflow goal objective="Migrate the database layer to Drizzle ORM" base_branch=develop
-/workflow goal objective="Migrate the database layer to Drizzle ORM and open a PR when complete" base_branch=develop create_pr=true
+/workflow goal objective="Update CLI docs, add one example, and validate the docs build"
 ```
 
-| Input         | Type     | Required | Default       | Description                                                   |
-| ------------- | -------- | -------- | ------------- | ------------------------------------------------------------- |
-| `objective`   | `text`   | ✓        | —             | Goal-runner objective or delta.                               |
-| `acceptance_criteria` | `text` | — | objective | Original immutable task contract; pass the original task text when launching follow-up Goal runs from reviewer findings. |
-| `max_turns`   | `number` | —        | `10`          | Maximum worker/review turns before human follow-up is needed. |
-| `base_branch` | `string` | —        | `origin/main` | Branch reviewers and the optional final stage compare the current delta with. |
-| `create_pr`    | `boolean` | —        | `false`       | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation after Goal reaches `complete`. |
-
-`goal` defaults to 10 worker/review turns. Reviewer quorum is fixed internally at 2 reviewer `complete` votes, and approval is deterministic on each reviewer's self-reported `stop_review_loop` boolean: a reviewer approves exactly when it returns `stop_review_loop=true` with no `reviewer_error` (parse failures count as non-approval), and the reducer completes the run when quorum of those booleans is met. Findings and `requirements_traceability` remain required audit evidence and drive the reviewer prompts that derive the flag (`required_by_objective` findings mean `false` at any priority, P3 included; `consistent_with_objective` P3 nice-to-haves, out-of-scope observations, the quorum process itself, and the authorized post-approval PR final action must not hold the flag at `false`), but the harness does not recompute approval from those arrays. Without quorum, the decision reason records the reviewers' remaining work, and the bounded loop stops inspectably at `max_turns` as `needs_human`. The repeated-blocker threshold defaults to 3 consecutive same-blocker turns and is clamped to `max_turns` when you run fewer than 3 turns.
-
-Child workflow outputs: `result`, `status`, `approved`, `goal_id`, `objective`, `acceptance_criteria`, `ledger_path`, `turns_completed`, `iterations_completed`, `receipts`, `remaining_work`, `review_report`, and `review_report_path`. `pr_report` is included only when `create_pr=true`, Goal reaches `complete`, and the final `pull-request` stage runs.
+Inputs: required `objective`; optional `acceptance_criteria`, `max_turns=10`, `base_branch=origin/main`, `git_worktree_dir=""`, and `create_pr=false`.
 
 ### `ralph`
 
-Raw prompt → prompt-engineering research → orchestrate → review workflow with optional final-stage PR handoff: use the raw prompt as the operative objective, keep optional `acceptance_criteria` as the immutable original task contract (defaulting to `prompt`), transform the prompt into a codebase and online research question with `/skill:prompt-engineer`, run `/skill:research-codebase` against it, write findings under `research/`, delegate implementation through sub-agents from that research, run parallel reviewers across Claude Fable 5 and GPT-5.5 Codex model families, and iterate until approval or the loop limit. At review start, each concurrent Ralph reviewer checks Intercom, discovers same-run sibling reviewers, communicates its validation plan, claims expensive or lock-prone checks, and coordinates serialization of conflicting shared-checkout/shared-environment commands. Reviewers announce coordinated check starts and finishes, release claimed resources, and share reusable command evidence, but each still independently inspects the patch and returns its own verdict. Ralph's research, orchestrator, and reviewer prompts receive the objective next to the literal acceptance contract; when launching follow-up Ralph runs from reviewer findings, pass the ORIGINAL task text as `acceptance_criteria` so deltas cannot drift from the contract. The orchestrator begins from an observable acceptance/contract matrix derived from the literal prompt/acceptance criteria, models states/transitions/invariants explicitly for stateful work, and repairs unresolved reviewer findings as one consolidated batch (the round artifact carries a deduplicated cross-reviewer `consolidated_findings` list) with durable regression evidence for reproduced findings. Reviewers independently derive adversarial checks from the literal contract before relying on the implementation notes, orchestrator report, or worker-authored tests, and each reviewer derives a single authoritative `stop_review_loop` boolean from that evidence (`required_by_objective` findings mean `false` at any priority, P3 included, while `consistent_with_objective` P3 nice-to-haves stay non-blocking); the loop gate approves deterministically on that boolean plus a null `reviewer_error` without recomputing approval from the findings arrays. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical with `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. They must assume credentials/auth/environment access exists until concrete non-destructive checks plus an actual launch/flow attempt prove otherwise; skipped E2E is valid only when exact attempted commands and observed failure output are recorded. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video, references it in the implementation notes, and exposes it as the `qa_video_path` output; reviewers receive that path and inspect the actual video before treating it as proof. Review decisions include `requirements_traceability`, a non-empty clause-by-clause map over every prompt/acceptance-criteria requirement kept as audit evidence for deriving the flag; worker-authored tests/snapshots passing are circular evidence unless tied to independent current-state proof, and process-only clauses (reviewer quorum, the authorized post-approval PR final action) must never hold `stop_review_loop` at `false`. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. Follow-up iterations pass unresolved review artifacts into prompt-engineering/research and fork research from prior research session data when available. Ralph skips PR creation by default; prompt text alone does not opt in. Pass `create_pr=true` to authorize only the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation (for example GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling). Ralph's own PR-creation instructions live in that final stage. Reviewers inspect repository infrastructure directly as needed; Ralph no longer runs separate `infra-*` discovery stages.
-
-Resource release is itself a coordinated update: after releasing a claim, the reviewer explicitly notifies its sibling through Intercom rather than treating release as a silent local action.
+Ralph runs prompt refinement, codebase research, delegated implementation, and independent multi-model review in a bounded loop. It can start from a task, issue, or spec path; set `create_pr=true` only to authorize the post-approval final stage.
 
 ```text
-/workflow ralph prompt="Migrate the database layer to Drizzle ORM" max_loops=3 base_branch=develop
-/workflow ralph prompt="Migrate the database layer to Drizzle ORM" max_loops=3 base_branch=develop create_pr=true
+/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic" max_loops=3
 ```
 
-| Input                 | Type      | Required | Default       | Description                                                   |
-| --------------------- | --------- | -------- | ------------- | ------------------------------------------------------------- |
-| `prompt`              | `text`    | ✓        | —             | Task, feature request, issue summary, or spec path to research, execute, refine, and review. |
-| `acceptance_criteria` | `text`    | —        | prompt        | Original immutable task contract; pass the original task text when launching follow-up Ralph runs from reviewer findings. |
-| `max_loops`           | `number`  | —        | `10`          | Maximum research/orchestrate/review iterations before completion or optional final handoff. |
-| `base_branch`         | `string`  | —        | `origin/main` | Branch reviewers and the optional final stage compare the current delta with; also used to create a missing worktree. |
-| `git_worktree_dir`    | `string`  | —        | `""`          | Optional reusable Git worktree root. Empty runs in the invoking checkout; non-empty values run Ralph stages in the created/reused worktree. |
-| `create_pr`           | `boolean` | —        | `false`       | Safe-by-default PR creation flag. Omitted or `false` skips the final `pull-request` stage and omits `pr_report`; prompt text alone does not opt in, and only strict `true` authorizes the final `pull-request` stage to attempt provider-appropriate PR/MR/review creation. |
+Inputs: required `prompt`; optional `acceptance_criteria`, `max_loops=10`, `base_branch=origin/main`, `git_worktree_dir=""`, and `create_pr=false`.
 
-Child workflow outputs: `result`, `plan` (latest transformed research question), `plan_path` (compatibility alias for `research_path`), `research`, `research_path`, `implementation_notes_path`, `qa_video_path` (reviewable QA end-to-end proof video recorded with `playwright-cli` for UI-applicable changes, when produced), `approved`, `iterations_completed`, `review_report`, and `review_report_path`. `pr_report` is included only when `create_pr=true` and the final `pull-request` stage runs.
+For either workflow, keep PR/MR creation out of the task text and pass the original task as `acceptance_criteria` on follow-up runs to prevent contract drift.
 
 ### `open-claude-design`
 
 Combined discovery/init → design-system/reference research → curated reference discovery with user preference check → separate forked generate and user-feedback chains → export/handoff pipeline. The `discovery` stage asks for output type and references, then runs impeccable init in the same stage so PRODUCT.md/DESIGN.md are detected, created, or reconciled. `ds-*` stages handle user-provided URL/file reference extraction directly, then `reference-discovery` uses that context and asks which curated direction you prefer (or asks for a reference image/path/URL if none fit). Export is only `exporter` plus `final-display`.
 
+Each refinement round pauses at a deterministic run-level prompt before its `user-feedback-*` stage starts (the stage's browser long-poll never sets `awaiting_input`, so the gate is where the wait surfaces). The prompt fires the needs-attention badge and names the preview path and `file://` URL; choose `Start live review` to open the browser session (the stage prints the live `http://` review URL first — see it with `/workflow connect`), or `Skip remaining review rounds and export as-is` to accept the current design. Headless runs skip the gate. A feedback stage that fails outright fails the run; only a completed review with no requested changes counts as approval.
+
+Research context moves between stages as artifact files, not inline prompt payloads: the project design context is written to `<artifact_dir>/design-context.md` and the curated references brief to `<artifact_dir>/references.md`; `reference-discovery` reads the design context, and the generate and exporter stages read both files via `reads`. Only verbatim user annotations and the word-capped prior design summary travel inline.
+
 ```text
 /workflow open-claude-design prompt="Design a kanban board component"
 ```

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

@@ -25,11 +25,6 @@ declare module "@bastani/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";