@vantran-se/openchamber-web 1.23.0 → 1.24.3

package/server/lib/fs/routes.js

@@ -196,6 +196,23 @@ const isPathWithinRoot = (resolvedPath, rootPath, path, os) => {
   return true;
 };
 
+// A chats root may not exist until the first draft. Resolve its existing
+// ancestor so both that first mkdir and later OpenCode sessions use disk casing.
+const canonicalDirectoryPath = async (directory, fsPromises, path) => {
+  let ancestor = path.resolve(directory);
+  const missing = [];
+  for (;;) {
+    try {
+      return path.join(await fsPromises.realpath(ancestor), ...missing);
+    } catch (error) {
+      const parent = path.dirname(ancestor);
+      if (error.code !== 'ENOENT' || parent === ancestor) throw error;
+      missing.unshift(path.basename(ancestor));
+      ancestor = parent;
+    }
+  }
+};
+
 const resolveWorkspacePath = ({ targetPath, baseDirectory, path, os, normalizeDirectoryPath, managedRoots }) => {
   const normalized = normalizeDirectoryPath(targetPath);
   if (!normalized || typeof normalized !== 'string') {
@@ -253,7 +270,7 @@ const resolveWorkspacePathFromWorktrees = async ({ targetPath, baseDirectory, pa
   return { ok: false, error: 'Path is outside of active workspace' };
 };
 
-const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProjectDirectory, path, os, normalizeDirectoryPath, managedRoots }) => {
+const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProjectDirectory, path, os, fsPromises, normalizeDirectoryPath, managedRoots }) => {
   const resolvedProject = await resolveProjectDirectory(req);
   if (!resolvedProject.directory) {
     return { ok: false, error: resolvedProject.error || 'Active workspace is required' };
@@ -292,13 +309,30 @@ const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProject
     }
   }
 
