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

package/server/lib/opencode/lifecycle.js

@@ -2,7 +2,10 @@ 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);
@@ -20,6 +23,10 @@ const HEALTH_CHECK_RESULT_CACHE_MS = parsePositiveInt(process.env.OPENCHAMBER_OP
 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;
@@ -51,23 +58,50 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     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 {
     }
   };
@@ -216,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) => {
@@ -447,14 +481,18 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
   // 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.
-  const fetchOpenCodeHealthOk = async (urlForPath, signal, options = {}) => {
+  // Health ok is reachability only — execution semantics live on runtimeContract.
+  const fetchOpenCodeHealthResult = async (urlForPath, signal, options = {}) => {
     const headerCandidates = [
-      { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
+      { Accept: 'application/json', ...getOpenCodeAuthHeaders(), authenticated: true },
     ];
     if (options.allowUnauthenticated) {
-      headerCandidates.push({ Accept: 'application/json' });
+      headerCandidates.push({ Accept: 'application/json', authenticated: false });
     }
-    for (const headers of headerCandidates) {
+    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), {
@@ -462,27 +500,115 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
             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);
-          if (gate.ok) return true;
+          lastGate = gate;
+          if (gate.ok) {
+            return {
+              ok: true,
+              version: gate.version,
+              authenticated: authenticated !== false,
+              healthOk: true,
+            };
+          }
         } catch {
         }
       }
     }
-    return false;
+    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 {
-      return await fetchOpenCodeHealthOk(
+      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;
     }
@@ -493,17 +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 healthy = await fetchOpenCodeHealthOk(
+      const result = await fetchOpenCodeHealthResult(
         (healthPath) => `${base}${healthPath}`,
         controller.signal,
         { allowUnauthenticated: true },
       );
       clearTimeout(timeout);
-      return healthy;
+      if (result.ok) {
+        refreshRuntimeContractFromProbe(result, state.v1Migration, generationAtStart);
+      }
+      return result.ok;
     } catch {
       return false;
     }
@@ -525,11 +655,114 @@ 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 () => {
+    // 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
@@ -589,8 +822,15 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         setOpenCodePort(port);
         setDetectedOpenCodeApiPrefix(prefix);
 
+        // 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;
         }
 
@@ -606,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;
@@ -639,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;
@@ -660,8 +923,14 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         if (healthy) {
           console.log(`External OpenCode server on port ${probePort} is healthy`);
           setOpenCodePort(probePort);
+          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();
@@ -679,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);
@@ -692,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) {
@@ -751,28 +1022,42 @@ 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 healthy = await fetchOpenCodeHealthOk(
+        const healthResult = await fetchOpenCodeHealthResult(
           (healthPath) => buildOpenCodeUrl(healthPath, ''),
           controller.signal
         );
 
-        if (!healthy) {
-          lastError = new Error('OpenCode health endpoint returned unhealthy response');
+        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 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;
         }
@@ -833,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();
 
@@ -901,12 +1196,19 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         state.openCodeBaseUrl = env.ENV_CONFIGURED_OPENCODE_HOST?.origin ?? null;
         setOpenCodePort(env.ENV_EFFECTIVE_PORT);
         // 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.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()) {
@@ -1119,15 +1421,20 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
   const runHealthCheckCycle = async (source) => {
     // External serve is read-only mount: never restart or spawn a second copy
-    // because the user's instance looks unhealthy from our probe.
-    if (state.isExternalOpenCode) return;
-    if (!state.openCodeProcess || state.isShuttingDown || state.isRestartingOpenCode) return;
+    // 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;
@@ -1185,6 +1492,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
   return {
     killProcessOnPort,
+    isSharedOpenCodeService: () => sharedServiceAttached,
     startOpenCode,
     restartOpenCode,
     waitForOpenCodeReady,
@@ -1195,5 +1503,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     startHealthMonitoring,
     triggerHealthCheck,
     waitForPortRelease,
+    revokeRuntimeExecutionPermit,
+    refreshRuntimeContractFromProbe,
   };
 };