@openchambery/web 1.19.20 → 2.0.0-beta.1

package/server/lib/opencode/proxy.js

@@ -21,6 +21,20 @@ import {
   stripIncludeReasoningParam,
 } from '../event-stream/reasoning-projection.js';
 
+/**
+ * v2 protocol mounts every JSON/SSE route under `/api`
+ * (`@opencode-ai/protocol` groups). Host traffic is already `/api/*`.
+ * Express `app.use('/api', …)` strips that prefix from `req.url`; put it back
+ * before talking to opencode2. Passing a root `/session` path to v2 returns
+ * the bundled Web UI HTML (`text/html`) and the SDK throws UnsupportedContentType.
+ */
+export const toUpstreamOpenCodeApiPath = (requestUrl) => {
+  const raw = typeof requestUrl === 'string' ? requestUrl : '';
+  if (!raw || raw === '/') return '/api';
+  if (raw.startsWith('/api/') || raw === '/api' || raw.startsWith('/api?')) return raw;
+  return raw.startsWith('/') ? `/api${raw}` : `/api/${raw}`;
+};
+
 export const createDirectoryQueryCanonicalizer = ({ realpath, ...cacheOptions } = {}) => {
   const realpathCache = createRealpathCache({ fallbackOnError: true, realpath, ...cacheOptions });
 
@@ -183,10 +197,19 @@ const sanitizeSessionListItem = (session) => {
 };
 
 const sanitizeSessionListPayload = (payload) => {
-  if (!Array.isArray(payload)) {
-    return payload;
+  if (Array.isArray(payload)) {
+    return payload.map((session) => sanitizeSessionListItem(session));
   }
-  return payload.map((session) => sanitizeSessionListItem(session));
+  if (payload && typeof payload === 'object' && Array.isArray(payload.data)) {
+    return { ...payload, data: payload.data.map((session) => sanitizeSessionListItem(session)) };
+  }
+  return payload;
+};
+
+const sessionListRecords = (payload) => {
+  if (Array.isArray(payload)) return payload;
+  if (payload && typeof payload === 'object' && Array.isArray(payload.data)) return payload.data;
+  return null;
 };
 
 export const isInteractiveSessionRequest = (method, requestUrl) => {
@@ -226,8 +249,56 @@ export const registerOpenCodeProxy = (app, deps) => {
     ensureOpenCodeApiPrefix,
     onInteractiveSessionRequest,
     onSessionTurnAdmission,
+    // OpenCode 2.x has no session-metadata update route. When the Host store is
+    // wired, fold its per-session metadata onto list/detail responses so
+    // clients keep reading `session.metadata` where they always did.
+    getStoredSessionMetadata = null,
   } = deps;
 
+  /**
+   * `{ [sessionID]: metadata }` for the current instance, or `null` when the
+   * store cannot answer. `null` means "unknown", and an unknown answer leaves
+   * the upstream record untouched — never rewrite a session as empty metadata.
+   */
+  const readStoredSessionMetadata = async () => {
+    if (typeof getStoredSessionMetadata !== 'function') return null;
+    try {
+      const stored = await getStoredSessionMetadata();
+      return stored && typeof stored === 'object' ? stored : null;
+    } catch (error) {
+      console.warn('[proxy] session metadata unavailable:', error?.message ?? error);
+      return null;
+    }
+  };
+
+  /**
+   * OpenChamber's stored metadata wins per key: OpenCode only ever saw what was
+   * set at create time, and everything written since lives on our side.
+   */
+  const withStoredMetadata = (session, stored) => {
+    if (!session || typeof session !== 'object' || typeof session.id !== 'string') return session;
+    const ours = stored[session.id];
+    if (!ours || typeof ours !== 'object' || Array.isArray(ours)) return session;
+    const theirs = session.metadata && typeof session.metadata === 'object' && !Array.isArray(session.metadata)
+      ? session.metadata
+      : {};
+    return { ...session, metadata: { ...theirs, ...ours } };
+  };
+
+  const overlaySession = (session, stored) => {
+    if (!stored) return session;
+    return withStoredMetadata(session, stored);
+  };
+
+  const overlayOwnedStateOnList = async (payload) => {
+    const records = sessionListRecords(payload);
+    if (!records) return payload;
+    const stored = await readStoredSessionMetadata();
+    if (!stored) return payload;
+    const overlaid = records.map((session) => overlaySession(session, stored));
+    return Array.isArray(payload) ? overlaid : { ...payload, data: overlaid };
+  };
+
   if (app.get('opencodeProxyConfigured')) {
     return;
   }
@@ -419,7 +490,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     try {
       // Strip includeReasoning before building the upstream OpenCode path.
       const strippedUrl = stripIncludeReasoningParam(requestUrl);
-      const upstreamPath = strippedUrl.startsWith('/api') ? strippedUrl.slice(4) || '/' : strippedUrl;
+      const upstreamPath = toUpstreamOpenCodeApiPath(strippedUrl);
       const headers = normalizeForwardedDirectoryHeaders(
         collectForwardProxyHeaders(req.headers, getOpenCodeAuthHeaders())
       );
@@ -625,8 +696,7 @@ export const registerOpenCodeProxy = (app, deps) => {
     const requestUrl = typeof req.originalUrl === 'string' && req.originalUrl.length > 0
       ? req.originalUrl
       : (typeof req.url === 'string' ? req.url : '');
-    const upstreamPathRaw = requestUrl.startsWith('/api') ? requestUrl.slice(4) || '/' : requestUrl;
-    return canonicalizeDirectoryQuery(upstreamPathRaw);
+    return canonicalizeDirectoryQuery(toUpstreamOpenCodeApiPath(requestUrl));
   };
 
   const forwardSanitizedSessionListRequest = async (req, res, next, logLabel) => {
@@ -643,14 +713,14 @@ export const registerOpenCodeProxy = (app, deps) => {
         return;
       }
 
-      if (result.parseError || !Array.isArray(result.payload)) {
+      if (result.parseError || !sessionListRecords(result.payload)) {
         res.setHeader('content-type', result.contentType);
         res.end(result.bodyText);
         return;
       }
 
       res.setHeader('content-type', result.contentType);
-      res.json(sanitizeSessionListPayload(result.payload));
+      res.json(await overlayOwnedStateOnList(sanitizeSessionListPayload(result.payload)));
     } catch (error) {
       if (isAbortError(error)) {
         return;
@@ -735,7 +805,7 @@ export const registerOpenCodeProxy = (app, deps) => {
   const READINESS_HOLD_POLL_MS = 75;
   const READINESS_HOLD_MAX_MS = 6000;
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-  const isStillWaiting = (runtimeState) => {
+  const isProcessWarmingUp = (runtimeState) => {
     const waitElapsed = runtimeState.openCodeNotReadySince === 0 ? 0 : Date.now() - runtimeState.openCodeNotReadySince;
     return (
       (!runtimeState.isOpenCodeReady && (runtimeState.openCodeNotReadySince === 0 || waitElapsed < OPEN_CODE_READY_GRACE_MS)) ||
@@ -744,6 +814,18 @@ export const registerOpenCodeProxy = (app, deps) => {
     );
   };
 
+  // Process warmup keeps the existing grace window. V1 migration is separate:
+  // admitTranscript=false holds with no grace until the gate admits or the
+  // client cancels. After grace, a still-running migration must not next()
+  // an empty session list through as an authoritative success.
+  const isMigrationBlockingTranscript = (runtimeState) => (
+    runtimeState?.v1Migration != null && runtimeState.v1Migration.admitTranscript !== true
+  );
+
+  const shouldHoldProxiedRequest = (runtimeState) => (
+    isProcessWarmingUp(runtimeState) || isMigrationBlockingTranscript(runtimeState)
+  );
+
   app.use('/api', async (req, res, next) => {
     if (
       req.path.startsWith('/themes/custom') ||
@@ -758,18 +840,22 @@ export const registerOpenCodeProxy = (app, deps) => {
       return next();
     }
 
-    if (!isStillWaiting(getRuntime())) {
+    if (!shouldHoldProxiedRequest(getRuntime())) {
       return next();
     }
 
-    const deadline = Date.now() + Math.min(OPEN_CODE_READY_GRACE_MS, READINESS_HOLD_MAX_MS);
-    while (Date.now() < deadline) {
+    const processDeadline = Date.now() + Math.min(OPEN_CODE_READY_GRACE_MS, READINESS_HOLD_MAX_MS);
+    while (true) {
       // Client gave up (closed/aborted) — stop holding.
       if (res.writableEnded || req.aborted) return;
-      await sleep(READINESS_HOLD_POLL_MS);
-      if (!isStillWaiting(getRuntime())) {
+      const runtimeState = getRuntime();
+      if (!shouldHoldProxiedRequest(runtimeState)) {
         return next();
       }
+      if (!isMigrationBlockingTranscript(runtimeState) && Date.now() >= processDeadline) {
+        break;
+      }
+      await sleep(READINESS_HOLD_POLL_MS);
     }
 
     if (!res.headersSent) {
@@ -852,7 +938,7 @@ export const registerOpenCodeProxy = (app, deps) => {
           return bTime - aTime;
         });
         console.log(`[SessionMerge] ${globalSessions?.length || 0} global + ${extraSessions.length} extra = ${merged.length} total`);
-        return res.json(sanitizeSessionListPayload(merged));
+        return res.json(await overlayOwnedStateOnList(sanitizeSessionListPayload(merged)));
       } catch (error) {
         console.log(`[SessionMerge] Error: ${error.message}`);
         return res.status(500).json({ error: error.message || 'Failed to merge Windows sessions' });
@@ -864,6 +950,55 @@ export const registerOpenCodeProxy = (app, deps) => {
     return forwardSanitizedSessionListRequest(req, res, next, 'session.list');
   });
 
+  // One session: the same metadata overlay as the list, so a detail read agrees
+  // with the list it came from. Everything else about the record is forwarded
+  // untouched. Without a store, fall through to the generic proxy.
+  app.get('/api/session/:sessionID', async (req, res, next) => {
+    if (typeof getStoredSessionMetadata !== 'function') return next();
+    // Nested routes (message, children, …) are registered separately; Express
+    // still matches this pattern for bare session ids only when no further
+    // segment is present — but be defensive if a child path slips through.
+    if (req.path.includes('/message') || String(req.params.sessionID || '').includes('/')) {
+      return next();
+    }
+    try {
+      const upstreamPath = await getRequestUpstreamPath(req);
+      const result = await fetchSessionListPayload(upstreamPath, { req });
+
+      res.status(result.upstream.status);
+      applyForwardProxyResponseHeaders(result.upstream.headers, res);
+      res.setHeader('content-type', result.contentType);
+
+      const record = result.isJson && !result.parseError ? result.payload : null;
+      const session = record && typeof record === 'object' && !Array.isArray(record)
+        ? (record.data && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : record)
+        : null;
+      if (!session || typeof session.id !== 'string') {
+        res.end(result.bodyText);
+        return;
+      }
+
+      const stored = await readStoredSessionMetadata();
+      if (!stored) {
+        res.end(result.bodyText);
+        return;
+      }
+
+      const overlaid = overlaySession(session, stored);
+      res.json(record.data && typeof record.data === 'object' && !Array.isArray(record.data)
+        ? { ...record, data: overlaid }
+        : overlaid);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      console.error('[proxy] OpenCode session.get proxy error:', error?.message ?? error);
+      if (!res.headersSent) {
+        res.status(503).json({ error: 'OpenCode service unavailable' });
+        return;
+      }
+      next(error);
+    }
+  });
+
   // Official session.messages list (not exact message — that is owned by
   // session-turn-pages and registered before this proxy).
   app.get('/api/session/:sessionID/message', (req, res, next) => {
@@ -881,7 +1016,9 @@ export const registerOpenCodeProxy = (app, deps) => {
   const apiProxy = createProxyMiddleware({
     target: resolveProxyTarget(),
     changeOrigin: true,
-    pathRewrite: { '^/api': '' },
+    // Express already stripped the `/api` mount. Restore it so v2 receives
+    // `/api/agent` rather than `/agent` (which serves the Web UI HTML).
+    pathRewrite: (pathValue) => toUpstreamOpenCodeApiPath(pathValue),
     timeout: PROXY_REQUEST_TIMEOUT_MS,
     proxyTimeout: PROXY_REQUEST_TIMEOUT_MS,
     // Dynamic target — port can change after restart

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

@@ -8,8 +8,21 @@ import {
   normalizeForwardedDirectoryHeaders,
   registerOpenCodeProxy,
   resolveSessionTurnAdmissionRequest,
+  toUpstreamOpenCodeApiPath,
 } from './proxy.js';
 
+describe('toUpstreamOpenCodeApiPath', () => {
+  it('keeps v2 /api paths and restores the prefix Express strips at the /api mount', () => {
+    expect(toUpstreamOpenCodeApiPath('/api/agent')).toBe('/api/agent');
+    expect(toUpstreamOpenCodeApiPath('/api/session?directory=/repo')).toBe('/api/session?directory=/repo');
+    expect(toUpstreamOpenCodeApiPath('/api')).toBe('/api');
+    expect(toUpstreamOpenCodeApiPath('/agent')).toBe('/api/agent');
+    expect(toUpstreamOpenCodeApiPath('/session/ses_1/message')).toBe('/api/session/ses_1/message');
+    expect(toUpstreamOpenCodeApiPath('/')).toBe('/api');
+    expect(toUpstreamOpenCodeApiPath('')).toBe('/api');
+  });
+});
+
 const originalFetch = globalThis.fetch;
 
 afterEach(() => {
@@ -300,3 +313,110 @@ describe('registerOpenCodeProxy reasoning projection routes', () => {
     expect(res.body[0].parts[0].text).toBe('keep-me');
   });
 });
+
+describe('registerOpenCodeProxy session metadata overlay', () => {
+  const mountProxyWithMetadata = (getStoredSessionMetadata) => {
+    const app = express();
+    registerOpenCodeProxy(app, {
+      fs: { promises: { realpath: async (v) => v } },
+      os: {},
+      path: {},
+      OPEN_CODE_READY_GRACE_MS: 1000,
+      LONG_REQUEST_TIMEOUT_MS: 60_000,
+      SSE_UPSTREAM_CONNECT_TIMEOUT_MS: 5_000,
+      SSE_UPSTREAM_STALL_TIMEOUT_MS: 5_000,
+      getRuntime: readyRuntime,
+      getOpenCodeAuthHeaders: () => ({}),
+      buildOpenCodeUrl: (path) => `http://127.0.0.1:4096${path}`,
+      ensureOpenCodeApiPrefix: () => {},
+      getStoredSessionMetadata,
+    });
+    return app;
+  };
+
+  it('merges Host store metadata onto session list and detail (store keys win)', async () => {
+    globalThis.fetch = vi.fn(async (url) => {
+      const path = String(url).split('?')[0];
+      if (path.endsWith('/api/session') || path.endsWith('/session')) {
+        return {
+          ok: true,
+          status: 200,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: async () => JSON.stringify([
+            {
+              id: 'ses_1',
+              title: 'Alpha',
+              metadata: { fromOpenCode: true, shared: 'theirs' },
+            },
+            { id: 'ses_2', title: 'Beta' },
+          ]),
+        };
+      }
+      if (path.includes('/session/ses_1')) {
+        return {
+          ok: true,
+          status: 200,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: async () => JSON.stringify({
+            id: 'ses_1',
+            title: 'Alpha',
+            metadata: { fromOpenCode: true, shared: 'theirs' },
+          }),
+        };
+      }
+      return {
+        ok: false,
+        status: 404,
+        headers: new Headers({ 'content-type': 'application/json' }),
+        text: async () => JSON.stringify({ error: 'not found' }),
+      };
+    });
+
+    const app = mountProxyWithMetadata(async () => ({
+      ses_1: { openchamber: { goal: { status: 'active' } }, shared: 'ours' },
+    }));
+
+    const list = await request(app).get('/api/session');
+    expect(list.status).toBe(200);
+    expect(list.body[0]).toMatchObject({
+      id: 'ses_1',
+      metadata: {
+        fromOpenCode: true,
+        shared: 'ours',
+        openchamber: { goal: { status: 'active' } },
+      },
+    });
+    expect(list.body[1].metadata).toBeUndefined();
+
+    const detail = await request(app).get('/api/session/ses_1');
+    expect(detail.status).toBe(200);
+    expect(detail.body).toMatchObject({
+      id: 'ses_1',
+      metadata: {
+        fromOpenCode: true,
+        shared: 'ours',
+        openchamber: { goal: { status: 'active' } },
+      },
+    });
+  });
+
+  it('leaves upstream records untouched when the store throws', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    globalThis.fetch = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      text: async () => JSON.stringify([
+        { id: 'ses_1', title: 'Alpha', metadata: { fromOpenCode: true } },
+      ]),
+    }));
+
+    const app = mountProxyWithMetadata(async () => {
+      throw new Error('store down');
+    });
+
+    const list = await request(app).get('/api/session');
+    expect(list.status).toBe(200);
+    expect(list.body[0]).toEqual({ id: 'ses_1', title: 'Alpha', metadata: { fromOpenCode: true } });
+  });
+});

package/server/lib/opencode/routes.js

@@ -1,5 +1,6 @@
 import { createProjectIdFromPath } from '../projects/project-id.js';
 import { projectBootstrapSettingsResponse } from './settings-helpers.js';
+import { PINNED_OPENCODE2_VERSION, isOpenCode1xVersion, resolveOpenCode2UpgradeTarget } from './opencode2-pin.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -22,6 +23,7 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
     buildOpenCodeUrl,
     getOpenCodeAuthHeaders,
     onSettingsPersisted,
+    getIsExternalOpenCode = () => false,
   } = dependencies;
 
   let authLibrary = null;
@@ -50,7 +52,7 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
   };
 
   const readOpenCodeCurrentVersion = async () => {
-    const healthResponse = await fetch(buildOpenCodeUrl('/global/health', ''), {
+    const healthResponse = await fetch(buildOpenCodeUrl('/api/info', ''), {
       method: 'GET',
       headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
     });
@@ -183,37 +185,30 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
 
   app.post('/api/opencode/upgrade', async (req, res) => {
     try {
-      if (await isBundledOpenCodeBinaryActive()) {
+      if (getIsExternalOpenCode()) {
         return res.status(409).json({
           success: false,
-          error: 'OpenCode is bundled with OpenChamber Desktop and cannot be upgraded separately.',
+          error: 'This is your own OpenCode serve. OpenChamber will not upgrade or restart it.',
         });
       }
 
-      const target = normalizeOpenCodeUpgradeTarget(req.body?.target);
-      if (!target) {
-        return res.status(400).json({
+      if (await isBundledOpenCodeBinaryActive()) {
+        return res.status(409).json({
           success: false,
-          error: 'OpenCode upgrade requires a semantic version target',
+          error: 'OpenCode is bundled with OpenChamber Desktop and cannot be upgraded separately.',
         });
       }
 
-      const response = await fetch(buildOpenCodeUrl('/global/upgrade', ''), {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Accept: 'application/json',
-          ...getOpenCodeAuthHeaders(),
-        },
-        body: JSON.stringify({ target }),
-      });
-      const payload = await response.json().catch(() => null);
-      if (!response.ok) {
-        return res.status(response.status).json({
+      const rawTarget = typeof req.body?.target === 'string' && req.body.target.trim().length > 0
+        ? req.body.target.trim()
+        : undefined;
+      if (isOpenCode1xVersion(rawTarget)) {
+        return res.status(400).json({
           success: false,
-          error: readOpenCodeUpgradeError(payload, response.statusText || 'Failed to upgrade OpenCode'),
+          error: 'OpenCode upgrade refuses 1.x targets. Only pinned opencode2 is allowed.',
         });
       }
+      const target = resolveOpenCode2UpgradeTarget(rawTarget);
 
       try {
         await refreshOpenCodeAfterConfigChange('OpenCode upgrade');
@@ -227,7 +222,7 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
         });
       }
 
-      return res.json({ ...(payload ?? { success: true }), restarted: true });
+      return res.json({ success: true, restarted: true, version: target, pinned: true });
     } catch (error) {
       console.error('Failed to upgrade OpenCode:', error);
       return res.status(500).json({
@@ -249,13 +244,10 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
         });
       }
 
-      const [healthResponse, latestVersion] = await Promise.all([
-        fetch(buildOpenCodeUrl('/global/health', ''), {
-          method: 'GET',
-          headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
-        }),
-        fetchLatestOpenCodeVersion(),
-      ]);
+      const healthResponse = await fetch(buildOpenCodeUrl('/api/info', ''), {
+        method: 'GET',
+        headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
+      });
       const health = await healthResponse.json().catch(() => null);
       if (!healthResponse.ok) {
         return res.status(healthResponse.status).json({
@@ -264,10 +256,11 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
         });
       }
       const currentVersion = typeof health?.version === 'string' ? health.version.replace(/^v/, '') : null;
+      const latestVersion = isOpenCode1xVersion(PINNED_OPENCODE2_VERSION) ? null : PINNED_OPENCODE2_VERSION;
       if (!currentVersion || !latestVersion) {
-        return res.json({ available: null, currentVersion, latestVersion: latestVersion || null });
+        return res.json({ available: null, currentVersion, latestVersion });
       }
-      const available = compareVersions(latestVersion, currentVersion) > 0;
+      const available = !isOpenCode1xVersion(currentVersion) && compareVersions(latestVersion, currentVersion) > 0;
       return res.json({
         available,
         currentVersion,
@@ -283,7 +276,7 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
 
   app.get('/api/opencode/health', async (_req, res) => {
     try {
-      const healthResponse = await fetch(buildOpenCodeUrl('/global/health', ''), {
+      const healthResponse = await fetch(buildOpenCodeUrl('/api/info', ''), {
         method: 'GET',
         headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
         signal: AbortSignal.timeout(4_000),
@@ -306,7 +299,7 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
 
   app.get('/api/opencode/version', async (_req, res) => {
     try {
-      const healthResponse = await fetch(buildOpenCodeUrl('/global/health', ''), {
+      const healthResponse = await fetch(buildOpenCodeUrl('/api/info', ''), {
         method: 'GET',
         headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
       });

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

@@ -4,6 +4,7 @@ import request from 'supertest';
 import fs from 'fs';
 
 import { registerOpenCodeRoutes } from './routes.js';
+import { isOpenCode1xVersion } from './opencode2-pin.js';
 
 const createDependencies = ({ formatSettingsResponse }) => ({
   crypto: {},
@@ -126,79 +127,77 @@ describe('behavior AGENTS.md route', () => {
   });
 });
 
-describe('opencode upgrade route', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  const jsonResponse = (body, status = 200, statusText = '') =>
-    new Response(JSON.stringify(body), {
-      status,
-      statusText,
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-  const createUpgradeApp = () => {
+describe('opencode2 upgrade pin (ticket 12)', () => {
+  const createUpgradeApp = (overrides = {}) => {
     const app = express();
     app.use(express.json());
-    const deps = createDependencies({ formatSettingsResponse: vi.fn(() => ({})) });
-    deps.getOpenCodeResolutionSnapshot.mockResolvedValue({ source: 'path' });
-    deps.buildOpenCodeUrl.mockImplementation((pathname) => `http://opencode.test${pathname}`);
-    deps.refreshOpenCodeAfterConfigChange.mockResolvedValue(undefined);
+    const deps = {
+      ...createDependencies({ formatSettingsResponse: vi.fn(() => ({})) }),
+      getOpenCodeResolutionSnapshot: vi.fn(async () => ({ source: 'path' })),
+      buildOpenCodeUrl: vi.fn((pathname) => `http://opencode.test${pathname}`),
+      getOpenCodeAuthHeaders: vi.fn(() => ({ Authorization: 'Basic secret' })),
+      refreshOpenCodeAfterConfigChange: vi.fn(async () => undefined),
+      ...overrides,
+    };
     registerOpenCodeRoutes(app, deps);
     return { app, deps };
   };
 
-  it('forwards an explicit target to OpenCode /global/upgrade', async () => {
-    const fetchMock = vi.fn(async (url, init) => {
-      expect(String(url)).toBe('http://opencode.test/global/upgrade');
-      expect(JSON.parse(init.body)).toEqual({ target: '1.18.26' });
-      return jsonResponse({ success: true, version: '1.18.26' });
-    });
-    globalThis.fetch = fetchMock;
+  it('rejects 1.x upgrade targets and never calls /global/upgrade', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
     const { app } = createUpgradeApp();
 
     const response = await request(app)
       .post('/api/opencode/upgrade')
-      .send({ target: 'v1.18.26' })
-      .expect(200);
+      .send({ target: '1.18.4' })
+      .expect(400);
 
-    expect(response.body).toEqual({ success: true, version: '1.18.26', restarted: true });
-    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(response.body.success).toBe(false);
+    expect(response.body.error).toMatch(/1\.x/);
+    expect(fetchMock).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
   });
 
-  it('rejects an omitted target without calling OpenCode', async () => {
-    const fetchMock = vi.fn();
-    globalThis.fetch = fetchMock;
+  it('does not treat a 1.x latest string as an available upgrade', async () => {
+    const fetchMock = vi.fn(async (url) => {
+      const href = String(url);
+      if (href.includes('/api/info')) {
+        return {
+          ok: true,
+          json: async () => ({ version: '2.0.12', healthy: true }),
+        };
+      }
+      if (href.includes('registry.npmjs.org/opencode-ai') || href.includes('github.com/repos/anomalyco/opencode')) {
+        return { ok: true, json: async () => ({ version: '1.18.18', tag_name: 'v1.18.18' }) };
+      }
+      throw new Error(`unexpected fetch ${href}`);
+    });
+    vi.stubGlobal('fetch', fetchMock);
     const { app } = createUpgradeApp();
 
-    const response = await request(app).post('/api/opencode/upgrade').send({}).expect(400);
+    const response = await request(app).get('/api/opencode/upgrade-status').expect(200);
 
-    expect(response.body).toEqual({
-      success: false,
-      error: 'OpenCode upgrade requires a semantic version target',
-    });
-    expect(fetchMock).not.toHaveBeenCalled();
+    expect(response.body.latestVersion).not.toMatch(/^v?1\./);
+    expect(isOpenCode1xVersion(response.body.latestVersion)).toBe(false);
+    expect(String(response.body.latestVersion || '')).not.toContain('1.18');
+    vi.unstubAllGlobals();
   });
 
-  it('surfaces OpenCode schema BadRequest messages instead of statusText', async () => {
-    const fetchMock = vi.fn(async () =>
-      jsonResponse(
-        { name: 'BadRequest', data: { message: 'Expected a semantic version', kind: 'Missing' } },
-        400,
-        'Bad Request',
-      ),
-    );
-    globalThis.fetch = fetchMock;
-    const { app } = createUpgradeApp();
+  it('returns 409 for external OpenCode and does not refresh', async () => {
+    const refreshOpenCodeAfterConfigChange = vi.fn(async () => undefined);
+    const { app, deps } = createUpgradeApp({
+      getIsExternalOpenCode: () => true,
+      refreshOpenCodeAfterConfigChange,
+    });
 
     const response = await request(app)
       .post('/api/opencode/upgrade')
-      .send({ target: 'latest' })
-      .expect(400);
+      .send({})
+      .expect(409);
 
-    expect(response.body).toEqual({ success: false, error: 'Expected a semantic version' });
+    expect(response.body.success).toBe(false);
+    expect(response.body.error).toMatch(/your own OpenCode serve/i);
+    expect(deps.refreshOpenCodeAfterConfigChange).not.toHaveBeenCalled();
   });
 });