@aiworker/web 1.22.2 → 1.23.1

package/server/lib/event-stream/global-ws-bridge.js

@@ -1,4 +1,4 @@
-import { sendMessageStreamWsEvent, sendMessageStreamWsFrame } from './protocol.js';
+import { sendMessageStreamWsEvent, sendMessageStreamWsFrame, sendSerializedMessageStreamWsFrame, serializeMessageStreamWsEvent } from './protocol.js';
 
 function shouldTriggerUpstreamHealthCheck(upstream) {
   if (!upstream) {
@@ -31,12 +31,9 @@ export function createGlobalMessageStreamWsBridge({
     wsClients.delete(socket);
   };
 
-  const replayEvents = (socket, requestedLastEventId) => {
-    for (const entry of globalHub.replayAfter(requestedLastEventId)) {
-      const sent = sendMessageStreamWsEvent(socket, entry.payload, {
-        directory: entry.directory,
-        eventId: entry.eventId,
-      });
+  const replayEvents = (socket, entries) => {
+    for (const entry of entries) {
+      const sent = sendSerializedMessageStreamWsFrame(socket, entry.serializedFrame);
       if (!sent) {
         removeClient(socket);
         return;
@@ -49,10 +46,10 @@ export function createGlobalMessageStreamWsBridge({
       return;
     }
 
-    const sent = sendMessageStreamWsFrame(socket, {
-      type: 'ready',
-      scope: 'global',
-    });
+    const replay = globalHub.replayAfter(requestedLastEventId);
+    const ready = { type: 'ready', scope: 'global' };
+    if (replay === null) ready.replayReset = true;
+    const sent = sendMessageStreamWsFrame(socket, ready);
     if (!sent) {
       removeClient(socket);
       return;
@@ -60,7 +57,7 @@ export function createGlobalMessageStreamWsBridge({
 
     readyClients.add(socket);
     wsClients.add(socket);
-    replayEvents(socket, requestedLastEventId);
+    if (replay !== null) replayEvents(socket, replay);
   };
 
   const stopHubIfUnused = () => {
@@ -88,26 +85,26 @@ export function createGlobalMessageStreamWsBridge({
     }
   };
 
-  const unsubscribeEvent = globalHub.subscribeEvent(({ payload, directory, eventId }) => {
+  const unsubscribeEvent = globalHub.subscribeEvent((event) => {
+    const { payload } = event;
     for (const socket of Array.from(clients)) {
       if (!readyClients.has(socket)) {
         continue;
       }
-      const sent = sendMessageStreamWsEvent(socket, payload, {
-        directory,
-        eventId,
-      });
+      const sent = sendSerializedMessageStreamWsFrame(socket, event.serialize());
       if (!sent) {
         removeClient(socket);
       }
     }
 
     processForwardedEventPayload(payload, (syntheticPayload) => {
+      if (readyClients.size === 0) return;
+      const serializedFrame = serializeMessageStreamWsEvent(syntheticPayload, { directory: 'global' });
       for (const socket of Array.from(clients)) {
         if (!readyClients.has(socket)) {
           continue;
         }
-        const sent = sendMessageStreamWsEvent(socket, syntheticPayload, { directory: 'global' });
+        const sent = sendSerializedMessageStreamWsFrame(socket, serializedFrame);
         if (!sent) {
           removeClient(socket);
         }

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

@@ -71,6 +71,14 @@ export function parseSseEventEnvelope(block) {
 }
 
 export function sendMessageStreamWsFrame(socket, payload) {
+  try {
+    return sendSerializedMessageStreamWsFrame(socket, JSON.stringify(payload));
+  } catch {
+    return false;
+  }
+}
+
+export function sendSerializedMessageStreamWsFrame(socket, serializedFrame) {
   if (!socket || socket.readyState !== 1) {
     return false;
   }
@@ -86,7 +94,7 @@ export function sendMessageStreamWsFrame(socket, payload) {
   }
 
   try {
-    socket.send(JSON.stringify(payload));
+    socket.send(serializedFrame);
     const bufferedAfter = typeof socket.bufferedAmount === 'number' ? socket.bufferedAmount : 0;
     if (bufferedAfter > MESSAGE_STREAM_WS_MAX_BUFFERED_BYTES) {
       try {
@@ -124,10 +132,16 @@ export function sendMessageStreamWsFrame(socket, payload) {
 }
 
 export function sendMessageStreamWsEvent(socket, payload, options = {}) {
-  return sendMessageStreamWsFrame(socket, {
-    type: 'event',
-    payload,
-    ...(typeof options.eventId === 'string' && options.eventId.length > 0 ? { eventId: options.eventId } : {}),
-    ...(typeof options.directory === 'string' && options.directory.length > 0 ? { directory: options.directory } : {}),
-  });
+  try {
+    return sendSerializedMessageStreamWsFrame(socket, serializeMessageStreamWsEvent(payload, options));
+  } catch {
+    return false;
+  }
+}
+
+export function serializeMessageStreamWsEvent(payload, options = {}) {
+  const frame = { type: 'event', payload };
+  if (typeof options.eventId === 'string' && options.eventId.length > 0) frame.eventId = options.eventId;
+  if (typeof options.directory === 'string' && options.directory.length > 0) frame.directory = options.directory;
+  return JSON.stringify(frame);
 }

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

@@ -5,7 +5,8 @@ import {
   MESSAGE_STREAM_DIRECTORY_WS_PATH,
   MESSAGE_STREAM_GLOBAL_WS_PATH,
   MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS,
-  sendMessageStreamWsEvent,
+  serializeMessageStreamWsEvent,
+  sendSerializedMessageStreamWsFrame,
 } from './protocol.js';
 import { createGlobalMessageStreamHub } from './global-hub.js';
 import { createGlobalMessageStreamWsBridge } from './global-ws-bridge.js';
@@ -28,20 +29,22 @@ export function createGlobalUiEventBroadcaster({
     }
 
     if (hasSseClients) {
+      const serializedPayload = JSON.stringify(payload);
       for (const res of sseClients) {
         try {
-          writeSseEvent(res, payload);
+          writeSseEvent(res, payload, serializedPayload);
         } catch {
         }
       }
     }
 
     if (hasWsClients) {
+      const serializedFrame = serializeMessageStreamWsEvent(payload, {
+        directory: typeof options.directory === 'string' && options.directory.length > 0 ? options.directory : 'global',
+        eventId: typeof options.eventId === 'string' && options.eventId.length > 0 ? options.eventId : undefined,
+      });
       for (const socket of Array.from(wsClients)) {
-        const sent = sendMessageStreamWsEvent(socket, payload, {
-          directory: typeof options.directory === 'string' && options.directory.length > 0 ? options.directory : 'global',
-          eventId: typeof options.eventId === 'string' && options.eventId.length > 0 ? options.eventId : undefined,
-        });
+        const sent = sendSerializedMessageStreamWsFrame(socket, serializedFrame);
         if (!sent) {
           wsClients.delete(socket);
         }

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

@@ -2,6 +2,66 @@ import { EventEmitter } from 'node:events';
 import { describe, expect, it } from 'vitest';
 
 import { createGlobalUiEventBroadcaster, createMessageStreamWsRuntime } from './runtime.js';
+import { createGlobalMessageStreamHub } from './global-hub.js';
+import { createNotificationEmitterRuntime } from '../notifications/emitter-runtime.js';
+
+it('serializes a UI broadcast once per wire format and isolates failed clients', () => {
+  let serializations = 0;
+  const payload = { toJSON() { serializations++; return { type: 'aiworker:test', properties: { value: 'same' } }; } };
+  const writes = [];
+  const sseClients = new Set(Array.from({ length: 4 }, () => ({ write: text => writes.push(text) })));
+  const sockets = Array.from({ length: 4 }, () => ({ readyState: 1, bufferedAmount: 0, send: text => writes.push(text) }));
+  const failed = { readyState: 1, bufferedAmount: 0, send() { throw new Error('closed'); } };
+  const wsClients = new Set([...sockets, failed]);
+  const { writeSseEvent } = createNotificationEmitterRuntime({});
+  const broadcast = createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent });
+  broadcast(payload);
+  expect(serializations).toBe(2);
+  expect(writes).toHaveLength(8);
+  expect(wsClients.has(failed)).toBe(false);
+  expect(wsClients.size).toBe(4);
+  expect(writes[0]).toBe(writes[3]);
+  expect(writes[4]).toBe(writes[7]);
+  sseClients.clear(); wsClients.clear();
+  broadcast(payload);
+  expect(serializations).toBe(2);
+});
+
+it('delivers oversized events live, but reports a replay gap instead of replaying across it', async () => {
+  const hub = createGlobalMessageStreamHub({
+    buildOpenCodeUrl: path => `http://127.0.0.1:4096${path}`,
+    getOpenCodeAuthHeaders: () => ({}),
+    replayByteLimit: 512,
+    fetchImpl: async (_url, options) => createSseResponse({
+      signal: options.signal, holdOpen: true,
+      blocks: [
+        'id: first\ndata: {"type":"first","properties":{}}\n\n',
+        `id: large\ndata: ${JSON.stringify({ type: 'large', properties: { text: '界'.repeat(1024) } })}\n\n`,
+        'id: last\ndata: {"type":"last","properties":{}}\n\n',
+      ],
+    }),
+  });
+  const runtime = createMessageStreamWsRuntime({
+    server: new EventEmitter(), globalEventHub: hub, wsClients: new Set(),
+    uiAuthController: null, isRequestOriginAllowed: async () => true,
+    rejectWebSocketUpgrade() {}, buildOpenCodeUrl: path => `http://127.0.0.1:4096${path}`,
+    getOpenCodeAuthHeaders: () => ({}), processForwardedEventPayload() {},
+  });
+  const first = new FakeSocket();
+  const reconnect = new FakeSocket();
+  try {
+    runtime.wsServer.emit('connection', first, { url: '/api/global/event/ws' });
+    await expect.poll(() => first.sent.filter(frame => frame.type === 'event').length).toBe(3);
+    expect(first.sent.find(frame => frame.eventId === 'large').payload.properties.text).toHaveLength(1024);
+    expect(hub.replayAfter('first')).toBeNull();
+    expect(hub.replayAfter('last')).toEqual([]);
+    runtime.wsServer.emit('connection', reconnect, { url: '/api/global/event/ws?lastEventId=first' });
+    await expect.poll(() => reconnect.sent.length).toBeGreaterThan(0);
+    expect(reconnect.sent).toEqual([{ type: 'ready', scope: 'global', replayReset: true }]);
+  } finally {
+    first.close(); reconnect.close(); hub.stop(); await runtime.close();
+  }
+});
 
 class FakeSocket extends EventEmitter {
   constructor() {
@@ -446,18 +506,18 @@ describe('message stream websocket runtime', () => {
     const socket = new FakeSocket();
     runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
 
-    await new Promise((resolve) => setTimeout(resolve, 35));
-
-    const readyFrames = socket.sent.filter((frame) => frame.type === 'ready');
-    const eventFrames = socket.sent.filter((frame) => frame.type === 'event' && frame.payload?.type === 'server.connected');
-
-    expect(readyFrames.length).toBeGreaterThanOrEqual(2);
-    expect(eventFrames.length).toBeGreaterThanOrEqual(2);
-    expect(fetchCalls.slice(0, 2)).toEqual([null, 'evt-1']);
-    expect(triggerHealthCheckCalls).toBe(0);
-
-    socket.close();
-    await runtime.close();
+    try {
+      // Wait for the reconnect event itself; a 35ms sleep raced the event
+      // loop when the workspace build and test workers ran together.
+      await expect.poll(() => socket.sent.filter((frame) => frame.type === 'ready').length).toBeGreaterThanOrEqual(2);
+      const eventFrames = socket.sent.filter((frame) => frame.type === 'event' && frame.payload?.type === 'server.connected');
+      expect(eventFrames.length).toBeGreaterThanOrEqual(2);
+      expect(fetchCalls.slice(0, 2)).toEqual([null, 'evt-1']);
+      expect(triggerHealthCheckCalls).toBe(0);
+    } finally {
+      socket.close();
+      await runtime.close();
+    }
   });
 
   it('keeps synthetic event processing on forwarded upstream events', async () => {

package/server/lib/fs/DOCUMENTATION.md

@@ -14,6 +14,8 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
     - `POST /api/fs/mkdir`
     - `GET /api/fs/read`
     - `GET /api/fs/raw`
+    - `GET /api/fs/stat`
+    - `GET /api/fs/directory-stat`
     - `GET /api/fs/serve/:path(*)`
     - `POST /api/fs/write`
     - `POST /api/fs/upload`
@@ -43,6 +45,7 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
 - Workspace checks accept, besides the active workspace and its worktrees, the **managed roots**: the AiWorker config root and the managed chats root (`managedChatsRoot` dependency; `AIWORKER_CHATS_DIR` upstream, default `<config root>/chats`). Chat worktrees may legitimately live outside every project workspace.
 - `GET /api/fs/home` answers `{ home, chatsRoot }`. `chatsRoot` is the server-resolved managed chats root; clients must use it instead of joining `home` + the well-known segment (a relocated root does not contain that segment).
 - Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
+- `GET /api/fs/directory-stat?path=...` uses one `stat` without listing contents or resolving project topology. It follows the same authenticated directory-discovery path policy as `/api/fs/list`, including targets outside the active workspace. A directory returns `{ isDirectory: true }`; `ENOENT` returns `not-found`, and a file or `ENOTDIR` returns `not-directory`. Permission and other failures remain distinct from a missing path. VS Code explicitly returns 501, so the shared client treats its probe as unknown.
 - Read-only routes authorize the requested path against the workspace before resolving symlinks. A symlink reached through the workspace may therefore target a file outside it, while a directly requested outside path still requires an exact-path grant. Write routes keep canonical-target boundary checks.
 - If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
 - `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.

package/server/lib/fs/routes.js

@@ -864,6 +864,37 @@ export const registerFsRoutes = (app, dependencies) => {
     }
   });
 
+  app.get('/api/fs/directory-stat', async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const paths = new URL(req.url, 'http://openchamber.local').searchParams.getAll('path');
+    const directoryPath = paths.length === 1 ? paths[0].trim() : '';
+    if (!directoryPath) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    try {
+      // Directory discovery uses the same path policy as /api/fs/list, including
+      // paths outside the current workspace. stat follows symlinks without readdir.
+      const resolvedPath = path.resolve(normalizeDirectoryPath(directoryPath));
+      const stats = await fsPromises.stat(resolvedPath);
+      if (!stats.isDirectory()) {
+        return res.status(400).json({ error: 'Specified path is not a directory', reason: 'not-directory' });
+      }
+      return res.json({ isDirectory: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        return res.status(error.code === 'ENOENT' ? 404 : 400).json({
+          error: error.code === 'ENOENT' ? 'Directory not found' : 'Specified path is not a directory',
+          reason: error.code === 'ENOENT' ? 'not-found' : 'not-directory',
+        });
+      }
+      if (isOsPermissionError(error)) {
+        return sendOsPermissionDenied(res, 'Access to directory denied');
+      }
+      return res.status(500).json({ error: 'Failed to stat directory' });
+    }
+  });
+
   app.get('/api/fs/stat', async (req, res) => {
     const filePath = typeof req.query.path === 'string' ? req.query.path.trim() : '';
     const optional = req.query.optional === 'true';

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

@@ -1,5 +1,9 @@
 import { EventEmitter } from 'events';
 import path from 'path';
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { mintOutsideFileGrant, registerFsRoutes } from './routes.js';
@@ -1385,7 +1389,11 @@ describe('fs stat directory scope (issue 3019)', () => {
       path: path.posix,
       fsPromises: {
         realpath: async (targetPath) => targetPath,
-        stat: async () => ({ isFile: () => true, size: 12 }),
+        stat: async (targetPath) => (
+          targetPath === '/repo-b'
+            ? { isDirectory: () => true, mtimeMs: 123 }
+            : { isFile: () => true, size: 12, mtimeMs: 456 }
+        ),
       },
       spawn: vi.fn(),
       crypto: { randomUUID: () => 'job-0' },
@@ -1428,6 +1436,107 @@ describe('fs stat directory scope (issue 3019)', () => {
     expect(res.statusCode).toBe(200);
     expect(res.body.isFile).toBe(true);
   });
+
+});
+
+describe('fs stat directory error handling', () => {
+  it('loads in Node without workspace node_modules, as packaged desktop does', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'openchamber-fs-import-'));
+    try {
+      await mkdir(path.join(directory, 'fs'));
+      await copyFile(new URL('./routes.js', import.meta.url), path.join(directory, 'fs/routes.mjs'));
+      await copyFile(new URL('../path-realpath-cache.js', import.meta.url), path.join(directory, 'path-realpath-cache.js'));
+      expect(() => execFileSync('node', [
+        '--input-type=module',
+        '--eval',
+        'await import(process.argv[1])',
+        pathToFileURL(path.join(directory, 'fs/routes.mjs')).href,
+      ], { cwd: directory, stdio: 'pipe' })).not.toThrow();
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  it('returns directory-missing reasons and permission errors for directory stat', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const enoent = Object.assign(new Error('missing'), { code: 'ENOENT' });
+    const enotdir = Object.assign(new Error('not a directory'), { code: 'ENOTDIR' });
+    const eacces = Object.assign(new Error('denied'), { code: 'EACCES' });
+    const stat = vi.fn(async (targetPath) => {
+      if (targetPath === '/repo-b') throw enoent;
+      if (targetPath === '/repo-b/file.txt/child') throw enotdir;
+      if (targetPath === '/repo-b/protected') throw eacces;
+      if (targetPath === '/repo-b/file.txt') return { isDirectory: () => false };
+      if (targetPath === '/repo-b/failure') throw new Error('unavailable');
+      return { isDirectory: () => true, mtimeMs: 1 };
+    });
+    const readdir = vi.fn(async () => []);
+    const callStat = async (handler, { headers = {}, query }) => {
+      const res = createMockResponse();
+      const req = {
+        url: `/api/fs/directory-stat?${new URLSearchParams(query)}`,
+        query,
+        get: (name) => headers[name.toLowerCase()] ?? undefined,
+      };
+      await handler(req, res);
+      return res;
+    };
+    registerFsRoutes(app, {
+      os: { homedir: () => '/home/user' },
+      path: path.posix,
+      fsPromises: {
+        realpath: async (targetPath) => targetPath,
+        stat,
+        readdir,
+      },
+      spawn: vi.fn(),
+      crypto: { randomUUID: () => 'job-0' },
+      normalizeDirectoryPath: (p) => p,
+      resolveProjectDirectory: async () => ({ directory: '/repo' }),
+      buildAugmentedPath: () => '/usr/bin',
+      resolveGitBinaryForSpawn: () => 'git',
+      aiworkerUserConfigRoot: '/home/user/.config',
+    });
+    const handler = getRoute('GET', '/api/fs/directory-stat');
+
+    const available = await callStat(handler, { query: { path: '/other-project' } });
+    expect(available.statusCode).toBe(200);
+    expect(available.body).toEqual({ isDirectory: true });
+    expect(available.getHeader('Cache-Control')).toBe('no-store');
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    const invalid = await callStat(handler, { query: { path: ' ' } });
+    expect(invalid.statusCode).toBe(400);
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    for (const query of ['path=/repo&path=/other', 'path[]=/repo', '']) {
+      const malformed = createMockResponse();
+      await handler({ url: `/api/fs/directory-stat?${query}` }, malformed);
+      expect(malformed.statusCode).toBe(400);
+    }
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    const missing = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b', directory: 'true' } });
+    expect(missing.statusCode).toBe(404);
+    expect(missing.body).toEqual({ error: 'Directory not found', reason: 'not-found' });
+
+    const notDir = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b/file.txt/child', directory: 'true' } });
+    expect(notDir.statusCode).toBe(400);
+    expect(notDir.body).toEqual({ error: 'Specified path is not a directory', reason: 'not-directory' });
+
+    const denied = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b/protected', directory: 'true' } });
+    expect(denied.statusCode).toBe(403);
+    expect(denied.body).toEqual({ error: 'Access to directory denied', reason: 'os-permission' });
+
+    const file = await callStat(handler, { query: { path: '/repo-b/file.txt' } });
+    expect(file.statusCode).toBe(400);
+    expect(file.body.reason).toBe('not-directory');
+
+    const failure = await callStat(handler, { query: { path: '/repo-b/failure' } });
+    expect(failure.statusCode).toBe(500);
+    expect(failure.body).toEqual({ error: 'Failed to stat directory' });
+    expect(readdir).not.toHaveBeenCalled();
+  });
 });
 
 describe('fs managed chats root', () => {

package/server/lib/git/DOCUMENTATION.md

@@ -25,9 +25,11 @@ The following functions are exported and used by the web server:
 
 ### Status and Diff Operations
 - `getStatus(directory)`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state.
-- `getDiff(directory, { path, staged, contextLines })`: Get diff output for files or entire working tree. Untracked symbolic links are represented as link entries without following their targets.
-- `getRangeDiff(directory, { base, head, path, contextLines })`: Get diff between two refs. Uses three-dot `base...head` semantics, so work merged into `head` from `base` is excluded and only the branch's own changes are returned. Prefers `origin/<base>` when that remote-tracking ref exists, so a stale local base branch does not resurface already-merged commits. Exposed as `GET /api/git/range-diff` (`path` optional; omit it for the whole range).
-- `getRangeFiles(directory, { base, head })`: Get list of changed files between two refs.
+- `getDiff(directory, { path, staged, contextLines })`: Get diff output for files or entire working tree with full Git blob identities. Untracked symbolic links are represented as link entries without following their targets.
+- `getRangeDiff(directory, { base, head, path, contextLines, includeWorkingTree })`: Compare the merge base of the exact selected refs with `head`. With `includeWorkingTree: true`, compare with the checked-out branch's current files instead, including committed, staged, unstaged, and untracked work in one net diff. This mode rejects a head that is not the checked-out branch. Exposed as `GET /api/git/range-diff`; omit `path` for the whole comparison.
+- `getRangeFiles(directory, { base, head, includeWorkingTree })`: List changed paths using the same comparison as `getRangeDiff`. A successful empty list means the final files match the merge base, even if staging and working-tree changes cancel each other out.
+- Both range operations honor refs literally. A local `main` is never replaced with `origin/main`, and an unavailable ref fails rather than choosing a different remote. The UI picker sends qualified refs to distinguish local and remote branches with matching display names.
+- Working-tree comparisons use the real index read-only. When untracked paths exist, a temporary copy of the index receives intent-to-add entries so Git computes additions, deletions, recreations, and renames together. Current contents come from the working tree, symlinks remain links, ignored files stay excluded, and temporary files are removed on success or failure.
 - `getFileDiff(directory, { path, staged })`: Get original and modified file contents for a single file (handles images as data URLs and symbolic links as their link-target text).
 - `listUntrackedPaths(directory)`: List individual untracked file paths honoring ignore rules. Much cheaper than `getStatus` when that is all a caller needs. Deliberately not `--directory`: collapsed directory entries end in a slash and are rejected by the per-file diff helpers, so a caller would silently lose every file inside a new directory.
 - `getUntrackedDiffs(directory, filePaths, { concurrency, contextLines })`: Diffs for untracked files against an empty tree. Resolves the repository context once instead of per file (`getDiff` re-resolves every call, costing an extra `rev-parse` each time) and bounds how many diff processes run at once. Returns one entry per input path in order; unreadable paths yield `''` rather than failing the batch.
@@ -35,9 +37,10 @@ The following functions are exported and used by the web server:
 - `revertFile(directory, filePath, options)`: Revert a file. Default scope `all` discards staged and working-tree changes; scope `working` discards only unstaged/working-tree changes.
 - `stageFile(directory, filePath)`: Add one file path to the index.
 - `unstageFile(directory, filePath)`: Remove one file path from the index while preserving working-tree content.
-- `applyHunk(directory, filePath, options)`: Apply a single-hunk patch via `git apply`. `options.action` is `stage` (`git apply --cached`), `unstage` (`git apply --cached --reverse`), or `discard` (`git apply --reverse` in the working tree). The patch is written to a temp file; a `--check` runs first so a stale hunk fails with a clear "refresh and try again" error instead of a partial mutation. The patch target path must match the requested file.
+- `applyHunk(directory, filePath, options)`: Apply a single-hunk patch via `git apply`. `options.action` is `stage` (`git apply --cached`), `unstage` (`git apply --cached --reverse`), or `discard` (`git apply --reverse` in the working tree). Inside the index mutation queue, the server verifies that the complete patch exactly matches one current three-context-line hunk for that file and scope, then runs `--check` before applying. Applicability alone cannot prove an unstaged change: old staged or committed hunks can reverse cleanly too. Stale, historical and multi-file patches fail with a refresh error. Temporary patch files are removed on success and failure; hunk content retains CRLF bytes.
 
 ### Branch Operations
+- `getBranchBase(directory, branch)`: Read a named creation source from reflog. After a rebase, the creation source is no longer a current parent record, so return `null` and let the user choose a base. Explicit per-runtime, directory, and branch choices in the shared UI outrank detection.
 - `getBranches(directory)`: Get list of local and remote branches (filtered to active remote branches).
 - `getUnpushedBranchCounts(directory, branchNames)`: Count commits ahead of each locally known upstream for up to five supplied local branches. This reads local refs only and omits branches without an upstream.
 - `createBranch(directory, branchName, options)`: Create and checkout a new branch.
@@ -47,12 +50,21 @@ The following functions are exported and used by the web server:
 - `getRemotes(directory)`: Get list of configured remotes.
 
 ### Worktree Operations
-- `getWorktrees(directory)`: List all git worktrees for a repository.
+- `getWorktrees(directory)`: List all git worktrees for a repository. A directory outside any repository (or one that does not exist) is an authoritative empty list; any other git failure throws so callers keep their last known topology instead of clearing it. `GET /api/git/worktrees` answers such a failure with 500.
+- `observeWorktreeTopology(directory)`: Compare the repository's registered linked-worktree set with the last one seen for it and notify `subscribeWorktreeTopologyChanges` listeners when it changed. The set is fingerprinted from the `worktrees` directory under the common Git directory (mtime plus entry names), so the check is a stat and a readdir; the common directory is resolved with `git rev-parse --git-common-dir` once per requested directory and cached. The first observation only records a baseline. Never throws.
+- `subscribeWorktreeTopologyChanges(listener)`: Listener receives `{ directories, at }`, where `directories` are every directory of that repository the server has observed, so clients can map them onto registered projects. Returns an unsubscribe function.
 - `validateWorktreeCreate(directory, input)`: Validate worktree creation parameters (mode, branchName, startRef, upstream config).
 - `createWorktree(directory, input)`: Create a new worktree (supports 'new' and 'existing' modes, upstream setup). When the current tracked branch has no unpublished commits, the UI supplies its remote-tracking ref and this operation fetches that branch once before creating the worktree. A failed fetch falls back to the local branch and reports `sourceFetchFailed`; other remote start refs still require an existing local ref when their fetch fails. After populating the worktree, the repository's `post-checkout` hook runs once with git's standard arguments (null ref as previous HEAD, the checked-out HEAD, and flag `1`) from the worktree directory, mirroring `git worktree add` without `--no-checkout`; a missing or non-executable hook is skipped and a failing hook is logged as a warning, never failing worktree creation or the session bootstrap.
 - `removeWorktree(directory, input)`: Remove a worktree (optionally delete local branch).
 - `isLinkedWorktree(directory)`: Check if directory is a linked worktree (not primary).
 
+### Worktree topology change tracking
+There is no filesystem watcher and no polling. The server notices worktree changes in two ways, and both scale with what users are doing rather than with the number of registered projects:
+- Its own `createWorktree` and `removeWorktree` publish a change right after `git worktree add` / `git worktree remove` succeed (creation notifies before background population and setup scripts run).
+- `GET /api/git/status` for a repository and `GET /api/git/worktrees` with a non-empty listing call `observeWorktreeTopology` beside the response. Clients request status while they work in a repository, and a completed agent tool call already triggers a status refresh, so a worktree added by an agent or from a terminal is noticed on the next such request; nothing runs while the app is idle.
+
+`feature-routes-runtime.js` forwards each change to connected control-event clients as `aiworker:worktree-changed` with `{ directories, at }`. A repository nobody sends status or listing requests for is not observed until the next ordinary listing. `git worktree move` rewrites files inside an entry without touching the `worktrees` directory and is not detected. Tracking state is bounded: 500 directory-to-repository entries, 200 repositories, 100 directories per repository, least recently used dropped first.
+
 ### Worktree creation from a GitHub pull request
 The UI provisions `pr-<owner>` via `ensureRemoteName`/`ensureRemoteUrl`
 (HTTPS clone URL preferred over SSH) and checks out
@@ -71,7 +83,8 @@ bootstrap, tracking is left unset rather than writing `branch.*.remote` /
 
 ### Log Operations
 - `getLog(directory, options)`: Get commit history with stats (supports maxCount, from, to, file filters).
-- `getCommitFiles(directory, commitHash)`: Get file changes for a specific commit.
+- `getCommitFiles(directory, commitHash)`: Get file changes for a specific commit relative to its first parent, or the empty tree for a root commit. NUL-delimited paths preserve whitespace; renamed files return their destination in `path` and source in `previousPath`.
+- `getCommitDiff(directory, { hash, path, previousPath, contextLines })`: Get the same commit's patch, with optional file filtering and context depth. `previousPath` keeps a rename's old and new paths in the per-file patch. Reads committed objects only, never the working tree. Exposed as `GET /api/git/commit-diff`; an unavailable hash fails rather than returning an empty diff.
 - `getCommitFileDiff(directory, hash, filePath, isBinary)`: Get before/after content for a specific file in a commit. Returns `{ original, modified, isBinary }`. Runs `git show <hash>^:<path>` and `git show <hash>:<path>` in parallel; returns empty strings on failure (added/deleted/root-commit edge cases).
 
 ### Merge and Rebase Operations
@@ -130,8 +143,28 @@ The following functions are internal helpers used by exported functions:
 
 ### Runtime availability of range diffs
 - `GET /api/git/range-diff` is served by the AiWorker web server, so it is available to web, desktop, and mobile clients. The shared `GitAPI.getGitRangeDiff` is therefore optional: web supplies the HTTP implementation, and VS Code does not implement it because the extension host serves Git through its own bridge rather than these routes. Features built on range diffs (currently the AI diff walkthrough) are not offered in VS Code.
+- Commit comparison uses the same server boundary through optional `GitAPI.getGitCommitDiff`. Desktop Changes, mobile Changes, and the existing walkthrough surface share branch/commit comparison semantics. Mobile Changes uses the same selectors and `useGitComparison` file-list owner, with a read-only list-to-detail flow. VS Code keeps its existing modes because its Git bridge does not provide these comparison operations. The HTTP operations are available to web, Electron, hosted mobile, and Capacitor clients.
 
 ### Staged and unstaged change handling
+- Desktop Changes floats a compact action capsule after each hunk's last changed row,
+  including single-hunk files. Whole-file controls remain in the Git panel.
+  `getPatchHunkAnchors` uses the canonical patch's final changed row and side, so a hunk
+  ending in deletions is anchored after those deletions rather than above them.
+  Zero-height Pierre annotation slots anchor the capsule over following context
+  without a separate band. At EOF the capsule lifts inside the code column;
+  a one-line code column has a minimum hit-target height. React controls mount only
+  for currently rendered slots and only after their rendered diff and anchor
+  identities match the current props. Comment annotations remain independent.
+- The canonical three-line-context action patch stays separate from the full-file
+  display patch. Their bytes must be identical, or their file headers and full
+  blob identities must match, including when reusing a cached action patch.
+  Mismatch leaves actions unavailable until Retry obtains a matching pair.
+  Successful hunk mutations invalidate
+  every mounted view of that path through `sessionEvents.requestGitRefresh`.
+  Actions remain unavailable until the refresh succeeds. Last turn, Branch and
+  Commit snapshots never expose hunk mutations. Mobile uses its separate Changes
+  surface and VS Code does not mount these controls.
+- Untracked patches from `getDiff` and `getUntrackedDiffs` use `git diff --no-index` with separate stdout, stderr, and process exit status. Exit codes 0 and 1 return stdout only, so line-ending warnings never become patch text or request failures. Other exits and process failures reject the single-file request; the batch keeps an empty entry for the failed path and preserves the other results.
 - `status.files` exposes both `index` and `working_dir` codes. Shared UI uses these as separate scopes: staged rows are derived from non-empty `index` statuses, while unstaged rows are derived from `working_dir` statuses and untracked files.
 - A file with both staged and unstaged changes can appear in both UI sections. Staged rows request diffs with `staged: true`; unstaged rows request normal working-tree diffs.
 - The shared Git panel exposes explicit staging actions. Unstaged rows use `stageFile`, staged rows use `unstageFile`, and commits operate on the current staged index.