fix(opencode): improve runtime preflight diagnostics

Author: 777genius

src/main/index.ts

@@ -226,7 +226,7 @@ import {
   TeamTaskStallSnapshotSource,
   TeamTranscriptSourceLocator,
   UpdaterService,
-  resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath,
+  resolveVerifiedOpenCodeRuntimeBinaryPath,
 } from './services';
 
 import type { FileChangeEvent } from '@main/types';
@@ -343,10 +343,8 @@ function describeMemberWorkSyncReviewPickupEscalationReason(reason: string): str
 }
 
 async function resolveOpenCodeRuntimeBinaryForBridgeEnv(): Promise<string | null> {
-  const manifestBinaryPath = await resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath();
-  if (manifestBinaryPath) {
-    return manifestBinaryPath;
-  }
+  const resolvedBinaryPath = await resolveVerifiedOpenCodeRuntimeBinaryPath();
+  if (resolvedBinaryPath) return resolvedBinaryPath;
 
   try {
     const status = await openCodeRuntimeInstallerService?.getStatus();
@@ -435,7 +433,7 @@ async function createOpenCodeRuntimeAdapterRegistry(
     await ensureOpenCodeBridgeRuntimeBinaryEnv({
       targetEnv,
       bridgeEnv,
-      resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath: resolveOpenCodeRuntimeBinaryForBridgeEnv,
+      resolveVerifiedOpenCodeRuntimeBinaryPath: resolveOpenCodeRuntimeBinaryForBridgeEnv,
       onWarning: (message) => logger.warn(message),
     });
   };

src/main/services/infrastructure/OpenCodeRuntimeInstallerService.ts

@@ -1,7 +1,7 @@
 import { execCli } from '@main/utils/childProcess';
 import { getAppDataPath } from '@main/utils/pathDecoder';
 import { safeSendToRenderer } from '@main/utils/safeWebContentsSend';
-import { getCachedShellEnv } from '@main/utils/shellEnv';
+import { getCachedShellEnv, resolveInteractiveShellEnvBestEffort } from '@main/utils/shellEnv';
 import { getErrorMessage } from '@shared/utils/errorHandling';
 import { createLogger } from '@shared/utils/logger';
 import { createHash, randomUUID } from 'crypto';
@@ -22,6 +22,7 @@ const MAX_TARBALL_BYTES = 250 * 1024 * 1024;
 const MAX_BINARY_BYTES = 350 * 1024 * 1024;
 const FETCH_TIMEOUT_MS = 60_000;
 const VERSION_TIMEOUT_MS = 10_000;
+const PATH_SHELL_ENV_TIMEOUT_MS = 1_500;
 
 interface NpmPackageMetadata {
   name?: string;
@@ -134,9 +135,15 @@ function splitPathEnv(pathValue: string | undefined): string[] {
     .filter(Boolean);
 }
 
-function resolvePathOpenCodeBinary(): string | null {
+function resolvePathOpenCodeBinary(
+  additionalEnvSources: (NodeJS.ProcessEnv | null | undefined)[] = []
+): string | null {
   const shellEnv = getCachedShellEnv() ?? {};
-  const pathEntries = [...splitPathEnv(shellEnv.PATH), ...splitPathEnv(process.env.PATH)];
+  const pathEntries = [
+    ...additionalEnvSources.flatMap((env) => splitPathEnv(env?.PATH)),
+    ...splitPathEnv(shellEnv.PATH),
+    ...splitPathEnv(process.env.PATH),
+  ];
   const seen = new Set<string>();
   for (const entry of pathEntries) {
     const normalizedEntry = path.resolve(entry);
@@ -154,6 +161,57 @@ function resolvePathOpenCodeBinary(): string | null {
   return null;
 }
 
+type OpenCodeBinaryVersionProbe =
+  | { ok: true; version: string | null }
+  | { ok: false; error: string };
+
+async function probeOpenCodeBinaryVersion(binaryPath: string): Promise<OpenCodeBinaryVersionProbe> {
+  try {
+    const { stdout } = await execCli(binaryPath, ['--version'], {
+      timeout: VERSION_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    return { ok: true, version: stdout.trim() || null };
+  } catch (error) {
+    return { ok: false, error: getErrorMessage(error) };
+  }
+}
+
+async function resolvePathOpenCodeBinaryWithBestEffortEnv(
+  options: { shellEnvTimeoutMs?: number } = {}
+): Promise<string | null> {
+  const cachedCandidate = resolvePathOpenCodeBinary();
+  if (cachedCandidate) {
+    return cachedCandidate;
+  }
+
+  const shellEnv = await resolveInteractiveShellEnvBestEffort({
+    timeoutMs: options.shellEnvTimeoutMs ?? PATH_SHELL_ENV_TIMEOUT_MS,
+    fallbackEnv: process.env,
+  });
+  return resolvePathOpenCodeBinary([shellEnv]);
+}
+
+async function resolveVerifiedPathOpenCodeBinaryPath(
+  options: { shellEnvTimeoutMs?: number } = {}
+): Promise<string | null> {
+  const binaryPath = await resolvePathOpenCodeBinaryWithBestEffortEnv(options);
+  if (!binaryPath) {
+    return null;
+  }
+
+  return (await probeOpenCodeBinaryVersion(binaryPath)).ok ? binaryPath : null;
+}
+
+export async function resolveVerifiedOpenCodeRuntimeBinaryPath(
+  options: { shellEnvTimeoutMs?: number } = {}
+): Promise<string | null> {
+  return (
+    (await resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath()) ??
+    (await resolveVerifiedPathOpenCodeBinaryPath(options))
+  );
+}
+
 function isLinuxMuslRuntime(): boolean {
   if (process.platform !== 'linux') {
     return false;
@@ -466,31 +524,27 @@ export class OpenCodeRuntimeInstallerService {
   }
 
   private async getPathStatus(): Promise<OpenCodeRuntimeStatus> {
-    const binaryPath = resolvePathOpenCodeBinary();
+    const binaryPath = await resolvePathOpenCodeBinaryWithBestEffortEnv();
     if (!binaryPath) {
       return { installed: false, source: 'missing', state: 'idle' };
     }
-    try {
-      const { stdout } = await execCli(binaryPath, ['--version'], {
-        timeout: VERSION_TIMEOUT_MS,
-        windowsHide: true,
-      });
-      return {
-        installed: true,
-        binaryPath,
-        version: stdout.trim() || undefined,
-        source: 'path',
-        state: 'ready',
-      };
-    } catch (error) {
+    const version = await probeOpenCodeBinaryVersion(binaryPath);
+    if (!version.ok) {
       return {
         installed: false,
         binaryPath,
         source: 'path',
         state: 'failed',
-        error: getErrorMessage(error),
+        error: version.error,
       };
     }
+    return {
+      installed: true,
+      binaryPath,
+      version: version.version ?? undefined,
+      source: 'path',
+      state: 'ready',
+    };
   }
 
   private async installInternal(): Promise<OpenCodeRuntimeStatus> {

src/main/services/runtime/openCodeBridgeRuntimeEnv.ts

@@ -1,3 +1,6 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+
 import { getErrorMessage } from '@shared/utils/errorHandling';
 
 import {
@@ -9,16 +12,76 @@ import {
 export interface EnsureOpenCodeBridgeRuntimeBinaryEnvOptions {
   targetEnv: NodeJS.ProcessEnv;
   bridgeEnv?: NodeJS.ProcessEnv;
-  resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath: () => Promise<string | null>;
+  resolveVerifiedOpenCodeRuntimeBinaryPath: () => Promise<string | null>;
   onWarning?: (message: string) => void;
 }
 
+function resolveExistingFilePath(filePath: string): string | null {
+  const resolvedPath = path.resolve(filePath.trim());
+  if (!existsSync(resolvedPath)) {
+    return null;
+  }
+  try {
+    return statSync(resolvedPath).isFile() ? resolvedPath : null;
+  } catch {
+    return null;
+  }
+}
+
+function getOpenCodeRuntimeBinaryEnvValues(env: NodeJS.ProcessEnv): string[] {
+  return [
+    env[OPENCODE_RUNTIME_BINARY_PATH_ENV]?.trim(),
+    env[OPENCODE_LEGACY_BINARY_PATH_ENV]?.trim(),
+  ].filter((value): value is string => Boolean(value));
+}
+
+function resolveExistingOpenCodeRuntimeBinaryEnvPath(env: NodeJS.ProcessEnv): string | null {
+  for (const value of getOpenCodeRuntimeBinaryEnvValues(env)) {
+    const resolvedPath = resolveExistingFilePath(value);
+    if (resolvedPath) {
+      return resolvedPath;
+    }
+  }
+  return null;
+}
+
+function clearOpenCodeRuntimeBinaryEnvValues(
+  env: NodeJS.ProcessEnv,
+  invalidValues: Set<string>
+): void {
+  for (const key of [OPENCODE_RUNTIME_BINARY_PATH_ENV, OPENCODE_LEGACY_BINARY_PATH_ENV]) {
+    const value = env[key]?.trim();
+    if (value && invalidValues.has(value)) {
+      delete env[key];
+    }
+  }
+}
+
 export async function ensureOpenCodeBridgeRuntimeBinaryEnv({
   targetEnv,
   bridgeEnv = targetEnv,
-  resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath,
+  resolveVerifiedOpenCodeRuntimeBinaryPath,
   onWarning,
 }: EnsureOpenCodeBridgeRuntimeBinaryEnvOptions): Promise<void> {
+  if (
+    targetEnv[OPENCODE_RUNTIME_BINARY_PATH_ENV]?.trim() ||
+    targetEnv[OPENCODE_LEGACY_BINARY_PATH_ENV]?.trim()
+  ) {
+    const existingBinaryPath = resolveExistingOpenCodeRuntimeBinaryEnvPath(targetEnv);
+    if (!existingBinaryPath) {
+      const invalidValues = new Set(getOpenCodeRuntimeBinaryEnvValues(targetEnv));
+      clearOpenCodeRuntimeBinaryEnvValues(targetEnv, invalidValues);
+      if (targetEnv !== bridgeEnv) {
+        clearOpenCodeRuntimeBinaryEnvValues(bridgeEnv, invalidValues);
+      }
+    } else {
+      targetEnv[OPENCODE_RUNTIME_BINARY_PATH_ENV] = existingBinaryPath;
+      targetEnv[OPENCODE_LEGACY_BINARY_PATH_ENV] = existingBinaryPath;
+      applyOpenCodeRuntimeBinaryEnv(targetEnv, existingBinaryPath);
+      return;
+    }
+  }
+
   if (
     targetEnv[OPENCODE_RUNTIME_BINARY_PATH_ENV]?.trim() ||
     targetEnv[OPENCODE_LEGACY_BINARY_PATH_ENV]?.trim()
@@ -28,8 +91,8 @@ export async function ensureOpenCodeBridgeRuntimeBinaryEnv({
   }
 
   try {
-    const appManagedOpenCodeBinary = await resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath();
-    applyOpenCodeRuntimeBinaryEnv(targetEnv, appManagedOpenCodeBinary);
+    const openCodeBinary = await resolveVerifiedOpenCodeRuntimeBinaryPath();
+    applyOpenCodeRuntimeBinaryEnv(targetEnv, openCodeBinary);
     if (
       targetEnv !== bridgeEnv &&
       targetEnv[OPENCODE_RUNTIME_BINARY_PATH_ENV] &&
@@ -38,8 +101,6 @@ export async function ensureOpenCodeBridgeRuntimeBinaryEnv({
       applyOpenCodeRuntimeBinaryEnv(bridgeEnv, targetEnv[OPENCODE_RUNTIME_BINARY_PATH_ENV]);
     }
   } catch (error) {
-    onWarning?.(
-      `[OpenCode] Runtime adapter bundled OpenCode binary unresolved: ${getErrorMessage(error)}`
-    );
+    onWarning?.(`[OpenCode] Runtime adapter OpenCode binary unresolved: ${getErrorMessage(error)}`);
   }
 }

src/main/services/runtime/providerAwareCliEnv.ts

@@ -1,7 +1,7 @@
 import { resolveVerifiedAppManagedCodexRuntimeBinaryPath } from '@features/codex-runtime-installer/main';
 import { getCachedShellEnv } from '@main/utils/shellEnv';
 
-import { resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath } from '../infrastructure/OpenCodeRuntimeInstallerService';
+import { resolveVerifiedOpenCodeRuntimeBinaryPath } from '../infrastructure/OpenCodeRuntimeInstallerService';
 
 import { ensureAgentTeamsMcpLocalLaunchEnv } from './agentTeamsMcpLaunchEnv';
 import { buildRuntimeBaseEnv } from './buildRuntimeBaseEnv';
@@ -45,8 +45,8 @@ export async function buildProviderAwareCliEnv(
     env: options.env,
   });
   if (!resolvedProviderId || resolvedProviderId === 'opencode') {
-    const appManagedOpenCodeBinary = await resolveVerifiedAppManagedOpenCodeRuntimeBinaryPath();
-    applyOpenCodeRuntimeBinaryEnv(env, appManagedOpenCodeBinary);
+    const openCodeBinary = await resolveVerifiedOpenCodeRuntimeBinaryPath();
+    applyOpenCodeRuntimeBinaryEnv(env, openCodeBinary);
   }
   const appManagedCodexBinary = await resolveVerifiedAppManagedCodexRuntimeBinaryPath();
   if (

src/main/services/team/AgentTeamsMcpHttpServer.ts

@@ -12,6 +12,7 @@ const logger = createLogger('Service:AgentTeamsMcpHttpServer');
 const MCP_HTTP_HOST = '127.0.0.1';
 const MCP_HTTP_ENDPOINT = '/mcp';
 const MCP_HTTP_READY_TIMEOUT_MS = 5_000;
+const MCP_HTTP_EXISTING_HANDLE_READY_TIMEOUT_MS = 3_000;
 const MCP_HTTP_READY_POLL_MS = 100;
 
 export interface AgentTeamsMcpHttpServerHandle {
@@ -120,18 +121,18 @@ export class AgentTeamsMcpHttpServer {
   private startPromise: Promise<AgentTeamsMcpHttpServerHandle> | null = null;
   private child: ChildProcess | null = null;
   private handle: AgentTeamsMcpHttpServerHandle | null = null;
+  private readonly expectedStopChildren = new WeakSet<ChildProcess>();
 
   constructor(private readonly deps: AgentTeamsMcpHttpServerDeps = {}) {}
 
   async ensureStarted(): Promise<AgentTeamsMcpHttpServerHandle> {
-    if (this.handle) {
-      return this.handle;
-    }
     if (this.startPromise) {
       return this.startPromise;
     }
 
-    this.startPromise = this.startOnce().finally(() => {
+    this.startPromise = (
+      this.handle ? this.reuseOrRestartExistingHandle(this.handle) : this.startOnce()
+    ).finally(() => {
       this.startPromise = null;
     });
     return this.startPromise;
@@ -142,10 +143,34 @@ export class AgentTeamsMcpHttpServer {
     this.child = null;
     this.handle = null;
     if (child) {
+      this.expectedStopChildren.add(child);
       killProcessTree(child, 'SIGKILL');
     }
   }
 
+  private async reuseOrRestartExistingHandle(
+    handle: AgentTeamsMcpHttpServerHandle
+  ): Promise<AgentTeamsMcpHttpServerHandle> {
+    const waitForPort = this.deps.waitForPort ?? waitForLoopbackPort;
+    try {
+      await waitForPort(MCP_HTTP_HOST, handle.port, MCP_HTTP_EXISTING_HANDLE_READY_TIMEOUT_MS);
+      if (this.handle === handle) {
+        return handle;
+      }
+    } catch (error) {
+      if (this.handle === handle) {
+        logger.warn(
+          `Agent Teams MCP HTTP server at ${handle.url} failed health reuse check, restarting: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        await this.stop();
+      }
+    }
+
+    return this.startOnce();
+  }
+
   private async startOnce(): Promise<AgentTeamsMcpHttpServerHandle> {
     const resolveLaunchSpec = this.deps.resolveLaunchSpec ?? resolveAgentTeamsMcpLaunchSpec;
     const allocatePort = this.deps.allocatePort ?? allocateLoopbackPort;
@@ -181,14 +206,21 @@ export class AgentTeamsMcpHttpServer {
     let startupSettled = false;
     const startupFailure = new Promise<never>((_, reject) => {
       child.once('exit', (code, signal) => {
+        const expectedStop = this.expectedStopChildren.delete(child);
         clearIfCurrent();
         const codeSuffix = typeof code === 'number' ? ` with code ${code}` : '';
         const signalSuffix = signal ? ` (${signal})` : '';
         const message = `Agent Teams MCP HTTP server exited before startup completed${codeSuffix}${signalSuffix}`;
-        if (!startupSettled) {
+        if (!startupSettled && !expectedStop) {
           reject(new Error(message));
+          logger.warn(message);
+          return;
+        }
+        if (startupSettled && !expectedStop) {
+          logger.warn(
+            `Agent Teams MCP HTTP server exited after startup${codeSuffix}${signalSuffix}`
+          );
         }
-        logger.warn(message);
       });
       child.once('error', (error) => {
         clearIfCurrent();
@@ -216,6 +248,7 @@ export class AgentTeamsMcpHttpServer {
         this.child = null;
         this.handle = null;
       }
+      this.expectedStopChildren.add(child);
       killProcessTree(child, 'SIGKILL');
       throw error;
     }