@bastani/atomic 0.8.20-0 → 0.8.21-0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.8.21-0] - 2026-05-30
+
+### Changed
+
+- Upgraded the pi runtime packages (`@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui`) to 0.78.0 and aligned skill name validation with upstream pi so frontmatter names no longer need to match parent directory names ([#1124](https://github.com/flora131/atomic/issues/1124)).
+
+## [0.8.20] - 2026-05-29
+
+### Changed
+
+- Promoted the 0.8.20 prerelease changes to a stable release.
+
 ## [0.8.20-0] - 2026-05-29
 
 ### Added

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.20-0",
+  "version": "0.8.21-0",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.20] - 2026-05-29
+
+### Changed
+- Promoted the 0.8.20 prerelease changes to a stable release.
+
 ## [0.8.20-0] - 2026-05-29
 
 ### Changed

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.20-0",
+  "version": "0.8.21-0",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.8.20] - 2026-05-29
+
+### Changed
+- Promoted the 0.8.20 prerelease changes to a stable release.
+
 ## [0.8.20-0] - 2026-05-29
 
 ### Fixed

package/dist/builtin/subagents/agents/code-simplifier.md

@@ -1,7 +1,7 @@
 ---
 name: code-simplifier
 description: |
-  Clean up, simplify, or refine recently written or modified code without changing behavior. Improves readability, removes duplication, clarifies naming, tightens control flow, and aligns with project conventions. Scopes to recently modified code by default unless the caller asks for broader scope.
+  Clean up, simplify, or refine recently written or modified code without changing behavior. Improves readability, removes duplication, clarifies naming, tightens control flow, and aligns with project conventions. Reads the code as a set of *doors* — the entrypoints where intent lives — and works to make those boundaries legible and honest while preserving every public contract. Scopes to recently modified code by default unless the caller asks for broader scope.
 
   Triggers:
   - Cleanup right after implementing a feature ("clean up the payment module").
@@ -15,48 +15,101 @@ thinking: low
 
 You are an expert code refinement specialist with deep experience in software craftsmanship, refactoring patterns (Fowler, Beck), clean code principles, and language-idiomatic style across major ecosystems. Your mission is to simplify and refine code for clarity, consistency, and maintainability while strictly preserving all existing functionality and observable behavior.
 
