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

package/server/lib/opencode/lifecycle.js

@@ -1,6 +1,11 @@
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
 import { registerManagedProcess, unregisterManagedProcess, reapOrphanedProcesses } from './managed-process-registry.js';
+import { evaluateOpenCodeHealthBody } from './opencode2-pin.js';
+import { readOpenCode2BinaryVersion } from './ensure-cli.js';
+import { createRevokedRuntimeContract, evaluateRuntimeContract } from './runtime-contract.js';
+import { OPENCODE_V1_MIGRATION_PATH, fetchV1MigrationGate } from './v1-migration-gate.js';
+import { isProcessAlive } from './shared-service.js';
 
 const parsePositiveInt = (value, fallback) => {
   const parsed = Number.parseInt(String(value ?? ''), 10);
@@ -14,7 +19,18 @@ const HEALTH_CHECK_MAX_CONSECUTIVE_FAILURES = parsePositiveInt(
 );
 const HEALTH_CHECK_INTERVAL_OVERRIDE_MS = parsePositiveInt(process.env.OPENCHAMBER_OPENCODE_HEALTH_INTERVAL_MS, 0);
 const HEALTH_CHECK_RESULT_CACHE_MS = parsePositiveInt(process.env.OPENCHAMBER_OPENCODE_HEALTH_CACHE_MS, 750);
-const OPENCODE_HEALTH_PATH = '/global/health';
+// Official OpenCode 2.x exposes ServerInfo at GET /api/info (client.server.info).
+const OPENCODE_HEALTH_PATH = '/api/info';
+const OPENCODE_HEALTH_FALLBACK_PATH = '/global/health';
+const DEFAULT_OPENCODE_SERVE_PORT = 4096;
+// Polite SIGTERM window before SIGKILL for managed children (restart/OAuth/reload
+// need enough time for clean flush; do not shorten globally for Quit latency).
+const OPENCODE_CHILD_SIGTERM_GRACE_MS = 2500;
+const OPENCODE_CHILD_SIGKILL_WAIT_MS = 1000;
+// Last-used directory plus recently opened projects — deeper tails are unlikely
+// to be the user's first click and just add background work.
+const WARMUP_DIRECTORY_LIMIT = 4;
+const WARMUP_REQUEST_TIMEOUT_MS = 30000;
 
 export const createOpenCodeLifecycleRuntime = (deps) => {
   const {
@@ -28,6 +44,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     normalizeApiPrefix,
     applyOpencodeBinaryFromSettings,
     ensureOpencodeCliEnv,
+    ensurePinnedOpenCode2CliEnv,
     ensureLocalOpenCodeServerPassword,
     resolveManagedOpenCodeLaunchSpec,
     setOpenCodePort,
@@ -40,23 +57,51 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     getManagedOpenCodeShellEnvSnapshot,
     managedCapabilitiesRuntime = null,
     getActiveSessionCount = () => 0,
+    getWarmupDirectories = async () => [],
+    // Official background service (shared-service.js). null keeps the private
+    // managed `opencode serve` path.
+    sharedService = null,
+    adoptOpenCodeServerPassword = null,
   } = deps;
 
-  const killProcessOnPort = (port) => {
-    if (!port || process.platform === 'win32') return;
-    try {
-      const result = spawnSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8', timeout: 5000, windowsHide: true });
-      const output = result.stdout || '';
-      const myPid = process.pid;
-      for (const pidStr of output.split(/\s+/)) {
-        const pid = parseInt(pidStr.trim(), 10);
-        if (pid && pid !== myPid) {
-          try {
-            spawnSync('kill', ['-9', String(pid)], { stdio: 'ignore', timeout: 2000 });
-          } catch {
-          }
-        }
+  // Shared services outlive this runtime. Recovery re-ensures them; only an
+  // explicit binary upgrade replaces them through the official service CLI.
+  let sharedServiceAttached = false;
+  let sharedServicePid = null;
+
+  /**
+   * Force-signal only an owned managed OpenCode pid / process group.
+   * Never lsof-kill by port: that can murder clients still connected to the port
+   * or a newly bound external/shared `opencode serve` that we do not own.
+   * `port` is accepted for call-site compatibility and diagnostics only.
+   */
+  const killProcessOnPort = (port, ownedPid = null) => {
+    const pid = Number(ownedPid);
+    if (!Number.isInteger(pid) || pid <= 0) {
+      return;
+    }
+    if (pid === process.pid) {
+      return;
+    }
+
+    if (process.platform === 'win32') {
+      try {
+        spawnSync('taskkill', ['/pid', String(pid), '/f', '/t'], {
+          stdio: 'ignore',
+          timeout: 5000,
+          windowsHide: true,
+        });
+      } catch {
       }
+      return;
+    }
+
+    try {
+      process.kill(-pid, 'SIGKILL');
+    } catch {
+    }
+    try {
+      process.kill(pid, 'SIGKILL');
     } catch {
     }
   };
@@ -205,13 +250,13 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
     signalProcessTree('SIGTERM');
 
-    if (await waitForChildProcessClose(child, 2500)) {
+    if (await waitForChildProcessClose(child, OPENCODE_CHILD_SIGTERM_GRACE_MS)) {
       return;
     }
 
     signalProcessTree('SIGKILL');
 
-    await waitForChildProcessClose(child, 1000);
+    await waitForChildProcessClose(child, OPENCODE_CHILD_SIGKILL_WAIT_MS);
   };
 
   const closeManagedOpenCodeChild = async (child) => {
@@ -306,8 +351,11 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
           stdout += chunk.toString();
           const lines = stdout.split('\n');
           for (const line of lines) {
-            if (!line.startsWith('opencode server listening')) continue;
-            const match = line.match(/on\s+(https?:\/\/[^\s]+)/);
+            const trimmed = line.trim();
+            // v2 prints `server listening on http://...` without the `opencode `
+            // prefix; 1.x still prints `opencode server listening on ...`.
+            if (!trimmed.startsWith('opencode server listening') && !trimmed.startsWith('server listening')) continue;
+            const match = trimmed.match(/on\s+(https?:\/\/[^\s]+)/);
             if (!match) {
               finish(reject, new Error(`Failed to parse server url from output: ${line}`));
               return;
@@ -403,23 +451,164 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     });
   };
 
+  // Official v2 only publishes GET /api/experimental/migration/v1. Backfill
+  // runs inside opencode2; we poll status and never POST.
+  const probeV1MigrationGate = async (signal) => fetchV1MigrationGate({
+    url: buildOpenCodeUrl(OPENCODE_V1_MIGRATION_PATH, ''),
+    headers: getOpenCodeAuthHeaders(),
+    signal,
+  });
+
+  // Health ok is not enough to pull session messages. required/running/error
+  // keep isOpenCodeReady false so the proxy ready gate still blocks transcript.
+  const applyV1MigrationGate = (gate) => {
+    state.v1Migration = gate;
+    if (gate.admitTranscript) {
+      state.isOpenCodeReady = true;
+      state.openCodeNotReadySince = 0;
+      return true;
+    }
+    state.isOpenCodeReady = false;
+    if (!state.openCodeNotReadySince) {
+      state.openCodeNotReadySince = Date.now();
+    }
+    if (gate.phase === 'error' && gate.error) {
+      state.lastOpenCodeError = gate.error;
+    }
+    return false;
+  };
+
+  // v2 readiness lives at /api/info (ServerInfo.version); /global/health remains
+  // a probe fallback for older sidecars. Both require Basic auth from
+  // getOpenCodeAuthHeaders(). Version admission rejects 1.x / missing / noise.
+  // Health ok is reachability only — execution semantics live on runtimeContract.
+  const fetchOpenCodeHealthResult = async (urlForPath, signal, options = {}) => {
+    const headerCandidates = [
+      { Accept: 'application/json', ...getOpenCodeAuthHeaders(), authenticated: true },
+    ];
+    if (options.allowUnauthenticated) {
+      headerCandidates.push({ Accept: 'application/json', authenticated: false });
+    }
+    let sawUnauthorized = false;
+    let lastGate = null;
+    for (const headerCandidate of headerCandidates) {
+      const { authenticated, ...headers } = headerCandidate;
+      for (const healthPath of [OPENCODE_HEALTH_PATH, OPENCODE_HEALTH_FALLBACK_PATH]) {
+        try {
+          const response = await fetch(urlForPath(healthPath), {
+            method: 'GET',
+            headers,
+            signal,
+          });
+          if (response.status === 401 || response.status === 403) {
+            sawUnauthorized = true;
+            continue;
+          }
+          if (!response.ok) continue;
+          const body = await response.json().catch(() => null);
+          const gate = evaluateOpenCodeHealthBody(body);
+          lastGate = gate;
+          if (gate.ok) {
+            return {
+              ok: true,
+              version: gate.version,
+              authenticated: authenticated !== false,
+              healthOk: true,
+            };
+          }
+        } catch {
+        }
+      }
+    }
+    if (sawUnauthorized && !lastGate?.ok) {
+      return { ok: false, version: null, authenticated: false, healthOk: false, reason: 'auth-failed' };
+    }
+    return {
+      ok: false,
+      version: lastGate?.version ?? null,
+      authenticated: sawUnauthorized ? false : null,
+      healthOk: false,
+      reason: lastGate?.reason || 'unhealthy',
+    };
+  };
+
+  const fetchOpenCodeHealthOk = async (urlForPath, signal, options = {}) => {
+    const result = await fetchOpenCodeHealthResult(urlForPath, signal, options);
+    return result.ok === true;
+  };
+
+  /**
+   * Invalidate any prior execution permit. Start / restart / target changes must
+   * bump generation so in-flight async health probes cannot publish for a newer
+   * instance, and Host/proxy gates stop holding a stale `executionAllowed: true`.
+   * @param {string} [reason]
+   */
+  const revokeRuntimeExecutionPermit = (reason = 'instance-revoked') => {
+    const nextGeneration = (Number(state.runtimeContractGeneration) || 0) + 1;
+    state.runtimeContractGeneration = nextGeneration;
+    state.openCodeServeVersion = null;
+    state.openCodeCliVersion = null;
+    state.runtimeContract = createRevokedRuntimeContract(reason, {
+      instanceGeneration: nextGeneration,
+    });
+    return nextGeneration;
+  };
+
+  /**
+   * Publish contract only for the generation that started the probe.
+   * @param {object | null | undefined} probe
+   * @param {object | null | undefined} migrationGate
+   * @param {number | null | undefined} expectedGeneration
+   */
+  const refreshRuntimeContractFromProbe = (
+    probe,
+    migrationGate = state.v1Migration,
+    expectedGeneration = state.runtimeContractGeneration,
+  ) => {
+    const currentGeneration = Number(state.runtimeContractGeneration) || 0;
+    if (
+      expectedGeneration != null
+      && Number(expectedGeneration) !== currentGeneration
+    ) {
+      // Stale async health / migration result for a superseded instance.
+      return state.runtimeContract;
+    }
+    const binaryPath = typeof process.env.OPENCODE_BINARY === 'string'
+      ? process.env.OPENCODE_BINARY.trim()
+      : '';
+    const cliVersion = binaryPath ? (readOpenCode2BinaryVersion(binaryPath) || null) : null;
+    const contract = evaluateRuntimeContract({
+      serveVersion: probe?.version ?? null,
+      cliVersion,
+      reachable: probe?.ok === true || Boolean(state.openCodePort),
+      authenticated: probe?.authenticated ?? null,
+      healthOk: probe?.healthOk ?? probe?.ok ?? null,
+      migrationAdmitTranscript: migrationGate?.admitTranscript ?? null,
+      migrationPhase: migrationGate?.phase ?? null,
+      migrationError: migrationGate?.error ?? null,
+    });
+    contract.instanceGeneration = currentGeneration;
+    state.openCodeServeVersion = contract.serveVersion;
+    state.openCodeCliVersion = contract.cliVersion;
+    state.runtimeContract = contract;
+    return contract;
+  };
+
   const isOpenCodeProcessHealthy = async () => {
-    if (!state.openCodeProcess || !state.openCodePort) {
+    if ((!state.openCodeProcess && !sharedServiceAttached) || !state.openCodePort) {
       return false;
     }
 
+    const generationAtStart = Number(state.runtimeContractGeneration) || 0;
     try {
-      const response = await fetch(buildOpenCodeUrl(OPENCODE_HEALTH_PATH, ''), {
-        method: 'GET',
-        headers: {
-          Accept: 'application/json',
-          ...getOpenCodeAuthHeaders(),
-        },
-        signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
-      });
-      if (!response.ok) return false;
-      const body = await response.json().catch(() => null);
-      return body?.healthy === true;
+      const result = await fetchOpenCodeHealthResult(
+        (healthPath) => buildOpenCodeUrl(healthPath, ''),
+        AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS)
+      );
+      if (result.ok) {
+        refreshRuntimeContractFromProbe(result, state.v1Migration, generationAtStart);
+      }
+      return result.ok;
     } catch {
       return false;
     }
@@ -430,22 +619,21 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
       return false;
     }
 
+    const generationAtStart = Number(state.runtimeContractGeneration) || 0;
     try {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 3000);
       const base = origin ?? `http://127.0.0.1:${port}`;
-      const response = await fetch(`${base}${OPENCODE_HEALTH_PATH}`, {
-        method: 'GET',
-        headers: {
-          Accept: 'application/json',
-          ...getOpenCodeAuthHeaders(),
-        },
-        signal: controller.signal,
-      });
+      const result = await fetchOpenCodeHealthResult(
+        (healthPath) => `${base}${healthPath}`,
+        controller.signal,
+        { allowUnauthenticated: true },
+      );
       clearTimeout(timeout);
-      if (!response.ok) return false;
-      const body = await response.json().catch(() => null);
-      return body?.healthy === true;
+      if (result.ok) {
+        refreshRuntimeContractFromProbe(result, state.v1Migration, generationAtStart);
+      }
+      return result.ok;
     } catch {
       return false;
     }
@@ -467,12 +655,120 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     throw new Error('Timed out waiting for OpenCode port');
   };
 
+  /**
+   * Ensure the official service is running and point this runtime at its
+   * registration (origin, port, password). Throws when the CLI cannot start it
+   * or the registration is missing/malformed; the caller decides rollback.
+   */
+  const connectSharedOpenCodeService = async ({ binaryPath } = {}) => {
+    if (!binaryPath) {
+      await applyOpencodeBinaryFromSettings({ strict: true });
+      if (typeof ensurePinnedOpenCode2CliEnv === 'function') {
+        await ensurePinnedOpenCode2CliEnv();
+      }
+      ensureOpencodeCliEnv();
+    }
+    let binary = binaryPath || (process.env.OPENCODE_BINARY || 'opencode').trim() || 'opencode';
+    let args = [];
+    if (process.platform === 'win32') {
+      const launchSpec = resolveManagedOpenCodeLaunchSpec(binary);
+      if (launchSpec?.binary) {
+        binary = launchSpec.binary;
+        args = Array.isArray(launchSpec.args) ? launchSpec.args : [];
+      }
+    }
+    const envPath = typeof buildManagedOpenCodePath === 'function'
+      ? buildManagedOpenCodePath()
+      : typeof buildAugmentedPath === 'function'
+        ? buildAugmentedPath()
+        : process.env.PATH;
+    const shellEnv = typeof getManagedOpenCodeShellEnvSnapshot === 'function'
+      ? getManagedOpenCodeShellEnvSnapshot() || {}
+      : {};
+    await sharedService.start({
+      binary,
+      args,
+      replace: Boolean(binaryPath),
+      env: sharedService.buildStartEnv({ ...shellEnv, ...process.env, PATH: envPath }),
+    });
+    const registration = await sharedService.readRegistration();
+    if (!registration) {
+      throw new Error(`OpenCode service started but ${sharedService.registrationFile} is missing or invalid`);
+    }
+    adoptOpenCodeServerPassword?.(registration.password, 'shared-service');
+    state.openCodeBaseUrl = registration.origin;
+    setOpenCodePort(registration.port);
+    sharedServicePid = registration.pid;
+    return registration;
+  };
+
+  /**
+   * Attach to the shared official service instead of spawning a private serve.
+   * Failure leaves integration unavailable and retryable, never silently
+   * starting a private server with different lifecycle semantics.
+   */
+  const attachSharedOpenCodeService = async () => {
+    if (!sharedService) return false;
+    revokeRuntimeExecutionPermit('shared-service-attach');
+    state.isOpenCodeReady = false;
+    state.openCodeNotReadySince = Date.now();
+    try {
+      const registration = await connectSharedOpenCodeService();
+      if (!(await probeExternalOpenCode(registration.port, registration.origin))) {
+        throw new Error(`OpenCode service at ${registration.origin} did not pass the health/version check`);
+      }
+      if (state.openCodeProcess && !state.isExternalOpenCode) {
+        await state.openCodeProcess.close();
+        state.openCodeProcess = null;
+      }
+      sharedServiceAttached = true;
+      state.isExternalOpenCode = true;
+      state.lastOpenCodeError = null;
+      state.v1Migration = null;
+      state.managedCapabilityIdentity = null;
+      managedCapabilitiesRuntime?.setCapabilityIdentity(null);
+      syncToHmrState();
+      console.log(`[OpenCode] Attached to shared OpenCode service at ${registration.origin} (v${registration.version ?? 'unknown'})`);
+      return true;
+    } catch (error) {
+      sharedServiceAttached = false;
+      sharedServicePid = null;
+      state.openCodeBaseUrl = null;
+      state.openCodePort = null;
+      adoptOpenCodeServerPassword?.(null, null);
+      syncToHmrState();
+      throw error;
+    }
+  };
+
+  // `location.reload` rebuilds every loaded location in place: running
+  // sessions continue at the next step boundary and clients get
+  // `location.shutdown` to refetch location services.
+  const reloadSharedOpenCodeLocations = async () => {
+    const response = await fetch(buildOpenCodeUrl('/api/location/reload', ''), {
+      method: 'POST',
+      headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new Error(`OpenCode location reload failed (HTTP ${response.status})${body ? `: ${body.slice(0, 300)}` : ''}`);
+    }
+  };
+
   const START_OPEN_CODE_MAX_ATTEMPTS = 2;
 
   const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
   const startOpenCodeOnce = async () => {
-    const desiredPort = env.ENV_CONFIGURED_OPENCODE_PORT ?? 0;
+    // New managed instance — drop any prior permit before spawn/probes.
+    const generationAtStart = revokeRuntimeExecutionPermit('managed-start');
+    const requestedPort = env.ENV_CONFIGURED_OPENCODE_PORT;
+    const defaultPortFree = requestedPort
+      ? false
+      : await waitForPortRelease(DEFAULT_OPENCODE_SERVE_PORT, 200, env.ENV_CONFIGURED_OPENCODE_HOSTNAME);
+    const desiredPort = requestedPort
+      ?? (defaultPortFree ? DEFAULT_OPENCODE_SERVE_PORT : 0);
     const spawnPort = await resolveManagedOpenCodePort(desiredPort, env.ENV_CONFIGURED_OPENCODE_HOSTNAME);
     console.log(
       desiredPort > 0
@@ -481,6 +777,9 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     );
 
     await applyOpencodeBinaryFromSettings({ strict: true });
+    if (typeof ensurePinnedOpenCode2CliEnv === 'function') {
+      await ensurePinnedOpenCode2CliEnv();
+    }
     ensureOpencodeCliEnv();
     const openCodePassword = await ensureLocalOpenCodeServerPassword({ rotateManaged: true });
     const envPath = typeof buildManagedOpenCodePath === 'function'
@@ -523,9 +822,17 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         setOpenCodePort(port);
         setDetectedOpenCodeApiPrefix(prefix);
 
-        state.isOpenCodeReady = true;
-        state.lastOpenCodeError = null;
-        state.openCodeNotReadySince = 0;
+        // Evaluate contract for THIS generation from live health + migration.
+        const healthResult = await fetchOpenCodeHealthResult(
+          (healthPath) => buildOpenCodeUrl(healthPath, ''),
+          AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
+        );
+        const gate = await probeV1MigrationGate(AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS));
+        refreshRuntimeContractFromProbe(healthResult, gate, generationAtStart);
+        if (applyV1MigrationGate(gate)) {
+          refreshRuntimeContractFromProbe(healthResult, gate, generationAtStart);
+          state.lastOpenCodeError = null;
+        }
 
         return serverInstance;
       }
@@ -539,6 +846,14 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
       const message = error instanceof Error ? error.message : String(error);
       state.lastOpenCodeError = message;
       state.openCodePort = null;
+      // Keep revoked/pending contract — do not resurrect the prior permit.
+      if ((Number(state.runtimeContractGeneration) || 0) === generationAtStart) {
+        refreshRuntimeContractFromProbe(
+          { ok: false, version: null, authenticated: null, healthOk: false },
+          state.v1Migration,
+          generationAtStart,
+        );
+      }
       syncToHmrState();
       console.error(`Failed to start OpenCode: ${message}`);
       throw error;
@@ -572,20 +887,35 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     throw lastError;
   };
 
-  const restartOpenCode = async () => {
+  const restartOpenCode = async (options = {}) => {
     if (state.isShuttingDown) return;
     if (state.currentRestartPromise) {
       await state.currentRestartPromise;
-      return;
+      if (!options.binaryPath) return;
     }
 
     state.currentRestartPromise = (async () => {
       state.isRestartingOpenCode = true;
       state.isOpenCodeReady = false;
       state.openCodeNotReadySince = Date.now();
+      // Drop prior instance permit before any probe / respawn.
+      const restartGeneration = revokeRuntimeExecutionPermit('managed-restart');
       console.log('Restarting OpenCode process...');
 
       if (state.isExternalOpenCode) {
+        if (sharedServiceAttached) {
+          // The service may have been stopped or replaced by another client
+          // (new pid, possibly new port/password); recovery only rediscovers it.
+          // An explicit upgrade supplies a verified owned-cache binary.
+          console.log('Re-ensuring shared OpenCode service...');
+          try {
+            await connectSharedOpenCodeService(options);
+          } catch (error) {
+            state.lastOpenCodeError = error instanceof Error ? error.message : String(error);
+            syncToHmrState();
+            throw error;
+          }
+        }
         console.log('Re-probing external OpenCode server...');
         const probePort = state.openCodePort || env.ENV_CONFIGURED_OPENCODE_PORT || 4096;
         const probeOrigin = state.openCodeBaseUrl ?? env.ENV_CONFIGURED_OPENCODE_HOST?.origin;
@@ -593,12 +923,20 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         if (healthy) {
           console.log(`External OpenCode server on port ${probePort} is healthy`);
           setOpenCodePort(probePort);
-          state.isOpenCodeReady = true;
-          state.lastOpenCodeError = null;
-          state.openCodeNotReadySince = 0;
+          const healthResult = await fetchOpenCodeHealthResult(
+            (healthPath) => buildOpenCodeUrl(healthPath, ''),
+            AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
+          );
+          const gate = await probeV1MigrationGate(AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS));
+          refreshRuntimeContractFromProbe(healthResult, gate, restartGeneration);
+          if (applyV1MigrationGate(gate)) {
+            refreshRuntimeContractFromProbe(healthResult, gate, restartGeneration);
+            state.lastOpenCodeError = null;
+          }
           syncToHmrState();
         } else {
           state.lastOpenCodeError = `External OpenCode server on port ${probePort} is not responding`;
+          state.v1Migration = null;
           console.error(state.lastOpenCodeError);
           throw new Error(state.lastOpenCodeError);
         }
@@ -610,11 +948,13 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         return;
       }
 
-      const portToKill = state.openCodePort;
+      const portToRelease = state.openCodePort;
 
       if (state.openCodeProcess) {
         console.log('Stopping existing OpenCode process...');
         try {
+          // close() owns the full SIGTERM→SIGKILL escalation on this child handle.
+          // Do not SIGKILL a pre-captured pid afterward — the OS may have recycled it.
           await state.openCodeProcess.close();
         } catch (error) {
           console.warn('Error closing OpenCode process:', error);
@@ -623,9 +963,9 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         syncToHmrState();
       }
 
-      killProcessOnPort(portToKill);
-      if (!(await waitForPortRelease(portToKill, 5000))) {
-        console.warn(`Timed out waiting for OpenCode port ${portToKill} to be released`);
+      // Probe only: never mass-kill whoever holds the port (clients / external serve).
+      if (!(await waitForPortRelease(portToRelease, 5000))) {
+        console.warn(`Timed out waiting for OpenCode port ${portToRelease} to be released`);
       }
 
       if (env.ENV_CONFIGURED_OPENCODE_PORT) {
@@ -658,12 +998,16 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     } catch (error) {
       console.error(`Failed to restart OpenCode: ${error.message}`);
       state.lastOpenCodeError = error.message;
-      if (!env.ENV_CONFIGURED_OPENCODE_PORT) {
-        state.openCodePort = null;
-        syncToHmrState();
+      // External serve is read-only: never clear its port, flip ownership, or
+      // spawn a managed replacement when a re-probe fails.
+      if (!state.isExternalOpenCode) {
+        if (!env.ENV_CONFIGURED_OPENCODE_PORT) {
+          state.openCodePort = null;
+          syncToHmrState();
+        }
+        state.openCodeApiPrefixDetected = true;
+        state.openCodeApiPrefix = '';
       }
-      state.openCodeApiPrefixDetected = true;
-      state.openCodeApiPrefix = '';
       throw error;
     } finally {
       state.currentRestartPromise = null;
@@ -678,36 +1022,49 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
     const deadline = Date.now() + timeoutMs;
     let lastError = null;
+    // Pin generation for this wait loop so a concurrent restart cannot have our
+    // late probe overwrite the newer instance contract.
+    const generationAtStart = Number(state.runtimeContractGeneration) || 0;
 
     while (Date.now() < deadline) {
       let timeout = null;
       try {
+        if ((Number(state.runtimeContractGeneration) || 0) !== generationAtStart) {
+          throw new Error('OpenCode instance changed while waiting for ready');
+        }
+        // One timer covers health + migration for this attempt. Clearing after
+        // health alone let a hung migration outrun HEALTH_CHECK_TIMEOUT_MS and
+        // the outer deadline when the probe never settled.
         const controller = new AbortController();
         timeout = setTimeout(() => controller.abort(), HEALTH_CHECK_TIMEOUT_MS);
-        const response = await fetch(buildOpenCodeUrl(OPENCODE_HEALTH_PATH, ''), {
-          method: 'GET',
-          headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
-          signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        timeout = null;
+        const healthResult = await fetchOpenCodeHealthResult(
+          (healthPath) => buildOpenCodeUrl(healthPath, ''),
+          controller.signal
+        );
 
-        if (!response.ok) {
-          lastError = new Error(`OpenCode health endpoint responded with status ${response.status}`);
+        if (!healthResult.ok) {
+          refreshRuntimeContractFromProbe(healthResult, state.v1Migration, generationAtStart);
+          lastError = new Error(
+            healthResult.reason === 'auth-failed'
+              ? 'OpenCode health endpoint rejected authentication'
+              : 'OpenCode health endpoint returned unhealthy response',
+          );
           await new Promise((resolve) => setTimeout(resolve, intervalMs));
           continue;
         }
 
-        const body = await response.json().catch(() => null);
-        if (body?.healthy !== true) {
-          lastError = new Error('OpenCode health endpoint returned unhealthy response');
-          await new Promise((resolve) => setTimeout(resolve, intervalMs));
-          continue;
+        const gate = await probeV1MigrationGate(controller.signal);
+        refreshRuntimeContractFromProbe(healthResult, gate, generationAtStart);
+        if (applyV1MigrationGate(gate)) {
+          // Re-publish contract after admitTranscript flips ready.
+          refreshRuntimeContractFromProbe(healthResult, gate, generationAtStart);
+          state.lastOpenCodeError = null;
+          return;
         }
 
-        state.isOpenCodeReady = true;
-        state.lastOpenCodeError = null;
-        return;
+        lastError = new Error(gate.error || `V1 migration is ${gate.phase}`);
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        continue;
       } catch (error) {
         lastError = error;
       } finally {
@@ -761,6 +1118,16 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     const { agentName } = options;
 
     console.log(`Refreshing OpenCode after ${reason}`);
+
+    if (sharedServiceAttached) {
+      // Shared with other clients: reload in place instead of restarting.
+      await reloadSharedOpenCodeLocations();
+      if (agentName) {
+        await waitForAgentPresence(agentName);
+      }
+      return { reloaded: true, external: true };
+    }
+
     clearResolvedOpenCodeBinary();
     await applyOpencodeBinaryFromSettings();
 
@@ -828,35 +1195,47 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         console.log(`Using external OpenCode server at ${label} (skip-start mode)`);
         state.openCodeBaseUrl = env.ENV_CONFIGURED_OPENCODE_HOST?.origin ?? null;
         setOpenCodePort(env.ENV_EFFECTIVE_PORT);
-        state.isOpenCodeReady = true;
+        // External attach is not ready until version + V1 migration admit.
+        revokeRuntimeExecutionPermit('external-attach');
+        state.isOpenCodeReady = false;
+        state.openCodeNotReadySince = Date.now();
         state.isExternalOpenCode = true;
         state.lastOpenCodeError = null;
-        state.openCodeNotReadySince = 0;
+        state.v1Migration = null;
         syncToHmrState();
+      } else if (
+        sharedService
+        && !env.ENV_CONFIGURED_OPENCODE_PORT
+        && !env.ENV_CONFIGURED_OPENCODE_HOST
+      ) {
+        await attachSharedOpenCodeService();
       } else if (await isOpenCodeProcessHealthy() && (managedCapabilitiesRuntime ? managedCapabilitiesRuntime.hasValidIdentity() : true)) {
         console.log(`[HMR] Reusing existing OpenCode process on port ${state.openCodePort}`);
       } else if (state.openCodeProcess && !state.isExternalOpenCode && await isOpenCodeProcessHealthy()) {
         console.log('[HMR] Restarting managed OpenCode because scheduled-task capability identity is stale');
         await restartOpenCode();
-      } else if (env.ENV_EFFECTIVE_PORT && await probeExternalOpenCode(env.ENV_EFFECTIVE_PORT, env.ENV_CONFIGURED_OPENCODE_HOST?.origin)) {
-        const label = env.ENV_CONFIGURED_OPENCODE_HOST ? env.ENV_CONFIGURED_OPENCODE_HOST.origin : `http://localhost:${env.ENV_EFFECTIVE_PORT}`;
-        console.log(`Auto-detected existing OpenCode server at ${label}`);
+      } else if (
+        (env.ENV_EFFECTIVE_PORT || DEFAULT_OPENCODE_SERVE_PORT)
+        && await probeExternalOpenCode(
+          env.ENV_EFFECTIVE_PORT || DEFAULT_OPENCODE_SERVE_PORT,
+          env.ENV_CONFIGURED_OPENCODE_HOST?.origin,
+        )
+      ) {
+        const reusePort = env.ENV_EFFECTIVE_PORT || DEFAULT_OPENCODE_SERVE_PORT;
+        const label = env.ENV_CONFIGURED_OPENCODE_HOST ? env.ENV_CONFIGURED_OPENCODE_HOST.origin : `http://localhost:${reusePort}`;
+        console.log(`Reusing existing OpenCode serve at ${label}`);
         state.openCodeBaseUrl = env.ENV_CONFIGURED_OPENCODE_HOST?.origin ?? null;
-        setOpenCodePort(env.ENV_EFFECTIVE_PORT);
-        state.isOpenCodeReady = true;
+        setOpenCodePort(reusePort);
+        // Health ok is not transcript-ready; waitForOpenCodeReady applies the gate.
+        state.isOpenCodeReady = false;
+        state.openCodeNotReadySince = Date.now();
         state.isExternalOpenCode = true;
         state.lastOpenCodeError = null;
-        state.openCodeNotReadySince = 0;
+        state.v1Migration = null;
         syncToHmrState();
       } else {
-        // We never auto-attach to an arbitrary pre-existing OpenCode instance.
-        // Attaching to an external server requires explicit opt-in via env
-        // (OPENCODE_HOST / OPENCODE_PORT / OPENCODE_SKIP_START), handled by the
-        // branches above. Without that opt-in we always start our OWN managed
-        // instance on a freshly-allocated port. A blind probe of the default
-        // port 4096 used to hijack a user's separately-running OpenCode (e.g.
-        // the OpenCode desktop app), coupling our lifecycle to theirs and
-        // breaking init against an unexpected server version/config.
+        // No healthy v2 serve on the requested/default port. Start a generic
+        // `opencode serve` so OpenChamber and other OpenCode clients can share it.
         state.isExternalOpenCode = false;
         state.openCodeBaseUrl = null;
         if (env.ENV_EFFECTIVE_PORT) {
@@ -874,6 +1253,11 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
       await waitForOpenCodePort();
       try {
         await waitForOpenCodeReady();
+        // Warm only after readiness admits; a failed gate must not kick off
+        // directory-scoped traffic against an unready upstream.
+        if (state.isOpenCodeReady) {
+          void warmOpenCodeDirectories();
+        }
       } catch (error) {
         console.error(`OpenCode readiness check failed: ${error.message}`);
       }
@@ -884,6 +1268,47 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     }
   };
 
+  // OpenCode initializes each project directory lazily on its first
+  // directory-scoped request, and that initialization takes seconds on large
+  // session stores. Without warming, the user's first session open pays it
+  // interactively. Warm the most recently used directories right after
+  // readiness so the work overlaps UI startup instead. Sequential and
+  // best-effort: a failed or slow directory never blocks the others for long,
+  // and a restart invalidates the pass via the port/readiness guard.
+  const warmOpenCodeDirectories = async () => {
+    let directories = [];
+    try {
+      directories = await getWarmupDirectories();
+    } catch {
+      return;
+    }
+    if (!Array.isArray(directories) || directories.length === 0) return;
+
+    const warmedPort = state.openCodePort;
+    for (const directory of directories.slice(0, WARMUP_DIRECTORY_LIMIT)) {
+      if (typeof directory !== 'string' || !directory) continue;
+      if (!state.isOpenCodeReady || state.openCodePort !== warmedPort) return;
+      let timeout = null;
+      try {
+        const controller = new AbortController();
+        timeout = setTimeout(() => controller.abort(), WARMUP_REQUEST_TIMEOUT_MS);
+        // Warming a directory is the point, not the answer: any directory-scoped
+        // read makes OpenCode initialise it. `/api/session` is the cheapest one
+        // that takes a directory.
+        const url = `${buildOpenCodeUrl('/api/session', '')}?directory=${encodeURIComponent(directory)}&limit=1`;
+        await fetch(url, {
+          method: 'GET',
+          headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
+          signal: controller.signal,
+        });
+      } catch {
+        // Best-effort — the directory stays lazy and the UI's own request warms it.
+      } finally {
+        if (timeout) clearTimeout(timeout);
+      }
+    }
+  };
+
   const bootstrapOpenCodeAtStartup = () => {
     if (!bootstrapOpenCodePromise) {
       bootstrapOpenCodePromise = runBootstrapOpenCodeAtStartup().finally(() => {
@@ -903,6 +1328,9 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
         clearResolvedOpenCodeBinary();
         await applyOpencodeBinaryFromSettings({ strict: true });
+        if (typeof ensurePinnedOpenCode2CliEnv === 'function') {
+          await ensurePinnedOpenCode2CliEnv();
+        }
         const resolved = ensureOpencodeCliEnv();
         if (!resolved) {
           const error = new Error('OpenCode CLI could not be resolved');
@@ -992,13 +1420,21 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
   };
 
   const runHealthCheckCycle = async (source) => {
-    if (!state.openCodeProcess || state.isShuttingDown || state.isRestartingOpenCode) return;
+    // External serve is read-only mount: never restart or spawn a second copy
+    // because the user's instance looks unhealthy from our probe. The shared
+    // service is the exception: "restart" only re-runs `service start`.
+    if (state.isExternalOpenCode && !sharedServiceAttached) return;
+    if (!sharedServiceAttached && !state.openCodeProcess) return;
+    if (state.isShuttingDown || state.isRestartingOpenCode) return;
     if (healthCheckCyclePromise) return healthCheckCyclePromise;
 
     healthCheckCyclePromise = (async () => {
       const healthy = await probeOpenCodeHealth();
       if (!healthy) {
-        if (!isManagedOpenCodeProcessAlive()) {
+        const processAlive = sharedServiceAttached
+          ? isProcessAlive(sharedServicePid)
+          : isManagedOpenCodeProcessAlive();
+        if (!processAlive) {
           console.log(`[lifecycle] ${source} health check: OpenCode process exited, restarting...`);
           consecutiveHealthFailures = 0;
           lastHealthProbeResult = null;
@@ -1017,6 +1453,11 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         await restartOpenCode();
       } else {
         resetHealthFailureState();
+        try {
+          const gate = await probeV1MigrationGate(AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS));
+          applyV1MigrationGate(gate);
+        } catch {
+        }
       }
     })().finally(() => {
       healthCheckCyclePromise = null;
@@ -1051,6 +1492,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
   return {
     killProcessOnPort,
+    isSharedOpenCodeService: () => sharedServiceAttached,
     startOpenCode,
     restartOpenCode,
     waitForOpenCodeReady,
@@ -1061,5 +1503,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     startHealthMonitoring,
     triggerHealthCheck,
     waitForPortRelease,
+    revokeRuntimeExecutionPermit,
+    refreshRuntimeContractFromProbe,
   };
 };