@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.3

package/server/lib/opencode/lifecycle.test.js

@@ -9,12 +9,14 @@ vi.mock('node:child_process', () => ({
 }));
 
 const { createOpenCodeLifecycleRuntime } = await import('./lifecycle.js');
+const { createOpenCodeNetworkRuntime } = await import('./network-runtime.js');
 
 const originalOpencodeBinary = process.env.OPENCODE_BINARY;
 const originalPath = process.env.PATH;
 
 afterEach(() => {
   spawnMock.mockReset();
+  vi.useRealTimers();
   vi.unstubAllGlobals();
   if (typeof originalOpencodeBinary === 'string') {
     process.env.OPENCODE_BINARY = originalOpencodeBinary;
@@ -57,6 +59,7 @@ const createRuntime = (overrides = {}, stateRef = null) => {
     openCodeApiDetectionTimer: null,
     lastOpenCodeError: null,
     isOpenCodeReady: false,
+    v1Migration: null,
     openCodeNotReadySince: 0,
     isExternalOpenCode: false,
     isShuttingDown: false,
@@ -109,6 +112,53 @@ const createRuntime = (overrides = {}, stateRef = null) => {
   });
 };
 
+const jsonResponse = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { 'content-type': 'application/json' },
+});
+
+const DEFAULT_V2_HEALTH = { version: '2.0.12', pid: 1, urls: [], paths: { tmp: '/tmp' } };
+
+const stubOpenCodeFetch = (overrides = {}) => {
+  const fetchMock = vi.fn(async (url, init) => {
+    const href = String(url);
+    if (href.includes('/api/experimental/migration/v1')) {
+      const migration = overrides.migration;
+      if (typeof migration === 'function') {
+        return migration(url, init);
+      }
+      if (migration && typeof migration === 'object' && Number.isInteger(migration.httpStatus)) {
+        return jsonResponse(migration.body ?? {}, migration.httpStatus);
+      }
+      return jsonResponse(migration ?? { status: 'completed' });
+    }
+    if (href.includes('/api/info') || href.includes('/global/health')) {
+      if (overrides.reuseDefaultServe !== true && href.includes(':4096/')) {
+        return new Response('not found', { status: 404 });
+      }
+      const health = overrides.health;
+      if (typeof health === 'function') {
+        return health(url, init);
+      }
+      return jsonResponse(health ?? DEFAULT_V2_HEALTH);
+    }
+    return new Response('not found', { status: 404 });
+  });
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+};
+
+const startListeningChild = () => {
+  const child = createMockChild();
+  spawnMock.mockImplementationOnce(() => {
+    queueMicrotask(() => {
+      child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+    });
+    return child;
+  });
+  return child;
+};
+
 describe('OpenCode lifecycle', () => {
   it('launches managed OpenCode with the managed PATH', async () => {
     delete process.env.OPENCODE_BINARY;
@@ -133,6 +183,173 @@ describe('OpenCode lifecycle', () => {
     await server.close();
   });
 
+  it('allows a polite SIGTERM close that finishes after 400ms without escalating early', async () => {
+    vi.useFakeTimers();
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    child.kill = vi.fn((signal) => {
+      if (signal === 'SIGTERM') {
+        // Slow-but-healthy flush: exits after 800ms (>400ms), still under 2500ms grace.
+        setTimeout(() => {
+          child.signalCode = 'SIGTERM';
+          child.emit('close', null, 'SIGTERM');
+        }, 800);
+      }
+      return true;
+    });
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+      });
+      return child;
+    });
+    stubOpenCodeFetch();
+
+    const runtime = createRuntime();
+    const server = await runtime.startOpenCode();
+    const closePromise = server.close();
+
+    await vi.advanceTimersByTimeAsync(400);
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM');
+    expect(child.kill).not.toHaveBeenCalledWith('SIGKILL');
+
+    await vi.advanceTimersByTimeAsync(400);
+    await closePromise;
+    expect(child.kill).not.toHaveBeenCalledWith('SIGKILL');
+    vi.useRealTimers();
+  });
+
+  it('escalates a hung managed child to SIGKILL only after the full 2500ms SIGTERM grace', async () => {
+    vi.useFakeTimers();
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    child.kill = vi.fn((signal) => {
+      if (signal === 'SIGKILL') {
+        child.signalCode = 'SIGKILL';
+        queueMicrotask(() => child.emit('close', null, 'SIGKILL'));
+      }
+      return true;
+    });
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+      });
+      return child;
+    });
+    stubOpenCodeFetch();
+
+    const runtime = createRuntime();
+    const server = await runtime.startOpenCode();
+    const closePromise = server.close();
+
+    await vi.advanceTimersByTimeAsync(2499);
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM');
+    expect(child.kill).not.toHaveBeenCalledWith('SIGKILL');
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(child.kill).toHaveBeenCalledWith('SIGKILL');
+    await vi.advanceTimersByTimeAsync(1000);
+    await closePromise;
+    vi.useRealTimers();
+  });
+
+  it('killProcessOnPort only signals the owned pid and never mass-kills by port', async () => {
+    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+      });
+      return child;
+    });
+    stubOpenCodeFetch();
+
+    const runtime = createRuntime();
+    await runtime.startOpenCode();
+    killSpy.mockClear();
+
+    runtime.killProcessOnPort(45678);
+    expect(killSpy).not.toHaveBeenCalled();
+
+    runtime.killProcessOnPort(45678, 4242);
+    expect(killSpy).toHaveBeenCalledWith(-4242, 'SIGKILL');
+    expect(killSpy).toHaveBeenCalledWith(4242, 'SIGKILL');
+    expect(killSpy.mock.calls.every(([target]) => target === -4242 || target === 4242)).toBe(true);
+
+    killSpy.mockRestore();
+  });
+
+  it('parses a v2 server listening line without the opencode prefix', async () => {
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+      });
+      return child;
+    });
+
+    const runtime = createRuntime();
+    const server = await runtime.startOpenCode();
+
+    expect(server.url).toBe('http://127.0.0.1:45678');
+
+    await server.close();
+  });
+
+  it('probes /api/info with Basic auth after the managed server is listening', async () => {
+    delete process.env.OPENCODE_BINARY;
+    const child = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => {
+        child.stdout.emit('data', 'server listening on http://127.0.0.1:45678\n');
+      });
+      return child;
+    });
+
+    const fetchMock = vi.fn(async (url) => {
+      if (String(url).includes('/api/info')) {
+        return new Response(JSON.stringify(DEFAULT_V2_HEALTH), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      if (String(url).includes('/api/experimental/migration/v1')) {
+        return new Response(JSON.stringify({ status: 'completed' }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      return new Response('not found', { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const authHeaders = { Authorization: 'Basic Zml4dHVyZQ==' };
+    const network = createOpenCodeNetworkRuntime({
+      state: {
+        openCodePort: 45678,
+        openCodeBaseUrl: null,
+        openCodeApiPrefix: '',
+        openCodeApiPrefixDetected: false,
+        openCodeApiDetectionTimer: null,
+      },
+      getOpenCodeAuthHeaders: () => authHeaders,
+    });
+    const runtime = createRuntime({
+      getOpenCodeAuthHeaders: () => authHeaders,
+      waitForReady: network.waitForReady,
+    });
+    const server = await runtime.startOpenCode();
+    const healthCall = fetchMock.mock.calls.find((call) => String(call[0]).includes('/api/info'));
+
+    expect(healthCall).toBeDefined();
+    expect(String(healthCall[0])).toContain('/api/info');
+    expect(healthCall[1].headers.Authorization).toMatch(/^Basic /);
+
+    await server.close();
+  });
+
   it('prepares a fresh managed capability environment and records the spawned child pid', async () => {
     const child = createMockChild();
     spawnMock.mockImplementationOnce(() => {
@@ -298,7 +515,7 @@ describe('OpenCode lifecycle', () => {
     stateRef.current.openCodeProcess = managedChild;
     stateRef.current.openCodePort = 45678;
     stateRef.current.isExternalOpenCode = false;
-    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ healthy: true }), { status: 200 })));
+    stubOpenCodeFetch();
     await runtime.bootstrapOpenCodeAtStartup();
     expect(managedChild.close).toHaveBeenCalledTimes(1);
     expect(stateRef.current.openCodeProcess).toBeNull();
@@ -324,7 +541,7 @@ describe('OpenCode lifecycle', () => {
     }, stateRef);
     stateRef.current.isExternalOpenCode = true;
     stateRef.current.openCodeBaseUrl = 'http://127.0.0.1:3001';
-    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ healthy: true }), { status: 200 })));
+    stubOpenCodeFetch();
 
     await runtime.bootstrapOpenCodeAtStartup();
 
@@ -367,6 +584,7 @@ describe('OpenCode lifecycle', () => {
       clearResolvedOpenCodeBinary,
     }, stateRef);
     const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
+    stubOpenCodeFetch();
 
     await runtime.bootstrapOpenCodeAtStartup();
     expect(spawnMock).not.toHaveBeenCalled();
@@ -378,10 +596,7 @@ describe('OpenCode lifecycle', () => {
       });
       return child;
     });
-    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ healthy: true }), {
-      status: 200,
-      headers: { 'content-type': 'application/json' },
-    })));
+    stubOpenCodeFetch();
 
     try {
       await runtime.retryOpenCodeStartup();
@@ -393,4 +608,481 @@ describe('OpenCode lifecycle', () => {
       await stateRef.current.openCodeProcess?.close();
     }
   });