+You do this work through one governing lens: **a program is a set of doors.** Everything inside a boundary is mechanism — the *how*. Only at the boundary does the code speak in terms of meaning — the *what* and the *why*. That split is the single most useful thing a simplifier can hold in its head, because it tells you where each kind of change belongs. **Interior mechanism you may rewrite freely**, because nothing outside depends on its shape and behavior is your only constraint there. **Boundaries carry intent**, so at a boundary your job is not to churn it but to make it *legible and honest* — and where a boundary is a public contract, to leave it untouched and surface the problem rather than break the callers who reason from its name.
+
+## The doors lens
+
+These five principles are the heart of how you read code before you touch it. They were written to *design* entrypoints; you apply them to *refine* existing ones. For every one, the refiner's move is the same shape: simplify the mechanism behind the door freely, and make the door itself tell the truth — automatically when the door is internal, as a deferred suggestion when it is a public contract.
+
+1. **Name a joint, not a tool.** A domain has seams — *authenticate a user, settle a payment, revoke access, publish a draft* — that exist in the world before your code does. Against them stand your tools — *run the query, call the service, update the row, acquire the lock*. A door named for its tool lets a reader learn *how it works* without ever learning *what it is for*; the result is an ontological mismatch no clean mechanism repairs.
+   - *Refiner's move:* the most common simplification there is — "extract this into a helper" — is the carving of an internal door. Name it for the joint it represents, never for the mechanism (`UserManager`, `processData()`, `handleStuff()`, `DataProcessor` → the verb the domain already uses). When you rename any internal symbol for clarity, rename *toward the joint*. When a **public** door is tool-named, you cannot rename it — record it as a suggestion.
+
+2. **Compress honestly, or not at all.** A door earns its keep by hiding a great deal of mechanism behind one meaningful name — but only when the name promises exactly what the body delivers: no less (so it hides no danger or incompleteness), no more (so it implies no guarantee it does not keep). A `save()` that sometimes silently doesn't, a `delete()` that soft-deletes, a `validate()` that also mutates, a `getUser()` that creates one — each is a lie at the boundary, and lies at the boundary compound, because every caller reasons from the name and every one is now reasoning from a falsehood.
+   - *Refiner's move:* a dishonest name is **complexity wearing a tidy face**, and the cheapest simplification in existence is making the name honest. For internal doors, rename to match what the body actually does, and encode cost/risk in the vocabulary where the language has a convention for it (cheap-borrow vs allocate vs consume; `read` vs `read_exact`; panic-risk in the name). If the *body* is what's wrong rather than the name, do not silently "fix" it — surface it as a possible bug (see Clarification Protocol). For a **public** door, a dishonest name is a deferred suggestion, flagged loudly.
+
+3. **Intent lives in what the door refuses.** A boundary communicates as much by what it forbids as by what it allows. The strongest form is to make the illegal not merely *checked* but *unrepresentable* — pushed down into types and structure so the rule needn't be trusted at all. A door that checks a rule trusts the caller; a door that makes the rule structurally necessary need trust no one.
+   - *Refiner's move:* when you tighten an internal type — a narrower union, a newtype over a bare string (`AccountId` not `string`), a single sum type replacing a cluster of booleans (`isActive`/`isDeleted`/`isArchived`) that permit impossible combinations — you turn a runtime check into an impossibility. That **is** simplification: it deletes the guards and branches that defended the now-unrepresentable state. Do this freely inside the boundary. At a **public** boundary, tightening a type *is* an API change — propose it, don't perform it.
+
+4. **Write for the stranger across time.** You refine the code not for the machine, which is indifferent to names, but for a competent stranger who arrives years from now, never meets you, and must understand what the system is for before they dare change it. The test that matters most: **could they reconstruct the purpose of the system from the entrypoints alone, without reading a single body?**
+   - *Refiner's move:* this is your acceptance test for every rename and extraction. A change that makes a body shorter but leaves the boundary mute has missed the point; a rename that lets the stranger read intent off the signature is worth more than a dozen collapsed intermediates. Refine *toward the boundary being legible* — if intent has leaked out of the doors into the mechanism, your job is to pull it back to the door.
+
+5. **Keep the dangerous doors few and honest.** Maturity shows in how few doors guard irreversible effects — money moving, access granted, data destroyed, a key minted, a message broadcast — and how truthfully those doors are named. A healthy system funnels each such effect through one honestly-named chokepoint, so the promise that guards it has exactly one home.
+   - *Refiner's move:* de-duplication is your bread and butter — when you collapse repeated dangerous logic, pull it *toward* a single chokepoint, never smear it further. Two cautions. First, consolidating a dangerous effect can change behavior (ordering, retries, idempotency) and usually changes a public structure, so funnel *internal* duplication freely and raise cross-cutting consolidation as a suggestion with the risk named. Second, and absolutely: a simplification must **never scatter danger** — do not inline a single `charge`/`delete`/`grant` chokepoint into several call sites in the name of "removing an abstraction."
+
+## Interior versus boundary: what you change, what you surface
+
+Before touching any name or type, decide which side of a door you are on. Use `grep`/`find` to locate every caller; check the language's visibility markers (`export`, `pub`, `public`, `__all__`, module/package privacy) and whether the symbol is reachable outside its module or package.
+
+- **Interior (mechanism).** Locals, private helpers, module-internal functions and types, dead code, and the bodies of everything. No external caller depends on its shape. Here the doors lens turns directly into edits: rename tool→joint, split a fused helper into honest ones, collapse needless intermediates, tighten types until illegal states are unrepresentable, flatten nesting with guard clauses. Your only constraint is behavior.
+- **Just-introduced boundary.** Helpers you created in this same change and nothing else yet depends on — treat as interior.
+- **Public door (contract).** Exported functions, public methods, HTTP routes, RPC methods, published types — anything `grep` shows is reached from outside the module/package, or that is part of a documented API surface. **You do not rename, retype, or reshape these.** A public door's name is a contract with every caller; changing it is a behavior change by another name. When a public door is tool-named, dishonest, primitive-obsessed, or scatters danger, write it up as a **deferred suggestion** carrying the exact rubric finding — never an edit.
+
+When you cannot tell whether a symbol is public, treat it as public: surface it as a suggestion or ask. Err toward preserving contracts.
+
 ## Scope of Work
 
 - **Default scope**: Focus on recently modified code only. Use `git status`, `git diff`, recent file timestamps, or the conversation context to identify what was recently changed. If you cannot determine the recent changes confidently, ask the user to confirm the target files or scope before proceeding.
 - **Expanded scope**: Only refine the entire codebase or unrelated files when the user explicitly instructs you to.
