@openchambery/web 2.0.0-beta.4 → 2.0.0-beta.5

package/server/lib/notifications/template-runtime.test.js

@@ -82,3 +82,99 @@ describe('notification template message extraction', () => {
     await expect(runtime.fetchLastAssistantMessageText('session-1', 'msg-1')).resolves.toBe('final answer');
   });
 });
+
+describe('notification session titles', () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('reads the OpenCode 2 session title from the data envelope', async () => {
+    const runtime = createNotificationTemplateRuntime({
+      readSettingsFromDisk: async () => ({}),
+      buildOpenCodeUrl: (path) => `http://opencode.test${path}`,
+      getOpenCodeAuthHeaders: () => ({ authorization: 'Basic test' }),
+      resolveGitBinaryForSpawn: () => 'git',
+    });
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      data: { id: 'ses_1', title: '发布说明' },
+    })));
+
+    const variables = await runtime.buildTemplateVariables({
+      type: 'message.updated',
+      location: { directory: '/repo' },
+      properties: { info: { sessionID: 'ses_1', role: 'assistant', finish: 'stop' } },
+    }, 'ses_1');
+
+    expect(variables.session_name).toBe('发布说明');
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      'http://opencode.test/session/ses_1?directory=%2Frepo',
+      expect.objectContaining({
+        headers: expect.objectContaining({ authorization: 'Basic test' }),
+      }),
+    );
+  });
+
+  it('keeps a title learned from session.renamed when the session fetch fails', async () => {
+    const runtime = createRuntime();
+    globalThis.fetch = vi.fn(async () => new Response(null, { status: 401 }));
+    runtime.maybeCacheSessionInfoFromEvent({
+      type: 'session.renamed',
+      data: { sessionID: 'ses_1', title: '修通知标题' },
+    });
+
+    const variables = await runtime.buildTemplateVariables({
+      type: 'session.execution.succeeded',
+      data: { sessionID: 'ses_1' },
+    }, 'ses_1');
+
+    expect(variables.session_name).toBe('修通知标题');
+  });
+
+  it('reads the latest assistant text from an OpenCode 2 message page', async () => {
+    const runtime = createRuntime();
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      data: [
+        {
+          id: 'msg_new',
+          sessionID: 'ses_1',
+          type: 'assistant',
+          agent: 'build',
+          model: { id: 'gpt-5', providerID: 'openai' },
+          content: [
+            { type: 'reasoning', text: 'private' },
+            { type: 'text', text: '发布说明已写好' },
+          ],
+          time: { created: 2 },
+        },
+        {
+          id: 'msg_old',
+          sessionID: 'ses_1',
+          type: 'assistant',
+          content: [{ type: 'text', text: 'older' }],
+          finish: 'stop',
+          time: { created: 1 },
+        },
+      ],
+    })));
+
+    await expect(runtime.fetchLastAssistantMessageText('ses_1')).resolves.toBe('发布说明已写好');
+  });
+
+  it('fills agent and model names from the OpenCode 2 session record', async () => {
+    const runtime = createRuntime();
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      data: { id: 'ses_1', title: '发布说明', agent: 'build', model: { id: 'gpt-5', providerID: 'openai' } },
+    })));
+
+    const variables = await runtime.buildTemplateVariables({
+      type: 'session.execution.succeeded',
+      data: { sessionID: 'ses_1' },
+    }, 'ses_1');
+
+    expect(variables).toMatchObject({
+      session_name: '发布说明',
+      agent_name: 'Build',
+      model_name: 'Gpt 5',
+    });
+  });
+});

package/server/lib/opencode/DOCUMENTATION.md

@@ -15,6 +15,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
 - `packages/web/server/lib/opencode/ensure-cli.js`: detect local `opencode` version and install the pinned official V2 into the OpenChamber data dir when missing or too old. Never uses a packaged/bundled binary.
