@openchambery/web 2.0.0-beta.25 → 2.0.0-beta.29

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

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readConfigFile, readConfigLayers, getConfigForPath, getJsonEntrySource, getJsonWriteTarget, writeConfig, writeConfigText } from './config-files.js';
+
+let root;
+let globalDir;
+const put = (file, text) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return file;
+};
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-config-files-'));
+  globalDir = path.join(root, 'xdg', 'opencode');
+  vi.stubEnv('XDG_CONFIG_HOME', path.dirname(globalDir));
+  vi.stubEnv('OPENCODE_CONFIG', '');
+  vi.stubEnv('OPENCODE_CONFIG_DIR', '');
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('physical configuration layers', () => {
+  it('resolves an explicit global directory at call time', () => {
+    const customDirectory = path.join(root, 'custom-directory');
+    put(path.join(customDirectory, 'opencode.jsonc'), '{"model":"custom-directory"}');
+    vi.stubEnv('OPENCODE_CONFIG_DIR', customDirectory);
+    expect(readConfigLayers().mergedConfig).toEqual({ model: 'custom-directory' });
+    expect(getJsonWriteTarget(readConfigLayers(), 'user').path).toBe(path.join(customDirectory, 'opencode.jsonc'));
+  });
+  it('merges both global documents and keeps each write target unmerged', () => {
+    const json = put(path.join(globalDir, 'opencode.json'), '{"model":"base","agent":{"base":{"model":"a"},"shared":{"model":"base","description":"kept"}}}');
+    const jsonc = put(path.join(globalDir, 'opencode.jsonc'), '{ // override\n "model":"override","agent":{"shared":{"model":"override"}},}');
+    put(path.join(globalDir, 'config.json'), '{"model":"legacy-not-loaded-by-v2"}');
+    const layers = readConfigLayers();
+    expect(layers.mergedConfig).toEqual({ model: 'override', agent: { base: { model: 'a' }, shared: { model: 'override', description: 'kept' } } });
+    expect(getJsonEntrySource(layers, 'agent', 'base').path).toBe(json);
+    expect(getJsonEntrySource(layers, 'agent', 'shared').path).toBe(jsonc);
+    expect(getConfigForPath(layers, jsonc)).toEqual({ model: 'override', agent: { shared: { model: 'override' } } });
+    expect(getJsonWriteTarget(layers, 'user').path).toBe(jsonc);
+  });
+
+  it('loads explicit config above global and below discovered project documents', () => {
+    put(path.join(globalDir, 'opencode.json'), '{"model":"global","global":true}');
+    const custom = put(path.join(root, 'custom.jsonc'), '{"model":"explicit","explicit":true}');
+    vi.stubEnv('OPENCODE_CONFIG', custom);
+    const workspace = path.join(root, 'workspace');
+    const nested = path.join(workspace, 'nested');
+    put(path.join(workspace, 'opencode.json'), '{"model":"parent","parent":true}');
+    put(path.join(nested, 'opencode.jsonc'), '{"model":"child"}');
+    put(path.join(workspace, '.opencode', 'opencode.json'), '{"model":"supplementary"}');
+    const layers = readConfigLayers(nested);
+    expect(layers.mergedConfig).toEqual({ model: 'supplementary', global: true, explicit: true, parent: true });
+    expect(getJsonWriteTarget(layers, 'user').path).toBe(custom);
+    expect(getJsonWriteTarget(layers, 'project').path).toBe(path.join(workspace, '.opencode', 'opencode.json'));
+    vi.stubEnv('OPENCODE_CONFIG', '');
+    expect(readConfigLayers().mergedConfig).toEqual({ model: 'global', global: true });
+  });
+
+  it.each(['opencode.json', 'opencode.jsonc'])('reads a single %s and treats missing, blank and comments-only documents explicitly as empty', (name) => {
+    expect(readConfigLayers().mergedConfig).toEqual({});
+    const file = put(path.join(globalDir, name), ' \n');
+    expect(readConfigLayers().mergedConfig).toEqual({});
+    put(file, '// empty config\n/* documented */');
+    expect(readConfigLayers().mergedConfig).toEqual({});
+    put(file, '{"model":"one"}');
+    expect(readConfigLayers().mergedConfig).toEqual({ model: 'one' });
+    expect(getJsonWriteTarget(readConfigLayers(), 'user').path).toBe(file);
+  });
+
+  it.each(['{"model":', '{"model":"x", broken}', '[]', 'null', 'plain text'])('rejects malformed/non-object content %s without changing it', (text) => {
+    const file = put(path.join(globalDir, 'opencode.jsonc'), text);
+    expect(() => readConfigLayers()).toThrow('Invalid JSONC');
+    expect(() => writeConfig({ model: 'new' }, file)).toThrow('Invalid JSONC');
+    expect(() => writeConfigText('{}', file)).toThrow('Invalid JSONC');
+    expect(fs.readFileSync(file, 'utf8')).toBe(text);
+    expect(fs.existsSync(`${file}.openchamber.backup`)).toBe(false);
+  });
+
+  it('propagates read failures instead of returning empty success', () => {
+    const original = fs.readFileSync;
+    vi.spyOn(fs, 'readFileSync').mockImplementation((file, ...args) => {
+      if (String(file) === path.join(globalDir, 'opencode.json')) throw Object.assign(new Error('denied'), { code: 'EACCES' });
+      return original(file, ...args);
+    });
+    expect(() => readConfigLayers()).toThrow('denied');
+  });
+});
+
+describe('structural JSONC writes', () => {
+  it.each(['absolute', 'relative'])('preserves a %s dotfiles symlink while updating its target, permissions and backup', (kind) => {
+    const original = '{ // dotfiles comment\n "model":"old"\n}';
+    const target = put(path.join(root, 'dotfiles', 'config.jsonc'), original);
+    fs.chmodSync(target, 0o664);
+    fs.mkdirSync(globalDir, { recursive: true });
+    const file = path.join(globalDir, 'opencode.jsonc');
+    const link = kind === 'relative' ? path.relative(globalDir, target) : target;
+    fs.symlinkSync(link, file);
+
+    writeConfig({ model: 'new' }, file);
+    expect(fs.lstatSync(file).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(file)).toBe(link);
+    expect(readConfigFile(target)).toEqual({ model: 'new' });
+    expect(fs.readFileSync(target, 'utf8')).toContain('// dotfiles comment');
+    expect(fs.statSync(target).mode & 0o777).toBe(0o664);
+    expect(fs.readFileSync(`${file}.openchamber.backup`, 'utf8')).toBe(original);
+    expect(fs.existsSync(`${target}.openchamber.backup`)).toBe(false);
+
+    const structured = fs.readFileSync(target, 'utf8');
+    writeConfigText('{"model":"raw"}', file);
+    expect(fs.readlinkSync(file)).toBe(link);
+    expect(readConfigFile(target)).toEqual({ model: 'raw' });
+    expect(fs.statSync(target).mode & 0o777).toBe(0o664);
+    expect(fs.readFileSync(`${file}.openchamber.backup`, 'utf8')).toBe(structured);
+  });
+
+  it.each(['writeFileSync', 'chmodSync', 'copyFileSync', 'renameSync'])('preserves a symlink and its original target when %s fails', (method) => {
+    const original = '{ // retained\n "model":"old"\n}';
+    const target = put(path.join(root, 'dotfiles', 'config.jsonc'), original);
+    fs.chmodSync(target, 0o640);
+    fs.mkdirSync(globalDir, { recursive: true });
+    const file = path.join(globalDir, 'opencode.jsonc');
+    const link = path.relative(globalDir, target);
+    fs.symlinkSync(link, file);
+    vi.spyOn(fs, method).mockImplementation(() => { throw new Error('simulated IO failure'); });
+    expect(() => writeConfig({ model: 'new' }, file)).toThrow('simulated IO failure');
+    expect(fs.readlinkSync(file)).toBe(link);
+    expect(fs.readFileSync(target, 'utf8')).toBe(original);
+    expect(fs.statSync(target).mode & 0o777).toBe(0o640);
+    for (const dir of [globalDir, path.dirname(target)]) {
+      expect(fs.readdirSync(dir).some((name) => name.endsWith('.tmp'))).toBe(false);
+    }
+  });
+
+  it.each(['structured', 'raw'])('rejects a dangling symlink during a %s write without replacing it', (kind) => {
+    fs.mkdirSync(globalDir, { recursive: true });
+    const file = path.join(globalDir, 'opencode.jsonc');
+    const link = '../../dotfiles/missing.jsonc';
+    fs.symlinkSync(link, file);
+    const write = () => kind === 'structured' ? writeConfig({ model: 'new' }, file) : writeConfigText('{}', file);
+    expect(write).toThrow(expect.objectContaining({ code: 'ENOENT' }));
+    expect(fs.readlinkSync(file)).toBe(link);
+    expect(fs.existsSync(path.resolve(globalDir, link))).toBe(false);
+    expect(fs.readdirSync(globalDir)).toEqual(['opencode.jsonc']);
+  });
+
+  it('edits nested values, adds fields and removes fields without losing surrounding comments or unrelated bytes', () => {
+    const original = '\uFEFF{\r\n\t// model comment\r\n\t"model": "old",\r\n\t"agent": {"review": {/* owned */ "model":"old", "remove":true, /* trailing */}},\r\n\t// unrelated field\r\n\t"unrelated" : [ 1, 2 ], // leave alone\r\n}\r\n';
+    const file = put(path.join(globalDir, 'opencode.jsonc'), original);
+    const config = readConfigFile(file);
+    config.model = 'new';
+    config.agent.review.model = 'new';
+    delete config.agent.review.remove;
+    config.agent.review.description = 'added';
+    writeConfig(config, file);
+    const saved = fs.readFileSync(file, 'utf8');
+    expect(readConfigFile(file)).toEqual(config);
+    for (const comment of ['// model comment', '/* owned */', '/* trailing */', '// unrelated field', '// leave alone']) expect(saved).toContain(comment);
+    expect(saved).toContain('\t"unrelated" : [ 1, 2 ], // leave alone\r\n');
+    expect(saved.startsWith('\uFEFF')).toBe(true);
+    expect(fs.readFileSync(`${file}.openchamber.backup`, 'utf8')).toBe(original);
+    writeConfig(config, file);
+    expect(fs.readFileSync(file, 'utf8')).toBe(saved);
+    expect(fs.readFileSync(`${file}.openchamber.backup`, 'utf8')).toBe(original);
+  });
+
+  it.each([
+    '{/* before */ "only":1, /* after , */}',
+    '{"keep":2, /* before */ "only":1 /* after */}',
+    '{/* before */ "only":1, /* after */ "keep":2}',
+  ])('removes a property and its comma from %s', (text) => {
+    const file = put(path.join(globalDir, 'opencode.jsonc'), text);
+    const desired = readConfigFile(file);
+    delete desired.only;
+    writeConfig(desired, file);
+    expect(readConfigFile(file)).toEqual(desired);
+    expect(fs.readFileSync(file, 'utf8')).toContain('/* before */');
+    expect(fs.readFileSync(file, 'utf8')).toContain('/* after');
+  });
+
+  it.each(['', '// notes without newline', '{"old":1}'])('supports new/empty/comment-only/JSON files (%s)', (text) => {
+    const file = path.join(globalDir, 'opencode.json');
+    if (text) put(file, text);
+    writeConfig({ model: 'new', nested: { enabled: true } }, file);
+    expect(readConfigFile(file)).toEqual({ model: 'new', nested: { enabled: true } });
+    if (text.startsWith('//')) expect(fs.readFileSync(file, 'utf8')).toContain(text);
+  });
+
+  it.each(['writeFileSync', 'copyFileSync', 'renameSync'])('keeps original content and cleans temporary files when %s fails', (method) => {
+    const original = '{ // retained\n "model":"old"\n}';
+    const file = put(path.join(globalDir, 'opencode.jsonc'), original);
+    vi.spyOn(fs, method).mockImplementation(() => { throw new Error('simulated IO failure'); });
+    expect(() => writeConfig({ model: 'new' }, file)).toThrow('simulated IO failure');
+    expect(fs.readFileSync(file, 'utf8')).toBe(original);
+    expect(fs.readdirSync(globalDir).some((name) => name.endsWith('.tmp'))).toBe(false);
+  });
+});

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

