@bastani/atomic 0.8.14 → 0.8.15-0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [0.8.15-0] - 2026-05-25
+
+### Breaking Changes
+
+- Changed workflow `ctx.ui.*` prompts to render as synthetic graph stage nodes with `awaiting_input` status, including new `StageSnapshot.promptAnswerState` metadata.
+- Changed `ctx.ui.select(..., [])` to throw before creating a prompt node instead of returning an empty string.
+
+### Added
+
+- Added live-memory prompt answer replay for workflow continuations.
+- Added workflow control and subagents documentation updates, plus bundled docs link validation.
+
+### Changed
+
+- Updated Ralph around an autonomous goal contract so stages infer verifiable criteria, require receipts, and judge completion against the verification oracle.
+- Updated Ralph to discover project initialization needs from repository evidence before implementation work proceeds.
+
+### Fixed
+
+- Returned the workflow overlay to the graph orchestrator after answering or skipping a `ctx.ui` prompt node.
+- Stopped eagerly starting MCP OAuth callback handling during session startup.
+- Carried forward bundled subagent fixes for nested fanout state, child allowlists, async runner config permissions, fallback models, read-only guard overrides, Windows child process spawning, stable running glyphs, and recovered intermediate child errors.
+
 ## [0.8.14] - 2026-05-25
 
 ### Changed

package/README.md

@@ -9,12 +9,6 @@
   <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
   <a href="https://www.npmjs.com/package/@bastani/atomic"><img alt="npm" src="https://img.shields.io/npm/v/@bastani/atomic?style=flat-square" /></a>
 </p>
-<p align="center">
-  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
-  <br /><br />
-  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
-</p>
-
 > New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ---
@@ -344,8 +338,6 @@ Place in `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, or `.agents/
 
 ### Extensions
 
-<p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
-
 TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
 
 ```typescript

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.14",
+  "version": "0.8.15-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,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Stopped eagerly starting MCP OAuth callback handling during session startup, preventing non-blocking OAuth initialization failures from surfacing as workflow/orchestrator errors.
+
 ## [2.6.1] - 2026-05-13
 
 ### Added

package/dist/builtin/mcp/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ToolInfo } from "@bastani/atomic";
+import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@bastani/atomic";
 import type { McpExtensionState } from "./state.ts";
 import { Type } from "typebox";
 import { showStatus, showTools, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
@@ -8,7 +8,7 @@ import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
 import { loadMetadataCache } from "./metadata-cache.ts";
 import { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.ts";
 import { getConfigPathFromArgv, truncateAtWord } from "./utils.ts";
-import { initializeOAuth, shutdownOAuth } from "./mcp-auth-flow.ts";
+import { shutdownOAuth } from "./mcp-auth-flow.ts";
 import { renderMcpToolResult } from "./tool-result-renderer.ts";
 
 export default function mcpAdapter(pi: ExtensionAPI) {
@@ -104,10 +104,6 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       return;
     }
 
-    await initializeOAuth().catch(() => {
-      console.error("MCP OAuth initialization failed");
-    });
-
     const promise = initializeMcp(pi, ctx);
     initPromise = promise;
 
@@ -264,7 +260,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         action: Type.Optional(Type.String({ description: "Action: 'ui-messages' to retrieve prompts/intents from UI sessions" })),
       }),
       renderResult: renderMcpToolResult,
-      async execute(_toolCallId, params: {
+      async execute(_toolCallId: string, params: {
         tool?: string;
         args?: string;
         connect?: string;
@@ -274,7 +270,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         includeSchemas?: boolean;
         server?: string;
         action?: string;
-      }, _signal, _onUpdate, _ctx) {
+      }, _signal: AbortSignal | undefined, _onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, _ctx: ExtensionContext) {
         let parsedArgs: Record<string, unknown> | undefined;
         if (params.args) {
           try {

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.14",
+  "version": "0.8.15-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.14",
+  "version": "0.8.15-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/subagents/skills/tmux/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: tmux
+description: "Control tmux-compatible sessions/windows/panes for interactive CLIs: list, capture output, send keys, paste text, monitor prompts."
+metadata:
+  {
+    "atomic":
+      {
+        "os": ["darwin", "linux", "windows"],
+        "requires": { "bins": ["tmux", "psmux"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "tmux",
+              "bins": ["tmux"],
+              "label": "Install tmux (brew)",
+            },
+            {
+              "id": "winget-psmux",
+              "kind": "winget",
+              "package": "psmux",
+              "bins": ["tmux"],
+              "label": "Install psmux (WinGet)",
+            },
+            {
+              "id": "cargo-psmux",
+              "kind": "cargo",
+              "crate": "psmux",
+              "bins": ["tmux"],
+              "label": "Install psmux (Cargo)",
+            },
+            {
+              "id": "scoop-psmux",
+              "kind": "scoop",
+              "bucket": "https://github.com/psmux/scoop-psmux",
+              "package": "psmux",
+              "bins": ["tmux"],
+              "label": "Install psmux (Scoop)",
+            },
+            {
+              "id": "choco-psmux",
+              "kind": "choco",
+              "package": "psmux",
+              "bins": ["tmux"],
+              "label": "Install psmux (Chocolatey)",
+            },
+          ],
+      },
+  }
+---
+
+# tmux
+
+Use for existing interactive tmux sessions. For one-shot commands, use normal shell. For new non-interactive background jobs, use background execution.
+
+On Windows, use [psmux](https://github.com/psmux/psmux), the native Windows tmux-compatible multiplexer. psmux automatically provides the `tmux` alias, so keep using the `tmux` commands below; no command changes are needed.
+
+When this skill is invoked, first confirm `tmux` is available before running tmux commands (`command -v tmux` or `tmux -V`; on Windows PowerShell, `Get-Command tmux`). If `tmux` is not found, tell the user to install tmux on macOS/Linux or psmux on Windows, depending on their OS, using one of the options below.
+
+## Installation
+
+Choose the install path that matches the host OS and package manager.
+
+### macOS/Linux tmux
+
+Package managers are preferred when available:
+
+```bash
+brew install tmux
+```
+
+To build official tmux from a release tarball, install `libevent` 2.x, `ncurses`, a C compiler, `make`, `pkg-config`, and `yacc` or `bison`, then run:
+
+```bash
+./configure && make
+sudo make install
+```
+
+To build the latest tmux from version control, also install `autoconf` and `automake`:
+
+```bash
+git clone https://github.com/tmux/tmux.git
+cd tmux
+sh autogen.sh
+./configure && make
+sudo make install
+```
+
+### Windows psmux
+
+psmux installs `psmux`, `pmux`, and `tmux`; this skill should continue to use `tmux` in examples and scripts.
+
+```powershell
+winget install psmux
+cargo install psmux
+scoop bucket add psmux https://github.com/psmux/scoop-psmux
+scoop install psmux
+choco install psmux
+```
+
+Alternatively, download the latest `.zip` from GitHub Releases and add it to `PATH`, or build from source with Cargo:
+
+```powershell
+git clone https://github.com/psmux/psmux.git
+cd psmux
+cargo build --release
+```
+
+## Basics
+
+```bash
+tmux ls
+tmux list-windows -t shared
+tmux list-panes -t shared:0
+tmux capture-pane -t shared:0.0 -p
+tmux capture-pane -t shared:0.0 -p -S -
+```
+
+Target format: `session:window.pane`, e.g. `shared:0.0`.
+
+## Send input
+
+Literal text, then Enter:
+
+```bash
+tmux send-keys -t shared:0.0 -l -- "Please continue"
+tmux send-keys -t shared:0.0 Enter
+```
+
+Special keys:
+
+```bash
+tmux send-keys -t shared:0.0 C-c
+tmux send-keys -t shared:0.0 C-d
+tmux send-keys -t shared:0.0 Escape
+```
+
+Use `-l --` for arbitrary text. Split text and Enter to avoid paste/newline surprises.
+
+## Sessions
+
+```bash
+tmux new-session -d -s worker
+tmux rename-session -t old new
+tmux kill-session -t worker
+```
+
+## Prompt checks
+
+```bash
+tmux capture-pane -t worker-3 -p | tail -20
+tmux capture-pane -t worker-3 -p | rg "proceed|permission|Yes|No|❯"
+```
+
+Approve/select only when the prompt is understood:
+
+```bash
+tmux send-keys -t worker-3 -l -- "y"
+tmux send-keys -t worker-3 Enter
+```
+
+## QA/testing and analysis
+
+Prefer read-only inspection before sending input. These commands are especially useful for diagnosing interactive tests, stuck agents, TUI apps, and long-running CLI workflows.
+
+Discover every pane with useful state:
+
+```bash
+tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_command} #{pane_current_path} active=#{pane_active} dead=#{pane_dead}'
+```
+
+Capture output for assertions or log review:
+
+```bash
+tmux capture-pane -t shared:0.0 -p -S -          # full scrollback
+tmux capture-pane -t shared:0.0 -p -S - -J       # join wrapped lines
+tmux capture-pane -t shared:0.0 -p -S -1000      # recent output only
+tmux capture-pane -t shared:0.0 -p -e -S -1000   # include escape/color codes for TUI debugging
+```
+
+Inspect what a pane is running:
+
+```bash
+tmux display-message -p -t shared:0.0 '#{pane_current_command} #{pane_current_path} pid=#{pane_pid}'
+tmux show-messages
+```
+
+Stream pane output to a file for later analysis without interrupting the process:
+
+```bash
+tmux pipe-pane -t shared:0.0 -o 'cat >> /tmp/tmux-pane-shared-0-0.log'
+```
+
+Coordinate tests or scripts with tmux signals:
+
+```bash
+tmux wait-for qa-ready      # wait
+tmux wait-for -S qa-ready   # signal
+```
+
+Keep failed commands visible and label panes for easier reports:
+
+```bash
+tmux set-option -t shared remain-on-exit on
+tmux select-pane -t shared:0.0 -T "api-tests"
+```
+
+If a tmux-compatible implementation does not support a specific format variable or option, fall back to the simpler `list-panes`, `capture-pane`, and `send-keys` forms above.
+
+## Helpers
+
+- `scripts/find-sessions.sh`: discover sessions.
+- `scripts/wait-for-text.sh`: wait until pane output contains text.
+
+## Notes
+
+- `capture-pane -p` prints to stdout for scripts.
+- `-S -` captures full scrollback.
+- tmux sessions persist across SSH disconnects.

package/dist/builtin/subagents/skills/tmux/scripts/find-sessions.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+  -L, --socket       tmux socket name (passed to tmux -L)
+  -S, --socket-path  tmux socket path (passed to tmux -S)
+  -A, --all          scan all sockets under ATOMIC_TMUX_SOCKET_DIR
+  -q, --query        case-insensitive substring to filter session names
+  -h, --help         show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${ATOMIC_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/atomic-tmux-sockets}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -L|--socket)      socket_name="${2-}"; shift 2 ;;
+    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+    -A|--all)         scan_all=true; shift ;;
+    -q|--query)       query="${2-}"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+  echo "Cannot combine --all with -L or -S" >&2
+  exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+  echo "Use either -L or -S, not both" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+list_sessions() {
+  local label="$1"; shift
+  local tmux_cmd=(tmux "$@")
+
+  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+    echo "No tmux server found on $label" >&2
+    return 1
+  fi
+
+  if [[ -n "$query" ]]; then
+    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+  fi
+
+  if [[ -z "$sessions" ]]; then
+    echo "No sessions found on $label"
+    return 0
+  fi
+
+  echo "Sessions on $label:"
+  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+  done
+}
+
+if [[ "$scan_all" == true ]]; then
+  if [[ ! -d "$socket_dir" ]]; then
+    echo "Socket directory not found: $socket_dir" >&2
+    exit 1
+  fi
+
+  shopt -s nullglob
+  sockets=("$socket_dir"/*)
+  shopt -u nullglob
+
+  if [[ "${#sockets[@]}" -eq 0 ]]; then
+    echo "No sockets found under $socket_dir" >&2
+    exit 1
+  fi
+
+  exit_code=0
+  for sock in "${sockets[@]}"; do
+    if [[ ! -S "$sock" ]]; then
+      continue
+    fi
+    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+  done
+  exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+  tmux_cmd+=(-L "$socket_name")
+  socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+  tmux_cmd+=(-S "$socket_path")
+  socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"

package/dist/builtin/subagents/skills/tmux/scripts/wait-for-text.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+  -t, --target    tmux target (session:window.pane), required
+  -p, --pattern   regex pattern to look for, required
+  -F, --fixed     treat pattern as a fixed string (grep -F)
+  -T, --timeout   seconds to wait (integer, default: 15)
+  -i, --interval  poll interval in seconds (default: 0.5)
+  -l, --lines     number of history lines to inspect (integer, default: 1000)
+  -h, --help      show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--target)   target="${2-}"; shift 2 ;;
+    -p|--pattern)  pattern="${2-}"; shift 2 ;;
+    -F|--fixed)    grep_flag="-F"; shift ;;
+    -T|--timeout)  timeout="${2-}"; shift 2 ;;
+    -i|--interval) interval="${2-}"; shift 2 ;;
+    -l|--lines)    lines="${2-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+  echo "target and pattern are required" >&2
+  usage
+  exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+  echo "timeout must be an integer number of seconds" >&2
+  exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+  echo "lines must be an integer" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+  # -J joins wrapped lines, -S uses negative index to read last N lines
+  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  now=$(date +%s)
+  if (( now >= deadline )); then
+    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+    echo "Last ${lines} lines from $target:" >&2
+    printf '%s\n' "$pane_text" >&2
+    exit 1
+  fi
+
+  sleep "$interval"
+done

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

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.14",
+  "version": "0.8.15-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,18 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- Changed workflow human-in-the-loop prompts (`ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor`) to render as synthetic graph stages with `awaiting_input` status; consumers should handle the new `StageSnapshot.promptAnswerState` metadata and avoid caching `StageSnapshot.parentIds` references across store updates ([#1046](https://github.com/flora131/atomic/issues/1046)).
+- Changed `ctx.ui.select(..., [])` to throw `pi-workflows: ctx.ui.select requires at least one option` before creating a prompt node instead of returning an empty string ([#1046](https://github.com/flora131/atomic/issues/1046)).
+
 ### Added
 
 - Added workflow tool stage introspection and control actions (`stages`, `stage`, `transcript`, `send`, `pause`, and `reload`) for inspecting stage state, reading transcripts, answering prompts, controlling live stages, pausing runs, and reloading workflow resources ([#1023](https://github.com/flora131/atomic/issues/1023)).
+- Added live-memory prompt answer replay for workflow continuations using snapshot-safe `promptAnswerState` markers and a private `PromptAnswerRecord` ledger that is excluded from snapshots and persistence ([#1046](https://github.com/flora131/atomic/issues/1046)).
 
 ### Changed
 
+- Updated Ralph around an autonomous goal contract so planner, implementation, and reviewer/auditor stages infer verifiable criteria, require receipts, and judge completion against the verification oracle instead of document completeness alone ([#1053](https://github.com/flora131/atomic/issues/1053)).
+- Updated Ralph's orchestrator prompt to discover project initialization needs from repository evidence before implementation work proceeds ([#1048](https://github.com/flora131/atomic/issues/1048)).
 - Added a final Ralph PR-preparation phase that reviews changes against the configured base branch, tries available GitHub credentials using local git identity as a hint, posts implementation notes as a PR comment, and creates a pull request when possible.
-- Updated Ralph to persist planner RFCs under `specs/`, keep OS-temp implementation notes during orchestration, and pass file paths rather than the full plan text to later stages ([#1037](https://github.com/flora131/atomic/issues/1037)).
+- Updated Ralph to persist planner goal contracts and implementation notes as OS-temp workflow artifacts, and pass file paths rather than full plan text to later stages ([#1037](https://github.com/flora131/atomic/issues/1037)).
 - Updated `deep-research-codebase` output layout to write public reports under `research/` and hidden per-run handoff artifacts under `research/.deep-research-<run-id>/`.
 
 ### Fixed
 
+- Returned the workflow overlay to the graph orchestrator after answering or skipping a `ctx.ui` prompt node, and preserved the prompt's question footprint for read-only prompt-node views.
 - Removed biasing stage-output and iteration-count context from Ralph reviewer prompts while making the comparison base branch explicit ([#1037](https://github.com/flora131/atomic/issues/1037)).
 - Ordered snapshot transcript fallback entries chronologically before applying `tail`/`limit`, preserving terminal result/error entries after tools for missing or tied timestamps ([#1023](https://github.com/flora131/atomic/issues/1023)).
 - Reloaded workflow resources directly for `workflow({ action: "reload" })` instead of queuing a literal `/workflow reload` follow-up ([#1023](https://github.com/flora131/atomic/issues/1023)).

package/dist/builtin/workflows/README.md

@@ -197,7 +197,9 @@ registry.get("alpha"); // compiled workflow definition | undefined
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`).
 
-Workflows always run as **background tasks** — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor`) surface there, never as modal dialogs over the chat.
+Workflows always run as **background tasks** — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat.
+
+Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node.
 
 ### `workflow` tool (LLM-callable)