+- `packages/web/server/lib/opencode/upgrade-screen.js`: startup gate for a detected OpenCode below `2.0.15`. It does not own process lifecycle. `GET /api/opencode/compatibility` classifies the version already detected by startup. `POST /api/opencode/install-required` installs `max(pin, 2.0.15)` through `installPinnedOpenCode2Cli`, points the managed binary at that cache, and restarts through the existing lifecycle hooks. Success requires the running serve to report `2.0.15` or newer. External serves are not replaced. Failure returns `upgraded: false` and the error; it does not claim the previous process was restored.
 - `packages/web/server/lib/opencode/env-config.js`: OpenCode-related environment variable parsing and validation (host/port/hostname).
 - `packages/web/server/lib/opencode/hmr-state-runtime.js`: HMR-persistent runtime state initialization, auth-state bootstrap, and HMR sync helpers.
 - `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
@@ -30,6 +31,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring. The SPA fallback sends `index.html` relative to `root`, so deep links keep working when the install lives under a dot directory.
 - `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
 - `packages/web/server/lib/conversations/`: combined create-session-and-prompt orchestration (OpenChamber-owned, registered before generic proxy).
+- `packages/web/server/lib/browser-provider/`: host for an installed extension that declares `browser`. Lists reachable providers, sends one agent browser action to the selected provider, and refuses when none is selected. Does not drive the in-app browser pane. See `browser-provider/DOCUMENTATION.md`.
 - `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`), anchor reconcile (`GET .../messages/reconcile`), Changes L2/L3 (`GET .../changes`), and exact message L1 projection (`GET /api/session/:sessionID/message/:messageID`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; all registered before generic proxy. L1 first-packet / SSE / exact-message paths keep `summary.diffs` as a slim `{ file, status?, additions, deletions }` list plus additive `diffCount`/`hasDiffs` (patch bodies stay on L3). See `session-turn-pages/DOCUMENTATION.md`.
 - `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot runtime for settings routes and diagnostics.
 - `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: active loopback-port wiring shared by pairing/LAN URLs and the private relay host.
@@ -87,6 +89,8 @@ This module provides OpenCode server integration utilities for the web server ru
   - `PUT /api/behavior/agents-md`
   - `POST /api/opencode/upgrade` (ticket 12): installs the pinned/target `@opencode/cli` into the **owned cache** at `~/.config/openchamber/opencode-cli/<version>/`. Managed owned-cache processes restart on that binary; official shared services use that exact binary's `service restart`, then adopt its registration again. Success requires a fresh running-serve version probe and runtime contract verification. Arbitrary external servers, private processes using global CLI, and private bundled binaries return HTTP 409; user installs are never overwritten. Concurrent upgrades are single-flight (`operation` state). Active sessions require `confirmActiveTasks`/`force`. Failure preserves cached binaries, restores the previous binary selection, and reports the failed phase; it does not claim the old process was restored. Shared-service recovery can subsequently re-ensure the registered service.
   - `GET /api/opencode/upgrade-status`: returns `currentVersion`/`serveVersion`/`cliVersion`, `targetVersion`/`latestVersion` (pin), `supplySource`, `ownership`, `canManage`, `management`, `guidance`, `contract`, and `operation`. Official shared services report `ownership: 'shared-service'`, `processOwnership: 'shared'`, and `canManage: true`. `available` is true only when `canManage` and target > current; unmanaged global/external runtimes report `available: null` plus manual guidance.
+  - `GET /api/opencode/compatibility`: startup upgrade-screen status. `state` is `compatible` at OpenCode `2.0.15` or newer, `incompatible` when a detected version is older or not 2.x, and `unavailable` when no version could be read. `canInstall` is true only for a local (managed or bundled) runtime this platform can install into the owned cache. External serves are reported and not replaced.
+  - `POST /api/opencode/install-required`: installs the upgrade-screen target (`2.0.15`, or the pin when the pin is newer) into the owned cache and restarts through the existing lifecycle. `upgraded: true` only after the running serve verifies at or above that target. Failure is `upgraded: false` plus `error`. Concurrent installs are single-flight.
   - `GET /api/opencode/contract` (ticket 11): runtime contract admission for the **running serve** (not health alone). Dimensions: reachable / authenticated / protocolCompatible / executionAllowed / capabilities / migration / CLI↔serve mismatch. Floor `2.0.12` (acceptable OpenCode 2.x at or above); below-min 2.x and 1.x block execution with upgrade guidance; no upper version cap.
   - `GET /api/opencode/health`: probes managed OpenCode `GET /api/info` (Basic auth, 4s timeout). `healthy` is reachability/version shape via `evaluateOpenCodeHealthBody` (admits official 2.x `ServerInfo` and classic `{ healthy: true, version }`; rejects 1.x / missing / `healthy: false`). Response also includes `executionAllowed`, `protocolCompatible`, and `contract` so clients do not treat health success as full execution semantics. Upstream non-OK responses pass through status with `{ healthy: false, error, contract }`; transport failures return HTTP 503.
   - `GET /api/opencode/version`: serve + CLI versions, mismatch flag, and contract snapshot

package/server/lib/opencode/ensure-cli.d.ts

@@ -0,0 +1,8 @@
+export function readOpenCode2BinaryVersion(binaryPath: string): string;
+
+export function installPinnedOpenCode2Cli(options?: {
+  version?: string;
+  platform?: string;
+  arch?: string;
+  dataDir?: string;
+}): Promise<string>;

package/server/lib/opencode/feature-routes-runtime.js

@@ -19,6 +19,9 @@ import { registerSessionTurnPageRoutes } from '../session-turn-pages/routes.js';
 import { registerAssistantRoutes } from '../assistants/routes.js';
 import { registerLlmRoutes } from '../llm/routes.js';
 import { registerMessageQueueRoutes } from '../message-queue/routes.js';
+import { getBrowserProviderHost } from '../browser-provider/host.js';
+import { registerBrowserProviderRoutes } from '../browser-provider/routes.js';
+import { createBrowserProviderSelectionStore } from '../browser-provider/selection-store.js';
 import { registerSkillRoutes } from './skill-routes.js';
 import { registerPluginRoutes } from './plugin-routes.js';
 import { getNpmInfo, clearCache as clearNpmCache } from './npm-registry.js';
@@ -513,6 +516,13 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       openchamberUserConfigRoot,
       openchamberDataDir,
     });
