@aiworker/web 1.22.2 → 1.23.1

package/server/lib/inherited-env.js

@@ -12,7 +12,9 @@
 import { createRequire } from 'node:module';
 import { existsSync } from 'node:fs';
 
-const LINUX_ENV_BINARIES = ['/usr/bin/env', '/bin/env'];
+const POSIX_ENV_BINARIES = ['/usr/bin/env', '/bin/env'];
+/** Variables a PTY shell must never inherit from the AiWorker host process. */
+const PTY_HOST_PRIVATE_VARIABLES = Object.freeze(['ARGV0', 'NODE_CHANNEL_FD']);
 
 /**
  * Remove AppImage `ARGV0` from a mutable env object (or `process.env`).
@@ -49,26 +51,31 @@ export function clearAppImageArgv0FromProcessEnv() {
 }
 
 /**
- * Resolve a Linux PTY launch that drops native `ARGV0` before the shell starts.
+ * Resolve a POSIX PTY launch that unsets host-private variables before the
+ * shell starts.
  *
- * `bun-pty` merges the OS environ into the child, so deleting `ARGV0` from the
- * JS env object alone is not enough. Wrapping with `env -u ARGV0` unsets it
- * before execing the real shell. No-op on non-Linux platforms.
+ * `bun-pty` merges the OS environ into the child, so deleting a variable from
+ * the JS env object alone is not enough: AppImage `ARGV0` came back on Linux,
+ * and the daemon's `NODE_CHANNEL_FD` came back everywhere (Node then warns
+ * "Failed to parse IPC channel number" when a CLI such as opencode exits).
+ * Wrapping with `env -u NAME ...` unsets them before execing the real shell.
+ * No-op on Windows and when no `env` binary is found.
  *
  * @param {string} executable
  * @param {string[]} args
+ * @param {readonly string[]} variables
  * @returns {{ executable: string, args: string[] }}
  */
-export function resolveLinuxPtyLaunch(executable, args = []) {
-  if (process.platform !== 'linux') {
+export function resolvePosixPtyLaunch(executable, args = [], variables = PTY_HOST_PRIVATE_VARIABLES) {
+  if (process.platform === 'win32' || variables.length === 0) {
     return { executable, args };
   }
-  const envBinary = LINUX_ENV_BINARIES.find((candidate) => existsSync(candidate));
+  const envBinary = POSIX_ENV_BINARIES.find((candidate) => existsSync(candidate));
   if (!envBinary) {
     return { executable, args };
   }
   return {
     executable: envBinary,
-    args: ['-u', 'ARGV0', executable, ...args],
+    args: [...variables.flatMap((name) => ['-u', name]), executable, ...args],
   };
 }

package/server/lib/inherited-env.test.js

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import {
   clearAppImageArgv0FromProcessEnv,
-  resolveLinuxPtyLaunch,
+  resolvePosixPtyLaunch,
   stripAppImageArgv0Leak,
 } from './inherited-env.js';
 
@@ -46,18 +46,17 @@ describe('clearAppImageArgv0FromProcessEnv', () => {
   });
 });
 
-describe('resolveLinuxPtyLaunch', () => {
-  it('wraps the shell with env -u ARGV0 on Linux', () => {
-    if (process.platform !== 'linux') return;
-    expect(resolveLinuxPtyLaunch('/bin/zsh', ['-l'])).toEqual({
+describe('resolvePosixPtyLaunch', () => {
+  it('wraps the shell with env -u for every host-private variable on POSIX', () => {
+    if (process.platform === 'win32') return;
+    expect(resolvePosixPtyLaunch('/bin/zsh', ['-l'])).toEqual({
       executable: expect.stringMatching(/\/env$/),
-      args: ['-u', 'ARGV0', '/bin/zsh', '-l'],
+      args: ['-u', 'ARGV0', '-u', 'NODE_CHANNEL_FD', '/bin/zsh', '-l'],
     });
   });
 
-  it('leaves non-Linux launches unchanged', () => {
-    if (process.platform === 'linux') return;
-    expect(resolveLinuxPtyLaunch('/bin/zsh', ['-l'])).toEqual({
+  it('leaves the launch unchanged with nothing to unset', () => {
+    expect(resolvePosixPtyLaunch('/bin/zsh', ['-l'], [])).toEqual({
       executable: '/bin/zsh',
       args: ['-l'],
     });

package/server/lib/message-queue/DOCUMENTATION.md

@@ -31,6 +31,7 @@ send never re-resolves mutable UI state:
 {
   id, createdAt,
   content,        // raw text for display and editing
+  contextPreview?, // bounded display-only summary captured by the UI
   text,           // text to deliver (agent mention stripped, file mentions resolved); defaults to content
   agentMention?,  // delivered as an `agent` part
   attachments: [{ id, filename, mimeType, size, source, serverPath?, dataUrl }],
@@ -56,6 +57,12 @@ context entry). Public snapshots and broadcasts strip the payloads —
 attachment `dataUrl` (megabytes of base64) and `context` (a PR diff, say) —
 so they do not ride every update; the only way to get them back is a `take`.
 
+Snapshots retain `contextPreview`, capped at 100 characters plus an ellipsis.
+It carries the attached comment or context label when `content` is empty and
+never replaces editable text or delivered parts. Older items without a summary
+derive one from the attached comment metadata or the first non-instruction
+context text. This optional field needs no queue-file migration.
+
 ## Persistence
 
 `<data-dir>/message-queue.json` (`AIWORKER_DATA_DIR` or
@@ -140,7 +147,10 @@ allowlists.
 
 Every mutation broadcasts `aiworker:message-queue.updated` with
 `{ revision, session }` to all connected clients (SSE and WS), so several
-devices on one server see one queue. The session in that payload always names
+devices on one server see one queue. SSE uses the shared control stream at
+`/api/openchamber/events`; `/api/global/event` carries no AiWorker events.
+The UI subscribes independently of its OpenCode transport and re-reads the
+snapshot whenever either stream reconnects. The session in that payload always names
 its `directory`, including the broadcast that removes the last item: the UI
 keys its projection by directory, and a broadcast without one left the
 delivered message on screen (a session's directory is remembered until the

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

@@ -133,6 +133,8 @@ export const parseQueuedItemInput = (value) => {
   if (agentMention) item.agentMention = agentMention;
   item.attachments = attachments;
   item.context = context;
+  const contextPreview = asNonEmptyString(raw.contextPreview).slice(0, 103);
+  if (contextPreview) item.contextPreview = contextPreview;
   item.sendConfig = sendConfig;
   return item;
 };
@@ -157,6 +159,17 @@ const toPublicItem = (item) => {
   const publicItem = { id: item.id, createdAt: item.createdAt, content: item.content, text: item.text };
   if (item.agentMention) publicItem.agentMention = item.agentMention;
   publicItem.attachments = item.attachments.map(toPublicAttachment);
+  // Older persisted items have no UI summary. Prefer their attached comment
+  // before falling back to the model-facing context text.
+  const contextPreview = item.contextPreview || item.context
+    .filter((part) => part.kind !== 'instruction')
+    .map((part) => asNonEmptyString(asRecord(part.metadata?.aiworkerContext)?.text) || part.text.trim())
+    .find(Boolean);
+  if (contextPreview) {
+    const firstLine = contextPreview.split('\n', 1)[0];
+    publicItem.contextPreview = firstLine.slice(0, 100)
+      + (contextPreview.length > firstLine.length || firstLine.length > 100 ? '...' : '');
+  }
   publicItem.sendConfig = { ...item.sendConfig };
   return publicItem;
 };

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

@@ -251,7 +251,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 +259,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 +316,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: { aiworkerContext: { 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: { aiworkerContext: { 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/network-defaults.js

@@ -0,0 +1,23 @@
+import net from 'node:net';
+
+// Node caps each happy-eyeballs connect attempt at 250ms by default
+// (autoSelectFamilyAttemptTimeout). TCP handshakes to provider endpoints that are
+// geographically distant routinely take 300-1500ms, so fetch() from a Node process
+// aborts every attempt (ETIMEDOUT) and surfaces "fetch failed" even though the host
+// is reachable — e.g. the z.ai quota endpoint from an IPv4-only egress (#3399).
+//
+// Every Node process entrypoint that performs provider fetches raises the
+// per-attempt cap. Family autoselection itself stays enabled, so the IPv6→IPv4
+// fallback and ::1/localhost servers keep working; disabling it instead breaks
+// local MCP servers. Runtimes without the setter (Bun's fetch path, older Node)
+// are a no-op.
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 5_000;
+
+export const applyConnectAttemptTimeout = (netModule = net) => {
+  try {
+    netModule.setDefaultAutoSelectFamilyAttemptTimeout(CONNECT_ATTEMPT_TIMEOUT_MS);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/server/lib/network-defaults.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest';
+import net from 'node:net';
+import { spawnSync } from 'node:child_process';
+
+import { applyConnectAttemptTimeout, CONNECT_ATTEMPT_TIMEOUT_MS } from './network-defaults.js';
+
+describe('applyConnectAttemptTimeout', () => {
+  it('initializes the server entrypoint in a fresh Node process', () => {
+    const serverUrl = new URL('../index.js', import.meta.url).href;
+    const result = spawnSync('node', ['--input-type=module', '--eval', `
+      import net from 'node:net';
+      import assert from 'node:assert/strict';
+      const family = net.getDefaultAutoSelectFamily();
+      net.setDefaultAutoSelectFamilyAttemptTimeout(250);
+      await import(${JSON.stringify(serverUrl)});
+      assert.equal(net.getDefaultAutoSelectFamilyAttemptTimeout(), 5000);
+      assert.equal(net.getDefaultAutoSelectFamily(), family);
+      process.exit(0);
+    `], { encoding: 'utf8', timeout: 15_000, windowsHide: true });
+    expect(result.status, result.stderr).toBe(0);
+  });
+
+  it('raises the per-attempt connect timeout on runtimes that expose the setter', () => {
+    const previous = net.getDefaultAutoSelectFamilyAttemptTimeout();
+    try {
+      expect(applyConnectAttemptTimeout()).toBe(true);
+      expect(net.getDefaultAutoSelectFamilyAttemptTimeout()).toBe(CONNECT_ATTEMPT_TIMEOUT_MS);
+    } finally {
+      net.setDefaultAutoSelectFamilyAttemptTimeout(previous);
+    }
+  });
+
+  it('is a no-op on runtimes without the setter', () => {
+    expect(applyConnectAttemptTimeout({})).toBe(false);
+  });
+
+  it('survives a throwing setter', () => {
+    const setDefaultAutoSelectFamilyAttemptTimeout = vi.fn(() => {
+      throw new Error('not supported');
+    });
+    expect(applyConnectAttemptTimeout({ setDefaultAutoSelectFamilyAttemptTimeout })).toBe(false);
+  });
+
+  it('leaves family autoselection itself untouched', () => {
+    const setDefaultAutoSelectFamily = vi.fn();
+    const setDefaultAutoSelectFamilyAttemptTimeout = vi.fn();
+    applyConnectAttemptTimeout({ setDefaultAutoSelectFamily, setDefaultAutoSelectFamilyAttemptTimeout });
+    expect(setDefaultAutoSelectFamilyAttemptTimeout).toHaveBeenCalledTimes(1);
+    expect(setDefaultAutoSelectFamilyAttemptTimeout).toHaveBeenCalledWith(CONNECT_ATTEMPT_TIMEOUT_MS);
+    expect(setDefaultAutoSelectFamily).not.toHaveBeenCalled();
+  });
+});

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/opencode/DOCUMENTATION.md

@@ -34,8 +34,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `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/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`: AiWorker 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.
@@ -132,8 +131,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. AiWorker 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
 AiWorker tool injection. Managed launch env strips AppImage `ARGV0` before
 spawn so zsh-backed OpenCode tools do not rewrite child argv[0] to the AppImage
@@ -156,6 +159,7 @@ Managed health failures are classified as `timeout`, `connection_refused`, `conn
 ## 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 `AIWORKER_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()`
@@ -212,7 +216,12 @@ Managed health failures are classified as `timeout`, `connection_refused`, `conn
   - `persistSettings(changes)`
 - Persistent permission auto-accept policy is stored under `permissionAutoAccept`; execution ownership lives in `lib/permission-auto-accept/`.
 - Queued follow-up messages live in `<data-dir>/message-queue.json`, not in settings; execution ownership lives in `lib/message-queue/`.
-- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter `settings.json`.
+- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter either settings file.
+- Two files (`settings-files.js`): `settings.json` holds instance facts and any legacy or unknown keys; `preferences.json` beside it holds every key the generated registry snapshot (`settings-registry.json`) marks `profile`, as `{ version: 1, fields: { key: { value, updatedAt, surfaces? } } }`. Keys the snapshot marks `perSurface` are stored per surface kind: `GET`/`PUT /api/config/settings` read the client's kind from the `surface` query parameter (`settingsSurfaceOf`; the legacy `x-openchamber-surface` header is still honoured, but a header forces a CORS preflight that cross-origin shells and older instances refuse, so clients must not send one) (`web`, `desktop`, `vscode`, `mobile`; anything else means base), `persistSettings(changes, { surface })` writes a changed per-surface key under `surfaces[surface]` and never touches its base, and `readSettingsFromDisk({ surface })` resolves that kind's value first, the base otherwise. Callers without a surface (migrations, the seed, server-side feature writers) read and write the base. `readSettingsFromDisk()` returns the merged document and seeds `preferences.json` once from an existing `settings.json` (which it leaves intact). An existing `preferences.json` that fails to parse is a failure, not an empty profile: it is never seeded or overwritten, the merged read serves the instance part, and `persistSettings` drops profile keys with a warning until the file is fixed or removed. `writeSettingsToDisk(document)` splits by scope and writes `settings.json` as the instance part plus a copy of the profile's base values (`legacySettingsDocumentOf`): a build from before the split reads only that file, so a rollback keeps the user's preferences, while current builds ignore the copy because `preferences.json` wins in the merge; device keys are dropped from writes. Modules that read one profile key off the disk on a hot path use `readMergedSettingsSync`.
+
+## Public exports (settings-files.js)
+- `parsePreferencesDocument(raw)`, `serializePreferencesDocument(fields)`, `flattenPreferences(fields)`, `buildPreferencesFields(previousFields, document, now)`, `instancePartOf(document)`, `seedPreferencesFrom(document, now)`, `readMergedSettingsSync({ fs, path, settingsFilePath })`, `getSettingsScope(key)`, `isProfileSettingsKey(key)`, `isDeviceSettingsKey(key)`, `preferencesFilePathFor(settingsFilePath, path)`.
+- The VS Code extension host writes the same two files with the same shape (`packages/vscode/src/settings-files.ts`); format changes go to both.
 
 ## Public exports (settings-helpers.js)
 - `createSettingsHelpers(dependencies)`: creates settings helper runtime for settings request/response shaping.
@@ -363,9 +372,20 @@ before starting managed OpenCode. The managed custom tool therefore receives
 an authoritative loopback callback URL even when AiWorker binds port `0`.
 
 ## Public exports (openchamber-routes.js)
+Browser completion checks use `appType=web&updateStatus=true` to stay on the
+Desktop Host's native updater. A rejected native restart is retained in the
+server process and returned to these polls as `DESKTOP_UPDATE_RESTART_FAILED`;
+ordinary availability checks remain usable so a browser reload can offer a
+retry. Starting another installation clears the previous restart error.
+The shared UI's `lib/web-update.ts` parses install/check responses and waits
+for the installed native target version, rather than treating absence of a
+newer release as installation success. Poll requests have individual deadlines
+within a ten-minute overall deadline.
+
 - `registerAiWorkerRoutes(app, dependencies)`: registers AiWorker endpoints:
   - `GET /api/openchamber/update-check`
   - `POST /api/openchamber/update-install`
+    - Desktop-managed hosts delegate authenticated Web update requests to the Electron main process, which checks, downloads, and applies the update through `electron-updater` before restarting the host.
     - Foreground servers running under a systemd user unit queue installation in
       a separate transient unit and restart the configured service afterwards.
       `AIWORKER_SYSTEMD_UNIT` overrides the default `aiworker.service`.
@@ -406,6 +426,16 @@ an authoritative loopback callback URL even when AiWorker binds port `0`.
   - 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

@@ -63,6 +63,7 @@ export const createBootstrapRuntime = (dependencies) => {
       getCachedZenModels,
       setAutoAcceptSession,
       agentToolRuntime,
+      desktopUpdater,
     } = options;
 
     const uiAuthController = createUiAuth({
@@ -153,6 +154,7 @@ export const createBootstrapRuntime = (dependencies) => {
       readSettingsFromDiskMigrated,
       fetchFreeZenModels,
       getCachedZenModels,
+      desktopUpdater,
     });
 
     return {

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

@@ -1110,7 +1110,11 @@ export const createOpenCodeEnvRuntime = (deps) => {
         return resolved;
       }
 
-      process.env.OPENCODE_BINARY = resolved;
+      // AppImage updates inherit process.env. Keep automatic desktop bundle
+      // selection local so the next app does not treat the old mount as an override.
+      if (process.env.AIWORKER_RUNTIME !== 'desktop' || state.resolvedOpencodeBinarySource !== 'bundled') {
+        process.env.OPENCODE_BINARY = resolved;
+      }
       prependToPath(path.dirname(resolved));
       ensureOpencodeShimRuntime(resolved);
       state.resolvedOpencodeBinary = resolved;

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

@@ -14,6 +14,7 @@ const originalResourcesPath = process.resourcesPath;
 const originalWslBinary = process.env.WSL_BINARY;
 const originalAiWorkerWslBinary = process.env.AIWORKER_WSL_BINARY;
 const originalPlatform = process.platform;
+const originalRuntime = process.env.AIWORKER_RUNTIME;
 const tempDirs = [];
 const itIf = (condition) => condition ? it : it.skip;
 
@@ -30,6 +31,8 @@ const setPlatform = (platform) => {
 };
 
 afterEach(() => {
+  if (originalRuntime === undefined) delete process.env.AIWORKER_RUNTIME;
+  else process.env.AIWORKER_RUNTIME = originalRuntime;
   Object.defineProperty(process, 'platform', {
     value: originalPlatform,
   });
@@ -117,7 +120,76 @@ const createRuntime = (settings, options = {}) => {
   return { runtime, state };
 };
 
+const createBundledCli = () => {
+  const resourcesPath = createTempDir('openchamber-resources-');
+  const directory = path.join(resourcesPath, 'opencode-cli');
+  fs.mkdirSync(directory);
+  const binary = path.join(directory, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+  fs.writeFileSync(binary, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+  Object.defineProperty(process, 'resourcesPath', { configurable: true, value: resourcesPath });
+  return binary;
+};
+
 describe('OpenCode env runtime', () => {
+  it.each(['linux', 'darwin', 'win32'])('keeps automatic desktop bundled resolution local across relaunch on %s', (platform) => {
+    setPlatform(platform);
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+
+    const oldBinary = createBundledCli();
+    const oldRuntime = createRuntime({});
+    expect(oldRuntime.runtime.ensureOpencodeCliEnv()).toBe(oldBinary);
+    expect(oldRuntime.runtime.ensureOpencodeCliEnv()).toBe(oldBinary);
+    expect(oldRuntime.state.resolvedOpencodeBinarySource).toBe('bundled');
+    expect(process.env.OPENCODE_BINARY).toBeUndefined();
+    expect(process.env.PATH.split(path.delimiter)[0]).toBe(path.dirname(oldBinary));
+
+    // The old binary remains executable and its directory is still in PATH.
+    const newBinary = createBundledCli();
+    const newRuntime = createRuntime({});
+    expect(newRuntime.runtime.ensureOpencodeCliEnv()).toBe(newBinary);
+    expect(newRuntime.state.resolvedOpencodeBinarySource).toBe('bundled');
+    expect(newRuntime.runtime.isBundledOpenCodeCliPath(newBinary)).toBe(true);
+    expect(process.env.OPENCODE_BINARY).toBeUndefined();
+  });
+
+  it.each(['web', 'ssh-remote'])('preserves automatic binary export outside desktop in %s', (runtimeName) => {
+    process.env.AIWORKER_RUNTIME = runtimeName;
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    const { runtime } = createRuntime({});
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
+  it.each(['env', 'settings'])('preserves explicit desktop %s selection even when it points at a bundled CLI', async (source) => {
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    if (source === 'env') process.env.OPENCODE_BINARY = binary;
+    const { runtime, state } = createRuntime(source === 'settings' ? { opencodeBinary: binary } : {});
+    await runtime.applyOpencodeBinaryFromSettings({ strict: true });
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(state.resolvedOpencodeBinarySource).toBe(source);
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
+  it('preserves automatic PATH binary export for desktop without a bundled CLI', () => {
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    Object.defineProperty(process, 'resourcesPath', { configurable: true, value: undefined });
+    process.env.PATH = path.dirname(binary);
+    const { runtime, state } = createRuntime({});
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(state.resolvedOpencodeBinarySource).toBe('path');
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
   it('searches an explicit PATH without mutating the process environment', () => {
     const defaultDir = createTempDir('openchamber-default-path-');
     const explicitDir = createTempDir('openchamber-explicit-path-');

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

@@ -10,6 +10,7 @@ import { registerDevServerRoutes } from '../dev-servers/routes.js';
 import { registerMagicPromptRoutes } from '../magic-prompts/routes.js';
 import { registerSessionFoldersRoutes } from '../session-folders/routes.js';
 import { registerProjectContextRoutes } from '../project-context/routes.js';
+import { registerProjectSetupRoutes } from '../projects/routes.js';
 import { registerAgentMemoryRoutes } from '../agent-memory/routes.js';
 import { registerSessionKnowledgeRoutes } from '../session-knowledge/routes.js';
 import { registerPermissionAutoAcceptRoutes } from '../permission-auto-accept/runtime.js';
@@ -306,7 +307,21 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     registerSessionGoalRoutes(app);
     registerGitHubRoutes(app);
     registerLinearRoutes(app);
-    registerGitRoutes(app);
+    registerGitRoutes(app, {
+      emitWorktreeChanged: ({ directories, at }) => {
+        const clients = getAiWorkerEventClients();
+        for (const client of clients) {
+          try {
+            writeSseEvent(client, {
+              type: 'aiworker:worktree-changed',
+              properties: { directories, at },
+            });
+          } catch {
+            clients.delete(client);
+          }
+        }
+      },
+    });
     registerDevServerRoutes(app, { scanner: devServerScanner, getOwnPorts });
     registerMagicPromptRoutes(app, {
       fsPromises,
@@ -314,6 +329,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       aiworkerDataDir,
     });
     registerProjectContextRoutes(app, { projectContextRuntime });
+    registerProjectSetupRoutes(app, { projectConfigRuntime });
     registerAgentMemoryRoutes(app, { agentMemoryRuntime, isAgentMemoryEnabled });
     registerSessionKnowledgeRoutes(app, { sessionKnowledgeRuntime });
 

package/server/lib/opencode/lifecycle.js

@@ -377,8 +377,8 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     return parts.length > 0 ? parts.join('\n\n') : 'No stdout/stderr captured';
   };
 
-  const createManagedOpenCodeServerProcess = async ({ hostname, port, timeout, cwd, env: processEnv, shellEnvKeysCount = 0 }) => {
-    let binary = (process.env.OPENCODE_BINARY || 'opencode').trim() || 'opencode';
+  const createManagedOpenCodeServerProcess = async ({ resolvedBinary, hostname, port, timeout, cwd, env: processEnv, shellEnvKeysCount = 0 }) => {
+    let binary = (resolvedBinary || process.env.OPENCODE_BINARY || 'opencode').trim() || 'opencode';
     const sourceBinary = binary;
     let args = ['serve', '--hostname', hostname, '--port', String(port)];
     let launchWrapperType = null;
@@ -694,7 +694,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     );
 
     await applyOpencodeBinaryFromSettings({ strict: true });
-    ensureOpencodeCliEnv();
+    const resolvedBinary = ensureOpencodeCliEnv();
     recordStartupPerformance('opencode.binary.ready', {
       attempt,
       durationMs: performance.now() - phaseStartedAt,
@@ -721,6 +721,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
     try {
       const serverInstance = await createManagedOpenCodeServerProcess({
+        resolvedBinary,
         hostname: env.ENV_CONFIGURED_OPENCODE_HOSTNAME,
         port: spawnPort,
         timeout: 30000,

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

@@ -126,6 +126,35 @@ const createRuntime = (overrides = {}, stateOverrides = {}, envOverrides = {}) =
 };
 
 describe('OpenCode lifecycle', () => {
+  it('uses the resolved binary directly on startup and managed restart without an env override', async () => {
+    delete process.env.OPENCODE_BINARY;
+    const binaries = ['/bundle one/opencode-cli/opencode', '/bundle two/opencode-cli/opencode'];
+    const ensureOpencodeCliEnv = vi.fn()
+      .mockReturnValueOnce(binaries[0])
+      .mockReturnValueOnce(binaries[1]);
+    spawnMock.mockImplementation(() => {
+      const child = createMockChild();
+      queueMicrotask(() => child.stdout.emit('data', 'opencode server listening on http://127.0.0.1:45678\n'));
+      return child;
+    });
+    globalThis.fetch = vi.fn(async () => ({ ok: false }));
+    const runtime = createRuntime({ ensureOpencodeCliEnv });
+    const firstServer = await runtime.startOpenCode();
+    runtime.testState.openCodeProcess = firstServer;
+    try {
+      await runtime.restartOpenCode();
+      expect(firstServer.signalCode).toBe('SIGTERM');
+      expect(spawnMock.mock.calls.map(([binary]) => binary)).toEqual(binaries);
+      expect(runtime.testState.lastOpenCodeLaunchDiagnostics.sourceBinary).toBe(binaries[1]);
+      expect(process.env.OPENCODE_BINARY).toBeUndefined();
+      for (const [, , options] of spawnMock.mock.calls) {
+        expect(options.env).not.toHaveProperty('OPENCODE_BINARY');
+      }
+    } finally {
+      await runtime.testState.openCodeProcess.close();
+    }
+  });
+
   it('records an authoritative ready terminal event for external startup', async () => {
     globalThis.fetch = vi.fn(async () => ({
       ok: true,

package/server/lib/opencode/managed-plugin-config.js

@@ -8,7 +8,7 @@ const isJsonObject = (value) => value !== null && value !== undefined && Object.
  *
  * Existing entries are preserved; an earlier entry for the same URL is dropped
  * so a restart never registers the same plugin twice. Every managed plugin
- * (agent tools, system prompt optimizer, MCP reconnect) goes through this one
+ * (agent tools, system prompt optimizer) goes through this one
  * merge so they compose in any order.
  *
  * @param {string | undefined} rawConfig the current `OPENCODE_CONFIG_CONTENT`, JSONC or unset