@aiworker/web 1.23.0 → 1.23.1

package/server/lib/git/routes.test.js

@@ -5,6 +5,9 @@ const gitLibraries = {
   unstageFiles: vi.fn(),
   isGitRepository: vi.fn(),
   getStatus: vi.fn(),
+  getWorktrees: vi.fn(),
+  observeWorktreeTopology: vi.fn(),
+  subscribeWorktreeTopologyChanges: vi.fn(),
 };
 
 vi.mock('./index.js', () => ({
@@ -12,6 +15,9 @@ vi.mock('./index.js', () => ({
   unstageFiles: gitLibraries.unstageFiles,
   isGitRepository: gitLibraries.isGitRepository,
   getStatus: gitLibraries.getStatus,
+  getWorktrees: gitLibraries.getWorktrees,
+  observeWorktreeTopology: gitLibraries.observeWorktreeTopology,
+  subscribeWorktreeTopologyChanges: gitLibraries.subscribeWorktreeTopologyChanges,
 }));
 
 const { registerGitRoutes } = await import('./routes.js');
@@ -141,6 +147,78 @@ describe('git routes index mutations', () => {
   });
 });
 
+describe('git worktree topology routes', () => {
+  beforeEach(() => {
+    gitLibraries.isGitRepository.mockReset();
+    gitLibraries.getStatus.mockReset();
+    gitLibraries.getWorktrees.mockReset();
+    gitLibraries.observeWorktreeTopology.mockReset();
+    gitLibraries.subscribeWorktreeTopologyChanges.mockReset();
+    gitLibraries.observeWorktreeTopology.mockResolvedValue(undefined);
+  });
+
+  it('observes the repository topology while serving status, never for non-repositories', async () => {
+    gitLibraries.isGitRepository.mockResolvedValueOnce(true).mockResolvedValueOnce(false);
+    gitLibraries.getStatus.mockResolvedValue({ current: 'main' });
+    const { app, getRoute } = createRouteRegistry();
+    registerGitRoutes(app);
+    const route = getRoute('GET', '/api/git/status');
+
+    const repoResponse = createMockResponse();
+    await route({ query: { directory: '/repo' } }, repoResponse);
+    expect(repoResponse.body).toEqual({ current: 'main' });
+    expect(gitLibraries.observeWorktreeTopology).toHaveBeenCalledWith('/repo');
+
+    await route({ query: { directory: '/plain-folder' } }, createMockResponse());
+    expect(gitLibraries.observeWorktreeTopology).toHaveBeenCalledTimes(1);
+  });
+
+  it('observes topology after a repository listing and reports listing failures', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    gitLibraries.getWorktrees
+      .mockResolvedValueOnce([{ path: '/repo', branch: 'main' }])
+      .mockResolvedValueOnce([])
+      .mockRejectedValueOnce(new Error('git failed'));
+    const { app, getRoute } = createRouteRegistry();
+    registerGitRoutes(app);
+    const route = getRoute('GET', '/api/git/worktrees');
+
+    const listed = createMockResponse();
+    await route({ query: { directory: '/repo' } }, listed);
+    expect(listed.body).toEqual([{ path: '/repo', branch: 'main' }]);
+    expect(gitLibraries.observeWorktreeTopology).toHaveBeenCalledWith('/repo');
+
+    await route({ query: { directory: '/plain-folder' } }, createMockResponse());
+    expect(gitLibraries.observeWorktreeTopology).toHaveBeenCalledTimes(1);
+
+    const failed = createMockResponse();
+    await route({ query: { directory: '/repo' } }, failed);
+    expect(failed.statusCode).toBe(500);
+    expect(failed.body).toEqual({ error: 'git failed' });
+    errorSpy.mockRestore();
+  });
+
+  it('forwards topology changes to the control event emitter once', async () => {
+    let listener = null;
+    gitLibraries.subscribeWorktreeTopologyChanges.mockImplementation((next) => {
+      listener = next;
+      return () => undefined;
+    });
+    gitLibraries.getWorktrees.mockResolvedValue([]);
+    const emitWorktreeChanged = vi.fn();
+    const { app, getRoute } = createRouteRegistry();
+    registerGitRoutes(app, { emitWorktreeChanged });
+    const route = getRoute('GET', '/api/git/worktrees');
+
+    await route({ query: { directory: '/repo' } }, createMockResponse());
+    await route({ query: { directory: '/repo' } }, createMockResponse());
+    expect(gitLibraries.subscribeWorktreeTopologyChanges).toHaveBeenCalledTimes(1);
+
+    listener({ directories: ['/repo'], at: 123 });
+    expect(emitWorktreeChanged).toHaveBeenCalledWith({ directories: ['/repo'], at: 123 });
+  });
+});
+
 describe('git routes status discovery', () => {
   beforeEach(() => {
     gitLibraries.isGitRepository.mockReset();

package/server/lib/git/service.js

@@ -4064,14 +4064,167 @@ export async function getWorktrees(directory) {
     // OpenCode's working directory or an unconfigured project path), git
     // exits with "fatal: not a git repository ...". Treat that as an
     // authoritative empty result so the route handler can still respond
-    // 200 [] and the desktop main.log stays free of noise.
-    if (!isNotGitRepositoryError(error)) {
-      console.warn('Failed to list worktrees, returning empty list:', error?.message || error);
+    // 200 [] and the desktop main.log stays free of noise. Any other failure
+    // is a failure: callers keep their last known topology instead of
+    // treating "git could not answer" as "there are no worktrees".
+    if (isNotGitRepositoryError(error)) return [];
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Worktree topology change tracking
+//
+// Linked worktrees are registered under the repository's common Git directory
+// (`<common>/worktrees/<name>`). Instead of watching the filesystem, the server
+// fingerprints that directory while handling requests clients already make
+// (status, worktree listing) and after its own worktree create/remove, and
+// tells connected clients when the set of worktrees changed. Cost scales with
+// user activity, never with the number of registered projects.
+// ---------------------------------------------------------------------------
+
+const MAX_TRACKED_WORKTREE_DIRECTORIES = 500;
+const MAX_TRACKED_WORKTREE_REPOSITORIES = 200;
+const MAX_DIRECTORIES_PER_WORKTREE_REPOSITORY = 100;
+const worktreeTopologyListeners = new Set();
+const worktreeRepositoryKeyByDirectory = new Map();
+const worktreeTopologyByRepository = new Map();
+
+export function subscribeWorktreeTopologyChanges(listener) {
+  worktreeTopologyListeners.add(listener);
+  return () => {
+    worktreeTopologyListeners.delete(listener);
+  };
+}
+
+const rememberWorktreeRepositoryKey = (directoryPath, key) => {
+  worktreeRepositoryKeyByDirectory.delete(directoryPath);
+  worktreeRepositoryKeyByDirectory.set(directoryPath, key);
+  while (worktreeRepositoryKeyByDirectory.size > MAX_TRACKED_WORKTREE_DIRECTORIES) {
+    const oldest = worktreeRepositoryKeyByDirectory.keys().next().value;
+    if (oldest === undefined) break;
+    worktreeRepositoryKeyByDirectory.delete(oldest);
+  }
+};
+
+/**
+ * Canonical common Git directory for `directoryPath`, resolved with git once per
+ * directory and cached. Returns null when git cannot answer (not a repository,
+ * missing directory).
+ */
+const resolveWorktreeRepositoryKey = async (directoryPath) => {
+  const cached = worktreeRepositoryKeyByDirectory.get(directoryPath);
+  if (cached) {
+    rememberWorktreeRepositoryKey(directoryPath, cached);
+    return cached;
+  }
+  const result = await runGitCommand(directoryPath, ['rev-parse', '--git-common-dir']);
+  const rawCommonDir = String(result.stdout || '').trim();
+  if (!result.success || !rawCommonDir) {
+    return null;
+  }
+  const commonDir = path.resolve(directoryPath, rawCommonDir);
+  let key = commonDir;
+  try {
+    key = fs.realpathSync(commonDir);
+  } catch {
+    // Keep the resolved path; a missing common dir cannot register worktrees.
+  }
+  rememberWorktreeRepositoryKey(directoryPath, key);
+  return key;
+};
+
+/**
+ * Cheap identity of the registered linked-worktree set: the `worktrees`
+ * directory's mtime plus its entry names. Adding, removing, or pruning a
+ * worktree changes at least one of them; `git worktree move` rewrites files
+ * inside an entry and is not detected.
+ */
+const readWorktreeTopologyFingerprint = (repositoryKey) => {
+  const worktreesDir = path.join(repositoryKey, 'worktrees');
+  try {
+    const stat = fs.statSync(worktreesDir);
+    const names = fs.readdirSync(worktreesDir).sort();
+    return `${stat.mtimeMs}:${names.join('\0')}`;
+  } catch {
+    return 'none';
+  }
+};
+
+const trackWorktreeTopologyDirectory = (repositoryKey, directoryPath) => {
+  let entry = worktreeTopologyByRepository.get(repositoryKey);
+  if (!entry) {
+    entry = { directories: new Set(), fingerprint: null };
+  }
+  // Re-insert so the map stays ordered by last use; the least recently used
+  // repository is dropped first once the bound is reached.
+  worktreeTopologyByRepository.delete(repositoryKey);
+  worktreeTopologyByRepository.set(repositoryKey, entry);
+  while (worktreeTopologyByRepository.size > MAX_TRACKED_WORKTREE_REPOSITORIES) {
+    const oldest = worktreeTopologyByRepository.keys().next().value;
+    if (oldest === undefined) break;
+    worktreeTopologyByRepository.delete(oldest);
+  }
+  if (entry.directories.size < MAX_DIRECTORIES_PER_WORKTREE_REPOSITORY) {
+    entry.directories.add(directoryPath);
+  }
+  return entry;
+};
+
+const notifyWorktreeTopologyChanged = (entry) => {
+  const event = { directories: [...entry.directories], at: Date.now() };
+  for (const listener of worktreeTopologyListeners) {
+    try {
+      listener(event);
+    } catch (error) {
+      console.warn('Worktree topology listener failed:', error?.message || error);
     }
-    return [];
+  }
+};
+
+/**
+ * Compare the repository's worktree set with the last one seen for it and
+ * notify listeners when it changed. The first observation only records a
+ * baseline. Called from request handlers that already touch the repository;
+ * never throws.
+ */
+export async function observeWorktreeTopology(directory) {
+  const directoryPath = normalizeDirectoryPath(directory);
+  if (!directoryPath) return;
+  try {
+    const repositoryKey = await resolveWorktreeRepositoryKey(directoryPath);
+    if (!repositoryKey) return;
+    const entry = trackWorktreeTopologyDirectory(repositoryKey, directoryPath);
+    const fingerprint = readWorktreeTopologyFingerprint(repositoryKey);
+    if (entry.fingerprint === fingerprint) return;
+    const hadBaseline = entry.fingerprint !== null;
+    entry.fingerprint = fingerprint;
+    if (hadBaseline) notifyWorktreeTopologyChanged(entry);
+  } catch (error) {
+    console.warn('Failed to observe worktree topology:', error?.message || error);
   }
 }
 
+/**
+ * Record that this server changed the repository's worktree set itself and
+ * notify listeners right away. `directory` is any directory inside the
+ * repository; never throws so a notification problem cannot fail the
+ * operation that triggered it.
+ */
+const publishWorktreeTopologyChange = async (directory) => {
+  const directoryPath = normalizeDirectoryPath(directory);
+  if (!directoryPath) return;
+  try {
+    const repositoryKey = await resolveWorktreeRepositoryKey(directoryPath);
+    if (!repositoryKey) return;
+    const entry = trackWorktreeTopologyDirectory(repositoryKey, directoryPath);
+    entry.fingerprint = readWorktreeTopologyFingerprint(repositoryKey);
+    notifyWorktreeTopologyChanged(entry);
+  } catch (error) {
+    console.warn('Failed to publish worktree topology change:', error?.message || error);
+  }
+};
+
 export async function validateWorktreeCreate(directory, input = {}) {
   const mode = input?.mode === 'existing' ? 'existing' : 'new';
   const errors = [];
@@ -4329,6 +4482,7 @@ async function attachGitWorktreeToCandidate(context, candidate, input = {}) {
   }
 
   await runGitCommandOrThrow(context.primaryWorktree, worktreeAddArgs, 'Failed to create git worktree');
+  await publishWorktreeTopologyChange(context.primaryWorktree);
 
   const upstreamRemote = shouldSetUpstream
     ? String(input?.upstreamRemote || inferredUpstream?.remote || '').trim()
@@ -4551,6 +4705,7 @@ export async function removeWorktree(directory, input = {}) {
     ['worktree', 'remove', '--force', matchedEntry.worktree],
     'Failed to remove git worktree'
   );
+  await publishWorktreeTopologyChange(context.primaryWorktree);
 
   if (deleteLocalBranch) {
     const branchName = cleanBranchName(String(matchedEntry.branchRef || matchedEntry.branch || '').trim());

package/server/lib/git/service.test.js

@@ -23,6 +23,7 @@ import {
   getStatus,
   getWorktrees,
   isGitRepository,
+  observeWorktreeTopology,
   populateWorktreeWithLockRecovery,
   removeWorktree,
   resolvePrimaryWorktreeRoot,
@@ -32,6 +33,7 @@ import {
   revertCommit,
   setLocalIdentity,
   stageFiles,
+  subscribeWorktreeTopologyChanges,
   unstageFiles,
   applyHunk,
   getDiff,
@@ -680,6 +682,78 @@ describe('getWorktrees', () => {
     expect(Array.isArray(result)).toBe(true);
     expect(warnSpy).not.toHaveBeenCalled();
   });
+  it('notifies subscribers only when another git process changes the worktree set', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    runGit(repo, ['commit', '--allow-empty', '-m', 'init']);
+    const worktreePath = path.join(createTempDir(), 'feature');
+
+    const events = [];
+    const unsubscribe = subscribeWorktreeTopologyChanges((event) => events.push(event));
+    try {
+      await observeWorktreeTopology(repo);
+      await observeWorktreeTopology(repo);
+      expect(events).toHaveLength(0);
+
+      runGit(repo, ['worktree', 'add', worktreePath, '-b', 'feature']);
+      await observeWorktreeTopology(worktreePath);
+      expect(events).toHaveLength(1);
+      expect(events[0].directories).toEqual(expect.arrayContaining([repo, worktreePath]));
+
+      await observeWorktreeTopology(repo);
+      expect(events).toHaveLength(1);
+
+      runGit(repo, ['worktree', 'remove', worktreePath]);
+      await observeWorktreeTopology(repo);
+      expect(events).toHaveLength(2);
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  it('publishes worktrees this server creates and removes', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = createTempDir();
+    const events = [];
+    const unsubscribe = subscribeWorktreeTopologyChanges((event) => events.push(event));
+    try {
+      const repo = createTempDir();
+      runGit(repo, ['init', '-b', 'main']);
+      runGit(repo, ['config', 'user.email', 'test@example.com']);
+      runGit(repo, ['config', 'user.name', 'Test User']);
+      runGit(repo, ['commit', '--allow-empty', '-m', 'init']);
+      await observeWorktreeTopology(repo);
+
+      const created = await createWorktree(repo, {
+        mode: 'new',
+        worktreeName: 'published',
+        branchName: 'aiworker/published',
+      });
+      expect(events).toHaveLength(1);
+      expect(events[0].directories).toContain(repo);
+
+      // The publish refreshed the baseline, so the next observation is quiet.
+      await observeWorktreeTopology(repo);
+      expect(events).toHaveLength(1);
+
+      await removeWorktree(repo, { directory: created.path });
+      expect(events).toHaveLength(2);
+    } finally {
+      unsubscribe();
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  });
+
   it('flags a worktree whose directory was deleted outside git as prunable', async () => {
     const repo = createTempDir();
     runGit(repo, ['init', '-b', 'main']);

package/server/lib/github/DOCUMENTATION.md

@@ -63,6 +63,11 @@
 
 ## Consumers of PR data
 
+PR list/search failures propagate as errors instead of successful empty lists.
+Comparison pickers use these responses to offer retry rather than claiming the
+repository has no PRs. A failed repository in a multi-repository listing fails
+that page, so callers cannot mistake a partial page for a complete one.
+
 - `packages/ui/src/components/session/SessionSidebar.tsx` reads all PR entries and maps them to `directory::branch`.
 - `packages/ui/src/components/session/sidebar/SessionGroupSection.tsx` renders the compact badge, PR number, title, checks summary, and GitHub link.
 - `packages/ui/src/components/views/git/PullRequestSection.tsx` uses the same shared entry for the full PR workflow.

package/server/lib/github/routes.js

@@ -1513,7 +1513,7 @@ export function registerGitHubRoutes(app) {
           return res.json({ connected: true, repo, prs, page: effectivePage, hasMore });
         } catch (error) {
           console.error('Failed to search GitHub PRs:', error);
-          return res.json({ connected: true, repo, prs: [], page: effectivePage, hasMore: false });
+          throw error;
         }
       }
 
@@ -1532,7 +1532,7 @@ export function registerGitHubRoutes(app) {
           return { prs, hasMore };
         } catch (error) {
           console.warn(`Failed to list PRs for ${repoRef.owner}/${repoRef.repo}:`, error?.message || error);
-          return { prs: [], hasMore: false };
+          throw error;
         }
       };
 

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

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/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()`
@@ -422,6 +426,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/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;