@bastani/atomic 0.9.11-alpha.7 → 0.9.11-alpha.9

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,36 @@ 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
@@ -15,6 +45,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - 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
 

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.
@@ -606,7 +608,7 @@ Raw stage-chat prompt answer replay is live-memory only. `StageSnapshot.promptAn
 ```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/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.",
+  "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",
@@ -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/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.`,

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

@@ -15,8 +15,12 @@ import { exportOpenClaudeDesign, refineOpenClaudeDesign } from "./open-claude-de
 import {
   NO_REFERENCES_BRIEF,
   buildReferenceDiscoveryPrompt,
+  designContextPath,
+  persistDesignContext,
   persistReferencesBrief,
+  referencesBriefPath,
   runDiscoveryAndInit,
+  type LiveReviewGateUi,
 } from "./open-claude-design-setup.js";
 
 const GROUNDED_REPORTING =
@@ -37,6 +41,7 @@ type OpenClaudeDesignContext = {
   exit?(options?: { readonly status?: string; readonly reason?: string; readonly outputs?: Partial<OpenClaudeDesignOutputs> }): never;
   task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
   parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+  readonly ui: LiveReviewGateUi;
 };
 
 export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext): Promise<OpenClaudeDesignOutputs> {
@@ -61,6 +66,10 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   );
   const previewFileUrl = `file://${previewPath}`;
   const specFileUrl = `file://${specPath}`;
+  const partialArtifactOutputs = {
+    playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
+    preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
+  };
 
   // Browser-centric workflow: the discovery/preview review and the interactive
   // `live` QA loop need the playwright-cli browser. If it is unavailable, exit
@@ -72,13 +81,31 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   ) {
     designContext.exit({
       reason: `open-claude-design needs the playwright-cli skill's browser for interactive design review, which is unavailable (${playwrightCli.error ?? playwrightCli.summary}). No design was generated. Install it (\`npm install -g @playwright/cli@latest\` + \`npx playwright install chromium\`) and re-run.`,
-      outputs: {
-        playwright_cli_status: playwrightCli.summary, run_id: runId, artifact_dir: artifactDir,
-        preview_path: previewPath, preview_file_url: previewFileUrl, spec_path: specPath, spec_file_url: specFileUrl,
-      },
+      outputs: partialArtifactOutputs,
     });
   }
 
+  // design-context.md / references.md are required `reads` inputs for the
+  // reference-discovery, generate, and exporter stages. A failed write must
+  // not let those stages dispatch against nonexistent context: exit the run
+  // as `blocked` through ctx.exit (mirroring the browser early-exit) with the
+  // artifact paths surfaced, or propagate the error when ctx.exit is absent.
+  const persistRequiredContextOrExit = (persist: () => void): void => {
+    try {
+      persist();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      if (typeof designContext.exit === "function") {
+        designContext.exit({
+          status: "blocked",
+          reason: `${detail} No design was generated.`,
+          outputs: partialArtifactOutputs,
+        });
+      }
+      throw error;
+    }
+  };
+
   // Anthropic-heavy chain for design taste. Opus stays at :xhigh here because
   // visual quality, rather than cost per task, is the primary objective.
   const designModelConfig = {
@@ -229,31 +256,41 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
   });
   const onboardingSummary = joinResults(onboardingAnalysis);
 
+  // Large research context is handed to later stages as an artifact file plus
+  // `reads`, never as an inline prompt embed or `previous` payload, so one
+  // oversized research result cannot become one oversized prompt message
+  // (issue #2121; same failure class as the #1499 413).
+  const designSystem = [
+    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
+    projectContext.summary,
+    "",
+    "Design-system and user-reference evidence:",
+    onboardingSummary,
+  ].join("\n\n");
+  persistRequiredContextOrExit(() => persistDesignContext(artifactDir, designSystem));
+  const designContextFile = designContextPath(artifactDir);
+
   const referenceResult = discoverReferences
     ? await designContext.task("reference-discovery", {
         prompt: buildReferenceDiscoveryPrompt({
           prompt: designBrief,
           outputType,
-          designContextHint: [
-            projectContext.summary,
-            "Design-system/reference discovery evidence from codebase design discovery stages:",
-            onboardingSummary,
-          ].join("\n\n"),
+          designContextFile,
           artifactDir,
           browserBootstrapRules,
         }),
-        previous: onboardingAnalysis,
+        reads: [designContextFile],
         ...designModelConfig,
       })
     : undefined;
-  const contextResults = referenceResult === undefined
-    ? onboardingAnalysis
-    : [...onboardingAnalysis, referenceResult];
 
   const referencesBriefRaw = (referenceResult?.text ?? "").trim();
   const referencesBrief =
     referencesBriefRaw.length > 0 ? referencesBriefRaw : NO_REFERENCES_BRIEF;
-  if (referencesBriefRaw.length > 0) persistReferencesBrief(artifactDir, referencesBrief);
+  // Always persist so the generate stages' `reads` target exists even when
+  // discovery is skipped or returned nothing.
+  persistRequiredContextOrExit(() => persistReferencesBrief(artifactDir, referencesBrief));
+  const referencesFile = referencesBriefPath(artifactDir);
 
   const importContext = references.length > 0
     ? [
@@ -261,16 +298,9 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
         "Reference sources:",
         userReferenceContext,
         "",
-        onboardingSummary,
+        "Full design-system and reference evidence: read the design-context file.",
       ].join("\n")
     : "No user reference was provided; infer the design direction from the brief, project design context, research, and curated reference inspiration.";
-  const designSystem = [
-    "Project design context from `/skill:impeccable init` and PRODUCT.md/DESIGN.md:",
-    projectContext.summary,
-    "",
-    "Design-system and user-reference evidence:",
-    onboardingSummary,
-  ].join("\n\n");
 
   let latestDesign = "";
   let approvedForExport = false;
@@ -285,12 +315,12 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     previewFileUrl,
     artifactDir,
     browserBootstrapRules,
-    designSystem,
-    generationContext: contextResults,
+    designContextFile,
+    referencesFile,
     designModelConfig,
     workflowCwd,
-    referencesBrief,
     importContext,
+    ui: designContext.ui,
   });
   latestDesign = refinement.latestDesign;
   approvedForExport = refinement.approvedForExport;
@@ -305,7 +335,8 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     specPath,
     specFileUrl,
     browserBootstrapRules,
-    designSystem,
+    designContextFile,
+    referencesFile,
     latestDesign,
     designModelConfig,
   });