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

package/docs/sdk.md

@@ -78,6 +78,24 @@ Atomic does not require package install scripts. If you want to disable dependen
 
 The SDK is included in the main package. No separate SDK package is needed.
 
+## Experimental remote sessions
+
+`@bastani/atomic/client` is an experimental entrypoint for upstream remote protocol sessions. It exports `RemoteSession` plus transcript projection helpers. Pass it a connected `PiClient` from `@earendil-works/pi-client`, then use `RemoteSession.open()` or `RemoteSession.create()` to own one remote session.
+
+`RemoteSession` and Atomic's isolated interactive engine deliberately **coexist**; neither adapts the other. `RemoteSession` owns the `pi-client`/`pi-protocol` transport, its `SessionLease`, the leased `SessionSnapshot`, and the transcript projection used by an external protocol client. The isolated engine owns Atomic's in-process host facade, child-process JSONL RPC engine, interactive rendering, custom UI, and engine recovery. The client entrypoint has no `atomic client` CLI command and does not start or control the local interactive engine.
+
+`RemoteSession.sessions` is a durable catalog of `SessionMetadata`. That is enough for listing and selecting stored sessions, but not for Atomic consumers that need runtime phase, model, thinking level, attachment, or lock state. Those consumers need the `SessionSnapshot` from an acquired lease; `RemoteSession.snapshot` exposes the current leased snapshot.
+
+This boundary is intentional. A bridge would join two different protocols and would risk routing isolated-engine teardown through the host facade's unbounded cooperative abort. Keep the surfaces separate until a future upstream `RemoteSession` change supplies an engine-aware/server contract with teardown semantics that can preserve Atomic's recovery guarantee. The API may change without notice while it remains experimental.
+
+## Experimental Harness factory
+
+The package root also exports `createCodingAgentHarness()` for applications that provide a pi-agent-core `ExecutionEnv`. It creates a Harness with Atomic's six coding tools: `read`, `bash`, `edit`, `write`, `find`, and `search`.
+
+The factory routes the primary operations for the first five tools through the supplied execution environment, including directory-tree reads. URL reads use the session id for cache scope, fetch through the process network, and do not persist host-local artifacts because the factory has no local session directory. `search` is fully local; read and edit still use local path-variant probes and notebook projection, read also uses local archive, SQLite, and internal-resource selectors, write retains local generated-file, shebang, conflict, and resource helpers, and bash validates its cwd locally and uses Atomic's local temp storage for overflow output.
+
+The factory requires `ExecutionEnv.renameFile()` and does not add a fallback filesystem implementation.
+
 ## Core Concepts
 
 ### createAgentSession()
@@ -279,7 +297,7 @@ await session.followUp("After you're done, also do this");
 
 Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued).
 
-`pauseQueuedMessages()` is a synchronous admission gate. It moves existing raw steering/follow-up entries into a hold before an abort boundary and keeps later context-bearing arrivals—including trigger-turn custom messages, batches, interrupts, async job delivery, `sendUserMessage()`, and ordinary `prompt()` calls—queued without starting a provider turn. Content blocks, optional data, duplicate identities, raw text, message types, and the existing order within each queue kind are retained. Non-trigger custom messages remain history-only and do not invent a turn.
+`pauseQueuedMessages()` is a synchronous admission gate. It moves existing raw steering/follow-up entries into a hold before an abort boundary and keeps later context-bearing arrivals—including trigger-turn custom messages, batches, interrupts, `sendUserMessage()`, and ordinary `prompt()` calls—queued without starting a provider turn. Content blocks, optional data, duplicate identities, raw text, message types, and the existing order within each queue kind are retained. Non-trigger custom messages remain history-only and do not invent a turn.
 
 `resumeQueuedMessages()` releases that hold exactly once but does **not** itself start or continue a model turn. Its promise resolves to `true` only when raw held steering/follow-up work was released, and to `false` when no held raw work existed. The caller must use its existing explicit resume action (for example, the interactive chat submission or workflow resume boundary) to drive execution. `clearQueue()` clears the paused flag when it explicitly removes the final unowned held item; if a protected or interrupt-owned item remains, the gate stays paused.
 
