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

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

@@ -2,9 +2,58 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
-import { createOpencodeClient } from '@opencode-ai/sdk/v2';
+import { OpenCode } from '@opencode/client';
 import { projectProviderCatalog } from './provider-catalog.js';
 
+// Compose official v2 provider.list + model.list (+ optional default) into the
+// catalog shape consumed by projectProviderCatalog. Missing arrays are failure.
+const composeV2ProviderCatalogSource = (providers, models, defaultModel) => {
+  if (!Array.isArray(providers) || !Array.isArray(models)) return null;
+
+  const modelsByProvider = new Map();
+  for (const model of models) {
+    if (!model || typeof model !== 'object') continue;
+    const providerID = typeof model.providerID === 'string' ? model.providerID : '';
+    const modelID = typeof model.modelID === 'string' && model.modelID
+      ? model.modelID
+      : (typeof model.id === 'string' ? model.id : '');
+    if (!providerID || !modelID) continue;
+    if (!modelsByProvider.has(providerID)) modelsByProvider.set(providerID, Object.create(null));
+    const entry = { id: modelID };
+    if (typeof model.name === 'string' && model.name) entry.name = model.name;
+    if (typeof model.family === 'string' && model.family) entry.family = model.family;
+    if (model.limit && typeof model.limit === 'object') entry.limit = model.limit;
+    if (model.capabilities) entry.capabilities = model.capabilities;
+    if (model.cost && typeof model.cost === 'object' && !Array.isArray(model.cost)) entry.cost = model.cost;
+    if (model.variants && typeof model.variants === 'object' && !Array.isArray(model.variants)) {
+      entry.variants = model.variants;
+    }
+    if (typeof model.time?.released === 'number' && Number.isFinite(model.time.released)) {
+      entry.release_date = new Date(model.time.released).toISOString().slice(0, 10);
+    }
+    modelsByProvider.get(providerID)[modelID] = entry;
+  }
+
+  const list = [];
+  for (const provider of providers) {
+    if (!provider || typeof provider.id !== 'string' || !provider.id) continue;
+    list.push({
+      id: provider.id,
+      name: typeof provider.name === 'string' && provider.name ? provider.name : provider.id,
+      models: modelsByProvider.get(provider.id) || Object.create(null),
+    });
+  }
+
+  const defaults = Object.create(null);
+  if (defaultModel && typeof defaultModel.providerID === 'string' && typeof defaultModel.modelID === 'string') {
+    defaults[defaultModel.providerID] = defaultModel.modelID;
+  }
+  return { providers: list, default: defaults };
+};
+
+const createOpenCodeClient = ({ baseUrl, headers, fetch: fetchImpl }) =>
+  OpenCode.make({ baseUrl, headers, fetch: fetchImpl });
+
 const MAX_GLOBAL_CONFIG_SIZE = 2 * 1024 * 1024;
 const GLOBAL_CONFIG_FILES = {
   opencode: ['opencode.json', 'opencode.jsonc'],
@@ -83,6 +132,7 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
     resolveOptionalProjectDirectory,
     refreshOpenCodeAfterConfigChange,
     clientReloadDelayMs,
+    waitForOpenCodeReady,
     getAgentSources,
     getAgentConfig,
     createAgent,
@@ -115,25 +165,43 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
       if (!directory) {
         return res.status(400).json({ error });
       }
-      const client = createOpencodeClient({
+      // Gate on managed-OpenCode readiness like the generic proxy: without this
+      // the SDK hits an upstream that is still starting (or a stale orphan from
+      // a nodemon restart) and gets HTML/401 back, surfacing as a spurious 502.
+      if (typeof waitForOpenCodeReady === 'function') {
+        await waitForOpenCodeReady(20_000, 200);
+      }
+      const client = createOpenCodeClient({
         baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''),
-        directory,
         headers: getOpenCodeAuthHeaders(),
-        fetch: (request) => fetch(request, { signal: AbortSignal.timeout(8_000) }),
+        // Forward the full init: the SDK carries Authorization in init.headers.
+        // Dropping init (the old `(request) => fetch(request, { signal })` shape)
+        // silently stripped auth and produced spurious upstream 401s.
+        fetch: (request, init) => fetch(request, { ...init, signal: AbortSignal.timeout(8_000) }),
       });
-      const response = await client.config.providers({ directory });
-      if (response?.error || response?.data === undefined) {
+      const location = { directory };
+      const [providersResult, modelsResult, defaultResult] = await Promise.all([
+        client.provider.list({ location }),
+        client.model.list({ location }),
+        client.model.default({ location }),
+      ]);
+      const source = composeV2ProviderCatalogSource(
+        providersResult?.data,
+        modelsResult?.data,
+        defaultResult?.data,
+      );
+      if (!source) {
         console.error('Provider catalog upstream response failed');
         return res.status(502).json({ error: 'Provider catalog is unavailable' });
       }
-      const catalog = projectProviderCatalog(response?.data);
+      const catalog = projectProviderCatalog(source);
       if (!catalog.ok) {
         console.error('Provider catalog upstream response is malformed');
         return res.status(502).json({ error: 'Provider catalog is unavailable' });
       }
       return res.json(catalog.value);
-    } catch {
-      console.error('Provider catalog request failed');
+    } catch (catalogError) {
+      console.error('Provider catalog request failed', catalogError?.reason ? `(${catalogError.reason})` : catalogError?.message ?? catalogError);
       return res.status(502).json({ error: 'Provider catalog is unavailable' });
     }
   });
@@ -500,14 +568,17 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
         if (!getOpenCodePort()) {
           return res.json({ commands: [] });
         }
-        const client = createOpencodeClient({
+        const client = createOpenCodeClient({
           baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''),
-          directory,
           headers: getOpenCodeAuthHeaders(),
           fetch: (request) => fetch(request, { signal: AbortSignal.timeout(8_000) }),
         });
-        const response = await client.command.list({ directory });
-        const commands = Array.isArray(response?.data) ? response.data : [];
+        const response = await client.command.list({ location: { directory } });
+        if (!Array.isArray(response?.data)) {
+          console.error('Command catalog upstream response failed');
+          return res.status(502).json({ error: 'Command catalog is unavailable' });
+        }
+        const commands = response.data;
         return res.json({
           commands: commands
             .filter((command) => command?.source !== 'skill')

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();
@@ -100,9 +101,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 +150,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 +193,30 @@ 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('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 +224,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/ensure-cli.js

@@ -0,0 +1,239 @@
+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)
+    || findBinary(extractDir, platform === 'win32' ? 'opencode2.exe' : 'opencode2');
+  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));
+  });
+});