@openchambery/web 2.0.0-beta.9 → 2.0.0

package/server/lib/opencode/routes.test.js

@@ -15,8 +15,10 @@ vi.mock('./ensure-cli.js', async (importOriginal) => {
 
 import { registerOpenCodeRoutes } from './routes.js';
 import { isOpenCode1xVersion } from './opencode2-pin.js';
+import { createOpenCodeUpdateDiscovery } from './update-discovery.js';
 
 const createDependencies = ({ formatSettingsResponse }) => ({
+  discoverOpenCodeUpdate: async () => '2.0.12',
   crypto: {},
   clientReloadDelayMs: 0,
   getOpenCodeResolutionSnapshot: vi.fn(),
@@ -231,26 +233,65 @@ describe('opencode2 upgrade pin (ticket 12)', () => {
   });
 
   it('upgrades a shared service using the owned cache and verifies the running version', async () => {
-    const binary = '/cache/opencode-cli/2.0.14/opencode';
+    const binary = '/cache/opencode-cli/2.0.23/opencode';
     vi.mocked(installPinnedOpenCode2Cli).mockResolvedValueOnce(binary);
-    vi.mocked(readOpenCode2BinaryVersion).mockReturnValueOnce('2.0.14');
-    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ version: '2.0.14', pid: 42 }))));
+    vi.mocked(readOpenCode2BinaryVersion).mockReturnValueOnce('2.0.23');
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ version: '2.0.23', pid: 42 }))));
     let resolvedBinary = '/usr/local/bin/opencode';
     const restartOpenCode = vi.fn(async () => {});
     const { app } = createUpgradeApp({
       getIsExternalOpenCode: () => true,
       getIsSharedOpenCodeService: () => true,
       getResolvedOpenCodeBinary: () => resolvedBinary,
-      getOpenCodeCliVersion: () => '2.0.14',
+      getOpenCodeCliVersion: () => '2.0.23',
       forceResolvedOpenCodeBinary: (value) => { resolvedBinary = value; },
       restartOpenCode,
       waitForOpenCodeReady: vi.fn(),
       openchamberDataDir: '/cache',
     });
 
-    const response = await request(app).post('/api/opencode/upgrade').send({ target: '2.0.14' }).expect(200);
+    const response = await request(app).post('/api/opencode/upgrade').send({ target: '2.0.23' }).expect(200);
     expect(restartOpenCode).toHaveBeenCalledWith({ binaryPath: binary });
-    expect(response.body).toMatchObject({ success: true, version: '2.0.14', ownership: 'shared-service' });
+    expect(response.body).toMatchObject({ success: true, version: '2.0.23', ownership: 'shared-service' });
+  });
+
+  it('discovers the remote release and updates a shared 2.0.16 service to 2.0.23', async () => {
+    let serveVersion = '2.0.16';
+    let binary = '/usr/local/bin/opencode';
+    const installed = '/cache/opencode-cli/2.0.23/opencode';
+    const fetchMock = vi.fn(async (url) => new Response(JSON.stringify({
+      version: String(url).includes('registry.npmjs.org') ? '2.0.23' : serveVersion,
+    })));
+    vi.stubGlobal('fetch', fetchMock);
+    vi.mocked(readOpenCode2BinaryVersion).mockReturnValue('2.0.23');
+    vi.mocked(installPinnedOpenCode2Cli).mockResolvedValueOnce(installed);
+    const restartOpenCode = vi.fn(async () => { serveVersion = '2.0.23'; });
+    const { app } = createUpgradeApp({
+      discoverOpenCodeUpdate: createOpenCodeUpdateDiscovery(),
+      getIsExternalOpenCode: () => true,
+      getIsSharedOpenCodeService: () => true,
+      getResolvedOpenCodeBinary: () => binary,
+      forceResolvedOpenCodeBinary: (value) => { binary = value; },
+      restartOpenCode,
+      waitForOpenCodeReady: vi.fn(),
+      openchamberDataDir: '/cache',
+    });
+    const before = await request(app).get('/api/opencode/upgrade-status').expect(200);
+    expect(before.body).toMatchObject({ available: true, serveVersion: '2.0.16', targetVersion: '2.0.23', canManage: true });
+    const result = await request(app).post('/api/opencode/upgrade').send({}).expect(200);
+    expect(result.body).toMatchObject({ success: true, restarted: true, version: '2.0.23' });
+    expect(restartOpenCode).toHaveBeenCalledWith({ binaryPath: installed });
+    const after = await request(app).get('/api/opencode/upgrade-status').expect(200);
+    expect(after.body).toMatchObject({ available: false, serveVersion: '2.0.23' });
+    expect(fetchMock.mock.calls.filter(([url]) => String(url).includes('registry.npmjs.org'))).toHaveLength(1);
+    vi.mocked(readOpenCode2BinaryVersion).mockReset();
+  });
+
+  it('reports registry failure as unknown rather than up-to-date', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ version: '2.0.16' }))));
+    const { app } = createUpgradeApp({ discoverOpenCodeUpdate: async () => { throw new Error('registry unavailable'); } });
+    const result = await request(app).get('/api/opencode/upgrade-status').expect(500);
+    expect(result.body).toMatchObject({ available: null, error: 'registry unavailable' });
   });
 
   it('does not report a failed shared replacement as success and restores binary selection', async () => {
@@ -344,7 +385,7 @@ describe('runtime contract routes (ticket 11)', () => {
       ok: true,
       status: 200,
       statusText: 'OK',
-      json: async () => ({ version: '2.0.12', pid: 1 }),
+      json: async () => ({ version: '2.0.20', pid: 1 }),
     })));
     const { app } = createContractApp();
 
