fix(events): stand by instead of exiting when the event runtime socket is owned (#561)

* fix(events): stand by instead of exiting when the event runtime socket is owned

A generated MCP server exited before answering `initialize` whenever another
process from the same plugin install already owned the event runtime socket
(`Event runtime endpoint already has a live server.`), so every session after
the first launched from one install root got no server at all.

`createEventRuntimeServer` gains `whenOwned: 'fail' | 'standby'` (default
`'fail'`, unchanged). Under `'standby'` a live owner is not fatal: the server
resolves in the `standby` role and a scope-bound fiber probes the endpoint
every ~1 s (jittered) and runs the existing `openServer` path the moment it is
free; the claim lock lets exactly one standby win. `EventRuntimeServer` exposes
`role()` and `onRoleChange()`. The generated runtime passes `'standby'` and
announces both the standby start and the takeover on stderr only.

Closes #559

* fix(events): hold the claim across teardown; report standby failures; guard role listeners

Self-review findings on #561 (752879a):

- close() now takes the endpoint claim before it stops listening and holds it
  through the identity-checked removal, so no standby can bind a new socket at
  the path — possibly on the inode the kernel just freed — before the old
  owner's identity check runs. Standbys wait out the claim (bounded retries).
- The standby loop only swallows "still owned"; every other takeover failure
  keeps it standing by but is reported through the new
  `onStandbyError` option, which the generated runtime writes to stderr at one
  line per distinct message per 30 s.
- Role listeners run in their own guards: a throwing listener is reported via
  `onStandbyError` and never stops the remaining listeners or the transition.

* fix(events): never let a throwing onStandbyError reporter end the standby loop or skip role listeners

Every onStandbyError invocation goes through one guarded helper that
swallows a reporter throw, so the standby keeps probing and the remaining
role listeners still run (second-pass self-review finding on 43a85a1).

Author: ScriptedAlchemy

.changeset/event-runtime-standby.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Keep a generated MCP server running when another process from the same install already owns the event runtime socket: the server stands by and takes the socket over when the owner exits, instead of exiting with `Event runtime endpoint already has a live server`. `createEventRuntimeServer` gains `whenOwned: 'fail' | 'standby'` (default `'fail'`), and the returned server exposes `role()` and `onRoleChange()`; the standby start and the takeover are announced on stderr only (#561)

packages/agent-bundle/src/events/ipc.ts

@@ -29,7 +29,7 @@ import {
   runAgentRequest,
   unavailable,
 } from '@agent-bundle/runtime';
-import type { createEventRuntimeServer } from './events/ipc.ts';
+import type { createEventRuntimeServer, EventRuntimeTransportError } from './events/ipc.ts';
 import type { createCanonicalEventProps, projectEventDocument } from './events/project.ts';
 import { createTaskAugmentedMcpServer, type TaskAugmentedMcpServer } from './mcp-tasks.ts';
 import { canonicalAgentEvents, type CanonicalAgentEvent } from './routes/public.ts';
@@ -731,6 +731,35 @@ const noticeDiagnostic = (line: string): void => {
 
 const describeError = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 
+/** stderr only: stdout is the protocol stream. */
+const eventRuntimeDiagnostic = (line: string): void => {
+  process.stderr.write(`agent-bundle event runtime: ${line}\n`);
+};
+
+/** How long one takeover-failure message stays reported before the same message earns another line. */
+const STANDBY_ERROR_REPEAT_INTERVAL_MS = 30_000;
+
+/**
+ * Turns the standby loop's recoverable failures into stderr lines without
+ * repeating one per probe tick: a message is reported when first seen and
+ * again once `STANDBY_ERROR_REPEAT_INTERVAL_MS` has passed since its last
+ * line, so a takeover that keeps failing the same way stays visible at one
+ * line per half minute while a new failure mode is reported at once.
+ */
+export const createStandbyErrorReporter = (
+  report: (line: string) => void,
+  now: () => number = Date.now,
+): ((error: EventRuntimeTransportError) => void) => {
+  const lastReportedAt = new Map<string, number>();
+  return (error) => {
+    const at = now();
+    const previous = lastReportedAt.get(error.message);
+    if (previous !== undefined && at - previous < STANDBY_ERROR_REPEAT_INTERVAL_MS) return;
+    lastReportedAt.set(error.message, at);
+    report(`takeover failed, still standing by: ${error.message}`);
+  };
+};
+
 /**
  * Installs `resources/subscribe` / `resources/unsubscribe` for the notice
  * inbox URI and returns the post-render observation that emits
@@ -878,6 +907,15 @@ const canonicalEvent = (event: string): CanonicalAgentEvent => {
  * The shared event runtime for one artifact: native envelopes arrive over the
  * IPC socket, render through the same dispatcher every route uses, and project
  * back into the host's own hook response shape.
+ *
+ * One process per install root owns the socket. Hosts routinely launch several
+ * sessions of the same plugin from one install (every Claude Code session
+ * Claude Desktop starts, Cursor importing a Claude-installed plugin), so a
+ * second server finding the socket owned is normal, not fatal: it starts in
+ * the `standby` role, serves its own MCP session, and takes the socket over
+ * when the owner exits. Both role changes, and any takeover failure other than
+ * "still owned", are announced on stderr only — the process's stdout is the
+ * MCP protocol stream.
  */
 const startEventRuntime = async (
   events: GeneratedEventRuntimeBinding,
@@ -888,7 +926,10 @@ const startEventRuntime = async (
   pluginRoot: Observed<AgentPluginIdentity> | undefined,
 ): Promise<{ readonly close: () => Promise<void> }> => {
   const startedAt = new Date().toISOString();
-  return events.createEventRuntimeServer({
+  // The socket path is known once the server exists; the standby loop only
+  // reports after its first probe interval, by which time it is.
+  let endpointLabel = events.endpointId;
+  const server = await events.createEventRuntimeServer({
     artifactEpoch: events.artifactEpoch,
     endpointId: events.endpointId,
     handle: async (request, signal) => settled(async () => {
@@ -966,7 +1007,19 @@ const startEventRuntime = async (
       pid: process.pid,
       startedAt,
     }),
+    onStandbyError: createStandbyErrorReporter((line) => {
+      eventRuntimeDiagnostic(`${endpointLabel} ${line}`);
+    }),
+    whenOwned: 'standby',
   });
+  endpointLabel = server.endpoint;
+  if (server.role() === 'standby') {
+    eventRuntimeDiagnostic(`${server.endpoint} is owned by another process; standing by`);
+    server.onRoleChange((role) => {
+      if (role === 'owner') eventRuntimeDiagnostic(`${server.endpoint} was released by its owner; took it over`);
+    });
+  }
+  return server;
 };
 
 /**

packages/agent-bundle/src/mcp-server-runtime.ts

@@ -551,7 +551,11 @@ export const openInMemoryMcpServer = async <
             allowedTargets: [options.lineageHost],
             artifactEpoch,
             createCanonicalEventProps: (() => { throw new Error('in-memory lineage sessions dispatch no events'); }) as never,
-            createEventRuntimeServer: (async () => ({ close: async () => undefined })) as never,
+            createEventRuntimeServer: (async () => ({
+              close: async () => undefined,
+              onRoleChange: () => () => undefined,
+              role: () => 'owner',
+            })) as never,
             endpointId: `${artifactEpoch}:in-memory`,
             projectEventDocument: (() => undefined) as never,
             target: options.lineageHost,