@bastani/atomic 0.9.41 → 0.9.42-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## [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.

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,19 @@ 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

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) {