@openchambery/web 2.0.0-beta.1 → 2.0.0-beta.4

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

@@ -16,6 +16,7 @@ const originalPath = process.env.PATH;
 
 afterEach(() => {
   spawnMock.mockReset();
+  vi.useRealTimers();
   vi.unstubAllGlobals();
   if (typeof originalOpencodeBinary === 'string') {
     process.env.OPENCODE_BINARY = originalOpencodeBinary;
@@ -182,6 +183,103 @@ 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();
@@ -741,6 +839,54 @@ describe('OpenCode lifecycle', () => {
     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({
@@ -764,3 +910,179 @@ describe('OpenCode lifecycle', () => {
     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();
+  });
+});

package/server/lib/opencode/managed-capabilities-runtime.js

@@ -122,15 +122,28 @@ export const createManagedCapabilitiesRuntime = ({
     bridgeOrigin = parsed.origin;
   };
 
+  const publishHostShim = async () => {
+    const sourceDir = pathLike.join(pathLike.dirname(fileURLToPath(import.meta.url)), 'v2-plugin-host-shim');
+    const target = pathLike.join(dataDir, 'managed-opencode-capabilities', 'v2-plugin-host-shim');
+    await fsLike.mkdir(target, { recursive: true });
+    await Promise.all(['package.json', 'index.mjs'].map((name) => fsLike.copyFile(pathLike.join(sourceDir, name), pathLike.join(target, name))));
+    return target;
+  };
+
   const prepareManagedChildEnv = async (baseEnv = {}) => {
     if (!bridgeOrigin) throw new Error('Managed scheduled-task bridge origin is unavailable');
-    const { pluginPath, instructionsPath } = await publishResources();
+    const [{ pluginPath, instructionsPath }, shimDirectory] = await Promise.all([
+      publishResources(),
+      publishHostShim(),
+    ]);
     const token = cryptoLike.randomBytes(32).toString('hex');
     const pluginUrl = pathToFileURL(pluginPath).href;
     identity = { version: materialVersion, origin: bridgeOrigin, token, childPid: null };
+    const merged = JSON.parse(mergeManagedOpenCodeConfig({ configContent: baseEnv.OPENCODE_CONFIG_CONTENT, pluginUrl, instructionsUrl: instructionsPath }));
+    merged.plugin = stableDedupe([...(Array.isArray(merged.plugin) ? merged.plugin : []), shimDirectory]);
     return {
       ...baseEnv,
-      OPENCODE_CONFIG_CONTENT: mergeManagedOpenCodeConfig({ configContent: baseEnv.OPENCODE_CONFIG_CONTENT, pluginUrl, instructionsUrl: instructionsPath }),
+      OPENCODE_CONFIG_CONTENT: JSON.stringify(merged),
       OPENCHAMBER_SCHEDULED_TASK_BRIDGE_ORIGIN: bridgeOrigin,
       OPENCHAMBER_SCHEDULED_TASK_BRIDGE_PATH: MANAGED_SCHEDULED_TASK_TOOL_PATH,
       OPENCHAMBER_SCHEDULED_TASK_TOKEN_HEADER: MANAGED_SCHEDULED_TASK_TOKEN_HEADER,

package/server/lib/opencode/managed-capabilities-runtime.test.js

@@ -24,6 +24,7 @@ describe('managed OpenCode capabilities runtime', () => {
       runtime.recordManagedChildPid(44);
       const identity = runtime.getCapabilityIdentity();
       expect(childEnv.OPENCODE_CONFIG_CONTENT).toContain('scheduled-task.mjs');
+      expect(JSON.parse(childEnv.OPENCODE_CONFIG_CONTENT).plugin).toContain(path.join(dataDir, 'managed-opencode-capabilities', 'v2-plugin-host-shim'));
       expect(JSON.parse(childEnv.OPENCODE_CONFIG_CONTENT).instructions[0]).toMatch(/^\//);
       expect(childEnv.OPENCHAMBER_SCHEDULED_TASK_BRIDGE_PATH).toBe(MANAGED_SCHEDULED_TASK_TOOL_PATH);
       expect(childEnv.OPENCHAMBER_SCHEDULED_TASK_TOKEN_HEADER).toBe(MANAGED_SCHEDULED_TASK_TOKEN_HEADER);

package/server/lib/opencode/openchamber-routes.js

@@ -14,11 +14,17 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
     getCachedZenModels,
     sessionIndexService,
     sessionIndexSyncRuntime,
+    /** Production: committed Host metadata for archive-aware snapshot/lookup. */
+    getCommittedHostMetadata = null,
     transcriptCacheService,
     express,
   } = dependencies;
 
-  registerSessionIndexRoutes(app, { sessionIndexService, sessionIndexSyncRuntime });
+  registerSessionIndexRoutes(app, {
+    sessionIndexService,
+    sessionIndexSyncRuntime,
+    getCommittedHostMetadata,
+  });
   registerTranscriptCacheRoutes(app, { transcriptCacheService });
   registerConfigSyncRoutes(app, { express });
 

package/server/lib/opencode/opencode2-pin.js

@@ -1,7 +1,7 @@
 // Pinned desktop/runtime opencode2. Upgrade and prepare must not fall back to 1.18.x.
 export const PINNED_OPENCODE2_VERSION = '2.0.12';
 
-// Global npm/bun package that installs the opencode2 binary (not 1.x opencode-ai).
+// Global npm/bun package that installs the opencode v2 binary (not 1.x opencode-ai).
 export const OPENCODE2_NPM_PACKAGE = '@opencode/cli';
 
 export function isOpenCode1xVersion(value) {
@@ -19,8 +19,8 @@ export function isAcceptableOpenCode2HealthVersion(value) {
   if (typeof value !== 'string') return false;
   const normalized = value.trim().replace(/^v/i, '');
   if (!normalized) return false;
-  if (isOpenCode1xVersion(normalized)) return false;
-  // Require a version-like token (semver or next pin), not free-form noise.
+  // Official CLI is 2.x. 1.x and pre-2 names like `opencode2 v0.0.0-beta-*` are not it.
+  if (!/^2(?:\.|$)/.test(normalized)) return false;
   return /^\d+(?:\.\d+)*(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(normalized);
 }
 
@@ -85,7 +85,7 @@ export function openCodeBinaryName(platform = process.platform) {
 
 /** @deprecated Packaging leftover. Runtime install uses `openCodeBinaryName`. */
 export function openCode2BinaryName(platform = process.platform) {
-  return platform === 'win32' ? 'opencode2.exe' : 'opencode2';
+  return openCodeBinaryName(platform);
 }
 
 export function resolveOpenCode2NpmArchitecture(arch = process.arch) {

package/server/lib/opencode/opencode2-pin.test.js

@@ -43,6 +43,7 @@ describe('opencode2 pin (ticket 12)', () => {
   it('accepts authoritative v2 health/info versions and rejects 1.x / missing / noise', () => {
     expect(isAcceptableOpenCode2HealthVersion(PINNED_OPENCODE2_VERSION)).toBe(true);
     expect(isAcceptableOpenCode2HealthVersion('v2.0.12')).toBe(true);
+    expect(isAcceptableOpenCode2HealthVersion('0.0.0-beta-18155')).toBe(false);
     expect(isAcceptableOpenCode2HealthVersion('1.15.0')).toBe(false);
     expect(isAcceptableOpenCode2HealthVersion('v1.18.18')).toBe(false);
     expect(isAcceptableOpenCode2HealthVersion('')).toBe(false);

package/server/lib/opencode/opencode2-sidecar.e2e.test.js

@@ -1,10 +1,18 @@
 import { afterEach, describe, expect, it } from 'bun:test';
+import fs from 'node:fs/promises';
 import net from 'node:net';
+import os from 'node:os';
 import path from 'node:path';
 
+import { readOpenCode2BinaryVersion } from './ensure-cli.js';
 import { createOpenCodeEnvRuntime } from './env-runtime.js';
 import { createOpenCodeLifecycleRuntime } from './lifecycle.js';
 import { createOpenCodeNetworkRuntime } from './network-runtime.js';
+import {
+  evaluateOpenCodeHealthBody,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode1xVersion,
+} from './opencode2-pin.js';
 import { fetchV1MigrationGate } from './v1-migration-gate.js';
 
 const E2E_PASSWORD = 'openchamber-opencode2-e2e';
@@ -12,6 +20,21 @@ const basicAuth = `Basic ${Buffer.from(`opencode:${E2E_PASSWORD}`, 'utf8').toStr
 const OPENCODE2_HEALTH_VERSION = /^(?:v)?(?:0\.0\.0-(?:next|beta)(?:-\d+)?|2(?:\.\d+)*)/i;
 const OPENCODE_1X_VERSION = /^v?1(?:\.|$)/;
 
+/** Env keys that must not leak into the real user OpenCode install during e2e. */
+const ISOLATION_ENV_KEYS = [
+  'HOME',
+  'USERPROFILE',
+  'XDG_DATA_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_STATE_HOME',
+  'OPENCODE_CONFIG',
+  'OPENCODE_CONFIG_DIR',
+  'OPENCODE_CONFIG_CONTENT',
+  'OPENCHAMBER_DATA_DIR',
+  'OPENCHAMBER_MANAGED_PROCESS_REGISTRY',
+];
+
 const freePort = () => new Promise((resolve, reject) => {
   const server = net.createServer();
   server.once('error', reject);
@@ -46,10 +69,72 @@ const jsonPost = async (url, pathname, payload) => {
   return { status: response.status, body };
 };
 
+const snapshotEnv = (keys) => {
+  /** @type {Record<string, string | undefined>} */
+  const snap = {};
+  for (const key of keys) snap[key] = process.env[key];
+  return snap;
+};
+
+const restoreEnv = (snap) => {
+  for (const [key, value] of Object.entries(snap)) {
+    if (typeof value === 'string') process.env[key] = value;
+    else delete process.env[key];
+  }
+};
+
+/**
+ * Point HOME + XDG + OpenChamber data at a fresh temp tree so managed opencode2
+ * never reads/writes the developer's real ~/.config/opencode or
+ * ~/.local/share/opencode (migration/auth/session DB).
+ * Does not seed from the user install — empty isolation only.
+ */
+const installIsolatedOpenCodeHome = async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'openchamber-opencode2-e2e-'));
+  const home = path.join(root, 'home');
+  const xdgData = path.join(root, 'xdg-data');
+  const xdgConfig = path.join(root, 'xdg-config');
+  const xdgCache = path.join(root, 'xdg-cache');
+  const xdgState = path.join(root, 'xdg-state');
+  const openchamberData = path.join(root, 'openchamber-data');
+  const opencodeConfig = path.join(xdgConfig, 'opencode');
+  await Promise.all([
+    fs.mkdir(home, { recursive: true }),
+    fs.mkdir(xdgData, { recursive: true }),
+    fs.mkdir(xdgConfig, { recursive: true }),
+    fs.mkdir(xdgCache, { recursive: true }),
+    fs.mkdir(xdgState, { recursive: true }),
+    fs.mkdir(openchamberData, { recursive: true }),
+    fs.mkdir(opencodeConfig, { recursive: true }),
+  ]);
+
+  process.env.HOME = home;
+  if (process.platform === 'win32') process.env.USERPROFILE = home;
+  process.env.XDG_DATA_HOME = xdgData;
+  process.env.XDG_CONFIG_HOME = xdgConfig;
+  process.env.XDG_CACHE_HOME = xdgCache;
+  process.env.XDG_STATE_HOME = xdgState;
+  process.env.OPENCODE_CONFIG_DIR = opencodeConfig;
+  delete process.env.OPENCODE_CONFIG;
+  delete process.env.OPENCODE_CONFIG_CONTENT;
+  process.env.OPENCHAMBER_DATA_DIR = openchamberData;
+  process.env.OPENCHAMBER_MANAGED_PROCESS_REGISTRY = path.join(openchamberData, 'managed-opencode');
+
+  return root;
+};
+
 describe('opencode2 sidecar e2e', () => {
   let server = null;
+  let isolationRoot = null;
   const previousBinary = process.env.OPENCODE_BINARY;
   const previousPassword = process.env.OPENCODE_PASSWORD;
+  const previousIsolation = snapshotEnv(ISOLATION_ENV_KEYS);
+  // Captured at suite load (before installIsolatedOpenCodeHome mutates HOME).
+  const realUserHome = path.resolve(
+    previousIsolation.HOME
+    || previousIsolation.USERPROFILE
+    || os.homedir(),
+  );
 
   afterEach(async () => {
     if (server?.close) {
@@ -66,9 +151,16 @@ describe('opencode2 sidecar e2e', () => {
     } else {
       delete process.env.OPENCODE_PASSWORD;
     }
+    restoreEnv(previousIsolation);
+    if (isolationRoot) {
+      await fs.rm(isolationRoot, { recursive: true, force: true }).catch(() => {});
+      isolationRoot = null;
+    }
   });
 
   it('starts managed opencode2 and serves health, migration, session, and message projection', async () => {
+    // Resolve the v2 binary against the real machine first (PATH + home fallbacks).
+    // Isolation mutates HOME/XDG and would hide ~/.bun/bin and similar fallbacks.
     delete process.env.OPENCODE_BINARY;
     delete process.env.OPENCODE_PATH;
     delete process.env.OPENCHAMBER_OPENCODE_PATH;
@@ -93,7 +185,16 @@ describe('opencode2 sidecar e2e', () => {
 
     const resolved = envRuntime.resolveOpencodeCliPath();
     expect(resolved).toBeTruthy();
-    expect(path.basename(resolved).replace(/\.exe$/i, '')).toBe('opencode2');
+    // Official v2 may install as `opencode` or legacy alias `opencode2`.
+    // Contract is version admission, not basename.
+    const binaryVersion = readOpenCode2BinaryVersion(resolved);
+    expect(isAcceptableOpenCode2HealthVersion(binaryVersion)).toBe(true);
+    expect(isOpenCode1xVersion(binaryVersion)).toBe(false);
+
+    // Isolate HOME/XDG/OpenChamber data BEFORE spawn so migration/auth never
+    // touch the developer's real OpenCode store. Absolute OPENCODE_BINARY keeps
+    // the resolved CLI after HOME changes.
+    isolationRoot = await installIsolatedOpenCodeHome();
 
     process.env.OPENCODE_BINARY = resolved;
     process.env.OPENCODE_PASSWORD = E2E_PASSWORD;
@@ -160,6 +261,15 @@ describe('opencode2 sidecar e2e', () => {
       buildManagedOpenCodePath: () => process.env.PATH,
       getManagedOpenCodeShellEnvSnapshot: () => ({
         PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        USERPROFILE: process.env.USERPROFILE,
+        XDG_DATA_HOME: process.env.XDG_DATA_HOME,
+        XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+        XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+        XDG_STATE_HOME: process.env.XDG_STATE_HOME,
+        OPENCODE_CONFIG_DIR: process.env.OPENCODE_CONFIG_DIR,
+        OPENCHAMBER_DATA_DIR: process.env.OPENCHAMBER_DATA_DIR,
+        OPENCHAMBER_MANAGED_PROCESS_REGISTRY: process.env.OPENCHAMBER_MANAGED_PROCESS_REGISTRY,
         OPENCODE_PASSWORD: E2E_PASSWORD,
         OPENCODE_SERVER_PASSWORD: E2E_PASSWORD,
       }),
@@ -167,15 +277,20 @@ describe('opencode2 sidecar e2e', () => {
 
     server = await runtime.startOpenCode();
     expect(server.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
-    expect(String(state.lastOpenCodeLaunchDiagnostics?.binary || '')).toContain('opencode2');
+    const launchedBinary = String(state.lastOpenCodeLaunchDiagnostics?.binary || '');
+    expect(launchedBinary.length).toBeGreaterThan(0);
+    // Launch path must still resolve to the same admitted v2 binary (name may be opencode).
+    expect(isAcceptableOpenCode2HealthVersion(readOpenCode2BinaryVersion(launchedBinary))).toBe(true);
 
     const health = await jsonGet(server.url, '/api/info');
     expect(health.status).toBe(200);
+    const healthGate = evaluateOpenCodeHealthBody(health.body);
+    expect(healthGate.ok).toBe(true);
+    expect(healthGate.version).toMatch(OPENCODE2_HEALTH_VERSION);
+    expect(String(health.body?.version ?? '')).not.toMatch(OPENCODE_1X_VERSION);
     expect(health.body).toMatchObject({
-      healthy: true,
       version: expect.stringMatching(OPENCODE2_HEALTH_VERSION),
     });
-    expect(String(health.body?.version ?? '')).not.toMatch(OPENCODE_1X_VERSION);
 
     const unauthenticated = await fetch(`${server.url}/api/info`);
     expect(unauthenticated.status).toBe(401);
@@ -187,6 +302,14 @@ describe('opencode2 sidecar e2e', () => {
     expect(gate.admitTranscript).toBe(true);
     expect(['completed', 'absent']).toContain(gate.phase);
 
+    // Safety: isolation root must stay under tmp and never equal real user home.
+    expect(isolationRoot.startsWith(os.tmpdir())).toBe(true);
+    expect(path.resolve(process.env.HOME)).not.toBe(path.resolve(realUserHome));
+    // Real user OpenCode paths must remain untouched (no accidental migration write).
+    const realConfigMarker = path.join(realUserHome, '.config', 'opencode');
+    const isolatedConfig = process.env.OPENCODE_CONFIG_DIR;
+    expect(path.resolve(isolatedConfig)).not.toBe(path.resolve(realConfigMarker));
+
     const created = await jsonPost(server.url, '/api/session', {});
     expect(created.status).toBe(200);
     const sessionID = created.body?.data?.id ?? created.body?.id;