@@ -377,6 +395,16 @@ session.subscribe((event) => {
 });
 ```
 
+A subscriber that rebuilds the assistant message from these deltas must
+accumulate them into its own message object. `message_start` reports the
+message the model is about to stream, but an in-process subscriber receives the
+provider's live partial rather than a snapshot of it, and the provider keeps
+appending to that same object as the stream runs. Appending a delta to it adds
+text the provider already added. A subscriber that attaches part-way through a
+turn missed the deltas that came before it and can seed itself from
+`session.agent.state.streamingMessage`, which holds the message currently being
+streamed, if any.
+
 ## Options Reference
 
 ### Directories
@@ -399,7 +427,7 @@ Atomic reads primary `.atomic` locations first and legacy `.pi` locations for co
   - `.atomic/skills/`, then legacy `.pi/skills/`
   - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
 - Project prompts (`.atomic/prompts/`, then legacy `.pi/prompts/`)
-- Context files (`AGENTS.md` walking up from cwd)
+- Context files (`AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` walking up from cwd)
 - Session directory naming
 
 `agentDir` is used by `DefaultResourceLoader` for:
@@ -408,7 +436,7 @@ Atomic reads primary `.atomic` locations first and legacy `.pi` locations for co
   - `skills/` under `agentDir` (for example `~/.atomic/agent/skills/`; legacy `~/.pi/agent/skills/` is also considered by default)
   - `~/.agents/skills/`
 - Global prompts (`prompts/`)
-- Global context file (`AGENTS.md`)
+- Global context files (`AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` under `agentDir`)
 - Settings (`settings.json`)
 - Custom models (`models.json`)
 - Credentials (`auth.json`)
@@ -459,7 +487,7 @@ If no model is provided:
 
 ### API Keys and OAuth
 
-`ModelRuntime` is the asynchronous SDK engine for provider composition, credentials, model catalogs, and requests. `ModelRegistry` remains a thin synchronous compatibility facade for extensions; new SDK integrations should pass `modelRuntime` to `createAgentSession`.
+`ModelRuntime` is the asynchronous SDK engine for provider composition, credentials, model catalogs, and requests. `ModelRegistry` remains a thin compatibility facade for extensions; `await modelRegistry.complete(model, context, options)` routes a request through its runtime with the resolved provider and auth. New SDK integrations should pass `modelRuntime` to `createAgentSession` and use `modelRuntime.complete()` directly when they issue standalone requests.
 
 Credential resolution combines runtime API-key overrides, stored `auth.json` credentials, environment variables, and the active `models.json` provider configuration. OAuth acquisition is provider-owned and runs through `ModelRuntime.login()`.
 
@@ -474,8 +502,12 @@ const { session } = await createAgentSession({
   modelRuntime,
 });
 
-// Runtime API key override (not persisted to disk)
-await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+// Runtime API key override (not persisted to disk). Setting the key updates
+// auth state; refresh the provider explicitly when its catalog must be current.
+const providerId = "anthropic";
+const authController = new AbortController();
+await modelRuntime.setRuntimeApiKey(providerId, "sk-my-temp-key", { signal: authController.signal });
+await modelRuntime.refresh({ providers: [providerId], signal: authController.signal });
 
 // Custom credential and model configuration locations
 const customRuntime = await ModelRuntime.create({
@@ -1009,9 +1041,13 @@ import {
 const authStorage = AuthStorage.create("/custom/agent/auth.json");
 const modelRuntime = await ModelRuntime.create({ credentials: authStorage, modelsPath: null });
 
-// Runtime API key override (not persisted)
+// Runtime API key override (not persisted). setRuntimeApiKey updates auth state;
+// the scoped refresh updates that provider's catalog.
 if (process.env.MY_KEY) {
-  await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY);
+  const providerId = "anthropic";
+  const authController = new AbortController();
+  await modelRuntime.setRuntimeApiKey(providerId, process.env.MY_KEY, { signal: authController.signal });
+  await modelRuntime.refresh({ providers: [providerId], signal: authController.signal });
 }
 
 // Inline tool

package/docs/security.md

@@ -9,7 +9,7 @@ Project trust controls whether Atomic loads project-local settings, resources, p
 Atomic considers a project to have trust inputs when it finds any of these from the current working directory:
 
 - `.atomic/` (or legacy `.pi/`) in the current directory
-- `AGENTS.md` or `CLAUDE.md` in the current directory or an ancestor directory
+- `AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` in the current directory or an ancestor directory
 - `.agents/skills` in the current directory or an ancestor directory
 
 When an interactive session starts in a project with configs in `.atomic`/`.pi`, project-local context files, or `.agents/skills` and no saved decision for the current directory or a parent directory, Atomic follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.atomic/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
@@ -21,7 +21,7 @@ Trusting a project allows Atomic to load trust-gated project inputs, including:
 - missing project packages configured through project settings
 - project-local extensions and project package-managed extensions
 
-Declining trust skips protected resources. Atomic also skips project-local `AGENTS.md` and `CLAUDE.md` context-file discovery while the project is untrusted; global context and explicitly supplied CLI resources remain available. Before trust is resolved, Atomic only loads user/global extensions and explicit CLI `-e` package-level extensions so those trusted extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision. When `-e <dir>` discovers project-local resources borrowed from that directory's `.atomic` or legacy `.pi` config, or from `.agents/skills`, Atomic resolves trust for that extension source before loading those borrowed resources, because borrowed extensions and workflows can execute code with the Atomic process permissions.
+Declining trust skips protected resources. Atomic also skips project-local `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` context-file discovery while the project is untrusted; global context and explicitly supplied CLI resources remain available. Before trust is resolved, Atomic only loads user/global extensions and explicit CLI `-e` package-level extensions so those trusted extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision. When `-e <dir>` discovers project-local resources borrowed from that directory's `.atomic` or legacy `.pi` config, or from `.agents/skills`, Atomic resolves trust for that extension source before loading those borrowed resources, because borrowed extensions and workflows can execute code with the Atomic process permissions.
 
 Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
 
@@ -53,18 +53,18 @@ If you bind-mount a host workspace read/write, writes from inside the container
 
 ## Credential Export
 
-`atomic auth print-api-key` and `atomic auth print-bearer-token` are the only commands that emit a stored credential. They exist so an external client can reuse the credential you already configured, rather than making you copy it out of `auth.json` by hand.
+`atomic auth print-api-key`, `atomic auth print-bearer-token`, and the explicit `atomic auth check --credentials` form can emit a stored or resolved credential. They let an external client reuse authentication you already configured instead of making you copy a value from `auth.json`. `atomic auth check` without `--credentials` stays status-only.
 
-What the commands guarantee:
+What credential-export forms guarantee:
 
-- **stdout carries the credential or nothing.** Warnings, provider selection, refresh notices, and even `atomic auth --help` go to stderr, and stdout is empty on every non-zero exit but one. `KEY=$(atomic auth print-api-key --model gpt-5.5)` cannot capture a diagnostic instead of a key. The rule runs both ways: once the credential is on stdout the command has succeeded, so a stream that then fails to drain is reported on stderr and the exit code stays `0`. The single exception is exit `9`: if the stream failed part-way through the payload, those bytes are already gone and stdout cannot be made empty, so the command says so rather than reporting a truncated secret as a whole one. Every other non-zero exit leaves stdout empty, which is what makes the exit code safe to branch on.
-- **No file or clipboard sink.** There is no `--output` flag. `--provider` and `--model` are the only options either subcommand accepts, checked as an allowlist: any other parsed flag, including `--export <path>` and `--session-dir <path>`, is a usage error. If you want the value in a file, you redirect it yourself and own that decision.
-- **No ambient model.** `--model` is required, so the command cannot emit a credential for a model you did not name.
-- **A failed refresh never strands you.** If the OAuth refresh itself fails, the command exits `5` and leaves the stored credential exactly as it was. Other OAuth failures — a token that still expires too soon after a successful refresh, or an auth derivation failure that may follow a rotation — exit `6` and `7` and make no claim about the stored credential, rather than asserting a rollback nothing verified.
+- **A credential reaches stdout only through an explicit export.** Warnings, provider selection, refresh notices, and even `atomic auth --help` go to stderr. A plain `KEY=$(atomic auth check --provider openai --credentials)` gets a credential only on success; a non-ready or invalid check leaves stdout empty and reports status on stderr. With `--json`, a failed check returns JSON status without a credential. Once the credential reaches stdout the command has succeeded, so a stream that then fails to drain is reported on stderr and the exit code stays `0`. The single exception is exit `9`: if the stream failed part-way through the payload, those bytes are already gone and stdout cannot be made empty, so the command says so rather than reporting a truncated secret as a whole one. Other **raw** credential-export failures leave stdout empty; a non-zero JSON check result carries status only, never a credential.
+- **No file or clipboard sink.** There is no `--output` flag. The print subcommands allow only `--provider` and `--model`; an auth check must name a provider or exact model before `--credentials` can emit anything. A fuzzy model match cannot select a credential for export. If you want the value in a file, you redirect it yourself and own that decision.
+- **No ambient target.** The print subcommands require `--model`; an exporting auth check requires `--provider` or an exact `--model`, so no export can use an unnamed current session model.
+- **Useful OAuth lifetime.** An auth-check export needs an OAuth token with at least 30 minutes remaining. Its normal path can refresh the token; `--no-refresh` makes no auth-file mutation and refuses a shorter-lived token. `print-bearer-token` applies the same floor and uses exit `5` only for a refresh failure that leaves the stored credential untouched.
 - **The value is not loggable in transit.** Internally the credential is carried in a wrapper that throws if anything tries to interpolate, serialize, or inspect it, so it cannot reach a log line, a session transcript, or an error message. The wrapper is tested under both Node and Bun, since the published binary is Bun-compiled and `Bun.inspect` is a different formatter.
-- **One egress, enumerated.** A single function in `src/cli/credential-print.ts` opens the wrapper and writes to stdout; nothing else in the source tree can read a credential out of it. A test walks every file under `packages/coding-agent/src` and lists *every* call that puts a non-literal value on the real stdout, so a new one has to be added to that list and reviewed. The test carries its own negative control: it feeds the scanner two planted egress modules and fails if either goes unreported. No RPC response type carries a credential either — that is asserted against `src/modes/rpc/rpc-types.ts` directly, because the RPC login reply once echoed the API key the host had just typed in.
+- **One egress, enumerated.** `credentialPayload` is the only source function that opens the wrapper, and it returns one payload only to `emitCredential`, which performs the guarded real-stdout write. Tests enumerate both allowed `Secret.take()` call sites and *every* call that puts a non-literal value on real stdout, so a new one has to be added to the list and reviewed. The tests carry negative controls for a planted third `take()` call and two planted egress modules. No RPC response type carries a credential either — that is asserted against `src/modes/rpc/rpc-types.ts` directly, because the RPC login reply once echoed the API key the host had just typed in.
 
-What they do **not** do: once the credential is on stdout it is ordinary text in your shell, your pipeline, and possibly your shell history and process listing. Prefer `print-bearer-token`, whose output expires, over a long-lived API key. Do not embed either command in a script that logs its own output.
+What they do **not** do: once the credential is on stdout it is ordinary text in your shell, your pipeline, and possibly your shell history and process listing. Prefer `print-bearer-token`, whose output expires, over a long-lived API key. Do not embed any credential-export form in a script that logs its own output.
 
 ## Reporting Security Issues
 

package/docs/session-format.md

@@ -307,6 +307,20 @@ Session metadata (e.g., user-defined display name). Set via `/name`, `--name` /
 
 The session name is displayed in the session selector (`/resume`) instead of the first message when set.
 
+### SessionSummaryEntry
+
+A generated one-line description of the session, written automatically once the agent goes idle and shown in the session selector. Never sent to the LLM.
+
+```json
+{"type":"session_summary","id":"l2m3n4o5","parentId":"k1l2m3n4","timestamp":"2024-12-03T14:36:00.000Z","summary":"Refactored auth module token refresh and added retry tests","summarizedThroughId":"j0k1l2m3","usage":{"input":812,"output":21}}
+```
+
+- `summary`: The stored line. Whitespace is collapsed and length is clamped before writing.
+- `summarizedThroughId`: Entry ID of the last user/assistant message the summary covers. The selector shows the summary only while this is still the newest conversation message; anything newer makes it stale and the selector falls back to the session name or first message. Tool results do not count.
+- `usage`: Optional token usage from the model call, counted toward session usage totals.
+
+A `branch_summary` written after a `session_summary` also retires it, because the branch it described was abandoned.
+
 ## Tree Structure
 
 Entries form a tree:
@@ -420,6 +434,7 @@ for (const stage of stages.filter((session) => session.internal)) {
 - `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary; pass `null` when no pre-boundary message is retained
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
+- `appendSessionSummary(summary, summarizedThroughId, usage?)` - Store a generated resume-picker summary, anchored to the message it describes
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
 

