agent-gear 1.3.0 → 2.0.0

package/src/mcp/relay.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { McpRelay, type McpRelayResult } from './relay.js';
+
+function createRelay() {
+  const emitted: Array<{ requestId: string; sessionId: string; serverName: string; token: string; body: unknown }> = [];
+  const relay = new McpRelay((payload) => emitted.push(payload));
+  return { relay, emitted };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('McpRelay', () => {
+  it('T-C6 resolves a pending request by requestId on mcp:response', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['github-mcp'] });
+
+    const promise = relay.forward('sess-1', 'github-mcp', { method: 'tools/list' });
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0].requestId).toMatch(/^mcpreq_/);
+    expect(emitted[0]).toMatchObject({
+      sessionId: 'sess-1',
+      serverName: 'github-mcp',
+      token: 'tok-1',
+      body: { method: 'tools/list' },
+    });
+
+    relay.handleMcpResponse(emitted[0].requestId, 200, { result: [] });
+    await expect(promise).resolves.toEqual({ status: 200, body: { result: [] } });
+  });
+
+  it('T-C7 times out after 60s with 504 and cleans up pending', async () => {
+    vi.useFakeTimers();
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['github-mcp'] });
+
+    const first = relay.forward('sess-1', 'github-mcp', { method: 'tools/list' });
+    await vi.advanceTimersByTimeAsync(60_000);
+    await expect(first).resolves.toEqual(expect.objectContaining({ status: 504 }));
+
+    const second = relay.forward('sess-1', 'github-mcp', { method: 'tools/call' });
+    emitted[1] && relay.handleMcpResponse(emitted[1].requestId, 200, { ok: true });
+    await expect(second).resolves.toEqual({ status: 200, body: { ok: true } });
+  });
+
+  it('T-C8 fails all pending immediately with 503 on disconnect', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['a-mcp'] });
+    const promises = [
+      relay.forward('sess-1', 'a-mcp', { id: 1 }),
+      relay.forward('sess-1', 'a-mcp', { id: 2 }),
+    ];
+    expect(emitted).toHaveLength(2);
+
+    relay.handleDisconnect();
+    const results = await Promise.all(promises);
+    expect(results).toEqual([
+      expect.objectContaining({ status: 503 }),
+      expect.objectContaining({ status: 503 }),
+    ]);
+  });
+
+  it('T-C9 unregistering a session fails its pending with 410, other sessions unaffected', async () => {
+    const { relay, emitted } = createRelay();
+    relay.registerSession('sess-1', { token: 'tok-1', serverNames: ['a-mcp'] });
+    relay.registerSession('sess-2', { token: 'tok-2', serverNames: ['b-mcp'] });
+
+    const sess1 = relay.forward('sess-1', 'a-mcp', { id: 1 });
+    const sess2 = relay.forward('sess-2', 'b-mcp', { id: 2 });
+
+    relay.unregisterSession('sess-1');
+    await expect(sess1).resolves.toEqual(expect.objectContaining({ status: 410 }));
+    expect(relay.hasSession('sess-1')).toBe(false);
+    expect(relay.hasSession('sess-2')).toBe(true);
+
+    emitted[1] && relay.handleMcpResponse(emitted[1].requestId, 200, { ok: true });
+    await expect(sess2).resolves.toEqual({ status: 200, body: { ok: true } });
+  });
+
+  it('T-C10 ignores mcp:response for an unknown requestId', async () => {
+    const { relay } = createRelay();
+    expect(() => relay.handleMcpResponse('mcpreq_unknown', 200, {})).not.toThrow();
+  });
+
+  it('forward returns 404 for an unregistered session', async () => {
+    const { relay } = createRelay();
+    const result: McpRelayResult = await relay.forward('missing', 'a-mcp', {});
+    expect(result.status).toBe(404);
+  });
+});

package/src/mcp/relay.ts

