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

package/README.md

@@ -4,7 +4,7 @@
 [![GitHub release](https://img.shields.io/github/v/release/yee94/openchamber?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgZmlsbD0iI2YxZWNlYyIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xMjgsMTI5LjA5VjIzMmE4LDgsMCwwLDEtMy44NC0xbC04OC00OC4xOGE4LDgsMCwwLDEtNC4xNi03VjgwLjE4YTgsOCwwLDAsMSwuNy0zLjI1WiIgb3BhY2l0eT0iMC4yIj48L3BhdGg%2BPHBhdGggZD0iTTIyMy42OCw2Ni4xNSwxMzUuNjgsMThhMTUuODgsMTUuODgsMCwwLDAtMTUuMzYsMGwtODgsNDguMTdhMTYsMTYsMCwwLDAtOC4zMiwxNHY5NS42NGExNiwxNiwwLDAsMCw4LjMyLDE0bDg4LDQ4LjE3YTE1Ljg4LDE1Ljg4LDAsMCwwLDE1LjM2LDBsODgtNDguMTdhMTYsMTYsMCwwLDAsOC4zMi0xNFY4MC4xOEExNiwxNiwwLDAsMCwyMjMuNjgsNjYuMTVaTTEyOCwzMmw4MC4zNCw0NC0yOS43NywxNi4zLTgwLjM1LTQ0Wk0xMjgsMTIwLDQ3LjY2LDc2bDMzLjktMTguNTYsODAuMzQsNDRaTTQwLDkwbDgwLDQzLjc4djg1Ljc5TDQwLDE3NS44MlptMTc2LDg1Ljc4aDBsLTgwLDQzLjc5VjEzMy44MmwzMi0xNy41MVYxNTJhOCw4LDAsMCwwLDE2LDBWMTA3LjU1TDIxNiw5MHY4NS43N1oiPjwvcGF0aD48L3N2Zz4%3D&logoColor=FFFCF0&labelColor=100F0F&color=205EA6)](https://github.com/yee94/openchamber/releases/latest)
 [![Discord](https://img.shields.io/badge/Discord-join.svg?style=flat&labelColor=100F0F&color=8B7EC8&logo=discord&logoColor=FFFCF0)](https://discord.gg/ZYRSdnwwKA)
 
-Run [OpenCode](https://opencode.ai) in your browser. Install the CLI, open `localhost:3000`, done. Works on desktop browsers, tablets, and phones as a PWA.
+Run [OpenCode](https://opencode.ai) in your browser. Install the `opencode` v2 CLI, open `localhost:3000`, done. Works on desktop browsers, tablets, and phones as a PWA.
 
 Full project overview, screenshots, and all features: [github.com/yee94/openchamber](https://github.com/yee94/openchamber)
 
@@ -16,10 +16,14 @@ curl -fsSL https://raw.githubusercontent.com/yee94/openchamber/main/scripts/inst
 
 Or install manually: `bun add -g @openchambery/web` (or npm, pnpm, yarn).
 
-> **Prerequisites:** [OpenCode CLI](https://opencode.ai) installed, Node.js 22+.
+> **Prerequisites:** [`opencode`](https://opencode.ai/v2/docs/) v2 CLI installed (PATH or `OPENCODE_BINARY`; 1.x versions are rejected), Node.js 22+.
 
 ## Usage
 
+By default, OpenChamber connects to the official shared OpenCode background service used by Desktop and TUI. Closing OpenChamber leaves OpenCode running, and the next launch reuses it. If the service cannot start, OpenChamber reports the failure for retry instead of launching a private fallback. In-app OpenCode upgrades install into OpenChamber's own cache and replace the shared service through the official service command; this also reconnects other clients using that service. User-installed CLI files are not overwritten.
+
+Explicit `OPENCODE_HOST` / `OPENCODE_PORT` connections keep their existing behavior. `OPENCHAMBER_OPENCODE_SHARED_SERVICE=0` selects the private managed lifecycle when required by an existing deployment.
+
 ```bash
 openchamber                          # Start on port 3000
 openchamber --port 8080              # Custom port
@@ -33,7 +37,7 @@ openchamber connect-url --port 3000  # Add this server to OpenChamber Desktop
 openchamber connect-url --server http://host:3000 --qr
 openchamber connect-url --port 3000 --qr
 openchamber logs                     # Follow latest instance logs
-OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber                    # Connect to external OpenCode server
+OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber                    # Connect to external opencode v2 server
 OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber  # Connect via custom host/HTTPS
 openchamber stop                     # Stop server
 openchamber update                   # Update to latest version
@@ -109,6 +113,8 @@ Generating a client token does not automatically password-protect the hosted bro
 <details>
 <summary>Connect to external OpenCode server</summary>
 
+The external host must be **OpenCode v2**. OpenChamber runs v2 health (`GET /api/info`) and V1 migration (`GET /api/experimental/migration/v1`) checks; a 1.x server will not pass. Automatic discovery uses the official `opencode` command only. `OPENCODE_BINARY` and `settings.opencodeBinary` can override the executable path; admission is checked by version.
+
 ```bash
 OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
 OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
@@ -116,8 +122,8 @@ OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
 
 | Variable | Description |
 |----------|-------------|
-| `OPENCODE_HOST` | Full base URL of external server (overrides `OPENCODE_PORT`) |
-| `OPENCODE_PORT` | Port of external server |
+| `OPENCODE_HOST` | Full base URL of external OpenCode v2 server (overrides `OPENCODE_PORT`) |
+| `OPENCODE_PORT` | Port of external OpenCode v2 server |
 | `OPENCODE_SKIP_START` | Skip starting embedded OpenCode server |
 | `OPENCHAMBER_OPENCODE_HOSTNAME` | Bind hostname for managed OpenCode server (default: `127.0.0.1`, use `0.0.0.0` for LAN/remote access — trusted networks only) |
 | `OPENCHAMBER_HOST` | Bind hostname for the OpenChamber web server (default: `127.0.0.1`; use `0.0.0.0` for LAN/remote access — trusted networks only) |
@@ -166,12 +172,12 @@ openchamber stop        # Stop background server
 <details>
 <summary>systemd service (VPN / LAN access)</summary>
 
-Use `--foreground` to keep the CLI process alive so systemd (or any other process manager) can track and restart it. Combine with `OPENCODE_HOST` to connect to an OpenCode instance running as a separate service.
+Use `--foreground` to keep the CLI process alive so systemd (or any other process manager) can track and restart it. Combine with `OPENCODE_HOST` to connect to an OpenCode v2 instance running as a separate service.
 
 **`~/.config/systemd/user/opencode.service`**
 ```ini
 [Unit]
-Description=OpenCode Server
+Description=OpenCode 2 Server
 
 [Service]
 Type=simple

package/bin/cli-opencode.test.js

@@ -0,0 +1,208 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { checkOpenCodeCLI } from './cli.js';
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function writeVersionBinary(filePath, version) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  if (process.platform === 'win32') {
+    fs.writeFileSync(filePath, `@echo off\r\necho ${version}\r\n`);
+    return;
+  }
+  fs.writeFileSync(filePath, `#!${process.execPath}\nconsole.log(${JSON.stringify(version)});\n`);
+  fs.chmodSync(filePath, 0o755);
+}
+
+async function withIsolatedOpenCodeEnv(fn) {
+  const previousBinary = process.env.OPENCODE_BINARY;
+  const previousPath = process.env.PATH;
+  const previousDataDir = process.env.OPENCHAMBER_DATA_DIR;
+  const previousAutoInstall = process.env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL;
+  const dataDir = createTempDir('openchamber-cli-opencode-data-');
+  process.env.OPENCHAMBER_DATA_DIR = dataDir;
+  process.env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL = '0';
+  try {
+    return await fn({ dataDir });
+  } finally {
+    if (typeof previousBinary === 'string') {
+      process.env.OPENCODE_BINARY = previousBinary;
+    } else {
+      delete process.env.OPENCODE_BINARY;
+    }
+    if (typeof previousPath === 'string') {
+      process.env.PATH = previousPath;
+    } else {
+      delete process.env.PATH;
+    }
+    if (typeof previousDataDir === 'string') {
+      process.env.OPENCHAMBER_DATA_DIR = previousDataDir;
+    } else {
+      delete process.env.OPENCHAMBER_DATA_DIR;
+    }
+    if (typeof previousAutoInstall === 'string') {
+      process.env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL = previousAutoInstall;
+    } else {
+      delete process.env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL;
+    }
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+}
+
+describe('checkOpenCodeCLI v2 gate', () => {
+  it('uses the same binary validation for TTY, non-TTY, --quiet, and --json notice styles', async () => {
+    await withIsolatedOpenCodeEnv(async () => {
+      const dir = createTempDir('openchamber-cli-mode-parity-');
+      const binary = path.join(dir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+      writeVersionBinary(binary, '1.18.4');
+      process.env.OPENCODE_BINARY = binary;
+      const pathDir = createTempDir('openchamber-cli-mode-path-');
+      writeVersionBinary(path.join(pathDir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2'), '2.0.12');
+      process.env.PATH = pathDir;
+
+      const notices = [];
+      const modes = [
+        { json: true, quiet: false },
+        { json: false, quiet: true },
+        { json: false, quiet: false },
+      ];
+      try {
+        for (const mode of modes) {
+          await expect(checkOpenCodeCLI((notice) => notices.push({ mode, notice }))).rejects.toMatchObject({
+            code: 'OPENCODE_BINARY_INVALID',
+            message: expect.stringMatching(/1\.x.*OpenCode v2/s),
+          });
+        }
+        expect(notices).toEqual([]);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+        fs.rmSync(pathDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('fails closed for opencode / opencode.exe / opencode.cmd and does not fall back to PATH', async () => {
+    await withIsolatedOpenCodeEnv(async () => {
+      const names = process.platform === 'win32'
+        ? ['opencode.exe', 'opencode.cmd']
+        : ['opencode', 'opencode.exe', 'opencode.cmd'];
+      const pathDir = createTempDir('openchamber-cli-legacy-path-');
+      const v2 = path.join(pathDir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2');
+      writeVersionBinary(v2, '2.0.12');
+      process.env.PATH = pathDir;
+
+      try {
+        for (const name of names) {
+          const dir = createTempDir(`openchamber-cli-legacy-${name}-`);
+          const binary = path.join(dir, name);
+          writeVersionBinary(binary, '1.18.4');
+          process.env.OPENCODE_BINARY = binary;
+          try {
+            await expect(checkOpenCodeCLI()).rejects.toMatchObject({
+              code: 'OPENCODE_BINARY_INVALID',
+              message: expect.stringMatching(/1\.x.*OpenCode v2/s),
+            });
+            expect(process.env.OPENCODE_BINARY).toBe(binary);
+          } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+          }
+        }
+      } finally {
+        fs.rmSync(pathDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('discovers official opencode from PATH and ignores the opencode2 alias', async () => {
+    await withIsolatedOpenCodeEnv(async () => {
+      const pathDir = createTempDir('openchamber-cli-path-opencode2-');
+      const legacy = path.join(pathDir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2');
+      const binary = path.join(pathDir, process.platform === 'win32' ? 'opencode.cmd' : 'opencode');
+      writeVersionBinary(legacy, '2.0.15');
+      writeVersionBinary(binary, '2.0.12');
+      process.env.PATH = pathDir;
+      delete process.env.OPENCODE_BINARY;
+
+      try {
+        await expect(checkOpenCodeCLI()).resolves.toBe(binary);
+        expect(process.env.OPENCODE_BINARY).toBe(binary);
+      } finally {
+        fs.rmSync(pathDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('fails closed when settings.opencodeBinary is a 1.x basename', async () => {
+    await withIsolatedOpenCodeEnv(async ({ dataDir }) => {
+      const dir = createTempDir('openchamber-cli-settings-1x-');
+      const binary = path.join(dir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+      writeVersionBinary(binary, '1.18.4');
+      fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ opencodeBinary: binary }));
+      delete process.env.OPENCODE_BINARY;
+      const pathDir = createTempDir('openchamber-cli-settings-path-');
+      writeVersionBinary(path.join(pathDir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2'), '2.0.12');
+      process.env.PATH = pathDir;
+      try {
+        await expect(checkOpenCodeCLI()).rejects.toMatchObject({
+          code: 'OPENCODE_BINARY_INVALID',
+          message: expect.stringMatching(/1\.x.*OpenCode v2/s),
+        });
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+        fs.rmSync(pathDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('accepts a configured opencode2 path after the v2 version gate', async () => {
+    await withIsolatedOpenCodeEnv(async ({ dataDir }) => {
+      const dir = createTempDir('openchamber-cli-settings-v2-');
+      const binary = path.join(dir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2');
+      writeVersionBinary(binary, '2.0.12');
+      fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ opencodeBinary: binary }));
+      delete process.env.OPENCODE_BINARY;
+      process.env.PATH = createTempDir('openchamber-cli-settings-empty-');
+      try {
+        await expect(checkOpenCodeCLI()).resolves.toBe(binary);
+        expect(process.env.OPENCODE_BINARY).toBe(binary);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  it('names opencode2 when PATH lookup finds nothing', async () => {
+    await withIsolatedOpenCodeEnv(async () => {
+      delete process.env.OPENCODE_BINARY;
+      process.env.PATH = createTempDir('openchamber-cli-missing-');
+      await expect(checkOpenCodeCLI()).rejects.toThrow(/opencode/);
+    });
+  });
+
+  it('installs pinned opencode2 when PATH has no usable binary', async () => {
+    await withIsolatedOpenCodeEnv(async ({ dataDir }) => {
+      delete process.env.OPENCODE_BINARY;
+      process.env.PATH = createTempDir('openchamber-cli-install-missing-');
+      const installed = path.join(dataDir, 'opencode-cli', '2.0.12', process.platform === 'win32' ? 'opencode2.exe' : 'opencode2');
+      writeVersionBinary(installed, '2.0.12');
+      const notices = [];
+      await expect(checkOpenCodeCLI((notice) => notices.push(notice), {
+        ensurePinnedOpenCode2Cli: async () => ({
+          path: installed,
+          version: '2.0.12',
+          source: 'installed',
+          installed: true,
+        }),
+      })).resolves.toBe(installed);
+      expect(process.env.OPENCODE_BINARY).toBe(installed);
+      expect(notices).toEqual([
+        expect.objectContaining({ code: 'OPENCODE_CLI_INSTALLED' }),
+      ]);
+    });
+  });
+});

package/bin/cli.js

@@ -18,7 +18,12 @@ import {
   findClosestMatch,
 } from './lib/cli-args.js';
 import { readDesktopLocalPortFromSettings } from './lib/cli-paths.js';
-import { resolveExplicitBinary, searchPathFor } from './lib/cli-executables.js';
+import { searchPathFor } from './lib/cli-executables.js';
+import {
+  assertOpenCode2Binary,
+  readConfiguredOpenCodeBinary,
+} from './lib/cli-startup.js';
+import { ensurePinnedOpenCode2Cli } from '../server/lib/opencode/ensure-cli.js';
 import { startupCommand } from './lib/commands-startup.js';
 import { logsCommand } from './lib/commands-logs.js';
 import { statusCommand } from './lib/commands-status.js';
@@ -75,14 +80,16 @@ function importFromFilePath(filePath) {
   return import(pathToFileURL(filePath).href);
 }
 
-async function checkOpenCodeCLI(onNotice) {
+// Binary validation is policy, not presentation: TTY, non-TTY, --quiet, and
+// --json all run this same check before serve starts.
+async function checkOpenCodeCLI(onNotice, options = {}) {
   if (process.env.OPENCODE_BINARY) {
-    const override = resolveExplicitBinary(process.env.OPENCODE_BINARY);
+    const override = assertOpenCode2Binary(process.env.OPENCODE_BINARY);
     if (override) {
       process.env.OPENCODE_BINARY = override;
       return override;
     }
-    const message = `OPENCODE_BINARY="${process.env.OPENCODE_BINARY}" is not an executable file. Falling back to PATH lookup.`;
+    const message = `OPENCODE_BINARY="${process.env.OPENCODE_BINARY}" is not a usable OpenCode v2 CLI. Falling back to PATH lookup.`;
     if (typeof onNotice === 'function') {
       onNotice({ level: 'warning', code: 'OPENCODE_BINARY_INVALID', message });
     } else {
@@ -90,15 +97,60 @@ async function checkOpenCodeCLI(onNotice) {
     }
   }
 
-  const resolvedFromPath = searchPathFor('opencode');
-  if (resolvedFromPath) {
-    process.env.OPENCODE_BINARY = resolvedFromPath;
-    return resolvedFromPath;
+  const configured = readConfiguredOpenCodeBinary();
+  if (configured) {
+    const fromConfig = assertOpenCode2Binary(configured);
+    if (fromConfig) {
+      process.env.OPENCODE_BINARY = fromConfig;
+      return fromConfig;
+    }
+  }
+
+  let discovered = '';
+  for (const name of ['opencode']) {
+    const resolvedFromPath = searchPathFor(name);
+    if (!resolvedFromPath) continue;
+    try {
+      const verified = assertOpenCode2Binary(resolvedFromPath);
+      if (verified) {
+        discovered = verified;
+        break;
+      }
+    } catch (error) {
+      if (error?.code === 'OPENCODE_BINARY_INVALID') continue;
+      throw error;
+    }
+  }
+  const ensureCli = typeof options.ensurePinnedOpenCode2Cli === 'function'
+    ? options.ensurePinnedOpenCode2Cli
+    : ensurePinnedOpenCode2Cli;
+
+  try {
+    const ensured = await ensureCli({ discoveredPath: discovered });
+    if (ensured?.path) {
+      if (typeof onNotice === 'function' && ensured.installed) {
+        onNotice({
+          level: 'info',
+          code: 'OPENCODE_CLI_INSTALLED',
+          message: `Installed opencode ${ensured.version} to ${ensured.path}`,
+        });
+      }
+      process.env.OPENCODE_BINARY = ensured.path;
+      return ensured.path;
+    }
+  } catch (error) {
+    if (error?.code === 'OPENCODE_CLI_MISSING') {
+      throw new Error(
+        `Unable to locate the opencode CLI on PATH (${process.env.PATH || '<empty>'}). ` +
+        'Ensure OpenCode v2 is installed and reachable, or set OPENCODE_BINARY to its full path.'
+      );
+    }
+    throw error;
   }
 
   throw new Error(
     `Unable to locate the opencode CLI on PATH (${process.env.PATH || '<empty>'}). ` +
-    'Ensure the CLI is installed and reachable, or set OPENCODE_BINARY to its full path.'
+    'Ensure OpenCode v2 is installed and reachable, or set OPENCODE_BINARY to its full path.'
   );
 }
 
@@ -304,4 +356,5 @@ export {
   findClosestMatch,
   TunnelCliError,
   EXIT_CODE,
+  checkOpenCodeCLI,
 };

package/bin/lib/cli-startup.js

@@ -6,10 +6,107 @@ import { DEFAULT_PORT } from './cli-args.js';
 import { EXIT_CODE, TunnelCliError } from './cli-errors.js';
 import { getDataDir } from './cli-paths.js';
 import { hasUiPasswordConfigured } from './cli-network.js';
-import { searchPathFor } from './cli-executables.js';
+import { resolveExplicitBinary, searchPathFor } from './cli-executables.js';
+import { isAcceptableOpenCode2HealthVersion, isOpenCode1xVersion } from '../../server/lib/opencode/opencode2-pin.js';
 
 const STARTUP_SERVICE_ID = 'dev.openchamber.web';
 
+function createOpenCode1xVersionError(candidate, version) {
+  const error = new Error(
+    `OpenCode 1.x is not supported (${candidate} reports ${version}). Install OpenCode v2 (opencode).`
+  );
+  error.code = 'OPENCODE_BINARY_INVALID';
+  return error;
+}
+
+function extractOpenCodeVersion(output) {
+  if (typeof output !== 'string' || output.trim().length === 0) {
+    return '';
+  }
+  const match = output.match(/v?\d+\.\d+[\w.+-]*/i);
+  return match ? match[0] : '';
+}
+
+function readOpenCodeBinaryVersion(binaryPath) {
+  const result = spawnSync(binaryPath, ['--version'], {
+    encoding: 'utf8',
+    timeout: 8000,
+    windowsHide: true,
+  });
+  return `${result.stdout || ''}\n${result.stderr || ''}`.trim();
+}
+
+// OPENCODE_BINARY and settings.opencodeBinary share the v2 version gate.
+function assertOpenCode2Binary(candidate) {
+  const trimmed = typeof candidate === 'string' ? candidate.trim() : '';
+  if (!trimmed) {
+    return null;
+  }
+  const resolved = resolveExplicitBinary(trimmed) || trimmed;
+  const version = extractOpenCodeVersion(readOpenCodeBinaryVersion(resolved));
+  if (isOpenCode1xVersion(version)) {
+    throw createOpenCode1xVersionError(resolved, version);
+  }
+  if (!isAcceptableOpenCode2HealthVersion(version)) {
+    return null;
+  }
+  return resolveExplicitBinary(trimmed);
+}
+
+function readConfiguredOpenCodeBinary() {
+  try {
+    const raw = fs.readFileSync(path.join(getDataDir(), 'settings.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.opencodeBinary !== 'string') {
+      return '';
+    }
+    const trimmed = parsed.opencodeBinary.trim();
+    if (!trimmed) {
+      return '';
+    }
+    try {
+      if (fs.statSync(trimmed).isDirectory()) {
+        return path.join(trimmed, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+      }
+    } catch {
+    }
+    return trimmed;
+  } catch {
+    return '';
+  }
+}
+
+function resolveOpenCode2BinaryForStartup() {
+  const explicit = typeof process.env.OPENCODE_BINARY === 'string' ? process.env.OPENCODE_BINARY.trim() : '';
+  if (explicit) {
+    const resolved = assertOpenCode2Binary(explicit);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const configured = readConfiguredOpenCodeBinary();
+  if (configured) {
+    const resolved = assertOpenCode2Binary(configured);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  for (const name of ['opencode']) {
+    const resolvedFromPath = searchPathFor(name);
+    if (!resolvedFromPath) continue;
+    try {
+      const resolved = assertOpenCode2Binary(resolvedFromPath);
+      if (resolved) return resolved;
+    } catch (error) {
+      if (error?.code === 'OPENCODE_BINARY_INVALID') continue;
+      throw error;
+    }
+  }
+  return null;
+}
+
 function getStartupServicePaths() {
   if (process.platform === 'darwin') {
     return {
@@ -82,9 +179,11 @@ function collectStartupEnv(options = {}) {
   );
 
   if (options.envSnapshot !== false) {
-    const opencodeBinary = process.env.OPENCODE_BINARY || searchPathFor('opencode');
+    const opencodeBinary = resolveOpenCode2BinaryForStartup();
     if (typeof opencodeBinary === 'string' && opencodeBinary.trim().length > 0) {
       env.OPENCODE_BINARY = opencodeBinary.trim();
+    } else {
+      delete env.OPENCODE_BINARY;
     }
   }
   const uiPassword = hasUiPasswordConfigured(options.uiPassword) ? options.uiPassword : undefined;
@@ -367,4 +466,8 @@ export {
   getStartupStatus,
   enableStartupService,
   disableStartupService,
+  collectStartupEnv,
+  assertOpenCode2Binary,
+  readConfiguredOpenCodeBinary,
+  resolveOpenCode2BinaryForStartup,
 };