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

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 `opencode2` 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,7 +16,7 @@ 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:** [`opencode2`](https://opencode.ai) CLI installed (PATH or `OPENCODE_BINARY`; `opencode` / `opencode.exe` / `opencode.cmd` are rejected), Node.js 22+.
 
 ## Usage
 
@@ -33,7 +33,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 opencode2 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 +109,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 **opencode2**. OpenChamber still runs v2 health (`GET /api/health`) and V1 migration (`GET /api/experimental/migration/v1`) checks; a 1.x `opencode` server will not pass. `OPENCODE_BINARY` and `settings.opencodeBinary` must resolve to `opencode2`, not `opencode` / `opencode.exe` / `opencode.cmd`.
+
 ```bash
 OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
 OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
@@ -116,8 +118,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 opencode2 server (overrides `OPENCODE_PORT`) |
+| `OPENCODE_PORT` | Port of external opencode2 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,16 +168,16 @@ 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 opencode2 instance running as a separate service.
 
-**`~/.config/systemd/user/opencode.service`**
+**`~/.config/systemd/user/opencode2.service`**
 ```ini
 [Unit]
-Description=OpenCode Server
+Description=OpenCode 2 Server
 
 [Service]
 Type=simple
-ExecStart=opencode serve --port 4095
+ExecStart=opencode2 serve --port 4095
 Environment="PATH=/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/YOU/.local/bin:/home/YOU/.npm-global/bin:/usr/local/bin:/usr/bin:/bin"
 Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
 Restart=on-failure
@@ -195,7 +197,7 @@ WantedBy=default.target
 ```ini
 [Unit]
 Description=OpenChamber Web Server
-After=opencode.service
+After=opencode2.service
 
 [Service]
 Type=simple
@@ -211,7 +213,7 @@ WantedBy=default.target
 
 ```bash
 systemctl --user daemon-reload
-systemctl --user enable --now opencode openchamber
+systemctl --user enable --now opencode2 openchamber
 ```
 
 `--host 0.0.0.0` is required to listen on all interfaces (the default is `127.0.0.1`). Use `--host <ip>` or `OPENCHAMBER_HOST=<ip>` to bind to a specific interface instead.

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 opencode2 from PATH and ignores a sibling 1.x opencode', async () => {
+    await withIsolatedOpenCodeEnv(async () => {
+      const pathDir = createTempDir('openchamber-cli-path-opencode2-');
+      const legacy = path.join(pathDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+      const binary = path.join(pathDir, process.platform === 'win32' ? 'opencode2.cmd' : 'opencode2');
+      writeVersionBinary(legacy, '1.18.4');
+      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', 'opencode2']) {
+    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', 'opencode2']) {
+    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,
 };