@@ -0,0 +1,94 @@
+export interface SessionEndpoint {
+  token: string;
+  serverNames: string[];
+}
+
+export interface McpRelayResult {
+  status: number;
+  body: unknown;
+}
+
+interface McpRequestPayload {
+  requestId: string;
+  sessionId: string;
+  serverName: string;
+  token: string;
+  body: unknown;
+}
+
+interface PendingRequest {
+  sessionId: string;
+  resolve: (result: McpRelayResult) => void;
+  timer: NodeJS.Timeout;
+}
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+export class McpRelay {
+  private pendingRequests = new Map<string, PendingRequest>();
+  private sessionEndpoints = new Map<string, SessionEndpoint>();
+  private emitMcpRequest: (payload: McpRequestPayload) => void;
+
+  constructor(emitMcpRequest: (payload: McpRequestPayload) => void) {
+    this.emitMcpRequest = emitMcpRequest;
+  }
+
+  registerSession(sessionId: string, endpoint: SessionEndpoint): void {
+    this.sessionEndpoints.set(sessionId, endpoint);
+  }
+
+  hasSession(sessionId: string): boolean {
+    return this.sessionEndpoints.has(sessionId);
+  }
+
+  hasServer(sessionId: string, serverName: string): boolean {
+    const endpoint = this.sessionEndpoints.get(sessionId);
+    return endpoint ? endpoint.serverNames.includes(serverName) : false;
+  }
+
+  unregisterSession(sessionId: string): void {
+    if (!this.sessionEndpoints.delete(sessionId)) return;
+    for (const [requestId, pending] of this.pendingRequests) {
+      if (pending.sessionId !== sessionId) continue;
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(requestId);
+      pending.resolve({ status: 410, body: { error: 'SESSION_ENDED', message: 'MCP session has ended' } });
+    }
+  }
+
+  async forward(sessionId: string, serverName: string, body: unknown): Promise<McpRelayResult> {
+    const endpoint = this.sessionEndpoints.get(sessionId);
+    if (!endpoint) return { status: 404, body: { error: 'SESSION_NOT_FOUND' } };
+    const requestId = `mcpreq_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    console.log(`[MCP relay] forward requestId=${requestId} session=${sessionId} server=${serverName} method=${(body as { method?: string })?.method ?? '?'}`);
+    return new Promise<McpRelayResult>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        console.log(`[MCP relay] requestId=${requestId} -> 504 (timeout after ${REQUEST_TIMEOUT_MS}ms, no mcp:response received)`);
+        resolve({ status: 504, body: { error: 'TIMEOUT', message: 'MCP request timed out' } });
+      }, REQUEST_TIMEOUT_MS);
+      this.pendingRequests.set(requestId, { sessionId, resolve, timer });
+      this.emitMcpRequest({ requestId, sessionId, serverName, token: endpoint.token, body });
+    });
+  }
+
+  handleMcpResponse(requestId: string, status: number, body: unknown): void {
+    const pending = this.pendingRequests.get(requestId);
+    if (!pending) {
+      console.log(`[MCP relay] response requestId=${requestId} status=${status} IGNORED (no pending request)`);
+      return;
+    }
+    console.log(`[MCP relay] response requestId=${requestId} status=${status}`);
+    clearTimeout(pending.timer);
+    this.pendingRequests.delete(requestId);
+    pending.resolve({ status, body });
+  }
+
+  handleDisconnect(): void {
+    for (const [requestId, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      this.pendingRequests.delete(requestId);
+      pending.resolve({ status: 503, body: { error: 'CONTROLLER_DISCONNECTED', message: 'Controller disconnected' } });
+    }
+  }
+}

package/src/socketio-client.ts

@@ -16,8 +16,10 @@ import { worktreeHandler } from './worktree-handler.js';
 import { fsHandler } from './fs-handler.js';
 import { gatewayManager } from './gateway.js';
 import { processRegistry, isProcessAlive } from './acp/process-registry.js';
+import { McpRelay } from './mcp/relay.js';
+import { LocalMcpServer } from './mcp/local-server.js';
 
-const CONTROLLER_VERSION = '1.1.1';
+const CONTROLLER_VERSION = '2.0.0';
 const acpBridges = new Map<string, AcpSessionBridge>();
 const permissionRequestBridge = new Map<string, AcpSessionBridge>();
 const elicitationRequestBridge = new Map<string, AcpSessionBridge>();
@@ -60,7 +62,7 @@ interface AcpStartPayload {
   serverType: string;
   cwd: string;
   mcpServers?: Array<{ name: string; command: string; args?: string[]; env?: Array<{ name: string; value: string }> }>;
-  mcpEndpoint?: { url: string; token: string; serverNames: string[] };
+  mcpEndpoint?: { token: string; serverNames: string[] };
   additionalDirectories?: string[];
   modeId?: string;
   modelId?: string;
@@ -73,13 +75,13 @@ interface AcpMessagePayload {
 
 // Summarize the MCP configuration of an acp:start/acp:resume payload for logs,
 // without leaking the endpoint token.
-function describeMcpConfig(data: { mcpServers?: unknown[]; mcpEndpoint?: { url: string; serverNames?: string[] } }): string {
+function describeMcpConfig(data: { mcpServers?: unknown[]; mcpEndpoint?: { serverNames?: string[] } }): string {
   const parts: string[] = [];
   if (data.mcpServers && data.mcpServers.length > 0) {
     parts.push(`mcpServers=${data.mcpServers.length}`);
   }
   if (data.mcpEndpoint) {
-    parts.push(`mcpEndpoint(url=${data.mcpEndpoint.url}, serverNames=${JSON.stringify(data.mcpEndpoint.serverNames ?? null)})`);
+    parts.push(`mcpEndpoint(serverNames=${JSON.stringify(data.mcpEndpoint.serverNames ?? null)})`);
   }
   return parts.length > 0 ? `mcp=[${parts.join(' ')}]` : 'mcp=[none]';
 }
@@ -132,7 +134,7 @@ interface AcpResumePayload {
   externalSessionId: string;
   serverType: string;
   cwd: string;
-  mcpEndpoint?: { url: string; token: string; serverNames: string[] };
+  mcpEndpoint?: { token: string; serverNames: string[] };
   additionalDirectories?: string[];
   modeId?: string;
   modelId?: string;
@@ -215,6 +217,15 @@ export function connectToServer(
 
   const heartbeat = new Heartbeat();
   const controllerName = options?.serverName || hostname();
+  const mcpRelay = new McpRelay((payload) => socket.emit('mcp:request', payload));
+  const localServer = new LocalMcpServer(mcpRelay);
+  // 回环 HTTP 服务在守护进程内只启动一次、进程退出前不停止（提案 Phase 2 要求全守护进程共享一个端口）。
+  // 断线快速失败由 mcpRelay.handleDisconnect()（503）承担，无需随 socket 连接启停 HTTP 服务。
+  // ready promise 保证 acp:start/acp:resume 读取 localServer.port 前服务已 listening（启动只 await 一次）。
+  const mcpServerReady = localServer.start();
+  mcpServerReady.catch((err: Error) => {
+    console.error(`[MCP] failed to start local MCP endpoint: ${err.message}`);
+  });
 
   // Seed the fs:remove-dir whitelist with cwds of ACP processes that survived
   // a controller restart (their worktrees remain controller-managed).
@@ -246,6 +257,13 @@ export function connectToServer(
 
   socket.on('error', (data: ErrorPayload) => {
     console.error(`Server error: ${data.code} - ${data.message}`);
+    if (data.code === 'VERSION_MISMATCH') {
+      console.error('The agent-controller version is not supported by the server.');
+      console.error('Please upgrade agent-controller to 2.x (npm i -g agent-gear@2 or the matching release).');
+      socket.disconnect();
+      process.exit(1);
+      return;
+    }
     if (data.code === 'KEY_ALREADY_ONLINE') {
       console.log('Clearing resume token and retrying connection...');
       clearResumeTokenFromConfig();
@@ -319,11 +337,23 @@ export function connectToServer(
         await existingBridge.stop().catch(() => {});
       }
       const spawner = createSpawner(data.serverType, data.sessionId, data.cwd);
+      if (data.mcpEndpoint) {
+        // 确保回环服务已 listening 后再读取 port 并注入（启动失败时 fail loudly，不静默注入端口 0）
+        await mcpServerReady;
+        if (localServer.port <= 0) {
+          throw new Error(`MCP endpoint unavailable: local loopback server not listening (port=${localServer.port})`);
+        }
+        mcpRelay.registerSession(data.sessionId, {
+          token: data.mcpEndpoint.token,
+          serverNames: data.mcpEndpoint.serverNames,
+        });
+      }
       const bridge = new AcpSessionBridge(socket, {
         sessionId: data.sessionId,
         cwd: data.cwd,
         mcpServers: data.mcpServers,
         mcpEndpoint: data.mcpEndpoint,
+        mcpPort: localServer.port,
         additionalDirectories: data.additionalDirectories,
         initialModeId: data.modeId,
         initialModelId: data.modelId,
@@ -338,6 +368,7 @@ export function connectToServer(
       bridge.on('acp:stopped', (payload: { sessionId: string }) => {
         if (payload.sessionId === data.sessionId) {
           processRegistry.deregister(data.sessionId);
+          mcpRelay.unregisterSession(data.sessionId);
         }
       });
 
@@ -406,6 +437,7 @@ export function connectToServer(
         bridge.off('acp:stopped', onStopped);
         acpBridges.delete(data.sessionId);
         processRegistry.deregister(data.sessionId);
+        mcpRelay.unregisterSession(data.sessionId);
         console.log(`[ACP ctrl] emitting acp:start:result: requestId=${data.requestId} sessionId=${data.sessionId} success=false reason=${payload.reason} error=${payload.error ?? 'n/a'}`);
         socket.emit('acp:start:result', {
           requestId: data.requestId,
@@ -422,6 +454,7 @@ export function connectToServer(
       await bridge.start();
     } catch (error) {
       console.error(`[ACP ctrl] bridge.start() failed: ${(error as Error).message}`);
+      mcpRelay.unregisterSession(data.sessionId);
       socket.emit('acp:start:result', {
         requestId: data.requestId,
         sessionId: data.sessionId,
@@ -443,10 +476,22 @@ export function connectToServer(
         await existingBridge.stop().catch(() => {});
       }
       const spawner = createSpawner(data.serverType, data.sessionId, data.cwd);
+      if (data.mcpEndpoint) {
+        // 确保回环服务已 listening 后再读取 port 并注入（启动失败时 fail loudly，不静默注入端口 0）
+        await mcpServerReady;
+        if (localServer.port <= 0) {
+          throw new Error(`MCP endpoint unavailable: local loopback server not listening (port=${localServer.port})`);
+        }
+        mcpRelay.registerSession(data.sessionId, {
+          token: data.mcpEndpoint.token,
+          serverNames: data.mcpEndpoint.serverNames,
+        });
+      }
       const bridge = new AcpSessionBridge(socket, {
         sessionId: data.sessionId,
         cwd: data.cwd,
         mcpEndpoint: data.mcpEndpoint,
+        mcpPort: localServer.port,
         additionalDirectories: data.additionalDirectories,
         // 初始 mode/model：resume 完成后、acp:initialized 之前应用（时序同 acp:start）
         initialModeId: data.modeId,
@@ -459,6 +504,7 @@ export function connectToServer(
       bridge.on('acp:stopped', (payload: { sessionId: string }) => {
         if (payload.sessionId === data.sessionId) {
           processRegistry.deregister(data.sessionId);
+          mcpRelay.unregisterSession(data.sessionId);
         }
       });
 
@@ -497,6 +543,7 @@ export function connectToServer(
         bridge.off('acp:stopped', onStopped);
         acpBridges.delete(data.sessionId);
         processRegistry.deregister(data.sessionId);
+        mcpRelay.unregisterSession(data.sessionId);
         console.log(`[ACP ctrl] emitting acp:resume:result: requestId=${data.requestId} sessionId=${data.sessionId} success=false reason=${payload.reason} error=${payload.error ?? 'n/a'}`);
         socket.emit('acp:resume:result', {
           requestId: data.requestId,
@@ -512,6 +559,7 @@ export function connectToServer(
       await bridge.resume(data.externalSessionId);
     } catch (error) {
       console.error(`[ACP ctrl] bridge.resume() failed: ${(error as Error).message}`);
+      mcpRelay.unregisterSession(data.sessionId);
       socket.emit('acp:resume:result', {
         requestId: data.requestId,
         sessionId: data.sessionId,
@@ -693,6 +741,7 @@ export function connectToServer(
         processRegistry.deregister(data.sessionId);
       }
     }
+    mcpRelay.unregisterSession(data.sessionId);
     if (data.ackRequired) {
       socket.emit('acp:stopped', {
         sessionId: data.sessionId,
@@ -967,6 +1016,7 @@ export function connectToServer(
           }
         } catch { /* process may already be dead */ }
         processRegistry.deregister(entry.sessionId);
+        mcpRelay.unregisterSession(entry.sessionId);
         // Also clean up bridge if present
         const bridge = acpBridges.get(entry.sessionId);
         if (bridge) {
@@ -1014,12 +1064,17 @@ export function connectToServer(
     }
   });
 
+  socket.on('mcp:response', (data: { requestId: string; status: number; body: unknown }) => {
+    mcpRelay.handleMcpResponse(data.requestId, data.status, data.body);
+  });
+
   socket.on('disconnect', (reason) => {
     console.log(`Disconnected: ${reason}`);
     heartbeat.stop();
     gatewayManager.closeAll();
     permissionRequestBridge.clear();
     elicitationRequestBridge.clear();
+    mcpRelay.handleDisconnect();
   });
 
   socket.on('connect_error', (err) => {

package/tests/acp-wire-mcp.test.ts

@@ -49,10 +49,10 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
       sessionId: 'sess-wire',
       cwd: workdir,
       mcpEndpoint: {
-        url: 'http://gateway/mcp/sess-wire',
         token: 'wire-token',
         serverNames: ['fluentui-mcp', 'fs-mcp'],
       },
+      mcpPort: 41234,
     }, spawner);
     return socket;
   }
@@ -76,13 +76,13 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
       {
         type: 'http',
         name: 'fluentui-mcp',
-        url: 'http://gateway/mcp/sess-wire/fluentui-mcp',
+        url: 'http://127.0.0.1:41234/mcp/sess-wire/fluentui-mcp',
         headers: [{ name: 'Authorization', value: 'Bearer wire-token' }],
       },
       {
         type: 'http',
         name: 'fs-mcp',
-        url: 'http://gateway/mcp/sess-wire/fs-mcp',
+        url: 'http://127.0.0.1:41234/mcp/sess-wire/fs-mcp',
         headers: [{ name: 'Authorization', value: 'Bearer wire-token' }],
       },
     ]);
@@ -92,7 +92,7 @@ describe('AcpSessionBridge - MCP wire format (ACP spec)', () => {
     const logLines = logSpy.mock.calls.map((c) => String(c[0]));
     const mcpLog = logLines.find((l) => l.includes('passing MCP servers via session/new'));
     expect(mcpLog).toBeDefined();
-    expect(mcpLog).toContain('fluentui-mcp(type=http, url=http://gateway/mcp/sess-wire/fluentui-mcp, headers=Authorization)');
+    expect(mcpLog).toContain('fluentui-mcp(type=http, url=http://127.0.0.1:41234/mcp/sess-wire/fluentui-mcp, headers=Authorization)');
     expect(mcpLog).not.toContain('wire-token');
   }, 15000);
 

package/tests/socketio-client.test.ts

@@ -9,6 +9,11 @@ const { mockStart, mockStop, MockHeartbeat } = vi.hoisted(() => {
   return { mockStart: start, mockStop: stop, MockHeartbeat: HB };
 });
 
+const { relayInstances, localServerInstances } = vi.hoisted(() => ({
+  relayInstances: [] as Array<Record<string, ReturnType<typeof vi.fn>>>,
+  localServerInstances: [] as Array<{ start: ReturnType<typeof vi.fn>; stop: ReturnType<typeof vi.fn>; port: number }>,
+}));
+
 const { MockAcpSyncBridge, mockBridge } = vi.hoisted(() => {
   const bridge = {
     connect: vi.fn().mockResolvedValue(undefined),
@@ -106,6 +111,32 @@ vi.mock('../src/heartbeat.js', () => ({
   Heartbeat: MockHeartbeat,
 }));
 
+vi.mock('../src/mcp/relay.js', () => ({
+  McpRelay: class {
+    registerSession = vi.fn();
+    unregisterSession = vi.fn();
+    handleDisconnect = vi.fn();
+    handleMcpResponse = vi.fn();
+    hasSession = vi.fn(() => true);
+    hasServer = vi.fn(() => true);
+    forward = vi.fn();
+    constructor() {
+      relayInstances.push(this as never);
+    }
+  },
+}));
+
+vi.mock('../src/mcp/local-server.js', () => ({
+  LocalMcpServer: class {
+    port = 0;
+    start = vi.fn(async () => {});
+    stop = vi.fn(async () => {});
+    constructor() {
+      localServerInstances.push(this as never);
+    }
+  },
+}));
+
 vi.mock('../src/config.js', () => ({
   clearConfigKey: vi.fn(),
   saveKeyToConfig: vi.fn(),
@@ -159,6 +190,8 @@ beforeEach(() => {
   vi.clearAllMocks();
   mockStart.mockClear();
   mockStop.mockClear();
+  relayInstances.length = 0;
+  localServerInstances.length = 0;
   vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
   vi.spyOn(console, 'log').mockImplementation(() => {});
   vi.spyOn(console, 'error').mockImplementation(() => {});
@@ -195,7 +228,7 @@ describe('SocketIO Client', () => {
       expect(mockSocket.emit).toHaveBeenCalledWith('register', {
         key: 'zag_k_1_abc123',
         hostname: 'my-machine',
-        version: '1.1.1',
+        version: '2.0.0',
         resumeToken: undefined,
         homeDir: '/home/user',
         platform: 'linux',
@@ -213,7 +246,7 @@ describe('SocketIO Client', () => {
       expect(mockSocket.emit).toHaveBeenCalledWith('register', {
         key: 'zag_k_1_abc123',
         hostname: 'test-machine',
-        version: '1.1.1',
+        version: '2.0.0',
         resumeToken: undefined,
         homeDir: '/home/user',
         platform: 'linux',
@@ -819,4 +852,161 @@ describe('SocketIO Client', () => {
       expect(killSpy).not.toHaveBeenCalled();
     });
   });
+
+  describe('MCP local endpoint lifecycle', () => {
+    function setup() {
+      bridgeInstances.length = 0;
+      const mockSocket = createMockSocket();
+      vi.mocked(io).mockReturnValue(mockSocket as never);
+      connectToServer('http://localhost:4001', 'zag_k_1_abc123');
+      return mockSocket;
+    }
+
+    it('starts the local loopback server exactly once at daemon startup and never stops on disconnect', async () => {
+      const mockSocket = setup();
+      const server = localServerInstances[0];
+      expect(server).toBeDefined();
+      expect(server.start).toHaveBeenCalledTimes(1);
+
+      // 断线→重连后服务不停止、端口不变（存活会话注入的旧 URL 仍可用）
+      mockSocket._trigger('disconnect', 'transport close');
+      expect(server.stop).not.toHaveBeenCalled();
+      mockSocket._trigger('connect');
+      expect(server.start).toHaveBeenCalledTimes(1);
+      // disconnect 仅触发 relay 快速失败（503），不触碰 HTTP 服务
+      const relay = relayInstances[0];
+      expect(relay.handleDisconnect).toHaveBeenCalled();
+    });
+
+    it('registers the session endpoint and injects the loopback port on acp:start', async () => {
+      const mockSocket = setup();
+      localServerInstances[0].port = 34567;
+      const relay = relayInstances[0];
+
+      mockSocket._trigger('acp:start', {
+        requestId: 'req-mcp',
+        sessionId: 'sess-mcp',
+        serverType: 'opencode',
+        cwd: '/home/user/wt',
+        mcpEndpoint: { token: 'tok-1', serverNames: ['tools', 'proxy'] },
+      });
+
+      await vi.waitFor(() => {
+        expect(relay.registerSession).toHaveBeenCalledWith('sess-mcp', {
+          token: 'tok-1',
+          serverNames: ['tools', 'proxy'],
+        });
+      });
+      await vi.waitFor(() => {
+        expect(mockSocket.emit).toHaveBeenCalledWith('acp:start:result', expect.objectContaining({ sessionId: 'sess-mcp', success: true }));
+      });
+    });
+
+    it('fails loudly (does not inject port 0) when the loopback server is not listening', async () => {
+      const mockSocket = setup();
+      localServerInstances[0].port = 0;
+      const relay = relayInstances[0];
+
+      mockSocket._trigger('acp:start', {
+        requestId: 'req-mcp0',
+        sessionId: 'sess-mcp0',
+        serverType: 'opencode',
+        cwd: '/home/user/wt',
+        mcpEndpoint: { token: 'tok-0', serverNames: ['tools'] },
+      });
+
+      await vi.waitFor(() => {
+        expect(mockSocket.emit).toHaveBeenCalledWith('acp:start:result', expect.objectContaining({
+          sessionId: 'sess-mcp0',
+          success: false,
+        }));
+      });
+      // registerSession 不得被调用（端口校验失败，不注入坏 URL）
+      expect(relay.registerSession).not.toHaveBeenCalledWith('sess-mcp0', expect.anything());
+    });
+
+    it('routes mcp:response to the relay', async () => {
+      const mockSocket = setup();
+      const relay = relayInstances[0];
+
+      mockSocket._trigger('mcp:response', { requestId: 'mcpreq_1', status: 200, body: { jsonrpc: '2.0', id: 1, result: {} } });
+
+      expect(relay.handleMcpResponse).toHaveBeenCalledWith('mcpreq_1', 200, { jsonrpc: '2.0', id: 1, result: {} });
+    });
+
+    it('outputs an upgrade guide and exits on VERSION_MISMATCH', () => {
+      const mockSocket = setup();
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      mockSocket._trigger('error', { code: 'VERSION_MISMATCH', message: 'Version mismatch' });
+
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('upgrade agent-controller'));
+      expect(mockSocket.disconnect).toHaveBeenCalled();
+      expect(process.exit).toHaveBeenCalledWith(1);
+    });
+
+    it('unregisters the session endpoint when the agent process exits on its own (onStopped)', async () => {
+      const mockSocket = setup();
+      localServerInstances[0].port = 34567;
+      const relay = relayInstances[0];
+
+      mockSocket._trigger('acp:start', {
+        requestId: 'req-exit',
+        sessionId: 'sess-exit',
+        serverType: 'opencode',
+        cwd: '/home/user/wt',
+        mcpEndpoint: { token: 'tok-x', serverNames: ['tools'] },
+      });
+      await vi.waitFor(() => {
+        expect(mockSocket.emit).toHaveBeenCalledWith('acp:start:result', expect.objectContaining({ sessionId: 'sess-exit', success: true }));
+      });
+
+      vi.mocked(relay.unregisterSession).mockClear();
+      bridgeInstances[0].emit('acp:stopped', { sessionId: 'sess-exit', reason: 'user_close' });
+
+      expect(relay.unregisterSession).toHaveBeenCalledWith('sess-exit');
+    });
+
+    it('unregisters the session endpoint on acp:stop', async () => {
+      const mockSocket = setup();
+      localServerInstances[0].port = 34567;
+      const relay = relayInstances[0];
+
+      mockSocket._trigger('acp:start', {
+        requestId: 'req-stop',
+        sessionId: 'sess-stop',
+        serverType: 'opencode',
+        cwd: '/home/user/wt',
+        mcpEndpoint: { token: 'tok-s', serverNames: ['tools'] },
+      });
+      await vi.waitFor(() => {
+        expect(mockSocket.emit).toHaveBeenCalledWith('acp:start:result', expect.objectContaining({ sessionId: 'sess-stop', success: true }));
+      });
+
+      vi.mocked(relay.unregisterSession).mockClear();
+      mockSocket._trigger('acp:stop', { sessionId: 'sess-stop' });
+
+      await vi.waitFor(() => {
+        expect(relay.unregisterSession).toHaveBeenCalledWith('sess-stop');
+      });
+    });
+
+    it('unregisters the session endpoint on acp:reconcile kill', async () => {
+      const mockSocket = setup();
+      vi.mocked(processRegistry.listEntries).mockReturnValue([
+        { sessionId: 's-recon', pid: 4444, cwd: '/x', acpServerType: 'opencode', startedAt: '2026-01-01' },
+      ]);
+      const killSpy = vi.spyOn(process, 'kill').mockReturnValue(true as never);
+      vi.mocked(isProcessAlive).mockReturnValue(false);
+      const relay = relayInstances[0];
+      vi.mocked(relay.unregisterSession).mockClear();
+
+      mockSocket._trigger('acp:reconcile', { activeSessionIds: [], pendingKillSessionIds: [] });
+
+      await vi.waitFor(() => {
+        expect(relay.unregisterSession).toHaveBeenCalledWith('s-recon');
+      });
+      expect(killSpy).toHaveBeenCalledWith(-4444, 'SIGTERM');
+    });
+  });
 });