@bastani/atomic 0.9.19-alpha.1 → 0.9.19-alpha.3

package/docs/workflows/operations.md

@@ -27,6 +27,8 @@ Send material updates through Intercom to every affected workflow stage, includi
 
 At 80 columns and wider, each `BACKGROUND` card keeps the full run identity and preserves its mode, progress, live-tool details, and elapsed/status metadata. When the remaining single-row budget permits, it adds bounded pending-stage details: a target is either shown exactly or replaced by a `stage`-labeled canonical ID, and `… N more` reports omitted pending stages. If no bounded pending-stage form fits, the pending label is omitted entirely rather than displacing the existing metadata. Tool nodes are read-only durable graph nodes, not attachable stage chats. Below 80 columns, the panel keeps its aggregate collapsed form and omits run IDs, stage identities, targets, and tool names.
 
+The panel's stage progress includes recursively nested child workflows and updates as new stages appear. The numerator counts completed, failed, and skipped stages; the denominator counts all currently materialized stages, not future work. Expanded children replace their workflow boundary rather than counting both, and durable tool nodes are not stages. A failed, skipped, missing, or invalid child expansion keeps its boundary summary. `single`/`chain` follows this same stage count.
+
 For chat surfaces such as workflow status, run detail, dispatch confirmation, and the run picker, a full id wraps onto continuation rows when the card is narrower than the id. Pending-stage targets in run detail use the same rule: the exact address wraps instead of being ellipsized, and narrow status cards wrap the canonical stage ID or drop its display-name decoration rather than rendering a partial ID. The renderer keeps the card border closed at its minimum layout width, while terminals below that floor — including sub-30-column terminals — can hard-clip the box. An awaiting-input attribution banner is titled `AWAITING INPUT` and contains the same two identity rows — `？` plus the full run id, then the workflow name and optional metadata — while the existing prompt question and options remain below it in the normal prompt UI.
 
 The `/workflow connect` run picker shows five runs at a time; use the arrow keys or mouse wheel to scroll through additional retained runs.
@@ -161,7 +163,7 @@ Surface behavior:
 - **Wheel and trackpad** - While the workflow graph is active, vertical wheel/trackpad gestures pan it up and down, and horizontal gestures pan wide graphs left and right when the terminal exposes horizontal wheel events. Focused graph and stage-chat overlays receive those gestures through the fullscreen application route, so scrolling stays inside the active workflow surface instead of falling through to terminal or main-chat scrollback.
 - **Fullscreen mouse routing and selection** - A focused workflow graph or attached stage chat overlay receives wheel/trackpad and click input through the host's application-owned input route before the fullscreen viewport. Events the overlay does not consume fall through to pi-tui's viewport, while non-overlay focused components leave pi-tui's transcript scrolling, scrollbar interaction, and drag-selection path intact. Graph panning, stage-chat scrolling, node click-to-attach, and drag or multi-click selection therefore work without a separate selection mode. Copy uses OSC 52; terminals that refuse OSC 52 writes still support the modifier-drag bypass (Shift/Option, as provided by the terminal). `ctrl+t` is not a workflow control: focused workflow overlays leave it to the host `app.thinking.toggle` action, while inline tree selectors keep `app.tree.filter.noTools`.
 - **Tool and node detail** - Attached stage chats match main chat's tool-detail expansion behavior while keeping expansion state local to the workflow UI context. Press Ctrl+O (the configurable `app.tools.expand` binding) to expand every visible workflow node and tool card, including single, parallel, and nested subagent progress, current tool activity, and artifact paths; press it again to collapse them. The toggle works for active, completed, and archived stage views, including at the supported 40-column terminal minimum. A mounted prompt, custom question, or other input-owning overlay keeps the key instead of changing it.
-- **Footer context** - An attached live stage chat carries the main chat's current-folder and Git-branch identity into its themed footer and mirrors live extension status lines such as the MCP server indicator. Branch changes trigger a repaint through the host's cached footer provider, and extension status changes are read from that same provider rather than recomputed by the workflow UI.
+- **Footer context** - An attached live stage chat shows its own current folder and Git branch and mirrors live extension status lines such as the MCP server indicator. Branch changes trigger a repaint through the host's cached footer provider. The compact `/tasks` picker retains this context and the stage's model and reasoning level even while its foreground turn streams; detail, transcript, input, and confirmation pages remain fullscreen.
 - **Working animation lifecycle** - Ordinary attached-stage work keeps the same exact one-cell `∀` visible while following the active workflow theme's dark → accent → bright/bold → accent → dark luminance ramp every 88ms. Every agent and SDK turn resets to the dark regular phase with a fresh lifecycle-relative cadence; turn, terminal, error, replacement, and disposal cleanup stop the active timer without stale repaint. In an eligible retained-stage chat, every accepted idle follow-up — including a workflow-authored `stage.sendUserMessage(...)` after a prior turn ended — shows Working on admission or attach, including while Atomic restores a saved retained conversation, and keeps it through prompt startup, pre-turn compaction, and agent handoff. Attaching or remounting mid-delivery paints immediately rather than waiting for the turn's first event. A message queued into a live turn with `followUp`/`steer` uses that turn's existing status instead of starting a new one. A no-turn result, prompt or restore error, or terminal completion removes it; once the last accepted post-terminal delivery settles, a leftover start cannot bring it back. An accepted manual retry clears stale status from the prior prompt before showing new pre-stream activity. `NO_COLOR` retains regular/bold activity without foreground-color escapes. Reduced motion uses a static regular accent `∀` without an animation timer; factual automatic retry, fallback, compaction, cancellation, and error copy retains precedence.
 - **Subagent statusline** - If a subagent is running while the fullscreen workflow graph is open, the graph statusline mirrors its summary so the run remains visible; hide the graph with `h`, leave it with `ctrl+x`, or reconnect later to return to the full below-editor widget.
 - **Run control** - Use `interrupt`, `pause`, and `resume` for resumable live work. Pause/interrupt holds a stage's queued steering and follow-up items in place without dequeuing them or starting continuation; `resume` releases those items once in their existing per-queue order, but queue release alone does not start a model turn. `resume` on a non-paused run reopens the saved snapshot or overlay. Use `quit` to pause a live run gracefully while preserving it for `/workflow resume`.
