@vantran-se/openchamber-web 2.0.4 → 2.0.6

package/server/lib/openchamber-sessions/fork-inheritance.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import { applyForkInheritance, sourceOwnedLinksPatch } from './fork-inheritance.js';
+
+const goal = (objectiveFile) => ({ id: 'goal_1', objective: objectiveFile ? '' : 'Ship it', objectiveFile, status: 'paused' });
+
+const harness = (metadata, overrides = {}) => {
+  const deps = {
+    readObjective: vi.fn(async () => 'Objective from file'),
+    writeObjective: vi.fn(async () => undefined),
+    writeMetadata: vi.fn(async () => undefined),
+    ...overrides,
+  };
+  const run = () => applyForkInheritance({ sourceSessionID: 'ses_source', fork: { id: 'ses_fork', metadata }, ...deps });
+  return { deps, run };
+};
+
+describe('sourceOwnedLinksPatch', () => {
+  it('pauses an active goal so the fork does not pursue it in parallel', () => {
+    expect(sourceOwnedLinksPatch({ openchamber: { goal: { id: 'g', status: 'active' } } }))
+      .toEqual({ goal: { status: 'paused', statusReason: 'paused in fork' } });
+    expect(sourceOwnedLinksPatch({ openchamber: { goal: { id: 'g', status: 'complete' } } })).toBeNull();
+  });
+
+  it('removes the btw and review links but keeps the goal', () => {
+    expect(sourceOwnedLinksPatch({ openchamber: { goal: goal(false), btwSessionID: 'b', reviewSessionID: 'r' } }))
+      .toEqual({ btwSessionID: null, reviewSessionID: null });
+  });
+
+  it('removes the btw marker of a btw source, keeps a review marker', () => {
+    expect(sourceOwnedLinksPatch({ openchamber: { kind: 'btw', originalSessionID: 'p', btwBoundaryMessageID: 'm' } }))
+      .toEqual({ kind: null, originalSessionID: null, btwBoundaryMessageID: null });
+    expect(sourceOwnedLinksPatch({ openchamber: { kind: 'review', originalSessionID: 'p' } })).toBeNull();
+    expect(sourceOwnedLinksPatch(undefined)).toBeNull();
+  });
+});
+
+describe('applyForkInheritance', () => {
+  it('does nothing for an inline goal without source links', async () => {
+    const h = harness({ openchamber: { goal: goal(false) } });
+    await h.run();
+    expect(h.deps.readObjective).not.toHaveBeenCalled();
+    expect(h.deps.writeMetadata).not.toHaveBeenCalled();
+  });
+
+  it('copies a file-backed objective and strips source links', async () => {
+    const h = harness({ openchamber: { goal: goal(true), btwSessionID: 'b' } });
+    await h.run();
+    expect(h.deps.readObjective).toHaveBeenCalledWith('ses_source');
+    expect(h.deps.writeObjective).toHaveBeenCalledWith('ses_fork', 'Objective from file');
+    expect(h.deps.writeMetadata).toHaveBeenCalledWith('ses_fork', { openchamber: { btwSessionID: null } });
+  });
+
+  it('inlines the objective when the file copy fails', async () => {
+    const h = harness({ openchamber: { goal: goal(true) } }, {
+      writeObjective: vi.fn(async () => { throw new Error('disk full'); }),
+    });
+    await h.run();
+    expect(h.deps.writeMetadata).toHaveBeenCalledWith('ses_fork', {
+      openchamber: { goal: { objective: 'Objective from file', objectiveFile: false } },
+    });
+  });
+
+  it('swallows a metadata write failure', async () => {
+    const h = harness({ openchamber: { reviewSessionID: 'r' } }, {
+      writeMetadata: vi.fn(async () => { throw new Error('offline'); }),
+    });
+    await expect(h.run()).resolves.toBeUndefined();
+  });
+});

package/server/lib/openchamber-sessions/routes.js

