@vantran-se/openchamber-web 2.0.2 → 2.0.4

package/server/lib/agent-tool/runtime.js

@@ -167,6 +167,40 @@ const resolveConcreteBoundAddress = (value) => {
  * answer with an empty completion instead of an error, and the `oneOf` branches
  * are what carry the per-action descriptions the model reads.
  */
+const createEnvironmentExecutionSource = (name) => `const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
+        const token = process.env.OPENCHAMBER_AGENT_TOOL_TOKEN
+        const callbackHeaders = {}
+        if (!endpoint || !token) {
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber managed tool connection is unavailable" } })
+        }
+
+        try {
+          const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+              authorization: "Bearer " + token,
+              "content-type": "application/json",
+              ...callbackHeaders,
+            },
+            // OpenCode 2 no longer hands a tool its session directory, so the
+            // session id goes over instead and OpenChamber resolves the
+            // directory on its own side. The signal fires when the session is
+            // aborted, so the OpenChamber side stops the action too.
+            body: JSON.stringify({ input: args, sessionID: context.sessionID, tool: ${JSON.stringify(name)} }),
+            signal: context.signal,
+          })
+          const content = await response.text()
+          let result = null
+          try { result = JSON.parse(content) } catch {}
+          const valid = result?.schemaVersion === ${TOOL_SCHEMA_VERSION} && typeof result?.ok === "boolean" && typeof result?.action === "string"
+          await progress({ ok: valid && result.ok === true })
+          if (valid) return { content, metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: result.ok === true } } }
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber returned an invalid response", kind: "runtime", status: response.status } })
+        } catch (error) {
+          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: error instanceof Error ? error.message : String(error), kind: "runtime" } })
+        }`;
+
+
 const createToolEntry = ({ name, description, definitions, parameters }) => String.raw`    tools.add({
       name: ${JSON.stringify(name)},
       description: ${JSON.stringify(description)},
@@ -199,8 +233,6 @@ const createToolEntry = ({ name, description, definitions, parameters }) => Stri
           },
         })
         await progress()
-        const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
-        const token = process.env.OPENCHAMBER_AGENT_TOOL_TOKEN
         // No output schema is declared, so a result must never carry an output
         // field: OpenCode rejects that with "Tool result declared output
         // without an output schema". The envelope travels as text content.
@@ -208,39 +240,17 @@ const createToolEntry = ({ name, description, definitions, parameters }) => Stri
           content: JSON.stringify(payload),
           metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: false } },
         })
-        if (!endpoint || !token) {
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber managed tool connection is unavailable" } })
-        }
-
-        try {
-          const response = await fetch(endpoint, {
-            method: "POST",
-            headers: {
-              authorization: "Bearer " + token,
-              "content-type": "application/json",
-            },
-            // OpenCode 2 no longer hands a tool its session directory, so the
-            // session id goes over instead and OpenChamber resolves the
-            // directory on its own side. The signal fires when the session is
-            // aborted, so the OpenChamber side stops the action too.
-            body: JSON.stringify({ input: args, sessionID: context.sessionID, tool: ${JSON.stringify(name)} }),
-            signal: context.signal,
-          })
-          const content = await response.text()
-          let result = null
-          try { result = JSON.parse(content) } catch {}
-          const valid = result?.schemaVersion === ${TOOL_SCHEMA_VERSION} && typeof result?.ok === "boolean" && typeof result?.action === "string"
-          await progress({ ok: valid && result.ok === true })
-          if (valid) return { content, metadata: { openchamber: { schemaVersion: ${TOOL_SCHEMA_VERSION}, action: args.action, description: title, ok: result.ok === true } } }
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: "OpenChamber returned an invalid response", kind: "runtime", status: response.status } })
-        } catch (error) {
-          return failure({ schemaVersion: ${TOOL_SCHEMA_VERSION}, ok: false, action: args.action, error: { message: error instanceof Error ? error.message : String(error), kind: "runtime" } })
-        }
+        ${createEnvironmentExecutionSource(name)}
       },
     })
 `;
 
-const createPluginSource = ({ includeControl, includeWeb, includeMemory }) => {
+
+export const createPluginSource = ({
+  includeControl,
+  includeWeb,
+  includeMemory,
+}) => {
   const entries = [];
   if (includeControl) {
     entries.push(createToolEntry({
@@ -267,15 +277,13 @@ const createPluginSource = ({ includeControl, includeWeb, includeMemory }) => {
     }));
   }
 
-  // The callback carries the per-child token over plain HTTP. With a proxy in
-  // the child's environment, fetch would hand a non-loopback callback, token
-  // included, to that proxy, and no per-request option turns that off. The
-  // exemption is added inside the child because only there is the final
-  // NO_PROXY, merged from the shell and server environments, visible.
-  return `const exemptCallbackFromProxy = () => {
-  const endpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL
-  if (!endpoint || !URL.canParse(endpoint)) return
-  const host = new URL(endpoint).hostname.replace(/^\\[|\\]$/g, "")
+  // The callback carries a bearer token over plain HTTP. With a proxy in the
+  // OpenCode environment, fetch could hand a non-loopback callback and token to
+  // that proxy. Add the callback host to both proxy exemption variables before
+  // a request.
+  return `const exemptCallbackFromProxy = (callbackEndpoint = process.env.OPENCHAMBER_AGENT_TOOL_URL) => {
+  if (!callbackEndpoint || !URL.canParse(callbackEndpoint)) return
+  const host = new URL(callbackEndpoint).hostname.replace(/^\\[|\\]$/g, "")
   for (const key of ["NO_PROXY", "no_proxy"]) {
     const entries = (process.env[key] || "").split(",").map((entry) => entry.trim()).filter(Boolean)
     if (!entries.includes(host)) process.env[key] = [...entries, host].join(",")
@@ -295,7 +303,7 @@ ${entries.join('')}    })
 
 // A configured plugin has to be a directory carrying a package.json that
 // resolves an entrypoint; OpenCode skips a plain .js path.
-const PLUGIN_PACKAGE_JSON = `${JSON.stringify({
+export const AGENT_TOOL_PLUGIN_PACKAGE_JSON = `${JSON.stringify({
   name: 'openchamber-agent-tool',
   version: '0.0.0',
   private: true,
@@ -334,8 +342,12 @@ export const createAgentToolRuntime = (dependencies) => {
       throw new Error('At least one OpenChamber managed tool must be enabled to inject the plugin');
     }
     await fsPromises.mkdir(pluginDirectory, { recursive: true });
-    await fsPromises.writeFile(pluginManifestPath, PLUGIN_PACKAGE_JSON, { mode: 0o600 });
-    await fsPromises.writeFile(pluginPath, createPluginSource({ includeControl, includeWeb, includeMemory }), { mode: 0o600 });
+    await fsPromises.writeFile(pluginManifestPath, AGENT_TOOL_PLUGIN_PACKAGE_JSON, { mode: 0o600 });
+    await fsPromises.writeFile(pluginPath, createPluginSource({
+      includeControl,
+      includeWeb,
+      includeMemory,
+    }), { mode: 0o600 });
     return pluginDirectory;
   };
 
@@ -371,15 +383,21 @@ export const createAgentToolRuntime = (dependencies) => {
     return boundAddress !== null && normalizeAddress(value) === boundAddress;
   };
 
-  const authorize = (req) => {
-    if (!activeToken || !isSameMachineAddress(req.socket?.remoteAddress)) return false;
+  const verifyBearer = (req, token) => {
+    if (!token) return false;
     const header = asNonEmptyString(req.headers?.authorization);
     if (!header?.startsWith('Bearer ')) return false;
     const provided = Buffer.from(header.slice(7));
-    const expected = Buffer.from(activeToken);
+    const expected = Buffer.from(token);
     return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
   };
 
+
+  const authorizeManagedChild = (req) => (
+    isSameMachineAddress(req.socket?.remoteAddress) && verifyBearer(req, activeToken)
+  );
+
+
   const execute = async (payload = {}, options = {}) => {
     const requested = asNonEmptyString(payload.input?.action);
     // Resolved against the calling tool's own actions: models drop the
@@ -455,8 +473,9 @@ export const createAgentToolRuntime = (dependencies) => {
   };
 
   const registerRoutes = (app, express) => {
+
     app.post('/api/openchamber/agent-tool', express.json({ limit: '1mb' }), async (req, res) => {
-      if (!authorize(req)) return res.status(401).json({ error: 'Unauthorized' });
+      if (!authorizeManagedChild(req)) return res.status(401).json({ error: 'Unauthorized' });
       const controller = new AbortController();
       const abortOnDisconnect = () => {
         if (!res.writableEnded) controller.abort();

package/server/lib/agent-tool/runtime.test.js

@@ -445,6 +445,8 @@ describe('managed agent tool runtime', () => {
     expect(response.body).toEqual(expect.objectContaining({ ok: true, action: 'projects.list' }));
   });
 
+
+
   it.each([
     ['0.0.0.0', 'http://127.0.0.1:3901/api/openchamber/agent-tool'],
     ['::', 'http://127.0.0.1:3901/api/openchamber/agent-tool'],

package/server/lib/event-stream/DOCUMENTATION.md

@@ -29,7 +29,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - `serializeMessageStreamWsEvent(payload, options)` and `sendSerializedMessageStreamWsFrame(socket, frame)` separate encoding from per-socket delivery. Delivery retains ready-state and backpressure checks.
 
 ### Runtime helpers
-- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
+- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay. The composition root owns the singleton and stops it during application shutdown; watchers and WebSocket bridges that receive it are borrowers and must not stop it.
 - `createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent })`: returns a broadcaster that fans out the same synthetic UI event to SSE and WS clients.
 - `createMessageStreamWsRuntime(...)`: mounts the message-stream WS server, upgrade handler, and SSE-to-WS bridge onto the web HTTP server.
 
@@ -59,7 +59,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - The hub numbers every event that arrives without an SSE id (`oc-<process>-<sequence>`). OpenCode 1.18 sends no ids at all, and an event without an id used to skip the replay buffer, so reconnecting clients had no cursor and lost whatever fell into the gap. The process prefix makes a cursor from before a server restart miss, which reports `replayReset`, instead of matching an unrelated sequence number.
 - Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
 - If an upstream SSE stream stalls after the browser WS is already ready, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
-- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and can run scoped state repair without requiring the browser WS to close.
+- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and runs its established scoped authoritative repair without requiring the browser WS to close. Shared-service recovery uses this edge rather than manufacturing a server-side interruption. Rebinding retires the old reader generation before starting its replacement, so delayed events, errors, and disconnect completion from the old reader cannot overwrite the replacement's connection state.
 - Health checks are reserved for initial upstream connect failures and explicit upstream-unavailable responses, not for ordinary stall recovery on an already-established stream.
 - Global synthetic events such as `openchamber:session-status`, `openchamber:session-activity`, `openchamber:notification`, and `openchamber:heartbeat` are preserved on the WS path, but heartbeat frames are emitted only while an upstream SSE stream is actively attached.
 - Global UI broadcasts are fan-out capable across both SSE and WS clients.

package/server/lib/event-stream/global-hub.js

@@ -40,9 +40,9 @@ export function createGlobalMessageStreamHub({
 
   let controller = null;
   let reader = null;
+  let readerGeneration = 0;
   let connected = false;
   let everConnected = false;
-  let buildUrlFailed = false;
 
   const notifySubscriber = (kind, subscriber, payload) => {
     try {
@@ -124,8 +124,11 @@ export function createGlobalMessageStreamHub({
     }
 
     controller = new AbortController();
+    const generation = ++readerGeneration;
+    const currentController = controller;
+    let buildUrlFailed = false;
     reader = createUpstreamSseReader({
-      signal: controller.signal,
+      signal: currentController.signal,
       stallTimeoutMs: upstreamStallTimeoutMs,
       reconnectDelayMs: upstreamReconnectDelayMs,
       fetchImpl,
@@ -140,20 +143,23 @@ export function createGlobalMessageStreamHub({
       },
       getHeaders: getOpenCodeAuthHeaders,
       onConnect() {
+        if (generation !== readerGeneration) return;
         connected = true;
         const wasReady = everConnected;
         everConnected = true;
         notifyStatus({ type: 'connect', wasReady });
       },
       onDisconnect({ reason }) {
+        if (generation !== readerGeneration) return;
         connected = false;
         notifyStatus({ type: 'disconnect', reason });
       },
       onEvent(event) {
+        if (generation !== readerGeneration) return;
         coalescer.push(event);
       },
       onError(error) {
-        if (controller?.signal.aborted) {
+        if (generation !== readerGeneration || currentController.signal.aborted) {
           return;
         }
 
@@ -168,8 +174,9 @@ export function createGlobalMessageStreamHub({
     void reader.start();
   };
 
-  const stop = () => {
+  const stopReader = ({ resetConnectionHistory }) => {
     connected = false;
+    readerGeneration += 1;
     // Text that already arrived belongs in the retained replay suffix.
     coalescer.flush();
     reader?.stop();
@@ -178,13 +185,22 @@ export function createGlobalMessageStreamHub({
     }
     reader = null;
     controller = null;
-    everConnected = false;
-    buildUrlFailed = false;
+    if (resetConnectionHistory) {
+      everConnected = false;
+    }
+  };
+
+  const stop = () => {
+    stopReader({ resetConnectionHistory: true });
   };
 
   return {
     start,
     stop,
+    rebind() {
+      stopReader({ resetConnectionHistory: false });
+      start();
+    },
     isConnected() {
       return connected;
     },

package/server/lib/event-stream/global-hub.test.js

@@ -25,7 +25,7 @@ it('bounds a contiguous replay suffix by UTF-8 bytes and event count', async ()
   } finally { hub.stop(); }
 });
 
-function createSseResponse({ blocks = [] } = {}) {
+function createSseResponse({ blocks = [], signal, holdOpen = false } = {}) {
   const encoder = new TextEncoder();
   let index = 0;
 
@@ -38,7 +38,18 @@ function createSseResponse({ blocks = [] } = {}) {
             if (index < blocks.length) {
               return { value: encoder.encode(blocks[index++]), done: false };
             }
-            return { value: undefined, done: true };
+            if (!holdOpen) {
+              return { value: undefined, done: true };
+            }
+            return new Promise((_resolve, reject) => {
+              const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                const error = new Error('Aborted');
+                error.name = 'AbortError';
+                reject(error);
+              };
+              signal.addEventListener('abort', onAbort, { once: true });
+            });
           },
         };
       },
@@ -224,6 +235,86 @@ describe('delta coalescing in the global hub', () => {
 });
 
 describe('createGlobalMessageStreamHub', () => {
+  it('uses the replacement service endpoint and auth after rebind', async () => {
+    let generation = 0;
+    const urls = ['http://127.0.0.1:4096/api/event', 'http://127.0.0.1:5096/api/event'];
+    const auth = ['Basic first', 'Basic second'];
+    const fetchImpl = vi.fn(async (_url, options) => createSseResponse({
+      signal: options.signal,
+      holdOpen: true,
+    }));
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: () => urls[generation],
+      getOpenCodeAuthHeaders: () => ({ Authorization: auth[generation] }),
+      fetchImpl,
+      upstreamReconnectDelayMs: 60_000,
+    });
+
+    try {
+      hub.start();
+      await waitForAssertion(() => expect(fetchImpl).toHaveBeenCalledTimes(1));
+
+      generation = 1;
+      hub.rebind();
+
+      await waitForAssertion(() => expect(fetchImpl).toHaveBeenCalledTimes(2));
+      expect(fetchImpl).toHaveBeenLastCalledWith(urls[1], expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: auth[1] }),
+      }));
+    } finally {
+      hub.stop();
+    }
+  });
+
+  it('ignores a retired reader disconnect that completes after its replacement connects', async () => {
+    let finishRetiredRead;
+    let fetchCount = 0;
+    const statuses = [];
+    const fetchImpl = vi.fn(async (_url, options) => {
+      fetchCount += 1;
+      if (fetchCount === 1) {
+        return {
+          ok: true,
+          body: {
+            getReader() {
+              return {
+                read() {
+                  return new Promise((resolve) => {
+                    finishRetiredRead = () => resolve({ value: undefined, done: true });
+                  });
+                },
+              };
+            },
+          },
+        };
+      }
+      return createSseResponse({ signal: options.signal, holdOpen: true });
+    });
+    const hub = createGlobalMessageStreamHub({
+      buildOpenCodeUrl: (pathname) => `http://127.0.0.1:4096${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      fetchImpl,
+      upstreamReconnectDelayMs: 60_000,
+    });
+    hub.subscribeStatus((status) => statuses.push(status.type));
+
+    try {
+      hub.start();
+      await waitForAssertion(() => expect(statuses).toEqual(['connect']));
+
+      hub.rebind();
+      await waitForAssertion(() => expect(statuses).toEqual(['connect', 'connect']));
+      expect(hub.isConnected()).toBe(true);
+
+      finishRetiredRead();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(statuses).toEqual(['connect', 'connect']);
+      expect(hub.isConnected()).toBe(true);
+    } finally {
+      hub.stop();
+    }
+  });
+
   it('continues fanout when an event subscriber throws', async () => {
     const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const received = [];

package/server/lib/event-stream/rebind.test.js

@@ -132,6 +132,7 @@ describe('rebindUpstream (#2638)', () => {
     expect(fetchCalls).toBe(2);
     expect(fetchImpl.mock.calls[1][0]).toContain(':5000/api/event');
     expect(socket.sent.some((frame) => frame.type === 'event' && frame.eventId === 'evt-2')).toBe(true);
+    expect(socket.sent.filter((frame) => frame.type === 'ready' && frame.scope === 'global')).toHaveLength(2);
 
     socket.close();
     await runtime.close();

package/server/lib/event-stream/runtime.js

@@ -182,8 +182,7 @@ export function createMessageStreamWsRuntime({
      * `Last-Event-ID` and re-establish the stream against the new port.
      */
     rebindUpstream() {
-      globalHub.stop();
-      globalHub.start();
+      globalHub.rebind();
       for (const socket of Array.from(directorySockets)) {
         try {
           socket.close(1012, 'OpenCode upstream restarted');

package/server/lib/opencode/DOCUMENTATION.md

@@ -11,13 +11,14 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/v1-migration-topup.js`: re-arms OpenCode's own V1 -> V2 session import for V1 sessions created after that migration already completed; runs only before a managed spawn. See "v1-migration-topup.js" below.
-- `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). After readiness it warms the most recently used directories (`getWarmupDirectories` dep, sequential and best-effort) because OpenCode initializes each directory lazily on first request and that cost would otherwise be paid by the user's first interactive session open.
+- `packages/web/server/lib/opencode/lifecycle.js`: OpenCode connection policy and the managed process lifecycle runtime. The composition helper selects `explicit-external` when `OPENCODE_HOST` is configured, `managed-owned` for Desktop, and `shared-local` for ordinary Web. The managed path still owns startup, restart, readiness, health monitoring, orphan reaping, credentials, and V1 migration top-up. After readiness it warms the most recently used directories (`getWarmupDirectories` dep, sequential and best-effort) because OpenCode initializes each directory lazily on first request and that cost would otherwise be paid by the user's first interactive session open.
 - `packages/web/server/lib/opencode/provider-env-aliases.js`: mirrors known provider credential env aliases into the managed OpenCode process environment (for example `GEMINI_API_KEY` → `GOOGLE_GENERATIVE_AI_API_KEY`) so OpenCode connection detection and the upstream AI SDK agree on the same key names. Canonical implementation shared by web lifecycle and the VS Code managed spawn path (`packages/vscode/src/provider-env-aliases.ts` re-exports this module).
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
 - `packages/web/server/lib/opencode/env-config.js`: OpenCode-related environment variable parsing and validation (host/port/hostname).
 - `packages/web/server/lib/opencode/hmr-state-runtime.js`: HMR-persistent runtime state initialization, auth-state bootstrap, and HMR sync helpers.
 - `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
-- `packages/web/server/lib/opencode/network-runtime.js`: OpenCode URL construction, health-probe readiness checks, and API prefix runtime.
+- `packages/web/server/lib/opencode/network-runtime.js`: OpenCode URL construction, health-probe readiness checks, and API prefix runtime. URL and service headers are resolved for every request so shared-service endpoint or credential rotation is immediate; lowercase service `authorization` is normalized to `Authorization` while other service headers are preserved.
+- `packages/web/server/lib/opencode/shared-service-runtime.js`: discovery-first connection used by ordinary Web when no explicit `OPENCODE_HOST` is configured. It probes `/api/info` before accepting an endpoint, refuses to replace an incompatible discovered service, and never owns or stops the shared process. Because the pinned client's discovery hides incompatible and unhealthy registrations, Web checks that the registration file is genuinely absent before calling its destructive `ensure`; an existing hidden registration fails startup untouched. Shared restart and health controls recover the connection, then rebind live event readers so their established reconnect edge repairs authoritative client state without synthetic interruption. Desktop does not instantiate this runtime.
 - `packages/web/server/lib/opencode/project-directory-runtime.js`: request-scoped and settings-backed project directory resolution/validation runtime.
 - `packages/web/server/lib/opencode/config-entity-routes.js`: route registration for agent/command/MCP config orchestration. OpenCode 2 watches these files, so a write is live as soon as it lands and the route answers plain success.
 - `packages/web/server/lib/opencode/websearch-config.js`: writes OpenCode's `websearch` choice (`PUT /api/config/websearch` in `routes.js`; body `{ selection: false | null | "random" | "<provider id>" }`, `null` removes the key, so OpenCode falls back to the answer given in its chat consent form, which it keeps in its own store) to `OPENCODE_CONFIG` when set, else the user config. `GET /api/config/websearch` returns `{ projectPath }`: the project config whose `websearch` overrides that write (OpenCode merges user < project < `OPENCODE_CONFIG`), so Settings disables the choice and names the file instead of letting it snap back; `findWebSearchProjectOverride` in `config-v2.js` holds the rule. The pure transform is `writeWebSearchSelection` in `config-v2.js`, shared with the VS Code bridge (`api:config/websearch`).
@@ -25,18 +26,18 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/snippets.js`: opencode-snippets-compatible snippet file CRUD, discovery, and hashtag expansion.
 - `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
 - `packages/web/server/lib/opencode/core-routes.js`: server status/system routes, auth/access guard routes, and settings utility route registration.
-- `packages/web/server/lib/opencode/shutdown-runtime.js`: graceful shutdown orchestration runtime for watcher/session/guest-services/terminal/process/server teardown.
-- `packages/web/server/lib/opencode/server-startup-runtime.js`: server listen/startup tunnel flow and process/signal handler orchestration runtime.
-- `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring.
-- `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
-- `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot runtime for settings routes and diagnostics.
-- `packages/web/server/lib/opencode/upgrade-capability.js`: authoritative upgrade ownership policy for the active OpenCode runtime. Bundled, external, and unresolved runtimes fail closed; only managed non-bundled runtimes delegate upgrades to OpenCode.
-- `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/shutdown-runtime.js`: graceful shutdown orchestration. Only `managed-owned` may close an OpenCode child, kill by port, or wait for port release. Shared and external connections dispose local state only.
+- `packages/web/server/lib/opencode/server-startup-runtime.js`: server listen, startup tunnel flow, and process or signal handler orchestration.
+- `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset and SPA fallback route registration.
+- `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition for dynamic route modules.
+- `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot for settings routes and diagnostics.
+- `packages/web/server/lib/opencode/upgrade-capability.js`: upgrade ownership policy. Bundled, external, and unresolved runtimes fail closed; only managed non-bundled runtimes delegate upgrades to OpenCode.
+- `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: tunnel service and active-port wiring.
+- `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: terminal, proxy, static route, and listen orchestration. Shared Web starts no managed-tool installation or registration step.
 - `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, same-machine authentication (loopback, or the bound address for a concrete bind), and fixed CLI action dispatch.
-- `packages/web/server/lib/opencode/managed-plugin-config.js`: the `OPENCODE_CONFIG_CONTENT` merge used only on the fallback path, when the user's own environment owns `OPENCODE_CONFIG`.
-- `packages/web/server/lib/opencode/managed-config-file.js`: the managed OpenCode config layer — materializes the enabled OpenChamber plugins (agent tools, system prompt optimizer) and publishes them in a file OpenCode watches.
+- `packages/web/server/lib/agent-tool/runtime.js`: Desktop's custom-tool schema and source generation, managed plugin materialization, environment injection, same-machine authentication, and fixed action dispatch.
+- `packages/web/server/lib/opencode/managed-plugin-config.js`: the `OPENCODE_CONFIG_CONTENT` merge used only when the user's environment owns `OPENCODE_CONFIG`.
+- `packages/web/server/lib/opencode/managed-config-file.js`: Desktop's managed OpenCode config layer for environment-backed OpenChamber tools and the system prompt optimizer.
 
 ### Managed plugins on OpenCode 2.x
 A configured plugin must be a DIRECTORY holding a `package.json` that resolves an
@@ -296,7 +297,8 @@ Installer output is discarded, not forwarded to clients or logs.
 The runtime maintains active-session count incrementally from idempotent activity phase transitions. Upstream stall-timeout and lifecycle health checks read it in O(1); the hourly cleanup removes activity phases older than 24 hours without broadcasting synthetic state transitions. Snapshot generation remains reserved for the session-activity API.
 
 ## Public exports (lifecycle.js)
-- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration. The optional `onOpenCodeRestarted` dependency (default `null`) is fired after a successful managed restart. `index.js` rebinds event-stream readers to the possibly-new port (#2638), then calls `interruptBusySessionsAfterRestart()` and broadcasts one `opencode-restart-interrupted` UI notification when interrupted turns exist (#2943).
+- `createOpenCodeRecoveryCallbacks(dependencies)`: composes the production recovery callbacks used by `index.js`. Managed restart resets providers, rebinds event readers, calls `interruptBusySessionsAfterRestart()`, and broadcasts the existing interruption notification. Shared recovery resets providers and rebinds readers only, leaving authoritative browser reconnect repair to the existing second `ready` edge.
+- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration. The optional `onOpenCodeRestarted` dependency (default `null`) is fired after a successful managed restart. `index.js` supplies the managed callback above.
 - Returned API:
   - `startOpenCode()`
   - `restartOpenCode()`
@@ -396,7 +398,7 @@ ConPTY or Console Window Host behavior.
   - `setupBaseRoutes(app, options)`
 
 ## Public exports (network-runtime.js)
-- `createOpenCodeNetworkRuntime(dependencies)`: creates runtime for OpenCode network and URL concerns.
+- `createOpenCodeNetworkRuntime(dependencies)`: creates runtime for OpenCode network and URL concerns. `getOpenCodeBaseUrl` and `getOpenCodeAuthHeaders` are read at call time; credentials remain request headers and never enter generated URLs.
 - Returned API:
   - `waitForReady(url, timeoutMs?)`
   - `normalizeApiPrefix(prefix)`
@@ -751,15 +753,15 @@ headers }` or v1 `{ npm, options }`. The stored entry is always a
   - `setupProxy(app)`
 
 ## Public exports (shutdown-runtime.js)
-- `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown runtime for managed OpenCode and web server teardown sequencing.
-- Daemon signals, `POST /api/system/shutdown`, and embedded `stop()` share one shutdown promise. Guest admission closes synchronously before any await. Cleanup stops the relay reconciliation timer, guest viewers, realtime proxy, relay host, dictation worker and session runtimes before draining guest services, including pending starts. Each cleanup is best-effort and runs once per shutdown, including after partial startup. A hard kill still requires the separate crash/SIGKILL recovery work; no persistent registry or boot reaper is provided here.
-- Register TCP connection tracking before the HTTP server starts listening. After stopping owned runtimes and OpenCode, HTTP shutdown closes the listener and all remaining sockets, including WebSocket upgrades and unanswered upgrade requests accepted during cleanup. This prevents client reconnects from holding Desktop open until the HTTP close deadline. Each runtime still owns its protocol cleanup; socket teardown runs afterwards and preserves the existing terminal and process grace periods.
+- `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown for Web-owned resources and explicit OpenCode process ownership.
+- Daemon signals, `POST /api/system/shutdown`, and embedded `stop()` share one shutdown promise. Guest admission closes before asynchronous cleanup. Each cleanup is best-effort and runs once, including after partial startup. The application-owned global event hub is stopped here after its watcher, so embedded shutdown aborts the upstream event fetch and reconnect loop; watcher and WebSocket bridges do not stop injected hubs.
+- Only `managed-owned` may close the OpenCode child, kill by port, or wait for port release. `shared-local` disposes only local connection state. `explicit-external` performs no OpenCode process teardown. TCP connection tracking closes the Web listener and remaining sockets after owned runtimes stop, while shared or external OpenCode and TUI work continue.
 - Returned API:
   - `gracefulShutdown(options?)`
   - `trackServerConnections(server)`: call once before listening; closed sockets leave the tracking set, and the server close event removes the connection listener.
 
 ## Public exports (server-startup-runtime.js)
-- `createServerStartupRuntime(dependencies)`: creates runtime for server bind/startup tunnel and process handler wiring.
+- `createServerStartupRuntime(dependencies)`: creates runtime for server bind/startup tunnel and process handler wiring. Daemon readiness is emitted only after listener-dependent startup completes. A startup failure sends `openchamber:error`, closes the listener and accepted connections, and rejects startup without a ready event.
 - Returned API:
   - `resolveBindHost(host)`
   - `startListeningAndMaybeTunnel(options)`
@@ -786,13 +788,11 @@ headers }` or v1 `{ npm, options }`. The stored entry is always a
   - `initialize(app, initialPort, hasUiPassword)`
 
 ## Public exports (startup-pipeline-runtime.js)
-- `createStartupPipelineRuntime(dependencies)`: creates runtime for terminal wiring, proxy/bootstrap scheduling, static route registration, and server startup/listen flow.
+- `createStartupPipelineRuntime(dependencies)`: creates terminal, proxy, static route, and server listen orchestration.
 - Returned API:
   - `run(options)`
 
-The pipeline binds the OpenChamber listener and publishes its active port
-before starting managed OpenCode. The managed custom tool therefore receives
-an authoritative loopback callback URL even when OpenChamber binds port `0`.
+The pipeline publishes the listener port before bootstrapping OpenCode, then waits for connection authentication and version validation before daemon readiness. Desktop's generated custom tool therefore receives the correct loopback callback URL even when OpenChamber binds port `0`, while ordinary Web cannot advertise readiness with an unusable shared service. Shared Web does not install a plugin or publish callback registration.
 
 ## Public exports (openchamber-routes.js)
 Browser completion checks use `appType=web&updateStatus=true` to stay on the