@vantran-se/openchamber-web 1.23.1 → 1.24.3

package/server/lib/fs/DOCUMENTATION.md

@@ -36,6 +36,14 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
   - Returns `{ searchFilesystemFiles(rootPath, options) }`.
   - Supports fuzzy matching, hidden-file handling, and optional `git check-ignore` filtering.
 
+Both search and directory listing discard `git check-ignore` stderr at spawn.
+They consume stdout for ignore matches. Never create an unread stderr pipe:
+Git diagnostics can fill it and block the child indefinitely, so repeated
+searches accumulate live Git processes. `git-process.test.js` exercises both
+paths with real OS pipes, twelve concurrent checks, and 2 MiB of diagnostics
+per child. Successful completion must preserve ignore filtering and reap all
+twelve children.
+
 ## Composition contract with `index.js`
 - `index.js` provides composition-time dependencies only (platform primitives + callbacks such as `resolveProjectDirectory`, `normalizeDirectoryPath`, and `buildAugmentedPath`).
 - `index.js` no longer owns FS route handlers or FS exec job state.
@@ -43,7 +51,8 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
 ## Notes for contributors
 - Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
 - Workspace checks accept, besides the active workspace and its worktrees, the **managed roots**: the OpenChamber config root and the managed chats root (`managedChatsRoot` dependency; `OPENCHAMBER_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).
+- `GET /api/fs/home` preserves `{ home, chatsRoot }` and adds `canonicalChatsRoot` and `canonicalLegacyChatsRoot`, resolved by the server's filesystem. If a root does not exist yet, it resolves the nearest existing ancestor and appends the missing segments, without creating directories. Errors resolving the configured root fail the request. A failed legacy lookup warns and omits only that optional alias, retaining exact legacy matching without blocking an accessible relocated root. Clients use confirmed aliases for exact membership while keeping the original roots as folder/scope identities. `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).
+- Workspace authorization accepts both the configured managed paths and their filesystem-confirmed canonical roots. Canonical lookup runs only when lexical workspace/managed-root checks fail. One failed managed-root lookup cannot reject an independently authorized root or worktree. Path comparisons remain case-sensitive on POSIX: distinct Linux directories named `chats` and `Chats` never become aliases through string folding. Shared UI keeps exact root membership for classification and directory cleanup.
 - 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.