@@ -354,7 +395,7 @@ describe('runtime contract routes (ticket 11)', () => {
     expect(health.body.executionAllowed).toBe(true);
 
     const contract = await request(app).get('/api/opencode/contract').expect(200);
-    expect(contract.body.serveVersion).toBe('2.0.12');
+    expect(contract.body.serveVersion).toBe('2.0.20');
     expect(contract.body.capabilities['core.protocol'].available).toBe(true);
   });
 
@@ -398,7 +439,7 @@ describe('GET /api/opencode/health', () => {
         status: 200,
         statusText: 'OK',
         json: async () => ({
-          version: '2.0.12',
+          version: '2.0.20',
           pid: 4242,
           urls: { api: 'http://127.0.0.1:4096' },
           paths: { config: '/tmp/config', data: '/tmp/data' },
@@ -412,7 +453,7 @@ describe('GET /api/opencode/health', () => {
 
     expect(response.body).toMatchObject({
       healthy: true,
-      version: '2.0.12',
+      version: '2.0.20',
       executionAllowed: true,
       protocolCompatible: true,
     });

package/server/lib/opencode/runtime-contract.js

@@ -7,20 +7,21 @@
  * execution semantics.
  *
  * Evidence bounds (ticket 11):
- * - MIN_VERIFIED: pin / installed verification (`2.0.12`)
+ * - MIN_VERIFIED: credential API availability (`2.0.20`)
  * Any acceptable OpenCode 2.x at or above MIN_VERIFIED may execute. Below-min
  * 2.x and 1.x are refused with upgrade guidance; there is no upper version cap.
  */
 
 import {
   PINNED_OPENCODE2_VERSION,
+  MINIMUM_OPENCODE2_VERSION,
   compareOpenCode2Versions,
   isAcceptableOpenCode2HealthVersion,
   isOpenCode1xVersion,
 } from './opencode2-pin.js';
 
 /** Lowest version with documented OpenChamber + OpenCode 2 contract tests. */
-export const RUNTIME_CONTRACT_MIN_VERIFIED = PINNED_OPENCODE2_VERSION;
+export const RUNTIME_CONTRACT_MIN_VERIFIED = MINIMUM_OPENCODE2_VERSION;
 
 /**
  * Optional / core capabilities and the minimum serve version that admits them.

package/server/lib/opencode/runtime-contract.test.js

@@ -13,14 +13,14 @@ import {
 } from './runtime-contract.js';
 
 describe('runtime contract admission (ticket 11)', () => {
-  it('records minimum verified bound from pin', () => {
-    expect(RUNTIME_CONTRACT_MIN_VERIFIED).toBe('2.0.12');
+  it('records the credential API floor independently of the install pin', () => {
+    expect(RUNTIME_CONTRACT_MIN_VERIFIED).toBe('2.0.20');
   });
 
   it('classifies version bands with a 2.x floor only', () => {
-    expect(classifyRuntimeVersionBand('2.0.12')).toBe('verified');
-    expect(classifyRuntimeVersionBand('2.0.14')).toBe('verified');
-    expect(classifyRuntimeVersionBand('2.0.15')).toBe('verified');
+    expect(classifyRuntimeVersionBand('2.0.19')).toBe('below-min');
+    expect(classifyRuntimeVersionBand('2.0.20')).toBe('verified');
+    expect(classifyRuntimeVersionBand('2.0.23')).toBe('verified');
     expect(classifyRuntimeVersionBand('2.1.0')).toBe('verified');
     expect(classifyRuntimeVersionBand('2.0.5')).toBe('below-min');
     expect(classifyRuntimeVersionBand('1.18.18')).toBe('1x');
@@ -30,8 +30,8 @@ describe('runtime contract admission (ticket 11)', () => {
 
   it('admits verified serve for core protocol and optional caps', () => {
     const result = evaluateRuntimeContract({
-      serveVersion: '2.0.12',
-      cliVersion: '2.0.12',
+      serveVersion: '2.0.20',
+      cliVersion: '2.0.20',
       reachable: true,
       authenticated: true,
       healthOk: true,
@@ -65,7 +65,7 @@ describe('runtime contract admission (ticket 11)', () => {
 
   it('admits newer 2.x above the documented floor for execution', () => {
     const result = evaluateRuntimeContract({
-      serveVersion: '2.0.15',
+      serveVersion: '2.0.23',
       reachable: true,
       authenticated: true,
       healthOk: true,
@@ -105,12 +105,12 @@ describe('runtime contract admission (ticket 11)', () => {
     expect(evaluateRuntimeContract({
       reachable: true,
       authenticated: false,
-      serveVersion: '2.0.12',
+      serveVersion: '2.0.20',
       healthOk: true,
     }).phase).toBe('unauthenticated');
 
     const migration = evaluateRuntimeContract({
-      serveVersion: '2.0.12',
+      serveVersion: '2.0.20',
       reachable: true,
       authenticated: true,
       healthOk: true,
@@ -122,7 +122,7 @@ describe('runtime contract admission (ticket 11)', () => {
     expect(migration.migrationExecutable).toBe(false);
 
     const mismatch = evaluateRuntimeContract({
-      serveVersion: '2.0.12',
+      serveVersion: '2.0.20',
       cliVersion: '2.0.14',
       reachable: true,
       authenticated: true,
@@ -179,7 +179,7 @@ describe('runtime contract admission (ticket 11)', () => {
       migrationAdmitTranscript: true,
     });
     const body = runtimeContractExecutionBlockedBody(contract);
-    expect(body.error).toContain('2.0.12');
+    expect(body.error).toContain('2.0.20');
     expect(body.error).toMatch(/Settings → About/i);
     expect(formatRuntimeContractBlockedError(contract)).toBe(body.error);
   });

package/server/lib/opencode/settings-normalization-runtime.js

@@ -44,7 +44,9 @@ export const createSettingsNormalizationRuntime = (dependencies) => {
       return value;
     }
     try {
-      return realpathSync(value);
+      // The JS implementation preserves input casing on case-insensitive volumes.
+      // Native realpath supplies the filesystem spelling used by Git and OpenCode.
+      return (realpathSync.native ?? realpathSync)(value);
     } catch {
       return value;
     }

package/server/lib/opencode/settings-normalization-runtime.test.js

@@ -22,6 +22,42 @@ const createTestRuntime = (overrides = {}) => {
 
 describe('settings normalization runtime - symlink resolution', () => {
   describe('normalizePathForPersistence', () => {
+    it('uses native realpath to recover filesystem casing instead of preserving the input spelling', () => {
+      const realpathSync = Object.assign((p) => p, {
+        native: (p) => p.replace('/code/', '/Code/'),
+      });
+      const runtime = createTestRuntime({ realpathSync, processLike: { platform: 'darwin' } });
+
+      expect(runtime.normalizePathForPersistence('/workspace/code/project')).toBe('/workspace/Code/project');
+      const result = runtime.normalizeSettingsPaths({
+        projects: [{ id: 'project', path: '/workspace/code/project' }],
+        lastDirectory: '/workspace/code/project',
+        pinnedDirectories: ['/workspace/code/project'],
+      });
+      expect(result.changed).toBe(true);
+      expect(result.settings.projects[0].path).toBe('/workspace/Code/project');
+      expect(result.settings.lastDirectory).toBe('/workspace/Code/project');
+      expect(result.settings.pinnedDirectories).toEqual(['/workspace/Code/project']);
+      expect(runtime.normalizeSettingsPaths(result.settings).changed).toBe(false);
+    });
+
+    it('preserves distinct directory casing when native realpath reports distinct locations', () => {
+      const runtime = createTestRuntime({ realpathSync: Object.assign((p) => p, { native: (p) => p }) });
+      expect(runtime.sanitizeProjects([
+        { id: 'lower', path: '/workspace/code/project' },
+        { id: 'upper', path: '/workspace/Code/project' },
+      ])).toHaveLength(2);
+    });
+
+    it('keeps unavailable paths when native realpath fails', () => {
+      const runtime = createTestRuntime({
+        realpathSync: Object.assign(() => '/incorrect-fallback', {
+          native: () => { throw new Error('EACCES'); },
+        }),
+      });
+      expect(runtime.normalizePathForPersistence('/unavailable/project')).toBe('/unavailable/project');
+    });
+
     it('resolves symlinks via realpathSync', () => {
       const runtime = createTestRuntime({
         realpathSync: (p) =>

package/server/lib/opencode/settings-runtime.test.js

@@ -5,8 +5,9 @@ import os from 'os';
 import path from 'path';
 import { createProjectIdFromPath } from '../projects/project-id.js';
 import { createSettingsRuntime } from './settings-runtime.js';
+import { createSettingsNormalizationRuntime } from './settings-normalization-runtime.js';
 
-const createRuntime = async () => {
+const createRuntime = async (overrides = {}) => {
   const tempRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'oc-settings-runtime-'));
   const settingsFilePath = path.join(tempRoot, 'settings.json');
   const runtime = createSettingsRuntime({
@@ -21,6 +22,7 @@ const createRuntime = async () => {
     normalizeStringArray: (values) => Array.isArray(values) ? values.filter((value) => typeof value === 'string') : [],
     formatSettingsResponse: (settings) => settings,
     resolveDirectoryCandidate: (value) => value,
+    ...overrides,
   });
 
   return {
@@ -34,6 +36,61 @@ const createRuntime = async () => {
 };
 
 describe('settings runtime', () => {
+  it('repairs existing project casing, migrates project data, and persists new paths canonically', async () => {
+    const normalization = createSettingsNormalizationRuntime({
+      os, path, processLike: process,
+      realpathSync: Object.assign((value) => value, {
+        native: (value) => value.replace(`${path.sep}code${path.sep}`, `${path.sep}Code${path.sep}`),
+      }),
+    });
+    let failSettingsWrite = true;
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime({
+      ...normalization,
+      fsPromises: {
+        ...fsPromises,
+        rename: async (source, target) => {
+          if (failSettingsWrite && path.basename(target) === 'settings.json') {
+            throw Object.assign(new Error('Simulated settings write failure'), { code: 'EIO' });
+          }
+          return fsPromises.rename(source, target);
+        },
+      },
+    });
+    try {
+      const legacyPath = path.join(tempRoot, 'code', 'project');
+      const canonicalPath = path.join(tempRoot, 'Code', 'project');
+      const oldId = createProjectIdFromPath(legacyPath);
+      const newId = createProjectIdFromPath(canonicalPath);
+      const projectsRoot = path.join(tempRoot, 'projects');
+      await fsPromises.mkdir(canonicalPath, { recursive: true });
+      await fsPromises.mkdir(projectsRoot, { recursive: true });
+      await fsPromises.writeFile(path.join(projectsRoot, `${oldId}.json`), JSON.stringify({ projectNotes: 'Keep these notes' }));
+      await fsPromises.writeFile(settingsFilePath, JSON.stringify({
+        projects: [{ id: oldId, path: legacyPath, label: 'My project' }],
+        activeProjectId: oldId,
+        lastDirectory: legacyPath,
+      }));
+
+      const original = await fsPromises.readFile(settingsFilePath, 'utf8');
+      await expect(runtime.readSettingsFromDiskMigrated()).rejects.toThrow('Simulated settings write failure');
+      expect(await fsPromises.readFile(settingsFilePath, 'utf8')).toBe(original);
+      failSettingsWrite = false;
+      const settings = await runtime.readSettingsFromDiskMigrated();
+      expect(settings.projects).toMatchObject([{ id: newId, path: canonicalPath, label: 'My project' }]);
+      expect(settings.activeProjectId).toBe(newId);
+      expect(settings.lastDirectory).toBe(canonicalPath);
+      expect(JSON.parse(await fsPromises.readFile(path.join(projectsRoot, `${newId}.json`), 'utf8')).projectNotes).toBe('Keep these notes');
+      expect(JSON.parse(await fsPromises.readFile(settingsFilePath, 'utf8'))).toEqual(settings);
+      expect(await runtime.readSettingsFromDiskMigrated()).toEqual(settings);
+
+      const saved = await runtime.persistSettings({ ...settings, projects: [{ id: oldId, path: legacyPath }] });
+      expect(saved.projects).toMatchObject([{ id: newId, path: canonicalPath }]);
+      expect(saved.activeProjectId).toBe(newId);
+    } finally {
+      await cleanup();
+    }
+  });
+
   it('migrates absent notification toggles to their defaults', async () => {
     const { runtime, settingsFilePath, cleanup } = await createRuntime();
     try {

package/server/lib/opencode/shared.js

@@ -2,18 +2,18 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import yaml from 'yaml';
-import { parse as parseJsonc } from 'jsonc-parser';
+import {
+  getGlobalConfigDirectory, readConfigFile, isPlainObject, readConfigLayers,
+  readConfig, getConfigForPath, writeConfig, getJsonEntrySource, getJsonWriteTarget,
+} from './config-files.js';
 
 // ============== PATH CONSTANTS ==============
 
-const OPENCODE_CONFIG_DIR = path.join(os.homedir(), '.config', 'opencode');
+const OPENCODE_CONFIG_DIR = getGlobalConfigDirectory();
 const AGENT_DIR = path.join(OPENCODE_CONFIG_DIR, 'agents');
 const COMMAND_DIR = path.join(OPENCODE_CONFIG_DIR, 'commands');
 const SKILL_DIR = path.join(OPENCODE_CONFIG_DIR, 'skills');
-const CONFIG_FILE = path.join(OPENCODE_CONFIG_DIR, 'config.json');
-const CUSTOM_CONFIG_FILE = process.env.OPENCODE_CONFIG
-  ? path.resolve(process.env.OPENCODE_CONFIG)
-  : null;
+const CONFIG_FILE = path.join(OPENCODE_CONFIG_DIR, 'opencode.jsonc');
 const PROMPT_FILE_PATTERN = /^\{file:(.+)\}$/i;
 
 // ============== SCOPE TYPE CONSTANTS ==============
@@ -89,175 +89,6 @@ function writeMdFile(filePath, frontmatter, body) {
 
 // ============== CONFIG FILE OPERATIONS ==============
 
-function getProjectConfigCandidates(workingDirectory) {
-  if (!workingDirectory) return [];
-  return [
-    path.join(workingDirectory, 'opencode.json'),
-    path.join(workingDirectory, 'opencode.jsonc'),
-    path.join(workingDirectory, '.opencode', 'opencode.json'),
-    path.join(workingDirectory, '.opencode', 'opencode.jsonc'),
-  ];
-}
-
-function getProjectConfigPath(workingDirectory) {
-  if (!workingDirectory) return null;
-
-  const candidates = getProjectConfigCandidates(workingDirectory);
-
-  for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  return candidates[0];
-}
-
-function getConfigPaths(workingDirectory) {
-  return {
-    userPaths: [
-      path.join(OPENCODE_CONFIG_DIR, 'config.json'),
-      path.join(OPENCODE_CONFIG_DIR, 'opencode.json'),
-      path.join(OPENCODE_CONFIG_DIR, 'opencode.jsonc'),
-    ],
-    projectPath: getProjectConfigPath(workingDirectory),
-    customPath: CUSTOM_CONFIG_FILE
-  };
-}
-
-function getPrimaryUserConfigPath(userPaths) {
-  for (const userPath of userPaths) {
-    if (fs.existsSync(userPath)) {
-      return userPath;
-    }
-  }
-
-  return CONFIG_FILE;
-}
-
-function readConfigFile(filePath) {
-  if (!filePath || !fs.existsSync(filePath)) {
-    return {};
-  }
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const normalized = content.trim();
-    if (!normalized) {
-      return {};
-    }
-    return parseJsonc(normalized, [], { allowTrailingComma: true });
-  } catch (error) {
-    console.error(`Failed to read config file: ${filePath}`, error);
-    throw new Error('Failed to read OpenCode configuration');
-  }
-}
-
-function isPlainObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function mergeConfigs(base, override) {
-  if (!isPlainObject(base) || !isPlainObject(override)) {
-    return override;
-  }
-  const result = { ...base };
-  for (const [key, value] of Object.entries(override)) {
-    if (key in result) {
-      const baseValue = result[key];
-      if (isPlainObject(baseValue) && isPlainObject(value)) {
-        result[key] = mergeConfigs(baseValue, value);
-      } else {
-        result[key] = value;
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-function readConfigLayers(workingDirectory) {
-  const { userPaths, projectPath, customPath } = getConfigPaths(workingDirectory);
-  const userPath = getPrimaryUserConfigPath(userPaths);
-  const userConfig = readConfigFile(userPath);
-  const projectConfig = readConfigFile(projectPath);
-  const customConfig = readConfigFile(customPath);
-  const mergedConfig = mergeConfigs(mergeConfigs(userConfig, projectConfig), customConfig);
-
-  return {
-    userConfig,
-    projectConfig,
-    customConfig,
-    mergedConfig,
-    paths: { userPath, projectPath, customPath }
-  };
-}
-
-function readConfig(workingDirectory) {
-  return readConfigLayers(workingDirectory).mergedConfig;
-}
-
-function getConfigForPath(layers, targetPath) {
-  if (!targetPath) {
-    return layers.userConfig;
-  }
-  if (layers.paths.customPath && targetPath === layers.paths.customPath) {
-    return layers.customConfig;
-  }
-  if (layers.paths.projectPath && targetPath === layers.paths.projectPath) {
-    return layers.projectConfig;
-  }
-  return layers.userConfig;
-}
-
-function writeConfig(config, filePath = CONFIG_FILE) {
-  try {
-    if (fs.existsSync(filePath)) {
-      const backupFile = `${filePath}.openchamber.backup`;
-      fs.copyFileSync(filePath, backupFile);
-      console.log(`Created config backup: ${backupFile}`);
-    }
-
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(config, null, 2), 'utf8');
-    console.log(`Successfully wrote config file: ${filePath}`);
-  } catch (error) {
-    console.error(`Failed to write config file: ${filePath}`, error);
-    throw new Error('Failed to write OpenCode configuration');
-  }
-}
-
-function getJsonEntrySource(layers, sectionKey, entryName) {
-  const { userConfig, projectConfig, customConfig, paths } = layers;
-  const customSection = customConfig?.[sectionKey]?.[entryName];
-  if (customSection !== undefined) {
-    return { section: customSection, config: customConfig, path: paths.customPath, exists: true };
-  }
-
-  const projectSection = projectConfig?.[sectionKey]?.[entryName];
-  if (projectSection !== undefined) {
-    return { section: projectSection, config: projectConfig, path: paths.projectPath, exists: true };
-  }
-
-  const userSection = userConfig?.[sectionKey]?.[entryName];
-  if (userSection !== undefined) {
-    return { section: userSection, config: userConfig, path: paths.userPath, exists: true };
-  }
-
-  return { section: null, config: null, path: null, exists: false };
-}
-
-function getJsonWriteTarget(layers, preferredScope) {
-  const { userConfig, projectConfig, customConfig, paths } = layers;
-  if (paths.customPath) {
-    return { config: customConfig, path: paths.customPath };
-  }
-  if (preferredScope === AGENT_SCOPE.PROJECT && paths.projectPath) {
-    return { config: projectConfig, path: paths.projectPath };
-  }
-  return { config: userConfig, path: paths.userPath };
-}
-
 // ============== GIT/WORKTREE HELPERS ==============
 
 function getAncestors(startDir, stopDir) {

package/server/lib/opencode/update-discovery.js

@@ -0,0 +1,39 @@
+import { OPENCODE2_NPM_PACKAGE } from './opencode2-pin.js';
+
+const stableVersion = (value) => typeof value === 'string' && /^2\.\d+\.\d+$/.test(value) ? value : null;
+
+// One bounded registry snapshot per host, shared by all connected clients.
+export function createOpenCodeUpdateDiscovery({ fetchImpl = (...args) => fetch(...args), now = Date.now } = {}) {
+  let snapshot = null;
+  let expiresAt = 0;
+  let pending = null;
+
+  const registry = () => {
+    if (snapshot && now() < expiresAt) return Promise.resolve(snapshot);
+    if (pending) return pending;
+    pending = (async () => {
+      try {
+        const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(OPENCODE2_NPM_PACKAGE)}/latest`, {
+          headers: { Accept: 'application/json' },
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) throw new Error(`OpenCode registry returned HTTP ${response.status}`);
+        const version = stableVersion((await response.json()).version);
+        if (!version) throw new Error('OpenCode registry did not return a stable 2.x version');
+        snapshot = { version, error: null };
+        expiresAt = now() + 5 * 60_000;
+      } catch (error) {
+        snapshot = { version: snapshot?.version ?? null, error: error instanceof Error ? error.message : 'OpenCode registry check failed' };
+        expiresAt = now() + 30_000;
+      }
+      return snapshot;
+    })().finally(() => { pending = null; });
+    return pending;
+  };
+
+  return async () => {
+    const remote = await registry();
+    if (remote.error) throw new Error(remote.error);
+    return remote.version;
+  };
+}

package/server/lib/opencode/update-discovery.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createOpenCodeUpdateDiscovery } from './update-discovery.js';
+
+describe('OpenCode remote update discovery', () => {
+  it('shares concurrent requests, caches for five minutes and refreshes after expiry', async () => {
+    let time = 0;
+    const fetchImpl = vi.fn(async () => Response.json({ version: '2.0.18' }));
+    const discover = createOpenCodeUpdateDiscovery({ fetchImpl, now: () => time });
+    expect(await Promise.all([discover(), discover(), discover()])).toEqual(['2.0.18', '2.0.18', '2.0.18']);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    time = 299_999;
+    await discover();
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    time = 300_000;
+    fetchImpl.mockResolvedValueOnce(Response.json({ version: '2.0.19' }));
+    expect(await discover()).toBe('2.0.19');
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(fetchImpl.mock.calls[0][1].signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it.each(['1.18.4', '3.0.0', '2.0.19-beta.1', 'latest', undefined])('rejects an invalid stable release %s', async (version) => {
+    const discover = createOpenCodeUpdateDiscovery({ fetchImpl: async () => Response.json({ version }) });
+    await expect(discover()).rejects.toThrow('stable 2.x');
+  });
+
+  it('backs off errors without reporting stale success, then recovers', async () => {
+    let time = 0;
+    const fetchImpl = vi.fn().mockResolvedValueOnce(Response.json({ version: '2.0.18' }))
+      .mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce(Response.json({ version: '2.0.19' }));
+    const discover = createOpenCodeUpdateDiscovery({ fetchImpl, now: () => time });
+    await discover();
+    time = 300_000;
+    await expect(discover()).rejects.toThrow('offline');
+    await expect(discover()).rejects.toThrow('offline');
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    time += 30_000;
+    expect(await discover()).toBe('2.0.19');
+  });
+});