@bastani/atomic 0.9.41-alpha.3 → 0.9.42-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 ## [Unreleased]
 
+## [0.9.42-alpha.1] - 2026-10-23
+
+Sessions, workflow runs, and Intercom can now share one libSQL / Turso database across machines, and provider rate limits are respected across every request in a process.
+
+- **Shared storage across machines:** install `@bastani/atomic-storage-libsql`, join a machine with `atomic storage join <url> --token-file <path>`, and check the result with `atomic storage status`. Atomic packages can ship storage adapters, and `createSqliteDatabase()` handles the facade rules when you write your own ([#3856](https://github.com/bastani-inc/atomic/issues/3856), [#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- **Intercom you can inspect and restart:** `atomic intercom status` and `atomic intercom restart` show and refresh the broker's storage selection and multi-node routing, and a broker that stops answering is replaced after about a minute instead of hanging every session ([#3857](https://github.com/bastani-inc/atomic/issues/3857), [#3862](https://github.com/bastani-inc/atomic/issues/3862))
+- **Rate limits handled across requests:** `configureProviderRequestBudget()` sets process-wide request budgets, 429 cooldowns are shared between model requests, and workflow model chains wait for the earliest eligible account instead of exhausting it ([#3864](https://github.com/bastani-inc/atomic/issues/3864))
+- **Admission limits and local workflow pools:** SDK hosts can share session and command limits with `resourceAdmission`, and workflows can run child subtrees in local worker processes ([#3869](https://github.com/bastani-inc/atomic/issues/3869))
+- **More responsive sessions and workflows:** Ctrl+C and queue clearing act without waiting for a busy engine, workflow stages reload resources four at a time, and standalone `run()` gives stages Intercom without an interactive host ([#3861](https://github.com/bastani-inc/atomic/issues/3861), [#3863](https://github.com/bastani-inc/atomic/issues/3863), [#3865](https://github.com/bastani-inc/atomic/issues/3865))
+- **Login, export, and search fixes:** device-code `/login` waits for Enter before opening the browser, HTML exports show billed costs and the session's own system prompt, and `/resume` search ranks name matches first ([pi #9282](https://github.com/earendil-works/pi/issues/9282), [pi #9980](https://github.com/earendil-works/pi/issues/9980), [pi #11261](https://github.com/earendil-works/pi/issues/11261), [pi #11220](https://github.com/earendil-works/pi/issues/11220))
+
+### Added
+
+- Markdown transformers registered with `pi.registerMarkdownTransformer()` now receive `messageId` and `timestamp` in their context when a message is rendered from the saved session, so an extension can tie its output to a session entry. Both are `undefined` for live messages. See [registerMarkdownTransformer](docs/extensions/api-reference.md#pi-registermarkdowntransformer-transformer)
+- Added `configureProviderRequestBudget(provider, { maxRequests, intervalMs })` for process-wide rolling request budgets shared across SDK model runtimes. Model requests also share provider cooldowns after 429 responses. Separate configured provider IDs remain independent ([#3864](https://github.com/bastani-inc/atomic/issues/3864)).
+- Storage adapter modules can import `@bastani/atomic/storage` and `@bastani/atomic` without an installed or linked copy of Atomic. They get the running Atomic's own modules, as extensions do, so Atomic recognizes the storage errors they throw ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- `createSqliteDatabase()` in `@bastani/atomic/storage` turns a SQLite-compatible driver's calls into a `SqliteDatabase` that applies the facade rules for you: call-order queueing, transaction handle lifetime, NUL rejection, integer and blob normalization, and typed errors with credentials redacted. `redactSecrets()` builds the credential redactor. The libSQL/Turso example in [Storage](docs/storage.md#bring-your-own-driver) now uses it and is a complete adapter ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- Atomic packages can provide storage adapters with a `storageAdapters` manifest entry, and `storage.adapter` can name one by package (`<package>` or `<package>/<name>`), so `atomic install npm:<adapter-package>` installs the adapter together with its driver. See [Adapters from Atomic packages](docs/storage.md#adapters-from-atomic-packages) ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- `@bastani/atomic-storage-libsql` is a first-party libSQL / Turso storage adapter package. Install it with `atomic install npm:@bastani/atomic-storage-libsql` and select it with `"storage": { "adapter": "@bastani/atomic-storage-libsql" }` to share sessions, workflow runs, and Intercom routing across machines. See [Turso and libSQL](docs/storage.md#turso-and-libsql) ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- `atomic storage status` shows, for sessions, workflow runs, and Intercom, the selected storage and where the selection comes from (environment variable, project or global settings, or default), the outranked selections, whether the adapter loads, and whether the database answers a `SELECT 1`, without creating anything. It also shows whether the running Intercom broker uses the current selection, its multi-node routing state, and the brokers live in the shared database. `--json` prints the same report. See [Checking the selected storage](docs/storage.md#checking-the-selected-storage) ([#3856](https://github.com/bastani-inc/atomic/issues/3856), [#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- `atomic storage join <url> --token-file <path>` joins this machine to a shared libSQL / Turso database in one step: it checks the token and the connection, stores the trimmed token in the agent directory with mode 600, writes only the global `storage` setting, creates no tables, and lists the environment variables and settings that override the new selection. It refuses a URL that carries the token itself, so a credential never reaches settings or output. When `@bastani/atomic-storage-libsql` is not installed, it prints the install command. See [Joining a machine to a shared database](docs/storage.md#joining-a-machine-to-a-shared-database) ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- `atomic intercom restart` replaces the running Intercom broker so it reads a changed storage selection; connected sessions reconnect to the new broker. `atomic intercom status` shows the broker, whether it uses the current selection, and its multi-node routing state ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- Interactive and print sessions warn at startup when the shared `storage` selection names an adapter that the running Atomic cannot load, naming the adapter and the cause, instead of Intercom multi-node routing staying off silently ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- SDK hosts can share admission limits through `resourceAdmission` and `withResourceAdmission()`. Session and managed-command permits remain held until cleanup, including background commands. Delegated sessions inherit the same service and request immediate admission or rejection rather than waiting on a permit held by their parent. See [Shared resource admission](docs/sdk.md#shared-resource-admission) ([#3869](https://github.com/bastani-inc/atomic/issues/3869)).
+
+### Changed
+
+- The standalone `atomic` binaries are now built with Bun 1.4.4, which includes upstream security fixes in the embedded runtime
+- Device-code `/login` flows (Kimi Code, GitHub Copilot, Meta, and extension providers) no longer open the browser on their own. Press Enter to open the verification URL and copy the code, or log in manually. Providers can turn off either action with `openBrowserOnConfirm: false` or `copyCodeOnConfirm: false`. See [Provider OAuth](docs/custom-provider/oauth.md#oauth-support) ([pi #9282](https://github.com/earendil-works/pi/issues/9282))
+- A `{ "file": ... }` storage secret now drops one trailing line ending (`\n` or `\r\n`), so a token saved with `turso db tokens create <db> > token` works without trimming it first. Other whitespace is still kept ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+
+### Fixed
+
+- HTML session exports now show the recorded total cost of each response, such as OpenRouter's billed cost, instead of the sum of its catalog-estimated components. Sessions recorded before totals were stored still use the component sum ([pi #9980](https://github.com/earendil-works/pi/issues/9980))
+- On macOS, cancelling a running bash command no longer lets the next command in a `a; b` sequence start while the shell is being killed: the process group is stopped before it is killed ([pi #11252](https://github.com/earendil-works/pi/issues/11252))
+- HTML session exports, including `atomic --export`, now show the system prompt and available tools from the session's first system message, and later system messages as named prompt-section and tool updates. Sessions without system entries still show the prompt and tools from the agent state ([pi #11261](https://github.com/earendil-works/pi/issues/11261))
+- HTML session exports of very long sessions no longer fail to render the session tree with a call-stack overflow ([pi #11225](https://github.com/earendil-works/pi/issues/11225))
+- `pi.exec()` now reports why a command could not be started (for example `ENOENT` for a missing executable) in `stderr` instead of returning an empty `stderr` with exit code 1 ([pi #11085](https://github.com/earendil-works/pi/issues/11085))
+- `/resume` search matches the session name, summary, id, messages and working directory separately. A name match ranks first, then text found in the id, summary, messages or directory, then characters scattered through the name, summary or directory. Matches deep in a long transcript are no longer ranked last, and scattered characters in session ids or message text no longer produce noise matches ([pi #11220](https://github.com/earendil-works/pi/issues/11220))
+- Updated the bundled `ip-address` dependency to 10.7.4, which fixes a quadratic-time zone-identifier match in IPv6 address parsing that a single long string could use to stall the process ([GHSA-rxp7-6hxx-x8q5](https://github.com/advisories/GHSA-rxp7-6hxx-x8q5))
+- Provider request-budget waits no longer consume OpenAI, Anthropic, Mistral, or explicit Codex SSE HTTP timeouts, and successive Anthropic federation-authenticated requests keep reusing their cached token. Cancelling a queued model request reports an aborted result without dispatching it ([#3864](https://github.com/bastani-inc/atomic/issues/3864)).
+- Cancelling or clearing queued messages no longer waits for a busy interactive engine to finish draining its output before acting. Cancelled prompts and shell commands waiting to start do not run later when output resumes. If queue clearing or cancellation of chat, shell commands, compaction, or retries stalls or fails, Ctrl+C can still replace the engine even while it continues sending heartbeats, including controls sent while a replacement initializes; an earlier failed queue pause no longer prevents an abort from being sent ([#3865](https://github.com/bastani-inc/atomic/issues/3865))
+- The standalone binary's Intercom broker now runs multi-node routing with a shared `storage` selection and loads storage adapters, as the npm installation does ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- `atomic storage join` keeps previous credentials intact when saving settings fails, rejects relative `file:` URLs that would select different databases from different directories, and rejects credentials embedded in `file:` URLs before printing or saving them. New joins use separate private token files, preserving existing sessions' credentials. A successful join no longer reports failure when malformed project settings prevent the final override report: it warns that storage was saved and asks you to fix the settings before running status ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- `atomic storage status` reports settings load failures, opens local SQLite files (including adapter `file:` URLs) read-only without creating missing databases or changing journal mode, and bounds connection cleanup even when a query stalls ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- `createSqliteDatabase()` preserves callback and rollback failures when transaction cleanup also fails ([#3856](https://github.com/bastani-inc/atomic/issues/3856))
+- Package-name storage adapters now honor packages listed in legacy global settings, while explicit agent directories remain isolated ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- On macOS, pausing a managed command no longer causes it to be reported as completed and terminated ([#3869](https://github.com/bastani-inc/atomic/issues/3869)).
+
+## [0.9.41] - 2026-10-22
+
+Workflows stay contained when they fail, classifiers read images, and usage totals say where their cost came from.
+
+- **Workflow failures stay inside their run:** an unhandled `ctx` rejection, a stray `ctx.exit()`, or a branch that outlives a kill or quit now fails or ends only its own run instead of the whole Atomic process ([#3846](https://github.com/bastani-inc/atomic/issues/3846), [#3849](https://github.com/bastani-inc/atomic/pull/3849))
+- **Image input for more classifiers:** `models.classify()` accepts `images` for Jev and Clef on Cloudflare Workers AI and OpenRouter, with corrected Workers AI pricing ([#3847](https://github.com/bastani-inc/atomic/pull/3847))
+- **Provider-billed cost flag:** `usage.cost.totalFromProvider` tells you whether a usage total is the provider's billed cost or a catalog estimate ([#3852](https://github.com/bastani-inc/atomic/pull/3852))
+- **Steady sessions and installs:** SDK and RPC `steer()`/`followUp()` start a turn on an idle session, extension OAuth providers can report rejected logins, and the installers skip downloading a release that is already installed ([#3801](https://github.com/bastani-inc/atomic/issues/3801), [#3851](https://github.com/bastani-inc/atomic/pull/3851))
+- **Terminal and rendering fixes:** Rex terminal support, terminal modes restored on unexpected exit, Markdown tables after unclosed `$$` blocks, CJK emphasis, and `@` autocomplete with regex characters ([#3847](https://github.com/bastani-inc/atomic/pull/3847))
+
+**Breaking change:** SDK `steer()` and `followUp()` and the RPC `steer` and `follow_up` commands now start a turn when the agent is idle and the session already has messages.
+
+### Breaking Changes
+
+- SDK `steer()` and `followUp()`, and the RPC `steer` and `follow_up` commands, now start a turn when the agent is idle and the session already has messages. On a session with no messages yet, or after a run was aborted, the message still waits for the next prompt. If you queue a message on an idle session that has messages and then call `prompt()` (or send an RPC `prompt`) right away, that prompt now fails with "Agent is already processing" unless you pass `streamingBehavior` (`"steer"` or `"followUp"`) to queue it behind the running turn.
+
+### Added
+
+- Added `usage.cost.totalFromProvider` to usage totals. Summed usage, including nested tool-call and compaction totals, reports `true` only when every part was a provider-reported billed cost; catalog-estimated and legacy sessions without the field report `false`.
+- Codemode `models.classify()` now also accepts `images` for TypeSafe's Jev and Cloudflare's Clef models on `cloudflare-workers-ai` and OpenRouter, next to Jev on `typesafe`, and lists Clef Omni and Jev 1.14 on Workers AI. See [Use classifier models](docs/models.md#use-classifier-models). Provider-level `compat` in `models.json` now also applies to classifier models, with the System One fields `imageInput` and `sendImageOptInHeader` for proxies that serve another service's classifiers. Extension classifier models accept `compat` too. See [Models Configuration](docs/models-configuration.md#typesafe-system-one).
+- Added support for the Rex terminal (`TERM_PROGRAM=rex`): OSC 8 hyperlinks, truecolor, and inline images. Links previously fell back to the `text (url)` format ([#11131](https://github.com/earendil-works/pi/issues/11131), [#11150](https://github.com/earendil-works/pi/pull/11150) by [@petrroll](https://github.com/petrroll), [#11183](https://github.com/earendil-works/pi/pull/11183) by [@nihaals](https://github.com/nihaals))
+- `routeExecutionModel()` accepts an optional `inference` option (exported type `RoutingInferenceBounds`) for callers that must not wait indefinitely on routing inference: `deadline` is an `AbortSignal` whose abort ends routing as a complete inference failure, so the caller can degrade to `AutoRoutingInferenceError.currentModelRoute`, and `limit` runs each routing inference under the caller's concurrency limit. Without it, routing keeps having no built-in deadline.
+- RPC `get_available_models` and `refresh_models` responses now list extension providers that accept an API key in `customAuthProviders`, and report extension providers' environment or configured-key authentication in `providerAuthStatuses`.
+- Extension OAuth providers can throw `OAuthRefreshRejectedError` (exported from `@bastani/atomic`, with `isOAuthRefreshRejectedError`) from `refreshToken` when the provider rejected the stored login. The user then sees the same `run /login <provider>` guidance as for a built-in provider. See [Provider OAuth](docs/custom-provider/oauth.md#rejected-logins).
+- Exported `noOpUIContext`, the default no-op extension UI context, from the SDK entry point ([#3801](https://github.com/bastani-inc/atomic/issues/3801))
+- `session.workflows.waitForSettled(runId)` resolves once a workflow run's ending is recorded in the workflow journal and its lease is released, so an SDK host can wait for the journal to be final after a run reports `completed`, `failed` or `killed`. It resolves at once for a run the session is not executing, and rejects with `WorkflowRunStorageError` when the journal could not record the ending. Extensions that call `registerWorkflowRunControl` must implement `waitForSettled` ([#3811](https://github.com/bastani-inc/atomic/issues/3811))
+- `createStructuredOutputTool()` and `generateStructuredOutput()` accept a `timeoutMs` option: the wall-clock limit in milliseconds for one whole structured decision, covering every repair attempt, transport retry, and model fallback together. Without it, the `structured_output` tool uses the session's `httpIdleTimeoutMs` setting and other calls use that setting's 10-minute default. The calling model cannot set it. Extensions can read the setting with `ctx.getHttpIdleTimeoutMs()` ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- The task-host `CancelCause` contract adds `pause` and `quit`, typed resumable stops for an agent that is paused and awaiting resume rather than ended. A workflow stage pausing now stops its agents with `pause` instead of `parent-handoff`; `parent-handoff` stays valid for fresh-start handoffs and for entries recorded by earlier versions.
+
+### Changed
+
+- `install.sh` and `install.ps1` no longer re-download Atomic when the requested release (or the latest release, when none is requested) is already installed and healthy. They print `atomic <tag> is already installed; skipping download`, keep the `Installed to` line and PATH guidance, and download nothing; on Windows a rerun also restores a missing User PATH entry. A different version, or a missing or broken launcher, `current` pointer (including one that points at a versions directory outside the install root), shim, or payload (including a missing `app.js` or other startup file), installs and repairs as before. Pass `--force` (`-Force` on Windows) or set `ATOMIC_FORCE_INSTALL=1` to reinstall anyway.
+- Reopening `/resume` is faster: the session list is kept between opens and reloads only the sessions that were created, renamed, deleted, or changed since the last open, including changes made by other Atomic processes sharing the store.
+- A subagent stopped with `pause` or `quit`, or by its workflow stage pausing, now reaches the parent as `Subagent <agent> quit · paused, awaiting resume` (or `paused · awaiting resume`) with `Stop reason: quit` or `pause` and the exact `subagent({ action: "resume", id: "<child-id>" })` call, as a quit workflow run is reported, instead of a `parent-handoff` stop notice saying the execution has ended and must not be restarted. Its `/tasks` row shows **Paused · awaiting resume**. Children cancelled for good keep the ended notice.
+- The What's New banner shown after an update now leads with the release's highlights summary and points to `/changelog` for the full list of changes. Releases without a summary still show their full notes ([#3804](https://github.com/bastani-inc/atomic/issues/3804))
+- Provider attribution headers now come from pi-ai's client identity, still sent only while `enableInstallTelemetry` is on. Chat requests to providers send Atomic's `User-Agent` (`atomic/<version> (<platform>; <runtime>; <arch>)`), including Cloudflare requests, which sent `atomic` before, and OpenCode requests send `x-opencode-client` whenever attribution is enabled, not only with a session. Extensions' `before_provider_headers` handlers no longer see the OpenRouter, NVIDIA NIM, and OpenCode attribution headers or the default `User-Agent`.
+- The release lookup that runs before Atomic downloads `fd` or `ripgrep` now sends Atomic's `User-Agent` (`atomic/<version> (<platform>; <runtime>; <arch>)`) instead of `atomic`.
+
+### Fixed
+
+- Fixed Cloudflare Workers AI classifier pricing: Clef Flash costs $0.038 and Jev $0.042 per million input tokens instead of Jev being listed as free.
+- Fixed the `grep` tool following ripgrep's `RIPGREP_CONFIG_PATH` whenever it searches with `rg`, such as with `literal: true`, where config options like `--ignore-case` silently changed what the tool returned. The tool now runs `rg --no-config` ([#11203](https://github.com/earendil-works/pi/issues/11203))
+- Fixed `@` file autocomplete returning no results for queries containing regex metacharacters such as `[` or `(` ([#10972](https://github.com/earendil-works/pi/issues/10972))
+- Fixed an unclosed `$$` display-math block swallowing or corrupting every Markdown table after it ([#11159](https://github.com/earendil-works/pi/issues/11159))
+- Fixed terminal modes (mouse tracking, focus reporting, Kitty keyboard protocol, bracketed paste, alternate screen) staying enabled when the process exits without calling `stop()`. A process `exit` handler now restores them synchronously ([#11170](https://github.com/earendil-works/pi/issues/11170))
+- Fixed Markdown bold and italic not rendering next to CJK punctuation ([#10730](https://github.com/earendil-works/pi/pull/10730) by [@theBucky](https://github.com/theBucky))
+- A rejection that workflow code leaves unhandled no longer ends the whole Atomic process. This covers a rejected `ctx.tool`, `ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.workflow`, `ctx.ui` prompt (`input`, `confirm`, `select`, `editor` or `custom`) or stage method call (`prompt`, `complete`, `steer`, `sendUserMessage`, `setModel`, `compact` and the other promise-returning stage methods), including one that is started and never awaited (`void ctx.task(...)` used to leave the run `completed` with no sign of the failure), a `ctx.tool` call made after its run has stopped (`ctx.tool admission is closed for this run`), a string, number or `undefined` thrown from a `ctx.tool` callback, and an error the workflow file throws or receives from `fs` itself, for example in a rolling pool that keeps `branch.finally(...)` as a separate promise. It also covers `ctx.exit()` called inside such a branch, which ends the run as exited with the status and outputs it asked for (on Bun the process used to end right after the run reported `completed`), and a child workflow's own branch that uses `ctx` after its parent exited. Stopping a run no longer ends the process either: a branch that keeps running after `/workflow quit`, a kill, or an abort signal from the code that started the run, and then calls `ctx.stage`, `ctx.task`, `ctx.workflow` or `ctx.exit()`, or that was waiting on a `ctx.ui` prompt when the run was killed, could end it with `workflow killed` (a kill), the quit error (`/workflow quit`), an `AbortError` or `atomic-workflows: HIL aborted` right after the run reported `killed` or `paused`, and the run keeps that status. `ctx.exit()` called in such a branch while the run is paused ends the run as exited once the run resumes, and a kill of the paused run still ends it as `killed` (on Node it used to end as `failed` with `Workflow exit is waiting for explicit resume`, and on Bun the process ended). The rejection fails its own run when it surfaces before that run decides its final status, so other runs, stages, and the interactive engine keep going; a `ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.workflow`, `ctx.ui` or stage method rejection that the workflow awaits or catches reaches that code unchanged and does not fail the run. Once the run has ended, an error that a `ctx` call rejected with, what `ctx.exit()` threw and the reason the run was stopped with are ignored (the reason of a kill is the string `workflow killed`, which is ignored by value for the rest of the process, so a branch that wakes up long after the run ended is covered too), and so is an error thrown by the workflow file for the next 30 seconds, so the remaining branches of a failing pool cannot end the process; a later one ends it as before. On Node the owning run is identified exactly; on Bun a `ctx` call's rejection, what `ctx.exit()` threw and the reason the run was stopped with are matched by identity (a `ctx` call's string, number or `undefined` only within the event-loop turn in which the call rejected, and the string a kill uses by value), and an error thrown by the workflow file itself is matched through its stack to the run of the file that calls `workflow()`, but only when no other run of that file is running or has run at the same time (a child workflow defined in the same file does not count), so a primitive thrown outside a `ctx` call on Bun is still fatal, and an error that either of two overlapping runs of one file could have thrown ends the process as before instead of failing a run that may be healthy. This works the same in the bundled install as in a source checkout. A rejection that belongs to no workflow run, including one raised by Atomic's own code, ends the process as before, with its original error and stack, and `--unhandled-rejections=warn|none|warn-with-error-code` are honored ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+- A workflow that omits `name` is now named after the file that defines it when Atomic runs from the bundled install, as it already was in a source checkout, instead of after the bundled extension file (`index.bundle`) ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+- `/workflow status <runId>` no longer reports `durable checkpoint topology is malformed or incomplete` for a running or crashed run whose child `ctx.workflow` calls have started but not yet recorded a stage or tool of their own, such as a pool of concurrent children when the process was killed. The children now show as running, and a crashed run can be inspected and resumed. A run that fails while such children are still starting now cancels them first, so its status can be inspected as well ([#3846](https://github.com/bastani-inc/atomic/issues/3846))
+- Fixed `structured_output` and `generateStructuredOutput` failing the whole request with `Structured output model is unavailable or not a chat or classifier model` when one explicit `model` or `fallbackModels` ID could not be resolved, for example a display name instead of a `provider/model` ID. The unresolvable ID is now skipped and recorded in `modelAttempts`, and the remaining candidates, including the current chat model, are still tried. The request fails with the original error only when no candidate resolves ([#3814](https://github.com/bastani-inc/atomic/issues/3814))
+- Fixed concurrent extension `select`/`confirm`/`input`/`editor` dialogs in interactive mode: a second dialog replaced the first and the first promise never settled, and a dialog opened from an inline `custom()` component hid that component for good. Closing the visible dialog now shows the previous one again ([#11166](https://github.com/earendil-works/pi/issues/11166))
+- Fixed pasting in the shell hanging after copying text in Atomic and suspending it with Ctrl+Z on Linux: the background `wl-copy`/`xclip`/`xsel` process that keeps serving the clipboard was suspended along with Atomic ([#11179](https://github.com/earendil-works/pi/issues/11179))
+- Fixed codemode scripts failing immediately when both codemode workers are busy, for example with parallel codemode calls or in-process subagents. Scripts now wait up to 60 seconds for a free worker, and `ATOMIC_CODEMODE_MAX_WORKERS` (or `PI_CODEMODE_MAX_WORKERS`) raises the limit of two workers ([#11184](https://github.com/earendil-works/pi/issues/11184))
+- Fixed `mcp.json` files that start with a UTF-8 BOM failing to parse, which skipped all their MCP servers and made `atomic mcp add`/`atomic mcp remove` fail ([#11191](https://github.com/earendil-works/pi/issues/11191))
+- The default GitHub Copilot model is now GPT-6.1 Sol. The previous default, GPT-5.4, was deprecated by GitHub on 2026-10-19 and dropped from the model catalog, so a Copilot login had no usable default model. GPT-6.1 Sol is GitHub's suggested replacement.
+- When extensions fail to start a session, the error now names each failing extension and its own error (`Extension startup failed: <extension path>: <error>`) instead of only `Extension startup failed`. The SDK exports the thrown `ExtensionStartupError`, whose `failures` lists the extension path, event, and message of each failure, together with `isExtensionStartupFailure()` and `isTransientExtensionStartupFailure()` ([#3807](https://github.com/bastani-inc/atomic/issues/3807)).
+- Stored OAuth logins, such as `openai-1` or `anthropic-2`, no longer stop working with `OAuth refresh failed ... invalid_grant` under heavy load from many sessions, workflow stages, or subagents until you run `/login`. A session that is slow or briefly unresponsive while it refreshes a token keeps its claim on that refresh, so another session no longer reuses the replaced refresh token. A slow token refresh is no longer cut off at its timeout. Its result is saved when the response arrives, and other sessions wait for it instead of reusing the replaced token. A token refresh the provider completed is also saved when another session took over meanwhile. A session whose refresh is rejected uses a login that another session has just saved. A login the provider has revoked or expired still fails. The error now tells you to run `/login <provider>` for that provider and shows only the provider's error code and description, never tokens.
+- Sessions waiting for another session's OAuth token refresh no longer fail with `Lock file is already being held` before that refresh finishes under heavy load. They now wait as long as a refresh can keep its claim, then use the rotated token. Cancelling the request still stops the wait.
+- Kimi Code logins no longer break with `invalid_grant` when a token refresh takes longer than 30 seconds or loses its connection mid-request. A revoked or expired OpenAI, Kimi Code, xAI, Meta or GitHub Copilot login now also tells you to run `/login <provider>`, for example on OpenAI's `refresh_token_expired` or `refresh_token_reused` errors.
+- A stored OAuth login no longer breaks with `invalid_grant` after Atomic exits while a token refresh is still running, for example a subagent or `atomic -p` run ending after its request timed out, quitting an interactive session, `SIGTERM`, or `atomic auth`. Atomic now waits up to three seconds on exit for the provider's response and saves the rotated token. An `atomic -p` run no longer stays alive waiting for a token refresh that never answers. If Atomic is killed or crashes during a token refresh, run `/login <provider>`.
+- An extension or `models.json` provider whose `$VAR` API key is unset now reports the missing key the way a built-in provider does wherever its models are used, for example `No API key found for <provider>` with the `/login` hint during compaction and branch summaries. Previously compaction, branch summaries, workflow stages, and subagents failed with `Failed to resolve API key ... from environment variable`.
+- Extension OAuth providers whose refresh is rejected now get the built-in `run /login <provider>` guidance, and a newer login another session saved is still used first, when `refreshToken` throws an error carrying a code the built-in providers treat as a rejected login (`invalid_grant`, `refresh_token_expired`, `refresh_token_reused`, or `refresh_token_invalidated`) in its `error` or `code` property or in an OAuth error response (flat or nested under `error.code`) in `body`, `data`, `response.data`, or `response.body`, or HTTP status 401 in `status`, `statusCode`, `response.status`, or `response.statusCode`. Previously these showed the raw error message, which could include the request's tokens.
+- In interactive sessions, `/login` lists extension providers that take an API key and logs in to them, `/logout` offers their stored keys, and `/login` shows an extension provider configured through an environment variable as configured instead of `not configured`.
+- `/resume` search no longer keeps a session's old text after the session is rewritten with the same message count, first message, header and last-modified time, for example when an earlier message's text is replaced. Search now finds the new text and not the removed text, including when another Atomic process made the change.
+- `structured_output` and `generateStructuredOutput` rejections now say what was wrong instead of the fixed `Invalid structured output: response does not match the decision schema.`. A schema mismatch lists up to five failing paths with the expected shape, such as `/files: expected array, got string` and `/summary: required`, followed by `and N more` when there are others, and never echoes the rejected values. When the provider's tool arguments were not valid JSON, the error is `Invalid structured output: tool call arguments were not valid JSON.` with the kind of syntax error and, when known, its position, without quoting the arguments, instead of a schema mismatch on `{}`. The same detail is sent to the model in the repair request and is kept in `modelAttempts` when a candidate model is exhausted ([#3802](https://github.com/bastani-inc/atomic/issues/3802))
+- Shell `wait` and `kill` results now read as one status line above the task's output instead of a raw JSON envelope with internal ids: `✓ completed · exit 0`, `✗ exited 1`, `● still running · showing output so far`, or `○ cancelled`. A truncated result keeps the full-output path as a dim line, and `(no output)` is dimmed. Waiting on or killing an unknown or foreign task id now says `No background task "<id>" in this session` and points to `/tasks`, instead of `UnknownTask: UnknownTask`. The agent receives the same facts as one compact sentence (state, exit code, truncation, full-output path), the structured observation or cancellation receipt stays in the result `details`, and the failures thrown by `wait` and `kill` keep their code in a `code` property ([#3828](https://github.com/bastani-inc/atomic/issues/3828))
+- Fixed a structured decision having no total time limit: a `structured_output` call, a `generateStructuredOutput()` call, or one routing inference for `model: "auto"` could run four slow generations back to back, plus retries, past every configured timeout, and held a workflow stage for over an hour. The whole decision is now stopped after the `httpIdleTimeoutMs` setting (10 minutes by default; disabled means effectively unbounded) and fails with `Structured output decision exceeded its <n>ms deadline; no decision was accepted.`, without trying another repair or fallback model ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- The error for exhausted `structured_output` and `generateStructuredOutput` repairs, and the new deadline error, now end with how each attempt finished and how long it took, such as `Attempts: 1) stopReason=stop 25m02s; 2) stopReason=length 1m30s.`, so one slow generation reads differently from several failed ones. Each provider request, including a transport retry, is listed on its own ([#3806](https://github.com/bastani-inc/atomic/issues/3806))
+- Messages typed while the agent was busy are no longer dropped or left waiting for the end of the run. A message typed while a prompt was still being prepared, while Atomic waited to retry a failed request, just after you sent a prompt (before the screen showed that the turn had started), or while extensions were still finishing the previous run used to appear nowhere and be sent only after the run ended, or be refused with "Agent is already processing" and lost. It now shows as queued straight away and joins the run at its next turn boundary, in the order you typed it. If the agent refuses a message, the text comes back to the editor, or stays in the queue, together with the error.
+- Queued messages are no longer left undelivered when the agent finishes before they are queued. The rest of a queued batch, such as the messages held during compaction, and a `steer` or `follow_up` sent to an idle agent whose session already has messages now start a turn instead of waiting for your next prompt.
+- Near-neutral backgrounds such as message and selection backgrounds no longer turn too bright or blue in 256-color terminals: they now use the nearest color-cube or grayscale entry. Tool status backgrounds keep their blue, green, or red tint, so pending, successful, and failed tool blocks stay distinguishable ([#2550](https://github.com/bastani-inc/atomic/issues/2550))
+- Fixed resumed sessions and `/tree` navigation leaving extension tools inactive when the branch recorded its tools before they were registered, such as tools from extensions installed after the session started. Extension tools the branch never added or removed are now active unless they are registered with `defaultActive: false` ([#11062](https://github.com/earendil-works/pi/issues/11062), [#11075](https://github.com/earendil-works/pi/issues/11075))
+
 ## [0.9.41-alpha.3] - 2026-10-22
 
 Usage totals now say whether their cost was billed by the provider or estimated.

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.42-alpha.1] - 2026-10-23
+
+### Added
+
+- `intercom({ action: "status" })` reports the broker's multi-node routing state, for example `Multi-node routing: on (adapter @bastani/atomic-storage-libsql, prefix none), 1 peer broker live (build-host)`, or why it is off or unavailable ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- The broker writes a positive line to `broker.log` when it starts: `Intercom multi-node routing is on (adapter <adapter>, prefix <prefix>)`, or `Intercom multi-node routing is off: <reason>`, also for an absent, in-memory, or domain-only selection, so a log without errors is no longer ambiguous ([#3856](https://github.com/bastani-inc/atomic/issues/3856), [#3857](https://github.com/bastani-inc/atomic/issues/3857))
+- The broker answers status and shutdown requests from `atomic storage status`, `atomic intercom status`, and `atomic intercom restart`: its storage selection, sessions, multi-node state, and the other brokers live in the shared database. A restart lets connected sessions reconnect to a broker that reads the current storage selection, without closing them ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+
+### Fixed
+
+- Fixed Intercom remaining stuck on a broker that accepts connections but stops answering. New brokers monitor their own request handling and terminate after about a minute of failed health checks so clients can start one replacement. Timed-out client requests also check connection health before entering reconnect recovery, without restarting a responsive broker. Identical in-flight sends keep sharing one result through the health check. A bounded previous broker log and the latest watchdog diagnosis survive replacement ([#3862](https://github.com/bastani-inc/atomic/issues/3862)).
+- Restarting an older broker on Windows no longer mistakes a lingering named pipe for a restarted broker after its process has exited ([#3857](https://github.com/bastani-inc/atomic/issues/3857))
+
+## [0.9.41] - 2026-10-22
+
+### Changed
+
+- Workflow route updates cost the Intercom broker far less when many runs are active. The broker now acknowledges each route registration itself instead of the session listing the previous version requested after every update, and each run's route connection retries on its own backoff, with limited concurrency, instead of all of them reconnecting at once. A workflow stage that starts while its run's route connection is waiting to retry waits for that retry rather than failing, and a retry that fails is retried by the stage like any other connection timeout. Mixed versions keep working: with an older broker the session listing is still used, and older sessions work with the new broker.
+
+### Fixed
+
+- `intercom list` with a `group` that names a workflow invocation group you are not a member of no longer reports `No sessions or workflow stages in this group.` The group is visible only to its members, so the peek now says that and tells you to `intercom join` it to see its stages, instead of looking like a run whose stages had all disappeared.
+- Fixed `Intercom event relay failed (atomic:workflow-pending-stage-route): Connection timeout` repeating for every route update when 50 or more workflows ran at once. A broker that is slow to answer a connection is now a recoverable condition that background relays retry quietly. A broker that stays unresponsive for a minute is reported once, and Intercom tool calls you make still report the failure.
+- Fixed a single workflow run's route connection failing to connect and dropping the session's healthy Intercom connection, which re-created every run's connection at the same time.
+
 ## [0.9.41-alpha.1] - 2026-10-21
 
 ### Changed

package/dist/builtin/intercom/README.md

@@ -389,7 +389,7 @@ When multiple live agent stages share a name, `ask` refuses the ambiguous target
 
 `contact_supervisor` decisions and interviews are deliberately exclusive per child: one supervisor wait may coexist with ordinary peer asks, but a second concurrent supervisor wait receives `Already waiting for a supervisor reply`. Claimed foreground parent handoffs remain first-claim-wins and do not allocate a waiter. Multiple children can contact the same parent independently because inbound asks and handoffs are keyed by child/message identity. Mutual peer asks are supported, but each side must process inbound work to reply; the per-waiter timeout remains the deadlock backstop.
 
-**`status`** — Shows connection status, session ID, every current membership, and the total visible-session count. A `group` filter remains a read-only peek.
+**`status`** — Shows connection status, session ID, every current membership, and the total visible-session count. It also reports the broker's multi-node routing state on a `Multi-node routing:` line: `on (adapter <adapter>, prefix <prefix>)` with the number of other brokers live in the shared database, or why routing is off or unavailable; `details.multiNode` carries the same fields. A broker that predates status reporting shows `unknown`, and `atomic intercom restart` replaces it. A `group` filter remains a read-only peek.
 
 ## Keyboard Shortcuts
 
@@ -463,6 +463,8 @@ graph TB
 
 The broker is a standalone TypeScript process that manages session registration and message routing. It auto-spawns when the first session that invokes Intercom needs it and exits after 5 seconds when it last has no registered sessions, including brokers that never received a connection and sockets that close before register. Clients reconnect automatically if the broker disappears and later comes back. A failed reconnect schedules the next attempt on a bounded backoff (1s, 2s, 5s, 10s, then 30s) once it releases reconnect ownership, so a transient failure never leaves a live session with nothing owning recovery; a failed explicit tool or overlay connection still returns its error to the caller and leaves the retry behind. A reconnect that fails after the broker already accepted it closes that connection first, so a session never appears twice in `intercom list`.
 
+A broker-owned watchdog checks the local request path independently of the broker's main thread. After about a minute without a valid response from its own broker instance, it terminates its own process; clients reconnect through the existing spawn lock. It never signals a PID read from `broker.pid`. A timed-out client request shares one connection-health check with other simultaneous timeouts on that connection, and invalidates a silent connection. A responsive broker is left running. Brokers already running from an older version gain the watchdog only after a restart; an OS-suspended process cannot run it.
+
 Each `send`, `ask`, or `reply` invocation retries typed recoverable disconnects internally up to three times, after delays of 1, 2, and 5 seconds. Retries keep the same message ID, exact arguments, attachment order and presence, and reply route. The model does not supply or receive a retry token; existing integrations must remove `retryToken`, which is now refused without sending. Every new invocation remains a fresh operation, even with identical text. Confirmation happens once, and neither retries nor renewed reply waits extend the original 11-minute operation deadline.
 
 Lazy initialization before delivery has a separate limit of three reconnect retries on the same schedule. If that phase stops, the tool reports `outcome: "not_sent"`. The initialization wrapper never re-executes a delivery that has already started.
@@ -494,7 +496,9 @@ Runtime files live under the active agent directory. Atomic defaults to `~/.atom
 - `delivered-messages.key` — random owner-only HMAC key paired with the authority database
 - `broker.spawn.lock` — Lock used to avoid duplicate auto-spawns. It records the spawner and its broker, and is held until the broker answers or the processes it names are gone, with a 60 second backstop. On Windows, where the hidden launcher does not expose the broker process, it ends with the spawner's 5 second readiness wait, and a later spawn that finds `broker.log` still held by a starting broker waits for that broker instead of starting another
 - `broker.sock.replace.lock` — Short-lived lock a starting broker holds while it re-checks and replaces a stale socket file, so two brokers never both replace it
-- `broker.log` — Broker stderr, truncated on every spawn and capped at 8 KiB by the broker itself
+- `broker.log` — Broker stderr, capped at 8 KiB by the broker itself. It records whether multi-node routing is on (`Intercom multi-node routing is on (adapter <adapter>, prefix <prefix>)`) or off and why
+- `broker.log.previous` — The bounded tail of the previous nonempty broker log, preserved on spawn
+- `broker-watchdog.log` — The latest watchdog termination's time, PID, instance, and reason; kept across spawns
 - `config.json` — User configuration
 
 The broker is a detached subprocess and never inherits the host's extension-loader module aliases, so every module reachable from `broker/broker.ts` resolves to Node built-ins or Intercom's own files. Its stderr is captured to `broker.log` through an already-open file descriptor rather than a pipe, because a pipe to a process that outlives its parent breaks once the parent exits. Startup failures — both an early exit and a readiness timeout — quote the log path and a bounded tail of that output.
@@ -505,7 +509,7 @@ The broker caps the file from the inside, since nothing on the parent side can b
 
 **Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux and a named pipe on Windows, which keeps setup simple and avoids port management.
 
-**Auto-spawn with file lock.** The broker starts on first connection and exits after 5 seconds idle. There is no daemon to manage. A spawn lock file, keyed by PID and timestamp, prevents duplicate brokers when multiple sessions start at once. A broker that starts while another broker already answers on the socket exits instead of taking the socket over; it replaces only a stale socket file. A broker whose socket path comes to point at another broker shuts down, and its sessions reconnect to the broker that owns the path.
+**Auto-spawn with file lock.** The broker starts on first connection and exits after 5 seconds idle. There is no daemon to manage. A spawn lock file, keyed by PID and timestamp, prevents duplicate brokers when multiple sessions start at once. A broker that starts while another broker already answers on the socket exits instead of taking the socket over; it replaces only a stale socket file. A broker whose socket path comes to point at another broker shuts down, and its sessions reconnect to the broker that owns the path. `atomic intercom restart` asks the broker to shut down over its socket (a `shutdown` request, accepted before registration like `broker_status`), so its sessions reconnect to a broker that reads the current storage selection.
 
 **`ask` stays client-side.** The broker still routes plain messages; it does not have a special request/response mode for `ask`. The client waits for a matching reply before it triggers a new turn, then returns that reply as the tool result. Reply hints make that flow practical by showing the recipient the exact `send` call to use. Separately, `list` / `sessions` now carry a `requestId` so a delayed session-list reply cannot be mistaken for a newer one.
 

package/dist/builtin/intercom/broker/broker-status.ts

@@ -0,0 +1,48 @@
+import type { BrokerMultiNodeStatus, BrokerStatusReport } from "../types.js";
+import type { JsonWireValue } from "./framing.js";
+
+type WireObject = { [key: string]: JsonWireValue };
+
+function isObject(value: JsonWireValue | undefined): value is WireObject {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isOptionalString(value: JsonWireValue | undefined): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+/** Whether a `broker_status` frame's `report` has the shape this version reads. */
+export function isBrokerStatusReport(value: JsonWireValue | undefined): value is WireObject & BrokerStatusReport {
+	if (!isObject(value) || typeof value.pid !== "number" || typeof value.sessions !== "number") return false;
+	const { storage, multiNode } = value;
+	if (
+		storage !== undefined &&
+		(!isObject(storage) ||
+			typeof storage.digest !== "string" ||
+			(storage.source !== "env" && storage.source !== "settings"))
+	)
+		return false;
+	return (
+		isObject(multiNode) &&
+		(multiNode.status === "off" ||
+			multiNode.status === "starting" ||
+			multiNode.status === "on" ||
+			multiNode.status === "unavailable") &&
+		isOptionalString(multiNode.reason) &&
+		isOptionalString(multiNode.adapter) &&
+		isOptionalString(multiNode.prefix) &&
+		(multiNode.peers === undefined ||
+			(Array.isArray(multiNode.peers) && multiNode.peers.every((peer) => typeof peer === "string")))
+	);
+}
+
+/** One line for a broker's multi-node routing state, e.g. `on (adapter x, prefix none), 1 peer broker live (host-b)`. */
+export function describeMultiNodeStatus(multiNode: BrokerMultiNodeStatus): string {
+	const storage = multiNode.adapter === undefined ? "" : ` (adapter ${multiNode.adapter}, prefix ${multiNode.prefix ?? "none"})`;
+	if (multiNode.status === "off" || multiNode.status === "unavailable") {
+		return `${multiNode.status}${storage}${multiNode.reason === undefined ? "" : `: ${multiNode.reason}`}`;
+	}
+	if (multiNode.status === "starting" || multiNode.peers === undefined) return `${multiNode.status}${storage}`;
+	const count = `${multiNode.peers.length} peer broker${multiNode.peers.length === 1 ? "" : "s"} live`;
+	return `on${storage}, ${count}${multiNode.peers.length === 0 ? "" : ` (${[...new Set(multiNode.peers)].join(", ")})`}`;
+}

package/dist/builtin/intercom/broker/broker.ts

@@ -17,17 +17,21 @@ import {
 } from "./socket-writes.js";
 import { isSocketAnswering } from "./socket-liveness.js";
 import { acquireSocketReplacementLock } from "./socket-replacement-lock.js";
+import { startBrokerWatchdog } from "./watchdog.js";
 import {
 	getBrokerDeliveredMessagesPath,
 	getBrokerPidPath,
+	getBrokerWatchdogLogPath,
 	getBrokerSocketPath,
 	getBrokerSocketReplacementLockPath,
 	getIntercomDirPath,
 } from "./paths.js";
+import { describeSharedStorage, sharedStorageDigest, sharedStorageSettingSource } from "./shared-storage-setting.js";
 import type {
 	SessionInfo,
 	Message,
 	BrokerMessage,
+	BrokerStatusReport,
 	SupervisorRegistration,
 	WorkflowStageRosterAnnouncement,
 	WorkflowStageRosterEntry,
@@ -86,6 +90,8 @@ import {
 
 const INTERCOM_DIR = getIntercomDirPath();
 const SOCKET_PATH = getBrokerSocketPath();
+const BROKER_IDLE_TIMEOUT_MS = 5_000;
+const UNCLASSIFIED_CONNECTION_RECHECK_MS = 100;
 const PID_PATH = getBrokerPidPath();
 const SOCKET_REPLACEMENT_LOCK_PATH = getBrokerSocketReplacementLockPath();
 
@@ -94,6 +100,13 @@ const LISTEN_ATTEMPTS = 5;
 const LISTEN_RETRY_DELAY_MS = 100;
 const SOCKET_OWNERSHIP_CHECK_MS = 1_000;
 const MULTI_NODE_CLOSE_BOUND_MS = 2_000;
+const NO_SHARED_STORAGE_REASON = "no shared storage selection (top-level `storage` in global settings, or ATOMIC_STORAGE)";
+/** The off reasons `resolveBrokerStateSource` reports without an error, as the log and `broker_status` state them. */
+const MULTI_NODE_OFF_REASONS: Readonly<Record<string, string>> = {
+  "no-storage": "the shared storage selection names no database",
+  memory: "the shared storage selection is in memory",
+  "domain-only-adapter": "the storage adapter has no openDatabase hook",
+};
 
 function exitBecauseLiveBrokerOwnsSocket(): never {
   console.error(`Intercom broker not started: a live broker already answers on ${SOCKET_PATH}`);
@@ -302,7 +315,9 @@ function isWorkflowPossibleStageAnnouncements(
 
 class IntercomBroker {
   private sessions = new Map<string, ConnectedSession>();
+  private unclassifiedConnections = new Map<net.Socket, number>();
   private server: net.Server;
+  private readonly instanceId = randomUUID();
   private shutdownTimer: NodeJS.Timeout | null = null;
   private boundSocketInode: number | undefined;
   private lastConnectionAt = performance.now();
@@ -328,6 +343,8 @@ class IntercomBroker {
     this.sharedStorageSetting === undefined ? undefined : (request) => this.routeRemoteSend(request);
   private multiNode: MultiNodeRouter | undefined;
   private multiNodeStatus: "starting" | "on" | "off" | "unavailable" = "off";
+  /** Why multi-node routing is off or unavailable, for `broker_status` and the log. */
+  private multiNodeReason: string | undefined = NO_SHARED_STORAGE_REASON;
   private multiNodeFirstAttempt: Promise<void> = Promise.resolve();
   private shuttingDown = false;
 
@@ -340,6 +357,7 @@ class IntercomBroker {
   start(): void {
     this.listen(1);
     if (this.sharedStorageSetting !== undefined) this.startMultiNode(this.sharedStorageSetting);
+    else console.error(`Intercom multi-node routing is off: ${NO_SHARED_STORAGE_REASON}`);
     process.on("SIGTERM", () => this.shutdown());
     process.on("SIGINT", () => this.shutdown());
   }
@@ -356,6 +374,7 @@ class IntercomBroker {
       releaseReplacementLock();
       writeFileSync(PID_PATH, String(process.pid));
       console.log(`Intercom broker started (pid: ${process.pid})`);
+      startBrokerWatchdog(SOCKET_PATH, this.instanceId, getBrokerWatchdogLogPath());
       this.lastConnectionAt = performance.now();
       this.scheduleShutdownCheck();
       if (this.boundSocketInode !== undefined) this.watchSocketOwnership();
@@ -415,11 +434,18 @@ class IntercomBroker {
 
   private handleConnection(socket: net.Socket): void {
     let sessionId: string | null = null;
-    this.lastConnectionAt = performance.now();
-    this.restartShutdownCheck();
+    this.unclassifiedConnections.set(socket, performance.now());
+    const recordActivity = () => {
+      this.lastConnectionAt = performance.now();
+      this.restartShutdownCheck();
+    };
 
     const reader = createMessageReader((msg) => {
       if (socket.destroyed || socket.writableEnded) return;
+      if (this.unclassifiedConnections.delete(socket)) {
+        const health = typeof msg === "object" && msg !== null && !Array.isArray(msg) && msg.type === "health";
+        if (!health) recordActivity();
+      }
       this.handleMessage(socket, msg, sessionId, (id) => {
         sessionId = id;
       });
@@ -441,6 +467,7 @@ class IntercomBroker {
     // is lost. disconnectSession is idempotent, so 'end', 'error' and 'close'
     // may each fire without duplicating the departure broadcast.
     const retire = () => {
+      if (this.unclassifiedConnections.delete(socket)) recordActivity();
       const departing = sessionId;
       if (departing === null) return;
       sessionId = null;
@@ -464,17 +491,24 @@ class IntercomBroker {
     });
   }
 
-  private scheduleShutdownCheck(): void {
+  private scheduleShutdownCheck(delayMs = BROKER_IDLE_TIMEOUT_MS): void {
     if (this.shutdownTimer) return;
 
     this.shutdownTimer = setTimeout(() => {
       this.shutdownTimer = null;
       if (this.sessions.size === 0) {
+        const now = performance.now();
+        const awaitingFirstFrame = [...this.unclassifiedConnections.values()]
+          .some((acceptedAt) => now - acceptedAt < BROKER_IDLE_TIMEOUT_MS);
+        if (awaitingFirstFrame) {
+          this.scheduleShutdownCheck(UNCLASSIFIED_CONNECTION_RECHECK_MS);
+          return;
+        }
         const idleMs = Math.round(performance.now() - this.lastConnectionAt);
         console.log(`No sessions connected for ${idleMs}ms since the last connection, shutting down`);
         this.shutdown();
       }
-    }, 5000);
+    }, delayMs);
   }
 
   private restartShutdownCheck(): void {
@@ -1473,6 +1507,27 @@ class IntercomBroker {
 
     const clientMessage = msg;
 
+    if (clientMessage.type === "health") {
+      if (typeof clientMessage.requestId !== "string" || clientMessage.requestId.length > 128) {
+        throw new Error("Invalid health request");
+      }
+      writeMessageIfOpen(socket, { type: "health", requestId: clientMessage.requestId, instanceId: this.instanceId });
+      return;
+    }
+
+    // Control requests need no registration: `atomic intercom restart` and `atomic storage status` send them.
+    if (clientMessage.type === "broker_status" || clientMessage.type === "shutdown") {
+      if (typeof clientMessage.requestId !== "string") throw new Error(`Invalid ${clientMessage.type} message`);
+      const requestId = clientMessage.requestId;
+      if (clientMessage.type === "broker_status") {
+        void this.statusReport().then((report) => writeMessageIfOpen(socket, { type: "broker_status", requestId, report }));
+        return;
+      }
+      console.error("Intercom broker shutting down on request, so its sessions reconnect to a new broker");
+      writeMessageWithOutcome(socket, { type: "shutdown_ack", requestId }, () => this.shutdown());
+      return;
+    }
+
     if (currentId === null && clientMessage.type !== "register") {
       throw new Error(`Received ${clientMessage.type} before register`);
     }
@@ -1567,6 +1622,7 @@ class IntercomBroker {
             ...(supervisorId ? { supervisorSessionId: supervisorId } : {}),
             ...(clientMessage.acknowledgesReceipt === true ? { acknowledgesReceipt: true as const } : {}),
             acknowledgesPendingStageRoutes: true as const,
+            brokerStatus: true as const,
           });
           if (isAgentRecipient(info)) this.broadcastToMemberships({ type: "session_joined", session: info }, sessionGroups(info), id);
           // #3761: messages written to this recipient's previous connection that it never confirmed saving go out again.
@@ -2097,12 +2153,32 @@ class IntercomBroker {
     });
   }
 
+  /** This broker's `broker_status` report: its storage selection's digest, multi-node state and live peers. */
+  private async statusReport(): Promise<BrokerStatusReport> {
+    const setting = this.sharedStorageSetting;
+    const peers = this.multiNodeStatus === "on" ? await this.multiNode?.peerBrokers() : undefined;
+    return {
+      pid: process.pid,
+      sessions: this.sessions.size,
+      ...(setting === undefined
+        ? {}
+        : { storage: { digest: sharedStorageDigest(setting), source: sharedStorageSettingSource() } }),
+      multiNode: {
+        status: this.multiNodeStatus,
+        ...(this.multiNodeReason === undefined ? {} : { reason: this.multiNodeReason }),
+        ...(setting === undefined ? {} : describeSharedStorage(setting)),
+        ...(peers === undefined ? {} : { peers }),
+      },
+    };
+  }
+
   /**
    * The shared state is loaded lazily, so a single-node broker never loads the host storage layer. A database that
    * cannot be opened is retried with exponential backoff; meanwhile local delivery continues.
    */
-  private startMultiNode(setting: Record<string, unknown>): void {
+  private startMultiNode(setting: Record<string, JsonWireValue>): void {
     this.multiNodeStatus = "starting";
+    this.multiNodeReason = undefined;
     let settleFirstAttempt: () => void = () => {};
     this.multiNodeFirstAttempt = new Promise<void>((resolve) => {
       settleFirstAttempt = resolve;
@@ -2112,7 +2188,8 @@ class IntercomBroker {
       settleFirstAttempt();
     };
     const report = (error: unknown): void => {
-      console.error(`Intercom multi-node routing is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      this.multiNodeReason = error instanceof Error ? error.message : String(error);
+      console.error(`Intercom multi-node routing is unavailable: ${this.multiNodeReason}`);
     };
     void (async () => {
       const startup = await resolveMultiNodeStartup(setting, dirname(INTERCOM_DIR), async () => {
@@ -2126,9 +2203,10 @@ class IntercomBroker {
         return opener;
       });
       if (startup.status === "off") {
-        // A standalone binary has no host storage module, and a selection may not resolve to a database: both
-        // leave this broker single-node, exactly as without a shared `storage`.
-        if (startup.error !== undefined) console.error(`Intercom multi-node routing is off: ${startup.reason}`);
+        // A selection that does not resolve to a database, or an adapter that cannot load, leaves this broker
+        // single-node, exactly as without a shared `storage`.
+        this.multiNodeReason = startup.error === undefined ? (MULTI_NODE_OFF_REASONS[startup.reason] ?? startup.reason) : startup.reason;
+        console.error(`Intercom multi-node routing is off: ${this.multiNodeReason}`);
         settle("off");
         return;
       }
@@ -2171,6 +2249,9 @@ class IntercomBroker {
             }
           }
           if (this.shuttingDown) await this.multiNode.close().catch(() => {});
+          this.multiNodeReason = undefined;
+          const { adapter, prefix } = describeSharedStorage(setting);
+          console.error(`Intercom multi-node routing is on (adapter ${adapter}, prefix ${prefix ?? "none"})`);
           settle("on");
           return;
         } catch (error) {