@bastani/atomic 0.9.54-alpha.1 → 0.9.55-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.55] - 2026-10-30
+
+### Fixed
+
+- Fixed a session write failing, or the next write waiting up to ten seconds, on Windows when the session lock directory could not be removed at once because another program, such as a virus scanner or file indexer, held it. The release is now retried, and a lock Atomic still cannot remove is cleared by the next write instead of waiting to go stale
+
+## [0.9.55-alpha.1] - 2026-10-30
+
+### Fixed
+
+- Fixed a session write failing, or the next write waiting up to ten seconds, on Windows when the session lock directory could not be removed at once because another program, such as a virus scanner or file indexer, held it. The release is now retried, and a lock Atomic still cannot remove is cleared by the next write instead of waiting to go stale
+
 ## [0.9.54] - 2026-10-29
 
 Fixes from upstream pi after 1.4.0: packages, Windows paths and start-up.

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.55] - 2026-10-30
+
+### Fixed
+
+- Intercom no longer fails to start on a busy machine or with an empty jiti cache because the broker was still starting. A new broker now gets 30 seconds, not 5, to answer on its socket. That is sized from measured start-up: 0.5 s on an idle machine, 2.6 s with five processes per core, and 8.7 s, 15 s and 28 s with an empty jiti cache at five, nine and seventeen. `brokerStartupTimeoutMs` in the Intercom `config.json` changes it, and the `Broker failed to start within timeout` error now names that setting. On Windows, a broker that crashes during start-up is reported as soon as it exits, with its log, instead of after that whole budget: the broker writes its own pid to `broker.starting` in the Intercom directory as its first act, and the session that spawned it watches that process. Only a broker that is alive and not yet listening is waited for the full budget.
+- A session that connects as the broker retires, whether idle for its window, shut down or replaced, no longer fails with `Connection closed before registration` or `connect ENOENT`. A broker that is closing answers a registration with `broker_retiring` instead of accepting a session it is about to drop, including one still waiting for its multi-node presence write when the shutdown begins. A connection that ended before the broker answered, with nothing answering on its socket any more, is a recoverable disconnect. The session spawns the replacement broker and registers again for up to ten seconds, so a child session's launch and a workflow stage's warm-up no longer fail on the race.
+
+## [0.9.55-alpha.1] - 2026-10-30
+
+### Fixed
+
+- Intercom no longer fails to start on a busy machine or with an empty jiti cache because the broker was still starting. A new broker now gets 30 seconds, not 5, to answer on its socket. That is sized from measured start-up: 0.5 s on an idle machine, 2.6 s with five processes per core, and 8.7 s, 15 s and 28 s with an empty jiti cache at five, nine and seventeen. `brokerStartupTimeoutMs` in the Intercom `config.json` changes it, and the `Broker failed to start within timeout` error now names that setting. On Windows, a broker that crashes during start-up is reported as soon as it exits, with its log, instead of after that whole budget: the broker writes its own pid to `broker.starting` in the Intercom directory as its first act, and the session that spawned it watches that process. Only a broker that is alive and not yet listening is waited for the full budget.
+- A session that connects as the broker retires, whether idle for its window, shut down or replaced, no longer fails with `Connection closed before registration` or `connect ENOENT`. A broker that is closing answers a registration with `broker_retiring` instead of accepting a session it is about to drop, including one still waiting for its multi-node presence write when the shutdown begins. A connection that ended before the broker answered, with nothing answering on its socket any more, is a recoverable disconnect. The session spawns the replacement broker and registers again for up to ten seconds, so a child session's launch and a workflow stage's warm-up no longer fail on the race.
+
 ## [0.9.48] - 2026-10-27
 
 ### Fixed

package/dist/builtin/intercom/README.md

@@ -425,6 +425,7 @@ The default `npx --no-install tsx` pair is a compatibility sentinel: intercom re
 |---------|---------|-------------|
 | `brokerCommand` | `"npx"` | Command used to start the local broker process; the default sentinel is hardened internally to avoid PATH lookup |
 | `brokerArgs` | `["--no-install", "tsx"]` | Arguments passed to `brokerCommand` before the broker script path |