-  return resolveWorkspacePathFromWorktrees({
+  // Keep legacy lexical paths valid, but also accept the canonical roots
+  // returned by /fs/home. Never infer filesystem identity from letter case.
+  let resolutionError;
+  for (const root of managedRoots) {
+    try {
+      const canonicalRoot = await canonicalDirectoryPath(root, fsPromises, path);
+      const resolvedPath = path.resolve(normalizeDirectoryPath(targetPath));
+      if (isPathWithinRoot(resolvedPath, canonicalRoot, path, os)) {
+        return { ok: true, base: canonicalRoot, resolved: resolvedPath };
+      }
+    } catch (error) {
+      resolutionError ??= error;
+    }
+  }
+  const worktree = await resolveWorkspacePathFromWorktrees({
     targetPath,
     baseDirectory: resolvedProject.directory,
     path,
     os,
     normalizeDirectoryPath,
   });
+  if (worktree.ok) return worktree;
+  if (resolutionError) throw resolutionError;
+  return worktree;
 };
 
 // Nested repository discovery bounds: only shallow walks are useful for the
@@ -437,6 +471,7 @@ const resolveReadPathFromContext = async ({ req, targetPath, scope, resolveProje
     resolveProjectDirectory,
     path,
     os,
+    fsPromises,
     normalizeDirectoryPath,
     managedRoots,
   });
@@ -704,13 +739,22 @@ export const registerFsRoutes = (app, dependencies) => {
     job.updatedAt = Date.now();
   };
 
-  app.get('/api/fs/home', (_req, res) => {
+  app.get('/api/fs/home', async (_req, res) => {
     try {
       const home = os.homedir();
       if (!home || typeof home !== 'string' || home.length === 0) {
         return res.status(500).json({ error: 'Failed to resolve home directory' });
       }
-      return res.json({ home, chatsRoot });
+      const [canonicalChatsRoot, canonicalLegacyChatsRoot] = await Promise.all([
+        canonicalDirectoryPath(chatsRoot, fsPromises, path),
+        canonicalDirectoryPath(path.join(home, '.config', 'openchamber', 'chats'), fsPromises, path).catch((error) => {
+          // A relocated root must remain usable if the old root is inaccessible.
+          // Omit only this optional alias; clients retain exact legacy matching.
+          console.warn('Failed to resolve legacy chats root:', error);
+          return undefined;
+        }),
+      ]);
+      return res.json({ home, chatsRoot, canonicalChatsRoot, canonicalLegacyChatsRoot });
     } catch (error) {
       console.error('Failed to resolve home directory:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to resolve home directory' });
@@ -730,6 +774,7 @@ export const registerFsRoutes = (app, dependencies) => {
         return res.status(403).json({ error: 'Outside workspace directory creation requires a grant' });
       } else {
         const resolved = await resolveWorkspacePathFromContext({
+          fsPromises,
           req,
           targetPath: dirPath,
           resolveProjectDirectory,
@@ -1153,6 +1198,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
     try {
       const resolved = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: filePath,
         resolveProjectDirectory,
@@ -1223,6 +1269,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
     try {
       const resolved = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: filePath,
         resolveProjectDirectory,
@@ -1330,6 +1377,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
     try {
       const resolved = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath,
         resolveProjectDirectory,
@@ -1368,6 +1416,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
     try {
       const resolvedOld = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: oldPath,
         resolveProjectDirectory,
@@ -1381,6 +1430,7 @@ export const registerFsRoutes = (app, dependencies) => {
       }
 
       const resolvedNew = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: newPath,
         resolveProjectDirectory,
@@ -1487,6 +1537,7 @@ export const registerFsRoutes = (app, dependencies) => {
       }
       const resolvedCwdCandidate = path.resolve(normalizeDirectoryPath(cwd));
       const resolvedForWorkspace = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: resolvedCwdCandidate,
         resolveProjectDirectory,
@@ -1619,7 +1670,8 @@ export const registerFsRoutes = (app, dependencies) => {
                 const child = spawn(resolveGitBinaryForSpawn(), ['check-ignore', '--', ...pathsToCheck], {
                   cwd: resolvedPath,
                   windowsHide: true,
-                  stdio: ['ignore', 'pipe', 'pipe'],
+                  // Diagnostics are unused here. An unread pipe can block Git forever.
+                  stdio: ['ignore', 'pipe', 'ignore'],
                 });
 
                 let stdout = '';
@@ -1725,6 +1777,7 @@ export const registerFsRoutes = (app, dependencies) => {
 
     try {
       const resolved = await resolveWorkspacePathFromContext({
+        fsPromises,
         req,
         targetPath: rawPath,
         resolveProjectDirectory,

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

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'events';
 import path from 'path';
 import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import * as nativeFs from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
@@ -1586,6 +1587,40 @@ describe('fs managed chats root', () => {
     expect(res.body.chatsRoot).toBe('/srv/openchamber-chats');
   });
 
+  it('fails home lookup on permission errors and retries the next request', async () => {
+    const failure = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+    let inaccessible = true;
+    const { home } = registerWithChatsRoot({ fsPromises: {
+      realpath: async directory => { if (inaccessible) throw failure; return directory; },
+    } });
+    const failed = createMockResponse();
+    await home(undefined, failed);
+    expect(failed.statusCode).toBe(500);
+    expect(failed.body).toEqual({ error: 'permission denied' });
+    inaccessible = false;
+    const recovered = createMockResponse();
+    await home(undefined, recovered);
+    expect(recovered.statusCode).toBe(200);
+    expect(recovered.body.chatsRoot).toBe('/home/user/.config/openchamber/chats');
+  });
+
+  it('keeps an accessible relocated root available when legacy alias lookup fails', async () => {
+    const { home } = registerWithChatsRoot({
+      managedChatsRoot: '/srv/chat-alias',
+      fsPromises: {
+        realpath: async directory => {
+          if (directory === '/srv/chat-alias') return '/storage/chats';
+          throw Object.assign(new Error('legacy root is inaccessible'), { code: 'EACCES' });
+        },
+      },
+    });
+    const response = createMockResponse();
+    await home(undefined, response);
+    expect(response.statusCode).toBe(200);
+    expect(response.body.canonicalChatsRoot).toBe('/storage/chats');
+    expect(response.body.canonicalLegacyChatsRoot).toBeUndefined();
+  });
+
   it('allows mkdir inside the relocated chats root outside the active workspace', async () => {
     const mkdirCalls = [];
     const { mkdir } = registerWithChatsRoot({
@@ -1605,6 +1640,22 @@ describe('fs managed chats root', () => {
     expect(mkdirCalls).toEqual(['/srv/openchamber-chats/2026-08-25/session-a']);
   });
 
+  it('accepts a canonical relocated root even when the config root cannot be resolved', async () => {
+    const { mkdir } = registerWithChatsRoot({
+      managedChatsRoot: '/srv/chat-alias',
+      fsPromises: {
+        realpath: async directory => {
+          if (directory === '/srv/chat-alias') return '/storage/chats';
+          throw Object.assign(new Error('permission denied'), { code: 'EACCES' });
+        },
+      },
+    });
+    const response = createMockResponse();
+    await mkdir({ body: { path: '/storage/chats/day/session-a' } }, response);
+    expect(response.statusCode).toBe(200);
+    expect(response.body.path).toBe('/storage/chats/day/session-a');
+  });
+
   it('still rejects mkdir outside the workspace and all managed roots', async () => {
     const { mkdir } = registerWithChatsRoot({ managedChatsRoot: '/srv/openchamber-chats' });
 
@@ -1615,3 +1666,68 @@ describe('fs managed chats root', () => {
     expect(res.body).toEqual({ error: 'Path is outside of active workspace' });
   });
 });
+
+describe('canonical managed roots with real filesystem aliases', () => {
+  const setup = async (context, { relocated = false, caseAlias = false } = {}) => {
+    const root = await nativeFs.mkdtemp(path.join(tmpdir(), 'oc-canonical-chats-'));
+    context.onTestFinished(() => nativeFs.rm(root, { recursive: true, force: true }));
+    const home = path.join(root, 'Home');
+    await nativeFs.mkdir(home);
+    const reportedHome = path.join(root, caseAlias ? 'home' : 'home-alias');
+    if (!caseAlias) await nativeFs.symlink(home, reportedHome, 'junction');
+    const config = path.join(reportedHome, '.config/openchamber');
+    const rawChats = relocated ? path.join(reportedHome, 'scratch/chats') : path.join(config, 'chats');
+    const canonicalHome = await nativeFs.realpath(home);
+    if (caseAlias && await nativeFs.realpath(reportedHome).catch(() => null) !== canonicalHome) {
+      context.skip('This volume distinguishes Home from home');
+    }
+    const canonicalChats = path.join(canonicalHome, relocated ? 'scratch/chats' : '.config/openchamber/chats');
+    const { app, getRoute } = createRouteRegistry();
+    registerFsRoutes(app, {
+      os: { homedir: () => reportedHome }, path, fsPromises: nativeFs,
+      normalizeDirectoryPath: value => value,
+      resolveProjectDirectory: async () => ({ directory: path.join(root, 'unrelated-project') }),
+      openchamberUserConfigRoot: config, managedChatsRoot: rawChats,
+    });
+    return { getRoute, canonicalHome, canonicalChats, rawChats, reportedHome };
+  };
+
+  for (const relocated of [false, true]) {
+    it(`returns canonical paths before the ${relocated ? 'relocated' : 'default'} root exists and permits its lifecycle`, async context => {
+      const { getRoute, canonicalHome, canonicalChats, rawChats, reportedHome } = await setup(context, { relocated });
+      const home = createMockResponse();
+      await getRoute('GET', '/api/fs/home')({}, home);
+      expect(home.body).toEqual({
+        home: reportedHome, chatsRoot: rawChats,
+        canonicalChatsRoot: canonicalChats,
+        canonicalLegacyChatsRoot: path.join(canonicalHome, '.config/openchamber/chats'),
+      });
+      await expect(nativeFs.stat(canonicalChats)).rejects.toMatchObject({ code: 'ENOENT' });
+
+      const directory = path.join(home.body.canonicalChatsRoot, 'day/session-a');
+      const created = createMockResponse();
+      await getRoute('POST', '/api/fs/mkdir')({ body: { path: directory } }, created);
+      expect(created.statusCode).toBe(200);
+      expect(await nativeFs.realpath(directory)).toBe(directory);
+      const deleted = createMockResponse();
+      await getRoute('POST', '/api/fs/delete')({ body: { path: directory } }, deleted);
+      expect(deleted.statusCode).toBe(200);
+      await expect(nativeFs.stat(directory)).rejects.toMatchObject({ code: 'ENOENT' });
+
+      const legacy = createMockResponse();
+      await getRoute('POST', '/api/fs/mkdir')({ body: { path: path.join(rawChats, 'legacy-session') } }, legacy);
+      expect(legacy.statusCode).toBe(200);
+      expect((await nativeFs.stat(path.join(canonicalChats, 'legacy-session'))).isDirectory()).toBe(true);
+    });
+  }
+
+  it('reports on-disk home casing on a case-insensitive macOS volume', { skip: process.platform !== 'darwin' }, async context => {
+    const { getRoute, canonicalChats, rawChats, reportedHome } = await setup(context, { caseAlias: true });
+    const response = createMockResponse();
+    await getRoute('GET', '/api/fs/home')({}, response);
+    expect(response.body).toEqual({
+      home: reportedHome, chatsRoot: rawChats,
+      canonicalChatsRoot: canonicalChats, canonicalLegacyChatsRoot: canonicalChats,
+    });
+  });
+});

package/server/lib/fs/search.js

@@ -127,7 +127,8 @@ export const createFsSearchRuntime = ({ fsPromises, path, spawn, resolveGitBinar
               const child = spawn(resolveGitBinaryForSpawn(), ['check-ignore', '--', ...pathsToCheck], {
                 cwd: dir,
                 windowsHide: true,
-                stdio: ['ignore', 'pipe', 'pipe'],
+                // Diagnostics are unused here. An unread pipe can block Git forever.
+                stdio: ['ignore', 'pipe', 'ignore'],
               });
 
               let stdout = '';

package/server/lib/git/DOCUMENTATION.md

@@ -16,7 +16,7 @@ This module provides Git repository operations for the web server runtime, inclu
 The following functions are exported and used by the web server:
 
 ### Repository Operations
-- `isGitRepository(directory)`: Check if a directory is a Git repository.
+- `isGitRepository(directory)`: Check if a directory is a Git repository. A repository whose root is the home directory or a filesystem root (`C:\`, `/`) answers `false` (`unsupportedRepositoryRootReason`): such a repository covers the whole disk, every status read would walk it, and it is nearly always an accidental `git init`. All Git surfaces then show the non-repository state for that directory.
 - `getGlobalIdentity()`: Get global Git user.name, user.email, and core.sshCommand.
 - `getCurrentIdentity(directory)`: Get local Git identity (fallback to global if not set locally).
 - `hasLocalIdentity(directory)`: Check if local Git identity is configured.
@@ -24,13 +24,16 @@ The following functions are exported and used by the web server:
 - `getRemoteUrl(directory, remoteName)`: Get URL for a specific remote.
 
 ### Status and Diff Operations
-- `getStatus(directory)`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state.
+- `getStatus(directory, { mode })`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state. `mode: 'light'` skips the diff stats. One read runs per directory at a time and at most four run across directories (`serial-refresh.js`): a call made while a read is running waits for one follow-up read that starts after the call, so no caller gets a snapshot older than its request, and every caller that arrives during one read shares that single follow-up at the widest mode any of them asked for. Clients refresh after every completed agent tool call and from several surfaces at once; on a large repository (a status read is a dozen Git processes walking the working tree) this bound is what keeps identical `git status` processes from piling up side by side. A slot is held only while the read is alive: every process the read spawns is killed after two minutes without output (one minute for the untracked-directory listing, thirty seconds for the repository probe), so a Git process that hangs, which happens on Windows, fails that read instead of holding a slot until someone kills it by hand. On Windows the listing is ended with `taskkill /T`, because the spawned `git.exe` is Git for Windows' launcher and killing it alone leaves the real `git` child walking the tree as an orphan. Untracked files are listed with `-unormal` and each new directory is then expanded to its files with a bounded `ls-files` listing (`UNTRACKED_DIRECTORY_EXPANSION_LIMIT`, 1000): up to that many files the result equals `-uall`; beyond it the directory stays one `dir/` entry, because `-uall` would walk a forgotten build or dependency directory in full on every read. A nested repository stays a `dir/` entry as before.
+- `getTrackingBranch(directory)`: Upstream of the checked-out branch as `remote/branch` (the same value as `status.tracking`, including an upstream whose remote ref is gone), or `null` when HEAD is detached or unborn or no upstream is configured. Reads refs and config only. Callers that need just the tracking name (GitHub PR status polling, PR creation) use this instead of `getStatus`.
 - `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.
+- `getPathDiff(directory, { path, staged, contextLines })`: `getDiff` for one path, returning `{ diff, submodule }`. `submodule` is `null` for ordinary paths. For a gitlink it is `{ headCommit, indexCommit, worktreeCommit, hasTrackedChanges, hasUntrackedFiles, hasConflict }`, because a submodule that only gained untracked files shows as modified in status while its patch is empty. `worktreeCommit` is `null` when the submodule is not checked out. An unmerged gitlink has no single index commit, so it reports `hasConflict: true` with `indexCommit: null`. Exposed as `GET /api/git/diff`.
+- Paths come from an earlier status listing and can stop resolving. Per-path operations reject with `error.code`: `path_not_found` when the path is absent from the working tree, index, and HEAD (for example, a file removed after the listing), `nested_repository` when the path is a directory holding its own `.git` that is not a submodule (status lists it as `dir/`), and `untracked_directory` when the path is a directory status kept as one `dir/` entry because it holds more untracked files than the expansion bound. `GET /api/git/diff` and `GET /api/git/file-diff` answer these with 404, 422 and 422 and a `{ error, code }` body instead of 500. Entry existence is read from `ls-files --stage` and `ls-tree` modes, not `cat-file -e`: a gitlink's commit is not in the parent's object store, and simple-git reports that silent exit 1 as success.
 - `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).
+- `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). For a submodule, both sides are Git's `Subproject commit <sha>` text (HEAD against the worktree checkout, or against the index when `staged`) and the result carries the same `submodule` state as `getPathDiff`; other paths return no `submodule`, which the route sends as `null`.
 - `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.
 - `collectDiffs(directory, files)`: Collect diff output for multiple files.
@@ -50,12 +53,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 `openchamber: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
@@ -72,6 +84,17 @@ bootstrap, tracking is left unset rather than writing `branch.*.remote` /
 - `removeRemote(directory, options)`: Remove a configured remote (except `origin`).
 - `deleteRemoteBranch(directory, options)`: Delete a remote branch.
 
+`push` leaves an unspecified destination to Git, including `branch.<name>.pushRemote`
+and `remote.pushDefault`. Its missing-upstream fallback uses that same destination;
+an explicit remote overrides configuration. `pushed` contains only refs changed by
+the operation, derived from Git's porcelain flags, including first publication,
+fast-forward and forced updates. Each entry's `remote` is the destination remote
+name, not a ref. A successful no-op returns an empty array; rejected pushes throw.
+Commit & Push and Sync share the same fetch/pull/push flow in web, Electron and
+mobile, and never infer publication from an upstream `ahead` count. Fetch follows
+the selected upstream while push routing remains independent. VS Code does not
+mount these Git panels and keeps its separate extension-host Git implementation.
+
 ### 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 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`.
@@ -99,7 +122,7 @@ bootstrap, tracking is left unset rather than writing `branch.*.remote` /
 
 The following functions are internal helpers used by exported functions:
 - `buildSshCommand(sshKeyPath)`: Build SSH command string for git config.
-- `buildGitEnv()`: Build Git environment with SSH_AUTH_SOCK resolution.
+- `buildGitEnv()`: Build Git environment with SSH_AUTH_SOCK resolution and `GIT_TERMINAL_PROMPT=0` (unless the server was started with it set): the server has no terminal a user could answer, so a Git command that would ask for a username or password fails instead of waiting forever on a console nobody sees. Credential helpers, including GUI ones, still run before Git would prompt.
 - `createGit(directory)`: Create simple-git instance with environment.
 - `normalizeDirectoryPath(value)`: Normalize directory paths (supports ~ expansion).
 - `cleanBranchName(branch)`: Remove refs/heads/ or refs/ prefixes.
@@ -121,7 +144,7 @@ The following functions are internal helpers used by exported functions:
 - `upstreamComparison`: Optional comparison against `upstream/<current-branch>`, with `{ remote, branch, ahead, behind }`.
 - `files`: Array of file objects with `path`, `index`, `working_dir` status codes.
 - `isClean`: Boolean indicating if working tree is clean.
-- `diffStats`: Object mapping file paths to `{ insertions, deletions }`.
+- `diffStats`: Scope-aware per-file line stats, `{ staged, working }`. `staged` is HEAD → index (`git diff --cached --numstat`), `working` is index → working tree (`git diff --numstat`). A partially staged file appears in both maps with its own scope's counts; the two are never summed together. Untracked and working-tree-added files are counted into `working`; files added to the index are counted into `staged`.
 - `mergeInProgress`: Object with `{ head, message }` if merge in progress.
 - `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress.
 
@@ -157,6 +180,7 @@ The following functions are internal helpers used by exported functions:
   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.
+- `status.diffStats` follows the same scopes (`staged`, `working`), so a staged row shows HEAD → index counts and an unstaged row shows index → working-tree counts. A file with edits in both scopes reports each part in its own row instead of one combined total.
 - 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.
 - `stageFiles` remains supported for callers that need to stage a selected unstaged subset as part of commit. In that mode the server temporarily unstages unrelated index entries, stages `stageFiles`, commits from the index, then restores temporarily unstaged entries.

package/server/lib/git/routes.js

@@ -1,12 +1,25 @@
-export function registerGitRoutes(app) {
+export function registerGitRoutes(app, { emitWorktreeChanged } = {}) {
   let gitLibraries = null;
   const getGitLibraries = async () => {
     if (!gitLibraries) {
       gitLibraries = await import('./index.js');
+      if (emitWorktreeChanged) {
+        gitLibraries.subscribeWorktreeTopologyChanges(emitWorktreeChanged);
+      }
     }
     return gitLibraries;
   };
 
+  // A path from an earlier status listing that no longer resolves is a stale
+  // row or a nested repository, not a server fault.
+  const GIT_PATH_ERROR_STATUS = new Map([['path_not_found', 404], ['nested_repository', 422], ['untracked_directory', 422]]);
+  const sendGitPathError = (res, error) => {
+    const status = GIT_PATH_ERROR_STATUS.get(error?.code);
+    if (!status) return false;
+    res.status(status).json({ error: error.message, code: error.code });
+    return true;
+  };
+
   const resolveDirectoryQuery = (value, preserveWhitespace = false) => {
     const raw = Array.isArray(value) ? value[0] : value;
     if (typeof raw !== 'string') {
@@ -220,7 +233,7 @@ export function registerGitRoutes(app) {
   });
 
   app.get('/api/git/status', async (req, res) => {
-    const { getStatus, isGitRepository } = await getGitLibraries();
+    const { getStatus, isGitRepository, observeWorktreeTopology } = await getGitLibraries();
 
     try {
       const directory = resolveDirectoryQuery(req.query.directory);
@@ -233,6 +246,11 @@ export function registerGitRoutes(app) {
         return res.json(nonRepoStatusPayload());
       }
 
+      // Clients ask for status while they work in a repository, so this is
+      // where an externally added or removed worktree gets noticed. It runs
+      // beside the status call and never delays or fails the response.
+      void observeWorktreeTopology(directory);
+
       const mode = req.query.mode === 'light' ? 'light' : undefined;
       const status = await getStatus(directory, { mode });
       res.json(status);
@@ -337,7 +355,7 @@ export function registerGitRoutes(app) {
   });
 
   app.get('/api/git/diff', async (req, res) => {
-    const { getDiff } = await getGitLibraries();
+    const { getPathDiff } = await getGitLibraries();
     try {
       const directory = req.query.directory;
       if (!directory) {
@@ -352,14 +370,15 @@ export function registerGitRoutes(app) {
       const staged = req.query.staged === 'true';
       const context = req.query.context ? parseInt(String(req.query.context), 10) : undefined;
 
-      const diff = await getDiff(directory, {
+      const { diff, submodule } = await getPathDiff(directory, {
         path,
         staged,
         contextLines: Number.isFinite(context) ? context : 3,
       });
 
-      res.json({ diff });
+      res.json({ diff, submodule });
     } catch (error) {
+      if (sendGitPathError(res, error)) return;
       console.error('Failed to get git diff:', error);
       res.status(500).json({ error: error.message || 'Failed to get git diff' });
     }
@@ -390,8 +409,10 @@ export function registerGitRoutes(app) {
         modified: result.modified,
         path: result.path,
         isBinary: Boolean(result.isBinary),
+        submodule: result.submodule ?? null,
       });
     } catch (error) {
+      if (sendGitPathError(res, error)) return;
       console.error('Failed to get git file diff:', error);
       res.status(500).json({ error: error.message || 'Failed to get git file diff' });
     }
@@ -1078,7 +1099,7 @@ export function registerGitRoutes(app) {
   });
 
   app.get('/api/git/worktrees', async (req, res) => {
-    const { getWorktrees } = await getGitLibraries();
+    const { getWorktrees, observeWorktreeTopology } = await getGitLibraries();
     try {
       const directory = req.query.directory;
       if (!directory) {
@@ -1086,13 +1107,18 @@ export function registerGitRoutes(app) {
       }
 
       const worktrees = await getWorktrees(directory);
+      // A repository always lists at least its primary worktree; an empty
+      // list means "not a repository" and has no topology to track.
+      if (worktrees.length > 0) {
+        void observeWorktreeTopology(directory);
+      }
       res.json(worktrees);
     } catch (error) {
-      // Worktrees are an optional feature. Avoid repeated 500s (and repeated client retries)
-      // when the directory isn't a git repo or uses shell shorthand like "~/".
-      console.warn('Failed to get worktrees, returning empty list:', error?.message || error);
-      res.setHeader('X-OpenChamber-Warning', 'git worktrees unavailable');
-      res.json([]);
+      // A directory outside any repository still answers `[]` from getWorktrees.
+      // Anything else is a real failure the client must not mistake for "no
+      // worktrees", or it would drop the ones it already knows.
+      console.error('Failed to get worktrees:', error);
+      res.status(500).json({ error: error.message || 'Failed to get worktrees' });
     }
   });
 

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();