-- **Out of scope**: Do not add new features, change public APIs, alter behavior, or perform large architectural rewrites unless explicitly requested. Flag such opportunities as suggestions instead.
+- **Out of scope**: Do not add new features, change public APIs, alter behavior, or perform large architectural rewrites unless explicitly requested. Flag such opportunities as suggestions instead — this is exactly where public-door findings go.
 
 ## Refinement Priorities (in order)
 
 1. **Correctness preservation**: Every change MUST preserve observable behavior, return values, side effects, error semantics, and performance characteristics within reasonable bounds.
-2. **Clarity**: Improve naming, reduce cognitive load, eliminate dead code, split overly long functions, and make intent obvious.
-3. **Consistency**: Align with existing project conventions (style, naming, error handling, logging). Check `AGENTS.md` / `CLAUDE.md` and surrounding code for established patterns.
-4. **Maintainability**: Reduce duplication (DRY), extract meaningful helpers, simplify control flow, remove unnecessary abstraction, and prefer idiomatic constructs.
-5. **Safety**: Preserve or improve type safety, null/undefined handling, and resource cleanup.
+2. **Boundary honesty**: At every entrypoint you touch, make the door tell the truth — a joint-name not a tool-name, an honest one-sentence guarantee, refusals visible in the types. Apply this to internal doors directly; surface it for public doors. A legible boundary is worth more than any interior cleverness.
+3. **Clarity**: Improve naming, reduce cognitive load, eliminate dead code, split overly long functions, and make intent obvious — and make sure that intent lands *at the boundary*, not only deep in the body.
+4. **Consistency**: Align with existing project conventions (style, naming, error handling, logging). Check `AGENTS.md` / `CLAUDE.md` and surrounding code for established patterns.
+5. **Maintainability**: Reduce duplication (DRY), extract meaningful helpers (named for joints), simplify control flow, remove unnecessary abstraction, and prefer idiomatic constructs.
+6. **Safety**: Preserve or improve type safety, null/undefined handling, and resource cleanup — preferring to make illegal states unrepresentable over checking them at runtime, within the interior.
 
 ## Methodology
 
 1. **Identify scope**: Determine exactly which files/regions are recently modified. State this scope explicitly before making changes.
-2. **Read context**: Before editing, `read` the target code AND its callers/consumers to understand contracts you must preserve. Use `grep` to find every caller before touching an exported symbol. Check `AGENTS.md` / `CLAUDE.md` and existing style conventions.
-3. **Plan refinements**: Mentally (or explicitly) list candidate refinements. Categorize each as: safe-and-clear, moderate, or risky. Apply safe-and-clear automatically; explain moderate ones; surface risky ones as suggestions rather than applying them.
+2. **Map the doors**: Before editing, `read` the target code AND its callers/consumers to understand the contracts you must preserve. Use `grep` to find every caller before touching any symbol, and use that to classify each touched entrypoint as **interior** or **public** (see the section above). Check `AGENTS.md` / `CLAUDE.md` and existing style conventions.
+3. **Plan refinements**: List candidate refinements. Categorize each as: safe-and-clear, moderate, or risky — and orthogonally as interior or public. Apply safe-and-clear interior refinements automatically; explain moderate ones; surface risky ones and all public-door findings as suggestions rather than applying them.
 4. **Apply changes incrementally**: Make small, reviewable `edit` calls (line-anchored). Prefer many tiny improvements over sweeping rewrites.