+| `brokerStartupTimeoutMs` | `30000` | How long a session waits for a newly spawned broker to answer on its socket, in milliseconds (at least `1000`). A broker loads its modules through jiti, which takes about 0.5 s on an idle machine and several seconds on a busy one or with an empty jiti cache (the first start after a reboot); raise it if Intercom start-up reports `Broker failed to start within timeout` on a very slow machine |
 | `confirmSend` | false | Show a confirmation dialog before non-reply sends from an interactive session with UI |
 | `replyHint` | true | Include reply instruction in incoming messages |
 | `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
@@ -514,7 +515,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. `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.
+**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. A session that connects just as the broker retires does not fail: a broker that is closing refuses a registration with a `broker_retiring` reply, and a connection that is reset or ended before the broker answered, with nothing left answering on the socket, means the same. Either way the session spawns the replacement broker and registers again, retrying for up to ten seconds. `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/announce-on-import.ts

@@ -0,0 +1,5 @@
+import { announceBrokerStart } from "./start-announcement.js";
+
+// Imported second by broker.ts, straight after the stderr cap and before any module that does real work, so the pid is
+// announced before the broker's module graph loads: a crash while loading is then a crash the parent can see.
+announceBrokerStart();

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

@@ -1,6 +1,8 @@
 // MUST stay first: ESM evaluates static dependencies before the importer's body, so this is the
 // only position from which the stderr cap covers the other modules' own initialization.
 import "./bounded-stderr-install.js";
+// MUST stay second: it announces the broker's pid before the rest of the module graph loads (see start-announcement.ts).
+import "./announce-on-import.js";
 import net from "net";
 import { chmodSync, writeFileSync, unlinkSync, mkdirSync, readFileSync, statSync } from "fs";
 import { dirname } from "path";
@@ -11,6 +13,7 @@ import {
   flushHeldWrites,
   type HeldWrite,
   holdWrites,
+  isHoldingWrites,
   releaseHeldWrites,
   writeMessageIfOpen,
   writeMessageWithOutcome,
@@ -19,6 +22,7 @@ import { boundWorkflowPossibleStageRow } from "../workflow-delivery-states.js";
 import { isSocketAnswering } from "./socket-liveness.js";
 import { acquireSocketReplacementLock } from "./socket-replacement-lock.js";
 import { startBrokerWatchdog } from "./watchdog.js";
+import { retractBrokerStartAnnouncement } from "./start-announcement.js";
 import {
 	getBrokerDeliveredMessagesPath,
 	getBrokerPidPath,
@@ -85,6 +89,7 @@ import { type ReceiptSender, RecipientReceipts, UNCERTAIN_RECEIPT_REASON } from
 import { matchStagePathSegments } from "../workflow-stage-path-matching.js";
 import { DELIVERED_MESSAGE_TTL_MS } from "../retry-policy.js";
 import { isAgentRecipient } from "../recipient-purpose.js";
+import { BROKER_RETIRING_CODE, BROKER_RETIRING_REASON } from "../recoverable-disconnect.js";
 import {
 	LIVE_WORKFLOW_STAGE_ROUTE_REFUSAL_REASONS,
 	type LiveWorkflowStageRouteRefusalCode,
@@ -102,6 +107,12 @@ 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;
+/** What a registration is answered with once this broker is closing: the client spawns the replacement and registers again. */
+const RETIRING_REFUSAL = {
+  type: "registration_failed",
+  reason: BROKER_RETIRING_REASON,
+  code: BROKER_RETIRING_CODE,
+} as const;
 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>> = {
@@ -393,6 +404,8 @@ class IntercomBroker {
       if (process.platform !== "win32") this.boundSocketInode = statSync(SOCKET_PATH).ino;
       releaseReplacementLock();
       writeFileSync(PID_PATH, String(process.pid));
+      // The pid file takes over from the start-up announcement the moment the broker answers.
+      retractBrokerStartAnnouncement();
       console.log(`Intercom broker started (pid: ${process.pid})`);
       startBrokerWatchdog(SOCKET_PATH, this.instanceId, getBrokerWatchdogLogPath());
       this.lastConnectionAt = performance.now();
@@ -1627,6 +1640,13 @@ class IntercomBroker {
 
     switch (clientMessage.type) {
       case "register": {
+        if (this.shuttingDown) {
+          // A client that connected while this broker was closing (a multi-node broker takes up to two seconds to give
+          // its leases up) learns it lost the race and spawns the replacement, instead of finding its socket reset.
+          writeMessageIfOpen(socket, RETIRING_REFUSAL);
+          socket.end();
+          return;
+        }
         if (!isSessionRegistration(clientMessage.session)) {
           throw new Error("Invalid register message");
         }
@@ -2539,6 +2559,14 @@ class IntercomBroker {
     console.log("Broker shutting down");
 
     for (const session of this.sessions.values()) {
+      // A registration still waiting for its presence write has been taken but not answered, and its frames are held
+      // behind the `registered` it is owed. It gets the same refusal a registration arriving now gets: the held
+      // frames go (each confirmed write reports `false`, as for a session that is gone) and the refusal is written
+      // before the socket ends, so its client registers with the replacement instead of finding the socket closed.
+      if (isHoldingWrites(session.socket)) {
+        discardHeldWrites(releaseHeldWrites(session.socket));
+        writeMessageIfOpen(session.socket, RETIRING_REFUSAL);
+      }
       session.socket.end();
     }
     this.sessions.clear();

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

@@ -24,7 +24,13 @@ import { buildSendSignature, PendingSendRegistry, PendingSendTimeoutError } from
 import { readSubagentMessageSource } from "../source-ownership.js";
 import { isMessage, isSessionInfo } from "./client-message-validation.js";
 import { normalizeGroups } from "../group.js";
-import { IntercomBrokerTimeoutError, IntercomClientDisconnectedError } from "../recoverable-disconnect.js";
+import {
+	BROKER_RETIRING_CODE,
+	IntercomBrokerRetiringError,
+	IntercomBrokerTimeoutError,
+	IntercomClientDisconnectedError,
+} from "../recoverable-disconnect.js";
+import { isSocketAnswering } from "./socket-liveness.js";
 import { IntercomLiveRouteRefusedError, isLiveWorkflowStageRouteRefusalCode } from "../live-route-refusal.js";
 import { SEND_RESPONSE_TIMEOUT_MS } from "../retry-policy.js";
 
@@ -64,6 +70,38 @@ function isBacklogRefusal(error: Error): boolean {
 	const code = (error as NodeJS.ErrnoException).code;
 	return code === "ECONNREFUSED" || code === "EAGAIN";
 }
+
+/** The broker closed the connection before it answered the registration. */
+class ConnectionClosedBeforeRegistrationError extends Error {
+	constructor() {
+		super("Connection closed before registration");
+		this.name = "ConnectionClosedBeforeRegistrationError";
+	}
+}
+
+/**
+ * Whether a failure before the broker answered `register` is what a broker that retired leaves behind: the socket path
+ * is gone (`ENOENT`), or the connection was reset or ended without an answer. A refusal the kernel gives a full listen
+ * backlog (`ECONNREFUSED`, `EAGAIN`) is not: those are retried above and still reject as before.
+ */
+function isLostBrokerSignature(error: Error): boolean {
+	if (error instanceof ConnectionClosedBeforeRegistrationError) return true;
+	const code = (error as NodeJS.ErrnoException).code;
+	return code === "ENOENT" || code === "ECONNRESET" || code === "EPIPE";
+}
+
+/**
+ * A failure before registration, classified: when it has the signature of a lost broker and nothing answers on the
+ * broker socket any more, the broker retired first and the failure is recoverable by spawning its replacement. A broker
+ * that still answers closed the connection for its own reasons (a refused or malformed registration), so the failure
+ * stays what it was.
+ */
+async function classifyRegistrationFailure(error: Error): Promise<Error> {
+	if (!isLostBrokerSignature(error) || (await isSocketAnswering(BROKER_SOCKET))) return error;
+	return new IntercomBrokerRetiringError(`Intercom broker went away before it registered this session: ${error.message}`, {
+    cause: error,
+  });
+}
 /** Extra wait past a broker hold, so the broker's own outcome for a held send always arrives first (#3760). */
 const HELD_SEND_GRACE_MS = 5000;
 
@@ -409,7 +447,12 @@ export class IntercomClient extends EventEmitter {
           return;
         } catch (error) {
           if (attempt.signal.aborted) throw connectAborted();
-          if (!(error instanceof Error) || !isBacklogRefusal(error) || retry >= BROKER_BACKLOG_RETRIES) throw error;
+          if (!(error instanceof Error)) throw error;
+          if (!isBacklogRefusal(error) || retry >= BROKER_BACKLOG_RETRIES) {
+            const classified = await classifyRegistrationFailure(error);
+            if (attempt.signal.aborted) throw connectAborted();
+            throw classified;
+          }
           const backoff = BROKER_BACKLOG_RETRY_BASE_MS * 2 ** retry;
           await abortableDelay(backoff * (0.5 + Math.random() / 2), attempt.signal);
         }
@@ -496,7 +539,7 @@ export class IntercomClient extends EventEmitter {
           this.emit("disconnected", disconnectError);
         }
         if (wasConnecting) {
-          reject(new Error("Connection closed before registration"));
+          reject(new ConnectionClosedBeforeRegistrationError());
         }
       };
 
@@ -645,6 +688,8 @@ export class IntercomClient extends EventEmitter {
         // reason as an ordinary, non-recoverable error.
         const refusal = isLiveWorkflowStageRouteRefusalCode(brokerMessage.code)
           ? new IntercomLiveRouteRefusedError(brokerMessage.code, brokerMessage.reason)
+          : brokerMessage.code === BROKER_RETIRING_CODE
+          ? new IntercomBrokerRetiringError(brokerMessage.reason)
           : new Error(brokerMessage.reason);
         if (this._sessionId === null) {
           // Still registering: `connect()` owns the failure and its own cleanup.

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

@@ -75,6 +75,15 @@ export function getBrokerLogPath(agentDir: string = getAgentDir()): string {
   return join(getIntercomDirPath(agentDir), "broker.log");
 }
 
+/**
+ * Where a broker announces its real pid as its first act, for a parent that cannot watch the process it spawned (the
+ * Windows launcher hides it); see `start-announcement.ts`. Written once at start-up and removed once the broker listens,
+ * never after the broker ends.
+ */
+export function getBrokerStartAnnouncementPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker.starting");
+}
+
 export function getBrokerWatchdogLogPath(agentDir: string = getAgentDir()): string {
   return join(getIntercomDirPath(agentDir), "broker-watchdog.log");
 }

package/dist/builtin/intercom/broker/socket-writes.ts

@@ -129,6 +129,11 @@ export function holdWrites(socket: net.Socket): void {
 	if (!heldWrites.has(socket)) heldWrites.set(socket, []);
 }
 
+/** Whether `socket`'s frames are being held, that is, its deferred `registered` has not been written. */
+export function isHoldingWrites(socket: net.Socket): boolean {
+	return heldWrites.has(socket);
+}
+
 /** Stop holding frames for `socket`; returns the frames held, in the order they were written. */
 export function releaseHeldWrites(socket: net.Socket): HeldWrite[] {
 	const held = heldWrites.get(socket) ?? [];

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

@@ -1,12 +1,21 @@
 import { spawn } from "child_process";
+import { randomUUID } from "crypto";
 import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { isSocketAnswering } from "./socket-liveness.js";
+import { BROKER_READY_TIMEOUT_MS } from "./startup-timeout.js";
+import {
+  BROKER_ANNOUNCE_PATH_ENV,
+  BROKER_ANNOUNCE_TOKEN_ENV,
+  type BrokerStartAnnouncement,
+  readBrokerStartAnnouncement,
+} from "./start-announcement.js";
 import { createChildProcessEnvironment, isBunBinary, processSharedStorageSelection } from "@bastani/atomic";
 import {
   BROKER_STORAGE_ENV,
+  getBrokerStartAnnouncementPath,
   getBrokerLogPath,
   getBrokerPidPath,
   getBrokerSocketPath,
@@ -37,6 +46,7 @@ const BROKER_SOCKET = getBrokerSocketPath();
 const BROKER_PID = getBrokerPidPath();
 const BROKER_SPAWN_LOCK = getBrokerSpawnLockPath();
 const BROKER_LOG = getBrokerLogPath();
+const BROKER_START_ANNOUNCEMENT = getBrokerStartAnnouncementPath();
 
 function ensurePrivateDirectory(path: string): void {
   mkdirSync(path, { recursive: true, mode: 0o700 });
@@ -58,8 +68,7 @@ export const BROKER_POLL_INITIAL_INTERVAL_MS = 10;
 /** Upper bound for the readiness poll interval, matching the historic flat poll. */
 export const BROKER_POLL_MAX_INTERVAL_MS = 100;
 
-/** How long one spawn attempt waits for the broker socket to answer. */
-export const BROKER_READY_TIMEOUT_MS = 5000;
+export { BROKER_READY_TIMEOUT_MS };
 
 /** Backstop only: a spawn lock normally ends when its broker is ready or the processes it names are gone. */
 export const BROKER_SPAWN_LOCK_MAX_AGE_MS = 60_000;
@@ -175,6 +184,12 @@ export function getWindowsBrokerCommandLine(
  * dropped instead: launching correctly without a captured log beats launching wrongly with one.
  * A `%` reaches here only from a custom `brokerCommand`/`brokerArgs` or an install path that
  * contains one, and the direct (non-launcher) Windows path still captures stderr normally.
+ *
+ * Nothing may follow the broker in this chain: after the broker's process ends, the resident `cmd.exe` must do no
+ * file I/O, because tests, `atomic intercom restart` and users remove the intercom directory the moment the broker
+ * is gone, and a file the chain creates there then fails that removal (the marker an earlier version appended made
+ * every Windows test that kills a broker and removes its directory fail with ENOTEMPTY). The broker's own start-up
+ * announcement (`start-announcement.ts`) is how the parent learns that a broker it cannot watch has exited.
  */
 export function getWindowsStderrRedirectCommandLine(commandLine: string, logPath: string): string {
   if (commandLine.includes("%")) return commandLine;
@@ -247,10 +262,12 @@ export function getBrokerLaunchSpec(
  *
  * The broker routes through the shared storage this process was launched with (`--storage`,
  * `--storage-file` or `ATOMIC_STORAGE`), passed as `ATOMIC_STORAGE`; without one it reads settings.
+ * With `announcement` it also gets the file and token it announces its pid with (`start-announcement.ts`).
  */
 export function getBrokerSpawnOptions(
   extensionDir: string = EXTENSION_DIR,
   stderr: number | "ignore" = "ignore",
+  announcement?: BrokerStartAnnouncement,
 ): {
   detached: true;
   stdio: ["ignore", "ignore", number | "ignore"];
@@ -266,6 +283,9 @@ export function getBrokerSpawnOptions(
     env: createChildProcessEnvironment({
       NODE_NO_WARNINGS: "1",
       ...(storage === undefined ? {} : { [BROKER_STORAGE_ENV]: storage }),
+      ...(announcement === undefined
+        ? {}
+        : { [BROKER_ANNOUNCE_PATH_ENV]: announcement.path, [BROKER_ANNOUNCE_TOKEN_ENV]: announcement.token }),
     }),
     windowsHide: true,
   };
@@ -357,6 +377,17 @@ export async function spawnBrokerIfNeeded(
 
     const brokerPath = resolveBrokerEntrypoint(extensionDir);
     const launch = getBrokerLaunchSpec(brokerPath, brokerCommand, brokerArgs, extensionDir);
+    // The Windows launcher hides the broker's pid and exit, so there the broker announces its pid, which this watches.
+    // Elsewhere the child is the broker and its exit event says how it ended.
+    const announcement: BrokerStartAnnouncement | undefined =
+      launch.kind === "windows-launcher" ? { path: BROKER_START_ANNOUNCEMENT, token: randomUUID() } : undefined;
+    if (announcement !== undefined) {
+      try {
+        unlinkSync(announcement.path);
+      } catch {
+        // None left by an earlier broker, or not removable: its token is not this spawn's, so it is ignored.
+      }
+    }
     if (launch.kind === "windows-launcher") {
       writeWindowsHiddenLauncher(launch.launcherCommandLine, launch.launcherPath);
     }
@@ -371,7 +402,7 @@ export async function spawnBrokerIfNeeded(
     const logFd = launch.kind === "direct" ? openSync(BROKER_LOG, "a") : undefined;
     let child: ReturnType<typeof spawn>;
     try {
-      child = spawn(launch.command, launch.args, getBrokerSpawnOptions(extensionDir, logFd ?? "ignore"));
+      child = spawn(launch.command, launch.args, getBrokerSpawnOptions(extensionDir, logFd ?? "ignore", announcement));
     } finally {
       if (logFd !== undefined) closeSync(logFd);
     }
@@ -411,7 +442,10 @@ export async function spawnBrokerIfNeeded(
 
       child.once("error", onError);
       child.once("exit", onExit);
-      waitForBroker(readyTimeoutMs).then(() => {
+      waitForBroker(
+        readyTimeoutMs,
+        announcement === undefined ? undefined : () => readBrokerStartAnnouncement(announcement),
+      ).then(() => {
         cleanup();
         resolve();
       }, (error) => {
@@ -549,16 +583,34 @@ export function releaseSpawnLock(owner: string, lockPath: string = BROKER_SPAWN_
  * Poll the broker socket with a short initial interval and bounded exponential backoff.
  * Startup is tens of milliseconds, so the previous flat 100 ms sleep dominated it; the
  * overall timeout semantics are unchanged.
+ *
+ * `announcedPid` reports the pid of a broker this spawner cannot watch directly (behind the Windows launcher), once the
+ * broker has announced it. A broker whose pid is gone and that does not answer has crashed, and the wait ends at once:
+ * only a broker that is alive and not yet listening is waited for the whole budget.
  */
-export async function waitForBroker(timeoutMs = BROKER_READY_TIMEOUT_MS): Promise<void> {
+export async function waitForBroker(
+  timeoutMs = BROKER_READY_TIMEOUT_MS,
+  announcedPid?: () => number | undefined,
+): Promise<void> {
   const start = Date.now();
   let interval = BROKER_POLL_INITIAL_INTERVAL_MS;
   while (Date.now() - start < timeoutMs) {
     if (await checkSocketConnectable()) {
       return;
     }
+    const pid = announcedPid?.();
+    if (pid !== undefined && !isProcessAlive(pid)) {
+      // A broker that finds a live broker on the socket yields and exits; that one answering is a success.
+      if (await checkSocketConnectable()) return;
+      throw new Error(`Intercom broker exited before startup (pid ${pid})\n${describeBrokerLog()}`);
+    }
     await sleep(interval);
     interval = Math.min(interval * 2, BROKER_POLL_MAX_INTERVAL_MS);
   }
-  throw new Error(`Broker failed to start within timeout\n${describeBrokerLog()}`);
+  throw new Error(
+    `Broker failed to start within timeout (${timeoutMs} ms)\n`
+      + "The broker did not answer on its socket in time; it may still be starting, which a busy machine or an empty jiti "
+      + "cache slows. Try again, or raise `brokerStartupTimeoutMs` in the Intercom config.json (default "
+      + `${BROKER_READY_TIMEOUT_MS} ms).\n${describeBrokerLog()}`,
+  );
 }

package/dist/builtin/intercom/broker/start-announcement.ts

@@ -0,0 +1,77 @@
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+
+/**
+ * A spawned broker announces its real pid, so a parent that cannot watch the process it spawned can tell a broker that
+ * crashed during start-up from one that is still loading.
+ *
+ * On Windows the broker starts behind `wscript -> cmd -> node`: `wscript` returns at once and hides the pid, so without
+ * this the parent waits the whole start-up budget for a broker that died in its first second. The broker is the one
+ * process that knows its own pid, so it writes it (with the spawn's token) before it loads the rest of its modules, and
+ * the parent polls `process.kill(pid, 0)` on it. That is the whole mechanism, and deliberately nothing else: no process
+ * of the launcher chain writes anything once the broker has ended, because tests, `atomic intercom restart` and users
+ * remove the intercom directory as soon as the broker is gone, and a file created there at that moment fails the
+ * removal on Windows.
+ *
+ * The parent hands the broker the file and token through the environment, so a broker started any other way (a test,
+ * an older parent) announces nothing. The token ties a file to the spawn that asked for it: a broker that is retiring
+ * and a replacement that is starting never read each other's announcement as their own.
+ */
+export const BROKER_ANNOUNCE_PATH_ENV = "ATOMIC_INTERCOM_BROKER_ANNOUNCE_PATH";
+export const BROKER_ANNOUNCE_TOKEN_ENV = "ATOMIC_INTERCOM_BROKER_ANNOUNCE_TOKEN";
+
+/** The file and token one spawn asks its broker to announce itself with. */
+export interface BrokerStartAnnouncement {
+	readonly path: string;
+	readonly token: string;
+}
+
+/** Tokens go in the file and the environment unquoted, so only plain characters are accepted. */
+const TOKEN_PATTERN = /^[A-Za-z0-9-]+$/u;
+
+/** The announcement the environment asks this process for, or undefined when it asks for none. */
+function requested(env: NodeJS.ProcessEnv): BrokerStartAnnouncement | undefined {
+	const path = env[BROKER_ANNOUNCE_PATH_ENV];
+	const token = env[BROKER_ANNOUNCE_TOKEN_ENV];
+	if (!path || !token || !TOKEN_PATTERN.test(token)) return undefined;
+	return { path, token };
+}
+
+/** Broker side: write `<token> <pid>` where the parent asked. A failure to write must never keep the broker from starting. */
+export function announceBrokerStart(env: NodeJS.ProcessEnv = process.env, pid: number = process.pid): void {
+	const announcement = requested(env);
+	if (announcement === undefined) return;
+	try {
+		writeFileSync(announcement.path, `${announcement.token} ${pid}\n`, { mode: 0o600 });
+	} catch {
+		// The parent then waits out its start-up budget, as it did before broker announcements existed.
+	}
+}
+
+/** Broker side: take the announcement back once the broker listens, so none outlives the broker's start-up. */
+export function retractBrokerStartAnnouncement(env: NodeJS.ProcessEnv = process.env, pid: number = process.pid): void {
+	const announcement = requested(env);
+	if (announcement === undefined) return;
+	// Only the broker's own announcement: a stale file from another broker is the parent's to replace.
+	if (readBrokerStartAnnouncement(announcement) !== pid) return;
+	try {
+		unlinkSync(announcement.path);
+	} catch {
+		// Already gone, or held open by the parent's read; the next spawn replaces it.
+	}
+}
+
+/** Parent side: the pid this spawn's broker announced, or undefined until it has, or when the file is another spawn's. */
+export function readBrokerStartAnnouncement(announcement: BrokerStartAnnouncement): number | undefined {
+	let text: string;
+	try {
+		text = readFileSync(announcement.path, "utf-8");
+	} catch {
+		return undefined;
+	}
+	// A complete line only: a write still in progress is read as nothing yet.
+	if (!text.endsWith("\n")) return undefined;
+	const [token, pid, ...rest] = text.trim().split(/\s+/u);
+	if (token !== announcement.token || rest.length > 0) return undefined;
+	const parsed = Number(pid);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}

package/dist/builtin/intercom/broker/startup-timeout.ts

@@ -0,0 +1,23 @@
+/**
+ * How long one spawn attempt waits for a new broker to answer on its socket, unless `brokerStartupTimeoutMs` in the
+ * Intercom config says otherwise.
+ *
+ * A Node install starts the broker from `broker/broker.ts` through jiti, so the wait is the broker's own start-up,
+ * which scales with the CPU share it gets. Measured from spawn to the first answered connection (Linux, one broker,
+ * pinned to a core shared with busy loops):
+ *
+ * | jiti cache | idle   | 5 processes per core | 9 per core | 17 per core |
+ * | ---------- | ------ | -------------------- | ---------- | ----------- |
+ * | warm       | 0.49 s | 2.6 s                | 4.6 s      |             |
+ * | cold       | 1.57 s | 8.7 s                | 15.0 s     | 27.7 s      |
+ *
+ * jiti's cache lives in the temporary directory, so a cold cache is the first start after a reboot or on a
+ * throwaway CI machine. The previous 5 s covered only a warm cache on a busy host, so a loaded or freshly started
+ * machine failed Intercom start-up with a broker that was still starting. 30 s covers a cold cache at 17 processes
+ * per core. A broker that exits ends the wait at once (except behind the Windows launcher, which hides its pid), so a
+ * long budget delays only the report of a broker that stays alive without listening.
+ */
+export const BROKER_READY_TIMEOUT_MS = 30_000;
+
+/** The smallest `brokerStartupTimeoutMs` the config accepts: below this a broker cannot listen on any host. */
+export const MIN_BROKER_STARTUP_TIMEOUT_MS = 1_000;