@bastani/atomic 0.9.28-alpha.4 → 0.9.28-alpha.5

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Added
+
+- Added `fromSignal` to the `session_shutdown` event. It is `true` when a `quit` comes from a host `SIGTERM` or `SIGHUP` instead of Ctrl+D or `/quit`, and `runtimeHost.dispose({ fromSignal: true })` sets it for SDK hosts ([#3492](https://github.com/bastani-inc/atomic/issues/3492)).
+
+### Changed
+
+- `openai-decisions/gpt-6-luna` no longer has its own `/login` entry, so you do not need to sign in again. The classifier uses the API key saved for `openai-api`, then the one saved for `openai`, then `OPENAI_API_KEY`. A ChatGPT sign-in on `openai` cannot call the Decisions API and is not used, so the classifier stays unavailable until one of those keys exists. See [Classifier models](docs/models.md#use-classifier-models).
+
+### Fixed
+
+- Fixed the startup project trust prompt opening inside the fully painted interface. Atomic now shows the prompt on its own and paints the interface after you choose.
+- Fixed the "This project is not trusted" warning staying in the transcript after you trusted the project at the startup prompt. The warning still appears when you decline trust or leave the project untrusted.
+- Fixed Herdr restoring panes without their Atomic conversation after a Herdr restart. With Herdr 0.9.2 or newer, Atomic now reports `atomic --session <id>` (plus `--session-dir` for a custom session directory) so Herdr can reopen the same session in the same pane, and keeps it registered when Herdr or the system ends Atomic with `SIGTERM` or `SIGHUP`. Quitting with Ctrl+D or `/quit` still clears it, and older Herdr versions keep status reporting without restore ([#3492](https://github.com/bastani-inc/atomic/issues/3492)).
+
 ## [0.9.28-alpha.4] - 2026-10-07
 
 ### Added

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Fixed
+
+- Fixed a slow-starting intercom broker taking over a live broker's socket, which left a connected session unreachable by `intercom list` and `send`, so messages to it were silently not delivered ([#3505](https://github.com/bastani-inc/atomic/issues/3505)).
+
 ## [0.9.28-alpha.1] - 2026-10-05
 
 ### Fixed

package/dist/builtin/intercom/README.md

@@ -492,7 +492,8 @@ Runtime files live under the active agent directory. Atomic defaults to `~/.atom
 - `broker.pid` — Broker process ID
 - `delivered-messages.sqlite` — bounded durable authority containing keyed digests, never plaintext payloads
 - `delivered-messages.key` — random owner-only HMAC key paired with the authority database
-- `broker.spawn.lock` — Short-lived lock used to avoid duplicate auto-spawns
+- `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
 - `config.json` — User configuration
 
@@ -504,7 +505,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.
+**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.
 
 **`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.ts

@@ -2,14 +2,17 @@
 // only position from which the stderr cap covers the other modules' own initialization.
 import "./bounded-stderr-install.js";
 import net from "net";
-import { chmodSync, writeFileSync, unlinkSync, mkdirSync, readFileSync } from "fs";
+import { chmodSync, writeFileSync, unlinkSync, mkdirSync, readFileSync, statSync } from "fs";
 import { randomUUID } from "crypto";
 import { createMessageReader, type JsonWireValue } from "./framing.js";
 import { writeMessageIfOpen, writeMessageWithOutcome } from "./socket-writes.js";
+import { isSocketAnswering } from "./socket-liveness.js";
+import { acquireSocketReplacementLock } from "./socket-replacement-lock.js";
 import {
 	getBrokerDeliveredMessagesPath,
 	getBrokerPidPath,
 	getBrokerSocketPath,
+	getBrokerSocketReplacementLockPath,
 	getIntercomDirPath,
 } from "./paths.js";
 import type {
@@ -60,8 +63,17 @@ import {
 const INTERCOM_DIR = getIntercomDirPath();
 const SOCKET_PATH = getBrokerSocketPath();
 const PID_PATH = getBrokerPidPath();
+const SOCKET_REPLACEMENT_LOCK_PATH = getBrokerSocketReplacementLockPath();
 
 const PENDING_STAGE_MESSAGE_TIMEOUT_MS = 10_000;
+const LISTEN_ATTEMPTS = 5;
+const LISTEN_RETRY_DELAY_MS = 100;
+const SOCKET_OWNERSHIP_CHECK_MS = 1_000;
+
+function exitBecauseLiveBrokerOwnsSocket(): never {
+  console.error(`Intercom broker not started: a live broker already answers on ${SOCKET_PATH}`);
+  process.exit(0);
+}
 
 interface PendingStageRouteRegistration {
   readonly sessionId: string;
@@ -249,6 +261,7 @@ class IntercomBroker {
   private sessions = new Map<string, ConnectedSession>();
   private server: net.Server;
   private shutdownTimer: NodeJS.Timeout | null = null;
+  private boundSocketInode: number | undefined;
   private lastConnectionAt = performance.now();
   private deliveredMessages = new DeliveredMessageCache(
 	DELIVERED_MESSAGE_TTL_MS,
@@ -267,25 +280,82 @@ class IntercomBroker {
   constructor() {
     mkdirSync(INTERCOM_DIR, { recursive: true, mode: 0o700 });
     if (process.platform !== "win32") chmodSync(INTERCOM_DIR, 0o700);
-    if (process.platform !== "win32") {
-      try {
-        unlinkSync(SOCKET_PATH);
-      } catch {
-        // A clean startup has no stale socket to remove.
-      }
-    }
     this.server = net.createServer(this.handleConnection.bind(this));
   }
 
   start(): void {
+    this.listen(1);
+    process.on("SIGTERM", () => this.shutdown());
+    process.on("SIGINT", () => this.shutdown());
+  }
+
+  private listen(attempt: number, releaseReplacementLock: () => void = () => {}): void {
+    const onError = (error: NodeJS.ErrnoException) => {
+      releaseReplacementLock();
+      void this.recoverFromListenError(error, attempt);
+    };
+    this.server.once("error", onError);
     this.server.listen(SOCKET_PATH, () => {
+      this.server.off("error", onError);
+      if (process.platform !== "win32") this.boundSocketInode = statSync(SOCKET_PATH).ino;
+      releaseReplacementLock();
       writeFileSync(PID_PATH, String(process.pid));
       console.log(`Intercom broker started (pid: ${process.pid})`);
       this.lastConnectionAt = performance.now();
       this.scheduleShutdownCheck();
+      if (this.boundSocketInode !== undefined) this.watchSocketOwnership();
     });
-    process.on("SIGTERM", () => this.shutdown());
-    process.on("SIGINT", () => this.shutdown());
+  }
+
+  private ownsSocketPath(): boolean {
+    if (this.boundSocketInode === undefined) return process.platform === "win32";
+    try {
+      return statSync(SOCKET_PATH).ino === this.boundSocketInode;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * A broker whose socket path now leads to another broker can no longer be reached by new clients, so its sessions
+   * would be stranded. It shuts down instead, and its clients reconnect through broker.sock to the broker that owns it.
+   */
+  private watchSocketOwnership(): void {
+    const timer = setInterval(() => {
+      if (this.ownsSocketPath()) return;
+      clearInterval(timer);
+      console.error(`Intercom broker lost ${SOCKET_PATH} to another broker; shutting down so its sessions reconnect`);
+      this.shutdown();
+    }, SOCKET_OWNERSHIP_CHECK_MS);
+    timer.unref();
+  }
+
+  /** Take over only a stale socket: a path a live broker answers on is never unlinked. */
+  private async recoverFromListenError(error: NodeJS.ErrnoException, attempt: number): Promise<void> {
+    if (error.code === "EADDRINUSE" && (await isSocketAnswering(SOCKET_PATH))) exitBecauseLiveBrokerOwnsSocket();
+    if (error.code !== "EADDRINUSE" || attempt >= LISTEN_ATTEMPTS) {
+      console.error(`Intercom broker could not listen on ${SOCKET_PATH}: ${error.message}`);
+      process.exit(1);
+    }
+    if (process.platform === "win32") {
+      await new Promise<void>((resolve) => setTimeout(resolve, LISTEN_RETRY_DELAY_MS));
+      this.listen(attempt + 1);
+      return;
+    }
+    const releaseReplacementLock = await acquireSocketReplacementLock(SOCKET_REPLACEMENT_LOCK_PATH, {
+      onWait: () => console.error(`Intercom broker waiting for another broker replacing ${SOCKET_PATH}`),
+    });
+    // Another broker may have replaced the stale socket while this one waited for the lock.
+    if (await isSocketAnswering(SOCKET_PATH)) {
+      releaseReplacementLock();
+      exitBecauseLiveBrokerOwnsSocket();
+    }
+    try {
+      unlinkSync(SOCKET_PATH);
+    } catch {
+      // A clean path has no stale socket to remove.
+    }
+    this.listen(attempt + 1, releaseReplacementLock);
   }
 
   private handleConnection(socket: net.Socket): void {
@@ -1807,9 +1877,10 @@ class IntercomBroker {
     const ownsRuntime = this.readPidFile() === process.pid;
     this.unlinkRuntimeFilesIfOwned();
     // Node unlinks a Unix socket path on server.close() even after a successor
-    // rebound that path. Skip close when we no longer own the pid; process.exit
-    // still closes our fd. Windows named pipes are not path-unlinked this way.
-    if (process.platform === "win32" || ownsRuntime) {
+    // rebound that path. Skip close when we no longer own the pid or the socket
+    // path; process.exit still closes our fd. Windows named pipes are not
+    // path-unlinked this way.
+    if (process.platform === "win32" || (ownsRuntime && this.ownsSocketPath())) {
       this.server.close();
     }
     process.exit(0);
@@ -1817,4 +1888,9 @@ class IntercomBroker {
 }
 
 // The stderr cap is already in place: `./bounded-stderr-install.js` is this file's first import.
-new IntercomBroker().start();
+async function startUnlessLiveBrokerAnswers(): Promise<void> {
+  if (await isSocketAnswering(SOCKET_PATH)) exitBecauseLiveBrokerOwnsSocket();
+  new IntercomBroker().start();
+}
+
+void startUnlessLiveBrokerAnswers();

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

@@ -46,6 +46,10 @@ export function getBrokerSpawnLockPath(agentDir: string = getAgentDir()): string
   return join(getIntercomDirPath(agentDir), "broker.spawn.lock");
 }
 
+export function getBrokerSocketReplacementLockPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker.sock.replace.lock");
+}
+
 /** Durable accepted-operation authority shared by replacement broker processes. */
 export function getBrokerDeliveredMessagesPath(agentDir: string = getAgentDir()): string {
   return join(getIntercomDirPath(agentDir), "delivered-messages.sqlite");

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

@@ -0,0 +1,32 @@
+import net from "net";
+
+export const SOCKET_PROBE_TIMEOUT_MS = 1000;
+
+/** True when something accepts a connection on the Unix socket or Windows named pipe at `socketPath`. */
+export function isSocketAnswering(socketPath: string, timeoutMs: number = SOCKET_PROBE_TIMEOUT_MS): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect(socketPath);
+    const finish = (isConnected: boolean) => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      resolve(isConnected);
+    };
+    const onConnect = () => {
+      // end() starts a half-close; a reset can still arrive before close. Keep a handler until then.
+      socket.on("error", () => {});
+      socket.end();
+      finish(true);
+    };
+    const onError = () => {
+      socket.destroy();
+      finish(false);
+    };
+    socket.on("connect", onConnect);
+    socket.on("error", onError);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      finish(false);
+    }, timeoutMs);
+  });
+}

package/dist/builtin/intercom/broker/socket-replacement-lock.ts

@@ -0,0 +1,104 @@
+import { readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+
+const SOCKET_REPLACEMENT_LOCK_POLL_MS = 20;
+/** Locks and tokens get their pid as they are created, so one still unreadable after this was left by a crash. */
+const UNREADABLE_FILE_GRACE_MS = 1_000;
+
+export interface SocketReplacementLockOptions {
+  readonly onWait?: () => void;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function holderPid(path: string): number | undefined {
+  try {
+    const pid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
+    return Number.isFinite(pid) ? pid : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+type Holder = { readonly kind: "live" } | { readonly kind: "abandoned"; readonly pid: number | undefined };
+
+/** A file whose pid is dead, or that stayed unreadable past the grace period, was left by a crashed broker. */
+function holderOf(path: string): Holder | undefined {
+  const pid = holderPid(path);
+  if (pid !== undefined) return isProcessAlive(pid) ? { kind: "live" } : { kind: "abandoned", pid };
+  try {
+    return Date.now() - statSync(path).mtimeMs >= UNREADABLE_FILE_GRACE_MS
+      ? { kind: "abandoned", pid: undefined }
+      : { kind: "live" };
+  } catch {
+    return undefined;
+  }
+}
+
+function removeFile(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already removed.
+  }
+}
+
+function createExclusively(path: string): boolean {
+  try {
+    writeFileSync(path, `${process.pid}\n`, { flag: "wx" });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    return false;
+  }
+}
+
+/**
+ * Removes an abandoned lock without ever touching a live one. Only the waiter that creates the takeover token for
+ * that holder may remove its lock, and while that lock exists no newer lock can be created, so the lock it removes is
+ * still the abandoned one. An abandoned token is removed so a later waiter can take over.
+ */
+function takeOverAbandonedLock(lockPath: string, abandonedPid: number | undefined): void {
+  const token = `${lockPath}.takeover-${abandonedPid ?? "unreadable"}`;
+  if (!createExclusively(token)) {
+    if (holderOf(token)?.kind === "abandoned") removeFile(token);
+    return;
+  }
+  try {
+    if (holderPid(lockPath) === abandonedPid) removeFile(lockPath);
+  } finally {
+    removeFile(token);
+  }
+}
+
+/**
+ * Serializes stale-socket replacement across brokers, so a broker that probed the socket as stale cannot unlink a
+ * socket another broker bound in the meantime: the holder re-probes before it unlinks. A live holder's lock is never
+ * taken; an abandoned one is. Resolves with the release function, which removes the lock only while this process
+ * holds it.
+ */
+export async function acquireSocketReplacementLock(
+  lockPath: string,
+  { onWait }: SocketReplacementLockOptions = {},
+): Promise<() => void> {
+  let announcedWait = false;
+  while (!createExclusively(lockPath)) {
+    const holder = holderOf(lockPath);
+    if (holder?.kind === "abandoned") {
+      takeOverAbandonedLock(lockPath, holder.pid);
+    } else if (holder?.kind === "live" && !announcedWait) {
+      announcedWait = true;
+      onWait?.();
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, SOCKET_REPLACEMENT_LOCK_POLL_MS));
+  }
+  return () => {
+    if (holderPid(lockPath) === process.pid) removeFile(lockPath);
+  };
+}

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

@@ -1,9 +1,9 @@
 import { spawn } from "child_process";
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync } from "fs";
+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 net from "net";
+import { isSocketAnswering } from "./socket-liveness.js";
 import { createChildProcessEnvironment, isBunBinary } from "@bastani/atomic";
 import {
   getBrokerLogPath,
@@ -57,6 +57,12 @@ 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;
+
+/** 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;
+
 type BrokerRuntime = "node" | "bun-source" | "bun-binary";
 
 export const INTERNAL_INTERCOM_BROKER_ARG = "--atomic-internal-intercom-broker";
@@ -257,10 +263,20 @@ export function getBrokerSpawnOptions(
   };
 }
 
-/** Truncate (or create) the broker log so each spawn starts from a bounded, current file. */
-function resetBrokerLog(logPath: string = BROKER_LOG): void {
+/**
+ * Truncate (or create) the broker log so each spawn starts from a bounded, current file. Returns false when a
+ * Windows broker that is still starting holds the log through its launcher's stderr redirect.
+ */
+function resetBrokerLog(logPath: string = BROKER_LOG): boolean {
   ensurePrivateDirectory(dirname(logPath));
-  closeSync(openSync(logPath, "w"));
+  try {
+    closeSync(openSync(logPath, "w"));
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (process.platform === "win32" && (code === "EBUSY" || code === "EPERM")) return false;
+    throw error;
+  }
 }
 
 /** Read at most {@link BROKER_LOG_TAIL_BYTES} trailing bytes of the broker log. */
@@ -299,19 +315,24 @@ function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error));
 }
 
-export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: string[]): Promise<void> {
+export async function spawnBrokerIfNeeded(
+  brokerCommand: string,
+  brokerArgs: string[],
+  readyTimeoutMs: number = BROKER_READY_TIMEOUT_MS,
+): Promise<void> {
   ensurePrivateDirectory(INTERCOM_DIR);
 
   if (await isBrokerRunning()) {
     return;
   }
 
-  const ownsLock = acquireSpawnLock();
-  if (!ownsLock) {
-    await waitForBroker();
+  const lockOwner = acquireSpawnLock();
+  if (lockOwner === undefined) {
+    await waitForBroker(readyTimeoutMs);
     return;
   }
 
+  let keepLock = false;
   try {
     if (await isBrokerRunning()) {
       return;
@@ -323,7 +344,10 @@ export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: str
       writeWindowsHiddenLauncher(launch.launcherCommandLine, launch.launcherPath);
     }
     // Reset before spawning either way: the Windows launcher appends to this same path.
-    resetBrokerLog();
+    if (!resetBrokerLog()) {
+      await waitForBroker(readyTimeoutMs);
+      return;
+    }
     // The Windows launcher redirects the broker's own stderr, so only the direct spawn
     // needs the descriptor. Node duplicates it during spawn, so the parent copy is closed
     // immediately afterwards rather than being held open for the broker's lifetime.
@@ -358,23 +382,38 @@ export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: str
           reject(new Error(`Intercom broker exited before startup with signal ${signal}\n${describeBrokerLog()}`));
           return;
         }
-        reject(
-          new Error(`Intercom broker exited before startup with code ${code ?? "unknown"}\n${describeBrokerLog()}`),
-        );
+        const exitedBeforeStartup = () =>
+          new Error(`Intercom broker exited before startup with code ${code ?? "unknown"}\n${describeBrokerLog()}`);
+        if (code === 0) {
+          // A broker that finds a live broker on the socket yields with a clean exit.
+          void checkSocketConnectable().then((answering) => (answering ? resolve() : reject(exitedBeforeStartup())));
+          return;
+        }
+        reject(exitedBeforeStartup());
       };
 
       child.once("error", onError);
       child.once("exit", onExit);
-      waitForBroker().then(() => {
+      waitForBroker(readyTimeoutMs).then(() => {
         cleanup();
         resolve();
       }, (error) => {
         cleanup();
+        // A broker still starting keeps the lock, so later spawners wait for it instead of starting another.
+        // Only now does the lock name the broker: until this hand-off it follows this live spawner, so no other
+        // spawner can judge it stale and replace it while this one may still release it.
+        // The Windows launcher hides the broker's pid, so its lock could only follow this live spawner and would
+        // block every later spawn; there the broker's own live-socket check is what prevents a takeover.
+        keepLock =
+          launch.kind === "direct" &&
+          child.exitCode === null &&
+          child.signalCode === null &&
+          handSpawnLockToBroker(child.pid, lockOwner);
         reject(toError(error));
       });
     });
   } finally {
-    releaseSpawnLock();
+    if (!keepLock) releaseSpawnLock(lockOwner);
   }
 }
 
@@ -397,39 +436,37 @@ async function isBrokerRunning(): Promise<boolean> {
 }
 
 function checkSocketConnectable(): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = net.connect(BROKER_SOCKET);
-    const finish = (isConnected: boolean) => {
-      clearTimeout(timeout);
-      socket.off("connect", onConnect);
-      socket.off("error", onError);
-      resolve(isConnected);
-    };
-    const onConnect = () => {
-      // end() starts a half-close; a reset can still arrive before close. Keep a handler until then.
-      socket.on("error", () => {});
-      socket.end();
-      finish(true);
-    };
-    const onError = () => {
-      socket.destroy();
-      finish(false);
-    };
-    socket.on("connect", onConnect);
-    socket.on("error", onError);
-    const timeout = setTimeout(() => {
-      socket.destroy();
-      finish(false);
-    }, 1000);
-  });
+  return isSocketAnswering(BROKER_SOCKET);
+}
+
+/** Records the still-starting broker on the lock so staleness follows that process instead of the spawner. */
+function handSpawnLockToBroker(pid: number | undefined, owner: string): boolean {
+  if (pid === undefined || !ownsSpawnLock(owner)) return false;
+  try {
+    appendFileSync(BROKER_SPAWN_LOCK, `${pid}\n`);
+    return true;
+  } catch {
+    // The startup error must still reach the caller; an unrecorded lock is released like any other.
+    return false;
+  }
 }
 
-function acquireSpawnLock(): boolean {
+function ownsSpawnLock(owner: string, lockPath: string = BROKER_SPAWN_LOCK): boolean {
+  try {
+    return readFileSync(lockPath, "utf-8").startsWith(owner);
+  } catch {
+    return false;
+  }
+}
+
+/** Returns the header this spawner wrote, which proves ownership on release, or undefined when another spawner holds the lock. */
+function acquireSpawnLock(): string | undefined {
   const maxRetries = 5;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const owner = `${process.pid}\n${Date.now()}\n`;
     try {
-      writeFileSync(BROKER_SPAWN_LOCK, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
-      return true;
+      writeFileSync(BROKER_SPAWN_LOCK, owner, { flag: "wx" });
+      return owner;
     } catch (error) {
       if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") {
         throw error;
@@ -442,42 +479,50 @@ function acquireSpawnLock(): boolean {
         }
         continue;
       }
-      return false;
+      return undefined;
     }
   }
-  return false;
+  return undefined;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
 }
 
-function isSpawnLockStale(): boolean {
-  if (!existsSync(BROKER_SPAWN_LOCK)) {
+/**
+ * A lock is stale once the broker it recorded is gone, or, while no broker is recorded, once its
+ * spawner is gone. A live broker keeps the lock even if its spawner died, until the age backstop.
+ */
+export function isSpawnLockStale(lockPath: string = BROKER_SPAWN_LOCK, nowMs: number = Date.now()): boolean {
+  if (!existsSync(lockPath)) {
     return false;
   }
 
   try {
-    const [pidLine = "", createdAtLine = "0"] = readFileSync(BROKER_SPAWN_LOCK, "utf-8").trim().split("\n");
-    const pid = Number.parseInt(pidLine, 10);
+    const [spawnerLine = "", createdAtLine = "", brokerLine = ""] = readFileSync(lockPath, "utf-8").trim().split("\n");
+    const spawnerPid = Number.parseInt(spawnerLine, 10);
     const createdAt = Number.parseInt(createdAtLine, 10);
-    const ageMs = Date.now() - createdAt;
-
-    if (Number.isFinite(pid)) {
-      try {
-        process.kill(pid, 0);
-      } catch {
-        // The process that created the lock is gone.
-        return true;
-      }
-    }
+    const brokerPid = Number.parseInt(brokerLine, 10);
 
-    return !Number.isFinite(createdAt) || ageMs > 10_000;
+    if (!Number.isFinite(spawnerPid) || !Number.isFinite(createdAt)) return true;
+    if (nowMs - createdAt > BROKER_SPAWN_LOCK_MAX_AGE_MS) return true;
+    return !isProcessAlive(Number.isFinite(brokerPid) ? brokerPid : spawnerPid);
   } catch {
     // Unreadable lock contents are treated as stale so a new broker can start.
     return true;
   }
 }
 
-function releaseSpawnLock(): void {
+/** Removes the lock only while it is still the one `owner` wrote; a spawner that replaced a stale lock keeps its own. */
+export function releaseSpawnLock(owner: string, lockPath: string = BROKER_SPAWN_LOCK): void {
+  if (!ownsSpawnLock(owner, lockPath)) return;
   try {
-    unlinkSync(BROKER_SPAWN_LOCK);
+    unlinkSync(lockPath);
   } catch {
     // Another cleanup path may already have removed the lock.
   }
@@ -488,7 +533,7 @@ function releaseSpawnLock(): void {
  * Startup is tens of milliseconds, so the previous flat 100 ms sleep dominated it; the
  * overall timeout semantics are unchanged.
  */
-export async function waitForBroker(timeoutMs = 5000): Promise<void> {
+export async function waitForBroker(timeoutMs = BROKER_READY_TIMEOUT_MS): Promise<void> {
   const start = Date.now();
   let interval = BROKER_POLL_INITIAL_INTERVAL_MS;
   while (Date.now() - start < timeoutMs) {