@@ -176,6 +178,24 @@ At the supported 40-column terminal minimum, attached stage chats keep the `ctrl
 
 Human-in-the-loop prompts appear as awaiting-input nodes in the workflow graph, not as ordinary chat modals — see [Lifecycle Notices and Human Input](#lifecycle-notices-and-human-input) for how to find and answer them.
 
+### Skills in attached stage chats
+
+Use `/skill:<selector> [arguments]` in an editable stage composer, including qualified selectors such as `/skill:review@project`. Completion reads that stage's own resource catalog and `enableSkillCommands` setting, with the same source tags as main chat. The next completion request reflects a stage resource reload. If the host cannot expose stage command metadata, it reports discovery as unavailable instead of substituting main-chat resources.
+
+Suggestions use the terminal's default background, including selected rows; accent text and the selection arrow mark the current choice, matching main chat.
+
+Enter starts an idle turn or steers a streaming turn; Ctrl+F preserves follow-up delivery. The command stays bound to the submitted stage even if you switch panes. Its session performs the existing expansion once, including the selected skill's location, candidate identity, base directory, and trimmed arguments. Relative skill references use the skill directory; tools retain the stage cwd and restrictions. Manually typed commands still work when suggestions are disabled. Unknown bare selectors pass through unchanged, while qualified-resolution and file-read errors appear in the attached chat.
+
+Mounted HIL and custom prompts take precedence: a `/skill:` answer is literal prompt input. Blocked stages, read-only archives, and replay do not admit skill messages. Explicit editable [post-mortem chat](#post-mortem-chat-vs-execution-resume) can use its own skills, but cannot revive a workflow node or change the completed DAG. Skill invocation grants no additional delegation or tool authority and does not forward unrelated commands to the parent chat.
+
+`/tasks` opens the owner task list locally, never a skill or model message. Empty and populated lists use the same compact picker as main chat, without combining tasks from other chats. Enter inspects the selected task; focused actions offer retained transcript inspection, foreground waiting, confirmed cancellation, and stdin when available. Terminal tasks omit live actions. Escape returns to the picker with selection preserved, then to chat. A stage question arriving during inspection remains pending and is shown when you leave the inspector. Task navigation does not create a main-chat input-needed notice; genuine main-chat prompts waiting behind a visible graph still do.
+
+`/tasks` is also suggested in the stage slash menu independently of `enableSkillCommands`. Its [background-task status](/background-tasks) appears below MCP status; the graph-return shortcut does not overwrite the task-inspection hint. Pausing a workflow stage cancels its active and admitted queued background agents and commands and waits for cleanup. It blocks fresh launches immediately; already-in-flight command setup may briefly start during the transition but must drain and be cancelled before pause completes. Stage-scoped pause leaves main-chat tasks and sibling stages alone. Merely detaching the chat or ending a foreground turn does not cancel background work. Closing the stage generation still cancels remaining owned work.
+
+If inspection fails, the host displays the error and keeps your input for retry. It does not send the command to the model.
+
+The shared chat host owns this local-command dispatch, including during interrupt settlement. Its host callback is the task-inspector integration point; stage session extension commands named `/tasks` do not override this reserved view action. Skill completion itself reuses the attached session and does not checkpoint it on each keystroke. Tab also completes relative paths rooted at the stage session cwd; `@` file-mention suggestions are not available.
+
 ## Monitor and Control Runs
 
 The workflow tool exposes lifecycle controls for non-interactive use:
@@ -229,6 +249,8 @@ Control behavior:
 - `status` / `status <runId>` show terminal `ctx.exit(...)` statuses (`completed`, `skipped`, `cancelled`, or `blocked`) and the optional exit reason when one was supplied.
 - `stages` lists stage summaries, including flattened stages from nested `ctx.workflow(...)` imports and `sessionFile`/`transcriptPath` when a stage has a persisted session. Use `statusFilter: "all"` to include completed, failed, skipped, and pending stages.
 - `stage` returns details for one stage by exact stage id or exact stage name, including nested child stages shown in the expanded graph and the persisted `sessionFile` when available. User-facing graph and control messages print full stage IDs; pass one back verbatim, or use the stage's exact name. Prefixes and partial names no longer resolve. Two stages sharing an exact name return an ambiguity diagnostic rather than selecting one.
+- Local and retained/durable `stages` listings use the same expanded graph as `stage` and `transcript`: pass the listed ID back unchanged with that listing's `runId`. Valid nested boundaries are replaced by their descendants; missing, empty, or invalid children retain an inspectable boundary summary. Detail/transcript results identify the actual owning run and local stage ID.
+- Intercom's slash-separated `target` is a messaging address, not a `workflow` `stageId`. An Intercom stage row also includes its owning `runId` and local `stageId`; pass that pair to `stage` or `transcript`, or use the expanded ID from `workflow stages` with the root run ID.
 - `transcript` is reference-first with a small preview by default: it returns metadata, transcript paths, and up to 5 recent entries. For targeted lookup, quote the exact `sessionFile`/`transcriptPath` value without changing platform separators (preserve Windows backslashes), search it with `rg` or `grep`, then read only small surrounding ranges. Text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals. Pass explicit `tail` or `limit` to override the 5-entry preview; `tail` overrides `limit`; `includeToolOutput` includes captured snapshot tool output in snapshot transcript results.
 - `answer` responds only to a pending primitive or structured human-input prompt. It accepts `promptId` plus `response`, `text`, or `message`, preserves prompt-kind validation, and never sends stage chat, steers, resumes, or starts a model turn.
 - Send free-form updates through ordinary Intercom to `workflow:<rootRunId>/<segment>[/<segment>...]`; `*` matches one segment and `**` any depth. Use `intercom list` inside the invocation group to see live, pending, and possible future targets. Atomic delivers immediately to live stages and queues matching future stages, delivering them before their first model turn. `workflow:<rootRunId>/**` remains sticky for every future descendant until root termination; narrower name and pattern sends reach every future match. Valid paths outside the known set queue with a `notInKnownSet` warning and settle undeliverable at terminal only if never delivered. Use `ask` once the target has a reply-capable live session. Use `workflow resume` only for paused workflow control.
@@ -240,6 +262,7 @@ Control behavior:
 - A targeted tool abort reports the node outcome and the run separately: `status: "cancelled"` for the node it cancelled, `stageId` for that node, `abandoned` when the callback ignored its signal, and `workflowStatus` for the run status *observed* when the action returned. It never reports `paused`, and it never predicts what the run does next.
 - `pause` never accepts a tool node: `ctx.tool` has no turn boundary to stop at, so Atomic rejects it with `Tool nodes cannot be paused; ... Use interrupt or quit to abort it.` instead of a silent no-op.
 - `interrupt` and `pause` preserve resumable live work. With no active stage/tool handle (including initialization and between-node waits), they keep the same executor paused rather than quitting it. Run-level `resume` on that live process releases the barrier exactly once; later tracked steps, cached replay, and run completion wait for that explicit resume. An already-started untracked JavaScript await or non-cancellable I/O may still finish; pause cannot physically freeze arbitrary author code or roll back effects. A stage declared during this pause defers registration until its asynchronous method runs after resume; synchronous session access requires resume first.
+- A stage pause cancels that generation's owned task executions, not its queued messages or future workflow stages. User and Intercom messages remain held until resume; resume allows fresh tasks and never restarts the cancelled executions. Cancellation and cleanup failures reject the pause rather than reporting a successful stop.
 - A whole-run executor-only pause also holds already-live owned child workflows, including children with no tracked node yet. Resume persists the root's running transition before releasing those child executors; a child-scoped control leaves sibling workflows alone.
 - Live executor resume does not require a checkpoint. Cross-process resume still requires durable checkpoint or pending-prompt progress: losing a zero-progress live owner cannot reconstruct its JavaScript continuation. Cancelling the original startup request before acknowledgement remains terminal cancellation, not this live pause.
 - `resume` can target a stage with `stageId`; the target may be an exact stage id or an exact stage name. `message` is forwarded to paused work. For a live interrupted streaming prompt, Atomic preserves the existing prompt loop without duplicating the user message and injects `Continue where you left off. If you believe you are finished with your original task (or a redefined task if the user told you), stop.` when required before normal readiness-gate completion. For a paused stage that was idle waiting for a new stage-chat turn, a non-empty message resumes the stage and starts exactly one fresh prompt containing that message; an empty resume releases the pause without creating a prompt.
@@ -305,6 +328,27 @@ Workflow stage sessions and first-party subagent transcripts created inside them
 
 Passing a stage session's file path to `--session` still opens it explicitly. Classification requires exact `internal: true` plus complete run/stage metadata; malformed legacy markers and ordinary user forks remain in standard history. Legacy workflow sessions created before this marker behavior lack provable ownership and continue to appear until they age out.
 
+## Workflow activity for extensions
+
+Extensions can subscribe with `ctx.observeWorkflowActivity(observer)` and use the typed `workflow_lifecycle`, `workflow_activity_changed`, `workflow_stage_completed`, and `workflow_heartbeat` hooks. See [Workflow activity and lifecycle hooks](/extensions#workflow-activity-and-lifecycle-hooks) for the public types and subscription example.
+
+The workflows extension publishes activity for its owning session, folding nested runs into full root summaries. Observation is silent and independent of `workflowNotifications.enabled`, `notifyOn`, and the user/agent attribution filters used by chat notices. It neither wakes the model nor adds graph nodes. The built-in [Herdr reporter](/herdr) is one consumer: it reports these root states, combined with agent and approval-prompt activity, to the owning Herdr pane (see its [compatibility matrix](/herdr#compatibility)).
+
+| Runtime situation | Root activity |
+| --- | --- |
+| A stage or `ctx.tool` is executing | `working` |
+| One branch waits for human input while another executes | `working`, with `needsAttention: true` |
+| Only human input can advance the workflow | `blocked / awaiting_input` |
+| An active failure requires intervention, or a budget stop requires approval | `blocked / manual_intervention` |
+| Paused with no execution draining | `idle / paused` |
+| Quit or cancellation requested while work drains | `working / stopping`; independent sibling execution retains its own working reason |
+| Execution completed or intentionally stopped | `idle` |
+| A failed or blocked executor has ended without a pending prompt or budget approval | `idle / quiescent`, with `needsAttention: true`; the stored failure remains unchanged |
+
+Registration delivers an ordered initial snapshot, followed by structurally changed root replacements and removals. Late attachment reconstructs current activity; historical `running` records alone are not evidence of live execution. Durable catalog/resume hydration publishes `recovering` before awaiting the backend and `ready` afterwards. `recovering` and `unavailable` are unknown source states, not empty ready snapshots: do not interpret them as idle.
+
+Lifecycle targets identify runs, stages, tools, and prompts. Nested stage/tool ids use the expanded graph's `runId:nodeId` identity; `runId` still names the actual owning run and `rootRunId` names the aggregate. Control requests carry `action` and remain distinct from the status outcome. Prompt cancellation is not an answer. The completion convenience hook shares its event id with the corresponding successful stage lifecycle event and excludes failed/skipped stages. Only an explicit execution replay publishes `delivery: "replay"`; reading restored history never manufactures completion hooks. Heartbeats observe the existing configured scheduler cadence and do not prove execution.
+
 ## Lifecycle Notices and Human Input
 
 Atomic emits deduplicated main-chat notices when top-level workflow runs complete, fail, end blocked, or stop at an active recoverable provider/auth/rate-limit block. A recoverable block remains resumable (`status` surfaces and headless results report it as blocked even though the stored live snapshot stays active), is retained durably as blocked for cross-session resume, appears in the resume picker, and its notice says the workflow **is blocked** rather than implying terminal completion. Each blocked occurrence is deduped by its `blockedAt` timestamp, so a resumed workflow that hits another recoverable block re-notifies the invoking chat. Nested child workflow outcomes are reflected inside the expanded parent graph instead of producing separate top-level cards.
@@ -326,6 +370,8 @@ The visible card preserves the lifecycle custom type, raw notice text, exact det
 
 When an active recoverable block is resumed in-process, Atomic dispatches a fresh-ID continuation that replays the source's completed stages and re-runs the failed one. The durable source is left untouched (stays `blocked`/resumable) so it remains discoverable and recoverable, including a zero-checkpoint first-stage block, if the process dies before the continuation settles. The local source snapshot is killed when that continuation is admitted, so this session has one active run. A fail-closed topology mismatch puts the blocked snapshot back so the same session can retry. A process-local claim prevents a concurrent same-session double-dispatch.
 
+Ended recoverable blocks, including reviewer execution failures, use this same in-process continuation path. A resume response that only returns an unchanged blocked snapshot or refuses a non-resumable target reports no progress, not success. Inspect the returned continuation ID rather than assuming the original snapshot became running.
+
 Completed top-level `ctx.tool` nodes also replay into the fresh run. See [`ctx.tool` — durable cached tool execution](#ctxtool--durable-cached-tool-execution). A fail-closed topology mismatch ends that continuation; the durable source stays blocked and resumable, and the same session can retry after the continuation settles.
 
 Deliberate control actions on a top-level run report themselves too. `/workflow <name>` emits a `WORKFLOW STARTED` notice (`▶`), `/workflow pause` a `WORKFLOW PAUSED` notice (`⏸`, warning tone), `/workflow quit` a `WORKFLOW QUIT` notice (`⏹`, warning tone, carrying a `resumable` field), and `/workflow resume` a `WORKFLOW RESUMED` notice (`▶`). All four travel the same steer delivery, capped-backoff retry, and notice-card path as the failure notice. The paused and quit text states that the stop was deliberate and user-requested and tells the model not to resume the run or take the work over unless asked, with `/workflow resume <run-id>` as the card hint; the resumed text does not, because the run is progressing again.
@@ -704,7 +750,7 @@ Example config:
     "team": { "path": "./workflows/team.ts" },
     "shared": { "path": "/shared/team/workflows" }
   },
-  "defaultConcurrency": 4,
+  "defaultConcurrency": 3,
   "maxDepth": 4,
   "budget": { "maxDurationMs": 0, "maxTokens": 0, "maxCost": 0, "warnAtPercent": 80 },
   "persistRuns": true,
@@ -724,7 +770,7 @@ Runtime config defaults:
 
 | Key | Default | Purpose |
 |-----|---------|---------|
-| `defaultConcurrency` | `4` | Default concurrency for authored `ctx.parallel(...)` execution |
+| `defaultConcurrency` | `3` | Default stage concurrency and concurrency for authored `ctx.parallel(...)` execution |
 | `maxDepth` | `4` | Maximum workflow nesting depth |
 | `budget` | `{ maxDurationMs: 0, maxTokens: 0, maxCost: 0, warnAtPercent: 80 }` | Default per-run budget declaration; `0` disables a dimension; warnings default to `80` percent |
 | `persistRuns` | `true` | Persist run metadata for status/resume/history |

package/docs/workflows/reliable-design.md

@@ -2,7 +2,7 @@
 
 Use this guide to turn an objective into an acyclic, evidence-producing workflow with explicit contracts, context boundaries, verification, and stop conditions. Read [Custom Workflow Authoring](/workflows/authoring) first if you have not built a workflow definition yet.
 
-First honor the user's task-scoped [execution-mode choice](/workflows/verification#execution-mode). Explicit inline/no-workflow requests override the routing rubric below, including complex tasks and review loops; preserve the same safety and verification bar without creating a hidden workflow. For workflow authoring, carry the [domain/environment verification and media evidence contract](/workflows/verification) into worker, reviewer and final handoff prompts.
+First honor the user's task-scoped [execution-mode choice](/workflows/verification#execution-mode). Requests to do the task "quickly" or "inline", or not to use a workflow, override the routing rubric below, including complex tasks and review loops. Preserve the same safety and verification bar without creating a hidden workflow. Descriptions of software that should run quickly are not execution-mode instructions. For workflow authoring, carry the [domain/environment verification and media evidence contract](/workflows/verification) into worker, reviewer and final handoff prompts.
 
 ## Choosing an Execution Shape
 
@@ -67,6 +67,37 @@ A first named workflow launch commits the selected execution shape for the turn.
 
 Choose the cheapest complete graph. Routing cues are not a reason to add decorative stages: avoid duplicated research and review loops. Before launch, state the selected graph, why one broad builtin is sufficient or insufficient, the evidence each major stage produces, and the stop/repair conditions. A simple direct match can be one sentence; a composed graph should briefly name its children and task-specific gates.
 
+### Runtime-aware scheduling and estimates
+
+Treat workflow runtime as a dependency-constrained task-scheduling problem. Optimize elapsed time while preserving the evidence and approval contract, not by deleting gates or minimizing node count.
+
+During the short architecture pass, inspect project scripts and available historical runtimes from comparable CI jobs, test-suite reports, and prior workflow stages. For GitHub projects, recent run/job timings and uploaded test-duration reports can provide evidence. Record the source links or artifact paths, sample size and range, runner/cache differences, and missing data. Do not run the full suite just to collect an estimate or turn timing reconnaissance into a separate research project.
+
+Use a compact schedule alongside the coverage matrix:
+
+```text
+node | prerequisites | duration range and source | shared resources | evidence needed by
+```
+
+- Estimate the critical path, the longest dependency path, rather than adding all parallel node durations. Account for bounded concurrency, runner queues, environment setup, model variability, retries, and resource contention. More parallel jobs can be slower when they compete for the same resources.
+- Put focused tests and necessary build/type/contract checks at each implementation slice. When repeated full-suite runs add no required evidence, run the full suite once on the final candidate instead of after every stage. Preserve mandatory per-slice checks, required CI contexts, approval gates, and repair reruns. Each slice must still pass its own gates before dependent work starts.
+- Start long CI/check waits when their candidate is ready and overlap independent review, documentation, or handoff preparation that neither mutates that candidate nor needs its check results. Use supported concurrency, keep workflow-owned CI launch/wait/result checks in durable `ctx.tool` nodes with finite timeouts and cancellation, and join required results before acceptance, merge, or publication. Background admission is not check completion.
+- Record the checked commit or artifact identity. Later edits invalidate affected results, so rerun those checks for the new candidate. Never reuse a green check from an older commit as proof for a changed head. Do not alter repository protections, required checks, or concurrency limits to shorten the estimate.
+
+Before launching a workflow, give the user an estimated wall-clock completion range without confidence labels or scores. Cite available timing sources and distinguish measured checks from estimated model work, queue/repair uncertainty, and human wait time. If history is missing, state that briefly rather than inventing metrics. An estimate is not a `budget` override or a promise.
+
+Proceed with inherited budget limits without asking the user to choose a budget before each launch; preserve existing budget limits and approval gates. Omit `budget` unless the user specified a limit, inheriting the workflow declaration and config. When the user does state a limit, pass only the fields they named, leave every other field inherited, and use `0` only for a field the user asked to disable. Never convert an estimate into a cap.
+
+For example, with hypothetical timings, 6 minutes of implementation followed by independent 12-minute CI and 4-minute read-only review branches, then a 1-minute handoff, has a 19-minute critical path, not a 23-minute sum. Queue delays, repairs, and human approval can extend that. Real launch estimates must cite actual project evidence rather than reuse these illustrative numbers.
+
+Revise the remaining-time estimate at lifecycle updates only when new evidence materially changes the path. Keep the normal heartbeat cadence and end-turn/no-polling rules. At completion, report actual elapsed time against the estimate and identify the main bottleneck to improve the next schedule. These are agent design/reporting instructions, not an automatic scheduler or ETA feature.
+
+### Questions and approvals
+
+When `ask_user_question` or an equivalent question tool is available, all agent-authored questions to the user must use that tool instead of plain text, including clarification, confirmation, and permission to proceed. Prefer `ask_user_question` when available; otherwise follow the equivalent tool's supported schema. In these sessions, do not append a prose-only "Proceed?" to a status update. Ask only for needed decisions, not repeat approval of already-authorized work. See the [question tool guidance and confirmation example](/tools#ask_user_question).
+
+Workflow-authored `ctx.ui` gates remain supported. `workflow answer` relays an actual user response to a pending prompt; it does not grant authority to choose an approval on the user's behalf. Intercom questions are for agents, not a substitute for user approval. If no usable question tool is available, continue autonomously using best judgment and record evidence-backed assumptions. Tool unavailability alone is not a blocker. Preserve safety, authorization, explicit approval gates, and budget limits. A cancelled or unanswered question is not approval.
+
 ### Stage model and thinking-level assignment
 
 Before launching an authored workflow, assign every model stage a **role**, **failure cost**, **primary model**, **thinking level**, and **fallback policy**. Read [Model Selection](/models/model-selection) for the role defaults and [Evals](/models/evals) for the measured per-evaluation scores — its task-type picker maps each stage type (terminal debugging, knowledge-work planning, tool-calling loops, document research, code-reading review) to the eval that measures it and the models that lead it — but treat thinking levels in benchmark rows as measurement configurations, not production defaults. Reserve `max` for high-cost-of-error roles or an explicit user request; use `high` for demanding mapping, lifecycle analysis, compatibility, planning, synthesis, triage, and repair; use `medium` for user-impact review and final reporting; and keep deterministic checks as tool nodes with no model call.
@@ -143,7 +174,7 @@ Interpretation:
 - **7+ total, or Iteration = 2, or Verifiability = 2 with a review/approval gate:** a real workflow. Prefer a named workflow when one fits the whole task; otherwise author a custom graph, nesting proven children where sub-problems overlap.
 - **Any single hard signal overrides the arithmetic:** an explicit loop/stop condition, an approval or evidence gate, or a request for durable/background execution puts the task in workflow territory regardless of total score.
 
-When workflow execution is permitted, use the rubric to select tracked implementation/review loops and transfer bounded reconnaissance through `reads`. It does not override an explicit inline request. In either mode, stop unbounded reconnaissance by recording findings and taking the next concrete in-scope action.
+When workflow execution is permitted, use the rubric to select tracked implementation/review loops and transfer bounded reconnaissance through `reads`. It does not override a request to do the task quickly or inline. In either mode, stop unbounded reconnaissance by recording findings and taking the next concrete in-scope action.
 
 ### Task queues and software factories
 
@@ -374,7 +405,7 @@ The factory self-prompt is: **enumerate → inspect and classify dependencies
 
 Humans can steer the shape directly:
 
-- **Name the shape or installed workflow.** "Do this inline", "use subagents to investigate", or "write a custom workflow for this" overrides automatic scoring.
+- **Name the shape or installed workflow.** "Do this quickly", "do this inline", "use subagents to investigate", or "write a custom workflow for this" overrides automatic scoring.
 - **State acceptance criteria.** Verbatim criteria make the objective provable and define reviewer and reducer contracts.
 - **State the loop.** "Iterate until tests pass" or "review and fix until approved" defines a hard workflow stop condition.
 - **State the evidence.** A QA video, test output, generated artifact, or reviewer sign-off tells the graph which gates it needs.
@@ -1004,7 +1035,7 @@ Pass file references, not content. This is the strongly encouraged default for e
 
 Three rules make that work in practice:
 
-1. **One owner per artifact.** The runner writes the stage's final assistant message to `output` after the stage ends, automatically writes the companion transcript outside the repository tree, and appends one instruction telling the model that its final message becomes the artifact. Your prompt does not need to restate any of that — describe the deliverable, not the plumbing. If a late admitted turn displaces the intended content, search the transcript with `rg` rather than assuming the curated artifact holds every later turn. A prompt may write other files freely; only the declared `output` path is runner-owned and overwritten at stage end.
+1. **One owner per artifact.** The runner writes the stage's completed answer to `output` and appends later completed answers from the same generation as numbered supplements. This preserves a report when an admitted clarification arrives before generation close, without copying tool progress or earlier history into the artifact. Completed handoffs are immutable under later chat. State corrections explicitly, and use a new tracked stage and output path for an intentional replacement. The runner also writes the companion transcript outside the repository and tells the model the output contract. Describe the deliverable in your prompt, not the plumbing. Search the transcript with `rg` for supporting details that belong outside the curated artifact.
 2. **Do not read an artifact back just to return it.** `outputMode: "file-only"` exists so the parent receives a compact reference. Calling `readFile` on that artifact and returning its text as a workflow output cancels the saving and drops the whole report into the caller's context window. Return the reference and a `*_path` output instead.
 3. **Return paths from the workflow.** Declared outputs are consumed by the calling session, so a workflow's `result` should be a reference plus explicit `*_path` outputs. Callers that need the body read the path; callers that only need the outcome pay nothing for it. When a detail is missing from the curated artifact, search its companion transcript with `rg` and inspect a narrow range.
 

package/docs/workflows/verification.md

@@ -4,14 +4,16 @@ Use executable verification appropriate to the changed behavior. Workflow author
 
 ## Execution mode
 
-An explicit request to work `inline`, `do this directly`, `don't use a workflow`, or equivalent overrides workflow-first defaults for that task, including complex implementation and review loops. Do not create or launch a hidden or nested replacement workflow, or ask the user to reapprove the choice. Keep appropriate testing, review and evidence inline. Safety and authorization requirements do not change.
+An explicit request to work `quickly`, `inline`, `do this directly`, `don't use a workflow`, or equivalent overrides workflow-first defaults for that task, including complex implementation and review loops. Treat "quickly" as an inline execution choice, not a request for a faster workflow. Do not create or launch a hidden or nested replacement workflow, or ask the user to reapprove the choice. Keep appropriate testing, review and evidence inline. Safety and authorization requirements do not change.
 
-Apply the preference only to its stated task. Quoted examples and questions about inline code are not execution-mode instructions. Without an opt-out, normal workflow fit defaults apply.
+Apply the preference only to its stated task. Quoted examples and questions about inline code are not execution-mode instructions; neither are descriptions of software that should run quickly. Without an opt-out, normal workflow fit defaults apply.
 
 If the user switches during an active workflow, safely hold or stop the affected run using its available lifecycle controls. Reconcile completed work and in-flight side effects before continuing inline so commands and external writes are not duplicated. Stages notify the controlling session rather than launching a replacement. Already-completed work remains completed; do not claim it was undone.
 
 ## Select the verification environment
 
+The same routing applies when a user asks for automation outside a verification workflow. Use PyAutoGUI for desktop computer use, also called CUA, and the playwright-cli skill for browser automation. Prefer herdr for terminal automation/testing on macOS, Linux and Windows. Install it if missing when network access and permissions permit; fall back to tmux or native Windows psmux when installation or use is not possible. Load the matching skill before acting. The pinned upstream herdr skill still requires an explicit user mention or request and `HERDR_ENV=1`; preference does not authorize control from outside a Herdr-managed pane. Keep desktop failsafes enabled and release held keys/buttons after interruption.
+
 Inspect installed tools, cached runtimes, existing sessions and safe test configuration first. Install missing tools/plugins when online access and permissions permit. Known offline or restricted installation is enough reason not to attempt a prohibited download. Otherwise make a reasonable capability check or one bounded setup attempt, not an endless installation retry loop.
 
 When a mechanism cannot run, continue available authoritative repository checks, retain useful local evidence, and record the constraint, attempted commands and observed output, narrower validation and missing coverage. Do not require production credentials or take unsafe actions to satisfy a generic verification suggestion. An unavailable optional mechanism is not failed implementation, but it does not waive a required project check.
@@ -19,16 +21,31 @@ When a mechanism cannot run, continue available authoritative repository checks,
 | Changed behavior | Verification and evidence |
 | --- | --- |
 | Browser/frontend, including API-dependent flows | Use the playwright-cli skill. Exercise the real user flow and assert its result. Retain current screenshots, video, DOM snapshots or network evidence as appropriate. |
-| TUI/terminal | Use tmux on supported hosts, native Windows psmux, or herdr where available and appropriate. Exercise actual interactive input and inspect pane output or a terminal recording. These tools do not have interchangeable CLIs. |
-| Desktop/simulator/emulator | Use suitable PyAutoGUI or native platform tools against a real visible app scenario. Capture screenshots/video from that environment, not a browser recording labeled as desktop or iOS proof. |
+| TUI/terminal | Prefer the herdr skill on macOS, Linux and Windows under its explicit-request and managed-pane requirements. Install if missing when permitted; fall back to the tmux skill or native Windows psmux if unavailable or unusable. Exercise actual interactive input and inspect pane output or a terminal recording. These tools do not have interchangeable CLIs. |
+| Desktop/simulator/emulator | Use PyAutoGUI for desktop CUA, with native platform tools where they provide safer input or better assertions. Capture screenshots/video from a real visible app scenario, not a browser recording labeled as desktop or iOS proof. |
 | Non-UI | Run relevant unit, integration, build, type or command-line scenarios. Do not manufacture a UI or video requirement. |
 
 ### Terminal contracts
 
+Herdr supports macOS, Linux and Windows. Check `herdr --version` and, inside a managed pane, `herdr status` before installing or relying on server features. If missing, use the [official installation instructions](https://github.com/herdrdev/herdr/tree/v0.9.0#install): `brew install herdr` on macOS, the reviewed `https://herdr.dev/install.sh` installer on macOS/Linux, or `https://herdr.dev/install.ps1` on Windows. Inspect downloaded installer code before executing it, follow host permissions and use a bounded setup attempt. Do not stop or replace a running server to make a test work. If installation is blocked or no eligible Herdr session is available, record the constraint and use tmux/psmux rather than taking over the focused session.
+
 [psmux](https://github.com/psmux/psmux) is a native Windows ConPTY multiplexer using tmux-style commands. Its [scripting guide](https://github.com/psmux/psmux/blob/master/docs/scripting.md) documents `psmux capture-pane -p -t %0` for stdout capture. Verify installed help and use the actual pane identifier rather than assuming `%0` belongs to the test.
 
 [herdr's CLI](https://herdr.dev/docs/cli-reference/) talks to a running server. Discover your isolated test pane with `herdr pane list`. `herdr pane run <pane_id> <command>` submits a command with Enter; `herdr pane send-text` alone does not submit. `herdr pane read <pane_id> --source visible` returns the screen text. For bounded waits use `herdr pane wait-output <pane_id> --match <text> --timeout 10000`. Do not confuse pane output with an agent lifecycle status or infer success from `idle`. Check installed version/help and host support before use. Do not take over unrelated panes.
 
+### Reproduce stage skill terminal evidence
+
+From an Atomic source checkout, install dependencies with `npm ci --ignore-scripts` and run `npm run build`. With Node, Bun, tmux and a POSIX shell on PATH, run the committed driver:
+
+```sh
+node test/fixtures/stage-chat-skill-driver.mjs --evidence-dir /tmp/stage-skills-80 --columns 80 --rows 24
+node test/fixtures/stage-chat-skill-driver.mjs --evidence-dir /tmp/stage-skills-48 --columns 48 --rows 16
+```
+
+Use a fresh evidence directory for each run; existing directories are refused. The driver executes `test/fixtures/stage-chat-skill-terminal.ts` directly with Bun, not `bun build`. No provider credentials are needed. It waits for the real editor to clear and the notice to render after each `/tasks` command before typing the next command, then verifies stage-local skill selection and invocation. Captures, assertions, render barriers and session events stay in the requested directory. Failures retain diagnostics and clean up the dedicated tmux session.
+
+The small driver contract tests run in the normal unit suite. The actual tmux scenario is an explicit local verification command, not an automatic CI terminal test. This POSIX driver does not establish Windows coverage.
+
 ### Desktop safety
 
 The [OpenAI CUA sample](https://github.com/openai/openai-cua-sample-app#first-run) distinguishes JavaScript Playwright browser control from Python PyAutoGUI desktop input. It is an optional sample requiring API/model access, not a prerequisite for every GUI test. Follow its [Python quickstart and interruption guidance](https://github.com/openai/openai-cua-sample-app/blob/main/python-app/README.md).

package/docs/workflows.md

@@ -42,7 +42,7 @@ Prefer composing builtin definitions with `ctx.workflow(...)` over copying or re
 
 ## When to Use Workflows
 
-Unless the user explicitly chooses inline execution, workflows are the default for non-trivial requests or structured work with a verifiable objective. Requests such as `inline`, `do this directly`, and `don't use a workflow` override that default for the specified task, even when complex. Do not launch a hidden/nested replacement or ask the user to reapprove the choice. Preserve testing, review, evidence, safety and authorization inline. Quoted examples and questions about inline code are not mode instructions. For an active switch, safely hold/stop the affected run and reconcile completed work and in-flight effects before continuing without duplicates; completed work is not undone. See [Verification and evidence](/workflows/verification).
+Unless the user explicitly chooses inline execution, workflows are the default for non-trivial requests or structured work with a verifiable objective. Requests such as `quickly`, `inline`, `do this directly`, and `don't use a workflow` override that default for the specified task, even when complex. Treat "quickly" as an inline execution choice, not a request for a faster workflow. Do not launch a hidden/nested replacement or ask the user to reapprove the choice. Preserve testing, review, evidence, safety and authorization inline. Quoted examples, questions about inline code, and descriptions of software that should run quickly are not mode instructions. For an active switch, safely hold/stop the affected run and reconcile completed work and in-flight effects before continuing without duplicates; completed work is not undone. See [Verification and evidence](/workflows/verification).
 
 When no opt-out was given, workflow signals include:
 
@@ -60,6 +60,8 @@ Workflow-first does not require builtins, monolithic workflows, or a force-fit b
 
 Rich custom workflows can compose the [common workflow patterns](/workflows/reliable-design#common-workflow-patterns): classify and branch at runtime, fan out and synthesize artifacts, run worker/verifier/reducer repair cycles, generate and filter or tournament-rank candidates, and loop until explicit evidence says the work is done. Workflow definitions are composable TypeScript modules — see [Workflow Composition](/workflows/authoring#workflow-composition). Atomic can write the definition, reload workflow resources, and run it for the current task; the workflow tool has no create action.
 
+Design for elapsed time using [runtime-aware scheduling and estimates](/workflows/reliable-design#runtime-aware-scheduling-and-estimates). Use available CI/test history to place focused checks at slice boundaries, defer redundant full-suite runs to the final candidate, and overlap independent work with CI without bypassing required gates. Before launch, report a completion range without confidence labels or scores. Inherit existing budget limits without asking for a budget choice before each launch, and override only limits the user explicitly requests. Preserve existing approval gates. An estimate is not a budget. At completion, compare the estimate with actual elapsed time.
+
 If exploration drifts without progress, save findings and choose a concrete next action. Transfer them through `reads` to a fitting workflow when permitted; continue directly with appropriate validation when inline was requested.
 
 | User need | Use |