@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/fs/git-state.test.ts

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The operation-state read, driven against REAL repositories in every state it
+ * reports.
+ *
+ * The state lives in FILES in the git directory, so the fixtures are the files
+ * git itself writes: a merge stopped on a conflict (`MERGE_HEAD`), a rebase
+ * (`rebase-merge`), a cherry-pick (`CHERRY_PICK_HEAD`), and — the case that
+ * makes the read non-trivial — a conflicting `git stash pop`, which leaves
+ * unmerged entries and NO operation file at all. That last one is why
+ * `stash-pop` is a distinct operation rather than a null: every `--abort` verb
+ * answers "no <op> in progress" there (verified), so the abort has to be
+ * `git reset --merge HEAD`.
+ *
+ * A detached HEAD is pinned too, because the branch read reports the literal
+ * string `HEAD` for it and that string used to reach the branch list as a
+ * branch the user could check out.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { abortArgsFor, readGitState } from '@/server/lib/fs/git-state';
+import { removeDir } from '@/test-support/remove-dir';
+
+const roots: string[] = [];
+
+/**
+ * Run one git command, ignoring its exit code.
+ *
+ * The fixtures deliberately run commands that FAIL: a conflicting merge, a
+ * rebase, a cherry-pick and a `stash pop` all exit non-zero by design. The
+ * helper returns stdout/stderr either way and lets each test assert on the
+ * STATE the failure left, which is the whole subject of this file.
+ */
+function git(cwd: string, ...args: string[]): string {
+  const result = Bun.spawnSync({ cmd: ['git', ...args], cwd, env: { ...Bun.env, GIT_EDITOR: 'true' } });
+  return result.stdout.toString().trim();
+}
+
+/** A repository on `main` and `feature` whose two branches edit the same line. */
+function makeConflictingRepo(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-gitstate-'));
+  roots.push(dir);
+  git(dir, 'init', '-q', '-b', 'main', '.');
+  git(dir, 'config', 'user.email', 'test@example.invalid');
+  git(dir, 'config', 'user.name', 'Test');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\nb\n');
+  git(dir, 'add', '.');
+  git(dir, 'commit', '-qm', 'base');
+  git(dir, 'checkout', '-qb', 'feature');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\nFEAT\n');
+  git(dir, 'commit', '-qam', 'feat');
+  git(dir, 'checkout', '-q', 'main');
+  fs.writeFileSync(path.join(dir, 'f.txt'), 'a\nMAIN\n');
+  git(dir, 'commit', '-qam', 'main');
+  return dir;
+}
+
+afterAll(() => {
+  for (const dir of roots) removeDir(dir);
+});
+
+describe('readGitState: no operation', () => {
+  test('a clean repository reports no operation and no conflicts', async () => {
+    const dir = makeConflictingRepo();
+    const state = await readGitState(dir);
+    expect(state.operation).toBeNull();
+    expect(state.conflicts).toEqual([]);
+    expect(state.detached).toBe(false);
+  });
+
+  test('a directory that is not a repository answers the empty state, not an error', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-notrepo-'));
+    roots.push(dir);
+    const state = await readGitState(dir);
+    expect(state).toEqual({ operation: null, conflicts: [], detached: false });
+  });
+});
+
+describe('readGitState: each operation', () => {
+  test('a stopped merge reports MERGE_HEAD and its conflicted path', async () => {
+    const dir = makeConflictingRepo();
+    git(dir, 'merge', '--no-edit', 'feature');
+    const state = await readGitState(dir);
+    expect(state.operation).toBe('merge');
+    expect(state.conflicts).toEqual(['f.txt']);
+    // The abort verb is the one git accepts in this state.
+    expect(abortArgsFor(state.operation!)).toEqual(['merge', '--abort']);
+  });
+
+  test('a stopped rebase reports rebase-merge and detaches HEAD', async () => {
+    const dir = makeConflictingRepo();
+    git(dir, 'rebase', 'feature');
+    const state = await readGitState(dir);
+    expect(state.operation).toBe('rebase');
+    expect(state.conflicts).toEqual(['f.txt']);
+    // A rebase detaches, which is the second reason the branch read needs this.
+    expect(state.detached).toBe(true);
+    expect(abortArgsFor(state.operation!)).toEqual(['rebase', '--abort']);
+  });
+
+  test('a stopped cherry-pick reports CHERRY_PICK_HEAD', async () => {
+    const dir = makeConflictingRepo();
+    git(dir, 'cherry-pick', 'feature');
+    const state = await readGitState(dir);
+    expect(state.operation).toBe('cherry-pick');
+    expect(state.conflicts).toEqual(['f.txt']);
+    expect(abortArgsFor(state.operation!)).toEqual(['cherry-pick', '--abort']);
+  });
+
+  test('a conflicting stash pop reports stash-pop, which has NO operation file', async () => {
+    const dir = makeConflictingRepo();
+    // Stash a change to the same line the incoming one touches, then pop it
+    // onto a commit that has since changed that line.
+    fs.writeFileSync(path.join(dir, 'f.txt'), 'a\nSTASHED\n');
+    git(dir, 'stash', 'push', '-q');
+    fs.writeFileSync(path.join(dir, 'f.txt'), 'a\nHEAD\n');
+    git(dir, 'commit', '-qam', 'moved-on');
+    git(dir, 'stash', 'pop');
+    const state = await readGitState(dir);
+    expect(state.operation).toBe('stash-pop');
+    expect(state.conflicts).toEqual(['f.txt']);
+    // No abort verb exists for it; the reset is the only thing that clears it.
+    expect(abortArgsFor(state.operation!)).toEqual(['reset', '--merge', 'HEAD']);
+  });
+});
+
+describe('readGitState: conflict list shape', () => {
+  test('a path with a space survives the NUL-separated read', async () => {
+    const dir = makeConflictingRepo();
+    const name = 'a file with spaces.txt';
+    fs.writeFileSync(path.join(dir, name), 'a\nb\n');
+    git(dir, 'add', '.');
+    git(dir, 'commit', '-qm', 'add spaced');
+    git(dir, 'checkout', '-qb', 'spaced');
+    fs.writeFileSync(path.join(dir, name), 'a\nSPACED\n');
+    git(dir, 'commit', '-qam', 'spaced change');
+    git(dir, 'checkout', '-q', 'main');
+    fs.writeFileSync(path.join(dir, name), 'a\nMAIN2\n');
+    git(dir, 'commit', '-qam', 'main change');
+    git(dir, 'merge', '--no-edit', 'spaced');
+    const state = await readGitState(dir);
+    expect(state.conflicts).toEqual([name]);
+  });
+
+  test('a conflict list names each path ONCE despite three index stages', async () => {
+    // `ls-files -u` prints a record per stage (1 base, 2 ours, 3 theirs), so a
+    // list without the dedupe would repeat every path three times — and the
+    // operation bar's "N conflicts left" count would read 3x the truth.
+    const dir = makeConflictingRepo();
+    git(dir, 'merge', '--no-edit', 'feature');
+    const state = await readGitState(dir);
+    expect(state.conflicts.length).toBe(1);
+  });
+});
+
+describe('readGitState: detached HEAD', () => {
+  test('a detached checkout is reported as detached', async () => {
+    const dir = makeConflictingRepo();
+    git(dir, 'checkout', '-q', '--detach', 'HEAD~1');
+    const state = await readGitState(dir);
+    expect(state.detached).toBe(true);
+    expect(state.operation).toBeNull();
+  });
+});

