@maudecode/talaria-web 0.0.0

package/dist/workspace/git.js

@@ -0,0 +1,1236 @@
+/**
+ * Git helpers for the workspace panel (Python `api/workspace_git.py`).
+ *
+ * The browser only sends session ids and workspace-relative paths. This module
+ * resolves the workspace server-side, scopes paths before they become Git
+ * pathspecs, and keeps every Git subprocess shell-free, env-scrubbed, hardened
+ * against repo-local config, and bounded by a timeout.
+ */
+import { spawnSync } 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 { dirname, join, relative, resolve, sep } from 'node:path';
+import { isWithin, resolvePathLikePython } from './paths.js';
+import { openAnchoredFd, rmtreeAnchored, safeResolveWs, unlinkAnchored } from './fs.js';
+import { str } from '../util.js';
+export const GIT_TIMEOUT_MS = 5_000;
+export const GIT_REMOTE_TIMEOUT_MS = 60_000;
+export const STATUS_FILE_LIMIT = 500;
+export const STATUS_CACHE_TTL_MS = 2_000;
+export const STATUS_CACHE_LIMIT = 32;
+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';
+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_PREFIXES = ['GIT_CONFIG_KEY_', 'GIT_CONFIG_VALUE_'];
+const BRANCH_SWITCH_STASH_PREFIX = 'hermes-webui branch switch';
+const GIT_HARDENED_CONFIG = [
+    ['core.fsmonitor', 'false'],
+    ['core.sshCommand', 'ssh'],
+    ['core.askPass', ''],
+    ['credential.helper', ''],
+    ['protocol.ext.allow', 'never'],
+    ['core.gitProxy', ''],
+    ['submodule.recurse', 'false'],
+    ['fetch.recurseSubmodules', 'false'],
+];
+const GIT_DESTRUCTIVE_HARDENED_CONFIG = [
+    ['commit.gpgSign', 'false'],
+    ['push.gpgSign', 'false'],
+    ['gpg.program', ''],
+    ['gpg.ssh.program', ''],
+    ['gpg.x509.program', ''],
+    ['core.alternateRefsCommand', ''],
+];
+const CONFLICT_CODES = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
+export class GitWorkspaceError extends Error {
+    code;
+    constructor(message, code = 'git_failed') {
+        super(message);
+        this.code = code;
+        this.name = 'GitWorkspaceError';
+    }
+}
+export function classifyGitError(message, args = []) {
+    const text = message.toLowerCase();
+    const joined = args.join(' ').toLowerCase();
+    if (text.includes('timed out'))
+        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'))
+        return 'not_a_repo';
+    if (text.includes('outside the workspace') || text.includes('outside the git repository'))
+        return 'path_outside_workspace';
+    if (text.includes('authentication failed') || text.includes('permission denied') || text.includes('could not read username'))
+        return 'auth_failed';
+    if (text.includes('no upstream') || text.includes('no configured push destination') || text.includes('has no upstream branch'))
+        return 'no_upstream';
+    if (text.includes('non-fast-forward') || text.includes('fetch first') || (text.includes('rejected') && joined.includes('push')))
+        return 'non_fast_forward';
+    if (text.includes('conflict') || text.includes('unmerged') || (text.includes('merge') && text.includes('needs')))
+        return 'conflict';
+    if (text.includes('working tree') && (text.includes('clean') || text.includes('dirty')))
+        return 'dirty_worktree';
+    if (text.includes('local changes') || text.includes('would be overwritten by checkout'))
+        return 'dirty_worktree';
+    if (text.includes('invalid reference') || text.includes('not a valid') || text.includes('unknown revision'))
+        return 'invalid_ref';
+    if (text.includes('hook'))
+        return 'hook_failed';
+    return 'git_failed';
+}
+/** Unified diff of `[]` → `lines` (Python `difflib.unified_diff` for an empty left side). */
+function unifiedDiffFromEmpty(lines, toFile) {
+    if (!lines.length)
+        return [];
+    // `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];
+}
+function splitLines(text) {
+    // Python `str.splitlines()`: no trailing empty element for a final newline.
+    const lines = text.split(/\r\n|\r|\n/);
+    if (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+export class GitRunner {
+    deps;
+    locks = new Map();
+    statusCache = new Map();
+    generations = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    destructiveEnabled() {
+        return ['1', 'true', 'yes', 'on'].includes((this.deps.env[WORKSPACE_GIT_DESTRUCTIVE_ENV] ?? '').trim().toLowerCase());
+    }
+    cleanEnv(extra) {
+        const env = {};
+        for (const [k, v] of Object.entries(this.deps.env))
+            if (v !== undefined)
+                env[k] = v;
+        Object.assign(env, extra ?? {});
+        for (const key of GIT_ENV_SCRUB_KEYS)
+            Reflect.deleteProperty(env, key);
+        for (const key of Object.keys(env))
+            if (GIT_ENV_SCRUB_PREFIXES.some((p) => key.startsWith(p)))
+                Reflect.deleteProperty(env, key);
+        env.GIT_TERMINAL_PROMPT = '0';
+        return env;
+    }
+    now() {
+        return this.deps.now ? this.deps.now() * 1000 : Date.now();
+    }
+    // ── subprocess ───────────────────────────────────────────────────────────
+    rawGit(cwd, argv, env, timeoutMs, input) {
+        return spawnSync('git', argv, { cwd, env, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, windowsHide: true, ...(input !== undefined ? { input } : {}) });
+    }
+    configNamesForScope(scope, cwd, env, pattern, nameRe, ignoreUnsupported = false) {
+        const result = this.rawGit(cwd, ['config', '--includes', scope, '--name-only', '--get-regexp', pattern], env, GIT_TIMEOUT_MS);
+        const names = new Set();
+        if (result.status !== 0 && result.status !== 1) {
+            if (ignoreUnsupported)
+                return names;
+            const message = (result.stderr || result.stdout || 'Git command failed').trim();
+            throw new GitWorkspaceError(message, classifyGitError(message, ['config']));
+        }
+        for (const line of (result.stdout || '').split('\n')) {
+            const m = nameRe.exec(line.trim());
+            if (m?.[1])
+                names.add(m[1]);
+        }
+        return names;
+    }
+    namesLocalAndWorktree(cwd, env, pattern, nameRe) {
+        const names = this.configNamesForScope('--local', cwd, env, pattern, nameRe);
+        for (const n of this.configNamesForScope('--worktree', cwd, env, pattern, nameRe, true))
+            names.add(n);
+        return names;
+    }
+    filterNames(cwd, env) {
+        return this.namesLocalAndWorktree(cwd, env, String.raw `^filter\..*\.(clean|smudge|process|required)$`, /^filter\.(.+)\.(clean|smudge|process|required)$/);
+    }
+    mergeDriverNames(cwd, env) {
+        return this.namesLocalAndWorktree(cwd, env, String.raw `^merge\..*\.driver$`, /^merge\.(.+)\.driver$/);
+    }
+    remoteHelperNames(cwd, env) {
+        return this.namesLocalAndWorktree(cwd, env, String.raw `^remote\..*\.(uploadpack|receivepack)$`, /^remote\.(.+)\.(uploadpack|receivepack)$/);
+    }
+    static legal(name) {
+        return !name.includes('\n') && !name.includes('\0');
+    }
+    hasRepoLocalFilters(cwd) {
+        return this.filterNames(cwd, this.cleanEnv()).size > 0;
+    }
+    run(ctxOrCwd, args, opts = {}) {
+        const cwd = typeof ctxOrCwd === 'string' ? ctxOrCwd : ctxOrCwd.repoRoot;
+        const runEnv = this.cleanEnv(opts.env);
+        const effectiveDestructive = Boolean(opts.destructive) && this.destructiveEnabled();
+        const hardenedDestructive = effectiveDestructive || Boolean(opts.forceDestructiveHardening);
+        let attributesFile = null;
+        let hooksPath = null;
+        const extraConfigs = [];
+        let argv = [...args];
+        try {
+            if (opts.disableFilterAttributes) {
+                attributesFile = join(mkdtempSync(join(tmpdir(), 'hermes-webui-git-attrs-')), 'attributes');
+                writeFileSync(attributesFile, '');
+            }
+            if (opts.disableFilterAttributes || opts.neutralizeFilterPrograms) {
+                for (const name of [...this.filterNames(cwd, runEnv)].sort()) {
+                    if (!GitRunner.legal(name))
+                        continue;
+                    extraConfigs.push([`filter.${name}.clean`, 'cat'], [`filter.${name}.smudge`, 'cat'], [`filter.${name}.process`, ''], [`filter.${name}.required`, 'false']);
+                }
+            }
+            if (effectiveDestructive) {
+                for (const name of [...this.mergeDriverNames(cwd, runEnv)].sort()) {
+                    if (!GitRunner.legal(name))
+                        continue;
+                    extraConfigs.push([`merge.${name}.driver`, 'git merge-file "%A" "%O" "%B"']);
+                }
+            }
+            if (effectiveDestructive || opts.neutralizeRemoteHelpers) {
+                const names = [...this.remoteHelperNames(cwd, runEnv)].sort();
+                for (const name of names) {
+                    if (!GitRunner.legal(name))
+                        continue;
+                    extraConfigs.push([`remote.${name}.uploadpack`, 'git-upload-pack'], [`remote.${name}.receivepack`, 'git-receive-pack']);
+                }
+                if (names.length && argv.length) {
+                    const command = argv[0];
+                    if (command === 'fetch' || command === 'pull')
+                        argv = [command, '--upload-pack=git-upload-pack', ...argv.slice(1)];
+                    else if (command === 'push')
+                        argv = [command, '--receive-pack=git-receive-pack', ...argv.slice(1)];
+                }
+            }
+            if (hardenedDestructive)
+                hooksPath = mkdtempSync(join(tmpdir(), 'hermes-webui-git-hooks-'));
+            if (extraConfigs.length) {
+                runEnv.GIT_CONFIG_COUNT = String(extraConfigs.length);
+                extraConfigs.forEach(([key, value], i) => {
+                    runEnv[`GIT_CONFIG_KEY_${i}`] = key;
+                    runEnv[`GIT_CONFIG_VALUE_${i}`] = value;
+                });
+            }
+            const full = [];
+            for (const [key, value] of GIT_HARDENED_CONFIG)
+                full.push('-c', `${key}=${value}`);
+            if (hardenedDestructive) {
+                for (const [key, value] of GIT_DESTRUCTIVE_HARDENED_CONFIG)
+                    full.push('-c', `${key}=${value}`);
+                if (hooksPath)
+                    full.push('-c', `core.hooksPath=${hooksPath}`);
+            }
+            if (attributesFile)
+                full.push('-c', `core.attributesFile=${attributesFile}`);
+            full.push(...argv);
+            const result = this.rawGit(cwd, full, runEnv, opts.timeoutMs ?? GIT_TIMEOUT_MS, opts.input);
+            if (result.error) {
+                const err = result.error;
+                if (err.code === 'ETIMEDOUT')
+                    throw new GitWorkspaceError('Git command timed out', 'timeout');
+                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));
+            }
+            const out = { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
+            if (opts.check && out.status !== 0) {
+                const message = (out.stderr || out.stdout || 'Git command failed').trim();
+                throw new GitWorkspaceError(message, classifyGitError(message, args));
+            }
+            return out;
+        }
+        finally {
+            if (attributesFile)
+                rmSync(dirname(attributesFile), { recursive: true, force: true });
+            if (hooksPath)
+                rmSync(hooksPath, { recursive: true, force: true });
+        }
+    }
+    // ── context and paths ────────────────────────────────────────────────────
+    resolveContext(workspace) {
+        const ws = resolvePathLikePython(workspace);
+        // Python ran `git rev-parse` with `cwd=<workspace>`; a vanished directory raised `FileNotFoundError`, which `_run_git`
+        // reported as `missing_git` — every route answered 400 rather than "not a repo".
+        if (!existsSync(ws))
+            throw new GitWorkspaceError('Git is not installed or not available on PATH', 'missing_git');
+        let result;
+        try {
+            result = this.run(ws, ['rev-parse', '--show-toplevel']);
+        }
+        catch (error) {
+            if (error instanceof GitWorkspaceError && (error.code === 'missing_git' || error.code === 'timeout'))
+                throw error;
+            return null;
+        }
+        if (result.status !== 0)
+            return null;
+        const repoRoot = resolvePathLikePython(result.stdout.trim());
+        if (ws !== repoRoot && !isWithin(ws, repoRoot))
+            return null;
+        const prefix = ws === repoRoot ? '' : relative(repoRoot, ws).split(sep).join('/');
+        return { workspace: ws, repoRoot, workspacePrefix: prefix };
+    }
+    static workspacePathspec(ctx) {
+        return ctx.workspacePrefix || '.';
+    }
+    static repoRel(ctx, workspaceRel) {
+        let target;
+        try {
+            target = safeResolveWs(ctx.workspace, workspaceRel || '.');
+        }
+        catch (error) {
+            throw new GitWorkspaceError(error.message, 'path_outside_workspace');
+        }
+        if (target !== ctx.repoRoot && !isWithin(target, ctx.repoRoot))
+            throw new GitWorkspaceError('Path is outside the Git repository', 'path_outside_workspace');
+        if (ctx.workspacePrefix && target !== ctx.workspace && !isWithin(target, ctx.workspace))
+            throw new GitWorkspaceError('Path is outside the workspace', 'path_outside_workspace');
+        const rel = relative(ctx.repoRoot, target).split(sep).join('/');
+        return rel || '.';
+    }
+    static workspaceRel(ctx, repoRel) {
+        const normalized = repoRel.replace(/\\/g, '/');
+        if (!ctx.workspacePrefix)
+            return normalized;
+        const prefix = `${ctx.workspacePrefix.replace(/\/+$/, '')}/`;
+        if (normalized === ctx.workspacePrefix)
+            return '.';
+        if (normalized.startsWith(prefix))
+            return normalized.slice(prefix.length);
+        return null;
+    }
+    // ── mutation lock ────────────────────────────────────────────────────────
+    async withMutationLock(ctx, fn) {
+        const key = ctx.repoRoot;
+        const previous = this.locks.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((r) => { release = r; });
+        const chained = previous.then(() => current);
+        this.locks.set(key, chained);
+        let timer;
+        const acquired = await Promise.race([previous.then(() => true), new Promise((r) => { timer = setTimeout(() => { r(false); }, GIT_REMOTE_TIMEOUT_MS); })]);
+        clearTimeout(timer);
+        if (!acquired) {
+            release();
+            throw new GitWorkspaceError('Another Git operation is still running', 'operation_in_progress');
+        }
+        try {
+            return fn();
+        }
+        finally {
+            this.invalidateStatusCache(ctx.repoRoot);
+            release();
+            if (this.locks.get(key) === chained)
+                this.locks.delete(key);
+        }
+    }
+    // ── status cache ─────────────────────────────────────────────────────────
+    static resolveGitDir(repoRoot) {
+        const dotGit = join(repoRoot, '.git');
+        try {
+            if (statSync(dotGit).isFile()) {
+                const text = readFileSync(dotGit, 'utf8').trim();
+                if (text.startsWith('gitdir:')) {
+                    const target = text.slice('gitdir:'.length).trim();
+                    return resolve(repoRoot, target);
+                }
+            }
+        }
+        catch { /* fall through */ }
+        return dotGit;
+    }
+    statusFingerprint(repoRoot) {
+        const gitDir = GitRunner.resolveGitDir(repoRoot);
+        const parts = [String(this.destructiveEnabled())];
+        for (const name of ['index', 'HEAD']) {
+            try {
+                const st = statSync(join(gitDir, name), { bigint: true });
+                parts.push(`${st.mtimeNs}:${st.size}:${st.ino}`);
+            }
+            catch {
+                parts.push('null');
+            }
+        }
+        return parts.join('|');
+    }
+    cachedStatus(workspace) {
+        const entry = this.statusCache.get(workspace);
+        if (!entry)
+            return null;
+        if (this.now() - entry.storedAt >= STATUS_CACHE_TTL_MS || this.statusFingerprint(entry.repoRoot) !== entry.fingerprint) {
+            this.statusCache.delete(workspace);
+            return null;
+        }
+        return structuredClone(entry.payload);
+    }
+    storeStatus(ctx, generation, fingerprint, payload) {
+        if ((this.generations.get(ctx.repoRoot) ?? 0) !== generation)
+            return;
+        if (!this.statusCache.has(ctx.workspace) && this.statusCache.size >= STATUS_CACHE_LIMIT) {
+            const oldest = this.statusCache.keys().next();
+            if (!oldest.done)
+                this.statusCache.delete(oldest.value);
+        }
+        this.statusCache.set(ctx.workspace, { storedAt: this.now(), repoRoot: ctx.repoRoot, fingerprint, payload: structuredClone(payload) });
+    }
+    invalidateStatusCache(repoRoot) {
+        this.generations.set(repoRoot, (this.generations.get(repoRoot) ?? 0) + 1);
+        for (const [key, entry] of this.statusCache)
+            if (entry.repoRoot === repoRoot)
+                this.statusCache.delete(key);
+    }
+    // ── status ───────────────────────────────────────────────────────────────
+    static statusCode(xy, untracked, renamed) {
+        if (untracked)
+            return '??';
+        if (CONFLICT_CODES.has(xy))
+            return xy;
+        if (renamed)
+            return 'R';
+        for (const ch of xy)
+            if ('MADRCUT'.includes(ch))
+                return ch;
+        return xy.replace(/^\.+|\.+$/g, '') || 'M';
+    }
+    parseNumstat(text, ctx) {
+        const stats = new Map();
+        const tokens = text.split('\0');
+        let i = 0;
+        while (i < tokens.length) {
+            const record = tokens[i] ?? '';
+            i += 1;
+            if (!record)
+                continue;
+            const first = record.indexOf('\t');
+            const second = first >= 0 ? record.indexOf('\t', first + 1) : -1;
+            if (first < 0 || second < 0)
+                continue;
+            const rawAdd = record.slice(0, first);
+            const rawDel = record.slice(first + 1, second);
+            let rawPath = record.slice(second + 1);
+            if (!rawPath) {
+                if (i + 1 >= tokens.length)
+                    break;
+                rawPath = tokens[i + 1] ?? '';
+                i += 2;
+            }
+            const binary = rawAdd === '-' || rawDel === '-';
+            const additions = binary ? 0 : Number.parseInt(rawAdd || '0', 10) || 0;
+            const deletions = binary ? 0 : Number.parseInt(rawDel || '0', 10) || 0;
+            const workspacePath = GitRunner.workspaceRel(ctx, rawPath);
+            if (workspacePath === null)
+                continue;
+            stats.set(workspacePath, [additions, deletions, binary]);
+        }
+        return stats;
+    }
+    collectNumstat(ctx, cached) {
+        const args = ['diff', '--numstat', '-z', '--no-textconv', '--ignore-cr-at-eol'];
+        if (cached)
+            args.push('--cached');
+        args.push('--', GitRunner.workspacePathspec(ctx));
+        const result = this.run(ctx, args, { disableFilterAttributes: this.destructiveEnabled(), neutralizeFilterPrograms: true });
+        if (result.status !== 0)
+            return null;
+        return this.parseNumstat(result.stdout, ctx);
+    }
+    /** An untracked file's bytes through the anchored walk (no symlinked component), or null when unreadable/too large. */
+    static readUntracked(workspace, path) {
+        let fd;
+        // Python read an untracked symlink through its target; that is kept for links that stay inside the workspace, so
+        // a link pointing outside can never pull foreign bytes into a diff.
+        let source = path;
+        try {
+            if (lstatSync(path).isSymbolicLink()) {
+                const real = realpathSync(path);
+                const root = realpathSync(workspace);
+                if (real !== root && !isWithin(real, root))
+                    return null;
+                source = real;
+            }
+        }
+        catch {
+            return null;
+        }
+        try {
+            fd = openAnchoredFd(workspace, source, { wantDir: false });
+        }
+        catch {
+            return null;
+        }
+        try {
+            const st = fstatSync(fd);
+            if (!st.isFile())
+                return null;
+            if (st.size > DIFF_SIZE_LIMIT)
+                return { tooLarge: true };
+            return { data: readFileSync(fd) };
+        }
+        catch {
+            return null;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    static countUntrackedFile(workspace, path) {
+        const read = GitRunner.readUntracked(workspace, path);
+        if (!read || 'tooLarge' in read)
+            return [0, 0, false];
+        const data = read.data;
+        if (data.includes(0))
+            return [0, 0, true];
+        const text = data.toString('utf8');
+        if (text.includes('�') && !data.equals(Buffer.from(text, 'utf8')))
+            return [0, 0, true];
+        return [splitLines(text).length || (text ? 1 : 0), 0, false];
+    }
+    status(workspace, opts = {}) {
+        const resolved = resolvePathLikePython(workspace);
+        if (opts.useCache) {
+            const cached = this.cachedStatus(resolved);
+            if (cached)
+                return cached;
+        }
+        const ctx = this.resolveContext(resolved);
+        if (!ctx)
+            return { is_git: false };
+        const generation = this.generations.get(ctx.repoRoot) ?? 0;
+        const result = this.run(ctx, ['status', '--porcelain=v2', '-z', '--branch', '--untracked-files=all', '--', GitRunner.workspacePathspec(ctx)], { check: true, disableFilterAttributes: this.destructiveEnabled(), neutralizeFilterPrograms: true });
+        const stagedStats = this.collectNumstat(ctx, true);
+        const unstagedStats = this.collectNumstat(ctx, false);
+        const statSources = [stagedStats ?? new Map(), unstagedStats ?? new Map()];
+        let branch = '';
+        let upstream = '';
+        let ahead = 0;
+        let behind = 0;
+        const files = new Map();
+        const noise = { filemode_only: 0, crlf_only: 0 };
+        const tokens = result.stdout.split('\0');
+        let i = 0;
+        let truncated = false;
+        while (i < tokens.length) {
+            const rec = tokens[i] ?? '';
+            i += 1;
+            if (!rec)
+                continue;
+            if (rec.startsWith('# ')) {
+                const parts = rec.split(' ');
+                const key = parts[1];
+                const value = parts.slice(2).join(' ');
+                if (key === 'branch.head')
+                    branch = value === '(detached)' ? '' : value;
+                else if (key === 'branch.upstream')
+                    upstream = value;
+                else if (key === 'branch.ab') {
+                    for (const bit of value.split(/\s+/)) {
+                        if (bit.startsWith('+') && /^\d+$/.test(bit.slice(1)))
+                            ahead = Number.parseInt(bit.slice(1), 10);
+                        else if (bit.startsWith('-') && /^\d+$/.test(bit.slice(1)))
+                            behind = Number.parseInt(bit.slice(1), 10);
+                    }
+                }
+                continue;
+            }
+            let oldPath = null;
+            let renamed = false;
+            let modeHead = '';
+            let modeIndex = '';
+            let modeWorktree = '';
+            let xy;
+            let repoPath;
+            let untracked;
+            if (rec.startsWith('? ')) {
+                xy = '??';
+                repoPath = rec.slice(2);
+                untracked = true;
+            }
+            else if (rec.startsWith('1 ')) {
+                const parts = rec.split(' ');
+                if (parts.length < 9)
+                    continue;
+                xy = parts[1] ?? '';
+                modeHead = parts[3] ?? '';
+                modeIndex = parts[4] ?? '';
+                modeWorktree = parts[5] ?? '';
+                repoPath = parts.slice(8).join(' ');
+                untracked = false;
+            }
+            else if (rec.startsWith('2 ')) {
+                const parts = rec.split(' ');
+                if (parts.length < 10)
+                    continue;
+                xy = parts[1] ?? '';
+                modeHead = parts[3] ?? '';
+                modeIndex = parts[4] ?? '';
+                modeWorktree = parts[5] ?? '';
+                repoPath = parts.slice(9).join(' ');
+                if (i < tokens.length) {
+                    oldPath = tokens[i] ?? null;
+                    i += 1;
+                }
+                renamed = true;
+                untracked = false;
+            }
+            else if (rec.startsWith('u ')) {
+                const parts = rec.split(' ');
+                if (parts.length < 11)
+                    continue;
+                xy = parts[1] ?? '';
+                repoPath = parts.slice(10).join(' ');
+                untracked = false;
+            }
+            else
+                continue;
+            const workspacePath = GitRunner.workspaceRel(ctx, repoPath);
+            if (workspacePath === null)
+                continue;
+            const oldWorkspacePath = oldPath ? GitRunner.workspaceRel(ctx, oldPath) : null;
+            const x = xy[0] ?? '.';
+            const y = xy[1] ?? '.';
+            const conflict = CONFLICT_CODES.has(xy) || rec.startsWith('u ');
+            let additions = 0;
+            let deletions = 0;
+            let binary = false;
+            for (const source of statSources) {
+                const entry = source.get(workspacePath);
+                if (entry) {
+                    additions += entry[0];
+                    deletions += entry[1];
+                    binary = binary || entry[2];
+                }
+            }
+            if (untracked)
+                [additions, deletions, binary] = GitRunner.countUntrackedFile(ctx.workspace, join(ctx.workspace, workspacePath));
+            let staged = x !== '.' && x !== '?' && !untracked;
+            let unstaged = y !== '.' && y !== ' ' && !untracked;
+            if (staged && stagedStats && !renamed) {
+                staged = stagedStats.has(workspacePath) || (oldWorkspacePath !== null && stagedStats.has(oldWorkspacePath));
+                if (!staged)
+                    noise.crlf_only += 1;
+            }
+            if (unstaged && unstagedStats && !renamed) {
+                unstaged = unstagedStats.has(workspacePath) || (oldWorkspacePath !== null && unstagedStats.has(oldWorkspacePath));
+                if (!unstaged)
+                    noise.crlf_only += 1;
+            }
+            if (!(staged || unstaged || untracked || conflict || renamed))
+                continue;
+            if (!(untracked || conflict || renamed || binary) && additions === 0 && deletions === 0) {
+                const modeOnly = (staged && modeHead !== modeIndex) || (unstaged && modeIndex !== modeWorktree);
+                noise[modeOnly ? 'filemode_only' : 'crlf_only'] += 1;
+                continue;
+            }
+            files.set(workspacePath, {
+                path: workspacePath, old_path: oldWorkspacePath, workspace_path: workspacePath, status: GitRunner.statusCode(xy, untracked, renamed),
+                staged, unstaged, untracked, ignored: false, conflict, additions, deletions, binary,
+            });
+            if (files.size >= STATUS_FILE_LIMIT) {
+                truncated = true;
+                break;
+            }
+        }
+        const fileList = [...files.values()].sort((a, b) => (a.path.toLowerCase() < b.path.toLowerCase() ? -1 : a.path.toLowerCase() > b.path.toLowerCase() ? 1 : 0));
+        const totals = { changed: fileList.length, staged: 0, unstaged: 0, untracked: 0, conflicts: 0 };
+        for (const item of fileList) {
+            if (item.staged)
+                totals.staged += 1;
+            if (item.unstaged)
+                totals.unstaged += 1;
+            if (item.untracked)
+                totals.untracked += 1;
+            if (item.conflict)
+                totals.conflicts += 1;
+        }
+        if (!branch)
+            branch = this.run(ctx, ['rev-parse', '--short', 'HEAD']).stdout.trim();
+        const payload = {
+            is_git: true, branch: branch || 'HEAD', upstream, ahead, behind, totals, files: fileList, truncated,
+            noise_filtering: { ...noise, active: noise.filemode_only > 0 || noise.crlf_only > 0 },
+        };
+        this.storeStatus(ctx, generation, this.statusFingerprint(ctx.repoRoot), payload);
+        return payload;
+    }
+    // ── branches ─────────────────────────────────────────────────────────────
+    branchAheadBehind(ctx, branch, upstream) {
+        if (!upstream)
+            return [0, 0];
+        const result = this.run(ctx, ['rev-list', '--left-right', '--count', `${branch}...${upstream}`]);
+        if (result.status !== 0)
+            return [0, 0];
+        const parts = result.stdout.trim().split(/\s+/);
+        if (parts.length !== 2)
+            return [0, 0];
+        const a = Number.parseInt(parts[0] ?? '', 10);
+        const b = Number.parseInt(parts[1] ?? '', 10);
+        return Number.isFinite(a) && Number.isFinite(b) ? [a, b] : [0, 0];
+    }
+    forEachRef(ctx, refPrefix) {
+        const fmt = '%(refname)%00%(refname:short)%00%(upstream:short)%00%(objectname:short)%00%(committerdate:unix)%00%(committerdate:relative)%00%(authorname)%00%(subject)';
+        const result = this.run(ctx, ['for-each-ref', `--format=${fmt}`, refPrefix], { check: true });
+        const refs = [];
+        for (const line of result.stdout.split('\n')) {
+            const [fullName = '', name = '', upstream = '', sha = '', updated = '', updatedRelative = '', author = '', subject = ''] = line.split('\0');
+            if (!name || fullName.endsWith('/HEAD') || name.endsWith('/HEAD'))
+                continue;
+            if (refPrefix === 'refs/remotes' && !name.includes('/'))
+                continue;
+            const item = { name, sha, updated: /^\d+$/.test(updated) ? Number.parseInt(updated, 10) : 0, updated_relative: updatedRelative, author, subject, upstream: '', ahead: 0, behind: 0 };
+            if (upstream) {
+                const [ahead, behind] = this.branchAheadBehind(ctx, name, upstream);
+                Object.assign(item, { upstream, ahead, behind });
+            }
+            refs.push(item);
+        }
+        return refs.sort((a, b) => (a.name.toLowerCase() < b.name.toLowerCase() ? -1 : a.name.toLowerCase() > b.name.toLowerCase() ? 1 : 0));
+    }
+    branches(workspace) {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository', 'not_a_repo');
+        const headName = this.run(ctx, ['branch', '--show-current'], { check: true }).stdout.trim();
+        const headSha = this.run(ctx, ['rev-parse', '--short', 'HEAD'], { check: true }).stdout.trim();
+        const status = this.status(workspace);
+        return {
+            is_git: true, current: headName || headSha || 'HEAD', detached: !headName, head: headSha,
+            local: this.forEachRef(ctx, 'refs/heads'), remote: this.forEachRef(ctx, 'refs/remotes'),
+            upstream: status.upstream ?? '', ahead: status.ahead ?? 0, behind: status.behind ?? 0,
+        };
+    }
+    // ── checkout ─────────────────────────────────────────────────────────────
+    validateLocalBranch(ctx, ref) {
+        const r = ref.trim();
+        if (!r)
+            throw new GitWorkspaceError('Branch name is required', 'invalid_ref');
+        this.run(ctx, ['show-ref', '--verify', `refs/heads/${r}`], { check: true });
+        return r;
+    }
+    validateRemoteBranch(ctx, ref) {
+        const r = ref.trim();
+        if (!r)
+            throw new GitWorkspaceError('Remote branch name is required', 'invalid_ref');
+        this.run(ctx, ['show-ref', '--verify', `refs/remotes/${r}`], { check: true });
+        return r;
+    }
+    validateCheckoutStart(ctx, ref) {
+        const r = (ref || 'HEAD').trim() || 'HEAD';
+        if (this.run(ctx, ['rev-parse', '--verify', `${r}^{commit}`]).status !== 0)
+            throw new GitWorkspaceError('Invalid checkout reference', 'invalid_ref');
+        return r;
+    }
+    validateNewBranchName(ctx, name) {
+        const n = name.trim();
+        if (!n)
+            throw new GitWorkspaceError('New branch name is required', 'invalid_ref');
+        if (this.run(ctx, ['check-ref-format', '--branch', n]).status !== 0)
+            throw new GitWorkspaceError('Invalid branch name', 'invalid_ref');
+        if (this.run(ctx, ['show-ref', '--verify', `refs/heads/${n}`]).status === 0)
+            throw new GitWorkspaceError('A local branch with that name already exists', 'invalid_ref');
+        return n;
+    }
+    dirtyWorktree(ctx) {
+        return this.run(ctx, ['status', '--porcelain=v2', '--untracked-files=all'], { check: true, neutralizeFilterPrograms: true }).stdout.trim() !== '';
+    }
+    currentCheckoutLabel(ctx) {
+        const branch = this.run(ctx, ['branch', '--show-current']).stdout.trim();
+        if (branch)
+            return branch;
+        return this.run(ctx, ['rev-parse', '--short', 'HEAD'], { check: true }).stdout.trim() || 'HEAD';
+    }
+    static stashSubjectParts(subject) {
+        const s = subject.trim();
+        if (!s.startsWith('On ') || !s.includes(': '))
+            return null;
+        const idx = s.indexOf(': ');
+        const branch = s.slice(3, idx).trim();
+        const message = s.slice(idx + 2).trim();
+        if (!branch || !message.startsWith(BRANCH_SWITCH_STASH_PREFIX))
+            return null;
+        return [branch, message];
+    }
+    branchSwitchStashes(ctx) {
+        const result = this.run(ctx, ['stash', 'list', '--format=%gd%x00%gs']);
+        if (result.status !== 0)
+            return [];
+        const out = [];
+        for (const line of result.stdout.split('\n')) {
+            const idx = line.indexOf('\0');
+            if (idx < 0)
+                continue;
+            const parts = GitRunner.stashSubjectParts(line.slice(idx + 1));
+            if (!parts)
+                continue;
+            out.push({ ref: line.slice(0, idx), branch: parts[0], message: parts[1] });
+        }
+        return out;
+    }
+    restoreBranchSwitchStashLocked(ctx, branch) {
+        if (this.destructiveEnabled() && this.hasRepoLocalFilters(ctx.repoRoot))
+            return { restore_blocked: true, restore_reason: 'Repository defines local filter programs' };
+        if (this.dirtyWorktree(ctx))
+            return {};
+        for (const item of this.branchSwitchStashes(ctx)) {
+            if (item.branch !== branch)
+                continue;
+            const result = this.run(ctx, ['stash', 'pop', '--index', item.ref], { destructive: true, disableFilterAttributes: true });
+            if (result.status === 0)
+                return { restored_stash: item };
+            return { restore_failed: true, restore_error: (result.stderr || result.stdout || 'Git stash restore failed').trim(), restore_stash: item };
+        }
+        return {};
+    }
+    validateCheckoutRequestLocked(ctx, ref, mode, newBranch) {
+        if (mode === 'local') {
+            this.validateLocalBranch(ctx, ref);
+            return;
+        }
+        if (mode === 'new' || mode === 'create') {
+            this.validateNewBranchName(ctx, newBranch || ref);
+            this.validateCheckoutStart(ctx, newBranch && ref && ref !== newBranch ? ref : 'HEAD');
+            return;
+        }
+        if (mode === 'remote') {
+            const remoteRef = this.validateRemoteBranch(ctx, ref);
+            const branchName = (newBranch || remoteRef.split('/').slice(1).join('/')).trim();
+            if (this.run(ctx, ['show-ref', '--verify', `refs/heads/${branchName}`]).status !== 0)
+                this.validateNewBranchName(ctx, branchName);
+            return;
+        }
+        if (mode === 'detached' || mode === 'detach') {
+            this.validateCheckoutStart(ctx, ref);
+            return;
+        }
+        throw new GitWorkspaceError('Unsupported checkout mode', 'invalid_ref');
+    }
+    performCheckoutLocked(ctx, ref, mode, newBranch, track) {
+        if (this.destructiveEnabled() && this.hasRepoLocalFilters(ctx.repoRoot)) {
+            throw new GitWorkspaceError('Cannot checkout: repository defines local filter programs that would alter file content', 'filtered_path');
+        }
+        const destructive = { check: true, destructive: true, disableFilterAttributes: true };
+        if (mode === 'local')
+            return this.run(ctx, ['switch', '--recurse-submodules=no', this.validateLocalBranch(ctx, ref)], destructive);
+        if (mode === 'new' || mode === 'create') {
+            const branch = this.validateNewBranchName(ctx, newBranch || ref);
+            const startRef = this.validateCheckoutStart(ctx, newBranch && ref && ref !== newBranch ? ref : 'HEAD');
+            return this.run(ctx, ['switch', '--recurse-submodules=no', '-c', branch, startRef], destructive);
+        }
+        if (mode === 'remote') {
+            const remoteRef = this.validateRemoteBranch(ctx, ref);
+            const branchName = (newBranch || remoteRef.split('/').slice(1).join('/')).trim();
+            if (this.run(ctx, ['show-ref', '--verify', `refs/heads/${branchName}`]).status === 0) {
+                const result = this.run(ctx, ['switch', '--recurse-submodules=no', branchName], destructive);
+                if (track)
+                    this.run(ctx, ['branch', '--set-upstream-to', remoteRef, branchName]);
+                return result;
+            }
+            const branch = this.validateNewBranchName(ctx, branchName);
+            const args = ['switch', '--recurse-submodules=no', '-c', branch];
+            if (track)
+                args.push('--track');
+            args.push(remoteRef);
+            return this.run(ctx, args, destructive);
+        }
+        if (mode === 'detached' || mode === 'detach')
+            return this.run(ctx, ['switch', '--recurse-submodules=no', '--detach', this.validateCheckoutStart(ctx, ref)], destructive);
+        throw new GitWorkspaceError('Unsupported checkout mode', 'invalid_ref');
+    }
+    static remoteMessage(result) {
+        return (result.stdout || result.stderr || '').trim();
+    }
+    async checkout(workspace, ref, mode, opts = {}) {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository', 'not_a_repo');
+        const m = (mode || 'local').trim().toLowerCase();
+        const dirtyMode = (opts.dirtyMode || 'block').trim().toLowerCase();
+        if (dirtyMode !== 'block')
+            throw new GitWorkspaceError('Only dirty_mode=block is supported for branch checkout', 'dirty_worktree');
+        const result = await this.withMutationLock(ctx, () => {
+            this.validateCheckoutRequestLocked(ctx, ref, m, opts.newBranch ?? null);
+            if (this.dirtyWorktree(ctx))
+                throw new GitWorkspaceError('Checkout blocked because the Git worktree has uncommitted changes', 'dirty_worktree');
+            return this.performCheckoutLocked(ctx, ref, m, opts.newBranch ?? null, Boolean(opts.track));
+        });
+        const status = this.status(workspace);
+        const branches = this.branches(workspace);
+        return { ok: true, message: GitRunner.remoteMessage(result), current_branch: branches.current, status, branches };
+    }
+    async stashAndCheckout(workspace, ref, mode, opts = {}) {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository', 'not_a_repo');
+        const m = (mode || 'local').trim().toLowerCase();
+        const targetLabel = (opts.newBranch || ref || 'HEAD').trim() || 'HEAD';
+        const stashName = `${BRANCH_SWITCH_STASH_PREFIX} to ${targetLabel}`.trim();
+        const outcome = await this.withMutationLock(ctx, () => {
+            this.validateCheckoutRequestLocked(ctx, ref, m, opts.newBranch ?? null);
+            if (this.destructiveEnabled() && this.hasRepoLocalFilters(ctx.repoRoot)) {
+                throw new GitWorkspaceError('Cannot stash: repository defines local filter programs that would alter file content', 'filtered_path');
+            }
+            let stashed = false;
+            if (this.dirtyWorktree(ctx)) {
+                const stashResult = this.run(ctx, ['stash', 'push', '-u', '-m', stashName], { check: true, destructive: true, disableFilterAttributes: true });
+                stashed = !GitRunner.remoteMessage(stashResult).includes('No local changes to save');
+            }
+            let result;
+            try {
+                result = this.performCheckoutLocked(ctx, ref, m, opts.newBranch ?? null, Boolean(opts.track));
+            }
+            catch (error) {
+                if (stashed)
+                    this.run(ctx, ['stash', 'pop', '--index', 'stash@{0}'], { destructive: true, disableFilterAttributes: true });
+                throw error;
+            }
+            const restored = this.restoreBranchSwitchStashLocked(ctx, this.currentCheckoutLabel(ctx));
+            return { result, stashed, restored };
+        });
+        const status = this.status(workspace);
+        const branches = this.branches(workspace);
+        const { restored } = outcome;
+        return {
+            ok: true, message: GitRunner.remoteMessage(outcome.result), stash_name: outcome.stashed ? stashName : '', stashed: outcome.stashed,
+            restored_stash: restored.restored_stash ?? null, restore_failed: Boolean(restored.restore_failed), restore_error: str(restored.restore_error),
+            restore_stash: restored.restore_stash ?? null, current_branch: branches.current, status, branches,
+        };
+    }
+    // ── diff ─────────────────────────────────────────────────────────────────
+    static syntheticUntrackedDiff(workspace, path, label) {
+        const read = GitRunner.readUntracked(workspace, path);
+        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 };
+        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 };
+        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 };
+    }
+    diff(workspace, path, kind = 'unstaged') {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository');
+        if (kind !== 'unstaged' && kind !== 'staged')
+            throw new GitWorkspaceError('kind must be staged or unstaged');
+        const repoRel = GitRunner.repoRel(ctx, path);
+        const workspaceRel = GitRunner.workspaceRel(ctx, repoRel) ?? path;
+        const status = this.status(workspace);
+        const fileState = (status.files ?? []).find((f) => f.path === workspaceRel);
+        if (kind === 'unstaged' && fileState?.untracked)
+            return { path: workspaceRel, kind, ...GitRunner.syntheticUntrackedDiff(ctx.workspace, join(ctx.workspace, workspaceRel), workspaceRel) };
+        const args = ['diff', '--no-ext-diff', '--no-textconv', '--unified=3'];
+        if (kind === 'staged')
+            args.push('--cached');
+        args.push('--', repoRel);
+        let diff = this.run(ctx, args, { check: true, neutralizeFilterPrograms: true }).stdout;
+        const binary = diff.includes('Binary files ') || diff.includes('GIT binary patch');
+        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 };
+    }
+    // ── stage / unstage / discard ────────────────────────────────────────────
+    static cleanPaths(paths) {
+        const cleaned = [];
+        for (const p of paths) {
+            const value = str(p).trim();
+            if (value && !cleaned.includes(value))
+                cleaned.push(value);
+        }
+        if (!cleaned.length)
+            throw new GitWorkspaceError('At least one path is required');
+        return cleaned;
+    }
+    static pathspecs(ctx, paths) {
+        return GitRunner.cleanPaths(paths).map((p) => GitRunner.repoRel(ctx, p));
+    }
+    blockFilteredDestructiveWrite(ctx, message) {
+        if (this.destructiveEnabled() && this.hasRepoLocalFilters(ctx.repoRoot))
+            throw new GitWorkspaceError(message, 'filtered_path');
+    }
+    requireContext(workspace) {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository', 'not_a_repo');
+        return ctx;
+    }
+    async stage(workspace, paths) {
+        const ctx = this.requireContext(workspace);
+        await this.withMutationLock(ctx, () => {
+            this.blockFilteredDestructiveWrite(ctx, 'Repository uses local Git filters; stage may corrupt index content. Use the terminal to stage manually.');
+            this.run(ctx, ['add', '--', ...GitRunner.pathspecs(ctx, paths)], { check: true, destructive: true, disableFilterAttributes: true });
+        });
+        return this.status(workspace);
+    }
+    async unstage(workspace, paths) {
+        const ctx = this.requireContext(workspace);
+        const specs = GitRunner.pathspecs(ctx, paths);
+        await this.withMutationLock(ctx, () => {
+            const result = this.run(ctx, ['restore', '--staged', '--', ...specs], { destructive: true });
+            if (result.status !== 0)
+                this.run(ctx, ['reset', 'HEAD', '--', ...specs], { check: true, destructive: true });
+        });
+        return this.status(workspace);
+    }
+    async discard(workspace, paths, opts = {}) {
+        const ctx = this.requireContext(workspace);
+        await this.withMutationLock(ctx, () => {
+            this.blockFilteredDestructiveWrite(ctx, 'Repository uses local Git filters; discard may corrupt working-tree content. Use the terminal to discard manually.');
+            const status = this.status(workspace);
+            const byPath = new Map((status.files ?? []).map((f) => [f.path, f]));
+            for (const path of GitRunner.cleanPaths(paths)) {
+                const repoRel = GitRunner.repoRel(ctx, path);
+                const workspaceRel = GitRunner.workspaceRel(ctx, repoRel) ?? path;
+                const state = byPath.get(workspaceRel) ?? byPath.get(`${workspaceRel.replace(/\/+$/, '')}/`);
+                if (state?.conflict)
+                    throw new GitWorkspaceError('Conflicted files cannot be discarded from this panel', 'conflict');
+                if (state?.untracked) {
+                    if (!opts.deleteUntracked)
+                        throw new GitWorkspaceError('Untracked files require delete_untracked=true');
+                    const target = safeResolveWs(ctx.workspace, workspaceRel);
+                    let isDir = false;
+                    try {
+                        isDir = lstatSync(target).isDirectory();
+                    }
+                    catch {
+                        isDir = false;
+                    }
+                    if (isDir)
+                        rmtreeAnchored(ctx.workspace, target);
+                    else {
+                        try {
+                            unlinkAnchored(ctx.workspace, target);
+                        }
+                        catch (error) {
+                            if (error.code !== 'ENOENT')
+                                throw error;
+                        }
+                    }
+                    continue;
+                }
+                this.run(ctx, ['restore', '--worktree', '--', repoRel], { check: true, destructive: true, disableFilterAttributes: true });
+            }
+        });
+        return this.status(workspace);
+    }
+    // ── commit messages ──────────────────────────────────────────────────────
+    stagedDiffText(ctx) {
+        const diff = this.run(ctx, ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--unified=3', '--', GitRunner.workspacePathspec(ctx)], { check: true, neutralizeFilterPrograms: true }).stdout;
+        return GitRunner.capDiff(diff);
+    }
+    static capDiff(diff) {
+        const encoded = Buffer.from(diff, 'utf8');
+        if (encoded.length <= COMMIT_MESSAGE_DIFF_LIMIT)
+            return [diff, false];
+        return [encoded.subarray(0, COMMIT_MESSAGE_DIFF_LIMIT).toString('utf8'), true];
+    }
+    selectedTempIndexEnv(ctx, specs) {
+        this.blockFilteredDestructiveWrite(ctx, 'Repository uses local Git filters; selected commit staging may corrupt index content. Use the terminal to commit manually.');
+        const dir = mkdtempSync(join(tmpdir(), 'hermes-webui-git-index-'));
+        const indexPath = join(dir, 'index');
+        const env = { GIT_INDEX_FILE: indexPath };
+        try {
+            const head = this.run(ctx, ['rev-parse', '--verify', 'HEAD'], { env, destructive: true });
+            if (head.status === 0)
+                this.run(ctx, ['read-tree', 'HEAD'], { check: true, env, destructive: true });
+            else
+                this.run(ctx, ['read-tree', '--empty'], { check: true, env, destructive: true });
+            this.run(ctx, ['add', '-A', '--', ...specs], { check: true, env, destructive: true, disableFilterAttributes: true });
+            return [env, dir];
+        }
+        catch (error) {
+            rmSync(dir, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    selectedFiles(ctx, paths) {
+        const requested = GitRunner.cleanPaths(paths);
+        const requestedSpecs = requested.map((p) => GitRunner.repoRel(ctx, p));
+        const workspacePaths = requestedSpecs.map((spec, i) => GitRunner.workspaceRel(ctx, spec) ?? requested[i] ?? spec);
+        const status = this.status(ctx.workspace);
+        const byPath = new Map((status.files ?? []).map((f) => [f.path, f]));
+        const specs = [];
+        const selected = [];
+        workspacePaths.forEach((path, i) => {
+            const state = byPath.get(path);
+            if (!state)
+                return;
+            if (state.conflict)
+                throw new GitWorkspaceError('Resolve conflicts before committing selected files', 'conflict');
+            if (state.staged || state.unstaged || state.untracked) {
+                selected.push(state);
+                for (const spec of [requestedSpecs[i] ?? '', state.old_path ? GitRunner.repoRel(ctx, state.old_path) : ''])
+                    if (spec && !specs.includes(spec))
+                        specs.push(spec);
+            }
+        });
+        if (selected.length !== workspacePaths.length)
+            throw new GitWorkspaceError('Selected paths have no committable changes');
+        return [specs, workspacePaths, selected];
+    }
+    selectedDiffText(ctx, specs) {
+        const [env, dir] = this.selectedTempIndexEnv(ctx, specs);
+        try {
+            return GitRunner.capDiff(this.run(ctx, ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--unified=3', '--', ...specs], { check: true, env, destructive: true, disableFilterAttributes: true }).stdout);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    static fileLines(files, label) {
+        const lines = files.slice(0, 80).map((item) => `- ${item.status || 'M'} ${item.path} (${item.binary ? 'binary' : `+${item.additions || 0} -${item.deletions || 0}`})`);
+        if (files.length > 80)
+            lines.push(`- ... ${files.length - 80} more ${label} file(s)`);
+        return lines;
+    }
+    selectedCommitMessagePrompt(workspace, paths) {
+        const ctx = this.requireContext(workspace);
+        const [specs, , selected] = this.selectedFiles(ctx, paths);
+        const [diff, truncated] = this.selectedDiffText(ctx, specs);
+        if (!diff.trim())
+            throw new GitWorkspaceError('No selected diff is available');
+        const status = this.status(workspace);
+        const userPrompt = `Write a commit message for the selected Git diff below.\n\nBranch: ${status.branch || 'HEAD'}\nSelected files (${selected.length}):\n${GitRunner.fileLines(selected, 'selected').join('\n')}${truncated ? '\n\nDiff was truncated for size; summarize only what is visible.\n' : '\n'}\nSelected diff:\n\`\`\`diff\n${diff}\n\`\`\``;
+        return { system_prompt: COMMIT_MESSAGE_SYSTEM_PROMPT, user_prompt: userPrompt, truncated, status };
+    }
+    stagedCommitMessagePrompt(workspace) {
+        const ctx = this.resolveContext(workspace);
+        if (!ctx)
+            throw new GitWorkspaceError('Workspace is not a Git repository');
+        const status = this.status(workspace);
+        if ((status.totals?.staged ?? 0) <= 0)
+            throw new GitWorkspaceError('Stage changes before generating a commit message');
+        const [diff, truncated] = this.stagedDiffText(ctx);
+        if (!diff.trim())
+            throw new GitWorkspaceError('No staged diff is available');
+        const stagedFiles = (status.files ?? []).filter((f) => f.staged);
+        const userPrompt = `Write a commit message for the staged Git diff below.\n\nBranch: ${status.branch || 'HEAD'}\nStaged files (${stagedFiles.length}):\n${GitRunner.fileLines(stagedFiles, 'staged').join('\n')}${truncated ? '\n\nDiff was truncated for size; summarize only what is visible.\n' : '\n'}\nStaged diff:\n\`\`\`diff\n${diff}\n\`\`\``;
+        return { system_prompt: COMMIT_MESSAGE_SYSTEM_PROMPT, user_prompt: userPrompt, truncated, status };
+    }
+    // ── commit / remote ──────────────────────────────────────────────────────
+    async commit(workspace, message) {
+        const msg = str(message).trim();
+        if (!msg)
+            throw new GitWorkspaceError('Commit message is required');
+        const ctx = this.requireContext(workspace);
+        await this.withMutationLock(ctx, () => {
+            this.run(ctx, ['commit', '-m', msg], { timeoutMs: 10_000, check: true, destructive: true, disableFilterAttributes: true });
+        });
+        const sha = this.run(ctx, ['rev-parse', '--short', 'HEAD'], { check: true }).stdout.trim();
+        return { ok: true, commit: sha, status: this.status(workspace) };
+    }
+    async commitSelected(workspace, message, paths) {
+        const msg = str(message).trim();
+        if (!msg)
+            throw new GitWorkspaceError('Commit message is required');
+        const ctx = this.requireContext(workspace);
+        const workspacePaths = await this.withMutationLock(ctx, () => {
+            const [specs, wsPaths] = this.selectedFiles(ctx, paths);
+            const [env, dir] = this.selectedTempIndexEnv(ctx, specs);
+            try {
+                const quiet = this.run(ctx, ['diff', '--cached', '--quiet', '--no-textconv', '--', ...specs], { env, destructive: true, disableFilterAttributes: true });
+                if (quiet.status === 0)
+                    throw new GitWorkspaceError('Selected paths have no committable changes');
+                this.run(ctx, ['commit', '-m', msg], { timeoutMs: 10_000, check: true, env, destructive: true, disableFilterAttributes: true });
+                this.run(ctx, ['reset', '-q', 'HEAD', '--', ...specs], { check: true, destructive: true });
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            return wsPaths;
+        });
+        const sha = this.run(ctx, ['rev-parse', '--short', 'HEAD'], { check: true }).stdout.trim();
+        return { ok: true, commit: sha, paths: workspacePaths, status: this.status(workspace) };
+    }
+    branchName(ctx) {
+        const branch = this.run(ctx, ['branch', '--show-current'], { check: true }).stdout.trim();
+        if (!branch)
+            throw new GitWorkspaceError('Cannot push from a detached HEAD');
+        return branch;
+    }
+    async fetch(workspace) {
+        const ctx = this.requireContext(workspace);
+        const result = await this.withMutationLock(ctx, () => this.run(ctx, ['fetch', '--prune', '--no-recurse-submodules'], {
+            timeoutMs: GIT_REMOTE_TIMEOUT_MS, check: true, forceDestructiveHardening: true, disableFilterAttributes: this.destructiveEnabled(), neutralizeFilterPrograms: true, neutralizeRemoteHelpers: true,
+        }));
+        return { ok: true, message: GitRunner.remoteMessage(result), status: this.status(workspace) };
+    }
+    async pull(workspace) {
+        const ctx = this.requireContext(workspace);
+        const result = await this.withMutationLock(ctx, () => {
+            this.blockFilteredDestructiveWrite(ctx, 'Repository uses local Git filters; pull may corrupt working-tree content. Use the terminal to pull manually.');
+            return this.run(ctx, ['pull', '--ff-only', '--no-recurse-submodules'], { timeoutMs: GIT_REMOTE_TIMEOUT_MS, check: true, destructive: true, disableFilterAttributes: true, neutralizeFilterPrograms: true, neutralizeRemoteHelpers: true });
+        });
+        return { ok: true, message: GitRunner.remoteMessage(result), status: this.status(workspace) };
+    }
+    async push(workspace) {
+        const ctx = this.requireContext(workspace);
+        const result = await this.withMutationLock(ctx, () => {
+            const status = this.status(workspace);
+            const args = ['push'];
+            if (!status.upstream) {
+                const branch = this.branchName(ctx);
+                const remotes = this.run(ctx, ['remote'], { check: true }).stdout.split(/\s+/).filter(Boolean);
+                if (!remotes.includes('origin'))
+                    throw new GitWorkspaceError('No upstream branch or origin remote is configured', 'no_upstream');
+                args.push('-u', 'origin', branch);
+            }
+            return this.run(ctx, args, { timeoutMs: GIT_REMOTE_TIMEOUT_MS, check: true, destructive: true, disableFilterAttributes: true, neutralizeFilterPrograms: true, neutralizeRemoteHelpers: true });
+        });
+        return { ok: true, message: GitRunner.remoteMessage(result), status: this.status(workspace) };
+    }
+}
+export const COMMIT_MESSAGE_SYSTEM_PROMPT = `When writing commit messages, PR titles, or PR descriptions:
+
+- Inspect the staged diff before suggesting a commit message.
+- Do not use vague subjects like "update", "improve", "refine", "misc changes", "fix stuff", or "various changes".
+- For large commits, write a concise subject plus a short body with 2-5 bullets summarizing the main areas changed.
+- The subject should describe the actual user-facing result or bug fixed, not just broad implementation activity.
+- Keep wording short, clear, and natural.
+- Never mention AI, Cursor, Zed, agents, or similar tooling in commits, branch names, PR titles, or PR descriptions.
+- Never add your own thoughts or questions into the commit message, the commit message is definitive in nature.
+
+Return only the commit message text. Do not wrap it in Markdown fences.`;
+export function cleanGeneratedCommitMessage(message) {
+    let text = str(message).trim();
+    if (text.startsWith('```')) {
+        let lines = text.split('\n');
+        if (lines[0]?.startsWith('```'))
+            lines = lines.slice(1);
+        if (lines.length && lines[lines.length - 1]?.trim() === '```')
+            lines = lines.slice(0, -1);
+        text = lines.join('\n').trim();
+    }
+    if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))
+        text = text.slice(1, -1).trim();
+    return text;
+}
+/** Ensure a git repository exists at `dir` (tests and the worktree helper). */
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+//# sourceMappingURL=git.js.map