@@ -1179,7 +1179,6 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
       req.path.startsWith('/api/config/commands') ||
       req.path.startsWith('/api/config/global') ||
       req.path.startsWith('/api/config/mcp') ||
-      req.path.startsWith('/api/config/snippets') ||
       req.path.startsWith('/api/config/settings') ||
       req.path.startsWith('/api/config/skills') ||
       req.path.startsWith('/api/config/plugins') ||

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

@@ -310,21 +310,6 @@ describe('core-routes', () => {
     expect(dependencies.gracefulShutdown).not.toHaveBeenCalled();
   });
 
-  it('should parse JSON bodies for snippet config routes', async () => {
-    const app = express();
-    registerCommonRequestMiddleware(app, { express });
-    app.post('/api/config/snippets/example', (req, res) => {
-      res.json({ body: req.body });
-    });
-
-    const response = await request(app)
-      .post('/api/config/snippets/example')
-      .send({ content: 'Snippet body' })
-      .expect(200);
-
-    expect(response.body).toEqual({ body: { content: 'Snippet body' } });
-  });
-
   // Global raw config saves send { content: "<jsonc string>" }. Without this
   // prefix in the JSON middleware allowlist, PUT arrives with an empty body and
   // the handler rejects with "Configuration content must be a string".

package/server/lib/opencode/credential-boundary.d.ts