@@ -9,7 +9,9 @@ import { AUTO_MODEL_REF, isAutoModel } from '../routing/defaults.js';
 import { parseScheduledCommandPrompt } from '../scheduled-tasks/runtime.js';
 import { buildGoalIntroText, createSessionGoal } from '../session-goal/create.js';
 import { OpenChamberControlError, asControlError } from '../openchamber-control/error.js';
+import { readObjective, writeObjective } from '../session-goal/objectives.js';
 import { createArchiveStore } from './archive-store.js';
+import { applyForkInheritance } from './fork-inheritance.js';
 import { createOpenCodeClient as defaultCreateOpenCodeClient } from './opencode-client.js';
 import { createSessionMetadataStore, createOpenCodeSessionMetadata } from './session-metadata-store.js';
 
@@ -889,6 +891,15 @@ export const createOpenChamberSessionService = (dependencies) => {
           messageID: asNonEmptyString(payload.messageId) || undefined,
         });
         targetSessionID = targetSession.id;
+        // Before the prompt goes out, so a goal armed by this dispatch writes
+        // over the copied objective rather than the other way round.
+        await applyForkInheritance({
+          sourceSessionID,
+          fork: targetSession,
+          readObjective,
+          writeObjective,
+          writeMetadata: (sessionID, patch) => writeMetadata(sessionID, patch, directory),
+        });
       }
 
       const baselineAssistantMessageId = await latestCompletedAssistantMessageID({

package/server/lib/openchamber-sessions/routes.test.js

@@ -920,6 +920,24 @@ describe('openchamber session routes', () => {
     }));
   });
 