package/src/server/lib/fs/git-state.ts

@@ -0,0 +1,178 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Whether a working tree is in the middle of a git OPERATION — a merge, rebase,
+ * cherry-pick, revert or `git am` that stopped and is waiting for a human.
+ *
+ * This is the read the panel was missing entirely, and its absence is why a
+ * conflict was a dead end: the commit box said "Committing is not possible
+ * because you have unmerged files", the discard button silently destroyed the
+ * conflict while leaving the merge open, and nothing on screen said a merge was
+ * in progress at all.
+ *
+ * **The state lives in FILES in the git directory, not in a command's exit
+ * code.** Every probe below is a stat, because every alternative was measured
+ * and is worse:
+ *
+ *  - `git rev-parse --git-path <name>` takes ONE name — passing five gives one
+ *    path and then `fatal: ambiguous argument 'rebase-merge': unknown revision`
+ *    — so a five-probe read would be five spawns.
+ *  - It also returns a path RELATIVE to the cwd (`../../.git/MERGE_HEAD` from a
+ *    subdirectory), which then has to be joined back.
+ *  - `--absolute-git-dir` is absolute and resolves from any subdirectory
+ *    (verified from `sub/deep/`), and it resolves correctly for a linked
+ *    worktree — `<main>/.git/worktrees/<name>` — which is where that worktree's
+ *    own operation state actually lives.
+ *
+ * So: one spawn for the directory, then stats.
+ *
+ * The conflict LIST is a separate read (`git ls-files -u`), because a
+ * conflicted file can exist with no operation file at all — a conflicting
+ * `git stash pop` leaves `UU f` and no `MERGE_HEAD`, `rebase-merge` or
+ * `CHERRY_PICK_HEAD` (verified). In that state every `--abort` verb exits 128
+ * with its own fatal, which is why `stash-pop` is a distinct operation name
+ * here and not a null.
+ */
+
+import fs from 'node:fs';
+import path from 'path';
+import { runGit } from '@/server/lib/fs/git-run';
+import type { GitOperation, GitState } from '@/shared/types';
+
+// The state vocabulary lives in `shared/types/git.ts` because the panel renders
+// it: two declarations of the same union would be two things to keep in step,
+// and the client cannot import a server module.
+export type { GitOperation, GitState };
+
+/**
+ * The paths git leaves behind, in the order they are checked.
+ *
+ * Exported because it is the vocabulary the state read is built on: a test
+ * asserts every operation except `stash-pop` has a file here (and that
+ * `stash-pop` deliberately does not), and the verb tables are keyed by the
+ * operations this list can produce.
+ */
+export const OPERATION_PATHS: Array<{ name: string; operation: GitOperation }> = [
+  { name: 'MERGE_HEAD', operation: 'merge' },
+  { name: 'rebase-merge', operation: 'rebase' },
+  { name: 'rebase-apply', operation: 'rebase-apply' },
+  { name: 'CHERRY_PICK_HEAD', operation: 'cherry-pick' },
+  { name: 'REVERT_HEAD', operation: 'revert' },
+];
+
+export interface GitStateOptions {
+  /** Reuse an already-read git dir, so a caller that knows it spawns no second. */
+  gitDir?: string;
+}
+
+/**
+ * Read one working tree's operation state.
+ *
+ * Never throws: a directory that is not a repository (or a host without `git`)
+ * answers `{operation: null, conflicts: [], detached: false}`, which is the
+ * honest answer — there is no operation in progress in a tree git cannot read.
+ */
+export async function readGitState(targetDir: string, options: GitStateOptions = {}): Promise<GitState> {
+  const empty: GitState = { operation: null, conflicts: [], detached: false };
+  try {
+    const gitDir = options.gitDir ?? await resolveGitDir(targetDir);
+    if (!gitDir) return empty;
+
+    const conflicts = await readConflicts(targetDir);
+    const detached = await isDetachedHead(targetDir);
+
+    for (const { name, operation } of OPERATION_PATHS) {
+      // `fs.existsSync`, not `Bun.file().exists()`: measured, `rebase-merge` is
+      // a DIRECTORY, and `Bun.file(<dir>).exists()` answers false for it — the
+      // rebase state was reported as `stash-pop` (the fallthrough for "conflicts
+      // with no operation file"), whose abort is `reset --merge HEAD` instead of
+      // `rebase --abort`. `stat()` sees the directory; `existsSync` is the one
+      // that is also correct for the FILE cases.
+      if (fs.existsSync(path.join(gitDir, name))) {
+        return { operation, conflicts, detached };
+      }
+    }
+    // No operation file, but unmerged entries: a stash pop/apply that
+    // conflicted. `git stash pop` leaves the stash entry in place precisely so
+    // this can be retried, and `git reset --merge HEAD` is what clears it.
+    if (conflicts.length > 0) return { operation: 'stash-pop', conflicts, detached };
+    return { ...empty, detached };
+  } catch {
+    return empty;
+  }
+}
+
+/** The absolute git directory, or null when this is not a repository. */
+async function resolveGitDir(cwd: string): Promise<string | null> {
+  const result = await runGit(['rev-parse', '--absolute-git-dir'], { cwd, timeout: 8_000 });
+  if (result.exitCode !== 0) return null;
+  const dir = result.stdout.trim();
+  return dir || null;
+}
+
+/**
+ * Repo-relative paths with unmerged index entries.
+ *
+ * `ls-files -u -z` rather than `git diff --name-only --diff-filter=U`: `-z` is
+ * the lossless form (the same reason `parsePorcelainZ` uses it — a path with a
+ * space, a quote or a non-ASCII byte comes back quoted and octal-escaped
+ * otherwise), and it prints one record PER STAGE (1 = base, 2 = ours,
+ * 3 = theirs), so the dedupe below is required rather than optional.
+ *
+ * A record is `<mode> <sha> <stage>\t<path>`.
+ */
+async function readConflicts(cwd: string): Promise<string[]> {
+  const result = await runGit(['ls-files', '-u', '-z'], { cwd, timeout: 8_000 });
+  if (result.exitCode !== 0) return [];
+  const paths = new Set<string>();
+  for (const record of result.stdout.split('\0')) {
+    const tab = record.indexOf('\t');
+    if (tab === -1) continue;
+    const file = record.slice(tab + 1);
+    if (file) paths.add(file);
+  }
+  return [...paths];
+}
+
+/**
+ * True when HEAD names no branch.
+ *
+ * The branch read marks HEAD from `%(HEAD)` in `for-each-ref`, and a detached
+ * checkout marks nothing — so it falls to `git rev-parse --abbrev-ref HEAD`,
+ * which prints the literal string `HEAD`. That string then reaches the branch
+ * list as a branch the user can check out (measured: `branches: ["HEAD",
+ * "main"]`), and during a REBASE CONFLICT it is what the panel shows as the
+ * current branch, because a rebase detaches HEAD too.
+ */
+async function isDetachedHead(cwd: string): Promise<boolean> {
+  const result = await runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd, timeout: 8_000 });
+  return result.exitCode !== 0;
+}
+
+/** Human wording for an operation, for a banner or a refusal message. */
+export { OPERATION_LABELS } from '@/shared/lib/fs/git-unmerged';
+
+/** The abort verb per operation — the ONE place the mapping is written down. */
+export function abortArgsFor(operation: GitOperation): string[] {
+  switch (operation) {
+    case 'merge':
+      return ['merge', '--abort'];
+    case 'rebase':
+    case 'rebase-apply':
+      return ['rebase', '--abort'];
+    case 'cherry-pick':
+      return ['cherry-pick', '--abort'];
+    case 'revert':
+      return ['revert', '--abort'];
+    case 'stash-pop':
+      // The only one with no git verb of its own: a conflicting stash pop
+      // leaves unmerged entries and no operation file, so every `--abort`
+      // answers "no <op> in progress". `--merge` resets the index and the
+      // conflicted paths to HEAD and leaves the stash entry in place
+      // (verified), so the pop can be retried.
+      return ['reset', '--merge', 'HEAD'];
+  }
+}