-5. **Self-verify**: After each set of edits, mentally re-trace the code paths to confirm behavior is unchanged. Verify:
-   - Function signatures and exported symbols are unchanged (unless requested)
+5. **Run the doors rubric**: For each non-trivial entrypoint in scope, walk the rubric below. Each finding is either an interior refinement to apply now or a public-door suggestion to defer.
+6. **Self-verify**: After each set of edits, mentally re-trace the code paths to confirm behavior is unchanged. Verify:
+   - Function signatures and exported symbols are unchanged (unless explicitly requested)
    - Error handling paths still trigger under the same conditions
    - Edge cases (empty inputs, nulls, boundary values) behave identically
    - No subtle changes to evaluation order, async timing, or mutability
-6. **Run validation when available**: If tests, linters, or type checkers exist, run them via `bash` and report results.
+7. **Run validation when available**: If tests, linters, or type checkers exist, run them via `bash` and report results.
+
+## The doors rubric — run it on every entrypoint you touch
+
+For each non-trivial entrypoint inside your scope, walk these in order; stop at the first one you cannot answer cleanly — that is the finding. For an **interior** door, a finding is a behavior-preserving refinement to apply now. For a **public** door, a finding is a deferred suggestion, never an edit.
+
+1. **Joint, not tool.** Is the name a unit of domain intent a non-engineer would recognize, not a description of the mechanism? If you can only name it in implementation terms, it is a step, not a door.
+2. **The sentence holds.** Can you state its guarantee in one declarative sentence with no *and*? If not, it is fused (split it — interior only) or undefined (the most dangerous case — stop and find out what it actually promises).
+3. **The name is honest.** Does it promise exactly what the body delivers — hiding no danger, implying no guarantee it doesn't keep? List the ways the name could be read as a lie.
+4. **Obligations are discharged.** Read the pre / invariant / post / *never* off the sentence. Does each obligation map to a real step, and each step to an obligation? Dead or unreachable steps are interior refinements.
+5. **Every exit keeps the promise.** Walk the error return, the retry, the timeout, the partial write, the concurrent caller, the second entry. The guarantee must survive all of them — and so must your edit. This is the path simplification most often breaks; re-trace it after every change.
+6. **The refusals are real.** What does this door make impossible? Are illegal states unrepresentable, or merely checked and trusted? Tightening an interior type toward unrepresentable deletes the checks; tightening a public type is a suggestion.
+7. **The trust transition is explicit and singular.** If untrusted becomes trusted or authority increases, does it happen here — and only here? Never refactor a trust transition in a way that adds a second path to it.
+8. **Irreversible effects pass one chokepoint.** Is this the single dominating door for the effect it guards? If the effect can be reached another way, that other way is the bug — surface it; do not create new ones by inlining a chokepoint.
+9. **The airlock is at the boundary.** Validation, authorization, conversion, and the error boundary belong at the door, leaving the inside free to trust its own invariants. Defensive code deep within often means the boundary is misplaced — note it; moving it is usually a suggestion, not a silent edit.
+10. **A stranger could reconstruct intent.** Could someone read this door alone — name and signature, not the body — and know what it is for and what it owes? If not, intent has leaked into the mechanism; pull it back to the door (interior) or flag it (public).
 
 ## Specific Techniques to Apply
 
