Merge #543: configurable git status repository limit and git timeout, unreadable repositories stay listed

# Conflicts: # src/web/public/styles.css
2026-10-10 17:29:41 +02:00 · 2026-10-09 05:32:55 +02:00
parent 1105d646f3 3ae22f64a4
commit 1ee566e7a1
13 changed files with 429 additions and 48 deletions
@@ -52,7 +52,10 @@ import { gitNonInteractiveEnv, redactGitCredentials } from './git-clone.js';

 const execFileAsync = promisify(execFile);

-const GIT_TIMEOUT_MS = 10_000;
+/** How long one git command may run, unless the caller passes `timeoutMs` (a slow network share needs more). */
+export const DEFAULT_GIT_TIMEOUT_MS = 30_000;
+export const MIN_GIT_TIMEOUT_MS = 5_000;
+export const MAX_GIT_TIMEOUT_MS = 120_000;
 /** `git status` on a huge tree can print a lot; a bound on what we will hold. */
 const MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 /** Max file rows returned. The counts stay exact. */
@@ -258,9 +261,9 @@ export function parseCommitLog(text: string): GitCommitEntry[] {
 // ---------------------------------------------------------------------------

 /** Runs `git <args>` in `cwd` and returns stdout. Injected so the cache and error paths test without git. */
-export type GitRunner = (cwd: string, args: string[]) => Promise<string>;
+export type GitRunner = (cwd: string, args: string[], opts?: { timeoutMs?: number }) => Promise<string>;

-export const runGit: GitRunner = async (cwd, args) => {
+export const runGit: GitRunner = async (cwd, args, opts) => {
  const { stdout } = await execFileAsync(
    'git',
    // --no-optional-locks: never touch the index just to look. core.fsmonitor=false: do not start or
@@ -269,7 +272,7 @@ export const runGit: GitRunner = async (cwd, args) => {
    ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'log.showSignature=false', ...args],
    {
      cwd,
-      timeout: GIT_TIMEOUT_MS,
+      timeout: opts?.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
      maxBuffer: MAX_OUTPUT_BYTES,
      env: { ...gitNonInteractiveEnv(), LC_ALL: 'C', LANG: 'C', GIT_OPTIONAL_LOCKS: '0' },
    }
@@ -288,17 +291,14 @@ function describeFailure(err: unknown): { notARepo: boolean; message: string } {
  return { notARepo: false, message: redactGitCredentials(text).slice(0, 300) };
 }

-async function collect(cwd: string, git: GitRunner): Promise<GitWorkspaceStatus> {
+async function collect(cwd: string, git: GitRunner, timeoutMs?: number): Promise<GitWorkspaceStatus> {
  let statusText: string;
  try {
-    statusText = await git(cwd, [
-      'status',
-      '--porcelain=v2',
-      '--branch',
-      '-z',
-      '--untracked-files=normal',
-      '--ignore-submodules=dirty',
-    ]);
+    statusText = await git(
+      cwd,
+      ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=normal', '--ignore-submodules=dirty'],
+      { timeoutMs }
+    );
  } catch (err) {
    const f = describeFailure(err);
    return f.notARepo ? emptyStatus('not-a-repo') : emptyStatus('error', { error: f.message });
@@ -307,7 +307,7 @@ async function collect(cwd: string, git: GitRunner): Promise<GitWorkspaceStatus>

  const safe = async (args: string[]): Promise<string> => {
    try {
-      return await git(cwd, args);
+      return await git(cwd, args, { timeoutMs });
    } catch {
      return '';
    }
@@ -415,10 +415,12 @@ async function singleFlight<T>(
 */
 export async function getGitWorkspaceStatus(
  cwd: string,
-  opts: { git?: GitRunner; now?: () => number; fresh?: boolean } = {}
+  opts: { git?: GitRunner; now?: () => number; fresh?: boolean; timeoutMs?: number } = {}
 ): Promise<GitWorkspaceStatus> {
  const git = opts.git ?? runGit;
-  return singleFlight(cache, cwd, { now: opts.now ?? Date.now, fresh: opts.fresh }, () => collect(cwd, git));
+  return singleFlight(cache, cwd, { now: opts.now ?? Date.now, fresh: opts.fresh }, () =>
+    collect(cwd, git, opts.timeoutMs)
+  );
 }

 type RepoToplevel = { state: 'ok'; root: string } | { state: 'not-a-repo' } | { state: 'error'; error: string };
@@ -427,12 +429,12 @@ const toplevelCache = new Map<string, CacheEntry<RepoToplevel>>();
 /** The root of the repository enclosing `cwd` (git walks up), from one cheap `rev-parse`. Cached like the status. */
 function enclosingRepoRoot(
  cwd: string,
-  opts: { git?: GitRunner; now?: () => number; fresh?: boolean }
+  opts: { git?: GitRunner; now?: () => number; fresh?: boolean; timeoutMs?: number }
 ): Promise<RepoToplevel> {
  const git = opts.git ?? runGit;
  return singleFlight(toplevelCache, cwd, { now: opts.now ?? Date.now, fresh: opts.fresh }, async () => {
    try {
-      const root = (await git(cwd, ['rev-parse', '--show-toplevel'])).trim();
+      const root = (await git(cwd, ['rev-parse', '--show-toplevel'], { timeoutMs: opts.timeoutMs })).trim();
      return root ? { state: 'ok', root } : { state: 'not-a-repo' };
    } catch (err) {
      const f = describeFailure(err);
@@ -451,6 +453,16 @@ const DISCOVERY_MAX_DEPTH = 2;
 const DISCOVERY_MAX_ENTRIES = 300;
 /** Repositories reported for one workspace. */
 export const MAX_REPOS = 12;
+/** The most repositories a caller may ask for: each one costs several git processes per poll. */
+export const MAX_REPOS_LIMIT = 50;
+
+/** `value` as a whole number within [min, max], else `fallback`. For options that arrive as untrusted query strings. */
+export function clampInt(value: unknown, min: number, max: number, fallback: number): number {
+  // An empty string is "not given", not 0 (Number('') is 0, which would clamp to the minimum).
+  const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
 /** The list of repositories under a folder changes rarely, so it is re-scanned far less often than status. */
 const DISCOVERY_TTL_MS = 30_000;
 /** Folders that are never worth descending into when looking for projects. */
@@ -472,8 +484,10 @@ export interface GitWorkspaceOverview {
  reason?: 'remote' | 'docker';
  error?: string;
  repos: GitRepoEntry[];
-  /** More than `MAX_REPOS` repositories were found; only the first are reported. */
+  /** More than `repoLimit` repositories were found; only the first are reported. */
  reposTruncated: boolean;
+  /** The most repositories this overview would list (the caller's setting, or `MAX_REPOS`). */
+  repoLimit?: number;
  checkedAt: number;
 }

@@ -553,7 +567,8 @@ async function readDirBounded(dir: string): Promise<import('node:fs').Dirent[] |
 /** Repositories up to `DISCOVERY_MAX_DEPTH` levels below `cwd`, nearest and alphabetical first. Never follows symlinks. */
 export async function discoverChildRepos(
  cwd: string,
-  excludeRealRoots: string[] = []
+  excludeRealRoots: string[] = [],
+  maxRepos: number = MAX_REPOS
 ): Promise<{ dirs: string[]; truncated: boolean }> {
  const found: string[] = [];
  let level = [cwd];
@@ -576,7 +591,7 @@ export async function discoverChildRepos(
    }
    level = next;
  }
-  return { dirs: found.slice(0, MAX_REPOS), truncated: found.length > MAX_REPOS };
+  return { dirs: found.slice(0, maxRepos), truncated: found.length > maxRepos };
 }

 const discoveryCache = new Map<string, { at: number; value: { dirs: string[]; truncated: boolean } }>();
@@ -602,13 +617,28 @@ export interface GitOverviewOptions {
  home?: string;
  /** Docker case workspaces (host paths): repositories at or inside these are never inspected. */
  dockerWorkspaces?: string[];
+  /** How many repositories to report below a folder that is not itself a repository (1 to `MAX_REPOS_LIMIT`, default `MAX_REPOS`). */
+  maxRepos?: number;
+  /** How long one git command may run, in ms (`MIN_GIT_TIMEOUT_MS` to `MAX_GIT_TIMEOUT_MS`, default `DEFAULT_GIT_TIMEOUT_MS`). */
+  timeoutMs?: number;
+}
+
+/** The repository limit and git timeout an overview was computed with, from untrusted options. */
+export function resolveOverviewLimits(opts: { maxRepos?: unknown; timeoutMs?: unknown }): {
+  maxRepos: number;
+  timeoutMs: number;
+} {
+  return {
+    maxRepos: clampInt(opts.maxRepos, 1, MAX_REPOS_LIMIT, MAX_REPOS),
+    timeoutMs: clampInt(opts.timeoutMs, MIN_GIT_TIMEOUT_MS, MAX_GIT_TIMEOUT_MS, DEFAULT_GIT_TIMEOUT_MS),
+  };
 }

 type WorkspaceRepos =
  | { kind: 'docker' }
  | { kind: 'error'; error: string }
  | { kind: 'enclosing'; root: string }
-  | { kind: 'children'; dirs: string[]; truncated: boolean };
+  | { kind: 'children'; dirs: string[]; truncated: boolean; limit: number };

 /**
 * WHICH repositories belong to the workspace (the module header has the rules), without a full
@@ -617,6 +647,7 @@ type WorkspaceRepos =
 */
 async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Promise<WorkspaceRepos> {
  const now = opts.now ?? Date.now;
+  const { maxRepos, timeoutMs } = resolveOverviewLimits(opts);
  const dockerRoots = await realAll(opts.dockerWorkspaces ?? []);
  // Checked BEFORE any git runs: git walks up from cwd, and a repository the container can write to
  // could carry config (a clean filter) that runs on the host.
@@ -624,7 +655,7 @@ async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Pro
  // The enclosing repository is identified before its full status runs, so an unrelated one above the
  // workspace (a dotfiles repo in $HOME) costs one rev-parse, and its status failing cannot hide the
  // repositories below.
-  const top = await enclosingRepoRoot(cwd, opts);
+  const top = await enclosingRepoRoot(cwd, { ...opts, timeoutMs });
  if (top.state === 'error') return { kind: 'error', error: top.error };
  if (top.state === 'ok') {
    if (await isInsideAny(top.root, dockerRoots)) return { kind: 'docker' };
@@ -633,18 +664,20 @@ async function resolveWorkspaceRepos(cwd: string, opts: GitOverviewOptions): Pro
  }

  // Not inside a repository of this workspace: look below for projects.
-  const hit = discoveryCache.get(cwd);
+  // Keyed by the limit too: a list cut at 12 must not answer a request for 30.
+  const discoveryKey = `${cwd}\0${maxRepos}`;
+  const hit = discoveryCache.get(discoveryKey);
  let found: { dirs: string[]; truncated: boolean };
  if (!opts.fresh && hit && now() - hit.at < DISCOVERY_TTL_MS) found = hit.value;
  else {
-    found = await discoverChildRepos(cwd, dockerRoots);
-    discoveryCache.set(cwd, { at: now(), value: found });
+    found = await discoverChildRepos(cwd, dockerRoots, maxRepos);
+    discoveryCache.set(discoveryKey, { at: now(), value: found });
    if (discoveryCache.size > CACHE_MAX_ENTRIES) discoveryCache.delete(discoveryCache.keys().next().value as string);
  }
  // The cached list can predate a Docker case linked since: filter it against the roots as they are NOW.
  const dirs: string[] = [];
  for (const dir of found.dirs) if (!(await isInsideAny(dir, dockerRoots))) dirs.push(dir);
-  return { kind: 'children', dirs, truncated: found.truncated };
+  return { kind: 'children', dirs, truncated: found.truncated, limit: maxRepos };
 }

 /**
@@ -659,7 +692,7 @@ export async function getGitWorkspaceOverview(
  if (where.kind === 'docker') return emptyOverview('unsupported', { reason: 'docker' });
  if (where.kind === 'error') return emptyOverview('error', { error: where.error });
  if (where.kind === 'enclosing') {
-    const primary = await getGitWorkspaceStatus(cwd, opts);
+    const primary = await getGitWorkspaceStatus(cwd, { ...opts, timeoutMs: resolveOverviewLimits(opts).timeoutMs });
    if (primary.state === 'error') return emptyOverview('error', { error: primary.error });
    if (primary.state !== 'ok') return emptyOverview('not-a-repo');
    const root = primary.repoRoot ?? where.root;
@@ -671,14 +704,21 @@ export async function getGitWorkspaceOverview(
    };
  }

-  const statuses = await mapLimited(where.dirs, STATUS_CONCURRENCY, (dir) => getGitWorkspaceStatus(dir, opts));
+  const timeoutMs = resolveOverviewLimits(opts).timeoutMs;
+  const statuses = await mapLimited(where.dirs, STATUS_CONCURRENCY, (dir) =>
+    getGitWorkspaceStatus(dir, { ...opts, timeoutMs })
+  );
  const repos: GitRepoEntry[] = [];
  where.dirs.forEach((dir, i) => {
    const status = statuses[i];
-    if (status.state === 'ok') repos.push({ name: basename(dir), path: relative(cwd, dir), status });
+    // A repository git could not read (a timeout on a slow share, a broken worktree) stays in the
+    // list with its error, so it is visible that something is not being reported; only a folder
+    // that turned out not to be a repository after all is left out.
+    if (status.state === 'ok' || status.state === 'error')
+      repos.push({ name: basename(dir), path: relative(cwd, dir), status });
  });
  if (!repos.length) return emptyOverview('not-a-repo');
-  return { state: 'ok', repos, reposTruncated: where.truncated, checkedAt: Date.now() };
+  return { state: 'ok', repos, reposTruncated: where.truncated, repoLimit: where.limit, checkedAt: Date.now() };
 }

 /**
@@ -726,7 +766,7 @@ export function isSafeRepoRelativePath(p: string): boolean {
 export async function getGitFileDiff(
  repoRoot: string,
  file: { path: string; origPath?: string; kind: GitFileKind },
-  opts: { git?: GitRunner } = {}
+  opts: { git?: GitRunner; timeoutMs?: number } = {}
 ): Promise<GitFileDiff> {
  if (!isSafeRepoRelativePath(file.path) || (file.origPath && !isSafeRepoRelativePath(file.origPath))) {
    throw new Error('Invalid path');
@@ -742,7 +782,7 @@ export async function getGitFileDiff(
  let out: string;
  let cutShort = false;
  try {
-    out = await git(repoRoot, args);
+    out = await git(repoRoot, args, { timeoutMs: opts.timeoutMs });
  } catch (err) {
    const e = err as { code?: unknown; stdout?: unknown };
    // `--no-index` exits 1 when the files differ, which is the normal case for it.
@@ -117,7 +117,9 @@ Object.assign(CodemanApp.prototype, {
    const epoch = (this._gitStatusEpoch = (this._gitStatusEpoch || 0) + 1);
    this._gitStatusFetchedAt = Date.now();
    try {
-      const data = await this._apiJson(`/api/sessions/${encodeURIComponent(sid)}/git-status${fresh ? '?fresh=1' : ''}`);
+      const query = new URLSearchParams(this.gitStatusLimits());
+      if (fresh) query.set('fresh', '1');
+      const data = await this._apiJson(`/api/sessions/${encodeURIComponent(sid)}/git-status?${query}`);
      if (epoch !== this._gitStatusEpoch || sid !== this.activeSessionId || !this.isGitStatusEnabled()) return;
      this._gitStatus = data ? { sessionId: sid, data } : null;
    } catch {
@@ -131,6 +133,23 @@ Object.assign(CodemanApp.prototype, {
    if (this._isGitStatusPanelOpen()) this._renderGitStatusPanel();
  },

+  /**
+   * How many repositories to list below a folder that is not itself a repository, and how long one
+   * git command may run, in seconds (Settings → Bottom bar, per device). The server clamps both again.
+   */
+  gitStatusLimits() {
+    const settings = this.loadAppSettingsFromStorage();
+    const defaults = this.getDefaultSettings();
+    const num = (v, min, max, fallback) => {
+      const n = Math.trunc(Number(v));
+      return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+    };
+    return {
+      maxRepos: num(settings.gitStatusMaxRepos ?? defaults.gitStatusMaxRepos, 1, 50, 12),
+      timeout: num(settings.gitStatusTimeoutSeconds ?? defaults.gitStatusTimeoutSeconds, 5, 120, 30),
+    };
+  },
+
  /** Whether the Git window groups changed files under collapsible folders (default on). */
  isGitStatusTree() {
    const settings = this.loadAppSettingsFromStorage();
@@ -150,13 +169,16 @@ Object.assign(CodemanApp.prototype, {
    let uncommitted = 0;
    let unpushed = 0;
    let conflicted = 0;
+    let unreadable = 0;
    for (const r of overview.repos) {
+      if (r.status.state === 'error') unreadable += 1;
      uncommitted += r.status.counts.uncommitted;
      unpushed += r.status.unpushedCount;
      conflicted += r.status.counts.conflicted;
    }
-    const tone = conflicted > 0 ? 'conflict' : uncommitted > 0 || unpushed > 0 ? 'dirty' : 'clean';
-    return { uncommitted, unpushed, conflicted, repos: overview.repos.length, tone };
+    // A repository that could not be read is not "clean": it must not let the indicator say ✓.
+    const tone = conflicted > 0 ? 'conflict' : uncommitted > 0 || unpushed > 0 || unreadable > 0 ? 'dirty' : 'clean';
+    return { uncommitted, unpushed, conflicted, unreadable, repos: overview.repos.length, tone };
  },

  /** One sentence for the tooltip and the screen-reader label. */
@@ -168,6 +190,8 @@ Object.assign(CodemanApp.prototype, {
    if (sum.conflicted) bits.push(plural(sum.conflicted, 'file with a merge conflict', 'files with merge conflicts'));
    if (sum.uncommitted) bits.push(plural(sum.uncommitted, 'uncommitted file', 'uncommitted files'));
    if (sum.unpushed) bits.push(plural(sum.unpushed, 'commit not pushed', 'commits not pushed'));
+    if (sum.unreadable)
+      bits.push(plural(sum.unreadable, 'repository could not be read', 'repositories could not be read'));
    if (!bits.length) bits.push('everything is committed and pushed');
    let where;
    if (sum.repos > 1) where = `${sum.repos} repositories`;
@@ -196,6 +220,7 @@ Object.assign(CodemanApp.prototype, {
    if (sum.conflicted) parts.push(`⚠ ${sum.conflicted}`);
    if (sum.uncommitted) parts.push(`● ${sum.uncommitted}`);
    if (sum.unpushed) parts.push(`↑ ${sum.unpushed}`);
+    if (sum.unreadable) parts.push(`? ${sum.unreadable}`);
    if (!parts.length) parts.push('✓');
    if (label) label.textContent = parts.join('  ');
    const sentence = this._gitStatusSentence(data);
@@ -343,7 +368,11 @@ Object.assign(CodemanApp.prototype, {
      for (const r of repos) body.append(this._gitRepoSection(r));
      if (overview.reposTruncated) {
        body.append(
-          el('div', 'git-status-more', `Showing the first ${repos.length} repositories found under this folder.`)
+          el(
+            'div',
+            'git-status-more',
+            `Showing the first ${overview.repoLimit || repos.length} of more than ${overview.repoLimit || repos.length} repositories under this folder. Raise “Git status: max repositories” in Settings → Bottom bar to see more.`
+          )
        );
      }
    }
@@ -364,6 +393,16 @@ Object.assign(CodemanApp.prototype, {
  _gitRepoSection(r) {
    const el = (tag, cls, text) => this._gitEl(tag, cls, text);
    const d = r.status;
+    if (d.state === 'error') {
+      // Kept in the list with the reason, rather than silently left out.
+      const row = el('div', 'git-status-repo git-status-repo--error');
+      row.append(el('span', 'git-status-repo-name', r.name));
+      if (r.path !== r.name) row.append(el('span', 'git-status-repo-path', r.path));
+      const why = el('span', 'git-status-repo-unreadable', `⚠ could not read: ${d.error || 'git failed'}`);
+      why.title = 'If this is a timeout, raise “Git status: git timeout” in Settings → Bottom bar.';
+      row.append(why);
+      return row;
+    }
    const section = el('details', 'git-status-repo');
    const outstanding = d.counts.uncommitted > 0 || d.unpushedCount > 0;
    const openRepos = (this._gitTreeOpen = this._gitTreeOpen || new Set());
@@ -582,7 +621,12 @@ Object.assign(CodemanApp.prototype, {
    const view = { sessionId, repoRoot, file, letter, state: 'loading' };
    this._gitDiffView = view;
    this._renderGitStatusPanel();
-    const qs = new URLSearchParams({ repo: repoRoot, path: file.path, kind: file.kind });
+    const qs = new URLSearchParams({
+      repo: repoRoot,
+      path: file.path,
+      kind: file.kind,
+      ...this.gitStatusLimits(),
+    });
    const res = await this._api(`/api/sessions/${encodeURIComponent(sessionId)}/git-diff?${qs}`);
    // Back, another file or another session while this was in flight: drop the answer.
    if (this._gitDiffView !== view) return;
@@ -2009,6 +2009,20 @@
                    </div>
                    <label class="switch switch-sm"><input type="checkbox" id="appSettingsGitStatusTree" checked><span class="slider"></span></label>
                  </div>
+                  <div class="set-row" data-search="git status maximum repositories folder many repos limit">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status: max repositories <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">When the session's folder holds several projects instead of being one, the Git window lists up to this many (1 to 50, default 12). Each one costs a few git commands per refresh.</span>
+                    </div>
+                    <input type="number" id="appSettingsGitStatusMaxRepos" class="set-num" value="12" min="1" max="50" step="1">
+                  </div>
+                  <div class="set-row" data-search="git status timeout seconds slow share network">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Git status: git timeout <span class="set-scope">device</span></span>
+                      <span class="set-row-desc">Seconds one git command may run before that repository is reported as unreadable (5 to 120, default 30). Raise it for repositories on a slow network share.</span>
+                    </div>
+                    <input type="number" id="appSettingsGitStatusTimeout" class="set-num" value="30" min="5" max="120" step="5">
+                  </div>
                </div>
              </div>

@@ -455,6 +455,8 @@ Object.assign(CodemanApp.prototype, {
    document.getElementById('appSettingsShowCronButton').checked = settings.showCronButton ?? defaults.showCronButton ?? false;
    document.getElementById('appSettingsShowGitStatus').checked = settings.showGitStatus ?? defaults.showGitStatus ?? false;
    document.getElementById('appSettingsGitStatusTree').checked = settings.gitStatusTree ?? defaults.gitStatusTree ?? true;
+    document.getElementById('appSettingsGitStatusMaxRepos').value = settings.gitStatusMaxRepos ?? defaults.gitStatusMaxRepos ?? 12;
+    document.getElementById('appSettingsGitStatusTimeout').value = settings.gitStatusTimeoutSeconds ?? defaults.gitStatusTimeoutSeconds ?? 30;
    // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
    // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
    // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
@@ -2552,6 +2554,9 @@ Object.assign(CodemanApp.prototype, {
      showCronButton: document.getElementById('appSettingsShowCronButton').checked,
      showGitStatus: document.getElementById('appSettingsShowGitStatus').checked,
      gitStatusTree: document.getElementById('appSettingsGitStatusTree').checked,
+      // Clamped here and again on the server; an empty or odd value falls back to the default.
+      gitStatusMaxRepos: Math.min(50, Math.max(1, parseInt(document.getElementById('appSettingsGitStatusMaxRepos').value, 10) || 12)),
+      gitStatusTimeoutSeconds: Math.min(120, Math.max(5, parseInt(document.getElementById('appSettingsGitStatusTimeout').value, 10) || 30)),
      gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
      subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
      subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
@@ -2823,6 +2828,8 @@ Object.assign(CodemanApp.prototype, {
      // Per-device bottom-bar indicator, absent from SettingsUpdateSchema (.strict()): it must not reach the PUT.
      showGitStatus: _sgs,
      gitStatusTree: _gst,
+      gitStatusMaxRepos: _gsm,
+      gitStatusTimeoutSeconds: _gst2,
      showTabDetachButton: _tdb,
      // Phone-only home surface, and absent from SettingsUpdateSchema (.strict()).
      mobileOverviewEnabled: _mov,
@@ -4228,7 +4235,7 @@ Object.assign(CodemanApp.prototype, {
          'language',
          'terminalWheelLocalScrollback',
          'autoCopySelection', 'copyStripMargin',
-          'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree',
+          'showSessionButton', 'showAwayDigestButton', 'showCronButton', 'showGitStatus', 'gitStatusTree', 'gitStatusMaxRepos', 'gitStatusTimeoutSeconds',
          'showTabDetachButton',
          'mobileOverviewEnabled',
          'sessionLineageLines',
@@ -20586,6 +20586,22 @@ html .toolbar .btn-git-status[aria-expanded='true'] {
  border-left: 1px solid var(--border);
 }

+/* Git status panel: a repository git could not read stays in the list, with the reason */
+.git-status-repo--error {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  padding: 0.35rem 0.5rem;
+  background: var(--bg-input);
+  min-width: 0;
+}
+
+.git-status-repo-unreadable {
+  color: #e0a030;
+  font-size: 0.68rem;
+}
+
 /* ============================================================
   Tab grouping by state (tabArrangement: 'state', opt-in;
   Discussion #426 option C)
@@ -20,6 +20,7 @@ import {
  emptyOverview,
  findWorkspaceRepo,
  getGitFileDiff,
+  resolveOverviewLimits,
  getGitWorkspaceOverview,
  getGitWorkspaceStatus,
  type GitFileDiff,
@@ -33,6 +34,18 @@ import type { SessionPort } from '../ports/index.js';
 const defaultDockerWorkspaces = async (): Promise<string[]> =>
  (await readDockerCases(getDataDir()).catch(() => [])).map((c) => c.hostWorkspacePath).filter(Boolean);

+/**
+ * The repository limit and git timeout a request asks for (Settings → Bottom bar, per device):
+ * `maxRepos` and `timeout` (seconds) query parameters, each clamped to a safe range, so an odd value
+ * can never cost more than the module's own ceiling.
+ */
+function limitsFrom(query: { maxRepos?: string; timeout?: string }) {
+  return resolveOverviewLimits({
+    maxRepos: query.maxRepos,
+    timeoutMs: query.timeout?.trim() ? Number(query.timeout) * 1000 : undefined, // '' and absent mean "default"
+  });
+}
+
 export function registerGitStatusRoutes(
  app: FastifyInstance,
  ctx: SessionPort,
@@ -41,7 +54,9 @@ export function registerGitStatusRoutes(
 ): void {
  app.get('/api/sessions/:id/git-status', async (req): Promise<ApiResponse<GitWorkspaceOverview>> => {
    const { id } = req.params as { id: string };
-    const { fresh } = req.query as { fresh?: string };
+    const query = req.query as { fresh?: string; maxRepos?: string; timeout?: string };
+    const { fresh } = query;
+    const limits = limitsFrom(query);
    const session = findSessionOrFail(ctx, id, req);
    if (session.remote) return { success: true, data: emptyOverview('unsupported', { reason: 'remote' }) };
    if (session.docker) return { success: true, data: emptyOverview('unsupported', { reason: 'docker' }) };
@@ -50,6 +65,7 @@ export function registerGitStatusRoutes(
      data: await getGitWorkspaceOverview(session.workingDir, {
        git,
        fresh: fresh === '1',
+        ...limits,
        dockerWorkspaces: await dockerWorkspaces(),
      }),
    };
@@ -62,16 +78,24 @@ export function registerGitStatusRoutes(
  // repository's status is refreshed: a click must not re-read every repository in the folder.
  app.get('/api/sessions/:id/git-diff', async (req, reply): Promise<ApiResponse<GitFileDiff>> => {
    const { id } = req.params as { id: string };
-    const { repo, path, kind } = req.query as { repo?: string; path?: string; kind?: string };
+    const query = req.query as { repo?: string; path?: string; kind?: string; maxRepos?: string; timeout?: string };
+    const { repo, path, kind } = query;
+    const limits = limitsFrom(query);
    const session = findSessionOrFail(ctx, id, req);
    if (session.remote || session.docker) {
      reply.code(400);
      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Git is not available for remote or Docker sessions');
    }
    const repoRoot = repo
-      ? await findWorkspaceRepo(session.workingDir, repo, { git, dockerWorkspaces: await dockerWorkspaces() })
+      ? await findWorkspaceRepo(session.workingDir, repo, {
+          git,
+          ...limits,
+          dockerWorkspaces: await dockerWorkspaces(),
+        })
+      : null;
+    const status = repoRoot
+      ? await getGitWorkspaceStatus(repoRoot, { git, fresh: true, timeoutMs: limits.timeoutMs })
      : null;
-    const status = repoRoot ? await getGitWorkspaceStatus(repoRoot, { git, fresh: true }) : null;
    const entry =
      status?.state === 'ok'
        ? status.files.find((f) => f.path === path && f.kind === (kind as GitFileKind))
@@ -81,7 +105,10 @@ export function registerGitStatusRoutes(
      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'That file has no outstanding change any more');
    }
    try {
-      return { success: true, data: await getGitFileDiff(status.repoRoot, entry, { git }) };
+      return {
+        success: true,
+        data: await getGitFileDiff(status.repoRoot, entry, { git, timeoutMs: limits.timeoutMs }),
+      };
    } catch (err) {
      reply.code(500);
      return createErrorResponse(