package/src/server/lib/fs/git-status-read.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The working-tree status read behind the Source Control panel.
+ *
+ * The load-bearing part is the porcelain DIALECT: `-z` is the only lossless
+ * form. The non-`-z` form quotes any path holding a space, a quote or a
+ * backslash and octal-escapes its non-ASCII bytes, and no decode reverses that
+ * — `JSON.parse` turns `"\303\274n"` into the literal text `\303\274`, a path
+ * that does not exist, so the panel listed a filename whose diff then read
+ * "No differences found". These tests drive a real repository holding those
+ * names and pin the file, the status, the staged flag, and the rename shape.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { testPosix } from '@/test-support/platform';
+import { parsePorcelainZ } from '@/server/lib/fs/git-run';
+import { readGitStatus } from '@/server/lib/fs/git-status-read';
+import { removeDir } from '@/test-support/remove-dir';
+
+const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-status-'));
+
+function git(...args: string[]): void {
+  const result = Bun.spawnSync({ cmd: ['git', ...args], cwd: repo });
+  if (result.exitCode !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString()}`);
+  }
+}
+
+function write(rel: string, content: string): void {
+  const full = path.join(repo, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+beforeAll(() => {
+  git('init', '-q', '-b', 'main');
+  // Pin the line ending: a Windows host defaults `core.autocrlf` to true, which
+  // rewrites every checked-out file to CRLF.
+  git('config', 'core.autocrlf', 'false');
+  git('config', 'core.eol', 'lf');
+  git('config', 'user.email', 'test@example.invalid');
+  git('config', 'user.name', 'Test');
+  write('plain.sh', 'p\n');
+  write('with space.sh', 's\n');
+  write('ünïcode.xml', '<a>1</a>\n');
+  write('a\\b.sh', 'b\n');
+  write('to-rename.txt', 'r\n');
+  git('add', '-A');
+  git('commit', '-q', '-m', 'base');
+
+  write('plain.sh', 'p2\n');
+  write('with space.sh', 's2\n');
+  write('ünïcode.xml', '<a>2</a>\n');
+  write('a\\b.sh', 'b2\n');
+  write('untracked.sh', 'u\n');
+  git('mv', 'to-rename.txt', 'renamed.txt');
+});
+
+afterAll(() => {
+  removeDir(repo);
+});
+
+describe('parsePorcelainZ', () => {
+  test('splits on NUL, not on newline', () => {
+    const rows = parsePorcelainZ(' M a.sh\0?? b.xml\0');
+    expect(rows.map((r) => r.file)).toEqual(['a.sh', 'b.xml']);
+    expect(rows[0].status).toBe(' M');
+    expect(rows[1].staged).toBe(false);
+  });
+
+  test('unwraps a rename from its own record, keeping the NEW path', () => {
+    // A rename spends two records: the new path, then the old one.
+    const rows = parsePorcelainZ('R  new.txt\0old.txt\0 M other.txt\0');
+    expect(rows).toHaveLength(2);
+    expect(rows[0].file).toBe('new.txt');
+    expect(rows[0].staged).toBe(true);
+    expect(rows[1].file).toBe('other.txt');
+  });
+
+  test('a copy is unwrapped the same way', () => {
+    const rows = parsePorcelainZ('C  copy.txt\0source.txt\0');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].file).toBe('copy.txt');
+  });
+
+  test('an empty listing yields no rows', () => {
+    expect(parsePorcelainZ('')).toEqual([]);
+    expect(parsePorcelainZ('\0')).toEqual([]);
+  });
+});
+
+describe('readGitStatus', () => {
+  test('reports every changed file with its path intact', async () => {
+    const status = await readGitStatus(repo);
+    const files = status.changes.map((c) => c.file).sort();
+    expect(files).toContain('plain.sh');
+    expect(files).toContain('with space.sh');
+    expect(files).toContain('untracked.sh');
+  });
+
+  // The bug this dialect exists to prevent: porcelain's default form escapes
+  // these, and a decode of the escaped text names a file that is not there.
+  test('a non-ASCII filename arrives as its real bytes, not an octal escape', async () => {
+    const status = await readGitStatus(repo);
+    const hit = status.changes.find((c) => c.file.includes('code.xml'));
+    expect(hit?.file).toBe('ünïcode.xml');
+  });
+
+  // `\` is a path separator on Windows, so a file literally named `a\b.sh` cannot
+  // exist there to be reported back unquoted; the quoting it exercises is a
+  // POSIX git behaviour.
+  testPosix('a filename holding a backslash arrives unquoted', async () => {
+    const status = await readGitStatus(repo);
+    const hit = status.changes.find((c) => c.file.includes('b.sh'));
+    expect(hit?.file).toBe('a\\b.sh');
+  });
+
+  test('a filename holding a space arrives unquoted', async () => {
+    const status = await readGitStatus(repo);
+    const hit = status.changes.find((c) => c.file === 'with space.sh');
+    expect(hit).toBeDefined();
+    expect(hit?.status.trim()).toBe('M');
+  });
+
+  test('a rename is reported under its new path, staged', async () => {
+    const status = await readGitStatus(repo);
+    const hit = status.changes.find((c) => c.file === 'renamed.txt');
+    expect(hit).toBeDefined();
+    expect(hit?.status[0]).toBe('R');
+    expect(hit?.staged).toBe(true);
+    // The old path is not a file the working tree still has.
+    expect(status.changes.some((c) => c.file === 'to-rename.txt')).toBe(false);
+  });
+});

package/src/server/lib/fs/git-status-read.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The git status read for one working tree: branch, branch lists, changed files
+ * and (on request) the ahead/behind count.
+ *
+ * Extracted from `routes/fs/git.ts` so the HTTP route and the realtime `git:`
+ * topic answer from ONE implementation. Two copies would drift on the details
+ * that matter — which files count as staged, how a rename is unwrapped, how a
+ * detached HEAD is named — and the panel would then show a different list
+ * depending on which path delivered it.
+ *
+ * Read-only: the caller supplies a directory inside a root it has already
+ * resolved.
+ */
+
+import { runShell } from '@/server/lib/fs/shell';
+import { GIT_ENV, parsePorcelainZ } from '@/server/lib/fs/git-run';
+import { gitSyncCount, refreshRemoteRefs } from '@/server/lib/fs/git-sync';
+import { readGitState } from '@/server/lib/fs/git-state';
+import type { GitChange, GitState } from '@/shared/types';
+
+export interface GitStatusPayload {
+  changes: GitChange[];
+  branch: string;
+  branches: string[];
+  remoteBranches: string[];
+  syncCount?: { ahead: number; behind: number };
+  /**
+   * Whether an operation is in progress (merge/rebase/cherry-pick/revert/stash
+   * pop), the conflicted paths, and whether HEAD is detached.
+   *
+   * Travels on the payload rather than a second endpoint because the panel
+   * reads this from the `git:` realtime topic: a merge started by a tool call
+   * has to reach the panel the same way a change to the tree does, and a second
+   * read path is a second answer.
+   */
+  state?: GitState;
+  error?: string;
+}
+
+/**
+ * How the ahead/behind count is produced, when one is asked for at all.
+ *
+ * - `fetch` — refresh the branch's remote-tracking ref first, so `behind`
+ *   describes origin rather than the last fetch. A network round trip, TTL'd
+ *   inside the helper. The git panel's own read (mount and Refresh) uses it.
+ * - `local` — count against the tracking ref as it stands. ~15ms of `git
+ *   rev-list`, no network, so the realtime `git:` topic can carry a count that
+ *   follows every push (a tool call's commit) without turning each one into a
+ *   fetch.
+ *
+ * Omitted means no count at all: the status-only readers (the activity bar's
+ * dot, the file explorer) must not pay for a value they never read.
+ */
+export type GitCountMode = 'fetch' | 'local';
+
+export interface GitStatusOptions {
+  count?: GitCountMode;
+}
+
+/**
+ * Read one working tree's status.
+ *
+ * Never throws: a directory that is not a repository (or a host without `git`)
+ * answers an empty change list with the error text, which is what the panel
+ * renders — a thrown error would take the whole response down over a directory
+ * the user merely pointed at.
+ */
+export async function readGitStatus(targetDir: string, options: GitStatusOptions = {}): Promise<GitStatusPayload> {
+  const countMode = options.count;
+  try {
+    // Started before the local probes below so the fetch overlaps them instead
+    // of adding up. `local` deliberately starts nothing: the tracking ref is
+    // read where it stands.
+    const remoteRefresh = countMode === 'fetch' ? refreshRemoteRefs(targetDir) : Promise.resolve();
+    // The operation/conflict read runs alongside the status probe for the same
+    // reason: it is one `rev-parse` plus stats, and awaiting it serially would
+    // add a spawn to every panel refresh.
+    const stateRead = readGitState(targetDir);
+
+    // `--porcelain=v1 -z -uall` so all individual edited/untracked files are
+    // listed, and so a path holding a space, a quote or a non-ASCII byte
+    // arrives VERBATIM. The non-`-z` form quotes those and octal-escapes the
+    // non-ASCII ones, which no decode reverses — see `parsePorcelainZ`.
+    const statusOut = (await runShell('git status --porcelain=v1 -z -uall', { cwd: targetDir, maxBuffer: 4 * 1024 * 1024, env: GIT_ENV })).stdout;
+
+    let branch = 'main';
+    // Seeded empty, not `['main']`: the seed used to be pushed as a real local
+    // branch, so a repository whose only branch is `main` listed it twice.
+    const branches: string[] = [];
+    const remoteBranches: string[] = [];
+    try {
+      // One `for-each-ref` answers all three questions the three previous
+      // spawns asked separately (`rev-parse --abbrev-ref HEAD`, `branch`,
+      // `branch -r`): `%(HEAD)` marks the checked-out branch with `*`, and the
+      // two refspecs cover local and remote in one listing. Measured 8.15 ms
+      // against 19.63 ms for the three-call form.
+      //
+      // Classification reads the FULL refname: `%(refname:short)` maps
+      // `refs/remotes/origin/HEAD` to the bare `origin`, which has no slash and
+      // would otherwise be listed as a local branch.
+      const refsOut = (await runShell(
+        'git for-each-ref --format="%(refname)%09%(refname:short)%09%(HEAD)" refs/heads refs/remotes',
+        { cwd: targetDir, env: GIT_ENV },
+      )).stdout;
+      let sawHead = false;
+      for (const line of refsOut.split('\n')) {
+        const [full, short, head] = line.split('\t');
+        if (!full || !short) continue;
+        // `refs/remotes/origin/HEAD` is a symbolic alias, not a branch.
+        if (full.endsWith('/HEAD')) continue;
+        if (full.startsWith('refs/remotes/')) {
+          remoteBranches.push(short);
+          continue;
+        }
+        branches.push(short);
+        if (head === '*') {
+          branch = short;
+          sawHead = true;
+        }
+      }
+      // Detached HEAD: no local ref is marked, and the branch is the sha
+      // `rev-parse --abbrev-ref HEAD` prints. Ask for it rather than reporting
+      // a branch the checkout is not on.
+      if (!sawHead) {
+        const headOut = await runShell('git rev-parse --abbrev-ref HEAD', { cwd: targetDir, env: GIT_ENV });
+        branch = headOut.stdout.trim() || 'main';
+      }
+    } catch {
+      // ignore branch resolution errors
+    }
+
+    const changes: GitChange[] = parsePorcelainZ(statusOut);
+    const state = await stateRead;
+
+    // `main` remains the answer only when nothing could be read (a non-repo
+    // directory, git missing) — a real listing always supplies its own refs.
+    // A DETACHED checkout is the exception: `rev-parse` answers the literal
+    // string `HEAD`, which then listed as a branch the user can check out
+    // (measured: `branches: ["HEAD", "main"]`). The state read is what knows,
+    // so the literal is dropped from the list and the branch is reported as
+    // the detached head it is.
+    const detachedBranch = state.detached ? branch : '';
+    const localBranches = branches.filter((b) => !detachedBranch || b !== detachedBranch);
+    if (localBranches.length === 0) localBranches.push('main');
+    else if (!detachedBranch && !localBranches.includes(branch)) localBranches.unshift(branch);
+
+    await remoteRefresh;
+    const syncCount = countMode ? await gitSyncCount(targetDir) : undefined;
+
+    return {
+      changes,
+      branch: branch || 'main',
+      branches: localBranches,
+      remoteBranches,
+      syncCount,
+      state,
+    };
+  } catch (error) {
+    return {
+      changes: [],
+      branch: 'main',
+      branches: ['main'],
+      remoteBranches: [],
+      syncCount: { ahead: 0, behind: 0 },
+      state: { operation: null, conflicts: [], detached: false },
+      error: error instanceof Error ? error.message : 'Git error',
+    };
+  }
+}