@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/workspace/git.js

@@ -7,12 +7,13 @@
  * against repo-local config, and bounded by a timeout.
  */
 import { execFile } from 'node:child_process';
-import { closeSync, existsSync, fstatSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, futimesSync, lstatSync, mkdtempSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { isWithin, resolvePathLikePython } from './paths.js';
+import { expandHome, isWithin, resolvePathLikePython } from './paths.js';
 import { openAnchoredFd, rmtreeAnchored, safeResolveWs, unlinkAnchored } from './fs.js';
 import { str } from '../util.js';
+import { diffHunks, hunkTotals } from '../text/diff.js';
 export const GIT_TIMEOUT_MS = 5_000;
 export const GIT_REMOTE_TIMEOUT_MS = 60_000;
 export const STATUS_FILE_LIMIT = 500;
@@ -22,8 +23,9 @@ export const DIFF_SIZE_LIMIT = 512 * 1024;
 export const COMMIT_MESSAGE_DIFF_LIMIT = 64 * 1024;
 export const WORKSPACE_GIT_DESTRUCTIVE_ENV = 'HERMES_WEBUI_WORKSPACE_GIT_DESTRUCTIVE';
 export const WORKSPACE_BUSY_MESSAGE = 'A Git operation is running in this workspace.';
+const ACTIVE_RUN_MESSAGE = 'A session run is active. Wait for it to finish before running this Git operation.';
 export const WORKSPACE_WRITE_BUSY_MESSAGE = 'A file operation is running in this workspace.';
-const GIT_ENV_SCRUB_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT', 'GIT_CONFIG_PARAMETERS', 'GIT_ASKPASS', 'SSH_ASKPASS', 'GIT_SSH', 'GIT_SSH_COMMAND'];
+const GIT_ENV_SCRUB_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_CONFIG', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_COUNT', 'GIT_CONFIG_PARAMETERS', 'GIT_ASKPASS', 'SSH_ASKPASS', 'GIT_SSH', 'GIT_SSH_COMMAND', 'GIT_GLOB_PATHSPECS', 'GIT_NOGLOB_PATHSPECS', 'GIT_ICASE_PATHSPECS'];
 const GIT_ENV_SCRUB_PREFIXES = ['GIT_CONFIG_KEY_', 'GIT_CONFIG_VALUE_'];
 const BRANCH_SWITCH_STASH_PREFIX = 'hermes-webui branch switch';
 const GIT_HARDENED_CONFIG = [
@@ -45,14 +47,43 @@ const GIT_DESTRUCTIVE_HARDENED_CONFIG = [
     ['core.alternateRefsCommand', ''],
 ];
 const CONFLICT_CODES = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
+const STATUS_CONFIG_KEYS = /^(core\.(autocrlf|eol|filemode|ignorecase|symlinks|ignorestat|checkstat|trustctime|protecthfs|protectntfs|precomposeunicode|excludesfile|attributesfile|quotepath)|(?:diff|status)\.(renames|renamelimit))$/;
 export class GitWorkspaceError extends Error {
     code;
-    constructor(message, code = 'git_failed') {
-        super(message);
+    constructor(message, code = 'git_failed', options) {
+        super(message, options);
         this.code = code;
         this.name = 'GitWorkspaceError';
     }
 }
+function gitDeadline(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return () => {
+        const ms = deadline - Date.now();
+        if (ms <= 0)
+            throw new GitWorkspaceError('Git command timed out', 'timeout', { cause: Object.assign(new Error('git timed out'), { code: 'ETIMEDOUT' }) });
+        return ms;
+    };
+}
+/** Python `git_info_for_workspace`: the branch badge for a status, null outside a repo. */
+export function gitBadge(status) {
+    if (!status.is_git)
+        return null;
+    const totals = status.totals ?? { changed: 0, staged: 0, unstaged: 0, untracked: 0, conflicts: 0 };
+    return { branch: status.branch ?? 'HEAD', dirty: totals.changed, modified: totals.staged + totals.unstaged, untracked: totals.untracked, ahead: status.ahead ?? 0, behind: status.behind ?? 0, is_git: true };
+}
+/** Porcelain v1 records retain their second NUL field for a rename/copy's source path. */
+export function porcelainStatusEntries(output) {
+    const fields = output.split('\0');
+    const entries = [];
+    for (let i = 0; i < fields.length; i++) {
+        const record = fields[i];
+        if (!record)
+            continue;
+        entries.push(/[RC]/.test(record.slice(0, 2)) ? [record, fields[++i] ?? ''] : [record]);
+    }
+    return entries;
+}
 /**
  * Run `git` without blocking the event loop, resolving like `spawnSync`: the exit status (null when a signal ended it),
  * plus the `error` that prevented a normal run (`ETIMEDOUT` when the timeout killed it). Without `env` the child
@@ -121,7 +152,7 @@ export function classifyGitError(message, args = []) {
         return 'timeout';
     if (text.includes('not installed') || text.includes("no such file or directory: 'git'"))
         return 'missing_git';
-    if (text.includes('not a git repository'))
+    if (text.includes('not a git repository') || text.includes('can only be used inside a git repository'))
         return 'not_a_repo';
     if (text.includes('outside the workspace') || text.includes('outside the git repository'))
         return 'path_outside_workspace';
@@ -150,18 +181,11 @@ function unifiedDiffFromEmpty(lines, toFile) {
     // `difflib` writes `+1` for a single-line range and `+1,N` otherwise.
     return [`--- /dev/null`, `+++ ${toFile}`, `@@ -0,0 +${lines.length === 1 ? '1' : `1,${String(lines.length)}`} @@`, ...lines.map((l) => `+${l}`)];
 }
-function diffStats(diff) {
-    let additions = 0;
-    let deletions = 0;
-    for (const line of diff.split('\n')) {
-        if (line.startsWith('+++') || line.startsWith('---'))
-            continue;
-        if (line.startsWith('+'))
-            additions += 1;
-        else if (line.startsWith('-'))
-            deletions += 1;
-    }
-    return [additions, deletions];
+/** A diff's counts and its parsed hunks (TAL-604): a too-large diff's cut text still counts, but ships no hunks. */
+function diffFields(diff, shown) {
+    const hunks = diffHunks(diff);
+    const [additions, deletions] = hunkTotals(hunks);
+    return { additions, deletions, hunks: shown ? hunks : [] };
 }
 function splitLines(text) {
     // Python `str.splitlines()`: no trailing empty element for a final newline.
@@ -193,6 +217,17 @@ export class GitRunner {
     workspaceBusy(path) {
         return overlapsAny(this.busy, path);
     }
+    /**
+     * A checkpoint diff or restore at `path` (TAL-913): refused while Git holds it or a run is active there, since the
+     * Agent's per-turn checkpoint capture stages into the same store index, and held busy so no run starts meanwhile.
+     */
+    holdCheckpoint(path, fn) {
+        if (this.workspaceBusy(path))
+            throw new GitWorkspaceError(WORKSPACE_BUSY_MESSAGE, 'operation_in_progress');
+        if (this.deps.activeRunIn?.(path))
+            throw new GitWorkspaceError(ACTIVE_RUN_MESSAGE, 'active_stream');
+        return this.holdWorkspace(path, fn);
+    }
     /** Run an asynchronous workspace writer at `path`: refused while Git holds it, and Git mutations refuse meanwhile. */
     holdWrite(path, fn) {
         if (this.workspaceBusy(path))
@@ -222,6 +257,8 @@ export class GitRunner {
             if (GIT_ENV_SCRUB_PREFIXES.some((p) => key.startsWith(p)))
                 Reflect.deleteProperty(env, key);
         env.GIT_TERMINAL_PROMPT = '0';
+        // Every pathspec here is a resolved file path; a glob reading would let `a\b.txt` also match `ab.txt`.
+        env.GIT_LITERAL_PATHSPECS = '1';
         return env;
     }
     now() {
@@ -235,7 +272,7 @@ export class GitRunner {
             if (ignoreUnsupported)
                 return names;
             const message = (result.stderr || result.stdout || 'Git command failed').trim();
-            throw new GitWorkspaceError(message, classifyGitError(message, ['config']));
+            throw new GitWorkspaceError(message, classifyGitError(message, ['config']), { cause: result.error });
         }
         for (const line of (result.stdout || '').split('\n')) {
             const m = nameRe.exec(line.trim());
@@ -265,9 +302,267 @@ export class GitRunner {
     async hasRepoLocalFilters(cwd) {
         return (await this.filterNames(cwd, this.cleanEnv())).size > 0;
     }
+    /** Hold the opened inode and reject devices/FIFOs before reading repository-controlled metadata. */
+    static withStatusFile(path, read) {
+        let fd;
+        try {
+            fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        try {
+            const stat = fstatSync(fd, { bigint: true });
+            if (!stat.isFile())
+                throw new GitWorkspaceError('Git status metadata must be a regular file', 'git_failed');
+            return read(fd, Number(stat.size), stat.mtimeNs);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** A private metadata view never loads executable repository/global configuration, even if the originals change. */
+    async withStatusRepository(cwd, remaining, read) {
+        const location = await this.run(cwd, ['rev-parse', '--absolute-git-dir', '--verify', 'HEAD'], { timeoutMs: remaining() });
+        const output = location.stdout.replace(/\r?\n$/, '');
+        const split = output.lastIndexOf('\n');
+        const gitDir = location.status === 0 ? output.slice(0, split).replace(/\r$/, '') : output;
+        const head = location.status === 0 ? output.slice(split + 1) : 'ref: refs/heads/status-probe';
+        if (!gitDir || (location.status !== 0 && location.status !== 128) || (location.status === 0 && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(head))) {
+            const message = (location.stderr || 'Git repository metadata could not be read').trim();
+            throw new GitWorkspaceError(message, classifyGitError(message, ['rev-parse']));
+        }
+        let common = gitDir;
+        const commonPath = GitRunner.withStatusFile(join(gitDir, 'commondir'), (fd, size) => {
+            if (size > DIFF_SIZE_LIMIT)
+                throw new GitWorkspaceError('Git common directory path is too large', 'git_failed');
+            const bytes = Buffer.alloc(DIFF_SIZE_LIMIT + 1);
+            let offset = 0;
+            while (offset < bytes.length) {
+                remaining();
+                const count = readSync(fd, bytes, offset, bytes.length - offset, null);
+                if (!count)
+                    break;
+                offset += count;
+            }
+            if (offset > DIFF_SIZE_LIMIT)
+                throw new GitWorkspaceError('Git common directory path is too large', 'git_failed');
+            return bytes.subarray(0, offset).toString('utf8');
+        });
+        if (commonPath !== null)
+            common = resolve(gitDir, commonPath.replace(/\r?\n$/, ''));
+        const config = await this.run(cwd, ['-c', `include.path=${join(cwd, '.gitmodules')}`, 'config', '--includes', '--null', '--list', '--show-scope'], { check: true, timeoutMs: remaining() });
+        const values = new Map();
+        const modules = new Map();
+        const entries = config.stdout.split('\0');
+        for (let i = 0; i + 1 < entries.length; i += 2) {
+            const scope = entries[i];
+            const entry = entries[i + 1] ?? '';
+            const split = entry.indexOf('\n');
+            if (split < 0)
+                continue;
+            const key = entry.slice(0, split);
+            if (scope === 'command') {
+                if (/^submodule\..+\.(path|ignore)$/.test(key))
+                    modules.set(key, entry.slice(split + 1));
+            }
+            else
+                values.set(key, entry.slice(split + 1));
+        }
+        const ignores = new Map();
+        for (const [key, path] of modules) {
+            if (!key.endsWith('.path'))
+                continue;
+            const ignore = values.get(`${key.slice(0, -5)}.ignore`) ?? modules.get(`${key.slice(0, -5)}.ignore`) ?? values.get('diff.ignoresubmodules') ?? 'none';
+            if (!['none', 'untracked', 'dirty', 'all'].includes(ignore))
+                throw new GitWorkspaceError('Invalid submodule ignore setting', 'git_failed');
+            ignores.set(path, ignore);
+        }
+        const root = mkdtempSync(join(tmpdir(), 'talaria-git-status-'));
+        try {
+            const objectFormat = values.get('extensions.objectformat') ?? 'sha1';
+            if (!['sha1', 'sha256'].includes(objectFormat))
+                throw new GitWorkspaceError('Unsupported Git repository format', 'git_failed');
+            mkdirSync(join(root, 'info'));
+            mkdirSync(join(root, 'refs'));
+            writeFileSync(join(root, 'config'), `[core]\nrepositoryFormatVersion = ${objectFormat === 'sha256' ? '1' : '0'}\nbare = false\n${objectFormat === 'sha256' ? '[extensions]\nobjectFormat = sha256\n' : ''}`);
+            writeFileSync(join(root, 'HEAD'), `${head}\n`);
+            const copy = (directory, file) => {
+                GitRunner.withStatusFile(join(directory, file), (source, _size, mtimeNs) => {
+                    const target = openSync(join(root, file), 'wx', 0o600);
+                    try {
+                        const chunk = Buffer.allocUnsafe(64 * 1024);
+                        for (;;) {
+                            remaining();
+                            const bytes = readSync(source, chunk, 0, chunk.length, null);
+                            if (!bytes)
+                                break;
+                            writeFileSync(target, chunk.subarray(0, bytes));
+                        }
+                        if (file === 'index' || file.startsWith('sharedindex.')) {
+                            // A newer index timestamp would suppress Git's racy-stat content check; round conservatively earlier.
+                            let margin = 1;
+                            do {
+                                remaining();
+                                const stamp = new Date(Number(mtimeNs / 1000000n) - margin);
+                                futimesSync(target, stamp, stamp);
+                                margin *= 2;
+                            } while (fstatSync(target, { bigint: true }).mtimeNs > mtimeNs);
+                        }
+                    }
+                    finally {
+                        closeSync(target);
+                    }
+                });
+            };
+            for (const file of ['index', ...readdirSync(gitDir).filter((name) => /^sharedindex\.[a-f0-9]+$/.test(name))]) {
+                copy(gitDir, file);
+            }
+            for (const file of ['packed-refs', 'shallow', 'info/attributes', 'info/exclude', 'info/sparse-checkout']) {
+                copy(common, file);
+            }
+            symlinkSync(join(common, 'objects'), join(root, 'objects'), process.platform === 'win32' ? 'junction' : 'dir');
+            const originalEnv = this.cleanEnv();
+            const home = originalEnv.HOME || homedir();
+            const xdg = originalEnv.XDG_CONFIG_HOME || join(home, '.config');
+            if (!values.has('core.attributesfile'))
+                values.set('core.attributesfile', join(xdg, 'git', 'attributes'));
+            if (!values.has('core.excludesfile'))
+                values.set('core.excludesfile', join(xdg, 'git', 'ignore'));
+            const prefix = [`--git-dir=${root}`, `--work-tree=${cwd}`];
+            for (const [key, raw] of values) {
+                if (!STATUS_CONFIG_KEYS.test(key))
+                    continue;
+                const value = key === 'core.attributesfile' || key === 'core.excludesfile' ? resolve(cwd, expandHome(raw, home)) : raw;
+                prefix.push('-c', `${key}=${value}`);
+            }
+            return await read(prefix, { HOME: root, XDG_CONFIG_HOME: root, GIT_CONFIG_NOSYSTEM: '1', GIT_OPTIONAL_LOCKS: '0', GIT_INDEX_FILE: join(root, 'index'), GIT_OBJECT_DIRECTORY: join(root, 'objects'), GIT_ALTERNATE_OBJECT_DIRECTORIES: '' }, ignores, { gitDir, commonDir: common, privateDir: root, refStorage: values.get('extensions.refstorage') ?? 'files' });
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }
+    /** Worktree lifecycle probes need only porcelain v1; child worktrees are inspected through the same private view. */
+    async worktreeStatus(cwd, timeoutMs = GIT_TIMEOUT_MS) {
+        const remaining = gitDeadline(timeoutMs);
+        const visited = new Set();
+        const inspect = async (path) => {
+            visited.add(resolvePathLikePython(path));
+            return this.withStatusRepository(path, remaining, async (prefix, env, ignores) => {
+                const run = (args) => this.run(path, [...prefix, ...args], { check: true, timeoutMs: remaining(), env });
+                // Commit differences remain visible; Git must not run a child status against live submodule configuration.
+                const result = await run(['status', '--porcelain', '-z', '--untracked-files=normal', '--ignore-submodules=dirty']);
+                const index = await run(['ls-files', '--stage', '-z']);
+                const gitlinks = index.stdout.split('\0').filter((entry) => entry.startsWith('160000 '));
+                const records = porcelainStatusEntries(result.stdout);
+                for (let i = records.length - 1; i >= 0; i--) {
+                    const record = records[i]?.[0] ?? '';
+                    if (ignores.get(record.slice(3)) !== 'all' || record.startsWith('??'))
+                        continue;
+                    if (record.startsWith(' '))
+                        records.splice(i, 1);
+                    else {
+                        const fields = records[i];
+                        if (fields)
+                            fields[0] = `${record[0]} ${record.slice(2)}`;
+                    }
+                }
+                result.stdout = records.length ? `${records.flat().join('\0')}\0` : '';
+                let trackedDirty = records.some(([record]) => !record?.startsWith('??'));
+                let untrackedDirty = records.some(([record]) => record?.startsWith('??'));
+                for (const entry of gitlinks) {
+                    const match = /^160000 [a-f0-9]+ [0-3]\t(.+)$/s.exec(entry);
+                    if (!match?.[1])
+                        continue;
+                    const ignore = ignores.get(match[1]) ?? 'none';
+                    if (ignore === 'all' || ignore === 'dirty')
+                        continue;
+                    const child = safeResolveWs(path, match[1]);
+                    if (visited.has(child) || !existsSync(join(child, '.git')))
+                        continue;
+                    const childStatus = await inspect(child);
+                    const untracked = ignore !== 'untracked' && childStatus.untrackedDirty;
+                    if (childStatus.trackedDirty || untracked)
+                        result.stdout += ` M ${match[1]}\0`;
+                    trackedDirty ||= childStatus.trackedDirty;
+                    untrackedDirty ||= untracked;
+                }
+                return { ...result, hasGitlinks: gitlinks.length > 0, trackedDirty, untrackedDirty };
+            });
+        };
+        const { status, stdout, stderr, hasGitlinks } = await inspect(cwd);
+        return { status, stdout, stderr, hasGitlinks };
+    }
+    /** Keep Git's own final clean check, but make its inherited configuration private and non-executable. */
+    async removeWorktree(repoRoot, worktree, timeoutMs = GIT_TIMEOUT_MS) {
+        const remaining = gitDeadline(timeoutMs);
+        const target = resolvePathLikePython(worktree);
+        const listed = await this.run(repoRoot, ['worktree', 'list', '--porcelain', '-z'], { check: true, timeoutMs: remaining() });
+        const paths = listed.stdout.split('\0').filter((field) => field.startsWith('worktree ')).map((field) => resolvePathLikePython(field.slice(9)));
+        if (paths[0] === target || !paths.slice(1).includes(target))
+            throw new GitWorkspaceError('Not a registered linked worktree', 'git_failed');
+        const callerCommon = (await this.run(repoRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir'], { check: true, timeoutMs: remaining() })).stdout.replace(/\r?\n$/, '');
+        const gitDir = (await this.run(target, ['rev-parse', '--absolute-git-dir'], { check: true, timeoutMs: remaining() })).stdout.replace(/\r?\n$/, '');
+        const registryRoot = join(callerCommon, 'worktrees');
+        if (dirname(resolvePathLikePython(gitDir)) !== resolvePathLikePython(registryRoot))
+            throw new GitWorkspaceError('Worktree Git directory does not belong to the repository', 'git_failed');
+        const lockPath = join(gitDir, 'index.lock');
+        let lock;
+        try {
+            lock = openSync(lockPath, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                throw new GitWorkspaceError('The worktree index is locked by another Git operation', 'operation_in_progress');
+            throw error;
+        }
+        let identity;
+        try {
+            identity = fstatSync(lock);
+            return await this.withStatusRepository(target, remaining, async (prefix, env, _ignores, metadata) => {
+                if (metadata.gitDir !== gitDir || resolvePathLikePython(metadata.commonDir) !== resolvePathLikePython(callerCommon))
+                    throw new GitWorkspaceError('Worktree metadata changed during removal', 'operation_in_progress');
+                const entries = await this.run(worktree, [...prefix, 'ls-files', '--stage', '-z'], { check: true, timeoutMs: remaining(), env });
+                // An uninitialized gitlink could become populated between Git's submodule guard and its internal status.
+                if (entries.stdout.split('\0').some((entry) => entry.startsWith('160000 ')))
+                    return { status: 128, stdout: '', stderr: 'Worktrees containing submodules require force=true to remove' };
+                const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+                rmdirSync(join(metadata.privateDir, 'refs'));
+                if (existsSync(join(metadata.commonDir, 'refs')))
+                    symlinkSync(join(metadata.commonDir, 'refs'), join(metadata.privateDir, 'refs'), linkType);
+                else
+                    mkdirSync(join(metadata.privateDir, 'refs'));
+                if (metadata.refStorage === 'reftable') {
+                    writeFileSync(join(metadata.privateDir, 'config'), '\n[core]\nrepositoryFormatVersion = 1\n[extensions]\nrefStorage = reftable\n', { flag: 'a' });
+                    symlinkSync(join(metadata.commonDir, 'reftable'), join(metadata.privateDir, 'reftable'), linkType);
+                }
+                else if (metadata.refStorage !== 'files')
+                    throw new GitWorkspaceError('Unsupported Git reference format', 'git_failed');
+                const registry = join(metadata.privateDir, 'worktrees');
+                mkdirSync(registry);
+                symlinkSync(gitDir, join(registry, 'target'), linkType);
+                return this.run(repoRoot, [...prefix, 'worktree', 'remove', worktree], { timeoutMs: remaining(), env, commonDir: metadata.privateDir });
+            });
+        }
+        finally {
+            try {
+                const current = lstatSync(lockPath);
+                if (current.dev === identity?.dev && current.ino === identity.ino)
+                    unlinkSync(lockPath);
+            }
+            catch { /* Git may already have removed its administrative directory */ }
+            finally {
+                closeSync(lock);
+            }
+        }
+    }
     async run(ctxOrCwd, args, opts = {}) {
         const cwd = typeof ctxOrCwd === 'string' ? ctxOrCwd : ctxOrCwd.repoRoot;
         const runEnv = this.cleanEnv(opts.env);
+        if (opts.commonDir)
+            runEnv.GIT_COMMON_DIR = opts.commonDir;
         const effectiveDestructive = Boolean(opts.destructive) && this.destructiveEnabled();
         const hardenedDestructive = effectiveDestructive || Boolean(opts.forceDestructiveHardening);
         let attributesFile = null;
@@ -333,10 +628,10 @@ export class GitRunner {
             if (result.error) {
                 const err = result.error;
                 if (err.code === 'ETIMEDOUT')
-                    throw new GitWorkspaceError('Git command timed out', 'timeout');
+                    throw new GitWorkspaceError('Git command timed out', 'timeout', { cause: err });
                 if (err.code === 'ENOENT')
-                    throw new GitWorkspaceError('Git is not installed or not available on PATH', 'missing_git');
-                throw new GitWorkspaceError(err.message, classifyGitError(err.message, args));
+                    throw new GitWorkspaceError('Git is not installed or not available on PATH', 'missing_git', { cause: err });
+                throw new GitWorkspaceError(err.message, classifyGitError(err.message, args), { cause: err });
             }
             const out = { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
             if (opts.check && out.status !== 0) {
@@ -394,15 +689,15 @@ export class GitRunner {
         const rel = relative(ctx.repoRoot, target).split(sep).join('/');
         return rel || '.';
     }
+    /** Git and `repoRel` both separate with `/`; a backslash is a literal POSIX filename character, never a separator. */
     static workspaceRel(ctx, repoRel) {
-        const normalized = repoRel.replace(/\\/g, '/');
         if (!ctx.workspacePrefix)
-            return normalized;
+            return repoRel;
         const prefix = `${ctx.workspacePrefix.replace(/\/+$/, '')}/`;
-        if (normalized === ctx.workspacePrefix)
+        if (repoRel === ctx.workspacePrefix)
             return '.';
-        if (normalized.startsWith(prefix))
-            return normalized.slice(prefix.length);
+        if (repoRel.startsWith(prefix))
+            return repoRel.slice(prefix.length);
         return null;
     }
     // ── mutation lock ────────────────────────────────────────────────────────
@@ -420,7 +715,7 @@ export class GitRunner {
     }
     assertRepoFree(repoRoot) {
         if (this.deps.activeRunIn?.(repoRoot))
-            throw new GitWorkspaceError('A session run is active. Wait for it to finish before running this Git operation.', 'active_stream');
+            throw new GitWorkspaceError(ACTIVE_RUN_MESSAGE, 'active_stream');
         if (overlapsAny(this.writing, repoRoot))
             throw new GitWorkspaceError(WORKSPACE_WRITE_BUSY_MESSAGE, 'operation_in_progress');
     }
@@ -1021,18 +1316,17 @@ export class GitRunner {
         if (!read)
             throw new GitWorkspaceError('Path is not a file');
         if ('tooLarge' in read)
-            return { binary: false, too_large: true, diff: '', additions: 0, deletions: 0 };
+            return { binary: false, too_large: true, diff: '', additions: 0, deletions: 0, hunks: [] };
         const data = read.data;
         const text = data.toString('utf8');
         if (data.includes(0) || (text.includes('�') && !data.equals(Buffer.from(text, 'utf8'))))
-            return { binary: true, too_large: false, diff: '', additions: 0, deletions: 0 };
+            return { binary: true, too_large: false, diff: '', additions: 0, deletions: 0, hunks: [] };
         const diffLines = unifiedDiffFromEmpty(splitLines(text), `b/${label}`);
         let diff = diffLines.join('\n') + (diffLines.length ? '\n' : '');
         const tooLarge = Buffer.byteLength(diff, 'utf8') > DIFF_SIZE_LIMIT;
         if (tooLarge)
             diff = diff.slice(0, DIFF_SIZE_LIMIT);
-        const [additions, deletions] = diffStats(diff);
-        return { binary: false, too_large: tooLarge, diff, additions, deletions };
+        return { binary: false, too_large: tooLarge, diff, ...diffFields(diff, !tooLarge) };
     }
     async diff(workspace, path, kind = 'unstaged') {
         const ctx = await this.resolveContext(workspace);
@@ -1055,8 +1349,7 @@ export class GitRunner {
         const tooLarge = Buffer.byteLength(diff, 'utf8') > DIFF_SIZE_LIMIT;
         if (tooLarge)
             diff = diff.slice(0, DIFF_SIZE_LIMIT);
-        const [additions, deletions] = diffStats(diff);
-        return { path: workspaceRel, kind, binary, too_large: tooLarge, additions, deletions, diff: binary ? '' : diff };
+        return { path: workspaceRel, kind, binary, too_large: tooLarge, ...diffFields(diff, !(binary || tooLarge)), diff: binary ? '' : diff };
     }
     // ── stage / unstage / discard ────────────────────────────────────────────
     static cleanPaths(paths) {