@bastani/atomic 0.9.28-alpha.4 → 0.9.28

package/CHANGELOG.md

@@ -2,6 +2,105 @@
 
 ## [Unreleased]
 
+## [0.9.28] - 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)).
+- Added the API-key-only providers `openai-api` and `anthropic-api`, so you can keep a ChatGPT or Claude subscription login on `openai`/`anthropic` and still use an API key for the same models. See [Subscription and API key at the same time](docs/providers.md#subscription-and-api-key-at-the-same-time).
+- `session.compact()` and extension `ctx.compact()` accept `compactionModel` to pick the compaction model for one run without changing the `compactionModel` setting. An unknown ID rejects before the active run is interrupted. See [Compaction and tree navigation](docs/sdk.md#compaction-and-tree-navigation).
+- Added terminal program-status reporting through OSC 7501 for runs, compaction, extension prompts, and sign-in. Compatible terminals can show when Atomic is working, waiting for input, done, or has failed.
+- Added recorded response and tool execution durations. Bash tool results show their execution time, including after a session is resumed.
+- Added OpenAI's GPT-6 Luna classifier through the Decisions API with `OPENAI_API_KEY`, and image input for codemode's `models.classify()` context. See [Classifier models](docs/models.md#use-classifier-models).
+- Added native classification for llama.cpp decision models through `/v1/systemone`. Decision-only models stay out of the chat selector, while chat models keep the next-token classifier fallback. Cached native classifiers remain available after restart.
+- Added exact-name `+name` and `-name` modifiers to CLI `--tools` and SDK `tools`, for example `atomic --tools +codemode,-write`. They change the resolved defaults instead of replacing them and persist across `/reload`.
+- Added `compactionModel` and a **Compaction model** selector in `/settings` to choose a compactor independently of the chat model ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Added verbatim classifier compaction with registered models such as `typesafe/jev-latest`, retaining protected context and recent messages ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Added Morph verbatim compaction with `morph/morph-compactor`, authenticated through `/login morph` or `MORPH_API_KEY` ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Added `session.workflows.observe(observer)`, so SDK hosts can follow the workflow runs the agent launches without writing an extension. The observer receives a snapshot first, then changes in order. Root activity now includes an optional `graph` that lists each stage and `ctx.tool` node with its status, parents, and pending prompt, plus any run-level prompts ([#3476](https://github.com/bastani-inc/atomic/issues/3476)).
+- Added `RunOpts.onStageSessionEvent` so workflow `run()` callers receive each stage session's events, such as message updates and tool executions, tagged with the run and stage ids. Events continue across fallback-model sessions and include nested workflow stages ([#3474](https://github.com/bastani-inc/atomic/issues/3474)).
+- Added `createTranscript()`, which turns session events into the assistant's output as ordered, JSON-serializable text, thinking, and tool call parts, with each tool call joined to its result ([#3475](https://github.com/bastani-inc/atomic/issues/3475)).
+- Added `createAgentSessionAdapter(baseOptions?)` to `@bastani/atomic/workflows`, which builds the default workflow stage-session adapter with `createAgentSession` options shared by every stage ([#3472](https://github.com/bastani-inc/atomic/issues/3472)).
+- Added `ctx.isPresentationOnly` so extension lifecycle hooks can leave execution to the isolated interactive engine while retaining host-side UI ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Exported `publishExtensionContextEffect(ctx, effect, phase?)` with a synchronous commit phase for generation identity handoff, and `registerExtensionContextRetirementEffect(ctx, dispose)` for observer cleanup before authority revocation ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Added Azure Foundry Chat Completions with `azure/deepseek-v4-pro`, using the existing Azure endpoint and deployment-name settings.
+- Added `*` patterns to `--tools` and `--exclude-tools`, including MCP tool names.
+- Added `--no-mcp` to disable built-in MCP support for one run, including interactive sessions.
+- Added `ExtensionAPI.getWorkflowHostModules()` to supply shared host module instances for the exact workflow imports `@bastani/atomic`, `@bastani/pi-ai`, and `@bastani/pi-ai/providers/all`, avoiding repeated package loading ([#3454](https://github.com/bastani-inc/atomic/issues/3454)).
+
+### 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).
+- Moved the GPT-6 Luna classifier from `openai/gpt-6-luna` to its own API-key-only provider, `openai-decisions/gpt-6-luna`, named "GPT-6 Luna Decisions". `openai/gpt-6-luna` now always means the chat model, and the classifier stays available while `openai` uses ChatGPT sign-in. Update `routerModel`, `compactionModel`, `structured_output` and codemode references that meant the classifier. See [Classifier models](docs/models.md#use-classifier-models).
+- Codemode labels returned output items with numbered headers and places console output in a separate trailing block.
+- Codemode now says that `ALL_TOOLS`, `searchTools()`, and `describeTool()` list only script-callable tools, and `searchTools()`/`describeTool()` answer an exact model-only tool name such as `subagent` with a hint to call it directly instead of returning nothing ([#3510](https://github.com/bastani-inc/atomic/issues/3510))
+- Changed `atomic mcp login --timeout` to limit the whole sign-in, including requests to the authorization server, instead of only the wait for the browser.
+- Compaction planners now receive structured per-message lines instead of a numbered transcript ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Compaction cards show the backend and model used, including `summary (pi fallback)` for policy-refusal summaries ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Home and End move the editor cursor to the start and end of the line. Ctrl+Home and Ctrl+End jump to the top and bottom of the fullscreen transcript.
+- Renamed the Azure provider to `azure`. Existing provider references remain supported, and startup migrates credentials and configuration without replacing existing `azure` entries. Project files are migrated only when trusted.
+- Codemode built-ins are frozen in pi 1.0.4. Patches to built-ins are ignored instead of crashing the host.
+
+### 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)).
+- Updated the sandbox example extension's lockfile to `shell-quote` 1.12.0, resolving the `quote()` command-injection advisory [GHSA-pqg4-j6r4-53mv](https://github.com/advisories/GHSA-pqg4-j6r4-53mv) in its `@anthropic-ai/sandbox-runtime` dependency.
+- Fixed hyperlinks being disabled in Herdr panes, while keeping image protocols off even when outer-terminal environment variables are inherited ([#10573](https://github.com/earendil-works/pi/issues/10573)).
+- Fixed `outputPad` applying inconsistently to tool results, shell output, summaries, skill invocations, and custom transcript entries. Changing it in `/settings` now updates existing blocks without rebuilding the transcript.
+- Fixed fullscreen text selections surviving a transcript rebuild and selecting unrelated replacement text.
+- Fixed extension-registered MCP servers silently remaining unused when an SDK host has no MCP contribution consumer. Atomic now reports each unhandled server once.
+- Fixed a false `Timeout waiting for response to resume_queued_messages` error when you send a message while a paused queue is still waiting for the agent's current turn to finish, and the follow-up `Agent is already processing` error caused by the stale paused state. The resume now waits for the turn instead of giving up after 30 seconds ([#3493](https://github.com/bastani-inc/atomic/issues/3493)).
+- Fixed extension `session_shutdown` handlers being cut off when you quit the interactive CLI. The engine now gets up to 5 seconds to finish extension shutdown, instead of about 750 ms, before it is force-stopped.
+- Fixed slow extension loading and `/reload` on Windows. Imports such as `./helper.js` that point at TypeScript sources no longer make the loader try hundreds of missing files before finding `helper.ts`.
+- Fixed `/mcp` waiting for startup connections before opening. The manager now updates live and stays usable while enabling, disabling, or reconnecting servers.
+- Fixed images being dropped as unresizable under `node --watch` when Node sends its own messages on the image resize worker channel.
+- Fixed codemode's tool description omitting `await` for `searchTools()`, `describeTool()`, and `describeNamespace()`, which could make scripts return unresolved promises instead of tool information.
+- Fixed slash commands and shell-command drafts typed during interactive startup running before Enter, including when launching with `--model` or `--provider`. Enter-terminated input stays ordered and unfinished text remains in the editor.
+- Fixed a stuck MCP server startup blocking re-enabling the server or shutting down after it was disabled.
+- Fixed clipboard paste doing nothing in Termux, and failed copies there omitting the Termux:API install hint.
+- Fixed `!` and RPC `bash` output keeping fragments of color codes, such as a stray `m`, when a code was split across output chunks.
+- Fixed MCP OAuth sign-ins that could not be cancelled while waiting on the authorization server and kept running after the session ended. The sign-in screen now cancels with Esc at every step, session shutdown aborts a running sign-in, and each request to the authorization server times out after 15 seconds.
+- Fixed shutdown waiting up to 15 seconds to refresh an MCP OAuth token that was about to expire, only to close the server's session.
+- Policy refusals from any chat compaction model, including `auto`, explicit chat-model IDs, and borrowed fallback entries, now try pi's summary compaction on the same model before continuing through fallback models. Summary requests retry recoverable errors; policy refusals are never retried. Classifier and Morph failures advance directly to fallback models ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Morph compaction failures now include the HTTP status and a bounded, credential-redacted response excerpt in error diagnostics ([#3470](https://github.com/bastani-inc/atomic/issues/3470)).
+- Fixed Herdr publishing duplicate pane activity when startup workflow recovery refreshes an unchanged activity snapshot ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed Herdr skipping a return to an earlier pane activity after an intervening report timed out or failed ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed project `.atomic/settings.json`, extensions, skills, and other trust-gated resources being ignored without notice in untrusted projects. Interactive sessions now show a warning that points to `/trust`, matching upstream pi.
+- Fixed `@bastani/atomic/workflows` type declarations disagreeing with the runtime: `StageSnapshot` now declares `parentIds`, `executionOrder`, `model`, `startedAt`, `endedAt`, and `durationMs`; `Store` now declares `snapshot()`, `graphSnapshot()`, and `subscribe()`; and an `AgentSessionAdapter.create` can return `createAgentSession(...)` directly without a type cast ([#3473](https://github.com/bastani-inc/atomic/issues/3473)).
+- Fixed `run()` from `@bastani/atomic/workflows` failing at the first `ctx.task` or `ctx.stage` with "prompt adapter not configured" when `opts.adapters` was omitted. Stages now default to in-process `createAgentSession` sessions with in-memory session managers ([#3472](https://github.com/bastani-inc/atomic/issues/3472)).
+- Fixed startup extension confirmations, including workflow recovery prompts, losing keyboard focus during terminal initialization ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed queued protected workflow notices producing `SessionClosed` replies during reload. Successful reload now preserves those notices for the replacement extensions without releasing an explicitly paused queue ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed idle workflow status and control commands not displaying their output in isolated interactive sessions, including after `/reload` ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed extension reload skipping remaining commit effects and predecessor shutdown when a commit effect and an SDK error observer both throw. Reload now retains both failures while keeping the replacement extensions active ([#3468](https://github.com/bastani-inc/atomic/issues/3468)).
+- Fixed syntax colors leaking across lines in multiline tokens and interpolation substitutions inheriting string colors.
+- Invalid router and provider-list settings retain their configuration validation errors during Azure provider migration.
+- Fixed codemode `tools.read()` returning text instead of an image block for image files. Pass the result to `image()` to display it ([#10251](https://github.com/earendil-works/pi/issues/10251)).
+- Fixed MCP OAuth dynamic registration omitting `application_type`, which caused redirect URI rejections on OpenID Connect servers ([#10493](https://github.com/earendil-works/pi/issues/10493)).
+- Fixed `--tools` removing MCP tools when selecting codemode. MCP tools remain callable unless the allowlist contains an entry starting with `mcp__`; unmatched tools are not declared directly.
+- Fixed shutdown leaving MCP connections open while a server was still connecting ([#10249](https://github.com/earendil-works/pi/issues/10249)).
+- Fixed hidden tools appearing in prompt rules and skill-reading hints. Codemode tool declarations now include each tool's prompt guidelines ([#10343](https://github.com/earendil-works/pi/issues/10343)).
+- Fixed interactive quit waiting on pending extension commands, which could leave connecting MCP servers running.
+- Fixed HTTP/2 pending stream cancellations being treated as user cancellations instead of retryable transport failures.
+- Updated the bundled `proxy-addr` dependency to 2.0.8, fixing IP spoofing through IPv4-mapped IPv6 trusted subnets.
+
+## [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,19 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.28] - 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)).
+- Fixed intercom occasionally reporting `Intercom not connected: connect ENOENT …/broker.sock` when a session connected just as an idle broker was shutting down.
+
+## [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);
+  };
+}