package/docs/sessions.md

@@ -6,6 +6,8 @@ Atomic saves conversations as sessions so you can continue work, branch from ear
 
 Sessions auto-save to `~/.atomic/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
 
+The session picker also scans linked project directories inside this default store, so project aliases or relocated session folders remain discoverable through `/resume` and `atomic -r`.
+
 ```bash
 atomic -c                  # Continue most recent session
 atomic -r                  # Browse and select from past sessions
@@ -55,6 +57,14 @@ In the picker you can:
 
 When available, Atomic uses the `trash` CLI for deletion instead of permanently removing files.
 
+### Session summaries
+
+Each row shows a short generated description of what the session was about in its own column, beside the session name or first message, so you can recognize a conversation without opening it. Atomic writes one after the agent goes idle, using the model the session is already configured with, and stores it in the session file as a `session_summary` entry.
+
+A summary describes the conversation up to a specific message. Once a newer message arrives it is considered stale and the summary column shows "No summary available." instead — the same placeholder you get when a summary has not been generated yet, could not be generated, or is still in flight. The session name and first message are never displaced by a summary, and the column only appears once at least one listed session has a summary. Summaries are also searchable along with the rest of the session text.
+
+Generation is best-effort and never blocks a turn: it is skipped for very short sessions, for workflow stage sessions, and in `--print` and JSON modes, it is cancelled when you send the next message or quit, and its failures are silent. Set `sessionSummary.enabled` to `false` to turn it off entirely.
+
 The picker opens instantly: its header, search field, and loading indicator paint on the first frame, then sessions are discovered and parsed off the terminal's UI loop. Large session directories are scanned in cooperative batches and a single very large transcript is parsed in yielding chunks, so search, navigation, and cancel stay responsive and no individual session can freeze the picker while it loads. Closing the picker cancels any in-flight scan and discards stale results, so a slow load that finishes after you leave never updates the list.
 
 ### Internal (workflow) sessions

package/docs/settings.md

@@ -86,7 +86,7 @@ Fallback attempts are visible as model changes in the session transcript and as
 
 ### Codex Fast Mode
 
-Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode only to supported `openai/*` and `openai-codex/*` providers, not `github-copilot/*` or other OpenAI-compatible providers. Chat and workflow-stage scopes are independent. When fast mode is active for the current supported model, Atomic shows `fast` after the model name in the chat footer and workflow stage model labels. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume priority-tier requests.
+Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode only to supported `openai/*` and `openai-codex/*` providers, not `github-copilot/*` or other OpenAI-compatible providers. Chat and workflow-stage scopes are independent. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use `codexFastMode.workflow`; normal-chat subagents use `codexFastMode.chat`. Fast mode is resolved again for each fallback model, so the marker and priority tier follow the effective provider. When fast mode is active for the current supported model, Atomic shows `fast` after the model name in the chat footer, workflow stage model labels, and subagent results. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume priority-tier requests.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -107,6 +107,7 @@ Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, a Catppuccin built-in, or custom) |
+| `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost transcript column and keeps it visible, and `"hidden"` hides it. The thumb can be dragged when shown. |
 | `quietStartup` | boolean | `false` | Hide startup header |
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
@@ -120,9 +121,15 @@ Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
 | `outputPad` | number | `1` | Horizontal padding for chat message output (user messages, assistant messages, thinking blocks). `0` or `1` |
 | `externalEditor` | string | - | Command for the Ctrl+G external editor; takes precedence over `$VISUAL`/`$EDITOR`. Defaults to Notepad on Windows and `nano` elsewhere |
-| `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
+| `autocompleteMaxVisible` | number | `5` | Max visible items in the default editor and custom editors installed through `ctx.ui.setEditorComponent()` (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
 
+Interactive sessions always use the fullscreen renderer. The transcript scrolls in its own viewport while the editor, status line, usage meter, extension widgets, and footer stay docked at the bottom. Wheel and trackpad gestures go first to a focused workflow overlay, including workflow graphs and stage chats. Events that overlay does not consume fall through to the alternate-screen viewport; non-overlay focused components leave mouse input with pi-tui so transcript scrolling, scrollbar interaction, and drag selection remain available.
+
+The fullscreen renderer keeps minimum sizes for nested layout stacks during resize, and transient fullscreen notices stack instead of replacing a notice that is still visible.
+
+The alternate screen restores the terminal's prior contents on exit, so an interactive transcript does not remain in terminal scrollback. Use `/export` before exit for an HTML copy, or resume the saved session later to review it in Atomic.
+
 Ctrl+G in main chat, embedded chat, and extension editor dialogs uses one shared asynchronous launcher. Atomic chooses `externalEditor`, then `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere. Each edit uses a private `atomic-editor-*` directory containing only `prompt.md`, removes the directory recursively afterward, and never scans the system temporary directory. A successful empty edit is preserved; a failed editor leaves the original text unchanged, and the TUI always restarts and renders after the editor exits.
 
 ### Telemetry and update checks
@@ -189,6 +196,12 @@ The model emits numbered line ranges only; Atomic reconstructs retained text mec
 | `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
 | `branchSummary.skipPrompt` | boolean | `false` | Skip "Summarize branch?" prompt on `/tree` navigation (defaults to no summary) |
 
+### Session Summary
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionSummary.enabled` | boolean | `true` | Generate a one-line summary of each session for the `/resume` picker once the agent goes idle |
+
 ### Retry
 
 | Setting | Type | Default | Description |
@@ -252,7 +265,9 @@ The `/settings` picker offers these presets:
 | `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
 | `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
 | `httpIdleTimeoutMs` | number or string | `600000` | HTTP idle timeout in milliseconds, a duration string, or `"disabled"`; also used by providers with explicit stream idle timeouts. |
-| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
+| `websocketConnectTimeoutMs` | number or string | `15000` | WebSocket connect/open handshake timeout; accepts milliseconds, a duration string, or `"disabled"`/`0` to disable. |
+
+Older settings with a boolean `websockets` value are migrated to `transport`: `true` becomes `"websocket"` and `false` becomes `"sse"` when `transport` is not already set.
 
 ### Terminal & Images
 
@@ -261,9 +276,12 @@ The `/settings` picker offers these presets:
 | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
 | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
-| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
+| `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 progress indicators in the terminal tab bar |
+| `images.autoResize` | boolean | `true` | Resize oversized images to a 2000x2000 maximum. Applies to `@file` attachments, `read`, and images returned by tools |
 | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
 
+When `images.autoResize` is enabled, Atomic normalizes images before sending them to the model. Tool-result images are normalized after `tool_result` extension handlers run, so images an extension inserts receive the same limit; if processing fails, Atomic keeps the original image. Set it to `false` to preserve source dimensions.
+
 ### Shell
 
 | Setting | Type | Default | Description |
@@ -319,6 +337,12 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+| `markdown.mermaid` | string | `"streaming"` | Mermaid rendering mode: `"off"`, `"final"`, or `"streaming"` |
+| `markdown.latex` | boolean | `true` | Render LaTeX expressions as terminal-friendly Unicode math |
+
+Mermaid code blocks render as themed Unicode diagrams in interactive transcripts when they fit the available width. `"off"` keeps the Markdown fence, `"final"` renders only finalized responses, and `"streaming"` also renders partial assistant responses. Invalid or too-wide diagrams remain as code, and rendering is display-only: stored messages and model context keep the original Markdown. LaTeX rendering is also display-only and converts supported expressions to terminal-friendly Unicode math; set `markdown.latex` to `false` to keep the source form.
+
+The installed pi-tui 0.84.1 LaTeX renderer also handles whitespace and matrix layouts correctly.
 
 ### Resources
 
@@ -363,6 +387,8 @@ Object form filters which resources to load:
 }
 ```
 
+Set `autoload` to `false` on an object-form package entry to start that package with no discovered resources and apply only its explicit `extensions`, `skills`, `prompts`, `themes`, or `workflows` patterns. This is useful when a package contains resources you do not want to load by default.
+
 See [Atomic packages](/packages) for package management details.
 
 ## Example
@@ -395,7 +421,7 @@ See [Atomic packages](/packages) for package management details.
 
 ## Project Overrides
 
-Project settings (`.atomic/settings.json`) override global settings. Nested objects are merged:
+Project settings (`.atomic/settings.json`) override global settings. Nested objects merge recursively; arrays and scalar values replace global values:
 
 ```json
 // ~/.atomic/agent/settings.json (global)

package/docs/subagents.md

@@ -5,7 +5,7 @@ description: "Run focused Atomic child agents"
 
 # Subagents
 