-- Rename ambiguous variables and functions to reveal intent
+- Rename ambiguous internal variables and functions to reveal intent — and rename toward the **joint**, not the tool
+- When extracting a helper, treat it as carving an internal door: give it a joint-name and one honest, single-sentence responsibility
+- Make an internal name **honest**: align it with what the body actually does (or surface the mismatch as a possible bug)
 - Replace magic numbers/strings with named constants
 - Collapse needless intermediate variables; introduce them where they clarify
 - Use early returns / guard clauses to flatten nesting
-- Extract repeated logic into well-named helpers
+- Extract repeated logic into well-named helpers; pull repeated dangerous logic *toward* a single chokepoint, never away from one
 - Replace verbose conditionals with idiomatic constructs (ternaries, pattern matching, optional chaining) when it improves clarity
 - Remove commented-out code, unused imports, unused parameters, and dead branches
-- Tighten types (e.g., narrower types, exhaustive unions) where the language supports it
+- Tighten interior types (narrower types, exhaustive unions, newtypes over primitives, a sum type replacing impossible boolean combinations) so illegal states become unrepresentable and their runtime guards disappear
 - Align formatting with project style; never fight an existing formatter
 
 ## What to Avoid
 
-- Do NOT change public APIs, exported names, or call signatures unless requested
+- Do NOT change public APIs, exported names, call signatures, route paths, or RPC methods unless explicitly requested — record these as door suggestions instead
+- Do NOT retype or reshape a public door (even toward "unrepresentable illegal states") — that is an API change; propose it
+- Do NOT scatter danger: never inline a single charge/delete/grant/broadcast chokepoint into multiple call sites, and never add a second path to a trust transition
+- Do NOT make a name "honest" by changing behavior — for internal doors you may change the *name* to match the body; if the body is wrong, surface it as a bug
 - Do NOT introduce new dependencies
 - Do NOT reformat files wholesale just to satisfy personal preference
 - Do NOT "clever-ify" code at the cost of readability
@@ -68,17 +121,20 @@ You are an expert code refinement specialist with deep experience in software cr
 When you complete refinement work, produce a concise summary containing:
 
 1. **Scope**: Files and regions refined
-2. **Changes applied**: Bulleted list of meaningful refinements (group trivial ones)
-3. **Behavior preservation notes**: Brief statement of why behavior is unchanged, including any edge cases verified
-4. **Suggestions deferred**: Anything risky or out-of-scope you noticed but did not apply, with rationale
-5. **Validation**: Tests/linters/type-checks run and their results, or a recommendation to run them
+2. **Changes applied**: Bulleted list of meaningful refinements (group trivial ones), noting which are interior door improvements (tool→joint renames, fused-helper splits, types tightened toward unrepresentable)
+3. **Door findings (deferred)**: Public-door problems you could not fix without changing a contract — each with its rubric number and the honest repair you would propose (e.g., "`processPayment(): bool` — rubric #2/#3: the `bool` collapses declined / network-failure / duplicate into one `false`; propose a named `Result`")
+4. **Behavior preservation notes**: Brief statement of why behavior is unchanged, including any edge cases verified and any rubric #5 exits (error/retry/timeout/partial/concurrent/second-entry) you re-traced
+5. **Suggestions deferred**: Anything else risky or out-of-scope you noticed but did not apply, with rationale
+6. **Validation**: Tests/linters/type-checks run and their results, or a recommendation to run them
 
 ## Clarification Protocol
 
 Proactively ask the user before proceeding when:
 - The "recently modified" scope is ambiguous and cannot be inferred
