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

package/server/lib/opencode/config-entity-routes.test.js

@@ -5,10 +5,11 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-vi.mock('@opencode-ai/sdk/v2', () => ({ createOpencodeClient: vi.fn() }));
+vi.mock('@opencode/client', () => ({ OpenCode: { make: vi.fn() } }));
 
-const { createOpencodeClient } = await import('@opencode-ai/sdk/v2');
+const { OpenCode } = await import('@opencode/client');
 const { registerConfigEntityRoutes } = await import('./config-entity-routes.js');
+const createOpencodeClient = OpenCode.make;
 
 beforeEach(() => {
   createOpencodeClient.mockReset();
@@ -49,6 +50,24 @@ const createDependencies = (getCommandSources, configDirectory, getAgentSources
   getOpenCodePort: () => 4096,
 });
 
+describe('V2 configuration persistence', () => {
+  it.each(['agents', 'commands', 'mcp'])('%s CRUD never restarts or reloads OpenCode', async (entity) => {
+    const dependencies = createDependencies(vi.fn());
+    dependencies.refreshOpenCodeAfterConfigChange.mockRejectedValue(new Error('must not manage the service'));
+    const app = express();
+    app.use(express.json());
+    registerConfigEntityRoutes(app, dependencies);
+    for (const method of ['post', 'patch', 'delete']) {
+      const response = await request(app)[method](`/api/config/${entity}/example?directory=%2Frepo`)
+        .send({ name: 'example', scope: 'project', type: 'local', command: ['example'] });
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({ success: true, requiresReload: false, application: 'watch' });
+      expect(response.body.requiresManualRestart).not.toBe(true);
+    }
+    expect(dependencies.refreshOpenCodeAfterConfigChange).not.toHaveBeenCalled();
+  });
+});
+
 describe('config entity command metadata route', () => {
   it('returns metadata for many commands through one request', async () => {
     const app = express();
@@ -100,9 +119,9 @@ describe('config entity command metadata route', () => {
 
     expect(createOpencodeClient).toHaveBeenCalledWith(expect.objectContaining({
       baseUrl: 'http://opencode-upstream:4096',
-      directory: '/repo',
       headers: { Authorization: 'Basic example' },
     }));
+    expect(createOpencodeClient.mock.calls[0][0].directory).toBeUndefined();
     expect(response.body.commands).toEqual([
       expect.objectContaining({ name: 'markdown', reference: markdownPath, description: `${'😀'.repeat(160)}…`, scope: 'project', isBuiltIn: false }),
       expect.objectContaining({ name: 'json', reference: 'json', description: 'JSON command', scope: 'project', isBuiltIn: false }),
@@ -149,14 +168,35 @@ describe('config entity command metadata route', () => {
       { name: 'long-path', reference: 'long-path' },
     ]);
   });
+
+  it('returns 502 when the command catalog is not an array instead of an empty success', async () => {
+    const app = express();
+    app.use(express.json());
+    createOpencodeClient.mockReturnValue({
+      command: { list: vi.fn(async () => ({ data: { commands: [] } })) },
+    });
+    registerConfigEntityRoutes(app, createDependencies(vi.fn()));
+
+    const response = await request(app)
+      .post('/api/config/commands/metadata?directory=%2Frepo')
+      .send({ catalog: true })
+      .expect(502);
+    expect(response.body).toEqual({ error: 'Command catalog is unavailable' });
+  });
 });
 
 describe('provider catalog route', () => {
   it('uses the resolved directory, OpenCode auth, SDK providers call, and explicit catalog route', async () => {
     const app = express();
     const resolveProjectDirectory = vi.fn(async () => ({ directory: '/project/from-header' }));
-    const providers = vi.fn(async () => ({ data: { providers: [], default: {} } }));
-    createOpencodeClient.mockReturnValue({ config: { providers } });
+    const location = { directory: '/project/from-header' };
+    const providers = vi.fn(async () => ({ data: [] }));
+    const models = vi.fn(async () => ({ data: [] }));
+    const modelDefault = vi.fn(async () => ({ data: null }));
+    createOpencodeClient.mockReturnValue({
+      provider: { list: providers },
+      model: { list: models, default: modelDefault },
+    });
     registerConfigEntityRoutes(app, {
       ...createDependencies(vi.fn()),
       resolveProjectDirectory,
@@ -171,22 +211,94 @@ describe('provider catalog route', () => {
     expect(resolveProjectDirectory).toHaveBeenCalledWith(expect.objectContaining({ query: { directory: '/repo' } }));
     expect(createOpencodeClient).toHaveBeenCalledWith(expect.objectContaining({
       baseUrl: 'http://opencode-upstream:4096',
-      directory: '/project/from-header',
       headers: { Authorization: 'Basic example' },
       fetch: expect.any(Function),
     }));
-    expect(providers).toHaveBeenCalledWith({ directory: '/project/from-header' });
+    expect(createOpencodeClient.mock.calls[0][0].directory).toBeUndefined();
+    expect(providers).toHaveBeenCalledWith({ location });
+    expect(models).toHaveBeenCalledWith({ location });
+    expect(modelDefault).toHaveBeenCalledWith({ location });
     expect(response.body).toEqual({ schemaVersion: 1, providers: [], default: {}, partial: false });
   });
 
+  it('projects ModelInfo.id as the catalog model id and default', async () => {
+    const app = express();
+    createOpencodeClient.mockReturnValue({
+      provider: { list: vi.fn(async () => ({ data: [{ id: 'openai', name: 'OpenAI' }] })) },
+      model: {
+        list: vi.fn(async () => ({
+          data: [{
+            id: 'gpt-5.4-mini',
+            modelID: 'internal-pack',
+            providerID: 'openai',
+            name: 'GPT-5.4 Mini',
+          }],
+        })),
+        default: vi.fn(async () => ({
+          data: { id: 'gpt-5.4-mini', modelID: 'internal-pack', providerID: 'openai', name: 'GPT-5.4 Mini' },
+        })),
+      },
+    });
+    registerConfigEntityRoutes(app, createDependencies(vi.fn()));
+
+    const response = await request(app).get('/api/config/catalog/providers').expect(200);
+    expect(response.body.providers).toEqual([{
+      id: 'openai',
+      name: 'OpenAI',
+      models: { 'gpt-5.4-mini': { id: 'gpt-5.4-mini', name: 'GPT-5.4 Mini' } },
+    }]);
+    expect(response.body.default).toEqual({ openai: 'gpt-5.4-mini' });
+    expect(JSON.stringify(response.body)).not.toContain('internal-pack');
+  });
+
+  it('projects v2 thinking variants into the provider catalog and strips request payloads', async () => {
+    const app = express();
+    createOpencodeClient.mockReturnValue({
+      provider: { list: vi.fn(async () => ({ data: [{ id: 'openai', name: 'OpenAI' }] })) },
+      model: {
+        list: vi.fn(async () => ({
+          data: [{
+            id: 'gpt-5.4',
+            modelID: 'internal-pack',
+            providerID: 'openai',
+            name: 'GPT 5.4',
+            capabilities: { tools: true, input: ['text', 'image'], output: ['text'] },
+            variants: [
+              { id: 'low', settings: { reasoningEffort: 'low', apiKey: 'variant-settings-sentinel' } },
+              { id: 'high', headers: { Authorization: 'variant-headers-sentinel' }, body: { store: false } },
+            ],
+          }],
+        })),
+        default: vi.fn(async () => ({ data: null })),
+      },
+    });
+    registerConfigEntityRoutes(app, createDependencies(vi.fn()));
+
+    const response = await request(app).get('/api/config/catalog/providers').expect(200);
+    expect(response.body.providers[0].models['gpt-5.4'].variants).toEqual({ low: {}, high: {} });
+    expect(response.body.providers[0].models['gpt-5.4'].capabilities).toEqual({
+      toolcall: true,
+      input: { text: true, image: true },
+      output: { text: true },
+    });
+    expect(JSON.stringify(response.body)).not.toContain('sentinel');
+    expect(JSON.stringify(response.body)).not.toContain('internal-pack');
+  });
+
   it('returns 502 for SDK failure and malformed catalog responses', async () => {
     const app = express();
-    createOpencodeClient.mockReturnValue({ config: { providers: vi.fn(async () => ({ data: { providers: {} } })) } });
+    createOpencodeClient.mockReturnValue({
+      provider: { list: vi.fn(async () => ({ data: {} })) },
+      model: { list: vi.fn(async () => ({ data: [] })), default: vi.fn(async () => ({ data: null })) },
+    });
     registerConfigEntityRoutes(app, createDependencies(vi.fn()));
     await request(app).get('/api/config/catalog/providers').expect(502);
 
     const failingApp = express();
-    createOpencodeClient.mockReturnValue({ config: { providers: vi.fn(async () => { throw new Error('upstream unavailable'); }) } });
+    createOpencodeClient.mockReturnValue({
+      provider: { list: vi.fn(async () => { throw new Error('upstream unavailable'); }) },
+      model: { list: vi.fn(async () => ({ data: [] })), default: vi.fn(async () => ({ data: null })) },
+    });
     registerConfigEntityRoutes(failingApp, createDependencies(vi.fn()));
     await request(failingApp).get('/api/config/catalog/providers').expect(502);
   });
@@ -194,7 +306,8 @@ describe('provider catalog route', () => {
   it('returns 502 for SDK error envelopes that include data', async () => {
     const app = express();
     createOpencodeClient.mockReturnValue({
-      config: { providers: vi.fn(async () => ({ error: { message: 'upstream sentinel' }, data: { providers: [], default: {} } })) },
+      provider: { list: vi.fn(async () => { throw new Error('upstream sentinel'); }) },
+      model: { list: vi.fn(async () => ({ data: [] })), default: vi.fn(async () => ({ data: null })) },
     });
     registerConfigEntityRoutes(app, createDependencies(vi.fn()));
 

package/server/lib/opencode/config-hot-reload.integration.test.js

@@ -0,0 +1,105 @@
+import { test, expect } from 'vitest';
+import { OpenCode } from '@opencode/client';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+// Opt-in, isolated real V2 server. No user config, credentials, model calls,
+// shared service registration, or npm plugin installs are used.
+test.skipIf(!process.env.OPENCHAMBER_TEST_OPENCODE_BINARY)('V2 applies credentials, global config and plugin changes in the same process', async () => {
+  const temporary = path.join(os.tmpdir(), 'opencode');
+  await fs.mkdir(temporary, { recursive: true });
+  const root = await fs.mkdtemp(path.join(temporary, 'config-hot-reload-'));
+  const config = path.join(root, 'config', 'opencode');
+  const directory = path.join(root, 'project');
+  await fs.mkdir(config, { recursive: true });
+  await fs.mkdir(directory, { recursive: true });
+  const password = randomBytes(24).toString('hex');
+  const child = spawn(process.env.OPENCHAMBER_TEST_OPENCODE_BINARY, ['serve', '--hostname', '127.0.0.1', '--port', '0'], {
+    cwd: directory,
+    env: {
+      PATH: process.env.PATH,
+      HOME: root,
+      TMPDIR: temporary,
+      XDG_CONFIG_HOME: path.join(root, 'config'),
+      XDG_DATA_HOME: path.join(root, 'data'),
+      XDG_STATE_HOME: path.join(root, 'state'),
+      XDG_CACHE_HOME: path.join(root, 'cache'),
+      OPENCODE_CONFIG_DIR: config,
+      OPENCODE_SERVER_PASSWORD: password,
+      OPENCODE_DISABLE_MODELS_FETCH: '1',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let output = '';
+  let spawnError;
+  child.on('error', (error) => { spawnError = error; });
+  child.stdout.on('data', (data) => { output = (output + data).slice(-8192); });
+  child.stderr.on('data', () => undefined);
+  const closed = once(child, 'close').catch(() => undefined);
+  const until = async (read, accepts, label) => {
+    const deadline = Date.now() + 20_000;
+    while (Date.now() < deadline) {
+      if (spawnError) throw spawnError;
+      if (child.exitCode !== null) throw new Error(`Isolated OpenCode exited during ${label}`);
+      const value = await read();
+      if (accepts(value)) return value;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timed out waiting for ${label}`);
+  };
+  const write = async (info) => {
+    const file = path.join(config, 'opencode.json');
+    await fs.writeFile(`${file}.tmp`, JSON.stringify(info));
+    await fs.rename(`${file}.tmp`, file);
+  };
+  try {
+    const origin = await until(
+      async () => output.match(/(?:server listening on|opencode server listening on) (http:\/\/[^\s]+)/)?.[1],
+      Boolean, 'listener',
+    );
+    const client = OpenCode.make({
+      baseUrl: origin,
+      headers: { Authorization: `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}` },
+      fetch: (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(15_000) }),
+    });
+    const location = { directory };
+    await client.command.list({ location });
+    const pid = child.pid;
+    const commands = { 'hot-reload-probe': { template: 'Do not execute anything.', description: 'one' } };
+    await write({ commands });
+    await until(() => client.command.list({ location }), (result) => result.data.some((entry) => entry.name === 'hot-reload-probe'), 'global command create');
+    await write({ commands: { 'hot-reload-probe': { ...commands['hot-reload-probe'], description: 'two' } } });
+    await until(() => client.command.list({ location }), (result) => result.data.some((entry) => entry.name === 'hot-reload-probe' && entry.description === 'two'), 'command update');
+
+    await write({ commands, plugins: ['*', '-opencode.config.command'] });
+    await until(() => client.command.list({ location }), (result) => !result.data.some((entry) => entry.name === 'hot-reload-probe'), 'plugin disable');
+    await write({ commands });
+    await until(() => client.command.list({ location }), (result) => result.data.some((entry) => entry.name === 'hot-reload-probe'), 'plugin re-enable');
+
+    await client.integration.connect.key({ integrationID: 'anthropic', key: 'isolated-test-placeholder', location });
+    const integration = await until(() => client.integration.get({ integrationID: 'anthropic', location }),
+      (result) => result.data.connections.some((connection) => connection.type === 'credential'), 'credential connection');
+    for (const connection of integration.data.connections) {
+      if (connection.type === 'credential') await client.credential.remove({ credentialID: connection.id });
+    }
+    await until(() => client.integration.get({ integrationID: 'anthropic', location }),
+      (result) => result.data.connections.length === 0, 'credential removal');
+    await write({ commands, mcp: { servers: { 'hot-reload-mcp': { type: 'local', command: ['unused-test-command'], disabled: true } } } });
+    await until(() => client.mcp.list({ location }), (result) => result.data.some((server) => server.name === 'hot-reload-mcp'), 'MCP config add');
+    await write({});
+    await until(() => client.mcp.list({ location }), (result) => !result.data.some((server) => server.name === 'hot-reload-mcp'), 'MCP config removal');
+    await until(() => client.command.list({ location }), (result) => !result.data.some((entry) => entry.name === 'hot-reload-probe'), 'command removal');
+    expect(child.pid).toBe(pid);
+    expect(child.exitCode).toBeNull();
+  } finally {
+    child.kill('SIGTERM');
+    const kill = setTimeout(() => child.kill('SIGKILL'), 5000);
+    await closed;
+    clearTimeout(kill);
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}, 120_000);

package/server/lib/opencode/ensure-cli.js

@@ -0,0 +1,238 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  PINNED_OPENCODE2_VERSION,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode2VersionAtLeast,
+  npmPackageForOpenCode2,
+  openCodeBinaryName,
+  parseOpenCode2VersionOutput,
+} from './opencode2-pin.js';
+
+const INSTALL_FETCH_TIMEOUT_MS = 30_000;
+
+export function isOpenCode2AutoInstallEnabled(env = process.env) {
+  const value = typeof env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL === 'string'
+    ? env.OPENCHAMBER_OPENCODE2_AUTO_INSTALL.trim().toLowerCase()
+    : '';
+  return value !== '0' && value !== 'false' && value !== 'no';
+}
+
+export function resolveOpenChamberDataDir(env = process.env, homedir = os.homedir) {
+  if (typeof env.OPENCHAMBER_DATA_DIR === 'string' && env.OPENCHAMBER_DATA_DIR.trim()) {
+    return path.resolve(env.OPENCHAMBER_DATA_DIR.trim());
+  }
+  const home = typeof homedir === 'function' ? homedir() : homedir;
+  return path.join(home, '.config', 'openchamber');
+}
+
+export function installedOpenCode2BinaryPath(version = PINNED_OPENCODE2_VERSION, options = {}) {
+  const dataDir = options.dataDir || resolveOpenChamberDataDir(options.env, options.homedir);
+  return path.join(dataDir, 'opencode-cli', version, openCodeBinaryName(options.platform));
+}
+
+export function readOpenCode2BinaryVersion(binaryPath, options = {}) {
+  if (typeof binaryPath !== 'string' || !binaryPath.trim()) return '';
+  const run = typeof options.spawnSync === 'function' ? options.spawnSync : spawnSync;
+  try {
+    const result = run(binaryPath, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 8_000,
+      windowsHide: true,
+    });
+    if (result.status !== 0) return '';
+    return parseOpenCode2VersionOutput(`${result.stdout || ''}\n${result.stderr || ''}`);
+  } catch {
+    return '';
+  }
+}
+
+const resolveNpmRegistry = (options = {}) => {
+  const env = options.env || process.env;
+  const electronRoot = options.electronRoot;
+  const candidates = [
+    env.NPM_CONFIG_REGISTRY,
+    options.cwd ? path.join(options.cwd, '.npmrc') : null,
+    electronRoot ? path.join(electronRoot, '.npmrc') : null,
+    path.join(os.homedir(), '.npmrc'),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      if (!String(candidate).endsWith('.npmrc')) {
+        if (/^https?:\/\//.test(candidate)) return String(candidate).replace(/\/+$/, '');
+        continue;
+      }
+      if (!fs.existsSync(candidate)) continue;
+      const match = fs.readFileSync(candidate, 'utf8').match(/^\s*registry\s*=\s*(\S+)\s*$/m);
+      if (match) return match[1].replace(/\/+$/, '');
+    } catch {
+      // Ignore unreadable npmrc candidates and fall back to the default registry.
+    }
+  }
+  return 'https://registry.npmjs.org';
+};
+
+const downloadBuffer = async (url, fetchImpl, timeoutMs) => {
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) {
+    throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+};
+
+const extractArchive = (archivePath, destination, run) => {
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.mkdirSync(destination, { recursive: true });
+  if (archivePath.endsWith('.zip')) {
+    if (process.platform === 'win32') {
+      run('powershell.exe', [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        `Expand-Archive -LiteralPath ${JSON.stringify(archivePath)} -DestinationPath ${JSON.stringify(destination)} -Force`,
+      ]);
+      return;
+    }
+    run('unzip', ['-q', archivePath, '-d', destination]);
+    return;
+  }
+  if (archivePath.endsWith('.tar.gz') || archivePath.endsWith('.tgz')) {
+    run('tar', ['-xzf', archivePath, '-C', destination]);
+    return;
+  }
+  throw new Error(`Unsupported opencode2 CLI archive: ${archivePath}`);
+};
+
+const findBinary = (root, binaryName) => {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isFile() && entry.name.toLowerCase() === binaryName.toLowerCase()) {
+      return fullPath;
+    }
+    if (entry.isDirectory()) {
+      const found = findBinary(fullPath, binaryName);
+      if (found) return found;
+    }
+  }
+  return null;
+};
+
+export async function installPinnedOpenCode2Cli(options = {}) {
+  const version = options.version || PINNED_OPENCODE2_VERSION;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const dataDir = options.dataDir || resolveOpenChamberDataDir(options.env, options.homedir);
+  const binaryName = openCodeBinaryName(platform);
+  const outputBinary = installedOpenCode2BinaryPath(version, { dataDir, platform });
+  const run = typeof options.spawnSync === 'function' ? options.spawnSync : spawnSync;
+  const fetchImpl = typeof options.fetch === 'function' ? options.fetch : fetch;
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : INSTALL_FETCH_TIMEOUT_MS;
+
+  const cacheDir = path.join(dataDir, 'opencode-cli', '.cache', version, `${platform}-${arch}`);
+  const archivePath = path.join(cacheDir, 'opencode2-cli.tgz');
+  const packageName = npmPackageForOpenCode2(platform, arch);
+
+  if (!fs.existsSync(archivePath)) {
+    const registry = resolveNpmRegistry(options);
+    const metadataResponse = await fetchImpl(`${registry}/${encodeURIComponent(packageName)}/${version}`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!metadataResponse.ok) {
+      throw new Error(
+        `Failed to resolve ${packageName}@${version} on ${registry}: ${metadataResponse.status} ${metadataResponse.statusText}`,
+      );
+    }
+    const metadata = await metadataResponse.json();
+    const tarball = metadata?.dist?.tarball;
+    if (typeof tarball !== 'string' || !/^https?:\/\//.test(tarball)) {
+      throw new Error(`No tarball found for ${packageName}@${version} on ${registry}`);
+    }
+    const bytes = await downloadBuffer(tarball, fetchImpl, timeoutMs);
+    fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+    const temp = `${archivePath}.tmp`;
+    fs.writeFileSync(temp, bytes);
+    fs.renameSync(temp, archivePath);
+  }
+
+  const extractDir = options.extractDir || path.join(cacheDir, 'extract');
+  if (typeof options.extract === 'function') {
+    await options.extract(archivePath, extractDir);
+  } else {
+    extractArchive(archivePath, extractDir, (command, args) => {
+      const result = run(command, args, {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        windowsHide: true,
+      });
+      if (result.status !== 0) {
+        const stderr = result.stderr ? `\n${result.stderr.trim()}` : '';
+        const stdout = result.stdout ? `\n${result.stdout.trim()}` : '';
+        throw new Error(`Command failed: ${command} ${args.join(' ')}${stderr}${stdout}`);
+      }
+      return result;
+    });
+  }
+
+  const extractedBinary = findBinary(extractDir, binaryName);
+  if (!extractedBinary) {
+    throw new Error(`Archive ${archivePath} did not contain ${binaryName} or opencode`);
+  }
+
+  fs.mkdirSync(path.dirname(outputBinary), { recursive: true });
+  fs.copyFileSync(extractedBinary, outputBinary);
+  if (platform !== 'win32') {
+    fs.chmodSync(outputBinary, 0o755);
+  }
+
+  const preparedVersion = readOpenCode2BinaryVersion(outputBinary, options);
+  if (preparedVersion !== version) {
+    throw new Error(`Installed opencode2 version mismatch: expected ${version}, got ${preparedVersion || 'unknown'}`);
+  }
+  return outputBinary;
+}
+
+/**
+ * Reuse any discovered acceptable 2.x CLI. Install the pin only when nothing
+ * usable is already installed (global PATH, explicit override, or cache).
+ */
+export async function ensurePinnedOpenCode2Cli(input = {}) {
+  const pin = input.pin || PINNED_OPENCODE2_VERSION;
+  const discoveredPath = typeof input.discoveredPath === 'string' ? input.discoveredPath.trim() : '';
+  const autoInstall = input.autoInstall ?? isOpenCode2AutoInstallEnabled(input.env);
+  const readVersion = typeof input.readVersion === 'function'
+    ? input.readVersion
+    : (binaryPath) => readOpenCode2BinaryVersion(binaryPath, input);
+  const install = typeof input.install === 'function' ? input.install : installPinnedOpenCode2Cli;
+
+  if (discoveredPath) {
+    const version = readVersion(discoveredPath);
+    if (isAcceptableOpenCode2HealthVersion(version)) {
+      return { path: discoveredPath, version, source: 'discovered', installed: false };
+    }
+  }
+
+  const cached = installedOpenCode2BinaryPath(pin, input);
+  const cachedVersion = readVersion(cached);
+  if (cachedVersion === pin || isOpenCode2VersionAtLeast(cachedVersion, pin)) {
+    return { path: cached, version: cachedVersion, source: 'installed', installed: false };
+  }
+
+  if (!autoInstall) {
+    const error = new Error(
+      `Unable to locate opencode ${pin}. Set OPENCODE_BINARY or install @opencode/cli@${pin}.`,
+    );
+    error.code = 'OPENCODE_CLI_MISSING';
+    throw error;
+  }
+
+  const installedPath = await install({ ...input, version: pin });
+  const version = readVersion(installedPath) || pin;
+  return { path: installedPath, version, source: 'installed', installed: true };
+}

package/server/lib/opencode/ensure-cli.test.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { PINNED_OPENCODE2_VERSION } from './opencode2-pin.js';
+import {
+  ensurePinnedOpenCode2Cli,
+  installedOpenCode2BinaryPath,
+  isOpenCode2AutoInstallEnabled,
+  resolveOpenChamberDataDir,
+} from './ensure-cli.js';
+
+const tempDirs = [];
+
+const createTempDir = (prefix) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('ensurePinnedOpenCode2Cli', () => {
+  it('keeps a discovered binary that already meets the pin', async () => {
+    const result = await ensurePinnedOpenCode2Cli({
+      discoveredPath: '/opt/opencode2',
+      pin: '2.0.12',
+      readVersion: () => '2.0.12',
+      install: async () => {
+        throw new Error('should not install');
+      },
+    });
+    expect(result).toEqual({
+      path: '/opt/opencode2',
+      version: '2.0.12',
+      source: 'discovered',
+      installed: false,
+    });
+  });
+
+  it('reuses an older global 2.x binary instead of reinstalling the pin', async () => {
+    const result = await ensurePinnedOpenCode2Cli({
+      discoveredPath: '/opt/old-opencode',
+      pin: '2.0.12',
+      readVersion: () => '2.0.5',
+      install: async () => {
+        throw new Error('should not install');
+      },
+    });
+    expect(result.source).toBe('discovered');
+    expect(result.path).toBe('/opt/old-opencode');
+  });
+
+  it('installs the pin only when no usable 2.x binary is present', async () => {
+    const dataDir = createTempDir('openchamber-ensure-cli-');
+    const installed = path.join(dataDir, 'opencode-cli', PINNED_OPENCODE2_VERSION, 'opencode');
+    let installedOnce = false;
+    const result = await ensurePinnedOpenCode2Cli({
+      discoveredPath: '',
+      pin: PINNED_OPENCODE2_VERSION,
+      dataDir,
+      platform: 'linux',
+      readVersion: (binaryPath) => {
+        if (binaryPath === installed && installedOnce) return PINNED_OPENCODE2_VERSION;
+        return '';
+      },
+      install: async () => {
+        installedOnce = true;
+        return installed;
+      },
+    });
+    expect(result).toEqual({
+      path: installed,
+      version: PINNED_OPENCODE2_VERSION,
+      source: 'installed',
+      installed: true,
+    });
+  });
+
+  it('reuses a cached pin without downloading', async () => {
+    const dataDir = createTempDir('openchamber-ensure-cached-');
+    const cached = installedOpenCode2BinaryPath(PINNED_OPENCODE2_VERSION, { dataDir, platform: 'linux' });
+    const result = await ensurePinnedOpenCode2Cli({
+      pin: PINNED_OPENCODE2_VERSION,
+      dataDir,
+      platform: 'linux',
+      readVersion: (binaryPath) => (binaryPath === cached ? PINNED_OPENCODE2_VERSION : ''),
+      install: async () => {
+        throw new Error('should not install');
+      },
+    });
+    expect(result.source).toBe('installed');
+    expect(result.installed).toBe(false);
+    expect(result.path).toBe(cached);
+  });
+
+  it('fails closed when auto-install is disabled and nothing usable is present', async () => {
+    await expect(ensurePinnedOpenCode2Cli({
+      pin: PINNED_OPENCODE2_VERSION,
+      autoInstall: false,
+      dataDir: createTempDir('openchamber-ensure-disabled-'),
+      readVersion: () => '',
+    })).rejects.toMatchObject({ code: 'OPENCODE_CLI_MISSING' });
+  });
+
+  it('treats OPENCHAMBER_OPENCODE2_AUTO_INSTALL=0 as disabled', () => {
+    expect(isOpenCode2AutoInstallEnabled({ OPENCHAMBER_OPENCODE2_AUTO_INSTALL: '0' })).toBe(false);
+    expect(isOpenCode2AutoInstallEnabled({})).toBe(true);
+  });
+
+  it('resolves the OpenChamber data dir from OPENCHAMBER_DATA_DIR', () => {
+    const dataDir = createTempDir('openchamber-data-dir-');
+    expect(resolveOpenChamberDataDir({ OPENCHAMBER_DATA_DIR: dataDir })).toBe(path.resolve(dataDir));
+  });
+});