-Atomic bundles `@bastani/subagents`, an extension for bounded specialist delegation with separate context while the parent remains in control. Use a single agent, chain, or parallel fan-out when isolation or a specialist pass materially helps with locating code, analyzing behavior, researching references, reproducing actual failures, or simplifying code. Keep interactive, exploratory, conceptual, and conversation-led work inline when direct user steering is more useful.
+Atomic bundles `@bastani/subagents`, an extension for bounded specialist delegation with separate context while the parent remains in control. Use a single agent or parallel fan-out when isolation or a specialist pass materially helps with locating code, analyzing behavior, researching references, reproducing actual failures, or simplifying code. Keep interactive, exploratory, conceptual, and conversation-led work inline when direct user steering is more useful.
 
 You do not need to install anything separately when you use `@bastani/atomic`.
 
@@ -25,35 +25,36 @@ Run a parallel review composition: one pass for current behavior, one for failur
 Research the upstream library behavior online, then compare it with our local implementation.
 ```
 
-Atomic decides whether delegation adds value, which specialist fits each bounded part, and whether the work should run as a single child, parallel group, chain, foreground run, or selective background run. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow; clearly delegated long-running autonomous work that needs durable stages, checkpoints, resumability, HIL, gates, retries, or loops is usually better served by a workflow.
+Atomic decides whether delegation adds value, which specialist fits each bounded part, and whether the work should run as a single child, parallel group, or forked-context run. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow; clearly delegated long-running autonomous work that needs durable stages, checkpoints, resumability, HIL, gates, retries, or loops is usually better served by a workflow.
 
 ## Subagent execution is non-interactive
 
-Supported subagent launches start immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, chain, foreground, background, fanout, prompt-template, and human-entered `/run`, `/chain`, `/parallel`, and `/run-chain` execution. Ask any necessary questions in the parent conversation before delegating.
+Supported subagent launches start immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, forked, fanout, prompt-template, and human-entered `/run` and `/parallel` execution. Ask any necessary questions in the parent conversation before delegating.
 
-The human slash commands remain registered and continue to use their separate parsing and event-bridge path, including background and fork flags.
+The human slash commands remain registered and continue to use their separate parsing and event-bridge path, including fork flags.
+Prompt-template delegation comes from the separately installed `pi-prompt-template-model` extension, whose `requestDelegatedRun` emits `prompt-template:subagent:request`. If that caller must survive an extension reload, import `registerPromptTemplateBridgeRequestSettlement` from `@bastani/subagents`, register it before the emit, and unregister it from the normal response, cancellation, or abort path. The hook rejects the caller only when the old bridge drops a stale response emit; normal completion still arrives through `prompt-template:subagent:response`. Atomic cannot register this opt-in for an out-of-tree emitter.
 
 Subagents now run and return their results directly. Atomic does not infer acceptance gates from prompt wording, inject `acceptance-report` instructions into child prompts, parse or strip `acceptance-report` blocks, or reject completed child runs because changed-file, test, or review evidence is missing. Put any evidence or validation requirements directly in the task text you give the parent or child agent.
 
 ## Foreground supervisor coordination
 
-When a foreground child sends `intercom.ask`, `intercom.send`, or `contact_supervisor` coordination, Atomic first probes for the exact foreground owner. Only an exact live child reserves the request; Atomic then sends a generation-scoped detach commit and waits for that child to acknowledge it before placing the message in the parent's model-visible steering queue. This first-refusal ordering also applies when the parent is a busy workflow stage: detach completes before the request enters the stage AgentSession generation boundary, breaking the child-waits-for-reply / stage-waits-for-child cycle. Unmatched and background-child messages retain existing routing—ordinary parents queue until idle, while open workflow stages fall back to their native generation admission. Blocking `need_decision` and `interview_request` calls remain actionable through [Intercom](/intercom)'s pending/reply tracker, and the exact threaded reply resumes the retained child without delayed duplicate delivery.
+When a foreground child sends `intercom.ask`, `intercom.send`, or `contact_supervisor` coordination, Atomic first probes for the exact foreground owner. Only an exact live child reserves the request; Atomic then sends a generation-scoped detach commit and waits for that child to acknowledge it before placing the message in the parent's model-visible steering queue. This first-refusal ordering also applies when the parent is a busy workflow stage: detach completes before the request enters the stage AgentSession generation boundary, breaking the child-waits-for-reply / stage-waits-for-child cycle. Blocking `need_decision` and `interview_request` calls remain actionable through [Intercom](/intercom)'s pending/reply tracker, and the exact threaded reply resumes the retained child without delayed duplicate delivery. Unmatched messages retain existing routing—ordinary parents queue until idle, while open workflow stages fall back to their native generation admission.
 
-Only the matching foreground child can authorize release of the parent `subagent` tool. For a parallel foreground group, that accepted commit releases foreground supervision for every active sibling as one unit, so a long-running sibling cannot keep a blocking child request trapped behind the aggregate tool call; tasks still waiting behind the concurrency limit are skipped and never launched unsupervised. Children are in-process `AgentSession` instances governed by the shared Rust control plane: there is no child OS process, idle watchdog, stdout drain, or detached placeholder to recover. A detached call becomes `continued` through `continue_in_background`; its canonical child remains live in the jobs widget and later delivers one terminal result. Fire-and-forget `intercom.send` and `progress_update` also release foreground supervision promptly, but do not create a reply waiter.
+Only the matching foreground child can authorize release of the parent `subagent` tool. For a parallel foreground group, that accepted commit releases foreground supervision for every active sibling as one unit, so a long-running sibling cannot keep a blocking child request trapped behind the aggregate tool call; tasks still waiting behind the concurrency limit are skipped and never launched unsupervised. Children are in-process `AgentSession` instances governed by the shared Rust control plane: there is no child OS process, idle watchdog, stdout drain, or detached placeholder to recover. A detached call becomes `continued` through `continue_detached`; its canonical child remains live and later delivers one terminal result. Fire-and-forget `intercom.send` and `progress_update` also release foreground supervision promptly, but do not create a reply waiter.
 
 Blocking coordination is race-safe: a session holds at most one outbound reply waiter, and concurrent blocking requests (parallel `intercom.ask` calls, or `intercom.ask` racing `contact_supervisor`) settle atomically. One request wins the reservation; every other concurrent call returns a normal "Already waiting for a reply" tool error without crashing the agent process or disturbing the pending ask. Cancellation and send failures release only their own waiter, and threaded replies still resolve the exact winning request.
 
 Subagent result announcements are also resilient in sessions that never receive an extension `session_start` (for example non-interactive in-process child sessions): the lazy Intercom runtime initializes from the most recent turn/tool lifecycle context and delivers self-addressed results locally. If no context is available at all, the relay acknowledges the announcement as undelivered — the `subagent` tool then falls back to returning results inline — instead of recording connection errors in the session transcript.
 
-Intercom connection remains tool-driven. Foreground and background launches do not import the heavy Intercom runtime or connect either the parent or bridged child automatically. If live child-to-parent coordination is needed, the parent model should invoke `intercom({ action: "status" })` before launch; the child then connects on its first `contact_supervisor` or `intercom` call. Cancellation or session replacement still invalidates the handshake generation, so stale acknowledgements cannot surface or detach a child.
+Intercom connection remains tool-driven. Foreground launches do not import the heavy Intercom runtime or connect either the parent or bridged child automatically. If live child-to-parent coordination is needed, the parent model should invoke `intercom({ action: "status" })` before launch; the child then connects on its first `contact_supervisor` or `intercom` call. Cancellation or session replacement still invalidates the handshake generation, so stale acknowledgements cannot surface or detach a child.
 
 Atomic's implementation adapts the prompt foreground release and later-result recovery contracts proven in `nicobailon/pi-subagents` commits `1b55c8c`, `589e51e`, `68fb528`, and `9dfe3df`; it retains Atomic's broker and raw-TypeScript architecture rather than copying upstream's filesystem transport.
 
 ## Migration from acceptance gates
 
-If you have older subagent calls, saved chains, or custom agents that used the removed gate fields:
+If you have older subagent calls or custom agents that used the removed gate fields:
 
-- Remove `acceptance` properties from `subagent()` calls, `tasks` entries, `chain` steps, static parallel task items, and dynamic fanout parallel templates. Atomic no longer reads these fields; JSON chain rewrites drop legacy copies.
+- Remove `acceptance` properties from `subagent()` calls, task entries, and parallel task items. Atomic no longer reads these fields.
 - Remove `completionGuard: false` from agent frontmatter and custom agent definitions. The no-mutation completion guard no longer exists, so the override has no effect and management rewrites strip it.
 - Move validation, command, evidence, review, or residual-risk requirements into the natural-language task text passed to the parent or child agent.
 
@@ -97,50 +98,41 @@ Review the current diff with fresh-context specialists: analyze correctness, ins
 
 Useful prompt templates include `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`, and `/parallel-cleanup`. Treat them as reusable compositions, not as separate bundled agent names. Their task templates define the requested outcome, evidence and delegation boundaries, downstream output shape, and an explicit stop rule; preserve those contracts when adapting a template.
 
-## Background work and control
+## Foreground work and control
 
-Foreground subagents stream progress in the conversation and are the right default when the parent needs the result before proceeding. Use background subagents selectively for genuinely long-running or independently useful bounded delegation; they keep working after control returns and report completion later.
+Foreground subagents stream progress in the conversation and return their results before the call completes.
 
 Natural-language examples:
 
 ```text