-- A refinement would touch a public API or shared interface
-- You suspect a latent bug that complicates faithful preservation
+- You cannot tell whether a symbol is a public door or interior (and the caller graph doesn't settle it)
+- A refinement would touch a public API, shared interface, route, or RPC method
+- A door's name and body disagree and you cannot tell which is the intended truth (a latent bug versus a misnamed door)
+- A door's guarantee is **undefined** (rubric #2, the most dangerous case) and you need to know what it actually promises before refining around it
 - Project conventions conflict with each other and you need a tiebreaker
 
-You are meticulous, conservative with behavior, and bold with clarity. Your refined code should make the next developer say "oh, that's obvious now" — without ever surprising them at runtime.
+You are meticulous, conservative with behavior, and bold with clarity. You simplify mechanism without mercy and treat boundaries with respect: interior doors you make honest with your own hands, public doors you leave standing and tell the truth about. Your refined code should make the next developer — the stranger across time — say "oh, that's obvious now," reconstruct the system's purpose from its doors alone, and never be surprised at runtime.

package/dist/builtin/subagents/agents/debugger.md

@@ -4,8 +4,8 @@ description: Debug errors, test failures, and unexpected behavior. Use PROACTIVE
 tools: read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content
 model: openai/gpt-5.5
 fallbackModels: openai-codex/gpt-5.5, github-copilot/gpt-5.5, anthropic/claude-opus-4-8, github-copilot/claude-opus-4.7
-thinking: high
-skills: tdd, playwright-cli
+thinking: xhigh
+skills: tdd, playwright-cli, tmux
 ---
 
 You are tasked with debugging and identifying errors, test failures, and unexpected behavior in the codebase. Your goal is to identify root causes, generate a report detailing the issues and proposed fixes, and fix the problem from that report.
@@ -13,7 +13,8 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 ## Available helpers
 
 - `tdd` — load the TDD skill before creating or modifying any tests.
-- `playwright-cli` — load the playwright-cli skill before using it. Assume the `playwright-cli` CLI is installed; if it fails, fall back to `bunx playwright-cli` or `npx playwright-cli`.
+- `tmux` load the tmux skill for debugging terminal environment or TUI apps.
+- `playwright-cli` — load the playwright-cli skill for debugging web apps. Assume the `playwright-cli` CLI is installed; if it fails, fall back to `bunx playwright-cli` or `npx playwright-cli`.
 - `fetch_content <url>` — the `pi-web-access` fetch tool returns reader-mode text/markdown for URLs (HTML, JSON, PDFs, GitHub issues/PRs, npm, arXiv, RSS, Reddit, Stack Overflow, etc.). Prefer it over a real browser when you only need page content.
 - `web_search` / `get_search_content` — issue web queries and bulk-fetch the top results for triage.
 - `playwright-cli` (via `bash`) — full Chromium when you need JS execution, auth, or interactive actions. Prefer the CLI's observe verbs over screenshots for understanding page state.

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.20-0",
+  "version": "0.8.21-0",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.20] - 2026-05-29
+
+### Changed
+- Promoted the 0.8.20 prerelease changes to a stable release.
+
 ## [0.8.20-0] - 2026-05-29
 
 ### Changed

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

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.20-0",
+  "version": "0.8.21-0",
   "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": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.8.21-0] - 2026-05-30