@@ -0,0 +1 @@
+export function isSensitiveCredentialResponse(method: string, requestPath: string): boolean;

package/server/lib/opencode/credential-boundary.js

@@ -0,0 +1,11 @@
+/** Credential list/create replies contain raw keys in v2. Keep them host-only. */
+export function isSensitiveCredentialResponse(method, requestPath) {
+  let pathname;
+  try {
+    pathname = decodeURIComponent(new URL(requestPath, 'http://openchamber.invalid').pathname).replace(/\/+$/, '').toLowerCase();
+  } catch {
+    return true;
+  }
+  const root = pathname === '/credential' || pathname === '/api/credential';
+  return root && ['GET', 'HEAD', 'POST'].includes(String(method).toUpperCase());
+}

package/server/lib/opencode/ensure-cli.js

@@ -233,6 +233,9 @@ export async function ensurePinnedOpenCode2Cli(input = {}) {
   }
 
   const installedPath = await install({ ...input, version: pin });
-  const version = readVersion(installedPath) || pin;
+  const version = readVersion(installedPath);
+  if (version !== pin) {
+    throw new Error(`Installed OpenCode version mismatch: expected ${pin}, got ${version || 'unknown'}`);
+  }
   return { path: installedPath, version, source: 'installed', installed: true };
 }

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

@@ -33,7 +33,10 @@ export const resolveOpenCodeEnvConfig = (options = {}) => {
       warnInvalidHost(`must use http or https scheme (got ${JSON.stringify(url.protocol)})`);
       return null;
     }
-    const port = parseInt(url.port, 10);
+    // WHATWG URL removes explicit default ports; inspect the authority before normalization.
+    const authority = raw.match(/^https?:\/\/([^/?#]+)/i)?.[1] ?? '';
+    const explicitPort = authority.match(/:(\d+)$/)?.[1];
+    const port = parseInt(url.port || explicitPort || '', 10);
     if (!Number.isFinite(port) || port <= 0) {
       warnInvalidHost('must include an explicit port (example: http://hostname:4096)');
       return null;

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

@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from 'vitest';
+import { resolveOpenCodeEnvConfig } from './env-config.js';
+
+describe('explicit OpenCode host ports', () => {
+  it.each([
+    ['http://example.test:80', 'http://example.test', 80],
+    ['https://example.test:443/', 'https://example.test', 443],
+    ['http://[::1]:80', 'http://[::1]', 80],
+    ['https://[::1]:443', 'https://[::1]', 443],
+    ['http://[::1]:4096', 'http://[::1]:4096', 4096],
+    ['https://example.test:80', 'https://example.test:80', 80],
+  ])('preserves the effective port of %s', (host, origin, port) => {
+    const config = resolveOpenCodeEnvConfig({ env: { OPENCODE_HOST: host, OPENCODE_PORT: '1234' } });
+    expect(config.configuredOpenCodeHost).toEqual({ origin, port });
+    expect(config.effectivePort).toBe(port);
+    expect(new URL('/api/info', config.configuredOpenCodeHost.origin).href).toBe(`${origin}/api/info`);
+  });
+
+  it.each(['http://example.test', 'https://example.test', 'http://[::1]', 'http://example.test:',
+    'ftp://example.test:80', 'http://example.test:80/path', 'http://example.test:80?q=1',
+    'http://example.test:80#hash', 'http://example.test:0', 'http://example.test:65536', 'invalid'])('retains rejection of %s', (host) => {
+    const logger = { warn: vi.fn() };
+    const config = resolveOpenCodeEnvConfig({ env: { OPENCODE_HOST: host, OPENCODE_PORT: '1234' }, logger });
+    expect(config.configuredOpenCodeHost).toBeNull();
+    expect(config.effectivePort).toBe(1234);
+    expect(logger.warn).toHaveBeenCalledOnce();
+  });
+});

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

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { createOpenCodeEnvRuntime } from './env-runtime.js';
+import { PINNED_OPENCODE2_VERSION } from './opencode2-pin.js';
 
 const originalOpencodeBinary = process.env.OPENCODE_BINARY;
 const originalComSpec = process.env.ComSpec;
@@ -305,7 +306,7 @@ describe('OpenCode env runtime', () => {
 
   it('discovers a previously installed pin from the OpenChamber data dir', () => {
     const dataDir = createTempDir('openchamber-installed-cli-');
-    const installedDir = path.join(dataDir, 'opencode-cli', '2.0.12');
+    const installedDir = path.join(dataDir, 'opencode-cli', PINNED_OPENCODE2_VERSION);
     const installedBinary = path.join(installedDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
     fs.mkdirSync(installedDir, { recursive: true });
     fs.writeFileSync(installedBinary, '#!/bin/sh\nexit 0\n');

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

@@ -5,6 +5,8 @@ import { registerSessionGoalRoutes } from '../session-goal/routes.js';
 import { registerSessionMetadataRoutes } from '../session-metadata/routes.js';
 import { registerGitHubRoutes } from '../github/routes.js';
 import { registerGitRoutes } from '../git/routes.js';
+import { makeOpenCodeV2Client } from './v2-client.js';
+import { releaseDeletedWorktreeLocation } from './location-release.js';
 import { registerMagicPromptRoutes } from '../magic-prompts/routes.js';
 import { registerSessionFoldersRoutes } from '../session-folders/routes.js';
 import { registerPermissionAutoAcceptRoutes } from '../permission-auto-accept/runtime.js';
@@ -31,7 +33,6 @@ import { getProviderSources, removeProviderConfig } from './providers.js';
 import { getAgentSources, getAgentConfig, listDisabledAgentOverrides, createAgent, updateAgent, deleteAgent } from './agents.js';
 import { getCommandSources, createCommand, updateCommand, deleteCommand } from './commands.js';
 import { listMcpConfigs, getMcpConfig, createMcpConfig, updateMcpConfig, deleteMcpConfig } from './mcp.js';
-import { listSnippets, getSnippet, createSnippet, updateSnippet, deleteSnippet, expandSnippets } from './snippets.js';
 import {
   listPluginEntries,
   getPluginEntry,
@@ -359,12 +360,6 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       createMcpConfig,
       updateMcpConfig,
       deleteMcpConfig,
-      listSnippets,
-      getSnippet,
-      createSnippet,
-      updateSnippet,
-      deleteSnippet,
-      expandSnippets,
     });
 
     registerPluginRoutes(app, {
@@ -492,6 +487,13 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     registerGitRoutes(app, {
       messageQueueService,
       broadcastWorktreeTopologyChanged,
+      releaseWorktreeLocation: (directory) => releaseDeletedWorktreeLocation({
+        directory,
+        getClient: () => makeOpenCodeV2Client({
+          baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''),
+          authHeaders: getOpenCodeAuthHeaders(),
+        }),
+      }),
     });
     registerMagicPromptRoutes(app, {
       fsPromises,

package/server/lib/opencode/hmr-state-runtime.js

@@ -35,9 +35,9 @@ export const createHmrStateRuntime = (dependencies) => {
     if (typeof hmrState.userProvidedOpenCodePassword !== 'undefined') {
       return;
     }
-    const initialPassword = typeof processLike.env.OPENCODE_SERVER_PASSWORD === 'string'
-      ? processLike.env.OPENCODE_SERVER_PASSWORD.trim()
-      : '';
+    const initialPassword = processLike.env.OPENCODE_PASSWORD?.trim()
+      || processLike.env.OPENCODE_SERVER_PASSWORD?.trim()
+      || '';
     hmrState.userProvidedOpenCodePassword = initialPassword || null;
   };
 
@@ -51,7 +51,7 @@ export const createHmrStateRuntime = (dependencies) => {
     openCodeAuthPassword:
       typeof hmrState.openCodeAuthPassword === 'string' && hmrState.openCodeAuthPassword.length > 0
         ? hmrState.openCodeAuthPassword
-        : userProvidedOpenCodePassword,
+        : hmrState.openCodeAuthSource === 'shared-service' ? null : userProvidedOpenCodePassword,
     openCodeAuthSource:
       typeof hmrState.openCodeAuthSource === 'string' && hmrState.openCodeAuthSource.length > 0
         ? hmrState.openCodeAuthSource

package/server/lib/opencode/lifecycle.js

@@ -29,8 +29,6 @@ const OPENCODE_CHILD_SIGTERM_GRACE_MS = 2500;
 const OPENCODE_CHILD_SIGKILL_WAIT_MS = 1000;
 // Last-used directory plus recently opened projects — deeper tails are unlikely
 // to be the user's first click and just add background work.
-const WARMUP_DIRECTORY_LIMIT = 4;
-const WARMUP_REQUEST_TIMEOUT_MS = 30000;
 
 export const createOpenCodeLifecycleRuntime = (deps) => {
   const {
@@ -57,7 +55,6 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     getManagedOpenCodeShellEnvSnapshot,
     managedCapabilitiesRuntime = null,
     getActiveSessionCount = () => 0,
-    getWarmupDirectories = async () => [],
     // Official background service (shared-service.js). null keeps the private
     // managed `opencode serve` path.
     sharedService = null,
@@ -796,6 +793,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
         ...shellEnv,
         ...process.env,
         PATH: envPath,
+        OPENCODE_PASSWORD: openCodePassword,
         OPENCODE_SERVER_PASSWORD: openCodePassword,
       };
       const managedEnv = managedCapabilitiesRuntime
@@ -1253,11 +1251,6 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
       await waitForOpenCodePort();
       try {
         await waitForOpenCodeReady();
-        // Warm only after readiness admits; a failed gate must not kick off
-        // directory-scoped traffic against an unready upstream.
-        if (state.isOpenCodeReady) {
-          void warmOpenCodeDirectories();
-        }
       } catch (error) {
         console.error(`OpenCode readiness check failed: ${error.message}`);
       }
@@ -1268,47 +1261,6 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     }
   };
 
-  // OpenCode initializes each project directory lazily on its first
-  // directory-scoped request, and that initialization takes seconds on large
-  // session stores. Without warming, the user's first session open pays it
-  // interactively. Warm the most recently used directories right after
-  // readiness so the work overlaps UI startup instead. Sequential and
-  // best-effort: a failed or slow directory never blocks the others for long,
-  // and a restart invalidates the pass via the port/readiness guard.
-  const warmOpenCodeDirectories = async () => {
-    let directories = [];
-    try {
-      directories = await getWarmupDirectories();
-    } catch {
-      return;
-    }
-    if (!Array.isArray(directories) || directories.length === 0) return;
-
-    const warmedPort = state.openCodePort;
-    for (const directory of directories.slice(0, WARMUP_DIRECTORY_LIMIT)) {
-      if (typeof directory !== 'string' || !directory) continue;
-      if (!state.isOpenCodeReady || state.openCodePort !== warmedPort) return;
-      let timeout = null;
-      try {
-        const controller = new AbortController();
-        timeout = setTimeout(() => controller.abort(), WARMUP_REQUEST_TIMEOUT_MS);
-        // Warming a directory is the point, not the answer: any directory-scoped
-        // read makes OpenCode initialise it. `/api/session` is the cheapest one
-        // that takes a directory.
-        const url = `${buildOpenCodeUrl('/api/session', '')}?directory=${encodeURIComponent(directory)}&limit=1`;
-        await fetch(url, {
-          method: 'GET',
-          headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
-          signal: controller.signal,
-        });
-      } catch {
-        // Best-effort — the directory stays lazy and the UI's own request warms it.
-      } finally {
-        if (timeout) clearTimeout(timeout);
-      }
-    }
-  };
-
   const bootstrapOpenCodeAtStartup = () => {
     if (!bootstrapOpenCodePromise) {
       bootstrapOpenCodePromise = runBootstrapOpenCodeAtStartup().finally(() => {

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

@@ -10,6 +10,8 @@ vi.mock('node:child_process', () => ({
 
 const { createOpenCodeLifecycleRuntime } = await import('./lifecycle.js');
 const { createOpenCodeNetworkRuntime } = await import('./network-runtime.js');
+const { resolveOpenCodeEnvConfig } = await import('./env-config.js');
+const { RUNTIME_CONTRACT_MIN_VERIFIED } = await import('./runtime-contract.js');
 
 const originalOpencodeBinary = process.env.OPENCODE_BINARY;
 const originalPath = process.env.PATH;
@@ -106,6 +108,7 @@ const createRuntime = (overrides = {}, stateRef = null) => {
     getManagedOpenCodeShellEnvSnapshot: vi.fn(() => ({
       PATH: '/home/user/.bun/bin:/usr/local/bin:/usr/bin',
       SHELL_ONLY: 'yes',
+      OPENCODE_PASSWORD: 'shell-v2-password',
       OPENCODE_SERVER_PASSWORD: 'shell-password',
     })),
     ...overrides,
@@ -160,6 +163,28 @@ const startListeningChild = () => {
 };
 
 describe('OpenCode lifecycle', () => {
+  it.each(['http://example.test:80', 'https://example.test:443', 'http://[::1]:80'])('attaches explicit default-port host %s without spawning', async (host) => {
+    const config = resolveOpenCodeEnvConfig({ env: { OPENCODE_HOST: host, OPENCODE_PORT: '9999' } });
+    const stateRef = {};
+    const runtime = createRuntime({
+      env: {
+        ENV_CONFIGURED_OPENCODE_PORT: config.configuredOpenCodePort,
+        ENV_CONFIGURED_OPENCODE_HOST: config.configuredOpenCodeHost,
+        ENV_EFFECTIVE_PORT: config.effectivePort,
+        ENV_CONFIGURED_OPENCODE_HOSTNAME: '127.0.0.1',
+        ENV_SKIP_OPENCODE_START: true,
+      },
+      buildOpenCodeUrl: (route) => new URL(route, config.configuredOpenCodeHost.origin).href,
+    }, stateRef);
+    const fetchMock = stubOpenCodeFetch({ health: { ...DEFAULT_V2_HEALTH, version: '2.0.23' } });
+    await runtime.bootstrapOpenCodeAtStartup();
+    await runtime.waitForOpenCodeReady(1000, 1);
+    expect(stateRef.current.isExternalOpenCode).toBe(true);
+    expect(stateRef.current.openCodePort).toBe(config.effectivePort);
+    expect(fetchMock.mock.calls.some(([url]) => String(url) === `${config.configuredOpenCodeHost.origin}/api/info`)).toBe(true);
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
   it('launches managed OpenCode with the managed PATH', async () => {
     delete process.env.OPENCODE_BINARY;
     const child = createMockChild();
@@ -179,6 +204,7 @@ describe('OpenCode lifecycle', () => {
     expect(options.env.PATH).toBe('/home/user/.bun/bin:/usr/local/bin:/usr/bin');
     expect(options.env.SHELL_ONLY).toBe('yes');
     expect(options.env.OPENCODE_SERVER_PASSWORD).toBe('password');
+    expect(options.env.OPENCODE_PASSWORD).toBe('password');
 
     await server.close();
   });
@@ -847,7 +873,7 @@ describe('OpenCode lifecycle', () => {
     stateRef.current.runtimeContract = {
       executionAllowed: true,
       phase: 'ready',
-      serveVersion: '2.0.12',
+      serveVersion: RUNTIME_CONTRACT_MIN_VERIFIED,
       instanceGeneration: 1,
     };
 
@@ -861,7 +887,7 @@ describe('OpenCode lifecycle', () => {
     runtime.refreshRuntimeContractFromProbe(
       {
         ok: true,
-        version: '2.0.12',
+        version: RUNTIME_CONTRACT_MIN_VERIFIED,
         authenticated: true,
         healthOk: true,
       },
@@ -875,7 +901,7 @@ describe('OpenCode lifecycle', () => {
     runtime.refreshRuntimeContractFromProbe(
       {
         ok: true,
-        version: '2.0.12',
+        version: RUNTIME_CONTRACT_MIN_VERIFIED,
         authenticated: true,
         healthOk: true,
       },
@@ -884,7 +910,7 @@ describe('OpenCode lifecycle', () => {
     );
     expect(stateRef.current.runtimeContract.executionAllowed).toBe(true);
     expect(stateRef.current.runtimeContract.instanceGeneration).toBe(2);
-    expect(stateRef.current.runtimeContract.serveVersion).toBe('2.0.12');
+    expect(stateRef.current.runtimeContract.serveVersion).toBe(RUNTIME_CONTRACT_MIN_VERIFIED);
   });
 
   it('does not mark external skip-start ready before version and migration admit', async () => {

package/server/lib/opencode/location-release.d.ts

@@ -0,0 +1,8 @@
+import type { OpenCodeClient } from '@opencode/client';
+
+export type LocationReleaseResult = { state: 'released' | 'timeout' | 'failed' | 'unavailable' };
+export function releaseDeletedWorktreeLocation(input: {
+  getClient: () => OpenCodeClient | null;
+  directory: string;
+  timeoutMs?: number;
+}): Promise<LocationReleaseResult>;

package/server/lib/opencode/location-release.js

@@ -0,0 +1,32 @@
+/**
+ * Explicit worktree deletion only. An eviction acknowledgement detaches cached
+ * services; it does not prove that borrowers have released every OS handle.
+ * Never use this operation for automatic navigation cleanup on a shared serve.
+ *
+ * @param {{ getClient: () => import('@opencode/client').OpenCodeClient | null, directory: string, timeoutMs?: number }} input
+ * @returns {Promise<{ state: 'released' | 'timeout' | 'failed' | 'unavailable' }>}
+ */
+export async function releaseDeletedWorktreeLocation({ getClient, directory, timeoutMs = 2000 }) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    if (!directory || !directory.trim()) return { state: 'unavailable' };
+    const client = getClient();
+    if (!client) return { state: 'unavailable' };
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        resolve({ state: 'timeout' });
+      }, timeoutMs);
+    });
+    const request = Promise.resolve().then(() => client.debug.location.evict(
+      { location: { directory } },
+      { signal: controller.signal },
+    )).then(() => ({ state: 'released' }), () => ({ state: controller.signal.aborted ? 'timeout' : 'failed' }));
+    return await Promise.race([request, deadline]);
+  } catch {
+    return { state: 'failed' };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/server/lib/opencode/location-release.test.js

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OpenCode } from '@opencode/client';
+import { releaseDeletedWorktreeLocation } from './location-release.js';
+
+afterEach(() => vi.useRealTimers());
+
+describe('explicit worktree location release', () => {
+  it('uses the official SDK exact target, current origin and auth', async () => {
+    const requests = [];
+    let origin = 'https://old.invalid';
+    const getClient = () => OpenCode.make({ baseUrl: origin, headers: { Authorization: 'test-auth' }, fetch: async (input, init) => {
+      requests.push(new Request(input, init));
+      return new Response(null, { status: 204 });
+    } });
+    origin = 'https://current.invalid';
+    expect(await releaseDeletedWorktreeLocation({ getClient, directory: '/repo/work tree' })).toEqual({ state: 'released' });
+    expect(requests).toHaveLength(1);
+    const url = new URL(requests[0].url);
+    expect(url.origin + url.pathname).toBe('https://current.invalid/api/debug/location');
+    expect(url.searchParams.get('location[directory]')).toBe('/repo/work tree');
+    expect(requests[0].method).toBe('DELETE');
+    expect(requests[0].headers.get('Authorization')).toBe('test-auth');
+  });
+
+  it('reports failure without claiming successful disposal', async () => {
+    const getClient = () => ({ debug: { location: { evict: async () => { throw new Error('unavailable'); } } } });
+    expect(await releaseDeletedWorktreeLocation({ getClient, directory: '/repo' })).toEqual({ state: 'failed' });
+    expect(await releaseDeletedWorktreeLocation({ getClient: () => null, directory: '/repo' })).toEqual({ state: 'unavailable' });
+  });
+
+  it('bounds even a transport that ignores abort and never settles', async () => {
+    vi.useFakeTimers();
+    let signal;
+    const getClient = () => ({ debug: { location: { evict: (_input, options) => {
+      signal = options.signal;
+      return new Promise(() => {});
+    } } } });
+    const result = releaseDeletedWorktreeLocation({ getClient, directory: '/repo', timeoutMs: 50 });
+    await vi.advanceTimersByTimeAsync(50);
+    expect(await result).toEqual({ state: 'timeout' });
+    expect(signal.aborted).toBe(true);
+  });
+});