@vantran-se/openchamber-web 1.23.0 → 1.24.3

package/server/lib/message-queue/runtime.test.js

@@ -58,7 +58,7 @@ const createOpenCode = () => {
   return { state, fetchImpl };
 };
 
-const createRuntime = ({ dataDir = makeDataDir(), openCode = createOpenCode(), knowledge = null, retryDelayMs } = {}) => {
+const createRuntime = ({ dataDir = makeDataDir(), openCode = createOpenCode(), knowledge = null, retryDelayMs, resolvePromptBody, now } = {}) => {
   let eventHandler = () => {};
   let statusHandler = () => {};
   const broadcasts = [];
@@ -79,6 +79,8 @@ const createRuntime = ({ dataDir = makeDataDir(), openCode = createOpenCode(), k
     abortHoldMs: 50,
   };
   if (retryDelayMs) options.retryDelayMs = retryDelayMs;
+  if (resolvePromptBody) options.resolvePromptBody = resolvePromptBody;
+  if (now) options.now = now;
   const runtime = createMessageQueueRuntime(options);
   return {
     runtime,
@@ -95,6 +97,36 @@ const settle = async (ms = 30) => {
   await new Promise((resolve) => setTimeout(resolve, ms));
 };
 
+describe('auto routing', () => {
+  it('lets the routing hook rewrite the model of a queued prompt and a queued command', async () => {
+    const resolvePromptBody = vi.fn(async (body) => {
+      if (body.model?.modelID === 'auto') body.model = { providerID: 'openai', modelID: 'gpt-6-astra' };
+      if (body.model === 'openchamber/auto') body.model = 'openai/gpt-6-astra';
+      return null;
+    });
+    const { runtime, openCode, emit } = createRuntime({ resolvePromptBody });
+    runtime.start();
+    openCode.state.statuses = { [SESSION]: { type: 'busy' } };
+    openCode.state.commands = [{ name: 'review', template: 'Review $ARGUMENTS' }];
+    const auto = { providerID: 'openchamber', modelID: 'auto', agent: 'build' };
+    await runtime.enqueue(SESSION, DIRECTORY, item({ content: 'plain', text: 'plain', sendConfig: auto }));
+    await runtime.enqueue(SESSION, DIRECTORY, item({ content: '/review src', text: '/review src', sendConfig: auto }));
+
+    openCode.state.statuses = {};
+    emit({ type: 'session.status', properties: { sessionID: SESSION, status: { type: 'idle' } } });
+    await settle();
+    emit({ type: 'session.status', properties: { sessionID: SESSION, status: { type: 'idle' } } });
+    await settle();
+
+    expect(openCode.state.sent.map((entry) => entry.body.model)).toEqual([
+      { providerID: 'openai', modelID: 'gpt-6-astra' },
+      'openai/gpt-6-astra',
+    ]);
+    expect(resolvePromptBody).toHaveBeenCalledTimes(2);
+    expect(resolvePromptBody.mock.calls[0][1]).toEqual({ sessionId: SESSION, directory: DIRECTORY });
+  });
+});
+
 describe('parseQueuedItemInput', () => {
   it('rejects an item the server could not deliver later', () => {
     expect(() => parseQueuedItemInput({ content: 'x' })).toThrow(TypeError);
@@ -175,9 +207,10 @@ describe('message queue runtime', () => {
   });
 
   it('does not send into a running turn even when the status event says idle', async () => {
-    const { runtime, openCode, emit } = createRuntime();
+    const { runtime, openCode, emit } = createRuntime({ now: () => 10_000 });
     runtime.start();
-    openCode.state.tail = [{ info: { role: 'assistant', time: { created: 1 } } }];
+    // Live unfinished turn: created after this runtime started.
+    openCode.state.tail = [{ info: { role: 'assistant', time: { created: 10_001 } } }];
     await runtime.enqueue(SESSION, DIRECTORY, item());
     emit({ type: 'session.status', properties: { sessionID: SESSION, status: { type: 'idle' } } });
     await settle();
@@ -185,10 +218,24 @@ describe('message queue runtime', () => {
 
     // The reply completes: that alone drains the queue (a missed idle event
     // must not strand it).
-    openCode.state.tail = [{ info: { role: 'assistant', time: { created: 1, completed: 2 } } }];
-    emit({ type: 'message.updated', properties: { info: { role: 'assistant', sessionID: SESSION, time: { created: 1, completed: 2 } } } });
+    openCode.state.tail = [{ info: { role: 'assistant', time: { created: 10_001, completed: 10_002 } } }];
+    emit({ type: 'message.updated', properties: { info: { role: 'assistant', sessionID: SESSION, time: { created: 10_001, completed: 10_002 } } } });
+    await settle();
+    expect(openCode.state.sent).toHaveLength(1);
+  });
+
+  it('delivers past an unfinished tail that predates this runtime (dead pre-restart run)', async () => {
+    const { runtime, openCode, emit } = createRuntime({ now: () => 10_000 });
+    runtime.start();
+    // Assistant reply interrupted by a server restart: unfinished, but older
+    // than this runtime — no completion event will ever arrive for it, so it
+    // must not block a restored queue forever.
+    openCode.state.tail = [{ info: { role: 'assistant', time: { created: 1 } } }];
+    await runtime.enqueue(SESSION, DIRECTORY, item());
+    emit({ type: 'session.status', properties: { sessionID: SESSION, status: { type: 'idle' } } });
     await settle();
     expect(openCode.state.sent).toHaveLength(1);
+    expect(openCode.state.sent[0].path).toBe(`/session/${SESSION}/prompt_async`);
   });
 
   it('treats an unreachable OpenCode as unknown, not idle', async () => {
@@ -251,7 +298,7 @@ describe('message queue runtime', () => {
     const first = createRuntime({ dataDir });
     first.runtime.start();
     first.openCode.state.statuses = { [SESSION]: { type: 'busy' } };
-    await first.runtime.enqueue(SESSION, DIRECTORY, item({ content: 'persisted', text: 'persisted' }));
+    await first.runtime.enqueue(SESSION, DIRECTORY, item({ content: 'persisted', text: 'persisted', contextPreview: 'Saved context preview' }));
     await first.runtime.flush();
     first.runtime.stop();
 
@@ -259,6 +306,7 @@ describe('message queue runtime', () => {
     second.runtime.start();
     await second.runtime.load();
     expect(second.runtime.sessionSnapshot(SESSION).items.map((entry) => entry.content)).toEqual(['persisted']);
+    expect(second.runtime.sessionSnapshot(SESSION).items[0].contextPreview).toBe('Saved context preview');
     second.connect();
     await settle();
     expect(second.openCode.state.sent).toHaveLength(1);
@@ -315,6 +363,35 @@ describe('message queue runtime', () => {
     expect(runtime.snapshot().sessions).toEqual([]);
   });
 
+  it('retains a bounded context preview in snapshots and broadcasts without exposing the full payload', async () => {
+    const { runtime, broadcasts } = createRuntime();
+    runtime.start();
+    const context = [{ kind: 'context', text: 'Full quoted content', metadata: { openchamberContext: { kind: 'chat-quote', quote: 'Original answer', text: 'Explain this' } } }];
+    const { itemId } = await runtime.enqueue(SESSION, DIRECTORY, item({ content: '', text: '', context, contextPreview: 'Explain this' }));
+    const projected = runtime.sessionSnapshot(SESSION).items[0];
+    expect(projected.contextPreview).toBe('Explain this');
+    expect(projected.content).toBe('');
+    expect(projected.text).toBe('');
+    expect(projected).not.toHaveProperty('context');
+    expect(broadcasts.at(-1).properties.session.items[0].contextPreview).toBe('Explain this');
+    const taken = await runtime.take(SESSION, itemId);
+    expect(taken.item.context).toEqual(context);
+    expect(taken.item.content).toBe('');
+
+    await runtime.enqueue(SESSION, DIRECTORY, item({ content: '', text: '', context, contextPreview: 'a'.repeat(5000) }));
+    expect(runtime.sessionSnapshot(SESSION).items[0].contextPreview).toBe('a'.repeat(100) + '...');
+  });
+
+  it('derives a preview for older queued annotations without a saved summary', async () => {
+    const { runtime } = createRuntime();
+    runtime.start();
+    await runtime.enqueue(SESSION, DIRECTORY, item({ content: '', text: '', context: [
+      { kind: 'instruction', text: 'Use the skill' },
+      { kind: 'context', text: 'Model-facing wrapper', metadata: { openchamberContext: { kind: 'browser-annotation', text: 'Fix the button\nMore detail' } } },
+    ] }));
+    expect(runtime.sessionSnapshot(SESSION).items[0].contextPreview).toBe('Fix the button...');
+  });
+
   it('names the directory in the broadcast that empties a queue', async () => {
     // The UI keys its projection by directory; without it the client cannot
     // tell which queue just delivered its last message and keeps showing it.

package/server/lib/notifications/DOCUMENTATION.md

@@ -77,7 +77,7 @@ This module provides notification message preparation utilities for the web serv
 ### Emitter runtime API (emitter-runtime.js)
 - `createNotificationEmitterRuntime(dependencies)`: creates runtime for unified notification emission channels.
 - Returned API:
-  - `writeSseEvent(res, payload)`
+   - `writeSseEvent(res, payload, serializedPayload?)`, where broadcast callers may share one JSON encoding across recipients
   - `emitDesktopNotification(payload)`
   - `broadcastUiNotification(payload)`
 

package/server/lib/notifications/emitter-runtime.js

@@ -22,8 +22,8 @@ export const createNotificationEmitterRuntime = (dependencies) => {
     onDesktopNotification = typeof cb === 'function' ? cb : null;
   };
 
-  const writeSseEvent = (res, payload) => {
-    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+  const writeSseEvent = (res, payload, serializedPayload = JSON.stringify(payload)) => {
+    res.write(`data: ${serializedPayload}\n\n`);
   };
 
   const emitDesktopNotification = (payload) => {
@@ -91,9 +91,10 @@ export const createNotificationEmitterRuntime = (dependencies) => {
       return;
     }
 
+    const serializedPayload = JSON.stringify(syntheticPayload);
     for (const res of clients) {
       try {
-        writeSseEvent(res, syntheticPayload);
+        writeSseEvent(res, syntheticPayload, serializedPayload);
       } catch {
         // ignore
       }

package/server/lib/notifications/routes.js

@@ -44,6 +44,7 @@ export const registerNotificationRoutes = (app, dependencies) => {
     writeSseEvent,
     getSessionActivitySnapshot,
     getSessionStateSnapshot,
+    getPendingBlockingRequestsSnapshot,
     getSessionAttentionSnapshot,
     getSessionState,
     getSessionAttentionState,
@@ -295,11 +296,15 @@ export const registerNotificationRoutes = (app, dependencies) => {
     });
   });
 
+  // Cross-project seed for clients that do not initialize every directory:
+  // live status per session plus the permission and question requests still
+  // waiting for an answer. Both come from the server's single upstream stream.
   app.get('/api/sessions/status', async (_req, res) => {
     await ensureSessionWatcher();
     const snapshot = getSessionStateSnapshot();
     res.json({
       sessions: snapshot,
+      pending: typeof getPendingBlockingRequestsSnapshot === 'function' ? getPendingBlockingRequestsSnapshot() : {},
       serverTime: Date.now(),
     });
   });

package/server/lib/openchamber-control/DOCUMENTATION.md

@@ -44,6 +44,12 @@ other.
 - Send and fork dispatches without an explicit model/agent/variant reuse the
   target session's last user-message selection before falling back to the
   configured defaults; only session creation resolves defaults directly.
+- Default agents resolve from the owning project before global settings and
+  OpenCode defaults. Directory-based requests identify the project before
+  creating a worktree; existing linked worktrees resolve through Git's primary
+  worktree root. Send/fork fallback uses that same owner. Configured model IDs
+  and effort preferences survive missing catalog entries rather than silently
+  dispatching with a different model.
 - Usage errors name the missing or conflicting input so CLI and agent-tool
   callers can correct an invalid request without an upfront usage manual.
 - Explicit `projectId` or `directory` scope takes precedence over the managed

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

@@ -1,6 +1,6 @@
 import express from 'express';
 import { createOpencodeClient } from '@opencode-ai/sdk/v2';
-import { createWorktree, getWorktreeBootstrapStatus } from '../git/index.js';
+import { createWorktree, getWorktreeBootstrapStatus, resolvePrimaryWorktreeRoot } from '../git/index.js';
 import { expandSnippets } from '../opencode/snippets.js';
 import { expandCommandGoalObjective, parseScheduledCommandPrompt } from '../scheduled-tasks/runtime.js';
 import { buildGoalIntroText, createSessionGoal } from '../session-goal/create.js';
@@ -75,6 +75,7 @@ const resolveVariant = (providers, providerID, modelID, variant) => {
   if (!normalized) return undefined;
   const provider = providers.find((entry) => entry?.id === providerID);
   const model = providerModels(provider).find((entry) => entry?.id === modelID);
+  if (!model) return normalized;
   return model?.variants && Object.prototype.hasOwnProperty.call(model.variants, normalized)
     ? normalized
     : undefined;
@@ -82,6 +83,18 @@ const resolveVariant = (providers, providerID, modelID, variant) => {
 
 const parseConfigModel = (value) => splitModel(value);
 
+const resolveProjectDefaults = (settings, directory, projectId) => {
+  const projects = Array.isArray(settings?.projects) ? settings.projects : [];
+  const matchedProject = projectId
+    ? projects.find((entry) => entry?.id === projectId) || null
+    : projects.find((entry) => entry?.path === directory) || null;
+  return {
+    defaultAgent: asNonEmptyString(matchedProject?.defaultAgent),
+    defaultModel: asNonEmptyString(matchedProject?.defaultModel),
+    defaultVariant: asNonEmptyString(matchedProject?.defaultVariant),
+  };
+};
+
 const buildDirectoryHeaders = (directory) => ({
   // OpenCode rejects non-ASCII header values; the official SDK sends this
   // header percent-encoded, so match that wire format (non-ASCII checkout
@@ -121,11 +134,15 @@ const fetchSelectionInputs = async ({ buildOpenCodeUrl, authHeaders, directory,
   };
 };
 
-const resolveDefaultSelection = ({ agents, providers, settings, opencodeDefaultAgent, opencodeDefaultModel }) => {
+const resolveDefaultSelection = ({ agents, providers, settings, projectDefaults, opencodeDefaultAgent, opencodeDefaultModel }) => {
   const primaryAgents = agents.filter((agent) => isPrimaryAgentMode(agent?.mode) && agent?.hidden !== true);
   let resolvedAgent = null;
+  const projectDefaultAgent = asNonEmptyString(projectDefaults?.defaultAgent);
   const settingsDefaultAgent = asNonEmptyString(settings?.defaultAgent);
-  if (settingsDefaultAgent) {
+  if (projectDefaultAgent) {
+    resolvedAgent = agents.find((agent) => agent?.name === projectDefaultAgent) || null;
+  }
+  if (!resolvedAgent && settingsDefaultAgent) {
     resolvedAgent = agents.find((agent) => agent?.name === settingsDefaultAgent) || null;
   }
   if (!resolvedAgent && opencodeDefaultAgent) {
@@ -140,20 +157,24 @@ const resolveDefaultSelection = ({ agents, providers, settings, opencodeDefaultA
 
   let model = null;
   let variant;
+  const projectDefaultModel = parseConfigModel(projectDefaults?.defaultModel);
   const settingsDefaultModel = parseConfigModel(settings?.defaultModel);
-  if (settingsDefaultModel && hasProviderModel(providers, settingsDefaultModel.providerID, settingsDefaultModel.modelID)) {
+  if (projectDefaultModel) {
+    model = projectDefaultModel;
+    variant = resolveVariant(providers, model.providerID, model.modelID, projectDefaults?.defaultVariant);
+  }
+  if (!model && settingsDefaultModel) {
     model = settingsDefaultModel;
     variant = resolveVariant(providers, model.providerID, model.modelID, settings?.defaultVariant);
   }
 
-  if (!model && resolvedAgent?.model?.providerID && resolvedAgent?.model?.modelID
-    && hasProviderModel(providers, resolvedAgent.model.providerID, resolvedAgent.model.modelID)) {
+  if (!model && resolvedAgent?.model?.providerID && resolvedAgent?.model?.modelID) {
     model = { providerID: resolvedAgent.model.providerID, modelID: resolvedAgent.model.modelID };
     variant = resolveVariant(providers, model.providerID, model.modelID, resolvedAgent.variant);
   }
 
   const opencodeModel = parseConfigModel(opencodeDefaultModel);
-  if (!model && opencodeModel && hasProviderModel(providers, opencodeModel.providerID, opencodeModel.modelID)) {
+  if (!model && opencodeModel) {
     model = opencodeModel;
   }
 
@@ -304,9 +325,15 @@ const resolveRequestedDirectory = async ({ payload, readSettingsFromDiskMigrated
 
   const directory = asNonEmptyString(payload?.directory);
   const validated = await validateDirectoryPath(directory);
-  return validated.ok
-    ? { ok: true, directory: validated.directory }
-    : { ok: false, status: 400, error: validated.error || 'Invalid directory' };
+  if (!validated.ok) return { ok: false, status: 400, error: validated.error || 'Invalid directory' };
+  const settings = await readSettingsFromDiskMigrated();
+  const projects = sanitizeProjects(settings?.projects || []);
+  let project = projects.find((entry) => entry.path === validated.directory);
+  if (!project && projects.length > 0) {
+    const { root } = await resolvePrimaryWorktreeRoot(validated.directory);
+    project = projects.find((entry) => entry.path === root);
+  }
+  return { ok: true, directory: validated.directory, ...(project ? { projectId: project.id } : {}) };
 };
 
 const PROMPT_LANDED_TIMEOUT_MS = 5_000;
@@ -395,6 +422,10 @@ export const createOpenChamberSessionService = (dependencies) => {
     emitSessionCreatedEvent,
     createSessionGoal: createSessionGoalOverride,
     sessionKnowledgeRuntime = null,
+    // Auto routing. Prompts dispatched here go straight to OpenCode, not
+    // through the proxy that rewrites the Auto sentinel, so the same hook runs
+    // on the body before it is sent. Null when routing is not wired in.
+    resolvePromptBody = null,
   } = dependencies;
 
   // Last user message of an existing session, as a selection to reuse. Returns
@@ -468,6 +499,7 @@ export const createOpenChamberSessionService = (dependencies) => {
     authHeaders,
     sessionID,
     directory,
+    projectId,
     prompt,
     goalInput,
     requestedModel,
@@ -495,7 +527,10 @@ export const createOpenChamberSessionService = (dependencies) => {
         directory,
         readSettingsFromDiskMigrated,
       });
-      const defaults = resolveDefaultSelection(inputs);
+      const defaults = resolveDefaultSelection({
+        ...inputs,
+        projectDefaults: resolveProjectDefaults(inputs.settings, directory, projectId),
+      });
       if (!model) {
         model = defaults.model;
         if (variant == null) variant = defaults.variant;
@@ -565,25 +600,21 @@ export const createOpenChamberSessionService = (dependencies) => {
         ? await sessionKnowledgeRuntime.resolvePendingForSession(sessionID, directory)
           .catch(() => ({ text: '', signature: '' }))
         : { text: '', signature: '' };
+      const payload = {
+        model,
+        ...(agent ? { agent } : {}),
+        ...(variant ? { variant } : {}),
+        parts: [
+          ...(knowledge.text ? [{ type: 'text', text: knowledge.text, synthetic: true }] : []),
+          { type: 'text', text: expandedPrompt },
+          ...(goalInput.enabled
+            ? [{ type: 'text', text: buildGoalIntroText(goalInput.tokenBudget), synthetic: true }]
+            : []),
+        ],
+      };
+      await resolvePromptBody?.(payload, { sessionId: sessionID, directory });
       try {
-        await runPromptAsync({
-          baseUrl,
-          authHeaders,
-          sessionID,
-          directory,
-          payload: {
-            model,
-            ...(agent ? { agent } : {}),
-            ...(variant ? { variant } : {}),
-            parts: [
-              ...(knowledge.text ? [{ type: 'text', text: knowledge.text, synthetic: true }] : []),
-              { type: 'text', text: expandedPrompt },
-              ...(goalInput.enabled
-                ? [{ type: 'text', text: buildGoalIntroText(goalInput.tokenBudget), synthetic: true }]
-                : []),
-            ],
-          },
-        });
+        await runPromptAsync({ baseUrl, authHeaders, sessionID, directory, payload });
       } catch (error) {
         throw markGoalPartial(error);
       }
@@ -735,6 +766,7 @@ export const createOpenChamberSessionService = (dependencies) => {
         authHeaders,
         sessionID,
         directory: sessionDirectory,
+        projectId: resolvedDirectory.projectId,
         prompt,
         goalInput,
         requestedModel: model,
@@ -838,6 +870,7 @@ export const createOpenChamberSessionService = (dependencies) => {
         authHeaders,
         sessionID: targetSessionID,
         directory,
+        projectId: resolvedDirectory.projectId,
         prompt,
         goalInput,
         requestedModel,

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

@@ -90,6 +90,7 @@ vi.mock('@opencode-ai/sdk/v2', () => ({
 vi.mock('../git/index.js', () => ({
   createWorktree: (...args) => globalThis.__openchamberCreateWorktreeMock(...args),
   getWorktreeBootstrapStatus: (...args) => globalThis.__openchamberGetWorktreeBootstrapStatusMock(...args),
+  resolvePrimaryWorktreeRoot: async (directory) => ({ root: directory === '/repo/worktrees/side-task' ? '/repo/app' : directory }),
 }));
 
 const createApp = (overrides = {}, options = {}) => {
@@ -360,6 +361,101 @@ describe('openchamber session routes', () => {
     }
   });
 
+  it('lets the routing hook replace an Auto default before the prompt leaves', async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async (url) => {
+      const text = String(url);
+      if (text.includes('/prompt_async')) {
+        return { ok: true, text: async () => '' };
+      }
+      if (text.includes('/config/providers')) {
+        return { ok: true, json: async () => ({ providers: [{ id: 'openai', models: { 'gpt-5.5': { id: 'gpt-5.5' } } }] }) };
+      }
+      if (text.includes('/agent')) {
+        return { ok: true, json: async () => [{ name: 'build', mode: 'primary' }] };
+      }
+      if (text.includes('/config')) {
+        return { ok: true, json: async () => ({}) };
+      }
+      return { ok: true, json: async () => ({ id: 'ses_123' }) };
+    });
+    globalThis.fetch = fetchMock;
+    const seen = [];
+    const resolvePromptBody = vi.fn(async (body, target) => {
+      seen.push({ model: body.model, target });
+      body.model = { providerID: 'openai', modelID: 'gpt-5.5' };
+    });
+    const { app } = createApp({
+      readSettingsFromDiskMigrated: async () => ({
+        defaultModel: 'openchamber/auto',
+        defaultAgent: 'build',
+        projects: [{ id: 'proj_1', path: '/repo/app' }],
+      }),
+      resolvePromptBody,
+    });
+    try {
+      await request(app)
+        .post('/api/openchamber/sessions')
+        .send({ directory: '/repo/app', prompt: 'Run this' })
+        .expect(200);
+
+      expect(seen).toEqual([{
+        model: { providerID: 'openchamber', modelID: 'auto' },
+        target: { sessionId: 'ses_123', directory: '/repo/app' },
+      }]);
+      const promptCall = fetchMock.mock.calls.find(([url]) => String(url).includes('/prompt_async'));
+      expect(JSON.parse(promptCall?.[1]?.body).model).toEqual({ providerID: 'openai', modelID: 'gpt-5.5' });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it.each([
+    ['', { projectId: 'proj_1' }],
+    ['', { directory: '/repo/app', worktree: { name: 'side-task' } }],
+    ['', { directory: '/repo/worktrees/side-task' }],
+    ['/ses_existing/send', { directory: '/repo/worktrees/side-task' }],
+    ['/ses_existing/fork', { directory: '/repo/worktrees/side-task' }],
+  ])('prefers project defaults for %s with %j', async (endpoint, scope) => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async (url) => {
+      const text = String(url);
+      if (text.includes('/prompt_async')) {
+        return { ok: true, text: async () => '' };
+      }
+      if (text.includes('/config/providers')) {
+        return { ok: true, json: async () => ({ providers: [{ id: 'openai', models: { 'gpt-5.5': { id: 'gpt-5.5' } } }] }) };
+      }
+      if (text.includes('/agent')) {
+        return { ok: true, json: async () => [{ name: 'build', mode: 'primary' }, { name: 'plan', mode: 'primary' }] };
+      }
+      if (text.includes('/config')) {
+        return { ok: true, json: async () => ({}) };
+      }
+      return { ok: true, json: async () => ({ id: 'ses_123' }) };
+    });
+    globalThis.fetch = fetchMock;
+    const { app } = createApp({
+      readSettingsFromDiskMigrated: async () => ({
+        defaultModel: 'openai/gpt-5.5',
+        defaultAgent: 'build',
+        projects: [{ id: 'proj_1', path: '/repo/app', defaultAgent: 'plan' }],
+      }),
+    });
+    try {
+      const response = await request(app)
+        .post(`/api/openchamber/sessions${endpoint}`)
+        .send({ ...scope, prompt: 'Run this' })
+        .expect(200);
+
+      expect(response.body.agent).toBe('plan');
+      const promptCall = fetchMock.mock.calls.find(([url]) => String(url).includes('/prompt_async'));
+      expect(JSON.parse(promptCall?.[1]?.body)).toMatchObject({ agent: 'plan' });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
   it('dispatches an initial prompt when model is provided', async () => {
     const originalFetch = globalThis.fetch;
     const fetchMock = vi.fn(async (url) => {

package/server/lib/opencode/DOCUMENTATION.md

@@ -32,10 +32,9 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: tunnel service/routes composition runtime and active-port wiring for main server startup.
 - `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: server startup tail orchestration runtime for terminal/proxy/static/start-listen flow.
 - `packages/web/server/lib/opencode/startup-performance.js`: opt-in startup phase diagnostics with fixed labels and numeric metadata allowlists.
-- `packages/web/server/lib/agent-tool/runtime.js`: managed OpenCode custom-tool materialization, environment injection, loopback authentication, and fixed CLI action dispatch.
+- `packages/web/server/lib/agent-tool/runtime.js`: managed OpenCode custom-tool materialization, environment injection, same-machine authentication (loopback, or the bound address for a concrete bind), and fixed CLI action dispatch.
 - `packages/web/server/lib/system-prompt/runtime.js`: opt-in managed OpenCode system-prompt optimizer materialization and plugin injection.
-- `packages/web/server/lib/mcp-reconnect/runtime.js`: always-on managed OpenCode plugin that reconnects MCP servers OpenCode marked `failed`, with per-server backoff.
-- `packages/web/server/lib/opencode/managed-plugin-config.js`: the one `OPENCODE_CONFIG_CONTENT` merge every managed plugin (agent tools, system prompt optimizer, MCP reconnect) appends itself through.
+- `packages/web/server/lib/opencode/managed-plugin-config.js`: the one `OPENCODE_CONFIG_CONTENT` merge every managed plugin (agent tools, system prompt optimizer) appends itself through.
 - `packages/web/server/lib/opencode/server-utils-runtime.js`: shared server runtime utilities for OpenCode proxy wiring, OpenCode port/readiness helpers, and snapshot fetchers.
 - `packages/web/server/lib/opencode/openchamber-routes.js`: OpenChamber update and models metadata route registration.
 - `packages/web/server/lib/opencode/pwa-manifest-routes.js`: PWA manifest route registration with recent-session shortcut resolution and short-lived caching.
@@ -45,6 +44,28 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/settings-helpers.js`: Settings payload sanitization/format helpers runtime for response shaping and persisted merge prep.
 - `packages/web/server/lib/opencode/settings-normalization-runtime.js`: path/settings/tunnel normalization and sanitization helpers runtime used by settings/routes/config wiring.
 - `packages/web/server/lib/opencode/theme-runtime.js`: custom theme JSON validation and theme directory loading runtime for settings utility routes.
+
+  `POST /api/config/themes` saves a converted VS Code palette. The runtime validates
+  literal colors and required authored roles, assigns a content-derived filename,
+  and publishes through a same-directory hard link so partial files and overwrites
+  are impossible. Identical retries reuse the existing file; a manually edited
+  collision returns 409. Temporary files are ignored by the loader and removed
+  after publication or failure. Non-missing-directory read failures propagate to
+  the route instead of returning an authoritative empty library.
+
+  The common request middleware parses theme POST bodies before these routes;
+  integration tests must use that middleware rather than an unrestricted test parser.
+  `DELETE /api/config/themes/:id` finds a valid regular JSON file by its metadata ID
+  inside the custom themes directory. IDs are never used as filenames. Hand-added
+  themes are supported; symlinks and bundled themes are outside deletion ownership.
+  Duplicate matching IDs fail explicitly. Missing themes are an idempotent success;
+  filesystem failures remain errors.
+  `theme-catalog.js` owns POST catalog search/package routes under
+  `/api/config/themes/catalog/`. It fetches only Open VSX and its Eclipse CDN over
+  HTTPS, validates redirects and checksums, and verifies packaged identity.
+  `theme-archive.js` reads selected JSON entries in memory with bounded decompression.
+  JSON includes and token references stay inside the package. Each failed variant
+  is reported separately so valid siblings remain available. No extension code runs.
 - `packages/web/server/lib/opencode/proxy.js`: OpenCode API/SSE forwarding and readiness-gate route registration.
 - `packages/web/server/lib/opencode/session-runtime.js`: session status/attention/activity runtime for OpenCode SSE events.
 - `packages/web/server/lib/opencode/watcher.js`: global SSE watcher runtime for push/session event fanout.
@@ -132,8 +153,12 @@ The runtime maintains active-session count incrementally from idempotent activit
   - `killProcessOnPort(port)`
 
 Managed OpenCode launch also merges the environment returned by the agent-tool
-runtime, the opt-in system prompt optimizer, and the always-on MCP reconnect
-plugin, each appending its `file://` entry to the previous one's config. PATH and `OPENCODE_SERVER_PASSWORD` remain lifecycle-owned and cannot
+runtime and the opt-in system prompt optimizer, each appending its `file://`
+entry to the previous one's config. OpenChamber adds no automatic MCP reconnect
+loop; recovery after a failed connection is manual for both local and remote
+servers. Previously generated reconnect plugin files are inert because managed
+launch no longer registers them. User-configured plugins remain user-owned.
+PATH and `OPENCODE_SERVER_PASSWORD` remain lifecycle-owned and cannot
 be replaced by injected values. External OpenCode processes receive no
 OpenChamber tool injection. Managed launch env strips AppImage `ARGV0` before
 spawn so zsh-backed OpenCode tools do not rewrite child argv[0] to the AppImage
@@ -153,9 +178,27 @@ Transport-triggered health checks share the periodic monitor's failure accountin
 
 Managed health failures are classified as `timeout`, `connection_refused`, `connection_reset`, `invalid_response`, or `error`. The lifecycle retains the latest counted failure with a bounded detail string and source. Managed process wrappers continue capturing a sanitized, bounded stderr tail after readiness and retain exit code/signal. Before replacing a managed process, lifecycle snapshots the reason, latest health failure, process diagnostics/aliveness, busy-session count, and timestamp into `lastOpenCodeRestartDiagnostics`; successful startup does not clear this snapshot, and `/health` exposes it for post-restart diagnosis without process environment or credentials.
 
+Managed process ownership starts at spawn. The registry and runtime process
+handle include children that have not announced readiness yet, so shutdown can
+stop an in-flight startup. Readiness timeout, malformed startup output, and
+health-probe errors close that child before retrying. Shutdown cancels further
+startup attempts. Closing a process is single-flight and unregisters it only
+after it exits.
+
+On Windows, managed teardown invokes the existing tree termination command
+before terminating the root. Calling `child.kill()` first loses the ancestry
+needed to find Git, shell, and MCP descendants. On POSIX, the managed child
+starts in its own process group and teardown escalates against that group even
+if the root has already exited. A tool ignoring SIGTERM must not survive just
+because the server closed its own pipes. The
+`lifecycle-process.test.js` regressions launch real parent/child fixtures and
+check PID exit plus registry cleanup. macOS results do not validate Windows
+ConPTY or Console Window Host behavior.
+
 ## Public exports (env-runtime.js)
 - `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state.
 - OpenCode CLI resolution order is persisted settings, environment overrides, bundled Desktop CLI when available, PATH, known install locations, then platform shell discovery.
+- Automatic bundled resolution under `OPENCHAMBER_RUNTIME=desktop` stays in runtime state and is returned to the managed launch function, including on OpenCode restart. It does not populate `process.env.OPENCODE_BINARY`: AppImage updater relaunch inherits that environment and would mistake the previous bundle path for an explicit override. Explicit settings/env selections and non-desktop or non-bundled resolution retain their existing environment behavior. This prevents future inheritance; it does not reinterpret overrides already inherited from older releases.
 - Returned API:
   - `applyLoginShellEnvSnapshot()`
   - `getLoginShellEnvSnapshot()`
@@ -328,6 +371,7 @@ Managed health failures are classified as `timeout`, `connection_refused`, `conn
 
 ## Public exports (shutdown-runtime.js)
 - `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown runtime for managed OpenCode and web server teardown sequencing.
+- After stopping owned runtimes and OpenCode, HTTP shutdown closes active connections as well as the listener. A remaining SSE response must not hold Desktop open until its fallback deadline. Upgraded sockets remain the responsibility of their owning runtime.
 - Returned API:
   - `gracefulShutdown(options?)`
 
@@ -385,6 +429,20 @@ within a ten-minute overall deadline.
     - Foreground servers running under a systemd user unit queue installation in
       a separate transient unit and restart the configured service afterwards.
       `OPENCHAMBER_SYSTEMD_UNIT` overrides the default `openchamber.service`.
+    - On Windows the install-and-restart script is written to
+      `<data dir>/update-install.cmd` before the response and run with
+      `cmd.exe /c <file>`. A newline ends a `cmd.exe /c` command line, so the
+      same script passed as an argument ran nothing and exited 0; the batch
+      file keeps every line. The package-manager line is `call`ed because
+      npm, pnpm and yarn are `.cmd` shims that would otherwise end the script,
+      the pre-install pause is a loopback `ping` because `timeout` rejects a
+      detached child's stdin, and the file deletes itself on its last line
+      because the restart command carries the server's flags. If the file
+      cannot be written the route answers 500 and the server keeps running.
+      The listener is closed before the batch is spawned: on Windows the
+      detached child inherits the listening socket and would hold the port
+      for the whole batch, so the restart inside it failed with "port already
+      in use" and the update ended with no server.
   - `GET /api/openchamber/models-metadata`
   - `GET /api/zen/models`
 
@@ -422,6 +480,16 @@ within a ten-minute overall deadline.
   - Generic `/api/*` forwarding with hop-by-hop header filtering
   - Windows `/session` merge fallback path behavior
   - OpenCode readiness gate for proxied `/api` requests
+  - Worktree checkout gate before directory-scoped upstream reads and writes
+
+Git bootstrap must reach `git-ready` before OpenCode can cache a new worktree's
+project identity or config. Setup scripts may still be running; the optional UI
+setup wait remains separate. Failed or timed-out checkout returns 503 without
+forwarding. The shared draft creator keeps the project directory selected until
+creation returns, because preview paths have no bootstrap state.
+
+This server gate covers web, Electron, hosted mobile, and Capacitor connections.
+The VS Code extension owns its separate Git and proxy implementation.
 
 ## Public exports (watcher.js)
 - `createOpenCodeWatcherRuntime(dependencies)`: creates global event watcher runtime backed by the shared upstream SSE reader.

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

@@ -131,6 +131,7 @@ export const createBootstrapRuntime = (dependencies) => {
       writeSseEvent,
       getSessionActivitySnapshot: sessionRuntime.getSessionActivitySnapshot,
       getSessionStateSnapshot: sessionRuntime.getSessionStateSnapshot,
+      getPendingBlockingRequestsSnapshot: sessionRuntime.getPendingBlockingRequestsSnapshot,
       getSessionAttentionSnapshot: sessionRuntime.getSessionAttentionSnapshot,
       getSessionState: sessionRuntime.getSessionState,
       getSessionAttentionState: sessionRuntime.getSessionAttentionState,