@bastani/atomic 0.9.41 → 0.9.42-alpha.1

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

@@ -1,12 +1,14 @@
 import { EventEmitter } from "events";
 import net from "net";
 import { randomUUID } from "crypto";
-import { writeMessage, createMessageReader } from "./framing.js";
+import { writeMessage, createMessageReader, type JsonWireValue } from "./framing.js";
+import { isBrokerStatusReport } from "./broker-status.js";
 import { getBrokerSocketPath } from "./paths.js";
 import type {
 	SessionInfo,
 	Message,
 	Attachment,
+	BrokerStatusReport,
 	GroupSummary,
 	SupervisorRegistration,
 	SessionDirectory,
@@ -16,7 +18,7 @@ import type {
 	WorkflowPossibleStageAnnouncement,
 	WorkflowRunParentAnnouncement,
 } from "../types.js";
-import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry.js";
+import { buildSendSignature, PendingSendRegistry, PendingSendTimeoutError } from "./pending-send-registry.js";
 import { readSubagentMessageSource } from "../source-ownership.js";
 import { isMessage, isSessionInfo } from "./client-message-validation.js";
 import { normalizeGroups } from "../group.js";
@@ -175,12 +177,14 @@ export class IntercomClient extends EventEmitter {
 	private brokerAcknowledgesReceipt = false;
 	/** The broker of the current registration answers a pending-stage route registration that carries a `requestId`. */
 	private brokerAcknowledgesPendingStageRoutes = false;
+	private brokerAnswersStatus = false;
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
   private _supervisorSessionId: string | null = null;
   /** Source identity is captured once at connect, never read from env per message. */
   private _messageSource: Message["source"] | undefined;
   private pendingSends = new PendingSendRegistry();
+  private readonly sendResults = new WeakMap<Promise<SendResult>, Promise<SendResult>>();
   private pendingReplyTargets = new Map<string, { messageId: string; bind(sessionId: string): void }>();
   private pendingGroupLists = new Map<string, { resolve: (groups: GroupSummary[]) => void; reject: (error: Error) => void }>();
   private pendingLists = new Map<string, { resolve: (directory: SessionDirectory) => void; reject: (e: Error) => void }>();
@@ -190,6 +194,7 @@ export class IntercomClient extends EventEmitter {
     groups?: string[];
   }>();
   private pendingMemberships = new Map<string, { resolve: (groups: string[]) => void; reject: (error: Error) => void }>();
+  private pendingBrokerStatus = new Map<string, { resolve: (report: BrokerStatusReport) => void; reject: (error: Error) => void }>();
   private _groups = normalizeGroups();
   private pendingLiveWorkflowStageRoutes = new Map<string, { resolve(): void; reject(error: Error): void }>();
   private pendingStageRouteRegistrations = new Map<string, { resolve(): void; reject(error: Error): void }>();
@@ -201,6 +206,43 @@ export class IntercomClient extends EventEmitter {
   private pendingRestoringRecipientRequests = new Map<string, { resolve(): void; reject(error: Error): void }>();
   private disconnecting = false;
   private disconnectError: Error | null = null;
+  private healthCheck: { socket: net.Socket; result: Promise<Error | undefined> } | undefined;
+
+  private async requestTimeout(socket: net.Socket, error: Error): Promise<Error> {
+    if (this.socket !== socket || socket.destroyed) return this.disconnectError ?? new IntercomClientDisconnectedError();
+    if (this.healthCheck?.socket !== socket) {
+      const requestId = randomUUID();
+      const result = new Promise<Error | undefined>((resolve) => {
+        const finish = (failure?: Error) => {
+          clearTimeout(timer);
+          this.pendingGroupLists.delete(requestId);
+          resolve(failure);
+        };
+        const timer = setTimeout(() => finish(new IntercomBrokerTimeoutError("Broker health check timed out")), GROUP_REQUEST_TIMEOUT_MS);
+        this.pendingGroupLists.set(requestId, { resolve: () => finish(), reject: finish });
+        try {
+          writeMessage(socket, { type: "list_groups", requestId });
+        } catch (cause) {
+          finish(new IntercomClientDisconnectedError({ cause }));
+        }
+      });
+      this.healthCheck = { socket, result };
+    }
+    const check = this.healthCheck;
+    const failure = await check.result;
+    if (this.healthCheck === check) this.healthCheck = undefined;
+    if (failure === undefined) return error;
+    const reported = failure instanceof IntercomBrokerTimeoutError
+      ? new IntercomBrokerTimeoutError(error.message, { cause: failure })
+      : failure;
+    if (this.socket === socket && !this.disconnecting) {
+      this.disconnectError ??= reported;
+      this.failPending(this.disconnectError);
+      socket.destroy();
+      return this.disconnectError;
+    }
+    return reported;
+  }
 
 	constructor(returnAddress: string = randomUUID(), options: IntercomClientOptions = {}) {
 		super();
@@ -221,6 +263,7 @@ export class IntercomClient extends EventEmitter {
     for (const pending of this.pendingMemberships.values()) pending.reject(error);
     for (const pending of this.pendingLiveWorkflowStageRoutes.values()) pending.reject(error);
     for (const pending of this.pendingStageRouteRegistrations.values()) pending.reject(error);
+    for (const pending of this.pendingBrokerStatus.values()) pending.reject(error);
     this.pendingLists.clear();
     this.pendingGroupLists.clear();
     this.pendingSupervisorAuthorizations.clear();
@@ -229,6 +272,7 @@ export class IntercomClient extends EventEmitter {
     this.pendingMemberships.clear();
     this.pendingLiveWorkflowStageRoutes.clear();
     this.pendingStageRouteRegistrations.clear();
+    this.pendingBrokerStatus.clear();
   }
 
 
@@ -332,6 +376,7 @@ export class IntercomClient extends EventEmitter {
         this._supervisorSessionId = null;
         this.brokerAcknowledgesReceipt = false;
         this.brokerAcknowledgesPendingStageRoutes = false;
+        this.brokerAnswersStatus = false;
         this._messageSource = undefined;
         this.disconnectError = null;
         if (connectionEstablished && !wasDisconnecting) {
@@ -440,7 +485,8 @@ export class IntercomClient extends EventEmitter {
         if (typeof brokerMessage.sessionId !== "string"
           || (brokerMessage.supervisorSessionId !== undefined && typeof brokerMessage.supervisorSessionId !== "string")
           || (brokerMessage.acknowledgesReceipt !== undefined && brokerMessage.acknowledgesReceipt !== true)
-          || (brokerMessage.acknowledgesPendingStageRoutes !== undefined && brokerMessage.acknowledgesPendingStageRoutes !== true)) {
+          || (brokerMessage.acknowledgesPendingStageRoutes !== undefined && brokerMessage.acknowledgesPendingStageRoutes !== true)
+          || (brokerMessage.brokerStatus !== undefined && brokerMessage.brokerStatus !== true)) {
           throw new Error("Invalid registered message");
         }
 
@@ -454,6 +500,7 @@ export class IntercomClient extends EventEmitter {
         // #3761: a broker from before receipts never echoes the capability and drops a client that sends `received`.
         this.brokerAcknowledgesReceipt = this.acknowledgesReceipt && brokerMessage.acknowledgesReceipt === true;
         this.brokerAcknowledgesPendingStageRoutes = brokerMessage.acknowledgesPendingStageRoutes === true;
+        this.brokerAnswersStatus = brokerMessage.brokerStatus === true;
         this.emit("_registered", { type: "registered", sessionId: brokerMessage.sessionId });
         break;
       }
@@ -539,6 +586,16 @@ export class IntercomClient extends EventEmitter {
         pending.resolve(groups as GroupSummary[]);
         break;
       }
+      case "broker_status": {
+        const { requestId } = brokerMessage;
+        const report = brokerMessage.report as JsonWireValue | undefined;
+        if (typeof requestId !== "string" || !isBrokerStatusReport(report)) throw new Error("Invalid broker_status message");
+        const pending = this.pendingBrokerStatus.get(requestId);
+        if (!pending) return;
+        this.pendingBrokerStatus.delete(requestId);
+        pending.resolve(report);
+        break;
+      }
       case "supervisor_authorized": {
         const { requestId, capability, supervisorSessionId, childName } = brokerMessage;
         if (typeof requestId !== "string" || typeof capability !== "string"
@@ -861,7 +918,7 @@ export class IntercomClient extends EventEmitter {
 		const requestId = randomUUID();
 		const timeout = setTimeout(() => {
 			if (!this.pendingLists.delete(requestId)) return;
-			reject(new Error("List sessions timeout"));
+			void this.requestTimeout(socket, new Error("List sessions timeout")).then(reject);
 		}, 5000);
 		this.pendingLists.set(requestId, {
 			resolve: (directory) => {
@@ -893,7 +950,7 @@ export class IntercomClient extends EventEmitter {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         if (!this.pendingGroupLists.delete(requestId)) return;
-        reject(new Error("List groups timeout"));
+        void this.requestTimeout(socket, new Error("List groups timeout")).then(reject);
       }, GROUP_REQUEST_TIMEOUT_MS);
       this.pendingGroupLists.set(requestId, {
         resolve: (groups) => { clearTimeout(timeout); resolve(groups); },
@@ -909,6 +966,35 @@ export class IntercomClient extends EventEmitter {
     });
   }
 
+  /** The broker's own status, including multi-node routing; `undefined` from a broker older than `broker_status`. */
+  brokerStatus(): Promise<BrokerStatusReport | undefined> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    if (!this.brokerAnswersStatus) return Promise.resolve(undefined);
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        if (!this.pendingBrokerStatus.delete(requestId)) return;
+        reject(new Error("Broker status timeout"));
+      }, GROUP_REQUEST_TIMEOUT_MS);
+      this.pendingBrokerStatus.set(requestId, {
+        resolve: (report) => { clearTimeout(timeout); resolve(report); },
+        reject: (error) => { clearTimeout(timeout); reject(error); },
+      });
+      try {
+        writeMessage(socket, { type: "broker_status", requestId });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingBrokerStatus.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
+
   joinGroup(group: string): Promise<string[]> {
     return this.updateMembership("join_group", group);
   }
@@ -928,7 +1014,7 @@ export class IntercomClient extends EventEmitter {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         if (!this.pendingMemberships.delete(requestId)) return;
-        reject(new Error("Membership update timeout"));
+        void this.requestTimeout(socket, new Error("Membership update timeout")).then(reject);
       }, GROUP_REQUEST_TIMEOUT_MS);
       this.pendingMemberships.set(requestId, {
         resolve: (groups) => { clearTimeout(timeout); resolve(groups); },
@@ -958,7 +1044,7 @@ export class IntercomClient extends EventEmitter {
       const requestId = randomUUID();
       const timeout = setTimeout(() => {
         if (!this.pendingSupervisorAuthorizations.delete(requestId)) return;
-        reject(new Error("Supervisor authorization timeout"));
+        void this.requestTimeout(socket, new Error("Supervisor authorization timeout")).then(reject);
       }, 5000);
       this.pendingSupervisorAuthorizations.set(requestId, {
         resolve: (authorization) => { clearTimeout(timeout); resolve(authorization); },
@@ -1020,7 +1106,7 @@ export class IntercomClient extends EventEmitter {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         if (!this.pendingRestoringRecipientRequests.delete(requestId)) return;
-        reject(new Error("Restoring-recipient request timeout"));
+        void this.requestTimeout(socket, new Error("Restoring-recipient request timeout")).then(reject);
       }, RESTORING_RECIPIENT_REQUEST_TIMEOUT_MS);
       this.pendingRestoringRecipientRequests.set(requestId, {
         resolve: () => { clearTimeout(timeout); resolve(); },
@@ -1088,7 +1174,7 @@ export class IntercomClient extends EventEmitter {
 			const requestId = randomUUID();
 			const timeout = setTimeout(() => {
 				if (!this.pendingStageRouteRegistrations.delete(requestId)) return;
-				reject(new IntercomBrokerTimeoutError("Pending-stage route registration timeout"));
+				void this.requestTimeout(socket, new IntercomBrokerTimeoutError("Pending-stage route registration timeout")).then(reject);
 			}, PENDING_STAGE_ROUTE_ACK_TIMEOUT_MS);
 			this.pendingStageRouteRegistrations.set(requestId, {
 				resolve: () => {
@@ -1239,7 +1325,21 @@ export class IntercomClient extends EventEmitter {
     } catch (error) {
       return Promise.reject(toError(error));
     }
-    if (!acquired.owner) return acquired.attempt.promise;
+    let result = this.sendResults.get(acquired.attempt.promise);
+    if (result === undefined) {
+      result = acquired.attempt.promise.catch(async (error: Error) => {
+        if (error instanceof PendingSendTimeoutError) {
+          try {
+            throw await this.requestTimeout(socket, error);
+          } finally {
+            this.pendingSends.release(acquired.attempt);
+          }
+        }
+        throw error;
+      });
+      this.sendResults.set(acquired.attempt.promise, result);
+    }
+    if (!acquired.owner) return result;
     const message: Message = {
       id: messageId,
       timestamp: Date.now(),
@@ -1271,7 +1371,7 @@ export class IntercomClient extends EventEmitter {
     }
     const clearReplyTarget = () => { this.pendingReplyTargets.delete(acquired.attempt.attemptId); };
     void acquired.attempt.promise.then(clearReplyTarget, clearReplyTarget);
-    return acquired.attempt.promise;
+    return result;
   }
   updatePresence(updates: PresenceUpdates): boolean {
     if (this.disconnecting) {
@@ -1306,7 +1406,7 @@ export class IntercomClient extends EventEmitter {
       };
       const timeout = setTimeout(() => {
         if (!this.pendingPresence.delete(requestId)) return;
-        reject(new Error("Presence update timeout"));
+        void this.requestTimeout(socket, new Error("Presence update timeout")).then(reject);
       }, PRESENCE_ACK_TIMEOUT_MS);
       this.pendingPresence.set(requestId, {
         resolve: wrappedResolve,

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

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import net from "node:net";
+import type { SqliteExecutor } from "@bastani/atomic/storage";
+import type { BrokerStatusReport } from "../types.js";
+import { describeMultiNodeStatus, isBrokerStatusReport } from "./broker-status.js";
+import { createMessageReader, type JsonWireValue, writeMessage } from "./framing.js";
+import { BROKER_LEASE_STALE_AFTER_MS } from "./multinode-state-store.js";
+import { getBrokerPidPath, getBrokerSocketPath } from "./paths.js";
+import {
+	describeSharedStorage,
+	readSharedStorageSetting,
+	sharedStorageDigest,
+	sharedStorageSettingSource,
+} from "./shared-storage-setting.js";
+import { readLiveBrokerNodes } from "./sql-lease-store.js";
+
+/**
+ * Broker control for the Atomic CLI (`atomic intercom restart`, `atomic storage status`): it asks the agent
+ * directory's running broker about itself, or to shut down, over the broker's own socket, without registering a
+ * session. The CLI loads this module from the bundled Intercom package.
+ */
+
+export { describeMultiNodeStatus };
+
+/** How long a control request waits for its answer; a status report may wait up to 2 s for the shared database. */
+export const BROKER_CONTROL_TIMEOUT_MS = 5_000;
+/** How long `restartIntercomBroker` waits for the old broker to exit; its multi-node close is bounded at 2 s. */
+export const BROKER_STOP_TIMEOUT_MS = 10_000;
+/** How long `restartIntercomBroker` waits for a reconnecting session to start a new broker (first retry after 1 s). */
+export const BROKER_RECONNECT_TIMEOUT_MS = 15_000;
+const POLL_INTERVAL_MS = 100;
+
+export type BrokerQuery =
+	| { readonly state: "stopped" }
+	| { readonly state: "running"; readonly report: BrokerStatusReport }
+	/** A broker older than `broker_status`: it answers on its socket but drops a connection that asks. */
+	| { readonly state: "legacy"; readonly pid?: number };
+
+/** The shared storage a broker started now from this environment would read: what `broker_status` compares with. */
+export interface ExpectedBrokerStorage {
+	readonly digest: string;
+	readonly source: "env" | "settings";
+	readonly adapter: string;
+	readonly prefix?: string;
+}
+
+export type RestartOutcome =
+	| { readonly status: "not-running" }
+	/** Stopped, and no broker came back: no session was connected, or none reconnected in time. */
+	| { readonly status: "stopped"; readonly previous: { readonly pid: number; readonly sessions?: number } }
+	| {
+			readonly status: "restarted";
+			readonly previous: { readonly pid: number; readonly sessions?: number };
+			readonly current: Exclude<BrokerQuery, { state: "stopped" }>;
+	  };
+
+type ControlReply = { readonly connected: false } | { readonly connected: true; readonly reply?: JsonWireValue };
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Send one control frame and wait for the reply of `replyType`; a broker that closes without one yields no reply. */
+function controlRequest(
+	socketPath: string,
+	type: "broker_status" | "shutdown",
+	replyType: "broker_status" | "shutdown_ack",
+	timeoutMs: number,
+): Promise<ControlReply> {
+	return new Promise((resolve) => {
+		const requestId = randomUUID();
+		const socket = net.connect(socketPath);
+		let connected = false;
+		let settled = false;
+		const finish = (result: ControlReply): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			resolve(result);
+		};
+		const timer = setTimeout(() => finish(connected ? { connected } : { connected: false }), timeoutMs);
+		socket.on("connect", () => {
+			connected = true;
+			writeMessage(socket, { type, requestId });
+		});
+		socket.on(
+			"data",
+			createMessageReader(
+				(message) => {
+					if (
+						typeof message === "object" &&
+						message !== null &&
+						!Array.isArray(message) &&
+						message.type === replyType &&
+						message.requestId === requestId
+					)
+						finish({ connected: true, reply: message });
+				},
+				() => finish({ connected }),
+			),
+		);
+		socket.on("error", () => finish(connected ? { connected } : { connected: false }));
+		socket.on("close", () => finish(connected ? { connected } : { connected: false }));
+	});
+}
+
+function readBrokerPid(agentDir: string): number | undefined {
+	try {
+		const pid = Number.parseInt(readFileSync(getBrokerPidPath(agentDir), "utf8").trim(), 10);
+		return Number.isFinite(pid) ? pid : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Ask the agent directory's broker for its status. */
+export async function queryIntercomBroker(
+	agentDir: string,
+	timeoutMs: number = BROKER_CONTROL_TIMEOUT_MS,
+): Promise<BrokerQuery> {
+	const answer = await controlRequest(
+		getBrokerSocketPath(process.platform, agentDir),
+		"broker_status",
+		"broker_status",
+		timeoutMs,
+	);
+	if (!answer.connected) return { state: "stopped" };
+	const reply = answer.reply;
+	if (typeof reply === "object" && reply !== null && !Array.isArray(reply) && isBrokerStatusReport(reply.report)) {
+		return { state: "running", report: reply.report };
+	}
+	const pid = readBrokerPid(agentDir);
+	// Windows can briefly accept a named-pipe connection after its broker has terminated.
+	if (pid !== undefined && !isProcessAlive(pid)) return { state: "stopped" };
+	return pid === undefined ? { state: "legacy" } : { state: "legacy", pid };
+}
+
+/** The shared selection a broker started from this environment and agent directory would read, if any. */
+export function expectedBrokerStorage(
+	agentDir: string,
+	env: NodeJS.ProcessEnv = process.env,
+): ExpectedBrokerStorage | undefined {
+	const setting = readSharedStorageSetting(agentDir, env);
+	if (setting === undefined) return undefined;
+	return { digest: sharedStorageDigest(setting), source: sharedStorageSettingSource(env), ...describeSharedStorage(setting) };
+}
+
+/** Host names of the brokers live in a shared database, without creating Intercom's tables. */
+export function readLiveBrokers(database: SqliteExecutor, prefix: string | undefined): Promise<string[] | undefined> {
+	return readLiveBrokerNodes(database, prefix, BROKER_LEASE_STALE_AFTER_MS);
+}
+
+export interface RestartOptions {
+	readonly stopTimeoutMs?: number;
+	readonly reconnectTimeoutMs?: number;
+	/** Progress lines, for example `Stopping the Intercom broker (pid 123, 2 sessions)`. */
+	readonly onProgress?: (line: string) => void;
+}
+
+/**
+ * Restart the agent directory's broker so it reads the current storage selection: ask it to shut down (a broker
+ * older than this request gets SIGTERM, which it handles the same way), wait for it to exit, then wait for its
+ * sessions to reconnect, which starts a new broker. Without connected sessions the next session starts one.
+ */
+export async function restartIntercomBroker(agentDir: string, options: RestartOptions = {}): Promise<RestartOutcome> {
+	const stopTimeoutMs = options.stopTimeoutMs ?? BROKER_STOP_TIMEOUT_MS;
+	const reconnectTimeoutMs = options.reconnectTimeoutMs ?? BROKER_RECONNECT_TIMEOUT_MS;
+	const before = await queryIntercomBroker(agentDir);
+	if (before.state === "stopped") return { status: "not-running" };
+	const pid = before.state === "running" ? before.report.pid : before.pid;
+	if (pid === undefined) {
+		throw new Error(`The Intercom broker answers, but ${getBrokerPidPath(agentDir)} does not name its process.`);
+	}
+	const sessions = before.state === "running" ? before.report.sessions : undefined;
+	const previous = sessions === undefined ? { pid } : { pid, sessions };
+	options.onProgress?.(
+		`Stopping the Intercom broker (pid ${pid}${sessions === undefined ? "" : `, ${sessions} session${sessions === 1 ? "" : "s"} connected`}).`,
+	);
+	const answer =
+		before.state === "running"
+			? await controlRequest(
+					getBrokerSocketPath(process.platform, agentDir),
+					"shutdown",
+					"shutdown_ack",
+					BROKER_CONTROL_TIMEOUT_MS,
+				)
+			: undefined;
+	if (answer === undefined || !answer.connected || answer.reply === undefined) {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+		}
+	}
+	const stopDeadline = Date.now() + stopTimeoutMs;
+	while (isProcessAlive(pid)) {
+		if (Date.now() >= stopDeadline) {
+			throw new Error(`The Intercom broker (pid ${pid}) did not exit within ${Math.round(stopTimeoutMs / 1000)} s.`);
+		}
+		await sleep(POLL_INTERVAL_MS);
+	}
+	if (sessions === 0) return { status: "stopped", previous };
+	options.onProgress?.("Stopped. Waiting for its sessions to reconnect and start a new broker.");
+	const reconnectDeadline = Date.now() + reconnectTimeoutMs;
+	let current: BrokerQuery = { state: "stopped" };
+	while (Date.now() < reconnectDeadline) {
+		current = await queryIntercomBroker(agentDir);
+		const settled =
+			current.state === "legacy" || (current.state === "running" && current.report.multiNode.status !== "starting");
+		if (settled) break;
+		await sleep(POLL_INTERVAL_MS * 2);
+	}
+	return current.state === "stopped" ? { status: "stopped", previous } : { status: "restarted", previous, current };
+}

package/dist/builtin/intercom/broker/multinode-router.ts

@@ -1,7 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
-import { join } from "node:path";
 import { normalizeGroup } from "../group.js";
 import { isAgentRecipient, NON_AGENT_RECIPIENT_REFUSAL, TERMINAL_CHILD_ASK_REFUSAL } from "../recipient-purpose.js";
 import { DELIVERED_MESSAGE_TTL_MS, RECIPIENT_RECEIPT_TIMEOUT_MS } from "../retry-policy.js";
@@ -34,7 +32,6 @@ import {
 	type RestoringReservationLease,
 	reservationKeyFor,
 } from "./multinode-state-store.js";
-import { BROKER_STORAGE_ENV } from "./paths.js";
 import type { PendingQuestionIndex } from "./pending-question-index.js";
 import { UNCERTAIN_RECEIPT_REASON } from "./recipient-receipts.js";
 import { RESTORING_RECIPIENT_HOLD_MS, restoringRecipientRetryReason } from "./restoring-recipients.js";
@@ -49,6 +46,8 @@ import type { BrokerOutboundFrame } from "./socket-writes.js";
 import type { SupervisorChannelCache } from "./supervisor-channel.js";
 import type { WakeUpBus, WakeUpEvent, WakeUpSubscription } from "./wake-up-bus.js";
 
+export { readSharedStorageSetting } from "./shared-storage-setting.js";
+
 /**
  * Multi-node S5 (specs/2026-10-19-intercom-multi-node.md §4–§8, §14): routes sends to sessions hosted by other
  * brokers through the shared state, and delivers the shared outbox to this broker's own sessions. Local delivery
@@ -91,39 +90,6 @@ const MAX_SUPERSEDED_HOPS = 8;
 export const KNOWN_SESSION_REFRESH_INTERVAL_MS = 60 * 60 * 1000;
 const TARGET_GROUP_REFUSAL = "Target session is in a different intercom group";
 
-/**
- * The raw shared `storage` selection, read without the host package so the broker stays self-contained: the
- * selection the launching process handed this broker in `ATOMIC_STORAGE` (its `--storage`, `--storage-file` or own
- * `ATOMIC_STORAGE`), otherwise the top-level `storage` value of the agent directory's settings. Relative paths in
- * either resolve against the agent directory's parent, as for sessions and the journal. `undefined` leaves
- * multi-node routing off: no selection, a per-process selection that is not a JSON object (the launching process
- * validated it; settings are never consulted instead), and the selections the storage layer reads as in-memory
- * (`memory: true` without a path, or `path: ":memory:"`), which no other broker can share. `path: ""` is not one of
- * them: it selects the default storage file.
- */
-export function readSharedStorageSetting(
-	agentDir: string,
-	env: NodeJS.ProcessEnv = process.env,
-): Record<string, unknown> | undefined {
-	const processSelection = env[BROKER_STORAGE_ENV];
-	let parsed: unknown;
-	try {
-		parsed =
-			processSelection === undefined || processSelection.length === 0
-				? (JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8")) as Record<string, unknown>).storage
-				: JSON.parse(processSelection);
-	} catch {
-		return undefined;
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
-	const selection = parsed as Record<string, unknown>;
-	if (selection.adapter === undefined) {
-		if (selection.memory === true && !selection.path) return undefined;
-		if (selection.path === ":memory:") return undefined;
-	}
-	return selection;
-}
-
 /** What the broker uses of `open-broker-state.ts`, which it loads lazily (replaceable in tests). */
 export interface BrokerStateOpener<Source> {
 	resolveBrokerStateSource(
@@ -139,9 +105,9 @@ export type MultiNodeStartup<Source> =
 
 /**
  * Decide whether a top-level `storage` value gives this broker a shared database. Multi-node routing is off, and
- * Intercom behaves exactly as a single-node broker, unless it does: also when the host storage module cannot be
- * loaded (a standalone binary) or the selection cannot be resolved to a database. Only a selection that resolved to a
- * database whose connection then fails makes cross-node sends fail explicitly.
+ * Intercom behaves exactly as a single-node broker, unless it does: also when the host storage module or the adapter
+ * cannot be loaded, or the selection cannot be resolved to a database. Only a selection that resolved to a database
+ * whose connection then fails makes cross-node sends fail explicitly.
  */
 export async function resolveMultiNodeStartup<Source>(
 	setting: Record<string, unknown>,
@@ -490,6 +456,33 @@ export class MultiNodeRouter {
 		});
 	}
 
+	/**
+	 * The host names of the other brokers whose membership lease is live, for status reports. `undefined` when the
+	 * database fails or does not answer within `REMOTE_SESSIONS_BOUND_MS`.
+	 */
+	peerBrokers(): Promise<string[] | undefined> {
+		if (this.closed) return Promise.resolve(undefined);
+		return new Promise((resolve) => {
+			const bound = setTimeout(() => resolve(undefined), REMOTE_SESSIONS_BOUND_MS);
+			bound.unref?.();
+			void this.state.leases.listLive("broker", BROKER_LEASE_STALE_AFTER_MS).then(
+				(live) => {
+					clearTimeout(bound);
+					resolve(
+						live.flatMap((lease) =>
+							lease.subject.kind === "broker" && lease.holderId !== this.brokerId ? [lease.subject.nodeId] : [],
+						),
+					);
+				},
+				(error: Error) => {
+					clearTimeout(bound);
+					this.report(error);
+					resolve(undefined);
+				},
+			);
+		});
+	}
+
 	// ---------------------------------------------------------------------------------------------------------
 	// Restoring reservations (§5.7): mirror this broker's reservations so senders on any host hold their sends.
 

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

@@ -75,6 +75,10 @@ export function getBrokerLogPath(agentDir: string = getAgentDir()): string {
   return join(getIntercomDirPath(agentDir), "broker.log");
 }
 
+export function getBrokerWatchdogLogPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker-watchdog.log");
+}
+
 export function getBrokerSocketPath(
   platform: NodeJS.Platform = process.platform,
   agentDir: string = getAgentDir(),