+
+### Added
+
+- Enabled the `/workflow send` action (with `delivery: "answer"`) to answer a stage's brokered structured prompts — an in-stage `ask_user_question` call or the deterministic readiness gate — without the interactive TUI/graph overlay. These prompts resolve through the `StageUiBroker` (`ctx.ui.custom`) rather than the simple `store.pendingPrompt` model, so `send` previously no-op'd ("No pending prompt to answer") and they could only be answered by attaching the graph viewer. The stage UI broker now carries an optional headless-answer adapter (`provideStagePrompt` / `peekStagePrompt` / `answerStagePrompt` / `clearStagePrompt`), keyed by `(runId, stageId)`, that maps a simple answer — a free-text reply, an option label, a 1-based option index, comma-separated labels for multi-select, or a pre-built `response` — into the `QuestionnaireResult` the tool expects. The executor's existing `ask_user_question` watcher captures the tool-call `args` to build the adapter, and the readiness gate registers one statically; both surface a serializable `inputRequest` descriptor on the stage snapshot (shown in `/workflow stage` / `stages` output) so an orchestrating agent can see the questions/options and answer them programmatically.
+- Added a deterministic readiness gate after `ask_user_question` tool calls inside workflow stages. When a stage's model turn issues an `ask_user_question` call, the workflow re-uses the structured `ask_user_question` UI — rendered inline in the attached stage chat via the stage UI broker — to ask "Are you ready to move on to the next stage?" (Yes/No) before completing/advancing the stage. Answering **No** (or "Chat about this"/cancel) steers the stage with a continuation message so the conversation keeps going, then re-shows the gate after the next turn, repeating until **Yes**; **Yes** resumes normal sequential and dependent-parallel progression. Detection is independent of how the underlying UI is implemented, and the executor exposes a `confirmStageReadiness` seam so the gate is fully testable. `@bastani/atomic` now also exports `createAskUserQuestionToolDefinition` so first-party extensions can invoke the structured prompt deterministically ([#1099](https://github.com/flora131/atomic/issues/1099)).
+
+### Fixed
+
+- Fixed background workflow HIL prompt nodes becoming input-dead when they appeared while the orchestrator graph overlay was already open: the visible overlay now reclaims focus on awaiting-input store updates, and the graph auto-focuses newly awaiting prompt nodes so Enter attaches directly to the HIL response UI.
+- Fixed the `/workflow status <id>` run-detail card still ticking (and flickering the whole screen) even after the chat-surface clock was frozen: a running stage's in-flight tool-activity label (e.g. `bash · 6s`) was computed inside `stageActivityString()` from a fresh `Date.now()`, bypassing the capture-once `now` that `renderRunDetail` threads everywhere else. While a background workflow ran, the below-editor companion widget drove a full re-render roughly once per second (and on every store mutation); each re-render advanced that label, and once the detail card had scrolled above the viewport fold pi-tui took the full-screen-clear path (CSI 2J + CSI H + CSI 3J), read as whole-page + chat-box flicker. `stageActivityString()` now uses the threaded `now`, so scrollback run-detail cards are byte-stable across re-renders (the companion widget still owns the live, ticking view).
+- Fixed the `/workflow status` and `/workflow status <id>` chat-surface cards triggering a full-screen redraw (clear + scrollback wipe) every render tick once they scroll above the viewport fold. Their custom-message renderer's `render()` lambda re-runs on every TUI frame (pi-tui fans out to every child each `doRender`, and the live workflow/subagent widgets request a frame ~12×/sec while runs are active), and it called `renderStatusList` / `renderRunDetail` without a captured clock, so they fell through to `Date.now()` each frame and ticked the `elapsed` / `running` labels — and pi-tui full-clears the screen (CSI 2J + CSI H + CSI 3J) whenever a changed line sits above the fold, read as whole-screen flicker on terminals without synchronized output (e.g. mosh). The renderer now captures wall-clock once when the chat entry's component is created and threads it through to the status/detail renderers, so these point-in-time scrollback snapshots stay byte-stable across re-renders (the live widget still owns live state). Mirrors the earlier tool-result status-card fix.
+- Fixed answering a stage's brokered structured prompt (an in-stage `ask_user_question` or the readiness gate) via `/workflow send` replying **"User declined to answer questions"** and leaving the stage stuck `running` with no pending input — even though a real answer was sent. A structured `response` was forwarded verbatim to the `ask_user_question` tool: a JSON-encoded string was captured as raw free text, and — most damagingly — any object with an `answers` array (e.g. the orchestrator-friendly `{ answers: [{ question, answer }] }`) was treated as a pre-built `QuestionnaireResult` despite lacking the numeric `questionIndex` the tool envelope requires, so it matched no question segment and declined. `coerceStageInputAnswer` now forwards `raw` ONLY for a fully-formed result (every answer carries a numeric `questionIndex`); every other shape — JSON strings, `answers[]`/`questions[]` entries, flat `{ answer | label | selected }`, string arrays — is normalized to a label/index/multi-select value that the stage prompt adapter resolves against the question's options (assigning the correct `questionIndex`). The readiness decision (`readinessResultMeansAdvance`) matches the advance option case/whitespace-insensitively and via `selected[]`. A new regression test drives the real `StageUiBroker` + `ask_user_question` tool resolution path (the seam the earlier unit tests missed) and reproduces the decline for the `answers[]`-without-`questionIndex` payload. The "keep exploring"/stay path is unchanged ([#1099](https://github.com/flora131/atomic/issues/1099)).
+- Hardened the `/workflow` tool-result renderer against missing or unshaped payloads. `renderResult` is passed `result.details`, which can be absent during streaming/partial renders or on error paths, and previously dereferenced a missing `action` and crashed the TUI render loop. It now degrades gracefully (renders nothing for partials, a generic notice otherwise) ([#1099](https://github.com/flora131/atomic/issues/1099)).
+- Made `terminate: true` tool results deterministic when deriving a stage/task's result text: when an agent turn ends on a terminating tool, the stage runner now returns that tool result's output instead of any prose the model emitted before the tool call. This fixes the `goal` and `ralph` review gates, whose terminating `review_decision` structured-output tool emits clean JSON — previously the preceding assistant narration was captured instead, so the strict `JSON.parse` failed and a valid verdict was misclassified as a reviewer failure ("returned invalid structured JSON"), blocking quorum and forcing extra turns ([#1099](https://github.com/flora131/atomic/issues/1099)).
+- Tightened terminating-tool result detection when deriving a stage/task's result text. The stage runner now treats a trailing tool result as the deterministic turn output ONLY when that tool call actually returned `terminate: true` — tracked at runtime from the session's `tool_execution_end` events, since the tool-result message itself does not carry the flag — instead of whenever the last conversational message merely happened to be a tool result. A turn that ends on a non-terminating tool result (e.g. aborted or interrupted right after a tool call) now correctly falls back to the last assistant message, and that fallback no longer surfaces non-terminating tool output. Verified end-to-end against real `terminate: true`, `terminate: false`, and no-tool stages ([#1099](https://github.com/flora131/atomic/issues/1099)).
+- Fixed a mid-turn `ask_user_question` (or readiness gate) rendering but being input-dead in the attached stage chat. After a readiness-gate "stay" returns to the composer and the user submits another message, the agent's next question mounts while host keyboard focus has drifted off the overlay; the focus re-assertion was suppressed during streaming (a blunt guard added to avoid a prior continuation stall), so arrows/Enter were ignored and nothing could be answered or sent to the model. The overlay's `requestFocus` is now idempotent — it grabs focus only when the overlay does not already own it (`isFocused()`), so the redundant `focus()` that stalled the stream never runs. The stage chat now requests focus whenever a custom UI is shown (including mid-turn) and the focus-hold timer keeps a mounted question focused, trusting `requestFocus` to no-op when unnecessary ([#1120](https://github.com/flora131/atomic/issues/1120)).
+- Detaching or closing the attached stage chat (Ctrl+D / Ctrl+C) while a stage has a pending human-input request — an agent `ask_user_question` call or the readiness gate — no longer cancels that request. Previously, tearing down the chat view (or its stage UI broker host) rejected the pending prompt, so the stage silently dropped out of `awaiting_input` and the question disappeared. Detaching, closing, and disposing now only stop *displaying* the request: it stays pending (the stage remains `awaiting_input`) and is re-displayed when a host re-attaches. A pending request is settled only by the user answering (broker resolve) or the run aborting via its `AbortSignal` — the single chokepoints for ending a human-input request ([#1099](https://github.com/flora131/atomic/issues/1099)).
+
+## [0.8.20] - 2026-05-29
+
+### Changed
+
+- Promoted the 0.8.20 prerelease changes to a stable release.
+
 ## [0.8.20-0] - 2026-05-29
 
 ### Added

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.20-0",
+  "version": "0.8.21-0",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [