@bastani/atomic 0.9.11-alpha.1 → 0.9.11-alpha.11

package/docs/quickstart.md

@@ -32,6 +32,10 @@ bun add -g @bastani/atomic
 
 Atomic does not require package install scripts. If you want to disable dependency lifecycle scripts during the Atomic install, you can add `--ignore-scripts` to the install command.
 
+### Alpine and musl Linux archives
+
+For Alpine Linux, use `atomic-linux-x64-musl.tar.gz` on x64 or `atomic-linux-arm64-musl.tar.gz` on arm64. These archives provide native search and PTY bindings. Install their runtime libraries with `apk add --no-cache libgcc libstdc++`, then see the [Alpine and musl Linux archive notes](/index#alpine-and-musl-linux-archives) for the clipboard fallback and external Postgres or Docker requirement for durable workflows.
+
 Then start Atomic in the project directory you want it to work on:
 
 ```bash
@@ -92,44 +96,47 @@ For an interactive tour any time, run `/atomic` inside the TUI; `/atomic overvie
 
 ### Try the built-in workflows
 
-Atomic ships with ten workflows you can run immediately. Use `/workflow list` to see them and `/workflow inputs <name>` to inspect their inputs in your environment.
+Atomic ships with nine workflows you can run immediately. Use `/workflow list` to see them and `/workflow inputs <name>` to inspect their inputs in your environment.
 
 | Workflow | When to use | Example |
 |---|---|---|
 | `classify-and-act` | Route requests through structured classification and low-confidence human fallback. | `/workflow classify-and-act prompt="Triage and handle this request"` |
-| `fan-out-and-synthesize` | Partition independent slices and synthesize their artifact evidence. | `/workflow fan-out-and-synthesize prompt="Review every API package"` |
+| `fan-out-and-synthesize` | Partition independent slices, including repository-focused research, and synthesize their artifact evidence. | `/workflow fan-out-and-synthesize prompt="Map payment retries by subsystem and synthesize cited findings"` |
 | `adversarial-verification` | Challenge a candidate with fresh verifiers and bounded repair. | `/workflow adversarial-verification task="Verify the migration patch"` |
 | `generate-and-filter` | Generate, dedupe, filter, optionally judge, and shortlist candidates. | `/workflow generate-and-filter prompt="Propose names for the new command"` |
 | `tournament` | Compare whole solutions through balanced pairwise judging. | `/workflow tournament prompt="Design the retry strategy"` |
 | `loop-until-done` | Iterate with a durable ledger until completion or bound exhaustion. | `/workflow loop-until-done prompt="Repair failures until the test suite passes"` |
-| `deep-research-codebase` | Heavy research for tasks requiring comprehensive, whole-repository context. | `/workflow deep-research-codebase prompt="How do payment retries work end to end?"` |
-| `goal` | Clearly delegated autonomous work that materially benefits from a durable goal ledger, bounded worker turns, named validation, and reviewer gates. It stops as `complete`, `blocked`, or `needs_human`, with optional final-stage PR creation through `create_pr=true` after approval. | `/workflow goal objective="Update the CLI docs for --json, include one example, run the docs build, and finish when the build passes"` |
-| `ralph` | Clearly delegated autonomous work that materially benefits from a durable research-first pipeline, delegated implementation, and iterative review. Ralph can start from a spec file, GitHub issue, or crisp ticket description and optionally lets only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic returns 429"` |
-| `open-claude-design` | UI and design-system work with separate forked generate and feedback chains; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
+| `goal` | Autonomous work that needs a durable ledger, bounded sub-agent orchestration, receipts, and reviewer-gated completion. | `/workflow goal objective="Update the CLI docs, add one example, and validate the docs build"` |
+| `ralph` | Research-first autonomous work with prompt refinement, delegated implementation, and iterative multi-model review. | `/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic"` |
+| `open-claude-design` | UI and design-system work with separate generate and feedback chains and a live `preview.html`. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
 
 <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
 
-Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `objective="multi word value"` preserve useful types. Some workflows expose reusable worktree inputs; for example, add `git_worktree_dir=../atomic-ralph-wt` to `ralph` to run its stages in a created/reused Git worktree while preserving your current repo-relative cwd. Goal and Ralph skip PR creation by default; prompt text alone does not opt in. Add `create_pr=true` only when you want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation after the workflow's review gate approves, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; the PR-creation instructions live in that final stage. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it.
+Inputs are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=5`, `flag=true`, and `prompt="multi word value"` preserve useful types. If you call `/workflow <name>` without required inputs, the TUI opens an inline picker; pass `--no-picker` to skip it. Goal and Ralph support `git_worktree_dir` only when you explicitly want a reusable worktree, and skip PR creation unless you set `create_pr=true` for the post-approval final stage.
 
-You can also launch workflows with **natural language** — just describe the task in chat and ask Atomic to run the matching workflow:
+You can also launch workflows with **natural language** — describe the task in chat and ask Atomic to run a matching installed workflow or author a task-specific one:
 
 ```text
-Run a deep codebase research workflow on how the rate limiter behaves under burst traffic.
+Fan out repository research by subsystem, save cited findings as artifacts, and synthesize the evidence.
 ```
 
 ```text
-Use the goal workflow to update the CLI docs for --json, include one example, run the docs build, and finish when the build passes.
+Create a worker → fresh verifier → reducer workflow that updates the CLI docs, runs the docs build, and repairs evidence-backed findings until it passes or reaches a bounded stop.
 ```
 
-Atomic picks the workflow, fills in inputs from the request, and confirms before launch.
+```text
+Use goal to update the CLI docs, include one example, run the docs build, and finish only when reviewers approve the evidence.
+```
 
-For a clearly delegated broad autonomous implementation job that benefits from a research/review loop, `ralph` is one available builtin. Give it a spec file, GitHub issue, or crisp ticket description; it refines the prompt, researches as needed, delegates implementation, reviews, records a QA proof video for UI/full-stack changes when practical, and iterates. Add `create_pr=true` only when you want the final PR handoff after the review gate approves.
+```text
+Use ralph to research and implement specs/rate-limit.md, then review and repair it within three loops.
+```
 
-For an autonomous one-off job that materially benefits from a durable goal ledger, bounded worker turns, and reviewer gates, use `goal` with a concrete task description that names the work surface, desired outcome, and validation. An ordinary small-to-medium change does not require it merely because it has tests, validation, or multiple files, but loop or stop-condition wording is a key workflow signal when the user delegates execution. Goal captures receipts, stops as `complete`, `blocked`, or `needs_human`, and can optionally run only the final PR handoff with `create_pr=true` after approval.
+Atomic chooses a complete execution shape, fills inputs from the request, and confirms before launch. Use Goal when a durable ledger and receipt-backed reviewer gate fit the task. Use Ralph when the job benefits from a research-first implementation/review loop. For exact domain contracts that either builtin does not cover, author a custom graph with deterministic checks and bounded repairs.
 
 ### Monitor and steer a run
 
-Named workflow runs execute in the background. After launch you get a run id; use it to inspect, connect, pause, quit, or resume.
+Named workflow runs execute in the background. After launch you get the full run id; user-facing workflow surfaces show that complete UUID. You can still type the full id or a unique short prefix to inspect, connect, pause, quit, or resume a run. Ambiguous prefixes are reported rather than selecting a run arbitrarily.
 
 ```text
 /workflow status <run-id>         # inspect one run's progress
@@ -141,6 +148,8 @@ Named workflow runs execute in the background. After launch you get a run id; us
 /workflow quit <run-id>           # pause gracefully and keep the run resumable
 ```
 
+The below-editor `BACKGROUND` panel uses two lines per card at 80 columns and wider: the status glyph and full id are on the first line, and the workflow name plus mode/progress/elapsed metadata are on the second. Below 80 columns it collapses to a count-only line. In chat surfaces, a full id wraps onto continuation lines at narrow widths instead of being cut, and the surrounding border remains intact.
+
 Human-in-the-loop prompts (`ctx.ui.input`, `confirm`, `select`, `editor`) surface in the graph viewer, not as chat modals — connect to the run to answer them.
 
 Atomic also posts main-chat lifecycle notices when a run completes, fails, or awaits input. If you answer a workflow prompt in the graph or attached stage chat, the main chat receives a display-only answer summary for audit; it does not wake the model, enter LLM context, or answer later prompts. See [Workflows](/workflows) for the full reference and authoring guide.
@@ -153,13 +162,13 @@ Skills are reusable expert instructions. Trigger one with `/skill:<name>` follow
 |---|---|---|
 | `research-codebase` | Scoped research that writes a grounded artifact for one subsystem or question. | `/skill:research-codebase how the rate limiter works in src/middleware/` |
 | `create-spec` | Turn research into an implementation-ready plan. | `/skill:create-spec from research/docs/2026-03-rate-limit.md` |
-| `prompt-engineer` | Tighten a vague prompt before a long run. | `/skill:prompt-engineer Draft a sharper repo-research prompt for payment retries end to end.` |
+| `prompt-engineer` | Create, optimize, evaluate, or troubleshoot prompts for GPT-5.6, Claude Opus 5, and Claude Fable 5. | `/skill:prompt-engineer Draft a sharper repo-research prompt for payment retries end to end.` |
 | `tdd` | Test-first feature or bug work. | `/skill:tdd` |
 | `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks. | `/skill:impeccable` |
 | `playwright-cli` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:playwright-cli` |
 | `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` |
 
-Use `/skill:research-codebase` for a focused area and `/workflow deep-research-codebase` when a clearly delegated repo-wide research job benefits from durable stages and artifacts. Keep conversation-led planning and implementation inline, or use bounded subagents while the parent remains in control. When an autonomous implementation job needs durable execution, use `/workflow goal` for a goal ledger, bounded worker turns, and reviewer-gated completion, or `/workflow ralph` for a research-first pipeline with delegated implementation and iterative review. Task size alone does not select either workflow. Add `create_pr=true` only when you want the workflow's final pull-request stage after approval.
+Use `/skill:research-codebase` for a focused subsystem or question. For repository-wide research, use `fan-out-and-synthesize` with distinct repository partitions and an artifact synthesis barrier. Use Goal for ledger-backed bounded orchestration and Ralph for research-first delegated implementation with iterative review; task size alone does not select either workflow.
 
 ### Create your own workflow in natural language
 
@@ -178,9 +187,10 @@ Atomic will:
 
 - ask clarifying questions if stage purpose, inputs, models, or handoffs are ambiguous,
 - write a `.atomic/workflows/<name>.ts` definition that uses `workflow({ ... })` and imports `Type` from `typebox`,
-- and run `/workflow reload` so the generated workflow is rediscovered and can be launched with `/workflow <name>`.
+- run `/workflow reload` so the generated workflow is rediscovered and can be launched with `/workflow <name>`,
+- then report the generated workflow folder so you can inspect the code it wrote, using `Custom workflow created. You can inspect its code at: <workflow-folder-path>` (for example, `.atomic/workflows/`); Atomic does this only for newly created custom workflows, never builtin or pre-existing workflows.
 
-The same plain-chat approach works for editing or hardening an existing workflow — ask Atomic to add a stage, switch a model, save artifacts, or wire in a human approval gate. For the full authoring reference, see [Workflows](/workflows). The authoring guide also covers [workflow composition](/workflows#workflow-composition), including calling user-defined workflows or builtin workflows such as `deep-research-codebase`, `goal`, and `ralph` from `@bastani/workflows/builtin`.
+The same plain-chat approach works for editing or hardening an existing workflow. For the full authoring reference, see [Workflows](/workflows), including composition with user-defined workflows and all nine builtins from `@bastani/workflows/builtin`.
 
 ### Default tools and prompts
 

package/docs/rpc.md

@@ -13,7 +13,6 @@ atomic --mode rpc [options]
 Common options:
 - `--provider <name>`: Set the LLM provider (anthropic, openai, google, etc.)
 - `--model <pattern>`: Model pattern or ID (supports `provider/id` and optional `:<thinking>`)
-- `--context-window <tokens>`: Select a supported context-window size for the startup model (`400k`, `1m`, or raw tokens)
 - `--name <name>` / `-n <name>`: Set the session display name at startup
 - `--no-session`: Disable session persistence
 - `--session-dir <path>`: Custom session storage directory
@@ -26,10 +25,14 @@ Common options:
 
 All commands support an optional `id` field for request/response correlation. If provided, the corresponding response will include the same `id`.
 
+If a complete saved provider/model default names a provider that remains unsupported after provider registration, the process stays live but `prompt` returns a correlated error with the generic configuration diagnostic before any user/model event is emitted. `get_available_models` and other non-prompt commands remain available. A successful explicit `set_model`, or a successful `cycle_model` that returns a different available model, clears the startup condition and allows later prompts. A null or unchanged cycle result does not clear it. Replacing the session applies the newly created session's condition again. Supported providers with an unknown model or missing authentication retain ordinary automatic fallback behavior.
+
 ### Framing
 
 RPC mode uses strict JSONL semantics with LF (`\n`) as the only record delimiter.
 
+Atomic does not impose a size limit on RPC or isolated interactive-engine JSONL records. Commands, responses, events, and render frames are serialized in full. Clients and extensions must account for the memory and latency cost of large records and must not add a smaller line limit unless they intend to reject valid Atomic output.
+
 This matters for clients:
 - Split records on `\n` only
 - Accept optional `\r\n` input by stripping a trailing `\r`
@@ -191,7 +194,7 @@ Response:
 }
 ```
 
-The `model` field is a full [Model](#model) object or `null`. Its `contextWindow` is the active/effective token budget; selectable models may also include `defaultContextWindow` and `contextWindowOptions`. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
+The `model` field is a full [Model](#model) object or `null`. Its `contextWindow` is the model's token budget. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
 
 #### get_messages
 
@@ -235,7 +238,7 @@ Response contains the full [Model](#model) object:
 
 #### cycle_model
 
-Cycle to the next available model. Returns `null` data if only one model available.
+Cycle to the next available model. Returns `null` when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a `null` or unchanged result does not.
 
 ```json
 {"type": "cycle_model"}
@@ -277,6 +280,16 @@ Response contains an array of full [Model](#model) objects:
 }
 ```
 
+The subprocess protocol returns full `Model` objects. The exported TypeScript `RpcClient.getAvailableModels()` keeps its smaller backward-compatible `ModelInfo` shape (`provider`, `id`, `contextWindow`, `reasoning`) and adds optional `compat`. When present, `compat` exposes constrained-sampling capability claims including `supportsStrictTools`, `supportsStrictMode`, canonical `supportsOpenAIGrammarTools`, and Atomic's synchronized `supportsGrammarTools` alias. Treat absence as unknown/unsupported; do not infer enforcement from the provider name.
+
+```typescript
+const models = await client.getAvailableModels();
+const capabilities = models[0]?.compat;
+if (capabilities?.supportsStrictTools) {
+  // The selected model advertises Anthropic/Bedrock strict-tool support.
+}
+```
+
 #### logout_provider
 
 Remove a provider's stored credential in the authoritative agent process, refresh its available-model catalog, and return the remaining authentication status and new catalog. Environment variables and `models.json` authentication are reported but are not modified.
@@ -304,66 +317,6 @@ Response:
 `models` preserves the refreshed catalog order. `scopedModels` is optional. If authentication remains through an environment variable, `authStatus.source` is `"environment"` and `authStatus.label` names the variable.
 
 
-### Context Window
-
-#### get_available_context_windows
-
-List the context-window token budgets supported by the current model and read the active/effective runtime selection.
-
-```json
-{"type": "get_available_context_windows"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_available_context_windows",
-  "success": true,
-  "data": {
-    "contextWindows": [400000, 1000000],
-    "currentContextWindow": 400000,
-    "supportsSelection": true
-  }
-}
-```
-
-- `contextWindows`: supported token budgets for the active model, sorted ascending.
-- `currentContextWindow`: the active/effective token budget on `model.contextWindow`; omitted when no model is selected.
-- `supportsSelection`: `true` when the active model exposes more than one supported budget.
-
-#### set_context_window
-
-Set the active context-window token budget for the current model at runtime.
-
-```json
-{"type": "set_context_window", "contextWindow": 1000000}
-```
-
-Compact string values are also accepted:
-```json
-{"type": "set_context_window", "contextWindow": "1m"}
-```
-
-Response:
-```json
-{"type": "response", "command": "set_context_window", "success": true}
-```
-
-This command calls `AgentSession.setContextWindow(...)` without `{ persistDefault: true }`: it updates the active model, appends a `context_window_change` session entry and emits `context_window_changed` when the budget changes, but it does **not** write context-window defaults to settings. Use startup `--context-window` or an interactive context-window selection when you intentionally want the effective selection persisted under `defaultContextWindows["provider/modelId"]`.
-
-Unsupported or malformed selections return the standard RPC error response:
-```json
-{
-  "type": "response",
-  "command": "set_context_window",
-  "success": false,
-  "error": "Context window 2m is not supported by custom/selectable-context. Supported values: 400k, 1m."
-}
-```
-
-Larger provider context windows may consume more credits/cost. For catalog-advertised GitHub Copilot long-context models (including `github-copilot/gpt-5.5`, `github-copilot/claude-sonnet-5`, and `github-copilot/gemini-3.1-pro-preview`), selecting `1m` raises Atomic's local budget and sends `X-GitHub-Api-Version: 2026-06-01`; GitHub applies the long-context billing tier server-side by prompt token count. That tier consumes more Copilot AI credits and requires Copilot long-context/usage-based billing entitlement, otherwise requests over GitHub's server cap are rejected with a friendly hint.
-
 ### Thinking
 
 #### set_thinking_level
@@ -401,6 +354,24 @@ Response:
 }
 ```
 
+#### get_available_thinking_levels
+
+Return the thinking levels supported by the current model, in cycle order.
+
+```json
+{"type": "get_available_thinking_levels"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_available_thinking_levels",
+  "success": true,
+  "data": {"levels": ["off", "low", "medium", "high"]}
+}
+```
+
 ### Queue Modes
 
 #### set_steering_mode
@@ -546,6 +517,15 @@ Response:
 }
 ```
 
+While the command runs, Atomic emits ordered deltas correlated by the command `id`:
+
+```json
+{"type":"bash_execution_update","id":"req-1","channel":"stdout","delta":"building...\n"}
+{"type":"bash_execution_update","id":"req-1","channel":"stderr","delta":"warning\n"}
+```
+
+`channel` is exactly `"stdout"` or `"stderr"`. Deltas preserve the order observed for that request; concurrent bash requests may interleave globally but never share IDs. Request ownership survives `new_session`, `switch_session`, `import_session`, fork, and clone while the command is running: later deltas still stream under the original ID, the replacement session is not contaminated, and exactly one ordinary `response` remains the terminal record for completion, cancellation, or error.
+
 If output was truncated, includes `fullOutputPath`:
 ```json
 {
@@ -564,7 +544,7 @@ If output was truncated, includes `fullOutputPath`:
 
 **How bash results reach the LLM:**
 
-The `bash` command executes immediately and returns a `BashResult`. Internally, a `BashExecutionMessage` is created and stored in the agent's message state. This message does NOT emit an event.
+The `bash` command executes immediately and returns a `BashResult`. Internally, a `BashExecutionMessage` is created and stored exactly once in the session where that request started, even if an RPC session replacement completes before the command. The message does NOT emit an event.
 
 When the next `prompt` command is sent, all messages (including `BashExecutionMessage`) are transformed before being sent to the LLM. The `BashExecutionMessage` is converted to a `UserMessage` with this format:
 
@@ -583,15 +563,15 @@ This means:
 
 #### abort_bash
 
-Abort a running bash command.
+Abort running bash commands. Omit `requestId` to retain the legacy behavior of aborting every active RPC-owned bash request, including requests that began before a session replacement, or provide the target bash command's `id` to cancel only that request. Targeted and legacy cancellation remain isolated across concurrent IDs. Closing RPC cancels and drains remaining owned requests before shutdown.
 
 ```json
-{"type": "abort_bash"}
+{"id":"cancel-1","type":"abort_bash","requestId":"req-1"}
 ```
 
 Response:
 ```json
-{"type": "response", "command": "abort_bash", "success": true}
+{"id":"cancel-1","type":"response","command":"abort_bash","success":true}
 ```
 
 ### Session
@@ -899,7 +879,7 @@ Each command has:
 
 ## Events
 
-Events are streamed to stdout as JSON lines during agent operation. Events do NOT include an `id` field (only responses do).
+Events are streamed to stdout as JSON lines. Most events do not include an `id`; `bash_execution_update` is the deliberate exception and uses the originating bash request ID.
 
 ### Event Types
 
@@ -915,12 +895,15 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `tool_execution_start` | Tool begins execution |
 | `tool_execution_update` | Tool execution progress (streaming output) |
 | `tool_execution_end` | Tool completes |
+| `bash_execution_update` | Correlated direct-bash stdout/stderr delta |
 | `queue_update` | Pending steering/follow-up queue changed |
-| `context_window_changed` | Active context-window token budget changed |
 | `compaction_start` | Verbatim line compaction begins |
 | `compaction_end` | Verbatim line compaction completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
+| `summarization_retry_scheduled` | Retry scheduled for a transient compaction or branch-summary provider error |
+| `summarization_retry_attempt_start` | Retried summarization request starts |
+| `summarization_retry_finished` | Summarization retry loop completes |
 | `extension_error` | Extension threw an error |
 
 ### agent_start
@@ -1054,6 +1037,10 @@ When complete:
 
 Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.
 
+### bash_execution_update
+
+Emitted only for direct `bash` and non-intercepted `user_bash` RPC execution. Each event is `{type, id?, channel, delta}` where `channel` is `"stdout"` or `"stderr"`; use `id` to keep concurrent streams separate. Tool-call bash continues to use `tool_execution_update` and its `toolCallId`.
+
 ### queue_update
 
 Emitted whenever the pending steering or follow-up queue changes.
@@ -1066,19 +1053,6 @@ Emitted whenever the pending steering or follow-up queue changes.
 }
 ```
 
-### context_window_changed
-
-Emitted when the active context-window token budget changes through RPC `set_context_window`, `AgentSession.setContextWindow()` in an SDK-backed runtime, or because in-place tree navigation replayed a branch-scoped `context_window_change` entry. Navigation replay updates the active model for accurate budgeting and compaction but does not append another session entry or write context-window defaults to settings.
-
-```json
-{
-  "type": "context_window_changed",
-  "contextWindow": 1000000
-}
-```
-
-Larger provider context windows may consume more credits/cost. Prefer the model default unless the additional repository/session context is useful for the current task. For catalog-advertised GitHub Copilot long-context models such as `github-copilot/gpt-5.5`, `github-copilot/claude-sonnet-5`, and `github-copilot/gemini-3.1-pro-preview`, a `1m` selection raises Atomic's local budget and sends `X-GitHub-Api-Version: 2026-06-01`; GitHub applies the long-context billing tier server-side by prompt size, consumes more Copilot AI credits, and requires long-context/usage-based billing entitlement.
-
 ### compaction_start / compaction_end
 
 Emitted when default Verbatim Compaction runs, whether manual or automatic. The result records deletion targets and stats rather than a generated summary.
@@ -1121,6 +1095,8 @@ If compaction was aborted, `result` is `null` and `aborted` is `true`.
 
 If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` is `false`, and `errorMessage` contains the error description.
 
+`result` and `errorMessage` are independent. A mid-turn post-tool compaction can commit a boundary and *then* fail the provider hard-input-limit gate, so one `compaction_end` may carry both a non-null `result` and an `errorMessage`. Treat the result as a committed durable boundary in that case; the error describes the follow-up request that was not sent.
+
 If overflow recovery exhausts the same-model compact-and-retry attempt, `compaction_end` includes `"unresolvedOverflow": true` and an `errorMessage`. Workflow orchestration treats that signal as a context-length failure that can advance configured model fallback tiers.
 
 There is no `context_compact` command; Atomic reports it as an unknown command. Use `compact`. Only `compaction_start` and `compaction_end` events are emitted.
@@ -1157,6 +1133,34 @@ On final failure (max retries exceeded):
 }
 ```
 
+
+### summarization_retry_scheduled / summarization_retry_attempt_start / summarization_retry_finished
+
+Emitted when compaction planning or branch summarization retries after a transient provider error. These events use the same retry settings as automatic assistant-turn retries.
+
+```json
+{
+  "type": "summarization_retry_scheduled",
+  "attempt": 1,
+  "maxAttempts": 3,
+  "delayMs": 2000,
+  "errorMessage": "terminated"
+}
+```
+
+```json
+{
+  "type": "summarization_retry_attempt_start",
+  "source": "compaction",
+  "reason": "threshold"
+}
+```
+
+For branch summaries, `source` is `"branchSummary"` and no `reason` is present. The loop then emits:
+
+```json
+{"type": "summarization_retry_finished"}
+```
 ### extension_error
 
 Emitted when an extension throws an error.
@@ -1406,8 +1410,6 @@ Source files and installed definitions:
   "reasoning": true,
   "input": ["text", "image"],
   "contextWindow": 200000,
-  "defaultContextWindow": 200000,
-  "contextWindowOptions": [200000, 1000000],
   "maxTokens": 16384,
   "cost": {
     "input": 3.0,
@@ -1418,7 +1420,7 @@ Source files and installed definitions:
 }
 ```
 
-`contextWindow` is the active/effective token budget used by Atomic's local budgeting, footer/stats, and compaction logic. `defaultContextWindow` is the model's scalar default before a session/runtime override, and `contextWindowOptions` lists selectable token budgets when the model supports more than one size. RPC clients can read/select the active runtime budget with `get_available_context_windows` and `set_context_window`; the runtime command does not persist context-window defaults to settings.
+`contextWindow` is the model's token budget used by Atomic's local budgeting, footer/stats, and compaction logic.
 
 ### UserMessage
 
@@ -1457,7 +1459,7 @@ The `content` field can be a string or an array of `TextContent`/`ImageContent`
 }
 ```
 
-Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`
+Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`. A partial message inside a `message_update` event carries `"pending"` until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it.
 
 ### ToolResultMessage