@bastani/atomic 0.9.39-alpha.2 → 0.9.40-alpha.1

package/docs/reference/cli.md

@@ -142,6 +142,8 @@ When a print-mode turn correctly finishes by calling an opt-in terminating struc
 | `--session-prefix <prefix>` | Use a non-default table prefix with `--session-store` |
 | `--name <name>`, `-n <name>` | Set the session display name |
 | `--no-session` | Ephemeral mode; do not save |
+| `--storage <json>` | Select storage for this process's sessions and workflow runs, in the same JSON form as the shared `storage` setting; never saved. See [Selecting storage per process](/storage#selecting-storage-per-process) |
+| `--storage-file <path>` | Read the `--storage` selection from a JSON file; cannot be combined with `--storage` |
 
 See [Choosing a store](/sessions#choosing-a-store) for precedence, prefix rules, and conflicts.
 
@@ -251,6 +253,9 @@ atomic --tools read,search,find,ls -p "Review the code"
 | `AI_AGENT` | Set to `atomic` by the CLI, RPC, and compiled binary entry points and in every Atomic-owned child-process environment so generic tooling can identify Atomic processes; child environments override caller-supplied values without mutating the caller's environment object |
 | `ATOMIC_CODING_AGENT_DIR` | Override config directory; default is `~/.atomic/agent`. Bundled intercom runtime/config files live under its `intercom/` subdirectory |
 | `ATOMIC_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
+| `ATOMIC_STORAGE` | Storage selection JSON for this process's sessions and workflow runs; overridden by `--storage` and the domain variables |
+| `ATOMIC_SESSIONS_STORAGE` | Session-only storage selection JSON; cannot be combined with `ATOMIC_CODING_AGENT_SESSION_DIR` |
+| `ATOMIC_WORKFLOWS_JOURNAL` | Workflow-run-only storage selection JSON; cannot be combined with `ATOMIC_WORKFLOW_JOURNAL_PATH` |
 | `ATOMIC_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
 | `ATOMIC_REDUCED_MOTION` | Set to `1` to skip startup choreography and render the ordinary working identity as a static regular accent `∀` without a timer |
 | `ATOMIC_OFFLINE` | Disable automatic network activity, including update checks, package update checks, install/update telemetry, and model catalog refreshes |

package/docs/rpc/protocol.md

@@ -789,6 +789,25 @@ If an extension cancelled the switch:
 {"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
 ```
 
+#### start_pending_recovery
+
+Recover work an earlier process left unfinished in the current session. Send it after you have shown the transcript, at startup or after `switch_session`.
+
+Loading or switching a session never recovers anything by itself. Until a client sends this command, interrupted deliveries stay pending in the session. The command runs once per loaded session; repeating it returns the same report. It does not block other commands, so prompts and `abort` keep working while it runs.
+
+```json
+{"type": "start_pending_recovery", "reason": "resume"}
+```
+
+`reason` is optional and accepts `"startup"`, `"resume"`, or `"workflow_stage_resume"`.
+
+Extensions first restore their background work. Interrupted deliveries that are still wanted are then replayed in a turn, which streams like any other turn. Notices and undelivered background task results are appended without starting a turn.
+
+The response arrives when recovery has finished:
+```json
+{"type": "response", "command": "start_pending_recovery", "success": true, "data": {"replayed": 1, "dropped": 1, "completions": 0, "notices": ["Worker reviewer is gone."]}}
+```
+
 #### fork
 
 Create a new fork from a previous user message on the active branch. Can be cancelled by a `session_before_fork` extension event handler. Returns the text of the message being forked from.

package/docs/rpc.md

@@ -32,6 +32,9 @@ Common options:
 - `--name <name>` / `-n <name>`: Set the session display name at startup
 - `--no-session`: Disable session persistence
 - `--session-dir <path>`: Custom session storage directory
+- `--storage '<json>'` / `--storage-file <path>`: Select storage for this process's sessions and workflow runs
+
+To give an RPC child its own store without changing the user's settings, start it with `ATOMIC_STORAGE` (or `--storage`) holding the same JSON selection as the shared `storage` setting, for example an adapter selection with `secrets` read from `{ "env": ... }`. The child keeps its sessions and workflow runs there, and `list_sessions` and `list_workflow_runs` report that store. An `atomic` started without the selection keeps using its settings. An invalid selection fails at startup with `StorageConfigError` naming the variable or flag. See [Selecting storage per process](/storage#selecting-storage-per-process).
 
 ## Protocol Overview
 

package/docs/sdk/web-server.md

@@ -304,7 +304,7 @@ By default, `run()` persists workflow state in the local SQLite journal at `~/.a
 
 Use `journal: { path: "/var/lib/my-service/workflows.sqlite" }` to select a file for a run, or `journal: { memory: true }` for process-local state that cannot survive a restart. Supply a caller-owned async SQLite facade as `{ database, prefix? }`; Atomic does not close it. You can also supply a `RunJournal` instance or `{ adapter, options?, secrets?, prefix? }` for a user-installed driver module.
 
-`RunOpts.journal` (or `createAgentSession({ journal })` for sessions) overrides a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, then `workflows.journal`, then shared top-level `storage`, then the default file. Nearer settings replace whole selections. Relative settings paths resolve against Atomic home. Configuration or storage failures stop the run instead of switching to memory. See [Choosing the durable backend](/workflows/api-reference#choosing-the-durable-backend).
+`RunOpts.journal` (or `createAgentSession({ journal })` for sessions) overrides `ATOMIC_WORKFLOWS_JOURNAL` or a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, then `ATOMIC_STORAGE`, then `workflows.journal`, then shared top-level `storage`, then the default file. Nearer settings replace whole selections. Relative settings paths resolve against Atomic home. Configuration or storage failures stop the run instead of switching to memory. See [Choosing the durable backend](/workflows/api-reference#choosing-the-durable-backend).
 
 ## Secure the endpoint
 

package/docs/sdk.md

@@ -144,6 +144,8 @@ Use `builtins: { "web-access": false, intercom: false }` to disable specific shi
 
 Creation finishes extension startup before returning. Pass `extensionBindings` when startup hooks need your host bindings. Later `session.bindExtensions(...)` updates those bindings without replaying `session_start`; reload starts a new extension generation. Missing shipped assets reject with an error whose `code` is `BuiltinUnavailable` and whose message names the package. Reinstall the package rather than continuing with a partially available session.
 
+Opening or binding a session never recovers work an earlier process left unfinished. That work includes restoring background subagents, replaying interrupted deliveries, and showing undelivered background results. Call `await session.startPendingRecovery("resume")` once you are ready to show its output. It runs once per session and resolves with a report: `{ replayed, dropped, completions, notices }`.
+
 ```typescript
 import { createAgentSession, SessionManager } from "@bastani/atomic";
 
@@ -172,7 +174,7 @@ const { session } = await createAgentSession({
 
 Other selections are `{ kind: "jsonl", dir }`, `{ kind: "memory" }`, `{ kind: "database", database, prefix? }`, and `{ kind: "adapter", module, options?, secrets?, prefix? }`. `database` must implement the async `SqliteDatabase` facade. Install your own driver and expose an adapter module for a remote database; Atomic bundles only its local `node:sqlite` adapter. See [Storage adapters](/storage).
 
-`sessionStore` also accepts a `SessionStore` instance. A supplied `sessionManager` takes precedence and remains caller-owned. Otherwise, explicit SDK storage wins over the session-directory environment variable, `sessions.storage`, shared `storage`, and the persistent default. Memory is never a default or an opening-failure fallback. The `sessionDir` factory option has been removed; use a JSONL `sessionStore` selection instead. See [Session storage settings](/settings#sessions) for scope and path rules.
+`sessionStore` also accepts a `SessionStore` instance. A supplied `sessionManager` takes precedence and remains caller-owned. Otherwise, explicit SDK storage wins over the process-level variables (`ATOMIC_SESSIONS_STORAGE` or the session-directory variable, then `ATOMIC_STORAGE`), `sessions.storage`, shared `storage`, and the persistent default. Memory is never a default or an opening-failure fallback. The `sessionDir` factory option has been removed; use a JSONL `sessionStore` selection instead. See [Session storage settings](/settings#sessions) for scope and path rules, and [Selecting storage per process](/storage#selecting-storage-per-process) to choose storage for the processes a host starts, such as `atomic --mode rpc` children, without editing settings.
 
 Atomic closes stores it opens from a selection when the session is disposed, after pending writes finish. Supplied `SessionStore` instances and stores belonging to supplied managers remain caller-owned. With `{ kind: "database", database }`, Atomic closes its store but leaves your database open. Always await `session.dispose()` and close caller-owned stores when no session still uses them.
 
@@ -293,7 +295,7 @@ const second = await createAgentSession({ journal: { memory: true } });
 
 Without a `journal` option, the session's own `workflows.journal` setting applies, including settings passed through `SettingsManager.inMemory({ workflows: { journal: { path: "./runs.sqlite" } } })`. A `memory: true` journal selected this way belongs to that session alone. Disposing a session closes the journals Atomic opened for it once no other session is using them, so runs kept in a memory journal end with the session. Atomic never closes a database or journal you supply.
 
-Without a per-run or per-session option, a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH` overrides `workflows.journal`, which overrides shared top-level `storage`. Nearer-scope settings replace whole selections. Relative settings paths resolve against Atomic home. The default journal is `~/.atomic/workflows/journal.sqlite`; an empty shared selection uses `~/.atomic/storage.sqlite`. Keep the original journal and working directory to resume saved runs. Invalid configuration and storage failures reject rather than switching to memory. See [Workflow storage settings](/settings#workflow-storage).
+Without a per-run or per-session option, `ATOMIC_WORKFLOWS_JOURNAL` or a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH` wins, then `ATOMIC_STORAGE`, then `workflows.journal`, then shared top-level `storage`. Setting both journal variables is a conflict. Nearer-scope settings replace whole selections. Relative settings paths resolve against Atomic home. The default journal is `~/.atomic/workflows/journal.sqlite`; an empty shared selection uses `~/.atomic/storage.sqlite`. Keep the original journal and working directory to resume saved runs. Invalid configuration and storage failures reject rather than switching to memory. See [Workflow storage settings](/settings#workflow-storage) and [Selecting storage per process](/storage#selecting-storage-per-process).
 
 ### Workflow run control
 
@@ -618,6 +620,7 @@ Important behavior:
 - `runtime.session` changes after those operations
 - event subscriptions are attached to a specific `AgentSession`, so re-subscribe after replacement
 - if you use extensions, call `runtime.session.bindExtensions(...)` again for the new session
+- after a `switchSession()`, call `runtime.session.startPendingRecovery("resume")` to recover interrupted work
 - creation returns diagnostics on `runtime.diagnostics`
 - if runtime creation or replacement fails, the method throws and the caller decides how to handle it
 

package/docs/sessions.md

@@ -46,7 +46,9 @@ Imported IDs are kept verbatim, including an empty ID. Resume an imported empty
 
 This selects JSONL under `~/.atomic/sessions`. Use `{ "path": "sessions.sqlite" }` for another local SQLite file, `{ "memory": true }` for ephemeral sessions, or an adapter selection for a user-installed database driver. The `sessionDir` setting has been removed without an alias.
 
-Precedence is SDK `sessionStore`, `--no-session`, `--session-dir <dir>` or `--session-store <path>` (mutually exclusive CLI selections), non-empty `ATOMIC_CODING_AGENT_SESSION_DIR`, `sessions.storage`, shared `storage`, then the default SQLite file. Each selection wins as a whole; project selections replace global ones rather than merging fields. Relative settings paths resolve against Atomic home; CLI paths and environment directories resolve against the working directory. Changing stores selects a different history, and only the default store shows earlier JSONL sessions; keep the original store to return to it.
+Precedence is SDK `sessionStore`, `--no-session`, `--session-dir <dir>` or `--session-store <path>` (mutually exclusive CLI selections), `--storage` or `--storage-file`, `ATOMIC_SESSIONS_STORAGE` or non-empty `ATOMIC_CODING_AGENT_SESSION_DIR`, `ATOMIC_STORAGE`, `sessions.storage`, shared `storage`, then the default SQLite file. Each selection wins as a whole; project selections replace global ones rather than merging fields. Relative settings paths resolve against Atomic home; `--session-dir`, `--session-store`, and `ATOMIC_CODING_AGENT_SESSION_DIR` resolve against the working directory. Changing stores selects a different history, and only the default store shows earlier JSONL sessions; keep the original store to return to it.
+
+`--storage '<json>'`, `--storage-file <path>`, and the `ATOMIC_STORAGE` and `ATOMIC_SESSIONS_STORAGE` variables select storage for one process, using the same JSON as the settings, without changing settings. `/resume` then lists the sessions in that process's store. See [Selecting storage per process](/storage#selecting-storage-per-process) for the precedence table and conflict rules.
 
 `--session-store` cannot be combined with `--session-dir` or `--no-session`. `--session-prefix` requires `--session-store` and defaults to empty, giving `session_` table names. A non-empty prefix is prepended to those names, must match `[A-Za-z_][A-Za-z0-9_]*`, and must not start with `sqlite_` (case-insensitive). Invalid configuration or unavailable storage raises a typed error, never a fallback to another store.
 
@@ -97,6 +99,20 @@ When you resume at startup with the default tool selection, Atomic restores the
 
 Workflow stages and subagents that fork the conversation keep their own configured tools, including stage result tools and child-only extension tools, rather than adopting the parent's recorded selection. Parent tool restrictions still apply.
 
+### Interrupted work on resume
+
+If Atomic exits while work is in flight, for example while background subagents are still sending Intercom messages, resuming the session with `--session`, `--continue`, `-r`, or `/resume` shows the transcript first. Recovery starts only after that, and everything it does appears in the transcript:
+
+- Background subagents the session launched are restored and reconnected to Intercom. This also covers children that were running when you switched away with `/new`, `/resume` to another session, or `/fork`. A session forked from it does not restore them. Paused, quit, interrupted, completed, and failed children are not restarted; continue them with `subagent({ action: "resume", id })`. Each subagent launch card shows the child's latest state, and a resumed child continues in its original card. See [Run control](/subagents#run-control).
+- Messages that were shown before the exit but never reached the agent are replayed in a visible turn. A "Replaying N interrupted deliveries" line appears before it.
+- Messages from a peer that no longer exists are not replayed. One notice tells you and the agent which peers are gone, and it does not start a turn.
+- If Intercom cannot be reached, its interrupted messages are neither replayed nor discarded. A notice says they were deferred, and the next resume decides about them again.
+- Messages from a background subagent that was relaunched but has not reconnected to Intercom yet are deferred in the same way, because it may still reconnect. The notice says it is not gone.
+- Background task results that were never delivered are shown as cards without starting a turn.
+- A status line summarizes what was recovered.
+
+Non-interactive runs such as `atomic -p` do not recover interrupted work. It stays pending until the session is next resumed interactively.
+
 In the picker you can:
 
 - search by typing

package/docs/settings.md

@@ -509,11 +509,13 @@ Plain names establish a replacement list before its modifiers apply. A project l
 
 Without configuration, sessions and workflow runs share `~/.atomic/workflows/journal.sqlite`. Session tables use `session_` names; workflow tables use `wf_` names. If `ATOMIC_CODING_AGENT_DIR` changes the agent directory, this default is `workflows/journal.sqlite` under its parent. JSONL is opt-in through `dir`, `--session-dir`, or `ATOMIC_CODING_AGENT_SESSION_DIR`. The `sessionDir` setting has been removed; use `sessions.storage.dir` instead.
 
-Session precedence is SDK `sessionStore`, `--no-session`, `--session-dir` or `--session-store` (mutually exclusive CLI selections), non-empty `ATOMIC_CODING_AGENT_SESSION_DIR`, `sessions.storage`, shared `storage`, then the default SQLite file. Empty environment values are ignored. Project selections replace global selections as whole objects, including options, secrets and prefix; fields are never merged. A present empty `sessions.storage` selects the default session database rather than inheriting `storage`. Relative settings paths resolve against Atomic home, normally `~/.atomic`. CLI paths and environment directories resolve against the working directory.
+Session precedence is SDK `sessionStore`, `--no-session`, `--session-dir` or `--session-store` (mutually exclusive CLI selections), `--storage` or `--storage-file`, `ATOMIC_SESSIONS_STORAGE` or non-empty `ATOMIC_CODING_AGENT_SESSION_DIR`, `ATOMIC_STORAGE`, `sessions.storage`, shared `storage`, then the default SQLite file. Empty environment values are ignored. Project selections replace global selections as whole objects, including options, secrets and prefix; fields are never merged. A present empty `sessions.storage` selects the default session database rather than inheriting `storage`. Relative settings paths resolve against Atomic home, normally `~/.atomic`, and so do relative paths in the JSON selections of `--storage`, `ATOMIC_STORAGE`, and `ATOMIC_SESSIONS_STORAGE`. `--session-dir`, `--session-store`, and `ATOMIC_CODING_AGENT_SESSION_DIR` resolve against the working directory.
+
+To select storage for one process without editing settings, pass the same JSON selection in `ATOMIC_STORAGE`, `ATOMIC_SESSIONS_STORAGE`, `ATOMIC_WORKFLOWS_JOURNAL`, `--storage`, or `--storage-file`. See [Selecting storage per process](/storage#selecting-storage-per-process).
 
 See [Choosing a store](/sessions#choosing-a-store) for CLI selection, prefix rules, and conflicts.
 
-Only the selected source is validated; invalid lower-precedence selections do not block an explicit override. Memory must be selected explicitly and is lost on exit. Invalid selected configuration raises `StorageConfigError`, whose `source`, `field`, and `reason` identify the problem. If a selected store cannot open, Atomic raises a typed storage error rather than falling back to memory. See [Sessions](/sessions#session-storage) and [Storage errors](/storage#storage-errors).
+Only the selected setting is validated; invalid lower-precedence settings do not block an explicit override. Every set `ATOMIC_STORAGE`, `ATOMIC_SESSIONS_STORAGE`, and `ATOMIC_WORKFLOWS_JOURNAL` is validated even when outranked. Memory must be selected explicitly and is lost on exit. Invalid selected configuration raises `StorageConfigError`, whose `source`, `field`, and `reason` identify the problem. If a selected store cannot open, Atomic raises a typed storage error rather than falling back to memory. See [Sessions](/sessions#session-storage) and [Storage errors](/storage#storage-errors).
 
 ### Models
 
@@ -573,7 +575,7 @@ Workflow runs use a SQLite journal, by default the local file `~/.atomic/workflo
 }
 ```
 
-Relative settings paths resolve against the Atomic home directory, normally `~/.atomic`, not the project directory. Precedence is SDK `RunOpts.journal` (or `createAgentSession({ journal })` for a session's `workflow` tool), non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, `workflows.journal`, shared top-level `storage`, then the default journal file. An empty environment variable is ignored. SDK sessions read `workflows.journal` from the settings they were given, so `SettingsManager.inMemory(...)` selects a journal per session. A present empty journal block selects the journal default rather than inheriting shared storage.
+Relative settings paths resolve against the Atomic home directory, normally `~/.atomic`, not the project directory. Precedence is SDK `RunOpts.journal` (or `createAgentSession({ journal })` for a session's `workflow` tool), `--storage` or `--storage-file`, `ATOMIC_WORKFLOWS_JOURNAL` or non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, `ATOMIC_STORAGE`, `workflows.journal`, shared top-level `storage`, then the default journal file. An empty environment variable is ignored. SDK sessions read `workflows.journal` from the settings they were given, so `SettingsManager.inMemory(...)` selects a journal per session. A present empty journal block selects the journal default rather than inheriting shared storage. See [Selecting storage per process](/storage#selecting-storage-per-process).
 
 To keep workflow records only in memory, set `"journal": { "memory": true }`. Do not combine `memory: true` with a non-empty `path`. Memory must be selected explicitly and cannot recover runs after the process exits; an environment path still takes precedence over this setting.
 

package/docs/skills.md

@@ -117,7 +117,7 @@ Offline, `qlty metrics` and `qlty smells` still work through built-in static ana
 
 Load `/skill:agent-browser` first for anything it covers: websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator (`agent-browser -p ios`), Electron and other apps that expose a CDP port, Slack, and cloud browsers. Its text snapshots cost far fewer tokens than screenshot-driven CUA. For everything else, including native desktop apps, native iOS apps in the Simulator, Android emulators, OS dialogs, and desktop Safari or other non-Chromium browsers, load `/skill:cua-driver` and drive the exact window with one-shot `cua-driver call <tool>` commands; when a custom workflow's TypeScript owns the scenario, use the `@trycua/cua-driver` SDK inside `ctx.tool` instead. See [what agent-browser covers](/computer-use#what-agent-browser-covers) for the full split, and [Computer use](/computer-use#desktop-automation-with-cua-driver) for installing the Cua Driver executable, turning telemetry off, readiness, and permissions. For terminal automation/testing, prefer `/skill:herdr` on macOS, Linux and Windows. Install Herdr if missing when network access and permissions permit; fall back to `/skill:tmux` or native Windows psmux when installation or use is not possible. Preserve the upstream skill's explicit-request and managed-pane requirements. These are separate interfaces, not interchangeable command names. See [verification and desktop safety](/workflows/verification) for installation, permissions, dedicated sessions and evidence.
 
-The bundled [Cua Driver skill](https://github.com/trycua/cua/tree/cua-driver-rs-v0.34.0/libs/cua-driver/rust/Skills/cua-driver) is upstream's `libs/cua-driver/rust/Skills/cua-driver` at tag `cua-driver-rs-v0.34.0`, vendored verbatim with all three platform guides (`MACOS.md`, `WINDOWS.md`, `LINUX.md`) plus `WORKFLOW.md`, `RUNTIME.md`, `VISUAL.md`, `BROWSER.md`, `RECORDING.md`, and `EMBEDDING.md`; only the `SKILL.md` frontmatter is Atomic-owned. MIT licensed, © 2025 Cua AI, Inc. Its core guide routes to focused references for authorization, exact targets, observation, and outcome verification. It does not install the `cua-driver` executable, grant permissions, or turn telemetry off, and Atomic never runs `cua-driver skills install`. Chromium browsers, Mobile Safari, and CDP-exposing apps stay with `agent-browser` even though the vendored `BROWSER.md` describes upstream's browser route; that route applies only to browsers agent-browser cannot reach, such as desktop Safari or Firefox.
+The bundled [Cua Driver skill](https://github.com/trycua/cua/tree/cua-driver-rs-v0.36.0/libs/cua-driver/rust/Skills/cua-driver) is upstream's `libs/cua-driver/rust/Skills/cua-driver` at tag `cua-driver-rs-v0.36.0`, vendored verbatim with all three platform guides (`MACOS.md`, `WINDOWS.md`, `LINUX.md`) plus `WORKFLOW.md`, `RUNTIME.md`, `VISUAL.md`, `BROWSER.md`, `RECORDING.md`, and `EMBEDDING.md`; only the `SKILL.md` frontmatter is Atomic-owned. MIT licensed, © 2025 Cua AI, Inc. Its core guide routes to focused references for authorization, exact targets, observation, and outcome verification. It does not install the `cua-driver` executable, grant permissions, or turn telemetry off, and Atomic never runs `cua-driver skills install`. Chromium browsers, Mobile Safari, and CDP-exposing apps stay with `agent-browser` even though the vendored `BROWSER.md` describes upstream's browser route; that route applies only to browsers agent-browser cannot reach, such as desktop Safari or Firefox.
 
 The bundled [Herdr skill](https://github.com/herdrdev/herdr/blob/v0.9.0/skills/herdr/SKILL.md) requires an explicit Herdr mention or request and `HERDR_ENV=1`; it stops outside a Herdr-managed pane. It does not install Herdr or authorize control of unrelated panes. Use returned pane IDs, and check completion separately from command submission.
 

package/docs/storage.md

@@ -1,6 +1,6 @@
 # SQLite storage API
 
-The SDK exposes an async SQLite API from `@bastani/atomic` and `@bastani/atomic/storage`. Sessions and workflow runs default to one local file, `~/.atomic/workflows/journal.sqlite`, with `session_` and `wf_` table prefixes. Use [storage settings](/settings#sessions) to choose a different file, explicit JSONL sessions, explicit memory, or an adapter module. A failed persistent store never falls back to memory.
+The SDK exposes an async SQLite API from `@bastani/atomic` and `@bastani/atomic/storage`. Sessions and workflow runs default to one local file, `~/.atomic/workflows/journal.sqlite`, with `session_` and `wf_` table prefixes. Use [storage settings](/settings#sessions) to choose a different file, explicit JSONL sessions, explicit memory, or an adapter module, or [select storage per process](#selecting-storage-per-process) without editing settings. A failed persistent store never falls back to memory.
 
 For CLI storage selection and resume commands, see [Choosing a store](/sessions#choosing-a-store).
 
@@ -306,7 +306,7 @@ export default {
 
 Select it with `sessions.storage: { "adapter": "@example/atomic-sqlite" }`, `workflows.journal`, or shared top-level `storage` in [settings](/settings#workflow-storage). SDK sessions accept `sessionStore: { kind: "adapter", module, options, secrets, prefix }`; workflow runs accept `journal: { adapter, options, secrets, prefix }`. Module specifiers resolve from the agent directory, normally `~/.atomic/agent`; absolute module paths also work. Project settings follow the same trust boundary as project extensions. A module executes with Atomic's privileges.
 
-`options` is an object of SQLite scalar values or booleans. In JSON settings use strings, numbers, booleans, or null. `secrets` maps option names to `{ env }` or `{ file }`; resolved values override same-named options without trimming file contents. Keep credentials out of `options` and database descriptors. `context` contains `agentDir`, `domain: "sessions" | "journal"`, and an optional `signal`.
+`options` is an object of SQLite scalar values or booleans. In JSON settings use strings, numbers, booleans, or null. `secrets` maps option names to `{ env }` or `{ file }`; resolved values override same-named options without trimming file contents. Keep credentials out of `options` and database descriptors. `context` contains `agentDir`, `domain: "sessions" | "journal" | "intercom"`, and an optional `signal`. Intercom brokers open the top-level `storage` selection with `domain: "intercom"` through `openDatabase`.
 
 A SQLite adapter implements `openDatabase(options, context): Promise<SqliteDatabase>`. Atomic applies its domain schema and optional table prefix. A full adapter can instead implement `openSessionStore(options, context, storage)` or `openRunJournal(options, context, storage)`; the domain hook takes priority over `openDatabase`. The typed third argument is `{ readonly prefix?: string }`. Domain adapters must honor this prefix to isolate selected stores. A missing domain/database hook raises `StorageConfigError` with reason `"adapter-domain-unsupported"`. Load failures and invalid module contracts raise `StorageAdapterLoadError`; driver opening failures raise `StorageUnavailableError`. None selects memory as a fallback.
 
@@ -318,6 +318,55 @@ If opening storage fails and closing its owned database also fails, the original
 
 Factory-created journal headers record a credential-free `storage` descriptor for diagnostics. Full domain adapters are responsible for recording their own safe descriptor. Directly supplied journals and their caller-provided headers are not rewritten.
 
+## Selecting storage per process
+
+A host that starts Atomic processes, for example a supervisor that launches `atomic --mode rpc` children, can select storage for those processes alone. Each option holds the same JSON selection the settings accept, including `adapter`, `options`, `secrets`, and `prefix`:
+
+| Option | Applies to | Same form as |
+|---|---|---|
+| `--storage '<json>'` | Sessions and workflow runs | Shared `storage` setting |
+| `--storage-file <path>` | Sessions and workflow runs; reads the JSON from a file | Shared `storage` setting |
+| `ATOMIC_STORAGE` | Sessions and workflow runs | Shared `storage` setting |
+| `ATOMIC_SESSIONS_STORAGE` | Sessions only; also accepts `{ "dir": "..." }` | `sessions.storage` |
+| `ATOMIC_WORKFLOWS_JOURNAL` | Workflow runs only | `workflows.journal` |
+
+```bash
+ATOMIC_STORAGE='{"adapter":"@example/atomic-sqlite","options":{"url":"libsql://team.example"},"secrets":{"authToken":{"env":"TEAM_DB_TOKEN"}},"prefix":"svc_"}' \
+  atomic --mode rpc
+
+atomic --mode rpc --storage-file /etc/atomic/storage.json
+```
+
+Nothing is written to settings. A process started without these options keeps using its settings, so an interactive `atomic` and an RPC child started with `ATOMIC_STORAGE` in the same account each keep their own sessions and workflow runs, and `/resume` in each lists only its own store. `--storage` and `--storage-file` cannot be combined. The interactive CLI passes its `--storage` selection to its background engine process. Other processes that Atomic starts inherit the environment variables but not the flag.
+
+The Intercom broker an Atomic process starts uses the same selection for multi-node routing: `--storage`, `--storage-file`, or `ATOMIC_STORAGE` from that process outranks the top-level `storage` setting, and a broker started by a process without them reads settings. One broker serves every session in an agent directory, so it keeps the selection of the process that started it until it exits.
+
+Precedence for each domain, highest first:
+
+| Sessions | Workflow runs |
+|---|---|
+| SDK `sessionStore` | SDK `RunOpts.journal` or `createAgentSession({ journal })` |
+| `--session-store`, `--no-session`, or `--session-dir` | |
+| `--storage` or `--storage-file` | `--storage` or `--storage-file` |
+| `ATOMIC_SESSIONS_STORAGE` or `ATOMIC_CODING_AGENT_SESSION_DIR` | `ATOMIC_WORKFLOWS_JOURNAL` or `ATOMIC_WORKFLOW_JOURNAL_PATH` |
+| `ATOMIC_STORAGE` | `ATOMIC_STORAGE` |
+| `sessions.storage` setting | `workflows.journal` setting |
+| Shared `storage` setting | Shared `storage` setting |
+| Default SQLite file | Default SQLite file |
+
+How the options combine with the path overrides:
+
+- The session flags are more specific than `--storage`. With `atomic --session-dir ./sessions --storage '{...}'`, sessions use `./sessions` and workflow runs use the `--storage` selection.
+- A path variable overrides `ATOMIC_STORAGE` for its domain. For example, `ATOMIC_WORKFLOW_JOURNAL_PATH` moves only the workflow runs.
+- `ATOMIC_SESSIONS_STORAGE` with a non-empty `ATOMIC_CODING_AGENT_SESSION_DIR`, or `ATOMIC_WORKFLOWS_JOURNAL` with a non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, is a conflict. Startup fails with `StorageConfigError` whose `source` is `"env"`, whose `field` names both variables, and whose `reason` is `"conflicting-overrides"`. Unset one of them.
+- `--storage` or `--storage-file` with a non-empty `ATOMIC_CODING_AGENT_SESSION_DIR` or `ATOMIC_WORKFLOW_JOURNAL_PATH` is also a conflict, with `source` `"cli"`, because the flag would otherwise silently override the variable. Unset the variable, or for sessions pass a session flag such as `--session-dir`, which takes precedence over both.
+
+Relative `path`, `dir`, and `secrets.file` values resolve against Atomic home, normally `~/.atomic`, and relative adapter module specifiers resolve from the agent directory, exactly as in settings and regardless of the working directory. A relative `--storage-file` path resolves against the working directory. Empty variables are ignored. `ATOMIC_CODING_AGENT_SESSION_DIR` and `ATOMIC_WORKFLOW_JOURNAL_PATH` keep their existing behavior.
+
+At startup, before any session starts and in every mode including RPC, the CLI validates `--storage` or `--storage-file` and every set `ATOMIC_STORAGE`, `ATOMIC_SESSIONS_STORAGE`, and `ATOMIC_WORKFLOWS_JOURNAL`, even one that a flag or another variable outranks. `createAgentSession()` validates the same set variables before it creates a session, even when the host supplies `sessionManager` or `sessionStore`. Invalid JSON, a selection that does not match the settings schema, or an unreadable `--storage-file` raises `StorageConfigError` with `source` `"env"` or `"cli"`, a `field` naming the variable or flag, and a `reason` such as `"invalid-json"`, `"invalid-selection"`, or `"unreadable-file"`. A missing `{ "env": ... }` secret reports `"secret-env-missing"` against the selection's variable or flag when the store opens. Atomic never falls back to settings or another store. Errors name the variable or flag, never the selection text or a resolved secret.
+
+These options come from the process that starts Atomic, so they are not subject to [project trust](/security) the way project settings are. An adapter module runs code with Atomic's privileges: select only modules you trust. Pass credentials through `secrets` rather than `options`. Command-line arguments can be visible to other local users, so prefer `--storage-file` or an environment variable when the selection itself is sensitive.
+
 ## Sharing storage across hosts
 
 By default, sessions and workflow runs live in a local file that serves one machine. To share them across machines, for example several service replicas or a CI fleet, select the same remote SQLite-compatible database on every host through an [adapter](#selecting-an-adapter), such as the libSQL/Turso wrapper above. Give each project or tenant its own `prefix`. Do not put the local SQLite file on a network filesystem; use a database driver instead.
@@ -329,7 +378,9 @@ With a shared journal:
 - Lease expiry uses the database clock, so clock differences between hosts do not affect ownership.
 - A displaced executor cannot save new checkpoints; its writes fail with `StaleLeaseError`.
 
-The database stores sessions and workflow checkpoints only. To resume a run on another host, that host also needs the same workflow definition and the run's original working directory, including any worktrees and artifacts the run uses. Effects that were not checkpointed may run again after a takeover, so make external effects idempotent. Every checkpoint commits before it is reported, so a remote database adds network latency to each durable `ctx.*` step. Backends may also enforce payload limits that raise `StoragePayloadTooLargeError`.
+Selecting the same top-level `storage` on every host, in global settings or with `--storage`, `--storage-file`, or `ATOMIC_STORAGE`, also lets Intercom sessions on different hosts message each other; `sessions.storage` and `workflows.journal` alone do not. Brokers route through the database, so Intercom message bodies are stored there until shortly after they are delivered. See [Running Intercom across machines](/intercom/operations#running-intercom-across-machines).
+
+The database stores sessions, workflow checkpoints, and, when Intercom brokers share it, Intercom messages and session routing state. To resume a run on another host, that host also needs the same workflow definition and the run's original working directory, including any worktrees and artifacts the run uses. Effects that were not checkpointed may run again after a takeover, so make external effects idempotent. Every checkpoint commits before it is reported, so a remote database adds network latency to each durable `ctx.*` step. Backends may also enforce payload limits that raise `StoragePayloadTooLargeError`.
 
 Scale by running more workflows, not by splitting one: a single run and a single session each have one writer. The built-in journal uses SQLite SQL, so `openDatabase` adapters need a SQLite-compatible driver. For another kind of database, implement `openRunJournal` and `openSessionStore` and validate them with the conformance suites below.
 

package/docs/subagents.md

@@ -100,9 +100,11 @@ In a parallel run, `intercom.ask`, `contact_supervisor({ reason: "need_decision"
 
 To update a working child, use ordinary Intercom `send` or `ask` with its exact connected name or full session ID from `intercom list`. An admitted child registers with Intercom when its session starts, so it is listed and reachable while it works even if it never calls Intercom itself. Foreground and background children treat it as a priority interrupt: the child's current model call or cancellable tool is cancelled and the message is handled next in the same child execution, without relaunching its task or repeating the original prompt. Tools that ignore cancellation finish first, and completed side effects are kept. Multiple updates stay in arrival order. A reply to an incoming ask uses ordinary `intercom.reply`; this does not change the single-child parent-targeted handoff described below.
 
-Targeted `kill` stops only the selected child and cannot be resumed. Explicit batch cancellation and session/workflow-stage lifetime closure still stop the intended owned children, including pending reply waits. A late or duplicate reply cannot revive a terminal child. Ordinary Intercom group restrictions and the authorized cross-group `contact_supervisor` route are unchanged.
+[Run control](#run-control) (`pause`, `quit`) stops only the selected child, and it stays resumable. Explicit batch cancellation and workflow-stage closure stop the intended owned children for good, including pending reply waits. Closing or switching away from a session also stops its children, but they stay resumable, as described next. A late or duplicate reply cannot revive a terminal child. Ordinary Intercom group restrictions and the authorized cross-group `contact_supervisor` route are unchanged.
 
-Completed, failed, interrupted, and cancelled noninteractive children cannot answer new Intercom asks, even when their retained registration still says `idle`. Such asks fail immediately with an explicit terminal-child error; an admitted ask also fails if its child terminates before replying. Launch a fresh child with the required context for follow-up work. This does not restrict live interactive idle sessions or workflow-stage post-mortem conversations, and does not change `send` delivery semantics.
+If Atomic exits or crashes while background subagents are still running, they come back when you reopen the session, or continue the workflow whose stage launched them: each unfinished child is relaunched from its own saved session with a continuation prompt. The same applies when you switch away from the session with `/new`, `/resume` to another session, or `/fork`: its running children stay resumable and are restored when you reopen it. A restored child first receives the steering and follow-up messages it had queued and not read, once, in order. A restored child keeps its Intercom name and group and gets a fresh supervisor authorization, so you can keep messaging it. It continues on its own model and thinking level, not on ones you switched to since, and runs on the agent definition it was launched with, even when a project agent of the same name would now shadow it, and a child launched with `context: "fork"` keeps its Intercom bridge instructions under `intercomBridge.mode: "fork-only"`. Messages sent to it by any session in its group wait for it, from the moment the reopened session starts, or, for a workflow stage's subagent, from the moment the run becomes addressable, until it has been restored; see [Intercom operations](/intercom/operations#connection-states-and-recovery). Only children that were still running are relaunched automatically; a child that finished, was paused or quit, or was cancelled for good stays as it was, and you can continue a resumable one with `resume`. Only the session that launched a child restores it: a fork of that session (`/fork`, `atomic --fork`) copies the child's record but never relaunches or reports it. If a child cannot be restored, for example because its session file or agent definition is gone, the agent gets a notice that it is gone. That notice is given once: the child is then recorded as gone in the session, so later restarts neither retry the restoration nor repeat the notice.
+
+Completed, failed, interrupted, and cancelled noninteractive children cannot answer new Intercom asks, even when their retained registration still says `idle`. Such asks fail immediately with an explicit terminal-child error; an admitted ask also fails if its child terminates before replying. For follow-up work, [resume](#run-control) a resumable child or launch a fresh child with the required context. This does not restrict live interactive idle sessions or workflow-stage post-mortem conversations, and does not change `send` delivery semantics.
 
 ### Peer coordination
 
@@ -114,7 +116,7 @@ Peers do not coordinate spontaneously. When related work runs in parallel, name
 
 A claimed parent-targeted blocking request ends a single child and returns its question, attachments, agent identity, and `[TASK_CONTEXT]` through the parent's `subagent` call. Start a fresh child with the answer and handoff. In parallel runs and collected sibling launches, the requesting child instead stays alive and continues its ongoing execution after receiving the supervisor's reply.
 
-The handoff explicitly tells the parent to start a fresh child with a normal launch such as `subagent({ agent: "worker", task: "[TASK_CONTEXT] ... Continue with this supervisor answer: ..." })`. The new child receives a new run identity. Completed, interrupted, and parent-question children are terminal for continuation; a prior run ID cannot revive one.
+The handoff explicitly tells the parent to start a fresh child with a normal launch such as `subagent({ agent: "worker", task: "[TASK_CONTEXT] ... Continue with this supervisor answer: ..." })`. The new child receives a new run identity.
 
 ## Foreground supervisor coordination
 
@@ -190,22 +192,60 @@ Tool examples:
 subagent({ agent: "codebase-analyzer", task: "Trace the auth flow with file references.", wait: { kind: "foreground", budgetMs: 30000 } })
 ```
 
-Use `subagent({ action: "kill", id: "<task-or-run-id>" })` to terminally stop a live child. Killed children cannot be resumed; launch a fresh child with an explicit context handoff for follow-up work. The former `interrupt` action is no longer accepted. Replace subagent calls using `action: "interrupt"` with `action: "kill"`. Workflow controls use `pause`; host cancellation APIs are unchanged.
+Use [run control](#run-control) to stop, hold, or continue a child.
 
 Cancelling the parent turn stops a running foreground child. This is terminal cancellation, not completion or a retryable failure. Atomic returns labelled partial findings from the run's modified `progress.md`, the last assistant text, or a cancellation notice with available artifact paths. Parallel siblings do not each receive duplicate copies of shared progress.
 
-Use the returned task or run ID for status and kill. Neither action revives completed work. Expand status cards to see every child, full paths, task, parent, and any recorded termination cause; status inspection does not start work.
+Use the returned task or run ID for status and run control. Expand status cards to see every child, full paths, task, parent, and any recorded termination cause; status inspection does not start work.
 
-When a workflow stage closes, it cancels its remaining children and suppresses their late findings. Already-submitted Intercom sends are not retracted, so a transport acknowledgement is not proof that a finding appeared in parent chat. Deliberate post-mortem stage chat remains separate.
+When a workflow stage closes for good (the stage finished, or its run ended or was cancelled), it cancels its remaining children and suppresses their late findings. Every subagent it launched then becomes terminal, whether it was running, paused, quit, completed, or failed: `resume` on one returns an error that says why. Already-submitted Intercom sends are not retracted, so a transport acknowledgement is not proof that a finding appeared in parent chat. Deliberate post-mortem stage chat remains separate.
 
 Live progress and completed results show each step's resolved model ID and effective reasoning level, including after a model fallback; parallel steps keep their metadata separate. Fast inference is part of the model ID, so an agent pinned to a fast variant renders it directly — `codebase-analyzer (openai-codex/gpt-5.6-sol-fast · thinking medium)` — with no separate `fast` badge. Select fast inference in an agent definition's `model` and fallback model fields, for example `openai-codex/gpt-5.6-sol-fast:medium`; normal and fast IDs stay distinct fallback candidates and distinct records. See [Providers](/providers#fast-models) for which providers publish fast variants and what each one sends upstream.
 
 Owner-task rows, status cards, foreground result receipts, and background completion cards retain these settings too. Background launch receipts include the concrete model and known, capability-clamped reasoning level selected at admission, including inherited defaults, without waiting for child session startup. A launch receipt remains a snapshot; inspect `/tasks` for later session resolution or fallback changes. Settings that are not yet resolved remain unavailable rather than being guessed from the parent's display. Completion metadata is persisted with the notification so it remains visible when replaying chat history.
 
+### Run control
+
+The `subagent` tool has the same run-control actions as the workflow tool: `pause`, `resume`, and `quit`. `id` accepts the child id (`<runId>:<index>`), its task id, its Intercom name, or the run id of a run that launched one child.
+
+```ts
+subagent({ action: "pause", id: "<child-id>" })   // stop now; queued messages wait for resume
+subagent({ action: "pause", all: true })          // every running child this session launched
+subagent({ action: "quit", id: "<child-id>" })    // graceful stop; stays resumable
+subagent({ action: "quit", all: true })           // also covers already-paused children
+subagent({ action: "resume", id: "<child-id>", message: "Focus on the failing test first." })
+```
+
+- **`pause`** stops the child's current turn and holds its queued steering and follow-ups in place; `resume` delivers them once, in order, before its own `message`. Intercom messages sent to a paused child wait until you resume it, as long as the same Atomic process keeps running.
+- **`quit`** stops the child gracefully, including a child that is already paused, by you or with its workflow stage. A quit child stays resumable while the session or workflow stage that launched it can still resume it; once that workflow stage closes for good, the child becomes terminal like every other child of the stage.
+- A parallel child still waiting for a free slot behind its concurrency limit can be paused or quit too, by id or with `all: true`. It then does not start when a slot frees; `resume` starts it on its original task, with `message`, if given, added after the task. This also works after Atomic restarts: the child starts as a new launch under the same child id, Intercom name, and group, with its original agent, task, working directory or worktree, model, thinking level, and skills. A child that inherited your model and thinking level keeps the ones you had when you launched it, even if you have switched since; if that model is no longer available, resume reports the child as gone instead of starting it on your current model. A child launched with `context: "fork"` starts on the copy of your conversation it was launched with; if that copy no longer exists, resume reports the child as gone instead of starting it without your conversation. A child that was still waiting for a slot when Atomic exited starts the same way when its session reopens.
+- A resumed child of a parallel run, queued or not, waits for a free slot under that run's concurrency limit, as its original launch did. A paused or quit child holds no slot.
+- **`resume`** continues the child from its own saved session, under the same child id, Intercom name, and group, with fresh supervisor authorization. For a paused, quit, or interrupted child, `message` is delivered once as its next prompt, and after replying the child continues where it left off. For a completed or failed child, `message` is one fresh prompt in the same session, with nothing queued after it. Without `message`, the child is asked to continue where it left off, or to stop if its task is finished; this works for completed and failed children too. `all: true` is not accepted for `resume`.
+
+Paused, quit, interrupted, completed, and failed children are resumable, including a paused child that you later quit. So are children whose session you closed or switched away from, whether Atomic exited or crashed, or you used `/new`, `/resume` to another session, or `/fork`; they are restored when that session reopens. Subagents of a workflow stage that was paused or quit, including by Atomic exiting or a session switch, stay resumable too: the stage agent can continue them with `resume`, and resuming the run after Atomic restarts restores them with the stage. These children are terminal, and `resume` returns an error that says why:
+
+- **Killed**: cancelled for good by an owner or batch cancellation. This includes stopping the subagent from `/tasks` and the removed `kill` action.
+- **Stage ended**: the workflow stage that launched it finished, or its run ended or was cancelled. This covers every subagent of that stage, including ones you paused or quit, and also a run killed while it waited, after a restart, for `/workflow resume`. The error reads `<agent> (<child-id>, <intercom-name>) is terminal and cannot be resumed: its workflow stage ended (the stage finished, or its run ended or was cancelled). Launch a fresh subagent if its work is still needed.`
+- **Gone**: it could not be restored after a restart.
+
+Resume also refuses a child that is still running (pause or quit it first) and an id this session did not launch. A resume that fails, for example because the child's agent is no longer defined, keeps its `worktree: true` worktree with its changes and branch.
+
+An SDK session without a task host runs its subagents directly and records them in its session the same way, so `pause`, `resume` (with or without `message`, queued messages included) and `quit` work there by id and with `all: true`, also after the session is reopened. A child resumed there runs in the background, and its result arrives as a completion notice. Closing the session stops such a child; reopening the session relaunches it automatically, and the messages it had queued and not read are delivered once, in order. For a terminal child, launch a fresh child with an explicit context handoff.
+
+The `kill` action was removed, and `interrupt` before it. Calls with either are rejected with an error that names `quit` as the replacement. For `kill` it reads:
+
+```text
+The subagent action "kill" was removed. Use { action: "quit", id } to stop a child gracefully; it stays resumable with { action: "resume", id, message? }.
+```
+
+Each background subagent launch card shows the child's latest state, including after you reopen the session with `/resume` or `atomic --session <id>`, and when you view a workflow stage's transcript: **Running in background**, **Paused (resumable)**, **Quit (resumable)**, **Interrupted (resumable)**, **Paused with its workflow stage (resumable)**, **Completed**, **Failed**, **Terminal · killed**, **Terminal · gone after a restart**, or **Terminal · its workflow stage ended**. A resumed child continues in its original launch card, marked **· resumed**, and the `resume` call's own card says the child continues in its original launch card. Expand a launch card to see the end of the child's saved transcript. Earlier `pause`, `resume`, and `quit` calls show their results, and rejected calls show their error.
+
 ## Task inspection
 
 Hosts with an owner task store expose `/tasks` and `/tasks <id>` for background agents and shells, including their retained terminal results. Foreground-only work is excluded. Enter opens detail; arrows select an explicit action. Cancel asks for confirmation of the selected task. Terminal tasks retain transcript inspection but omit foreground, cancellation, and stdin actions. Escape returns from detail or stdin before returning to the composer.
 
+Cancelling a subagent from `/tasks` stops it for good: its row shows **Killed (non-resumable)** and `resume` refuses it. To stop a child and keep it resumable, use `subagent({ action: "quit", id })` or `pause` instead.
+
 `/tasks` appears in slash-command autocomplete. The inspector groups agents and shells with counts, status symbols, and a highlighted selection. Task descriptions lead; the selected row shows secondary activity and tool counts. The header and footer remain visible in ordinary terminal sizes, with a compact fallback for short terminals.
 
 The list opens as a compact inline widget, like the `/workflow connect` picker. Detail, transcript, input, and stop-confirmation pages are fullscreen; returning to the list preserves selection. Every agent row includes its resolved model and reasoning level when available, including completed background tasks.
@@ -241,7 +281,7 @@ For adversarial review or research, prefer fresh context so the specialist inspe
 
 For parallel implementation work, `worktree: true` can give each child an isolated git worktree so concurrent edits do not clobber each other.
 
-Observation yields do not release these worktrees. Cancelling a queued child before it starts, or closing the session or workflow-stage owner, still allows the batch's worktrees and branches to be removed after the remaining executions finish. Live children's changes stay in place until then; Atomic captures worktree diffs before cleanup.
+Observation yields do not release these worktrees. The batch's worktrees and branches are removed once every child that uses them has finished; Atomic first saves each worktree's changes as a patch under the run's `worktree-diffs/<run id>` artifact directory. When a child is paused or quit, or stays resumable because you closed or switched away from its session or its workflow stage paused, its worktree is kept only if it has uncommitted or untracked changes or commits that are not in the run's base; a clean worktree is removed with the others. Resuming the child continues in its kept worktree, or recreates a removed one from the run's base with its saved patch applied, so a resumed completed child starts with its earlier changes. A resumed child keeps its worktree until it finishes again, and then saves a new patch (`task-<n>-<agent>.<execution>.patch`) rather than overwriting the earlier one. Cancelling a child for good, including a queued one, or its workflow stage closing for good, lets its worktree be removed. If you never resume a stopped child that has unsaved changes, its worktree stays on disk under `.atomic/worktrees/`.
 
 Fresh children inherit the invoking session's SDK configuration, resource-discovery inputs, model/auth runtime and host callbacks. Child tool selections can narrow the parent's permissions but cannot restore disabled packages or excluded tools. Intercom has no mandatory bypass; a child without access receives no supervisor grant. Model fallback keeps the same inherited restrictions. See [SDK child configuration](/sdk#workflow-and-subagent-children).
 
@@ -275,7 +315,7 @@ Use `group` on a call or task to select the child's [Intercom](/intercom) group.
 
 Pending Intercom asks belong to the addressed session. A workflow child cannot inspect or answer its parent stage's pending asks, and sibling children keep separate pending lists.
 
-Detached children remain owned by the workflow stage that launched them. When that stage completes, Atomic cancels every still-running owned child (single or parallel) with the existing parent-cancellation outcome (`status: "interrupted"`, `cause: "abort"`) and suppresses late findings and completion notifications instead of routing them to the parent/main chat. A detached child that finishes while its stage is still live notifies normally, and completing one stage does not affect children owned by other stages or sessions.
+Detached children remain owned by the workflow stage that launched them. When that stage completes, Atomic cancels every still-running owned child (single or parallel) with the existing parent-cancellation outcome (`status: "interrupted"`, `cause: "abort"`) and suppresses late findings and completion notifications instead of routing them to the parent/main chat. These children are terminal; `resume` refuses them with an error that says their workflow stage ended. When the stage completes, or its run ends or is cancelled, every other subagent it launched becomes terminal too, whether it was paused, quit, completed, or failed. A detached child that finishes while its stage is still live notifies normally, and completing one stage does not affect children owned by other stages or sessions.
 
 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.
 
@@ -289,7 +329,7 @@ subagent({ agent: "worker", task: "Implement the approved fix.", progress: true
 
 ## Delegation and child boundaries
 
-Delegation is exactly one level deep and cannot be configured. Children complete their assigned tasks directly; they cannot launch or kill other children. Children can still run background shells. Those shells appear in the parent's `/tasks`: the main chat's, or the current workflow stage's. See [Shells started by subagents](/background-tasks#shells-started-by-subagents). They may inspect definitions and status with `list`, `get`, and `status`; management-restricted children also cannot `create`, `update`, or `delete` definitions.
+Delegation is exactly one level deep and cannot be configured. Children complete their assigned tasks directly; they cannot launch other children or `pause`, `resume`, or `quit` them. Children can still run background shells. Those shells appear in the parent's `/tasks`: the main chat's, or the current workflow stage's. See [Shells started by subagents](/background-tasks#shells-started-by-subagents). They may inspect definitions and status with `list`, `get`, `status`, and `wait`; management-restricted children also cannot `create`, `update`, or `delete` definitions.
 
 Child prompts omit parent orchestration artifacts and prior subagent control traffic. Tool availability does not grant delegation authority. The parent remains responsible for orchestration.
 

package/docs/usage.md

@@ -46,7 +46,7 @@ While the agent works, `∀` pulses beside a working message. Retry, fallback, c
 
 See [Keybindings](/keybindings) for all shortcuts and customization.
 
-On native Windows, `!` and `!!` execute PowerShell (preferring `pwsh.exe`, then `powershell.exe` on `PATH`). Linux, macOS, and WSL use Bash. Extension-provided execution operations still take precedence. `shellCommandPrefix` is still prepended, so use syntax matching the selected shell; `shellPath` configures Bash, not Windows interactive PowerShell. Escape or Ctrl+C cancels a running command. `!!` output remains excluded from model context.
+On native Windows, `!` and `!!` execute PowerShell (preferring PowerShell 7 `pwsh.exe`, then Windows PowerShell `powershell.exe`; see [Windows](/windows) for the locations checked). Linux, macOS, and WSL use Bash. Extension-provided execution operations still take precedence. `shellCommandPrefix` is still prepended, so use syntax matching the selected shell; `shellPath` configures Bash, not Windows interactive PowerShell. Escape or Ctrl+C cancels a running command. `!!` output remains excluded from model context.
 
 On Windows, ALT+Z lends the terminal to an interactive PowerShell subshell. Type `exit` to return to the same Atomic session; owned background tasks keep running. CTRL+Z remains editor undo. On POSIX systems, CTRL+Z suspends Atomic and `fg` resumes it.
 

package/docs/windows.md

@@ -37,10 +37,20 @@ Package-manager installation remains available but requires Node.js; see the [Qu
 Atomic uses a Bash shell for the `bash` tool. For that tool, Atomic checks these locations in order:
 
 1. Custom path from `~/.atomic/agent/settings.json` (legacy `~/.pi/agent/settings.json` also supported)
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+2. Git Bash at `%ProgramFiles%\Git\bin\bash.exe`
+3. Git Bash at `%ProgramFiles(x86)%\Git\bin\bash.exe`
+4. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
 
-For the Bash tool, [Git for Windows](https://git-scm.com/download/win) is sufficient. Native Windows `!`/`!!` shortcuts instead use PowerShell, preferring `pwsh.exe` and falling back to `powershell.exe` on `PATH`. They do not use `shellPath`; any `shellCommandPrefix` must use PowerShell syntax. WSL remains Bash-based.
+Windows Store app aliases, such as those in `%LOCALAPPDATA%\Microsoft\WindowsApps`, are accepted wherever Atomic looks for a shell. When Atomic uses the legacy WSL `bash.exe` launcher from `%SystemRoot%\System32`, it sends commands over stdin to avoid command-line quoting problems.
+
+For the Bash tool, [Git for Windows](https://git-scm.com/download/win) is sufficient. Native Windows `!`/`!!` shortcuts instead use PowerShell. They do not use `shellPath`; any `shellCommandPrefix` must use PowerShell syntax. WSL remains Bash-based.
+
+PowerShell discovery checks these locations in order:
+
+1. `pwsh.exe` on `PATH`
+2. `%ProgramFiles%\PowerShell\7\pwsh.exe`
+3. `powershell.exe` on `PATH`
+4. `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`
 
 ## Custom Shell Path
 
@@ -70,7 +80,7 @@ If Atomic cannot safely self-update the current installation, it exits with a cl
 
 ### PowerShell tool
 
-On native Windows, Atomic registers the `powershell` tool by default when PowerShell 7 (`pwsh.exe`) or Windows PowerShell (`powershell.exe`) is on `PATH`. If neither executable is available, the tool is omitted so the agent is not offered a command that cannot run. Add `powershell` to `defaultTools` to enable it explicitly when you want it active alongside a narrower built-in selection. The `bash` tool continues to use Bash; `!`/`!!` use PowerShell. Both `ATOMIC_*` and legacy `PI_*` session variables are available.
+On native Windows, Atomic registers the `powershell` tool by default when PowerShell 7 (`pwsh.exe`) or Windows PowerShell (`powershell.exe`) is found in one of the PowerShell discovery locations above. If neither executable is available, the tool is omitted so the agent is not offered a command that cannot run. Add `powershell` to `defaultTools` to enable it explicitly when you want it active alongside a narrower built-in selection. The `bash` tool continues to use Bash; `!`/`!!` use PowerShell. Both `ATOMIC_*` and legacy `PI_*` session variables are available.
 
 PowerShell calls are rendered in the transcript with a `PS>` prompt so they are never mistaken for Bash, and truncated PowerShell output is spilled to its own `atomic-powershell-*` temp file rather than the Bash one.
 

package/docs/workflows/api-reference.md

@@ -1427,7 +1427,7 @@ interface RunJournal {
 
 Custom journals need only the async contract; no synchronous journal methods are required. Use `registerRunJournalConformance(runner, name, open, observeRead)` to check a fresh journal per case. Supply a read observer that reports actual page sizes and entries loaded or copied, with `restore()` and `reset()` methods, so the suite can verify lazy reads without consuming the whole history.
 
-Precedence is `RunOpts.journal` (`createAgentSession({ journal })` for a session's `workflow` tool), non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, `workflows.journal`, shared top-level `storage`, then the default `~/.atomic/workflows/journal.sqlite`. Nearer settings selections replace whole objects, never merge options or secrets. Relative settings paths resolve against Atomic home. Invalid selected values raise `StorageConfigError`; storage failures reject the call without selecting memory. Keep the same journal and working directory when resuming stored runs.
+Precedence is `RunOpts.journal` (`createAgentSession({ journal })` for a session's `workflow` tool), `--storage` or `--storage-file`, `ATOMIC_WORKFLOWS_JOURNAL` or non-empty `ATOMIC_WORKFLOW_JOURNAL_PATH`, `ATOMIC_STORAGE`, `workflows.journal`, shared top-level `storage`, then the default `~/.atomic/workflows/journal.sqlite`. Nearer settings selections replace whole objects, never merge options or secrets. Relative settings paths resolve against Atomic home. Invalid selected values raise `StorageConfigError`; storage failures reject the call without selecting memory. Keep the same journal and working directory when resuming stored runs.
 
 ```ts
 import { run } from "@bastani/atomic/workflows";

package/docs/workflows/authoring.md

@@ -529,7 +529,7 @@ Prerequisites and setup, each as one bounded attempt:
 
 - `node` (preferred) or `bun` on the host. If neither is present, install one in a bounded attempt (Node via [fnm](https://github.com/Schniz/fnm) with `fnm install --lts` or the host's package manager, Bun via `curl -fsSL https://bun.sh/install | bash`) and report what the installer did; if the install is refused or fails, report that as the limitation rather than retrying.
 - The `cua-driver` executable (`cua-driver --version`), installed with upstream's one-line installer if missing, followed by `cua-driver telemetry disable` once.
-- The SDK installed at the exact driver version into a scratch directory outside the user's repository, for example `npm install @trycua/cua-driver@0.34.0 --prefix ~/.cache/atomic-cua`. The package ships per-platform native optional dependencies. Daemon-backed clients verify contract, tool-schema, capability, and protocol versions before each action and refuse on mismatch, so the pin must match `cua-driver --version`.
+- The SDK installed at the exact driver version into a scratch directory outside the user's repository, for example `npm install @trycua/cua-driver@0.36.0 --prefix ~/.cache/atomic-cua`. The package ships per-platform native optional dependencies. Daemon-backed clients verify contract, tool-schema, capability, and protocol versions before each action and refuse on mismatch, so the pin must match `cua-driver --version`.
 
 The executable installer does not install an agent skill. Atomic bundles the skill, so skip upstream's optional `cua-driver skills install`, `cua-driver skills update`, and `clawhub install @cua/driver` steps; leave existing user-level skills alone.