-Run the local research scan in the background.
+Run the local research scan.
 ```
 
 ```text
-Show me the current async subagent runs.
+Show me the current subagent status.
 ```
 
 Tool examples:
 
 ```ts
-subagent({ agent: "codebase-analyzer", task: "Trace the auth flow with file references.", async: true })
-subagent({ action: "status" })
-subagent({ action: "status", id: "<run-id>" })
-subagent({ action: "interrupt", id: "<run-id>" })
-subagent({ action: "resume", id: "<run-id>", message: "continue with the test failures" })
-subagent({ action: "doctor" })
+subagent({ agent: "codebase-analyzer", task: "Trace the auth flow with file references." })
 ```
 
-Use `interrupt` when you want a resumable stop. Use `resume` to send a follow-up to a reachable child, or to cold-reload a completed child from its saved session. Use `doctor` for read-only setup diagnostics.
-
-`async: true` means **do not wait**. Atomic admits an in-process child, returns its canonical child path immediately, and tracks the live child through the jobs widget. Intercom detach uses this exact same continuation mechanism, so a foreground child that asks its supervisor to coordinate becomes `continued` instead of returning a detached placeholder.
-
-**`async: true` does not survive parent exit. The live child is owned by the parent process; quitting Atomic ends any in-flight async run. Only the persisted canonical identity and session file survive, and a later session can list that cold identity and resume it.**
+Use `interrupt` when you want a resumable stop. Use `resume` for a follow-up to a reachable or retained child. Use `doctor` for read-only setup diagnostics.
 
 Status, interrupt, list, and resume use the Rust registry and status watch for live children; terminal delivery is an in-memory bounded envelope with the artifact and run-history record persisted once. There is no PID polling, result-claim file, stale-run reconciliation, or detached runner process.
 
-Inside workflow stages, completion delivery observes the stage generation boundary. A completion received before the boundary closes is queued through the stage AgentSession and processed before the stage publishes its terminal snapshot. A completion that arrives after close is routed once to the parent/main chat and cannot reopen or append to the completed stage transcript. Producers that are still running do not hold the stage open, so background work remains non-blocking; explicit post-mortem stage chat is still available separately.
+Inside workflow stages, completion delivery observes the stage generation boundary. A completion received before the boundary closes is queued through the stage AgentSession and processed before the stage publishes its terminal snapshot. A completion that arrives after close is routed once to the parent/main chat and cannot reopen or append to the completed stage transcript. Explicit post-mortem stage chat is still available separately.
 
-When a workflow graph overlay is open, Atomic also publishes the live async subagent summary into the shared status surface. The below-editor async widget remains available when the workflow overlay is hidden, and the overlay statusline keeps the run count/state visible while the graph fills the terminal.
+Live progress and completed results show each step's resolved model, effective reasoning level, and applied Codex fast-mode marker, including after a model fallback; parallel steps keep their metadata separate.
 
 ## Orchestrator model and group policy
 
-Atomic applies the same delegation policy to any parent chat or workflow stage that orchestrates subagents. A named agent uses the model and fallback chain declared by its agent definition, so the orchestrator normally omits the subagent tool's explicit `model` argument. An override needs either the user's exact model request or a documented task-specific reason recorded before launch; model diversity alone is not enough.
+Atomic applies the same delegation policy to any parent chat or workflow stage that orchestrates subagents. A named agent uses the model and fallback sequence declared by its agent definition, so the orchestrator normally omits the subagent tool's explicit `model` argument. An override needs either the user's exact model request or a documented task-specific reason recorded before launch; model diversity alone is not enough.
 
 If an agent declares no model or fallback policy, the orchestrator consults the role guidance in [Model selection](/models/model-selection), then calls `workflow({ action: "models" })` when that tool is available. It may pin only a returned `fullId` and may add a thinking suffix only when the model entry lists that level. When the catalog tool is unavailable, the catalog is empty, or no recommended model is present, the child stays unpinned and the orchestrator reports the limit instead of inventing a model or inspecting credentials.
 
-Each workflow invocation automatically receives one stable, non-`"default"` Intercom group as typed admission policy. Its stages and delegated children carry that group across single, parallel, chain, async, and follow-up work unless a call explicitly overrides `group`. Outside workflows, children inherit the launching session's resolved group. This isolates workflow runs from unrelated runs and the main chat while `contact_supervisor` retains its authorized cross-group route.
+Each workflow invocation automatically receives one stable, non-`"default"` Intercom group as typed admission policy. Its stages and delegated children carry that group across single, parallel, and follow-up work unless a call explicitly overrides `group`. Outside workflows, children inherit the launching session's resolved group. This isolates workflow runs from unrelated runs and the main chat while `contact_supervisor` retains its authorized cross-group route.
 
 ## Context and execution modes
 
@@ -157,27 +149,27 @@ Fresh child sessions use normal Atomic package discovery when an agent omits `ex
 
 Top-level parallel calls support up to 50 subagents after expanding each task's optional `count`. The extension's `parallel.maxTasks` setting defaults to 50 and can enforce a lower task limit; `parallel.concurrency` independently controls how many of those children run at once, while the Rust turn limiter admits at most four running turns per parent.
 