package/server/lib/fs/git-process.test.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createFsSearchRuntime } from './search.js';
+import { registerFsRoutes } from './routes.js';
+
+// Use real OS pipes. A mocked data event cannot reproduce a full stderr pipe.
+const noisyGit = `
+  const fs = require('node:fs');
+  const chunk = Buffer.alloc(65536, 'x');
+  for (let i = 0; i < 32; i++) fs.writeSync(2, chunk);
+  fs.writeSync(1, 'ignored.txt\\n');
+`;
+
+describe('filesystem Git process ownership', () => {
+  for (const operation of ['search', 'list']) {
+    it(`${operation} completes repeated checks with more diagnostics than an OS pipe can hold`, async () => {
+      const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-git-pipes-'));
+      const children = [];
+      const exits = [];
+      const launch = (binary, args, options) => {
+        expect(binary).toBe('git');
+        expect(args).toContain('check-ignore');
+        expect(args).toContain('ignored.txt');
+        const child = spawn(process.execPath, ['-e', noisyGit], options);
+        children.push(child);
+        exits.push(new Promise((resolve) => child.once('close', (code) => resolve(code))));
+        return child;
+      };
+      let deadline;
+      try {
+        await fs.writeFile(path.join(root, 'ignored.txt'), 'ignored');
+        await fs.writeFile(path.join(root, 'visible.txt'), 'visible');
+        const dependencies = { fsPromises: fs, path, spawn: launch, resolveGitBinaryForSpawn: () => 'git' };
+        const search = createFsSearchRuntime(dependencies);
+        const routes = new Map();
+        registerFsRoutes({
+          get(route, handler) { routes.set(route, handler); }, post() {}, put() {}, delete() {},
+        }, {
+          ...dependencies, os, crypto, normalizeDirectoryPath: (value) => value,
+          resolveProjectDirectory: async () => ({ directory: root }),
+          buildAugmentedPath: () => process.env.PATH,
+          openchamberUserConfigRoot: root,
+          gitCheckIgnoreTimeoutMs: 10_000,
+        });
+        const work = Array.from({ length: 12 }, async () => {
+          if (operation === 'search') {
+            const files = await search.searchFilesystemFiles(root, { query: '', limit: 10, respectGitignore: true });
+            expect(files.map((file) => file.name)).toEqual(['visible.txt']);
+          } else {
+            const response = { status() { return this; }, json(value) { this.body = value; } };
+            await routes.get('/api/fs/list')({ query: { path: root, respectGitignore: 'true' } }, response);
+            expect(response.body.entries.map((entry) => entry.name)).toEqual(['visible.txt']);
+          }
+        });
+        await Promise.race([
+          Promise.all(work),
+          new Promise((_, reject) => { deadline = setTimeout(() => reject(new Error('Git blocked on unread diagnostics')), 5000); }),
+        ]);
+        expect(children).toHaveLength(12);
+        expect(await Promise.all(exits)).toEqual(Array(12).fill(0));
+        for (const child of children) expect(child.exitCode).toBe(0);
+      } finally {
+        clearTimeout(deadline);
+        for (const child of children) {
+          child.stderr?.resume();
+          if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+        }
+        await Promise.all(exits);
+        await fs.rm(root, { recursive: true, force: true });
+      }
+    }, 15_000);
+  }
+});

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.
@@ -81,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`.
@@ -108,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.
@@ -130,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.
 
@@ -166,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

@@ -10,6 +10,16 @@ export function registerGitRoutes(app, { 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') {
@@ -345,7 +355,7 @@ export function registerGitRoutes(app, { emitWorktreeChanged } = {}) {
   });
 
   app.get('/api/git/diff', async (req, res) => {
-    const { getDiff } = await getGitLibraries();
+    const { getPathDiff } = await getGitLibraries();
     try {
       const directory = req.query.directory;
       if (!directory) {
@@ -360,14 +370,15 @@ export function registerGitRoutes(app, { emitWorktreeChanged } = {}) {
       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' });
     }
@@ -398,8 +409,10 @@ export function registerGitRoutes(app, { emitWorktreeChanged } = {}) {
         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' });
     }

package/server/lib/git/serial-refresh.js

@@ -0,0 +1,93 @@
+// Runs one refresh per key at a time and bounds how many keys refresh at once.
+//
+// A request that arrives while a refresh for its key is running does not join
+// that run: the run may have read the working tree before the change the
+// caller just made. Instead the request waits for one follow-up run that starts
+// after the current one finishes, so every caller receives a result at least as
+// fresh as its own arrival. All requests that arrive during one run share the
+// same follow-up, which caps the work per key at "one running, one pending"
+// no matter how many callers ask.
+
+export function createSerialRefresh({ maxConcurrent = Number.POSITIVE_INFINITY } = {}) {
+  const runs = new Map();
+  let running = 0;
+  const waiting = [];
+
+  const acquire = () => new Promise((resolve) => {
+    if (running < maxConcurrent) {
+      running += 1;
+      resolve();
+      return;
+    }
+    waiting.push(resolve);
+  });
+
+  const release = () => {
+    const next = waiting.shift();
+    if (next) {
+      next();
+      return;
+    }
+    running -= 1;
+  };
+
+  const start = (key, requests, execute, deferred) => {
+    const run = { follower: null };
+    runs.set(key, run);
+    const promise = (async () => {
+      await acquire();
+      try {
+        return await execute(requests);
+      } finally {
+        release();
+      }
+    })();
+    if (deferred) {
+      promise.then(deferred.resolve, deferred.reject);
+    }
+    promise
+      .catch(() => undefined)
+      .then(() => {
+        if (runs.get(key) !== run) return;
+        if (run.follower) {
+          const follower = run.follower;
+          start(key, follower.requests, follower.execute, follower);
+          return;
+        }
+        runs.delete(key);
+      });
+    return promise;
+  };
+
+  return {
+    /**
+     * @template TRequest, TResult
+     * @param {string} key
+     * @param {TRequest} request
+     * @param {(requests: TRequest[]) => Promise<TResult>} execute receives every
+     *   request the run answers, so it can widen the work to satisfy all of them
+     * @returns {Promise<TResult>}
+     */
+    run(key, request, execute) {
+      const current = runs.get(key);
+      if (!current) {
+        return start(key, [request], execute);
+      }
+      if (!current.follower) {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+          resolve = res;
+          reject = rej;
+        });
+        current.follower = { requests: [], execute, promise, resolve, reject };
+      }
+      current.follower.requests.push(request);
+      return current.follower.promise;
+    },
+    /** Keys with a running or pending refresh. Exposed for tests. */
+    get activeKeys() {
+      return Array.from(runs.keys());
+    },
+  };
+}