+    const browserProviderHost = getBrowserProviderHost();
+    if (typeof openchamberDataDir === 'string' && openchamberDataDir) {
+      browserProviderHost.attachSelectionStore(createBrowserProviderSelectionStore(
+        path.join(openchamberDataDir, 'browser-provider-selection.json'),
+      ));
+    }
+    registerBrowserProviderRoutes(app, { host: browserProviderHost });
   };
 
   return {

package/server/lib/opencode/feature-routes-runtime.test.js

@@ -54,6 +54,13 @@ describe('feature routes runtime composition', () => {
     expect(source).toMatch(/registerScheduledTaskRoutes\(app, \{[\s\S]*runHistoryStore,/);
   });
 
+  it('registers browser provider routes on the shared host before proxy composition', async () => {
+    const source = await fs.readFile(new URL('./feature-routes-runtime.js', import.meta.url), 'utf8');
+    expect(source).toContain("import { registerBrowserProviderRoutes } from '../browser-provider/routes.js';");
+    expect(source).toContain('registerBrowserProviderRoutes(app, { host: browserProviderHost });');
+    expect(source).toContain('createBrowserProviderSelectionStore(');
+  });
+
   it('registers message queue routes with the injected service before proxy composition', async () => {
     const source = await fs.readFile(new URL('./feature-routes-runtime.js', import.meta.url), 'utf8');
     expect(source).toContain("import { registerMessageQueueRoutes } from '../message-queue/routes.js';");

package/server/lib/opencode/proxy.js

@@ -957,7 +957,9 @@ export const registerOpenCodeProxy = (app, deps) => {
       req.path === '/opencode/version' ||
       req.path === '/opencode/contract' ||
       req.path === '/opencode/upgrade-status' ||
-      req.path === '/opencode/upgrade'
+      req.path === '/opencode/upgrade' ||
+      req.path === '/opencode/compatibility' ||
+      req.path === '/opencode/install-required'
     ) {
       return next();
     }

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

@@ -518,7 +518,7 @@ describe('registerOpenCodeProxy session metadata overlay', () => {
     return app;
   };
 
-  it('merges Host store metadata onto session list and detail (store keys win)', async () => {
+  it('merges side-store gaps onto the OpenCode record without letting the side row win conflicts', async () => {
     globalThis.fetch = vi.fn(async (url) => {
       const path = String(url).split('?')[0];
       if (path.endsWith('/api/session') || path.endsWith('/session')) {
@@ -566,7 +566,7 @@ describe('registerOpenCodeProxy session metadata overlay', () => {
       id: 'ses_1',
       metadata: {
         fromOpenCode: true,
-        shared: 'ours',
+        shared: 'theirs',
         openchamber: { goal: { status: 'active' } },
       },
     });
@@ -578,7 +578,7 @@ describe('registerOpenCodeProxy session metadata overlay', () => {
       id: 'ses_1',
       metadata: {
         fromOpenCode: true,
-        shared: 'ours',
+        shared: 'theirs',
         openchamber: { goal: { status: 'active' } },
       },
     });

package/server/lib/opencode/routes.js

@@ -11,6 +11,7 @@ import {
   readOpenCode2BinaryVersion,
   resolveOpenChamberDataDir,
 } from './ensure-cli.js';
+import { registerUpgradeScreenRoutes } from './upgrade-screen.js';
 import { evaluateRuntimeContract } from './runtime-contract.js';
 import {
   buildUpgradeStatusSnapshot,
@@ -253,6 +254,35 @@ export const registerOpenCodeRoutes = (app, dependencies) => {
     return fallback;
   };
 
+  registerUpgradeScreenRoutes(app, {
+    resolveOwnership: resolveOwnershipContext,
+    readServeVersion: async () => {
+      const probe = await readOpenCodeCurrentVersion().catch(() => ({ currentVersion: null }));
+      return probe.currentVersion || null;
+    },
+    readCliVersion: () => {
+      const fromRuntime = typeof getOpenCodeCliVersion === 'function' ? getOpenCodeCliVersion() : null;
+      if (fromRuntime) return fromRuntime;
+      const binaryPath = typeof getResolvedOpenCodeBinary === 'function' ? getResolvedOpenCodeBinary() : null;
+      return binaryPath ? readOpenCode2BinaryVersion(binaryPath) : null;
+    },
+    readConfiguredBinary: async () => {
+      const settings = await readSettingsFromDiskMigrated();
+      return typeof settings?.opencodeBinary === 'string' ? settings.opencodeBinary : null;
+    },
+    persistBinary: async (binaryPath) => {
+      await persistSettings({ opencodeBinary: binaryPath });
+    },
+    getResolvedBinary: getResolvedOpenCodeBinary,
+    getResolvedBinarySource: getResolvedOpenCodeBinarySource,
+    forceBinary: typeof forceResolvedOpenCodeBinary === 'function' ? forceResolvedOpenCodeBinary : null,
+    restart: typeof restartOpenCode === 'function' ? restartOpenCode : null,
+    waitReady: typeof waitForOpenCodeReady === 'function' ? waitForOpenCodeReady : null,
+    isSharedService: () => getIsSharedOpenCodeService() === true,
+    install: (options) => installPinnedOpenCode2Cli({ ...options, dataDir: resolveDataDir() }),
+    readBinaryVersion: readOpenCode2BinaryVersion,
+  });
+
   app.get('/api/config/settings', async (req, res) => {
     try {
       const settings = await readSettingsFromDiskMigrated();

package/server/lib/opencode/upgrade-screen.d.ts

@@ -0,0 +1,30 @@
+export const REQUIRED_OPENCODE_VERSION: string;
+
+export type UpgradeScreen = {
+  state: 'unavailable' | 'compatible' | 'incompatible';
+  version: string | null;
+  installation: 'managed' | 'external' | 'bundled';
+  minimumVersion: string;
+  targetVersion: string;
+  canInstall: boolean;
+  guidance: string | null;
+};
+
+export function describeUpgradeScreen(input?: {
+  version?: string | null;
+  installation?: 'managed' | 'external' | 'bundled';
+  platformCanInstall?: boolean;
+  guidance?: string | null;
+  pin?: string;
+}): UpgradeScreen;
+
+export function platformSupportsUpgradeScreenInstall(platform?: string, arch?: string): boolean;
+
+export function installRequiredOpenCode(deps: object): Promise<{
+  ok: true;
+  upgraded: true;
+  version: string;
+  targetVersion: string;
+  error: null;
+  errorCode: null;
+}>;

package/server/lib/opencode/upgrade-screen.js

@@ -0,0 +1,299 @@
+/**
+ * Startup upgrade screen for OpenCode below 2.0.15.
+ *
+ * This module does not own process lifecycle. It classifies the version the
+ * existing startup path already detected, and installs through the owned-cache
+ * installer (`installPinnedOpenCode2Cli`) plus the caller's restart hook.
+ * Success is a verified running version, never a download that has not started.
+ */
+
+import {
+  PINNED_OPENCODE2_VERSION,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode1xVersion,
+  isOpenCode2VersionAtLeast,
+  npmPackageForOpenCode2,
+} from './opencode2-pin.js';
+
+/** Oldest OpenCode this OpenChamber build will enter a session against. */
+export const REQUIRED_OPENCODE_VERSION = '2.0.15';
+
+const normalizeVersion = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/^v/i, '');
+  return trimmed || null;
+};
+
+/**
+ * Install target is the pin when the pin already satisfies the screen, otherwise
+ * the screen minimum. A pin still at 2.0.12 must not be what this screen installs.
+ * @param {string} [pin]
+ */
+export function resolveUpgradeScreenTarget(pin = PINNED_OPENCODE2_VERSION) {
+  if (isOpenCode2VersionAtLeast(pin, REQUIRED_OPENCODE_VERSION)) return pin;
+  return REQUIRED_OPENCODE_VERSION;
+}
+
+/** 2.x at or above the screen minimum. A future major is not this contract. */
+function isUpgradeScreenSatisfied(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized || !isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+function isOlderThanUpgradeScreenMinimum(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized) return false;
+  if (isOpenCode1xVersion(normalized)) return true;
+  if (!isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return !isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+/**
+ * @param {string | null | undefined} ownership
+ * @returns {'managed' | 'external' | 'bundled'}
+ */
+function classifyUpgradeScreenInstallation(ownership) {
+  if (ownership === 'external-serve') return 'external';
+  if (ownership === 'bundled') return 'bundled';
+  return 'managed';
+}
+
+export function platformSupportsUpgradeScreenInstall(platform = process.platform, arch = process.arch) {
+  try {
+    npmPackageForOpenCode2(platform, arch);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const pickDetectedVersion = (serveVersion, cliVersion) => {
+  const serve = normalizeVersion(serveVersion);
+  const cli = normalizeVersion(cliVersion);
+  if (serve && !isUpgradeScreenSatisfied(serve)) return serve;
+  if (serve) return serve;
+  return cli;
+};
+
+/**
+ * @param {{
+ *   version?: string | null,
+ *   installation?: 'managed' | 'external' | 'bundled',
+ *   platformCanInstall?: boolean,
+ *   guidance?: string | null,
+ *   pin?: string,
+ * }} input
+ */
+export function describeUpgradeScreen(input = {}) {
+  const version = normalizeVersion(input.version);
+  const installation = input.installation === 'external' || input.installation === 'bundled'
+    ? input.installation
+    : 'managed';
+  const state = version == null
+    ? 'unavailable'
+    : isUpgradeScreenSatisfied(version)
+      ? 'compatible'
+      : 'incompatible';
+  const older = version != null && isOlderThanUpgradeScreenMinimum(version);
+  // External processes are not replaced. Bundled and managed locals can receive
+  // an owned-cache install; that does not overwrite the user's other binaries.
+  const canInstall = state === 'incompatible'
+    && older
+    && installation !== 'external'
+    && input.platformCanInstall === true;
+  const guidance = canInstall
+    ? null
+    : (typeof input.guidance === 'string' && input.guidance.trim() ? input.guidance.trim() : null);
+  return {
+    state,
+    version,
+    installation,
+    minimumVersion: REQUIRED_OPENCODE_VERSION,
+    targetVersion: resolveUpgradeScreenTarget(input.pin),
+    canInstall,
+    guidance,
+  };
+}
+
+/**
+ * A running serve below the minimum, or a missing version, is not an upgrade.
+ * @param {{ targetVersion?: string | null, serveVersion?: string | null }} input
+ */
+export function evaluateUpgradeScreenInstallResult(input = {}) {
+  const targetVersion = resolveUpgradeScreenTarget(input.targetVersion || REQUIRED_OPENCODE_VERSION);
+  const version = normalizeVersion(input.serveVersion);
+  if (!version || !isUpgradeScreenSatisfied(version) || !isOpenCode2VersionAtLeast(version, targetVersion)) {
+    const found = version || 'unknown';
+    return {
+      ok: false,
+      upgraded: false,
+      version,
+      targetVersion,
+      errorCode: 'UPGRADE_SCREEN_NOT_VERIFIED',
+      error: `OpenCode is still ${found}. OpenChamber requires ${REQUIRED_OPENCODE_VERSION} or newer.`,
+    };
+  }
+  return {
+    ok: true,
+    upgraded: true,
+    version,
+    targetVersion,
+    error: null,
+    errorCode: null,
+  };
+}
+
+async function readUpgradeScreenStatus(deps) {
+  const ownership = typeof deps.resolveOwnership === 'function'
+    ? await deps.resolveOwnership()
+    : { ownership: 'unknown', guidance: null };
+  const installation = classifyUpgradeScreenInstallation(ownership?.ownership);
+  const serveVersion = typeof deps.readServeVersion === 'function'
+    ? await Promise.resolve(deps.readServeVersion()).catch(() => null)
+    : null;
+  const cliVersion = typeof deps.readCliVersion === 'function'
+    ? await Promise.resolve(deps.readCliVersion()).catch(() => null)
+    : null;
+  return describeUpgradeScreen({
+    version: pickDetectedVersion(serveVersion, cliVersion),
+    installation,
+    platformCanInstall: typeof deps.platformCanInstall === 'boolean'
+      ? deps.platformCanInstall
+      : platformSupportsUpgradeScreenInstall(deps.platform, deps.arch),
+    guidance: ownership?.guidance ?? null,
+    pin: deps.pin,
+  });
+}
+
+const failure = (message, code, status = 500) => {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  return error;
+};
+
+/**
+ * Install the screen target into the owned cache and restart through the
+ * caller's existing lifecycle hooks. Restores the previous binary selection
+ * when verification fails. Never returns upgraded:true for a failed install.
+ * @param {object} deps
+ */
+export async function installRequiredOpenCode(deps) {
+  const status = await readUpgradeScreenStatus(deps);
+  if (status.state !== 'incompatible' || status.canInstall !== true) {
+    throw failure(
+      status.guidance || 'Automatic OpenCode installation is unavailable for this runtime.',
+      'UPGRADE_SCREEN_UNAVAILABLE',
+      409,
+    );
+  }
+  const target = status.targetVersion;
+  const previousBinary = typeof deps.getResolvedBinary === 'function' ? deps.getResolvedBinary() : null;
+  const previousSource = typeof deps.getResolvedBinarySource === 'function' ? deps.getResolvedBinarySource() : null;
+  const previousSetting = typeof deps.readConfiguredBinary === 'function'
+    ? await deps.readConfiguredBinary()
+    : undefined;
+  let persisted = false;
+  try {
+    if (typeof deps.install !== 'function') {
+      throw failure('OpenCode install is not configured.', 'UPGRADE_SCREEN_INSTALL_UNAVAILABLE', 500);
+    }
+    const installedPath = await deps.install({ version: target });
+    const diskVersion = typeof deps.readBinaryVersion === 'function'
+      ? await Promise.resolve(deps.readBinaryVersion(installedPath))
+      : null;
+    if (diskVersion !== target) {
+      throw failure(
+        `Installed OpenCode version mismatch: expected ${target}, got ${diskVersion || 'unknown'}`,
+        'UPGRADE_SCREEN_BINARY_MISMATCH',
+        500,
+      );
+    }
+    if (typeof deps.persistBinary === 'function') {
+      await deps.persistBinary(installedPath);
+      persisted = true;
+    }
+    if (typeof deps.forceBinary === 'function') {
+      deps.forceBinary(installedPath, 'installed');
+    }
+    if (typeof deps.restart === 'function') {
+      const shared = typeof deps.isSharedService === 'function' && deps.isSharedService() === true;
+      await deps.restart(shared ? { binaryPath: installedPath } : undefined);
+    }
+    if (typeof deps.waitReady === 'function') {
+      await deps.waitReady();
+    }
+    const serveVersion = typeof deps.readServeVersion === 'function'
+      ? await deps.readServeVersion()
+      : null;
+    const verification = evaluateUpgradeScreenInstallResult({ targetVersion: target, serveVersion });
+    if (!verification.ok) {
+      throw failure(verification.error, verification.errorCode, 500);
+    }
+    return verification;
+  } catch (error) {
+    if (persisted && typeof deps.persistBinary === 'function') {
+      try {
+        await deps.persistBinary(typeof previousSetting === 'string' ? previousSetting : '');
+      } catch {
+        // Keep the install error. A failed restore must not become success.
+      }
+    }
+    if (previousBinary && typeof deps.forceBinary === 'function') {
+      try {
+        deps.forceBinary(previousBinary, previousSource || 'discovered');
+      } catch {
+        // Same: report the install failure, not a restored-success.
+      }
+    }
+    throw error;
+  }
+}
+
+export function registerUpgradeScreenRoutes(app, deps) {
+  app.get('/api/opencode/compatibility', async (_req, res) => {
+    try {
+      res.json(await readUpgradeScreenStatus(deps));
+    } catch (error) {
+      res.status(503).json({
+        error: error instanceof Error ? error.message : 'Could not check OpenCode compatibility',
+      });
+    }
+  });
+
+  let inFlight = null;
+  app.post('/api/opencode/install-required', async (_req, res) => {
+    try {
+      if (!inFlight) {
+        inFlight = installRequiredOpenCode(deps).finally(() => {
+          inFlight = null;
+        });
+      }
+      const result = await inFlight;
+      if (!result || result.ok !== true || result.upgraded !== true || !result.version) {
+        return res.status(500).json({
+          success: false,
+          upgraded: false,
+          error: result?.error || 'OpenCode installation did not verify a new version',
+          errorCode: result?.errorCode || 'UPGRADE_SCREEN_NOT_VERIFIED',
+          version: result?.version ?? null,
+        });
+      }
+      return res.json({
+        success: true,
+        upgraded: true,
+        version: result.version,
+        targetVersion: result.targetVersion,
+      });
+    } catch (error) {
+      const status = Number.isInteger(error?.status) ? error.status : 500;
+      return res.status(status).json({
+        success: false,
+        upgraded: false,
+        error: error instanceof Error ? error.message : 'OpenCode installation failed',
+        errorCode: error?.code || 'UPGRADE_SCREEN_FAILED',
+      });
+    }
+  });
+}