+
+  it('does not mark OpenCode ready for messages while V1 migration is required', async () => {
+    delete process.env.OPENCODE_BINARY;
+    startListeningChild();
+    const stateRef = {};
+    stubOpenCodeFetch({ migration: { status: 'required' } });
+    const runtime = createRuntime({}, stateRef);
+
+    const server = await runtime.startOpenCode();
+
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: false,
+      phase: 'required',
+    });
+
+    await server.close();
+  });
+
+  it('keeps the ready gate closed while waitForOpenCodeReady sees required migration', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stubOpenCodeFetch({
+      migration: { status: 'required' },
+    });
+
+    await expect(runtime.waitForOpenCodeReady(250, 40)).rejects.toThrow(/V1 migration is required/);
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: false,
+      phase: 'required',
+    });
+  });
+
+  it('marks OpenCode ready for messages after V1 migration completed', async () => {
+    delete process.env.OPENCODE_BINARY;
+    startListeningChild();
+    const stateRef = {};
+    stubOpenCodeFetch({ migration: { status: 'completed' } });
+    const runtime = createRuntime({}, stateRef);
+
+    const server = await runtime.startOpenCode();
+
+    expect(stateRef.current.isOpenCodeReady).toBe(true);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: true,
+      phase: 'completed',
+    });
+
+    await server.close();
+  });
+
+  it('admits messages when V1 migration is absent', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stubOpenCodeFetch({
+      migration: { httpStatus: 404, body: {} },
+    });
+
+    await runtime.waitForOpenCodeReady(1000, 40);
+
+    expect(stateRef.current.isOpenCodeReady).toBe(true);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: true,
+      phase: 'absent',
+    });
+  });
+
+  it('retries V1 migration error and still blocks messages until completed', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    let migrationCalls = 0;
+    const fetchMock = stubOpenCodeFetch({
+      migration: () => {
+        migrationCalls += 1;
+        if (migrationCalls === 1) {
+          return jsonResponse({ status: 'error', error: 'locked' });
+        }
+        return jsonResponse({ status: 'completed' });
+      },
+    });
+
+    await runtime.waitForOpenCodeReady(2000, 40);
+
+    expect(migrationCalls).toBeGreaterThan(1);
+    expect(fetchMock.mock.calls.some((call) => String(call[0]).includes('/api/experimental/migration/v1'))).toBe(true);
+    expect(fetchMock.mock.calls.every((call) => !call[1] || call[1].method !== 'POST')).toBe(true);
+    expect(stateRef.current.isOpenCodeReady).toBe(true);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: true,
+      phase: 'completed',
+    });
+  });
+
+  it('publishes v1Migration on lifecycle state for health snapshot', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stubOpenCodeFetch({
+      migration: {
+        status: 'running',
+        progress: { label: 'Sessions', numerator: 2, denominator: 8 },
+      },
+    });
+
+    await expect(runtime.waitForOpenCodeReady(200, 40)).rejects.toThrow(/V1 migration is running/);
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.v1Migration).toMatchObject({
+      admitTranscript: false,
+      phase: 'running',
+      progress: { label: 'Sessions', numerator: 2, denominator: 8 },
+    });
+    expect(stateRef.current.v1Migration.userNotice).toContain('V1 subtasks do not appear in v2');
+  });
+
+  it('clears v1Migration when an external OpenCode restart probe fails', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({
+      env: {
+        ENV_CONFIGURED_OPENCODE_PORT: null,
+        ENV_CONFIGURED_OPENCODE_HOST: null,
+        ENV_EFFECTIVE_PORT: 45678,
+        ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
+        ENV_SKIP_OPENCODE_START: false,
+      },
+    }, stateRef);
+    stateRef.current.isExternalOpenCode = true;
+    stateRef.current.openCodePort = 45678;
+    stateRef.current.openCodeBaseUrl = 'http://127.0.0.1:45678';
+    stateRef.current.v1Migration = { admitTranscript: true, phase: 'completed' };
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ healthy: false }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })));
+
+    await expect(runtime.restartOpenCode()).rejects.toThrow('External OpenCode server on port 45678 is not responding');
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.v1Migration).toBeNull();
+    // Read-only external mount: failed re-probe keeps port + ownership; never spawn.
+    expect(stateRef.current.openCodePort).toBe(45678);
+    expect(stateRef.current.isExternalOpenCode).toBe(true);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('rejects healthy 1.x health bodies instead of admitting the process', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stubOpenCodeFetch({ health: { healthy: true, version: '1.15.0' } });
+
+    await expect(runtime.waitForOpenCodeReady(300, 40)).rejects.toThrow(/unhealthy|Timed out|1\.|version/i);
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+  });
+
+  it('rejects healthy responses with a missing version', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stubOpenCodeFetch({ health: { healthy: true } });
+
+    await expect(runtime.waitForOpenCodeReady(300, 40)).rejects.toThrow();
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+  });
+
+  it('health version + migration matrix: v2+completed admits, v2+running blocks, 1.x blocks', async () => {
+    const cases = [
+      { health: DEFAULT_V2_HEALTH, migration: { status: 'completed' }, admit: true },
+      { health: DEFAULT_V2_HEALTH, migration: { status: 'running' }, admit: false },
+      { health: DEFAULT_V2_HEALTH, migration: { status: 'required' }, admit: false },
+      { health: DEFAULT_V2_HEALTH, migration: { status: 'error', error: 'disk' }, admit: false },
+      { health: { healthy: true, version: '1.18.18' }, migration: { status: 'completed' }, admit: false },
+    ];
+
+    for (const entry of cases) {
+      const stateRef = {};
+      const runtime = createRuntime({}, stateRef);
+      stateRef.current.openCodePort = 45678;
+      stubOpenCodeFetch({ health: entry.health, migration: entry.migration });
+      if (entry.admit) {
+        await runtime.waitForOpenCodeReady(1000, 40);
+        expect(stateRef.current.isOpenCodeReady).toBe(true);
+      } else {
+        await expect(runtime.waitForOpenCodeReady(250, 40)).rejects.toThrow();
+        expect(stateRef.current.isOpenCodeReady).toBe(false);
+      }
+    }
+  });
+
+  it('aborts a hung migration probe with the same per-attempt signal after health', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    let migrationStarted = 0;
+    let sawAbort = false;
+    stubOpenCodeFetch({
+      health: DEFAULT_V2_HEALTH,
+      migration: (_url, init) => {
+        migrationStarted += 1;
+        return new Promise((_resolve, reject) => {
+          const signal = init?.signal;
+          if (!signal) {
+            reject(new Error('migration probe missing abort signal'));
+            return;
+          }
+          if (signal.aborted) {
+            sawAbort = true;
+            reject(new DOMException('Aborted', 'AbortError'));
+            return;
+          }
+          signal.addEventListener('abort', () => {
+            sawAbort = true;
+            reject(new DOMException('Aborted', 'AbortError'));
+          }, { once: true });
+        });
+      },
+    });
+
+    // Default per-attempt health timeout is 5s; outer deadline must exceed it once
+    // so the hung migration is aborted by the attempt timer, not only the loop exit.
+    const started = Date.now();
+    await expect(runtime.waitForOpenCodeReady(6500, 50)).rejects.toThrow();
+    const elapsed = Date.now() - started;
+    expect(migrationStarted).toBeGreaterThan(0);
+    expect(sawAbort).toBe(true);
+    expect(elapsed).toBeLessThan(12_000);
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+  }, 15_000);
+
+  it('revokes execution permit on restart and ignores stale async health for a new generation', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({}, stateRef);
+    stateRef.current.openCodePort = 45678;
+    stateRef.current.runtimeContractGeneration = 1;
+    stateRef.current.runtimeContract = {
+      executionAllowed: true,
+      phase: 'ready',
+      serveVersion: '2.0.12',
+      instanceGeneration: 1,
+    };
+
+    const genBefore = runtime.revokeRuntimeExecutionPermit('test-restart');
+    expect(genBefore).toBe(2);
+    expect(stateRef.current.runtimeContract.executionAllowed).toBe(false);
+    expect(stateRef.current.runtimeContract.phase).toBe('pending');
+    expect(stateRef.current.runtimeContract.instanceGeneration).toBe(2);
+
+    // Stale probe from generation 1 must not re-open execution on generation 2.
+    runtime.refreshRuntimeContractFromProbe(
+      {
+        ok: true,
+        version: '2.0.12',
+        authenticated: true,
+        healthOk: true,
+      },
+      { admitTranscript: true, phase: 'done', error: null },
+      1,
+    );
+    expect(stateRef.current.runtimeContract.executionAllowed).toBe(false);
+    expect(stateRef.current.runtimeContract.instanceGeneration).toBe(2);
+
+    // Matching generation publishes verified permit.
+    runtime.refreshRuntimeContractFromProbe(
+      {
+        ok: true,
+        version: '2.0.12',
+        authenticated: true,
+        healthOk: true,
+      },
+      { admitTranscript: true, phase: 'done', error: null },
+      2,
+    );
+    expect(stateRef.current.runtimeContract.executionAllowed).toBe(true);
+    expect(stateRef.current.runtimeContract.instanceGeneration).toBe(2);
+    expect(stateRef.current.runtimeContract.serveVersion).toBe('2.0.12');
+  });
+
+  it('does not mark external skip-start ready before version and migration admit', async () => {
+    const stateRef = {};
+    const runtime = createRuntime({
+      env: {
+        ENV_CONFIGURED_OPENCODE_PORT: null,
+        ENV_CONFIGURED_OPENCODE_HOST: { origin: 'http://127.0.0.1:3001' },
+        ENV_EFFECTIVE_PORT: 3001,
+        ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
+        ENV_SKIP_OPENCODE_START: true,
+      },
+      syncFromHmrState: vi.fn(),
+    }, stateRef);
+    // Reject health so bootstrap's waitForOpenCodeReady fails quickly without a
+    // 20s migration spin, while still proving skip-start never pre-admits ready.
+    stubOpenCodeFetch({ health: { healthy: true, version: '1.15.0' } });
+
+    await runtime.bootstrapOpenCodeAtStartup();
+
+    expect(stateRef.current.isExternalOpenCode).toBe(true);
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.openCodePort).toBe(3001);
+  }, 25_000);
+});
+
+describe('shared official OpenCode service', () => {
+  const UNCONFIGURED_ENV = {
+    ENV_CONFIGURED_OPENCODE_PORT: null,
+    ENV_CONFIGURED_OPENCODE_HOST: null,
+    ENV_EFFECTIVE_PORT: null,
+    ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
+    ENV_SKIP_OPENCODE_START: false,
+  };
+  const REGISTRATION = {
+    origin: 'http://127.0.0.1:49374',
+    port: 49374,
+    pid: process.pid,
+    password: 'service-password',
+    version: '2.0.12',
+  };
+
+  const createSharedService = (overrides = {}) => ({
+    registrationFile: '/state/opencode/service.json',
+    buildStartEnv: (env) => {
+      const { OPENCODE_SERVER_PASSWORD: _password, ...rest } = env;
+      return rest;
+    },
+    start: vi.fn(async () => {}),
+    readRegistration: vi.fn(async () => REGISTRATION),
+    ...overrides,
+  });
+
+  const stubSharedFetch = () => {
+    const base = stubOpenCodeFetch();
+    const fetchMock = vi.fn(async (url, init) => (String(url).includes('/api/location/reload')
+      ? new Response(null, { status: 204 })
+      : base(url, init)));
+    vi.stubGlobal('fetch', fetchMock);
+    return fetchMock;
+  };
+
+  it('attaches to the registered service instead of spawning a private serve', async () => {
+    process.env.OPENCODE_BINARY = '/mock/opencode';
+    const sharedService = createSharedService();
+    const adoptOpenCodeServerPassword = vi.fn();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword }, stateRef);
+    const fetchMock = stubSharedFetch();
+
+    await runtime.bootstrapOpenCodeAtStartup();
+
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(sharedService.start).toHaveBeenCalledTimes(1);
+    const startInput = sharedService.start.mock.calls[0][0];
+    expect(startInput.binary).toBe('/mock/opencode');
+    expect(startInput.env.OPENCODE_SERVER_PASSWORD).toBeUndefined();
+    expect(adoptOpenCodeServerPassword).toHaveBeenCalledWith('service-password', 'shared-service');
+    expect(stateRef.current.isExternalOpenCode).toBe(true);
+    expect(stateRef.current.openCodeBaseUrl).toBe('http://127.0.0.1:49374');
+    expect(stateRef.current.openCodePort).toBe(49374);
+    expect(runtime.isSharedOpenCodeService()).toBe(true);
+    // The leftover private serve on 4096 is never probed once the service wins.
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes(':4096/'))).toBe(false);
+  });
+
+  it('reports shared startup failure without probing or spawning a private serve, and can retry', async () => {
+    process.env.OPENCODE_BINARY = '/mock/opencode';
+    const sharedService = createSharedService({ start: vi.fn(async () => { throw new Error('boom'); }) });
+    const adoptOpenCodeServerPassword = vi.fn();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword }, stateRef);
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const fetchMock = stubSharedFetch();
+
+    await runtime.bootstrapOpenCodeAtStartup();
+
+    expect(adoptOpenCodeServerPassword).toHaveBeenLastCalledWith(null, null);
+    expect(runtime.isSharedOpenCodeService()).toBe(false);
+    expect(stateRef.current.isExternalOpenCode).toBe(false);
+    expect(stateRef.current.openCodeBaseUrl).toBeNull();
+    expect(stateRef.current.openCodeProcess).toBeNull();
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.lastOpenCodeError).toBe('boom');
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    sharedService.start.mockResolvedValue(undefined);
+    await runtime.bootstrapOpenCodeAtStartup();
+    expect(runtime.isSharedOpenCodeService()).toBe(true);
+    expect(stateRef.current.isOpenCodeReady).toBe(true);
+  });
+
+  it('reconnects using updated registration without replacing the service', async () => {
+    const sharedService = createSharedService();
+    const adoptOpenCodeServerPassword = vi.fn();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword }, stateRef);
+    stubSharedFetch();
+    await runtime.bootstrapOpenCodeAtStartup();
+    sharedService.readRegistration.mockResolvedValue({ ...REGISTRATION, port: 49375, origin: 'http://127.0.0.1:49375', password: 'rotated' });
+
+    await runtime.restartOpenCode();
+
+    expect(sharedService.start.mock.lastCall[0].replace).toBe(false);
+    expect(stateRef.current.openCodePort).toBe(49375);
+    expect(adoptOpenCodeServerPassword).toHaveBeenLastCalledWith('rotated', 'shared-service');
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('reattaches shared ownership across HMR and retires an old private child', async () => {
+    const sharedService = createSharedService();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService }, stateRef);
+    const close = vi.fn();
+    stateRef.current.openCodeProcess = { pid: 12345, close };
+    stateRef.current.openCodePort = 4096;
+    stubSharedFetch();
+    await runtime.bootstrapOpenCodeAtStartup();
+    expect(close).toHaveBeenCalledOnce();
+    expect(stateRef.current.openCodeProcess).toBeNull();
+    expect(runtime.isSharedOpenCodeService()).toBe(true);
+    await runtime.bootstrapOpenCodeAtStartup();
+    expect(runtime.isSharedOpenCodeService()).toBe(true);
+    expect(stateRef.current.isExternalOpenCode).toBe(true);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('uses the explicit upgrade binary without settings rediscovery and propagates replacement failures', async () => {
+    const sharedService = createSharedService();
+    const applyOpencodeBinaryFromSettings = vi.fn();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, applyOpencodeBinaryFromSettings }, stateRef);
+    stubSharedFetch();
+    await runtime.bootstrapOpenCodeAtStartup();
+    applyOpencodeBinaryFromSettings.mockClear();
+
+    await runtime.restartOpenCode({ binaryPath: '/cache/opencode-cli/2.0.14/opencode' });
+
+    expect(sharedService.start.mock.lastCall[0]).toMatchObject({ binary: '/cache/opencode-cli/2.0.14/opencode', replace: true });
+    expect(applyOpencodeBinaryFromSettings).not.toHaveBeenCalled();
+    sharedService.start.mockRejectedValue(new Error('replacement failed'));
+    await expect(runtime.restartOpenCode({ binaryPath: '/cache/opencode-cli/2.0.14/opencode' })).rejects.toThrow('replacement failed');
+    expect(stateRef.current.isOpenCodeReady).toBe(false);
+    expect(stateRef.current.runtimeContract.executionAllowed).toBe(false);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it('reloads config changes in place instead of restarting the shared service', async () => {
+    process.env.OPENCODE_BINARY = '/mock/opencode';
+    const sharedService = createSharedService();
+    const stateRef = {};
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword: vi.fn() }, stateRef);
+    const fetchMock = stubSharedFetch();
+    await runtime.bootstrapOpenCodeAtStartup();
+    fetchMock.mockClear();
+
+    const result = await runtime.refreshOpenCodeAfterConfigChange('plugin add');
+
+    expect(result).toEqual({ reloaded: true, external: true });
+    const reloadCalls = fetchMock.mock.calls.filter(([url]) => String(url).includes('/api/location/reload'));
+    expect(reloadCalls).toHaveLength(1);
+    expect(reloadCalls[0][1]?.method).toBe('POST');
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(sharedService.start).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps an explicitly configured OpenCode port instead of the shared service', async () => {
+    const sharedService = createSharedService();
+    const stateRef = {};
+    const runtime = createRuntime({ sharedService, adoptOpenCodeServerPassword: vi.fn() }, stateRef);
+    stubSharedFetch();
+    startListeningChild();
+
+    await runtime.bootstrapOpenCodeAtStartup();
+
+    expect(sharedService.start).not.toHaveBeenCalled();
+    expect(runtime.isSharedOpenCodeService()).toBe(false);
+    await stateRef.current.openCodeProcess?.close();
+  });
 });