-Subagent tasks, parallel/chain items, and the top-level call accept a `group` field that sets the spawned child's [Intercom](/intercom) home group, so same-group subagents can intercom each other while staying isolated from other groups. A named string joins that group; `true` auto-generates one shared UUID group per parallel set. Precedence is `explicit subagent group > inherited current-session group > config > "default"`. Workflow stages carry their runtime-owned invocation group, so children launched without `group` automatically join the workflow group; callers do not need to copy or generate an ID. In other sessions, omission inherits that launching session's resolved group. The child group is applied only when the child has Intercom access (the peer `intercom` tool or subagent-only `contact_supervisor` tool); a child without Intercom receives no group. `contact_supervisor` still reaches the supervisor across group boundaries because Atomic requests a broker capability during typed admission and binds the child's registration to the issuing supervisor. Foreground and single-child paths use exact child scopes; asynchronous chains use bounded per-child slots so indexes shifted by dynamic fanout remain valid. The lightweight Intercom wrapper lazy-loads the authorization provider; provider failures abort launch, while hosts without a provider omit supervisor metadata instead of exposing a broken channel.
+Subagent tasks, parallel items, and the top-level call accept a `group` field that sets the spawned child's [Intercom](/intercom) home group, so same-group subagents can intercom each other while staying isolated from other groups. A named string joins that group; `true` auto-generates one shared UUID group per parallel set. Precedence is `explicit subagent group > inherited current-session group > config > "default"`. Workflow stages carry their runtime-owned invocation group, so children launched without `group` automatically join the workflow group; callers do not need to copy or generate an ID. In other sessions, omission inherits that launching session's resolved group. The child group is applied only when the child has Intercom access (the peer `intercom` tool or subagent-only `contact_supervisor` tool); a child without Intercom receives no group. `contact_supervisor` still reaches the supervisor across group boundaries because Atomic requests a broker capability during typed admission and binds the child's registration to the issuing supervisor. Foreground paths use exact child scopes. The lightweight Intercom wrapper lazy-loads the authorization provider; provider failures abort launch, while hosts without a provider omit supervisor metadata instead of exposing a broken channel.
 
-When a subagent call, parallel task, chain step, or background run uses a `cwd`, Atomic validates that working directory before starting the child runtime. Missing or non-directory paths are reported as `cwd` problems instead of lower-level runtime errors.
+When a subagent call or parallel task uses a `cwd`, Atomic validates that working directory before starting the child runtime. Missing or non-directory paths are reported as `cwd` problems instead of lower-level runtime errors.
 
-Single-agent calls also accept `reads: string[] | false`. Atomic prepends those files as read context for foreground and background execution through the same in-process session path, including `/run agent[reads=a.md+b.md]`. Relative entries resolve against the effective child `cwd` (including a relative top-level `cwd` resolved from the parent); absolute entries are unchanged. Invalid values fail before the child session starts.
+Single-agent calls also accept `reads: string[] | false`. Atomic prepends those files as read context for foreground execution through the same in-process session path, including `/run agent[reads=a.md+b.md]`. Relative entries resolve against the effective child `cwd` (including a relative top-level `cwd` resolved from the parent); absolute entries are unchanged. Invalid values fail before the child session starts.
 
-Single-agent calls accept `progress: boolean` in foreground, background, and revived/resumed mode. `progress: true` creates a run-scoped `progress.md` under isolated subagent artifact storage and instructs the child to maintain it without writing `progress.md` into the child `cwd`; `progress: false` disables an agent's `defaultProgress`. When `progress` is omitted, the agent's default is inherited, except that inherited progress is suppressed for read-only tasks (`progress: true` still explicitly opts in). Foreground runs remove this run-owned progress storage after the child exits when `artifacts: false`, including children temporarily detached for intercom coordination. This is separate from `includeProgress: true`, which only includes detailed runtime progress telemetry in the final tool result and does not create or maintain a file.
+Single-agent calls accept `progress: boolean` in foreground and resumed mode. `progress: true` creates a run-scoped `progress.md` under isolated subagent artifact storage and instructs the child to maintain it without writing `progress.md` into the child `cwd`; `progress: false` disables an agent's `defaultProgress`. When `progress` is omitted, the agent's default is inherited, except that inherited progress is suppressed for read-only tasks (`progress: true` still explicitly opts in). Foreground runs remove this run-owned progress storage after the child exits when `artifacts: false`, including children temporarily detached for intercom coordination. This is separate from `includeProgress: true`, which only includes detailed runtime progress telemetry in the final tool result and does not create or maintain a file.
 
 ```ts
 subagent({ agent: "worker", task: "Implement the approved fix.", progress: true })
-subagent({ agent: "worker", task: "Implement it in the background.", progress: true, async: true })
 ```
 
 ## Nested and fanout boundaries
 
 Child-safety boundaries are enforced by typed admission policy and the bundled subagent extension:
 
