@bastani/atomic 0.9.11-alpha.8 → 0.9.11

package/dist/builtin/web-access/github-extract.ts

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { extname, join, resolve as resolvePath, sep as pathSep } from "node:path";
 import { activityMonitor } from "./activity.js";
 import type { ExtractedContent } from "./extract.js";
+import { flattenTruncatedString } from "./flat-string.js";
 import { checkGhAvailable, checkRepoSize, fetchViaApi, showGhHint } from "./github-api.js";
 import { BINARY_EXTENSIONS, MAX_INLINE_FILE_CHARS, MAX_TREE_ENTRIES, NOISE_DIRS, loadGitHubConfig, parseGitHubUrl, resetGitHubConfig, type GitHubCloneConfig, type GitHubUrlInfo } from "./github-config.js";
 export { parseGitHubUrl, type GitHubUrlInfo } from "./github-config.js";
@@ -225,14 +226,14 @@ function buildDirListing(rootPath: string, subPath: string): string {
 	return lines.join("\n");
 }
 
-function readReadme(localPath: string): string | null {
+export function readReadme(localPath: string): string | null {
 	const candidates = ["README.md", "readme.md", "README", "README.txt", "README.rst"];
 	for (const name of candidates) {
 		const readmePath = join(localPath, name);
 		if (existsSync(readmePath)) {
 			try {
 				const content = readFileSync(readmePath, "utf-8");
-				return content.length > 8192 ? content.slice(0, 8192) + "\n\n[README truncated at 8K chars]" : content;
+				return content.length > 8192 ? flattenTruncatedString(content.slice(0, 8192) + "\n\n[README truncated at 8K chars]") : content;
 			} catch {
 				continue;
 			}

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.11-alpha.8",
+  "version": "0.9.11",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [
@@ -31,7 +31,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.82.1"
+    "@earendil-works/pi-tui": "^0.83.0"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {
@@ -46,6 +46,6 @@
     "linkedom": "^0.18.13",
     "p-limit": "^7.3.0",
     "turndown": "^7.2.0",
-    "unpdf": "^1.6.2"
+    "unpdf": "1.7.0"
   }
 }

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,93 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.11] - 2026-08-03
+
+### Added
+
+- Added per-node cancellation and abort targeting to `ctx.tool`. Every callback receives a `WorkflowToolContext` (`{ signal }`) combining a per-invocation controller with the run signal, and `workflow({ action: "quit"|"interrupt", runId, stageId })` resolves a tool node by expanded id, local `tool:<argsHash>` id, or tool name. Aborting one node leaves siblings running; existing zero-argument callbacks are unchanged ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Added opt-in `ctx.tool(..., { failureMode: "return" })` for checks that may fail during repair flows, preserving bounded redacted `exitCode`, `stdout`, and `stderr` as typed durable data that replays without rerunning the callback ([#1993](https://github.com/bastani-inc/atomic/issues/1993)).
+- Re-added the built-in Goal and Ralph workflows with their typed composition exports, command metadata, tests, and docs.
+- Added a run-contract discipline to every builtin workflow: only the user may change a run's contract, mid-run steering and resume text are authoritative amendments, and each stage restates the amendments it received. Every bundled workflow wraps its context once through `withSteeringPropagationContext` (exported from `@bastani/workflows/builtin/steering-context`), so `ctx.task`, `ctx.chain`, and `ctx.parallel` prompts carry it automatically. Implementation stages also freeze acceptance criteria before writing code and keep a deferred list instead of a growing diff.
+- Added a draft handoff for `ralph` runs that exhaust their review budget: with `create_pr` enabled, the run opens a draft pull request reproducing every unresolved blocking finding with priority and cited `file:line` instead of leaving the branch unpushed.
+- Added the opt-in `autoAttach` workflow-definition field, which opens the graph overlay for interactive top-level named launches, and `ctx.models`, which optionally exposes the host session's model catalog to custom definitions.
+- Embedded DBOS Postgres now works when Atomic runs as root on Linux (containers, CI sandboxes, eval harnesses) by resolving an unprivileged system account and keeping the cluster under `/var/lib/atomic-postgres`.
+
+### Changed
+
+- Workflow invocations now assign a stable, non-`default` Intercom group from the top-level run identity and apply it to every Intercom-capable stage. Nested workflows, model fallback, pause/resume, durable replay, and subagent inheritance retain the group; separate runs stay isolated and explicit overrides still win, so authors no longer thread group names manually ([#1999](https://github.com/bastani-inc/atomic/issues/1999)).
+- 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 Copilot and OpenRouter mirrors added throughout. Ralph's research and reviewer-B chains keep GPT-5.6 primaries and gain Opus 5 fallbacks.
+- Reworked the Goal, Ralph, Open Claude Design, and six pattern-workflow stage prompts, plus the bundled `prompt-engineer` skill (864 → 396 lines), for GPT-5.6, Claude Opus 5, and Claude Fable 5: artifacts before the final query, explicit output and stop contracts, evidence-grounded status claims, damped delegation, and no response prefilling or internal-reasoning requests. Schemas, convergence semantics, and exports are preserved.
+- Changed the builtin Goal execution stage from a direct worker into a Ralph-style sub-agent orchestrator that delegates implementation, validation, and documentation through the `subagent` tool and writes `orchestrator-receipt.md`, while retaining Goal's ledger, reviewer, reducer, and optional PR flow.
+- Strengthened reviewer prompts with a contract-probe playbook and a code-delta integrity contract: reviewers prove the delta exists in the review checkout before trusting receipts, treat claimed-but-absent work as blocking, and flag modified or deleted pre-existing tests ([#1973](https://github.com/bastani-inc/atomic/issues/1973)).
+- Strengthened workflow-authoring and routing guidance to require DAG-only dynamic topologies with pre-launch cycle rejection, bounded loop unrolling, and topology sketches, and to triage multi-item queues into bounded concurrent top-level runs with separate worktrees ([#2010](https://github.com/bastani-inc/atomic/issues/2010), [#2012](https://github.com/bastani-inc/atomic/issues/2012)).
+- Added a worktree-discipline contract to Goal and Ralph prompts (work stays in the invoking checkout), and made PR creation an explicitly authorized `create_pr=true` action rather than embedded task text.
+- Documented deterministic delivery timing for stage messages: `steer` is consumed after the current response finishes its whole tool batch and before the next model request, `followUp` only when the agent would otherwise stop ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Workflow stage chat now renders Atomic's one-cell `∀` on the shared 88 ms luminance ramp, honours caller-supplied palettes through the detected terminal color mode, and drops redundant overlay status chrome.
+
+### Removed
+
+- Removed the parenthesized context-window authoring token (`(1m)`, `(1.1m)`, `(936k)`, `(long)`) from workflow model strings along with the `contextWindow` / `contextWindowStrict` stage options. Every stage session uses its model's catalog context window.
+- Removed Cursor model fallbacks and Cursor-branded Impeccable harness compatibility ([#1994](https://github.com/bastani-inc/atomic/issues/1994)), and removed the built-in `deep-research-codebase` workflow.
+
+### Fixed
+
+- Fixed workflow graph rendering and memory on large fan-outs. Cards, edges, and composed rows clip to the viewport; store observation offers a synchronous invalidation channel plus one memoized immutable graph projection per store version, so a status update no longer `JSON.stringify`/`JSON.parse`-clones the full run payload; and truncated fields plus durable tool-result summaries copy into fresh flat strings, since a V8 SlicedString kept multi-megabyte results alive behind a 240-character summary ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed graceful quit ignoring in-flight `ctx.tool` calls, which previously reported `No controllable stages on run <id>` and left callbacks running. Quit now counts running tool nodes as controllable work, closes the tool-admission boundary, aborts the whole root/nested set, and only then records the durable paused transition. Resume re-executes the cancelled call at the same node instead of replaying a cancellation as data, a caught cancellation cannot publish a completed run over quit's paused record, and a failed durable write still leaves the run controllable so a retried quit can upgrade the pause ([#2078](https://github.com/bastani-inc/atomic/issues/2078)).
+- Fixed durable nested `ctx.workflow(...)` resume and completed hydration across fresh processes: boundary identity persists before child dispatch, ids stay stable under reversed parallel ordering, and stale, aliased, cyclic, or nonreciprocal records fail closed instead of flattening an unrelated run. Completed child work and `ctx.tool(...)` effects stay exactly-once, and ambiguous child-local stage ids no longer route to the first match.
+- Fixed `ctx.tool()` calls durably completing side effects before a late empty-stage rejection. Tools now create ordered, inspectable, non-attachable graph nodes with live, failed, completed, cancelled, and cached states; tool-only workflows complete normally; and terminal publication closes admission so post-terminal calls reject before any callback runs ([#1991](https://github.com/bastani-inc/atomic/issues/1991)).
+- Fixed host-session replacement (`/new`, `/resume`, `/fork`, `/reload`) leaving the process-global DBOS executor stopped, so every later run in the same process failed at its first durable checkpoint with `` `DBOS.launch()` must be called before running workflows ``. The executor lifetime is now process-scoped, and the backend factory never hands out a stopped backend ([#1957](https://github.com/bastani-inc/atomic/issues/1957)).
+- Fixed stage message queues across detach and reattach: a typed Enter in an attached stage chat names steering explicitly instead of being demoted to a follow-up, the stage handle keeps its own projection of `queue_update` snapshots so pending rows survive detaching, the graph shows a `✉ N queued` badge, a session that arrives already holding queued messages replays the snapshot its listeners missed, and Escape restores queued steering and follow-ups into the editor ([#2074](https://github.com/bastani-inc/atomic/issues/2074)).
+- Fixed controlled workflow pauses allowing queued or late-arriving work to run after a stage was visibly paused. A synchronous raw queue hold is established before one serialized abort boundary, and resume releases preserved steering, follow-up, custom, async, and user entries exactly once ([#1983](https://github.com/bastani-inc/atomic/issues/1983)).
+- Fixed programmatic `workflow send` reopening retained stage conversations after the root workflow had terminated; terminal roots now return a structured `WORKFLOW_TERMINAL` failure before any session probing or delivery, while `/workflow attach` and Intercom keep their explicit post-mortem paths ([#2009](https://github.com/bastani-inc/atomic/issues/2009)).
+- Fixed three `open-claude-design` faults: a failed `user-feedback-*` stage no longer converts into design approval and exports an unreviewed design ([#2123](https://github.com/bastani-inc/atomic/issues/2123)); research context now persists to `<artifact_dir>/design-context.md` and `references.md` and is read through `reads` instead of embedded inline, removing the `413 request_too_large` class ([#2121](https://github.com/bastani-inc/atomic/issues/2121)); and each refinement round raises a run-level prompt naming the preview path and `file://` URL instead of blocking on live review while reporting `running` ([#2060](https://github.com/bastani-inc/atomic/issues/2060)).
+- Fixed the Ralph research stage destroying its own artifact by declaring the authored report path as its runner-owned `output`; research stages now return the full report as their final message. Fixed the Classify-and-act, Fan-out-and-synthesize, Generate-and-filter, Loop-until-done, and Tournament workflows returning whole terminal artifacts into the calling session's context — each `result` is now the compact artifact reference, with the full report on the existing path outputs.
+- Fixed admitted durable `ctx.tool(...)` failures being misclassified as killed or cancelled, and fixed failed physical session appends leaving malformed JSONL tails, duplicate ids, or phantom parents after a partial write ([#2021](https://github.com/bastani-inc/atomic/issues/2021)).
+- Fixed fresh-process resume and completed-run inspection losing nested child-workflow and parallel hierarchy, and fixed `workflow({ action: "resume", runId })` returning `Run not found` for eligible durably paused runs after session-local state was cleared ([#1924](https://github.com/bastani-inc/atomic/issues/1924)).
+- Fixed session teardown crashing the process with exit code 1 after DBOS provisioning had failed, which turned otherwise-successful `--print` runs into nonzero exits. When no durable backend can be provisioned at all, workflows degrade to a loud non-durable in-memory backend instead of failing every action.
+- Hardened the bundled `impeccable` live-mode scripts against four CodeQL findings (insecure randomness, resource exhaustion, regex injection, double escaping), preserving behaviour for all valid inputs.
+- Fixed retained terminal stage chats dropping the Working indicator after Enter and before the follow-up turn started ([#1982](https://github.com/bastani-inc/atomic/issues/1982)).
+
+## [0.9.11-alpha.11] - 2026-08-03
+
+### Fixed
+
+- Fixed workflow graph rendering for large, wide fan-outs by clipping cards, edges, and composed rows to the visible viewport, retaining cached topology and layout across status-only updates, and making idle animation eligibility constant-time ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed every interactive store mutation cloning the full run payload before the graph could repaint. A status or question update used to build a complete `JSON.stringify`/`JSON.parse` snapshot, traversing workflow inputs, authored stage result bodies, child output values, and tool input/output bodies, so mutation cost scaled with payload size rather than with the graph. Store observation now offers a synchronous invalidation-only channel plus one immutable memoized graph projection per store version, and the graph, overlay, attach pane, stage chat, widget, lifecycle and HIL notifications, resume picker, and send admission all read that projection. In the default configuration (`statusFile: false`), mutations no longer build the legacy full snapshot; enabling `statusFile` retains that snapshot and status-file serialization cost. Topology, status, timing, prompts, attachment state, notices, bounded returned-status fields, durable tool summaries, and child output counts are preserved; the existing `Store.snapshot()` / `Store.subscribe(snapshot)` contract is unchanged for external consumers ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed the memoized graph projection keeping whole run results in memory. Truncating a result field with `slice()` leaves a V8 SlicedString that points at its untruncated parent, so a 1 KiB projected field kept a multi-megabyte run result alive — inside the store's cached projection, and inside every long-lived holder of one — long after the run itself was removed. Truncated fields are now copied into fresh flat strings, so a session with large workflow results no longer grows heap ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed durable tool-result summaries retaining the payloads they summarize. `summarizeToolResult` and `summarizeCompletedToolResult` bounded a serialized value with `` `${serialized.slice(0, 237)}...` ``, which leaves a V8 SlicedString behind a ConsString, both pointing at the untruncated parent — so a 240-character summary written into a durable checkpoint or held in a completed-run catalog row kept the entire `JSON.stringify` output alive (measured at 8.4 MiB for one large tool result). Both summaries now copy into fresh flat strings via a shared `flattenTruncatedString` helper, which the memoized graph projection also uses ([#2100](https://github.com/bastani-inc/atomic/issues/2100)).
+- Fixed Escape in an attached workflow-stage chat restoring queued steering and follow-up messages into the editor instead of leaving them stuck in the pending-message queue.
+
+## [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

package/dist/builtin/workflows/README.md

@@ -587,6 +587,8 @@ 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. 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.
@@ -761,6 +763,10 @@ For either workflow, keep PR/MR creation out of the task text and pass the origi
 
 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/builtin/goal-ledger.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { createWorkflowArtifactDirectory } from "../src/shared/workflow-artifacts.js";
 import { LEDGER_FILENAME, type GoalLedger, type GoalLifecycleEvent } from "./goal-types.js";
 
 type ModelVisibleGoalLedger = Omit<
@@ -55,11 +55,13 @@ export function appendLifecycleEvent(
 export async function createGoalLedger(
   objective: string,
   acceptanceCriteria = objective,
+  runId?: string,
 ): Promise<{ ledger: GoalLedger; ledgerPath: string; artifactDir: string }> {
-  const artifactDir = await mkdtemp(join(tmpdir(), "atomic-goal-runner-"));
+  const goalId = randomUUID();
+  const artifactDir = await createWorkflowArtifactDirectory(runId);
   const now = new Date().toISOString();
   const ledger: GoalLedger = {
-    goal_id: randomUUID(),
+    goal_id: goalId,
     objective,
     acceptance_criteria: acceptanceCriteria,
     status: "active",

package/dist/builtin/workflows/builtin/goal-runner.ts

@@ -64,6 +64,7 @@ function normalizeBranchInput(
 }
 type GoalRunnerContext = {
   readonly inputs: GoalWorkflowInputs;
+  readonly runId?: string;
   task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
   parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
 };
@@ -109,7 +110,7 @@ export async function runGoalWorkflow(ctx: GoalRunnerContext, options: GoalWorkf
     const reviewQuorum = DEFAULT_REVIEW_QUORUM;
     const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
     const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
-    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, acceptanceCriteria);
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, acceptanceCriteria, ctx.runId);
 
     let latestReviews: ReviewRecord[] = [];
     let latestReviewArtifactPaths: string[] = [];

package/dist/builtin/workflows/builtin/goal.ts

@@ -47,7 +47,7 @@ export default workflow({
     goal_id: Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })),
     objective: Type.Optional(Type.String({ description: "Raw goal objective used by the run." })),
     acceptance_criteria: Type.Optional(Type.String({ description: "Immutable acceptance criteria used by the run." })),
-    ledger_path: Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
+    ledger_path: Type.Optional(Type.String({ description: "Durable run-scoped path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
     turns_completed: Type.Optional(Type.Number({ description: "Orchestrator/review turns completed." })),
     iterations_completed: Type.Optional(Type.Number({ description: "Orchestrator/review turns completed, retained for status summaries." })),
     receipts: Type.Optional(Type.Array(Type.Object({

package/dist/builtin/workflows/builtin/open-claude-design-phases.ts

@@ -13,7 +13,13 @@ import {
   userAnnotationsBlock,
   type PreviewFeedback,
 } from "./open-claude-design-feedback.js";
-import { buildLivePreviewDisplayPrompt } from "./open-claude-design-setup.js";
+import {
+  LIVE_REVIEW_GATE_OPTIONS,
+  buildLiveReviewGateMessage,
+  buildLivePreviewDisplayPrompt,
+  isUiUnavailableRejection,
+  type LiveReviewGateUi,
+} from "./open-claude-design-setup.js";
 
 const GROUNDED_REPORTING =
   "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
@@ -47,17 +53,18 @@ type RefineOptions = {
   readonly previewFileUrl: string;
   readonly artifactDir: string;
   readonly browserBootstrapRules: string;
-  readonly designSystem: string;
-  readonly generationContext: readonly WorkflowTaskResult[];
+  /** Path to the persisted design-context.md artifact (issue #2121). */
+  readonly designContextFile: string;
+  /** Path to the persisted references.md artifact (issue #2121). */
+  readonly referencesFile: string;
   readonly designModelConfig: ModelConfig;
   readonly workflowCwd: string;
-  readonly referencesBrief?: string;
   readonly importContext?: string;
+  readonly ui: LiveReviewGateUi;
 };
 
 export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{ readonly latestDesign: string; readonly approvedForExport: boolean; readonly refinementCount: number; }> {
-  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designSystem, designModelConfig, workflowCwd } = options;
-  const referencesBrief = options.referencesBrief ?? "";
+  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designContextFile, referencesFile, designModelConfig, workflowCwd } = options;
   const importContext = options.importContext ?? "";
   let latestDesign = "";
   let latestGenerateSessionFile: string | undefined;
@@ -73,17 +80,17 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
           prompt,
           outputType,
           previewPath,
-          designSystem,
-          referencesBrief,
+          designContextFile,
+          referencesFile,
           importContext,
         })
       : buildGenerateRevisionPrompt({
           prompt,
           outputType,
           previewPath,
-          designSystem,
+          designContextFile,
+          referencesFile,
           latestDesign,
-          referencesBrief,
           importContext,
           feedback: pendingFeedback,
         });
@@ -91,11 +98,17 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
       assertUserAnnotationsThreaded(generatePrompt, [pendingFeedback], generateStageName);
     }
 
+    // Large research context travels by artifact file (`reads` + explicit
+    // read instructions in the prompt), not as an inline `previous` payload,
+    // so a single oversized research result cannot become a single oversized
+    // prompt message (issue #2121). Only the revision loop threads the small,
+    // word-capped prior design summary inline.
     const generated = await designContext.task(generateStageName, {
       prompt: generatePrompt,
-      previous: pendingFeedback === undefined
-        ? options.generationContext
-        : { name: "current-design", text: latestDesign },
+      reads: [designContextFile, referencesFile],
+      ...(pendingFeedback === undefined
+        ? {}
+        : { previous: { name: "current-design", text: latestDesign } }),
       ...designModelConfig,
       ...forkContinuationOptions(latestGenerateSessionFile),
     });
@@ -103,22 +116,49 @@ export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{
     latestGenerateSessionFile = generated.sessionFile ?? latestGenerateSessionFile;
     refinementCount = iteration;
 
-    const userFeedbackResult = await designContext
-      .task(`user-feedback-${iteration}`, {
-        prompt: buildLivePreviewDisplayPrompt({
-          previewPath,
-          previewFileUrl,
-          browserBootstrapRules,
-          iteration,
-          maxRefinements,
-        }),
-        ...designModelConfig,
-        ...forkContinuationOptions(latestUserFeedbackSessionFile),
-      })
-      .catch(() => undefined);
+    // Deterministic live-review gate (issue #2060): the user-feedback stage
+    // waits on a browser long-poll that never sets `awaiting_input`, so raise
+    // a run-level `ctx.ui` prompt first. It fires the needs-attention badge,
+    // names the preview URL, and syncs the review to the user's presence.
+    // Only the executor's unavailable-UI rejection (headless / no adapter)
+    // degrades to running the review; lifecycle failures such as interruption
+    // or a failed durable checkpoint must propagate and stop the workflow.
+    const gateChoice = await options.ui
+      .select(
+        buildLiveReviewGateMessage({ iteration, maxRefinements, previewPath, previewFileUrl }),
+        LIVE_REVIEW_GATE_OPTIONS,
+      )
+      .catch((error: unknown) => {
+        if (isUiUnavailableRejection(error)) return LIVE_REVIEW_GATE_OPTIONS[0];
+        throw error;
+      });
+    if (gateChoice === LIVE_REVIEW_GATE_OPTIONS[1]) {
+      approvedForExport = true;
+      break;
+    }
+
+    // A rejected feedback stage propagates and fails the run (issue #2123;
+    // the #1499 catch-then-approve path). Browser/tooling trouble never
+    // rejects: playwright-cli is auto-installed up front, the runner exits
+    // early when the browser is unavailable, and the stage prompt requires a
+    // degraded non-empty report instead of failing. What rejects here is
+    // model/infra failure — provider errors, fallback exhaustion, broken
+    // session forks — and that must never be laundered into approval. Only a
+    // resolved result with no meaningful notes means the user approved.
+    const userFeedbackResult = await designContext.task(`user-feedback-${iteration}`, {
+      prompt: buildLivePreviewDisplayPrompt({
+        previewPath,
+        previewFileUrl,
+        browserBootstrapRules,
+        iteration,
+        maxRefinements,
+      }),
+      ...designModelConfig,
+      ...forkContinuationOptions(latestUserFeedbackSessionFile),
+    });
 
     latestUserFeedbackSessionFile =
-      userFeedbackResult?.sessionFile ?? latestUserFeedbackSessionFile;
+      userFeedbackResult.sessionFile ?? latestUserFeedbackSessionFile;
     const feedback = toPreviewFeedback({
       iteration,
       stageName: `user-feedback-${iteration}`,
@@ -140,15 +180,21 @@ function buildInitialGeneratePrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
   readonly previewPath: string;
-  readonly designSystem: string;
-  readonly referencesBrief: string;
+  readonly designContextFile: string;
+  readonly referencesFile: string;
   readonly importContext: string;
 }): string {
   return taggedPrompt([
     ["design_brief", args.prompt],
-    ["design_system", args.designSystem],
+    [
+      "design_context_file",
+      `Read the file at ${args.designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* design-system evidence before designing.`,
+    ],
     ["reference_context", args.importContext],
-    ["reference_inspiration", args.referencesBrief],
+    [
+      "reference_inspiration_file",
+      `Read the file at ${args.referencesFile} for the curated reference inspiration to heavily emulate.`,
+    ],
     ["reference_precedence", REFERENCE_PRECEDENCE],
     ["preview_artifact_path", args.previewPath],
     ["html_rules", HTML_PREVIEW_RULES],
@@ -161,8 +207,9 @@ function buildInitialGeneratePrompt(args: {
     [
       "instructions",
       [
+        `First read the design-context and reference-inspiration files named above; they are the design system and reference authority for every decision. If a file is missing, say so and proceed from the brief.`,
         `Create the HTML artifact exactly at ${args.previewPath}.`,
-        "Follow <reference_precedence>; heavily reference <reference_inspiration> without copying wholesale or inventing traits.",
+        "Follow <reference_precedence>; heavily reference the reference-inspiration file without copying wholesale or inventing traits.",
         `Build the requested output_type (${args.outputType}): render full realistic layouts for prototypes/pages, or the component in at least three representative contexts.`,
         "Include structure, states, accessibility, responsive behavior, and integration notes as HTML comments so the preview stays clean.",
         "Use project language rather than generic placeholders when conventions exist. Add no features or abstractions beyond this design brief.",
@@ -188,16 +235,22 @@ function buildGenerateRevisionPrompt(args: {
   readonly prompt: string;
   readonly outputType: string;
   readonly previewPath: string;
-  readonly designSystem: string;
+  readonly designContextFile: string;
+  readonly referencesFile: string;
   readonly latestDesign: string;
-  readonly referencesBrief: string;
   readonly importContext: string;
   readonly feedback: PreviewFeedback;
 }): string {
   const annotations = userAnnotationsBlock([args.feedback]);
   return taggedPrompt([
-    ["design_system", args.designSystem],
-    ["reference_inspiration", args.referencesBrief],
+    [
+      "design_context_file",
+      `Read the file at ${args.designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* design-system evidence.`,
+    ],
+    [
+      "reference_inspiration_file",
+      `Read the file at ${args.referencesFile} for the curated reference inspiration.`,
+    ],
     ["reference_context", args.importContext],
     ["reference_precedence", REFERENCE_PRECEDENCE],
     ["preview_artifact_path", args.previewPath],
@@ -242,18 +295,29 @@ type ExportOptions = {
   readonly specPath: string;
   readonly specFileUrl: string;
   readonly browserBootstrapRules: string;
-  readonly designSystem: string;
+  /** Path to the persisted design-context.md artifact (issue #2121). */
+  readonly designContextFile: string;
+  /** Path to the persisted references.md artifact (issue #2121). */
+  readonly referencesFile: string;
   readonly latestDesign: string;
   readonly designModelConfig: ModelConfig;
 };
 
 export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{ readonly latestDesign: string; readonly handoff: WorkflowTaskResult; }> {
-  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designSystem, designModelConfig } = options;
+  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designContextFile, referencesFile, designModelConfig } = options;
   const latestDesign = options.latestDesign;
 
   const handoff = await designContext.task("exporter", {
+    reads: [designContextFile, referencesFile],
     prompt: taggedPrompt([
-      ["design_system", designSystem],
+      [
+        "design_context_file",
+        `Read the file at ${designContextFile} for the project design context (PRODUCT.md/DESIGN.md summary) and the ds-* design-system evidence to document.`,
+      ],
+      [
+        "reference_inspiration_file",
+        `Read the file at ${referencesFile} for the curated reference research that informed the approved design; use it wherever the spec cites visual direction or reference provenance.`,
+      ],
       ["preview_artifact_path", previewPath],
       ["spec_artifact_path", specPath],
       ["final_design_summary", "{previous}"],
@@ -267,7 +331,7 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
       [
         "instructions",
         [
-          "Read preview_artifact_path as the canonical approved design, then use the Write tool to create one self-contained HTML5 file at spec_artifact_path.",
+          "First read the design-context file named above, then read preview_artifact_path as the canonical approved design, and use the Write tool to create one self-contained HTML5 file at spec_artifact_path.",
           "In order, include: sticky header with title/status/run id; Executive Summary; Live Preview embedding the full preview via `<iframe srcdoc=\"...\">` or a side-by-side rendered copy in `<article class=\"preview-frame\">`; the six DESIGN.md sections (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) rendered with swatches, tables, and code blocks; Implementation handoff (Recommended files + components, Implementation steps, Usage example, Accessibility & responsive checklist, Validation commands, Known limitations); and an appendix linking the raw preview path.",
           "Use dense legible typography, generous whitespace, monospaced code, rendered hex/oklch swatches, and copy-to-clipboard hints in HTML comments.",
           `Show the absolute preview path (${previewPath}) and file URL (${previewFileUrl}) prominently. Preserve assumptions and limitations; introduce no requirement absent from the final design or DESIGN.md.`,