+  it('strips source-owned links from a fork before dispatching', async () => {
+    sessionForkMock.mockImplementationOnce(async () => ({
+      id: 'ses_fork',
+      title: 'Forked session',
+      metadata: { openchamber: { btwSessionID: 'ses_btw', reviewSessionID: 'ses_review', assist: { recap: 'kept' } } },
+    }));
+    const { app, sessionMetadataStore } = createApp();
+    sessionMetadataStore.entries.set('ses_fork', {
+      openchamber: { btwSessionID: 'ses_btw', reviewSessionID: 'ses_review', assist: { recap: 'kept' } },
+    });
+    await request(app)
+      .post('/api/openchamber/sessions/ses_source/fork')
+      .send({ directory: '/repo/app', prompt: 'Carry on', model: 'openai/gpt-5.5', agent: 'build' })
+      .expect(200);
+
+    expect(sessionMetadataStore.entries.get('ses_fork')).toEqual({ openchamber: { assist: { recap: 'kept' } } });
+  });
+
   it('rejects send and fork requests without a prompt before calling OpenCode', async () => {
     const { app } = createApp();
     await request(app)

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

@@ -1,3 +1,5 @@
+import { registerNotificationEmitRoutes } from '../notifications/emit-route.js';
+
 export const createBootstrapRuntime = (dependencies) => {
   const {
     createUiAuth,
@@ -63,7 +65,9 @@ export const createBootstrapRuntime = (dependencies) => {
       getCachedZenModels,
       setAutoAcceptSession,
       agentToolRuntime,
+      pluginNotificationEmitter,
       desktopUpdater,
+      skipBodyParsing,
     } = options;
 
     const uiAuthController = createUiAuth({
@@ -90,10 +94,17 @@ export const createBootstrapRuntime = (dependencies) => {
       uiAuthController,
     });
 
-    registerCommonRequestMiddleware(app, { express, verboseRequestLogs });
+    registerCommonRequestMiddleware(app, { express, verboseRequestLogs, skipBodyParsing });
 
     registerAgentToolRoutes(app, { express, agentToolRuntime });
 
+    const notificationEmitRoutes = registerNotificationEmitRoutes(app, {
+      express,
+      isAgentToolRequestAuthorized: (req) => agentToolRuntime?.authorizeRequest?.(req) === true,
+      emitter: pluginNotificationEmitter,
+    });
+    notificationEmitRoutes.registerPluginRoute();
+
     registerAuthAndAccessRoutes(app, {
       express,
       tunnelAuthController,
@@ -110,6 +121,8 @@ export const createBootstrapRuntime = (dependencies) => {
       normalizeTunnelSessionTtlMs,
     });
 
+    notificationEmitRoutes.registerApiRoute();
+
     registerTtsRoutes(app, { sayTTSCapability });
 
     registerNotificationRoutes(app, {

package/server/lib/opencode/compatibility.js

@@ -63,13 +63,16 @@ export const requireOpenCodeV2 = async (launch, options) => {
 
 // External URLs have no local executable. A legacy probe identifies v1 only
 // from its JSON contract; neither HTML fallbacks nor auth failures imply v1.
+// v1 has no `/api/info`: its catch-all serves the web UI, and a v1 build
+// without the embedded UI proxies that path to app.opencode.ai, which can hang
+// or fail. A failed v2 probe therefore still falls through to the v1 probe.
 export const readExternalOpenCodeVersion = async (baseUrl, headers, fetchImpl = fetch) => {
   const request = (pathname) => fetchImpl(new URL(pathname, baseUrl), {
     headers: { ...headers, Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(5000),
   });
-  const response = await request('/api/info');
-  if (response.status === 401 || response.status === 403) return null;
-  const info = await readOpenCodeInfo(response);
+  const response = await request('/api/info').catch(() => null);
+  if (response && (response.status === 401 || response.status === 403)) return null;
+  const info = response ? await readOpenCodeInfo(response) : null;
   if (info) return info.version;
   const legacy = await request('/global/health');
   if (!legacy.ok) return null;

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

@@ -30,6 +30,14 @@ describe('OpenCode compatibility', () => {
     expect(requests).toEqual(['/api/info', '/global/health']);
   });
 
+  it('still identifies v1 when its /api/info fallback hangs or fails', async () => {
+    const fetchImpl = async (url) => {
+      if (url.pathname === '/api/info') throw new DOMException('The operation timed out.', 'TimeoutError');
+      return Response.json({ healthy: true, version: '1.18.32' });
+    };
+    expect(await readExternalOpenCodeVersion('http://localhost:4096', {}, fetchImpl)).toBe('1.18.32');
+  });
+
   it.each([401, 403])('does not call an auth failure v1 (%s)', async (status) => {
     let requests = 0;
     expect(await readExternalOpenCodeVersion('http://localhost:4096', {}, async () => {

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

@@ -261,6 +261,33 @@ describe('entity modules speak OpenCode 2 shapes', () => {
     }
   });
 
+  it('lists servers from a global opencode.jsonc next to opencode.json and edits them in place', () => {
+    const configDir = path.join(process.env.XDG_CONFIG_HOME, 'opencode');
+    const jsonPath = path.join(configDir, 'opencode.json');
+    const jsoncPath = path.join(configDir, 'opencode.jsonc');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(jsonPath, JSON.stringify({ autoupdate: true }, null, 2), 'utf8');
+    fs.writeFileSync(jsoncPath, [
+      '{',
+      '  // servers live only in the jsonc file',
+      '  "mcp": { "servers": { "docs": { "type": "remote", "url": "https://docs.example.com/mcp" } } }',
+      '}',
+    ].join('\n'), 'utf8');
+
+    try {
+      expect(listMcpConfigs(projectDir).map((entry) => entry.name)).toContain('docs');
+      expect(getMcpConfig('docs', projectDir)).toEqual(expect.objectContaining({ scope: 'user' }));
+
+      updateMcpConfig('docs', { disabled: true }, projectDir);
+
+      expect(getMcpConfig('docs', projectDir)).toEqual(expect.objectContaining({ disabled: true }));
+      expect(readJson(jsonPath)).toEqual({ autoupdate: true });
+    } finally {
+      fs.rmSync(jsonPath, { force: true });
+      fs.rmSync(jsoncPath, { force: true });
+    }
+  });
+
   it('reads a v1 mcp entry and rewrites it under mcp.servers in the same file', () => {
     const configPath = write('opencode.json', JSON.stringify({
       mcp: {

package/server/lib/opencode/config-paths.test.js

@@ -111,6 +111,18 @@ describe('OpenCode global config paths', () => {
     expect(response.json).toHaveBeenLastCalledWith({
       content: 'Global behavior', exists: true, path: path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'),
     });
+
+    // A write based on an outdated copy is refused and leaves the file alone.
+    await handlers.get('PUT /api/behavior/agents-md')({
+      body: { content: 'Stale draft', expectedContent: 'Older behavior' },
+    }, response);
+    expect(response.status).toHaveBeenLastCalledWith(409);
+    expect(fs.readFileSync(path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'), 'utf8')).toBe('Global behavior');
+
+    await handlers.get('PUT /api/behavior/agents-md')({
+      body: { content: 'Current draft', expectedContent: 'Global behavior' },
+    }, response);
+    expect(fs.readFileSync(path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'), 'utf8')).toBe('Current draft');
     fs.rmSync(root, { recursive: true, force: true });
   });
 });

package/server/lib/opencode/config-v2.d.ts

@@ -162,6 +162,7 @@ export function deleteMcpEntry(config: Record<string, unknown>, name: string): b
 export function toProviderPackage(value: unknown): string | undefined;
 export function toNpmPackage(value: unknown): string | undefined;
 export function toProviderEntity(raw: unknown): ProviderEntity;
+export function readStoredProviderEntry(configs: unknown[], providerId: string): ProviderEntity | null;
 
 export function toPluginEntity(raw: unknown): PluginEntity | null;
 export function fromPluginEntity(entity: unknown): string | PluginEntity | null;
@@ -171,6 +172,7 @@ export function readPluginList(config: unknown): Array<{ entry: PluginEntity; ke
 export type WebSearchSelection = false | string | null;
 export function parseWebSearchSelection(value: unknown): WebSearchSelection | undefined;
 export function writeWebSearchSelection(config: Record<string, unknown>, selection: WebSearchSelection): boolean;
+export function writeWarmingEnabled(config: Record<string, unknown>, enabled: boolean): boolean;
 export interface WebSearchConfigLayers {
   userConfig: object | null;
   projectConfig: object | null;

package/server/lib/opencode/config-v2.js

@@ -668,6 +668,28 @@ function toProviderEntity(raw) {
   ]);
 }
 
+/**
+ * The provider entry an editor should start from: the winning config layer's
+ * stored entry (layers passed highest precedence first) in v2 shape, without
+ * the literal `settings.apiKey` secret. Returns null when no layer defines it.
+ * Unlike the live provider OpenCode serves, this carries `env` and only the
+ * reasoning levels the user wrote.
+ */
+function readStoredProviderEntry(configs, providerId) {
+  for (const config of configs) {
+    const { value } = readSectionEntry(config, 'providers', providerId);
+    if (value === undefined) continue;
+    const entity = toProviderEntity(value);
+    if (entity.settings && 'apiKey' in entity.settings) {
+      const { apiKey: _secret, ...settings } = entity.settings;
+      if (Object.keys(settings).length) entity.settings = settings;
+      else delete entity.settings;
+    }
+    return entity;
+  }
+  return null;
+}
+
 // ============== PLUGINS ==============
 
 const PLUGIN_SECTION = { v2: 'plugins', v1: 'plugin' };
@@ -742,6 +764,24 @@ function writeWebSearchSelection(config, selection) {
   return JSON.stringify(config.websearch) !== before;
 }
 
+// ============== SESSION WARMING ==============
+
+/**
+ * The `warming` key: `true` keeps idle sessions' prompt cache warm with
+ * OpenCode's defaults, an object tunes prompt/interval/duration. Turning it on
+ * keeps a hand-tuned object as is; turning it off removes the key (OpenCode's
+ * default is off). Returns whether the config changed.
+ */
+function writeWarmingEnabled(config, enabled) {
+  const before = JSON.stringify(config.warming);
+  if (!enabled) {
+    delete config.warming;
+  } else if (typeof config.warming !== 'object' || config.warming === null) {
+    config.warming = true;
+  }
+  return JSON.stringify(config.warming) !== before;
+}
+
 const hasWebSearchKey = (config) => config != null && Object.hasOwn(config, 'websearch');
 
 /**
@@ -792,10 +832,12 @@ export {
   toProviderPackage,
   toNpmPackage,
   toProviderEntity,
+  readStoredProviderEntry,
   toPluginEntity,
   fromPluginEntity,
   readPluginList,
   parseWebSearchSelection,
   writeWebSearchSelection,
   findWebSearchProjectOverride,
+  writeWarmingEnabled,
 };

package/server/lib/opencode/config-v2.test.js

@@ -9,6 +9,7 @@ import {
   parseModelSelection,
   formatModelSelection,
   toAgentEntity,
+  writeWarmingEnabled,
   fromAgentEntity,
   isLegacyAgentFrontmatter,
   toCommandEntity,
@@ -464,3 +465,19 @@ describe('findWebSearchProjectOverride', () => {
     expect(findWebSearchProjectOverride(layers(), [{ path: userPath, config: { websearch: false } }])).toBeNull();
   });
 });
+
+describe('session warming', () => {
+  it('turns warming on and off, keeping a hand-tuned object', () => {
+    const config = { model: 'openai/gpt-5' };
+    expect(writeWarmingEnabled(config, true)).toBe(true);
+    expect(config.warming).toBe(true);
+    expect(writeWarmingEnabled(config, true)).toBe(false);
+    expect(writeWarmingEnabled(config, false)).toBe(true);
+    expect(config).toEqual({ model: 'openai/gpt-5' });
+    expect(writeWarmingEnabled(config, false)).toBe(false);
+
+    const tuned = { warming: { interval: '3 minutes' } };
+    expect(writeWarmingEnabled(tuned, true)).toBe(false);
+    expect(tuned.warming).toEqual({ interval: '3 minutes' });
+  });
+});

package/server/lib/opencode/core-routes.js

@@ -94,6 +94,7 @@ export const registerServerStatusRoutes = (app, dependencies) => {
       'api.health.v1',
       'api.runtime-url.v1',
       'api.raw-file.v1',
+      'api.notifications.emit.v1',
       'realtime.sse.v1',
       'realtime.websocket.global-events.v1',
       'terminal.websocket.v1',
@@ -1074,10 +1075,15 @@ export const registerSettingsUtilityRoutes = (app, dependencies) => {
 };
 
 export const registerCommonRequestMiddleware = (app, dependencies) => {
-  const { express, verboseRequestLogs = false } = dependencies;
+  // `skipBodyParsing(req)` names a request whose body must reach its route untouched: a
+  // request the isolated-spaces dispatcher streams into a space, where a parsed body would
+  // otherwise be consumed here and lost.
+  const { express, verboseRequestLogs = false, skipBodyParsing = () => false } = dependencies;
 
   app.use((req, res, next) => {
-    if (req.path === '/api/config/themes' || req.path.startsWith('/api/config/themes/')) {
+    if (skipBodyParsing(req)) {
+      next();
+    } else if (req.path === '/api/config/themes' || req.path.startsWith('/api/config/themes/')) {
       express.json({ limit: '1mb' })(req, res, next);
     } else if (req.path.startsWith('/api/behavior')) {
       const contentLength = parseInt(req.headers['content-length'] || '0', 10);
@@ -1093,6 +1099,8 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
       req.path.startsWith('/api/config/settings') ||
       req.path.startsWith('/api/config/skills') ||
       req.path.startsWith('/api/config/plugins') ||
+      req.path.startsWith('/api/config/websearch') ||
+      req.path.startsWith('/api/config/warming') ||
       req.path.startsWith('/api/projects') ||
       req.path.startsWith('/api/fs') ||
       req.path.startsWith('/api/git') ||
@@ -1112,7 +1120,8 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
       req.path.startsWith('/api/text') ||
       req.path.startsWith('/api/voice') ||
       req.path.startsWith('/api/tts') ||
-      req.path.startsWith('/api/openchamber/tunnel')
+      req.path.startsWith('/api/openchamber/tunnel') ||
+      req.path.startsWith('/api/openchamber/spaces')
     ) {
       express.json({ limit: '50mb' })(req, res, next);
     } else if (req.path.startsWith('/api')) {
@@ -1122,7 +1131,14 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
     }
   });
 
-  app.use(express.urlencoded({ extended: true, limit: '50mb' }));
+  const urlencoded = express.urlencoded({ extended: true, limit: '50mb' });
+  app.use((req, res, next) => {
+    if (skipBodyParsing(req)) {
+      next();
+      return;
+    }
+    urlencoded(req, res, next);
+  });
 
   app.use((req, _res, next) => {
     if (verboseRequestLogs) {

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

@@ -127,6 +127,47 @@ describe('core-routes', () => {
     expect(response.body).toEqual({ body: { content: 'Snippet body' } });
   });
 
+  it('leaves the body of a request alone when told to, for both parsers', async () => {
+    const app = express();
+    registerCommonRequestMiddleware(app, { express, skipBodyParsing: (req) => req.path.startsWith('/api/spaces/') });
+    const raw = (req, res) => {
+      // A body a parser read is complete already, and its stream ends no second time.
+      if (req.complete) {
+        res.json({ body: req.body ?? null, raw: '' });
+        return;
+      }
+      const chunks = [];
+      req.on('data', (chunk) => chunks.push(chunk));
+      req.on('end', () => res.json({ body: req.body ?? null, raw: Buffer.concat(chunks).toString('utf8') }));
+    };
+    app.post('/api/spaces/abc/form', raw);
+    app.post('/api/spaces/abc/config/snippets/x', raw);
+    app.post('/api/other/form', raw);
+
+    const kept = await request(app).post('/api/spaces/abc/form').type('form').send('a=1&b=2').expect(200);
+    expect(kept.body).toEqual({ body: null, raw: 'a=1&b=2' });
+    const keptJson = await request(app).post('/api/spaces/abc/config/snippets/x').send({ content: 'x' }).expect(200);
+    expect(keptJson.body).toEqual({ body: null, raw: '{"content":"x"}' });
+    // Elsewhere the parsers still run, and a parsed body leaves nothing to read.
+    const parsed = await request(app).post('/api/other/form').type('form').send('a=1&b=2').expect(200);
+    expect(parsed.body).toEqual({ body: { a: '1', b: '2' }, raw: '' });
+  });
+
+  it('should parse JSON bodies for the web search config route', async () => {
+    const app = express();
+    registerCommonRequestMiddleware(app, { express });
+    app.put('/api/config/websearch', (req, res) => {
+      res.json({ body: req.body });
+    });
+
+    const response = await request(app)
+      .put('/api/config/websearch')
+      .send({ selection: 'random' })
+      .expect(200);
+
+    expect(response.body).toEqual({ body: { selection: 'random' } });
+  });
+
   it('should parse JSON bodies for custom provider upsert routes', async () => {
     const app = express();
     registerCommonRequestMiddleware(app, { express });

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

@@ -698,15 +698,8 @@ export const createOpenCodeEnvRuntime = (deps) => {
   ];
 
   const getWindowsNativeOpencodePackageNames = () => {
-    // TEMPORARY WORKAROUND — Windows ARM64: native opencode.exe fails with a Bun
-    // FFI/TinyCC dlopen error (https://github.com/anomalyco/opencode/issues/19130).
-    // prepare-opencode-cli.mjs bundles x64-baseline instead; match that here so
-    // the runtime resolver looks for the same x64-baseline package. Restore the
-    // arm64 branch below when the upstream issue is resolved.
     if (process.arch === 'arm64') {
-      // --- ORIGINAL (restore when ARM64 is fixed) ---
-      // return ['@opencode/cli-windows-arm64', 'opencode-windows-arm64'];
-      return WINDOWS_X64_NATIVE_PACKAGES;
+      return [path.join('@opencode', 'cli-windows-arm64'), 'opencode-windows-arm64'];
     }
     if (process.arch === 'x64') {
       // Prefer the baseline build when bypassing package-manager wrappers so the

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

@@ -103,6 +103,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       createFsSearchRuntime,
       openchamberDataDir,
       onGuestDeactivated,
+      surfaceViewerHeaders,
       openchamberUserConfigRoot,
       managedChatsRoot,
       normalizeDirectoryPath,
@@ -331,7 +332,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     registerGitHubRoutes(app);
     registerLinearRoutes(app);
     await registerBuiltInGuests({ persistPath: extensionsPersistPath(openchamberDataDir), root: routeDependencies.builtInExtensionsDir });
-    registerGuestRoutes(app, { openchamberDataDir, openchamberVersion, resolveGitBinaryForSpawn, resolveOptionalProjectDirectory, getSmallModelService, onGuestDeactivated });
+    registerGuestRoutes(app, { openchamberDataDir, openchamberVersion, resolveGitBinaryForSpawn, resolveOptionalProjectDirectory, getSmallModelService, onGuestDeactivated, surfaceViewerHeaders });
     registerGitRoutes(app, {
       emitWorktreeChanged: ({ directories, at }) => {
         const clients = getOpenChamberEventClients();

package/server/lib/opencode/lifecycle.js

@@ -1,4 +1,4 @@
-import { readOpenCodeInfo, isSupportedOpenCodeVersion, requireOpenCodeV2, UnsupportedOpenCodeVersionError } from './compatibility.js';
+import { readOpenCodeInfo, readExternalOpenCodeVersion, isSupportedOpenCodeVersion, requireOpenCodeV2, UnsupportedOpenCodeVersionError } from './compatibility.js';
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
 import { stripAppImageArgv0Leak } from '../inherited-env.js';
@@ -803,6 +803,16 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     }
   };
 
+  // The version of an explicitly configured server that answered but is not a
+  // supported OpenCode (v1, or 2.x below the minimum); null for anything else,
+  // including a server that is down.
+  const readUnsupportedExternalOpenCodeVersion = async (port, origin) => {
+    if (!port || port <= 0) return null;
+    const version = await readExternalOpenCodeVersion(origin ?? `http://127.0.0.1:${port}`, getOpenCodeAuthHeaders())
+      .catch(() => null);
+    return version && !isSupportedOpenCodeVersion(version) ? version : null;
+  };
+
   const waitForOpenCodePort = async (timeoutMs = 15000) => {
     if (state.openCodePort !== null) {
       return state.openCodePort;
@@ -1117,7 +1127,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         }
 
         const info = await readOpenCodeInfo(response);
-        if (!info) throw new Error('OpenCode did not return valid version information.');
+        if (!info) throw new Error('The server did not identify itself as OpenCode 2.x. OpenChamber requires OpenCode 2.x; if the server runs an older OpenCode, upgrade it.');
         if (!isSupportedOpenCodeVersion(info.version)) throw new UnsupportedOpenCodeVersionError(info.version);
         state.isOpenCodeReady = true;
         state.lastOpenCodeError = null;
@@ -1216,6 +1226,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
   const bootstrapOpenCodeAtStartup = async () => {
     const bootstrapStartedAt = performance.now();
     let bootstrapError = null;
+    let unsupportedExternalVersion = null;
     recordStartupPerformance('opencode.bootstrap.start');
     try {
       // Before doing anything, reap any OpenCode process WE spawned in a prior
@@ -1256,6 +1267,20 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         state.lastOpenCodeError = null;
         state.openCodeNotReadySince = 0;
         syncToHmrState();
+      } else if (env.ENV_EFFECTIVE_PORT && (unsupportedExternalVersion = await readUnsupportedExternalOpenCodeVersion(
+        env.ENV_EFFECTIVE_PORT,
+        env.ENV_CONFIGURED_OPENCODE_HOST?.origin,
+      ))) {
+        // The configured server is an OpenCode this OpenChamber cannot use.
+        // Attach to it anyway, not ready, so the compatibility check reports
+        // its version instead of a managed instance silently replacing it.
+        const label = env.ENV_CONFIGURED_OPENCODE_HOST ? env.ENV_CONFIGURED_OPENCODE_HOST.origin : `http://localhost:${env.ENV_EFFECTIVE_PORT}`;
+        console.warn(`OpenCode ${unsupportedExternalVersion} at ${label} is not supported by this OpenChamber`);
+        state.openCodeBaseUrl = env.ENV_CONFIGURED_OPENCODE_HOST?.origin ?? null;
+        setOpenCodePort(env.ENV_EFFECTIVE_PORT);
+        state.isExternalOpenCode = true;
+        syncToHmrState();
+        throw new UnsupportedOpenCodeVersionError(unsupportedExternalVersion);
       } else {
         // We never auto-attach to an arbitrary pre-existing OpenCode instance.
         // Attaching to an external server requires explicit opt-in via env
@@ -1282,6 +1307,9 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         await waitForOpenCodeReady();
       } catch (error) {
         bootstrapError = error;
+        // Skip-start mode assumed readiness up front; a server that never
+        // proved itself must not keep reporting ready to startup diagnostics.
+        state.isOpenCodeReady = false;
         console.error(`OpenCode readiness check failed: ${error.message}`);
       }
     } catch (error) {

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

@@ -467,6 +467,33 @@ describe('OpenCode lifecycle', () => {
     expect(runtime.testState.openCodeBaseUrl).toBe('http://seamus:4095');
   });
 
+  it('attaches to an OPENCODE_HOST running OpenCode v1 instead of starting a managed server', async () => {
+    const requested = [];
+    globalThis.fetch = vi.fn(async (url) => {
+      const href = String(url);
+      requested.push(href);
+      if (href.endsWith('/global/health')) return Response.json({ healthy: true, version: '1.18.32' });
+      return new Response('<html>OpenCode</html>', { headers: { 'content-type': 'text/html' } });
+    });
+    const runtime = createRuntime({
+      reapManagedOrphanedProcesses: vi.fn(async () => ({ reaped: 0 })),
+    }, {}, {
+      ENV_CONFIGURED_OPENCODE_PORT: null,
+      ENV_CONFIGURED_OPENCODE_HOST: { origin: 'http://seamus:4095', port: 4095 },
+      ENV_EFFECTIVE_PORT: 4095,
+    });
+
+    await runtime.bootstrapOpenCodeAtStartup();
+
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(requested).toContain('http://seamus:4095/global/health');
+    expect(runtime.testState.isExternalOpenCode).toBe(true);
+    expect(runtime.testState.isOpenCodeReady).toBe(false);
+    expect(runtime.testState.openCodeBaseUrl).toBe('http://seamus:4095');
+    expect(runtime.testState.openCodePort).toBe(4095);
+    expect(runtime.testState.lastOpenCodeError).toContain('1.18.32');
+  });
+
   it('warms recently used directories after a successful bootstrap', async () => {
     const fetchMock = vi.fn(async () => ({
       ok: true,