-- Normal child sessions do not receive the `subagent` tool or the parent-only subagents skill.
+- In-process child sessions load bundled extensions through normal discovery. The `subagent` tool may therefore be registered when the child's active tool selection permits it, including the default no-allowlist case; an explicit allowlist may omit it. Tool presence does not grant fanout. The bundled subagents skill remains parent-only and is stripped from child prompts, including fanout-authorized children.
 - Child context is filtered to remove parent orchestration artifacts, old control/status messages, and prior parent `subagent` tool calls/results.
 - Non-fanout children are instructed that they are not the parent orchestrator and must not propose or run subagents.
 - Nested fanout is available only for explicitly authorized agents whose resolved tools include `subagent`. Authorized fanout children receive narrower instructions that limit delegation to the assigned fanout.
+- Typed admission policy lets a non-fanout child use only `list`, `get`, `status`, and `doctor`; delegation, `resume`, and `interrupt` receive the fanout refusal. A management-restricted child is also refused `create`, `update`, and `delete`.
 - The recursion guard has a hard maximum of five delegated subagent levels. The admitted depth policy may choose a lower value from `0` to `5`; deeper admission is refused rather than inherited from process environment state.
 
 This keeps the parent session responsible for orchestration unless you deliberately choose a fanout-capable custom agent.
@@ -213,30 +205,11 @@ Cite each actionable issue with file:line evidence and the observed failure or r
 Return only issues worth fixing now. Stop when the relevant diff and affected call paths have been inspected, or name the evidence you could not access.
 ```
 
-If an agent or chain step uses an explicit empty `tools: []` allowlist together with `outputSchema`, Atomic starts the child with only `structured_output` enabled for the required final answer. It does not omit `--tools` and accidentally restore default tools. Path-only tool entries remain extension paths and do not create a builtin allowlist by themselves. The typed child session construction registers its schema-backed `structured_output` tool before explicit allowlists are applied.
-
-## Structured output schemas
-
-Chain and parallel steps can declare an `outputSchema` when the parent needs reliable machine-readable handoff data. Atomic passes that schema directly to a `structured_output` tool backed by the shared Atomic factory. The child should call `structured_output` when it is done:
-
-```ts
-structured_output({
-  files: ["src/auth.ts"],
-  risks: ["missing regression test"],
-})
-```
-
-`outputSchema` is a plain JSON Schema descriptor object. It may describe object, array, or primitive final values, and the child should pass a JSON value that matches that schema directly. Atomic no longer adds object-root restrictions, sidecar metadata, transcript-finality checks, or duplicate-call guards. The child runtime writes the tool arguments to `output.json`; the parent validates that captured JSON against the schema, reads it back as `result.structuredOutput`, and exposes it in named-chain references under `outputs.name.structured`. If the child exits without calling `structured_output`, or the captured value fails schema validation, Atomic retries up to three times with a corrective prompt that quotes the exact contract/validation error and reminds the child to call `structured_output` rather than returning plain JSON.
-
-Children without `outputSchema` do not receive `structured_output` from Atomic's default tool registry. They can still use a custom extension-provided terminating tool if you explicitly add one.
-
-Dynamic fanout `collect.outputSchema` validates the collected result array after child runs finish.
-
 ## Fallback models
 
 Agents can define ordered `fallbackModels` for retryable provider or model failures such as rate limits, quota/usage-limit exhaustion (for example a provider reporting `The usage limit has been reached`, or `usage_limit_reached`/`insufficient_quota` codes), auth problems, unavailable models, network timeouts, or 5xx errors. Atomic tries the requested primary model first, then configured fallbacks, and finally appends the current user-selected model as the last fallback candidate when available. The main chat and workflow stages share one failure classifier, so auth, model-availability, request-incompatibility, and transport signals are handled consistently. Cancellations, safety refusals, and task/tool failures are never retried on another model.
 
-A candidate that cannot serve the current request — for example an HTTP 400/413/422 bad/unprocessable/payload-too-large request, an unsupported tool or parameter, a context-length/context-window overflow, or a `too large` / `invalid_request` error — is treated as request/context incompatible and the chain advances to the next candidate rather than stopping. This means that if none of the configured candidates are applicable to the request, Atomic falls back to the currently selected user model instead of failing outright.
+A candidate that cannot serve the current request — for example an HTTP 400/413/422 bad/unprocessable/payload-too-large request, an unsupported tool or parameter, a context-length/context-window overflow, or a `too large` / `invalid_request` error — is treated as request/context incompatible and the fallback sequence advances to the next candidate rather than stopping. This means that if none of the configured candidates are applicable to the request, Atomic falls back to the currently selected user model instead of failing outright.
 
 Model fallback decisions use structured provider and attempt causes. There is no per-attempt idle watchdog, no child wall-clock kill cap, and no timeout-regex classification: a quiet provider response is allowed to finish, and only an explicit termination or provider failure supplies a retryable cause. Numeric process exit codes are not used as an outcome discriminator.
 

package/docs/themes.md

@@ -73,6 +73,7 @@ vim ~/.atomic/agent/themes/my-theme.json
     "text": "",
     "thinkingText": "secondary",
     "selectedBg": "#2d2d30",
+    "scrollbarThumb": "#555566",
     "userMessageBg": "#2d2d30",
     "userMessageText": "",
     "customMessageBg": "#2d2d30",
@@ -149,14 +150,14 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 - `name` is required, must be unique, and must not contain `/`.
 - `vars` is optional. Define reusable colors here, then reference them in `colors` or `workingIndicator`.
-- `colors` must define all 51 required tokens.
+- `colors` must define all 51 required tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted.
 - `workingIndicator` is optional and may override any subset of the six tones in the outward half of the ordinary `∀` ramp; Atomic derives omitted tones from selected background, accent, and text roles, then mirrors the palette back after `peak`. Explicit numeric values from 0 through 255 remain exact terminal palette indices. When a numeric index from 0 through 15 seeds an omitted tone, Atomic mixes from its built-in approximation of the common ANSI RGB value; the terminal still controls the actual appearance of the explicit index. Both explicit and derived tones update on theme hot reload.
 
 The `$schema` field enables editor auto-completion and validation.
 
 ## Color Tokens
 
-Every theme must define all 51 color tokens. There are no optional colors.
+Every theme must define all 51 required color tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted.
 
 ### Core UI (11 colors)
 
@@ -174,11 +175,12 @@ Every theme must define all 51 color tokens. There are no optional colors.
 | `text` | Default text (usually `""`) |
 | `thinkingText` | Thinking block text |
 
-### Backgrounds & Content (11 colors)
+### Backgrounds & Content (11 required, 1 optional)
 
 | Token | Purpose |
 |-------|---------|
 | `selectedBg` | Selected line background |
+| `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
 | `userMessageBg` | User message background |
 | `userMessageText` | User message text |
 | `customMessageBg` | Extension message background |