@myagentroam/node 0.11.35 → 0.11.37

package/dist/workspace/git.js

@@ -0,0 +1,991 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { logNodeCommandFailure } from '../operational.js';
+import { terminateProcessTree } from '../process-tree.js';
+import { gitOperationEnvironment } from '../service/git-operation-service.js';
+import { isWithinAllowedRoot, normalizeWorkspacePath, resolveRegisteredWorkspaceRoot, resolveWorkspaceEntry } from './path-access.js';
+import { isUtf8ContinuationByte, isValidUtf8 } from './utf8.js';
+const GIT_TIMEOUT_MS = 5_000;
+const GIT_STATUS_TIMEOUT_MS = 30_000;
+const GIT_HISTORY_TIMEOUT_MS = 15_000;
+const GIT_OUTPUT_LIMIT = 512 * 1024;
+const GIT_LARGE_OUTPUT_LIMIT = 8 * 1024 * 1024;
+const GIT_WORKTREE_LIST_LIMIT = 128;
+const REF_PATTERN = /^(?!-)(?!.*\.\.)(?!.*@\{)[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/;
+export async function inspectWorkspace(requestedPath, allowedRoots, includeParentRepository = true) {
+    const resolvedPath = await realpath(requestedPath);
+    const resolvedRoots = await Promise.all(allowedRoots.map((root) => realpath(root)));
+    const directory = await stat(resolvedPath);
+    if (!directory.isDirectory() || !isWithinAllowedRoot(resolvedPath, resolvedRoots)) {
+        throw new Error('WORKSPACE_NOT_ALLOWED');
+    }
+    try {
+        const repositoryRoot = await resolveWorkspaceGitRoot(resolvedPath, includeParentRepository);
+        const summary = { ...(await readGitSummary(repositoryRoot)), repositoryRoot };
+        return { path: resolvedPath, kind: 'GIT_WORKSPACE', gitSummary: summary };
+    }
+    catch (error) {
+        if ((error instanceof GitCommandError && error.code === 128) ||
+            isGitUnavailable(error) ||
+            (error instanceof Error && error.message === 'WORKSPACE_NOT_GIT')) {
+            return { path: resolvedPath, kind: 'DIRECTORY' };
+        }
+        throw error;
+    }
+}
+/** Resolves the working tree without changing the registered Workspace identity. */
+export async function resolveWorkspaceGitRoot(workspacePath, includeParentRepository = true) {
+    const workspace = await resolveRegisteredWorkspaceRoot(workspacePath);
+    if (!includeParentRepository) {
+        const marker = await lstat(resolve(workspace, '.git')).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (marker === undefined ||
+            marker.isSymbolicLink() ||
+            (!marker.isFile() && !marker.isDirectory()))
+            throw new Error('WORKSPACE_NOT_GIT');
+    }
+    const result = await runReadOnlyGit(workspace, ['rev-parse', '--show-toplevel']);
+    const root = await realpath(result.text.replace(/\n$/u, ''));
+    if (!includeParentRepository &&
+        normalizeWorkspacePath(root) !== normalizeWorkspacePath(workspace))
+        throw new Error('WORKSPACE_NOT_GIT');
+    return root;
+}
+export async function readGitSummary(workspacePath) {
+    const commonDir = (await runReadOnlyGit(workspacePath, ['rev-parse', '--git-common-dir'])).text.trim();
+    const headResult = await runReadOnlyGitAllowFailure(workspacePath, [
+        'rev-parse',
+        '--verify',
+        'HEAD'
+    ]);
+    const branchResult = await runReadOnlyGitAllowFailure(workspacePath, [
+        'symbolic-ref',
+        '--quiet',
+        '--short',
+        'HEAD'
+    ]);
+    const statusOptions = {
+        timeoutMs: GIT_STATUS_TIMEOUT_MS,
+        outputLimit: GIT_LARGE_OUTPUT_LIMIT
+    };
+    const status = await runReadOnlyGit(workspacePath, ['status', '--porcelain=v1'], statusOptions);
+    return {
+        commonDir,
+        head: headResult.code === 0 ? headResult.text.trim() : '',
+        branch: branchResult.code === 0 ? branchResult.text.trim() : null,
+        dirty: status.output.length > 0,
+        snapshot: summarizeText(status.text)
+    };
+}
+export function assertSafeGitRef(ref) {
+    if (!REF_PATTERN.test(ref)) {
+        throw new Error('GIT_REF_INVALID');
+    }
+}
+export async function readRestrictedDiff(workspacePath, fromRef, toRef) {
+    assertSafeGitRef(fromRef);
+    assertSafeGitRef(toRef);
+    const result = await runReadOnlyGit(workspacePath, [
+        'diff',
+        '--no-ext-diff',
+        '--no-textconv',
+        fromRef,
+        toRef
+    ]);
+    const binary = isBinaryGitPatch(result.text);
+    if (binary) {
+        return {
+            binary: true,
+            summary: `binary diff sha256=${createHash('sha256').update(result.output).digest('hex')} bytes=${result.output.length}`,
+            truncated: result.truncated
+        };
+    }
+    return { binary: false, text: result.text, truncated: result.truncated };
+}
+function currentBranchFromStatusHeader(header) {
+    const value = header.slice(3);
+    if (value.startsWith('HEAD '))
+        return null;
+    const unborn = /^(?:No commits yet on|Initial commit on) (.+)$/.exec(value);
+    if (unborn !== null)
+        return unborn[1] ?? null;
+    return value.split('...')[0]?.split(' ')[0] ?? null;
+}
+function trackingFromStatusHeader(header) {
+    const match = /^## [^ ]+\.\.\.([^ ]+)(?: \[(ahead \d+)?(?:, )?(behind \d+)?\])?$/.exec(header);
+    if (match?.[1] === undefined)
+        return undefined;
+    return {
+        upstream: match[1],
+        ahead: Number(match[2]?.slice(6) ?? 0),
+        behind: Number(match[3]?.slice(7) ?? 0)
+    };
+}
+export async function listGitWorktrees(workspacePath) {
+    const options = {
+        timeoutMs: GIT_STATUS_TIMEOUT_MS,
+        outputLimit: GIT_LARGE_OUTPUT_LIMIT
+    };
+    const nulDelimited = await runReadOnlyGitAllowFailure(workspacePath, ['worktree', 'list', '--porcelain', '-z'], options);
+    if (nulDelimited.code === 0)
+        return parseGitWorktreeList(workspacePath, nulDelimited, true);
+    if (!canRetryGitWorktreeListWithoutNullOutput(nulDelimited))
+        throw gitCommandFailure(nulDelimited.code, nulDelimited.stderr, 'worktree');
+    const lineDelimited = await runReadOnlyGit(workspacePath, ['worktree', 'list', '--porcelain'], options);
+    return parseGitWorktreeList(workspacePath, lineDelimited, false);
+}
+async function parseGitWorktreeList(workspacePath, result, nulDelimited) {
+    const currentPath = normalizeWorkspacePath(await realpath(workspacePath));
+    const entries = [];
+    let truncated = result.truncated;
+    const groups = nulDelimited ? result.text.split('\0\0') : result.text.split(/\r?\n\r?\n/);
+    for (const group of groups) {
+        if (group.length === 0)
+            continue;
+        if (entries.length >= GIT_WORKTREE_LIST_LIMIT) {
+            truncated = true;
+            break;
+        }
+        const fields = (nulDelimited ? group.split('\0') : group.split(/\r?\n/)).filter((field) => field.length > 0);
+        if (!nulDelimited &&
+            fields.some((field) => !(field.startsWith('worktree ') ||
+                field.startsWith('HEAD ') ||
+                field.startsWith('branch ') ||
+                field === 'bare' ||
+                field === 'detached' ||
+                field === 'locked' ||
+                field.startsWith('locked ') ||
+                field === 'prunable' ||
+                field.startsWith('prunable ')))) {
+            throw new Error('GIT_WORKTREE_LIST_INVALID');
+        }
+        if (fields.some((field) => field === 'bare'))
+            continue;
+        const pathField = fields.find((field) => field.startsWith('worktree '));
+        const headField = fields.find((field) => field.startsWith('HEAD '));
+        const path = pathField?.slice('worktree '.length);
+        const head = headField?.slice('HEAD '.length);
+        if (path === undefined ||
+            path.length === 0 ||
+            head === undefined ||
+            !/^[0-9a-f]{40,64}$/u.test(head)) {
+            if (result.truncated) {
+                truncated = true;
+                continue;
+            }
+            throw new Error('GIT_WORKTREE_LIST_INVALID');
+        }
+        const branchField = fields.find((field) => field.startsWith('branch '));
+        const branchRef = branchField?.slice('branch '.length);
+        const branch = branchRef === undefined
+            ? null
+            : branchRef.startsWith('refs/heads/')
+                ? branchRef.slice('refs/heads/'.length)
+                : branchRef;
+        const directoryName = (basename(path).trim() || branch || head.slice(0, 12)).slice(0, 512);
+        entries.push({
+            path,
+            directoryName,
+            branch,
+            head,
+            current: normalizeWorkspacePath(path) === currentPath,
+            locked: fields.some((field) => field === 'locked' || field.startsWith('locked ')),
+            prunable: fields.some((field) => field === 'prunable' || field.startsWith('prunable '))
+        });
+    }
+    return { entries, truncated };
+}
+export async function readCurrentChangesSummary(workspacePath, isolateSubmoduleFailures = false) {
+    const args = [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--branch',
+        '--ahead-behind',
+        '--untracked-files=all'
+    ];
+    const options = { timeoutMs: GIT_STATUS_TIMEOUT_MS, outputLimit: GIT_LARGE_OUTPUT_LIMIT };
+    const result = await runReadOnlyGit(workspacePath, args, options).catch((error) => {
+        if (!isolateSubmoduleFailures || !(error instanceof GitCommandError))
+            throw error;
+        // Validate root facts independently when descending into a damaged child fails.
+        // A second failure remains a repository failure, never an empty success.
+        return runReadOnlyGit(workspacePath, [...args, '--ignore-submodules=dirty'], options);
+    });
+    const records = result.text.split('\0');
+    if (result.truncated)
+        records.pop();
+    const header = records.shift() ?? '';
+    const output = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (record.length < 4)
+            continue;
+        const indexState = record[0];
+        const worktreeState = record[1];
+        const path = record.slice(3);
+        if (indexState === '?' && worktreeState === '?') {
+            output.push({ path, state: 'UNTRACKED', change: 'ADDED' });
+            continue;
+        }
+        if (indexState !== ' ') {
+            output.push({ path, state: 'STAGED', change: gitChange(indexState) });
+        }
+        if (worktreeState !== ' ') {
+            output.push({ path, state: 'UNSTAGED', change: gitChange(worktreeState) });
+        }
+        // Porcelain v1 -z emits a second NUL-delimited source path for rename
+        // and copy records. It is metadata for the same entry, never another
+        // status record.
+        if (indexState === 'R' || indexState === 'C' || worktreeState === 'R' || worktreeState === 'C')
+            index += 1;
+    }
+    const tracking = trackingFromStatusHeader(header);
+    const branch = header.startsWith('## ') ? currentBranchFromStatusHeader(header) : null;
+    const head = branch === null
+        ? (await runReadOnlyGit(workspacePath, ['rev-parse', '--verify', 'HEAD'])).text.trim()
+        : undefined;
+    return {
+        branch,
+        ...(head === undefined ? {} : { head }),
+        ...(tracking === undefined ? {} : { tracking }),
+        ...(result.truncated ? { changesTruncated: true } : {}),
+        changes: output
+    };
+}
+export async function listGitSubmodules(workspacePath) {
+    const result = await runReadOnlyGit(workspacePath, ['ls-files', '--stage', '-z'], {
+        timeoutMs: GIT_STATUS_TIMEOUT_MS,
+        outputLimit: GIT_LARGE_OUTPUT_LIMIT
+    });
+    if (result.truncated)
+        throw new Error('GIT_SUBMODULE_DISCOVERY_TRUNCATED');
+    const paths = [
+        ...new Set(result.text.split('\0').flatMap((record) => {
+            const match = /^160000 [0-9a-f]+ [0-3]\t([\s\S]+)$/.exec(record);
+            return match?.[1] === undefined ? [] : [match[1]];
+        }))
+    ].sort((left, right) => left.localeCompare(right));
+    if (paths.length === 0)
+        return [];
+    const unavailable = (mapping, gitExitCode) => paths.map((path) => ({ path, mapping, ...(gitExitCode === undefined ? {} : { gitExitCode }) }));
+    try {
+        const modulesFile = await lstat(resolve(workspacePath, '.gitmodules'));
+        if (!modulesFile.isFile() || modulesFile.isSymbolicLink())
+            return unavailable('INVALID');
+    }
+    catch (error) {
+        return unavailable(error.code === 'ENOENT' ? 'MISSING' : 'INVALID');
+    }
+    const mappings = await runReadOnlyGitAllowFailure(workspacePath, ['config', '--null', '--file', '.gitmodules', '--get-regexp', '^submodule\\..*\\.(path|url)$'], { outputLimit: GIT_LARGE_OUTPUT_LIMIT });
+    if (mappings.truncated || (mappings.code !== 0 && mappings.code !== 1))
+        return unavailable('INVALID', mappings.code);
+    const byName = new Map();
+    for (const entry of mappings.text.split('\0')) {
+        const separator = entry.indexOf('\n');
+        if (separator < 0)
+            continue;
+        const key = entry.slice(0, separator);
+        const value = entry.slice(separator + 1);
+        const match = /^submodule\.(.*)\.(path|url)$/.exec(key);
+        if (match?.[1] === undefined)
+            continue;
+        const mapping = byName.get(match[1]) ?? {};
+        if (match[2] === 'path')
+            mapping.path = value;
+        else
+            mapping.hasUrl = value.trim().length > 0;
+        byName.set(match[1], mapping);
+    }
+    const mappedPaths = new Set([...byName.values()].flatMap((mapping) => mapping.path !== undefined && mapping.hasUrl ? [mapping.path] : []));
+    return paths.map((path) => ({ path, mapping: mappedPaths.has(path) ? 'MAPPED' : 'MISSING' }));
+}
+export async function resolveGitRepository(workspacePath, repositoryPath, initializedSubmodulePaths) {
+    const root = await realpath(workspacePath);
+    if (repositoryPath.length === 0)
+        return root;
+    if (repositoryPath.includes('\0') ||
+        repositoryPath.startsWith('/') ||
+        repositoryPath.startsWith('\\') ||
+        repositoryPath
+            .split('/')
+            .some((segment) => segment.length === 0 || segment === '.' || segment === '..'))
+        throw new Error('GIT_REPOSITORY_INVALID');
+    try {
+        const requestedRepository = resolve(root, repositoryPath);
+        const repository = await realpath(requestedRepository);
+        if (normalizeWorkspacePath(requestedRepository) !== normalizeWorkspacePath(repository) ||
+            !isWithinAllowedRoot(repository, [root]))
+            throw new Error('invalid');
+        if (initializedSubmodulePaths !== undefined) {
+            if (!initializedSubmodulePaths.includes(repositoryPath))
+                throw new Error('invalid');
+            return repository;
+        }
+        await assertGitSuperprojectChain(root, repository);
+        return repository;
+    }
+    catch {
+        throw new Error('GIT_REPOSITORY_INVALID');
+    }
+}
+export async function resolveGitRepositoryTarget(workspacePath, repositoryPath, worktreePath, initializedSubmodulePaths) {
+    if (worktreePath === undefined)
+        return resolveGitRepository(workspacePath, repositoryPath, initializedSubmodulePaths);
+    if (repositoryPath.length !== 0 ||
+        worktreePath.length === 0 ||
+        worktreePath.length > 4096 ||
+        worktreePath.includes('\0'))
+        throw new Error('GIT_REPOSITORY_INVALID');
+    const requestedKey = normalizeWorkspacePath(worktreePath);
+    const worktrees = await listGitWorktrees(workspacePath);
+    const matched = worktrees.entries.find((entry) => normalizeWorkspacePath(entry.path) === requestedKey);
+    if (matched === undefined || matched.prunable)
+        throw new Error('GIT_REPOSITORY_INVALID');
+    try {
+        return await realpath(matched.path);
+    }
+    catch {
+        throw new Error('GIT_REPOSITORY_INVALID');
+    }
+}
+async function assertGitSuperprojectChain(root, repository) {
+    const rootKey = normalizeWorkspacePath(root);
+    let current = repository;
+    const visited = new Set();
+    for (let depth = 0; depth < 64; depth += 1) {
+        const currentKey = normalizeWorkspacePath(current);
+        if (currentKey === rootKey)
+            return;
+        if (visited.has(currentKey))
+            throw new Error('invalid');
+        visited.add(currentKey);
+        const result = await runReadOnlyGit(current, [
+            'rev-parse',
+            '--show-toplevel',
+            '--show-superproject-working-tree'
+        ]);
+        const [topLevel, superproject] = result.text.split(/\r?\n/);
+        if (topLevel === undefined || superproject === undefined || superproject.length === 0)
+            throw new Error('invalid');
+        const resolvedTopLevel = await realpath(topLevel);
+        const resolvedSuperproject = await realpath(superproject);
+        if (normalizeWorkspacePath(resolvedTopLevel) !== currentKey ||
+            normalizeWorkspacePath(resolvedSuperproject) === currentKey ||
+            !isWithinAllowedRoot(resolvedSuperproject, [root]) ||
+            !isWithinAllowedRoot(current, [resolvedSuperproject]))
+            throw new Error('invalid');
+        current = resolvedSuperproject;
+    }
+    throw new Error('invalid');
+}
+export async function listGitHistoryRefs(repository) {
+    const result = await runReadOnlyGit(repository, [
+        'for-each-ref',
+        '--format=%(refname)%09%(refname:short)%09%(objectname)%09%(HEAD)%09%(symref)',
+        'refs/heads',
+        'refs/remotes'
+    ], {
+        timeoutMs: GIT_HISTORY_TIMEOUT_MS,
+        outputLimit: GIT_LARGE_OUTPUT_LIMIT
+    });
+    return result.text
+        .split(/\r?\n/)
+        .flatMap((line) => {
+        const [name, displayName, hash, head, symref] = line.split('\t');
+        if (name === undefined ||
+            displayName === undefined ||
+            hash === undefined ||
+            symref === undefined ||
+            symref.length > 0 ||
+            !/^[0-9a-f]{40,64}$/.test(hash))
+            return [];
+        const kind = name.startsWith('refs/heads/')
+            ? 'LOCAL'
+            : name.startsWith('refs/remotes/')
+                ? 'REMOTE'
+                : undefined;
+        return kind === undefined ? [] : [{ name, displayName, kind, hash, current: head === '*' }];
+    })
+        .sort((left, right) => left.kind.localeCompare(right.kind) || left.displayName.localeCompare(right.displayName));
+}
+function selectedHistoryRefs(available, requested) {
+    if (requested === undefined || requested.length === 0)
+        return available;
+    const unique = [...new Set(requested)];
+    const selected = unique.map((name) => available.find((entry) => entry.name === name));
+    if (selected.some((entry) => entry === undefined))
+        throw new Error('GIT_HISTORY_REF_INVALID');
+    return selected;
+}
+function historyCursor(offset, fingerprint) {
+    return Buffer.from(JSON.stringify({ offset, fingerprint })).toString('base64url');
+}
+function parseHistoryCursor(value, fingerprint) {
+    if (value === undefined)
+        return 0;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        if (!Number.isInteger(parsed.offset) ||
+            parsed.offset < 0 ||
+            parsed.fingerprint !== fingerprint)
+            throw new Error('invalid');
+        return parsed.offset;
+    }
+    catch {
+        throw new Error('GIT_HISTORY_CURSOR_INVALID');
+    }
+}
+export async function readGitHistory(repository, input) {
+    const available = await listGitHistoryRefs(repository);
+    const selected = selectedHistoryRefs(available, input.refs);
+    if (selected.length === 0)
+        return { commits: [], nextCursor: null };
+    const limit = input.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error('GIT_HISTORY_LIMIT_INVALID');
+    const names = selected.map((entry) => entry.name).sort();
+    const allBranchesSelected = input.refs === undefined ||
+        input.refs.length === 0 ||
+        (selected.length === available.length &&
+            selected.every((entry) => available.some((candidate) => candidate.name === entry.name)));
+    const revisionArguments = allBranchesSelected ? ['--branches', '--remotes'] : names;
+    // Bind the offset cursor to the exact branch tips. Advancing a branch invalidates
+    // the cursor instead of silently skipping or duplicating commits between pages.
+    const fingerprint = createHash('sha256')
+        .update(selected
+        .map((entry) => `${entry.name}\0${entry.hash}`)
+        .sort()
+        .join('\0'))
+        .digest('hex');
+    const offset = parseHistoryCursor(input.cursor, fingerprint);
+    const result = await runReadOnlyGit(repository, [
+        'log',
+        '--topo-order',
+        '--date-order',
+        `--skip=${offset}`,
+        `--max-count=${limit + 1}`,
+        '-z',
+        '--format=%H%x00%P%x00%an%x00%ae%x00%ct%x00%s',
+        ...revisionArguments,
+        '--'
+    ], { timeoutMs: GIT_HISTORY_TIMEOUT_MS });
+    const refsByHash = new Map();
+    for (const entry of available) {
+        const refs = refsByHash.get(entry.hash) ?? [];
+        refs.push(entry.displayName);
+        refsByHash.set(entry.hash, refs);
+    }
+    const fields = result.text.split('\0');
+    const commits = [];
+    for (let index = 0; index + 5 < fields.length; index += 6) {
+        const [hash, parents = '', authorName = '', authorEmail = '', committedAt = '0', subject = ''] = fields.slice(index, index + 6);
+        if (hash === undefined || !/^[0-9a-f]{40,64}$/.test(hash))
+            continue;
+        commits.push({
+            hash,
+            parents: parents.length === 0 ? [] : parents.split(' '),
+            authorName,
+            authorEmail,
+            committedAt: Number(committedAt) * 1000,
+            subject,
+            refs: refsByHash.get(hash) ?? []
+        });
+    }
+    const hasMore = commits.length > limit;
+    return {
+        commits: commits.slice(0, limit),
+        nextCursor: hasMore ? historyCursor(offset + limit, fingerprint) : null
+    };
+}
+async function assertHistoryCommitReachable(repository, commit, refs) {
+    if (!/^[0-9a-f]{40,64}$/.test(commit))
+        throw new Error('GIT_HISTORY_COMMIT_INVALID');
+    const selected = selectedHistoryRefs(await listGitHistoryRefs(repository), refs);
+    for (const ref of selected) {
+        const result = await runReadOnlyGitAllowFailure(repository, [
+            'merge-base',
+            '--is-ancestor',
+            commit,
+            ref.name
+        ]);
+        if (result.code === 0)
+            return;
+    }
+    throw new Error('GIT_HISTORY_COMMIT_INVALID');
+}
+export async function readGitHistoryFiles(repository, commit, refs) {
+    await assertHistoryCommitReachable(repository, commit, refs);
+    const result = await runReadOnlyGit(repository, [
+        'diff-tree',
+        '--root',
+        '--first-parent',
+        '--no-commit-id',
+        '-r',
+        '-z',
+        '-M',
+        '-C',
+        '--name-status',
+        commit
+    ], {
+        timeoutMs: GIT_STATUS_TIMEOUT_MS,
+        outputLimit: GIT_LARGE_OUTPUT_LIMIT
+    });
+    const records = result.text.split('\0');
+    const files = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const status = records[index];
+        if (status === undefined || status.length === 0)
+            continue;
+        const code = status[0] ?? 'M';
+        if (code === 'R' || code === 'C') {
+            const previousPath = records[index + 1];
+            const path = records[index + 2];
+            if (previousPath !== undefined && path !== undefined)
+                files.push({ path, previousPath, change: gitChange(code) });
+            index += 2;
+        }
+        else {
+            const path = records[index + 1];
+            if (path !== undefined)
+                files.push({ path, change: gitChange(code) });
+            index += 1;
+        }
+    }
+    return files;
+}
+export async function readGitHistoryFileDiff(repository, commit, requestedPath, refs, requestedPreviousPath) {
+    await assertHistoryCommitReachable(repository, commit, refs);
+    const path = safeGitWorkspacePath(requestedPath);
+    const previousPath = requestedPreviousPath === undefined ? undefined : safeGitWorkspacePath(requestedPreviousPath);
+    const result = await runReadOnlyGit(repository, [
+        'show',
+        '--format=',
+        '--first-parent',
+        '--no-ext-diff',
+        '--no-textconv',
+        commit,
+        '--',
+        `:(literal)${path}`,
+        ...(previousPath === undefined || previousPath === path ? [] : [`:(literal)${previousPath}`])
+    ]);
+    const binary = isBinaryGitPatch(result.text);
+    if (binary) {
+        return {
+            binary: true,
+            summary: `binary diff sha256=${createHash('sha256').update(result.output).digest('hex')} bytes=${result.output.length}`,
+            truncated: result.truncated
+        };
+    }
+    return { binary: false, text: result.text, truncated: result.truncated };
+}
+export async function readGitHistoryFileContentRange(repository, commit, requestedPath, offset, limit, refs) {
+    if (!Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 20 * 1024 * 1024 ||
+        offset + limit > 20 * 1024 * 1024)
+        throw new Error('FILE_RANGE_INVALID');
+    await assertHistoryCommitReachable(repository, commit, refs);
+    const path = safeGitWorkspacePath(requestedPath);
+    const object = `${commit}:${path}`;
+    const sizeResult = await runReadOnlyGit(repository, ['cat-file', '-s', object]);
+    const size = Number(sizeResult.text.trim());
+    if (!Number.isSafeInteger(size) || size < 0 || offset > size)
+        throw new Error('FILE_RANGE_INVALID');
+    if (offset === size)
+        return { path, size, offset, contentBase64: '', nextOffset: null };
+    const result = await runReadOnlyGitAllowFailure(repository, ['cat-file', 'blob', object], {
+        outputLimit: offset + limit,
+        timeoutMs: GIT_HISTORY_TIMEOUT_MS
+    });
+    if (result.code !== 0)
+        throw gitCommandFailure(result.code, result.stderr, 'cat-file');
+    const content = result.output.subarray(offset, Math.min(size, offset + limit));
+    const nextOffset = offset + content.length;
+    return {
+        path,
+        size,
+        offset,
+        contentBase64: content.toString('base64'),
+        nextOffset: nextOffset < size ? nextOffset : null
+    };
+}
+export async function openGitHistoryFileContent(repository, commit, requestedPath, refs) {
+    await assertHistoryCommitReachable(repository, commit, refs);
+    const path = safeGitWorkspacePath(requestedPath);
+    const object = `${commit}:${path}`;
+    const sizeResult = await runReadOnlyGit(repository, ['cat-file', '-s', object]);
+    const size = Number(sizeResult.text.trim());
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error('FILE_RANGE_INVALID');
+    return {
+        path,
+        size,
+        chunks: (async function* () {
+            const child = spawn('git', ['cat-file', 'blob', object], {
+                cwd: repository,
+                shell: false,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: {
+                    ...process.env,
+                    ...gitOperationEnvironment.getStore(),
+                    GIT_OPTIONAL_LOCKS: '0'
+                }
+            });
+            const errors = [];
+            let errorSize = 0;
+            let closed = false;
+            const exit = new Promise((resolveExit) => {
+                child.stderr.on('data', (chunk) => {
+                    const remaining = Math.max(0, 4096 - errorSize);
+                    if (remaining === 0)
+                        return;
+                    const retained = chunk.subarray(0, remaining);
+                    errors.push(retained);
+                    errorSize += retained.length;
+                });
+                child.once('error', (error) => {
+                    closed = true;
+                    resolveExit({ code: 1, stderr: error.message });
+                });
+                child.once('close', (code) => {
+                    closed = true;
+                    resolveExit({
+                        code: code ?? 1,
+                        stderr: Buffer.concat(errors).toString('utf8')
+                    });
+                });
+            });
+            try {
+                for await (const chunk of child.stdout)
+                    yield new Uint8Array(chunk);
+                const result = await exit;
+                if (result.code !== 0)
+                    throw gitCommandFailure(result.code, result.stderr, 'cat-file');
+            }
+            finally {
+                if (!closed)
+                    child.kill('SIGKILL');
+            }
+        })()
+    };
+}
+export async function readCurrentChanges(workspacePath) {
+    return (await readCurrentChangesSummary(workspacePath)).changes;
+}
+export async function readCurrentChangeDiff(workspacePath, requestedPath) {
+    const path = safeGitWorkspacePath(requestedPath);
+    await assertCurrentChangePathAccessible(workspacePath, path);
+    const result = await readCurrentChangeGitDiff(workspacePath, path);
+    const after = await readWorkingTreeText(workspacePath, path);
+    const binary = isBinaryGitPatch(result.text);
+    if (binary) {
+        return {
+            binary: true,
+            summary: `binary diff sha256=${createHash('sha256').update(result.output).digest('hex')} bytes=${result.output.length}`,
+            truncated: result.truncated || after?.truncated === true
+        };
+    }
+    return {
+        binary: false,
+        text: result.text,
+        truncated: result.truncated || after?.truncated === true,
+        // A non-UTF-8 worktree must not override Git's text patch or supply lossy context.
+        ...(after?.binary === true ? {} : { afterText: after?.text ?? '' }),
+        ...(after === undefined || after.binary ? {} : { afterTruncated: after.truncated })
+    };
+}
+async function readCurrentChangeGitDiff(workspacePath, path) {
+    const untracked = await runReadOnlyGit(workspacePath, [
+        'ls-files',
+        '--others',
+        '--exclude-standard',
+        '-z',
+        '--',
+        `:(literal)${path}`
+    ]);
+    if (untracked.text.split('\0').includes(path)) {
+        const result = await runReadOnlyGitAllowFailure(workspacePath, [
+            'diff',
+            '--no-index',
+            '--no-ext-diff',
+            '--no-textconv',
+            '--',
+            '/dev/null',
+            path
+        ]);
+        if (result.code !== 0 && result.code !== 1)
+            throw gitCommandFailure(result.code, result.stderr, 'diff');
+        return result;
+    }
+    return runReadOnlyGit(workspacePath, [
+        'diff',
+        '--no-ext-diff',
+        '--no-textconv',
+        'HEAD',
+        '--',
+        `:(literal)${path}`
+    ]);
+}
+/** Current Changes must not expose an external link. */
+export async function isWorkspaceChangeVisible(workspacePath, requestedPath) {
+    try {
+        await assertCurrentChangePathAccessible(workspacePath, safeGitWorkspacePath(requestedPath));
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.message === 'FILE_PATH_ESCAPE' ||
+                error.message === 'FILE_NOT_FOUND' ||
+                error.message === 'FILE_NOT_REGULAR'))
+            return false;
+        throw error;
+    }
+}
+async function assertCurrentChangePathAccessible(workspacePath, path) {
+    const root = await realpath(workspacePath);
+    const candidate = resolve(root, path);
+    const metadata = await lstat(candidate).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (metadata === undefined)
+        return;
+    await resolveWorkspaceEntry(root, path, false);
+}
+function isBinaryGitPatch(text) {
+    // Git lines use LF; Unicode line separators inside hunk content are not marker boundaries.
+    return /(?:^|\n)Binary files [^\n]+ differ(?:\r?\n|$)/u.test(text);
+}
+async function readWorkingTreeText(workspacePath, path) {
+    const root = await realpath(workspacePath);
+    let file;
+    try {
+        file = await resolveWorkspaceEntry(root, path, false);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'FILE_NOT_FOUND')
+            return undefined;
+        throw error;
+    }
+    const metadata = await lstat(file);
+    if (!metadata.isFile())
+        return undefined;
+    const source = await readFile(file);
+    return diffTextFromBuffer(source, source.length > GIT_OUTPUT_LIMIT);
+}
+function diffTextFromBuffer(source, truncated) {
+    if (source.includes(0) || !isValidUtf8(source))
+        return { binary: true, truncated };
+    let end = Math.min(source.length, GIT_OUTPUT_LIMIT);
+    while (end > 0 && end < source.length && isUtf8ContinuationByte(source[end]))
+        end -= 1;
+    return { binary: false, text: source.subarray(0, end).toString('utf8'), truncated };
+}
+export async function restoreCurrentChange(workspacePath, requestedPath, state) {
+    const path = safeGitWorkspacePath(requestedPath);
+    const pathspec = `:(literal)${path}`;
+    if (state === 'UNTRACKED') {
+        const status = await runReadOnlyGit(workspacePath, [
+            'status',
+            '--porcelain=v1',
+            '-z',
+            '--untracked-files=all',
+            '--',
+            pathspec
+        ]);
+        if (!status.text
+            .split('\0')
+            .some((record) => record.startsWith('?? ') && record.slice(3) === path))
+            throw new Error('GIT_CHANGE_RESTORE_UNAVAILABLE');
+        const root = await realpath(workspacePath);
+        const file = resolve(root, path);
+        const metadata = await lstat(file);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new Error('GIT_CHANGE_RESTORE_UNAVAILABLE');
+        await unlink(file);
+        return;
+    }
+    if (state === 'UNSTAGED') {
+        await runGit(workspacePath, ['restore', '--worktree', '--', pathspec]);
+        return;
+    }
+    await runGit(workspacePath, [
+        'restore',
+        '--source=HEAD',
+        '--staged',
+        '--worktree',
+        '--',
+        pathspec
+    ]);
+}
+function safeGitWorkspacePath(requestedPath) {
+    if (requestedPath.length === 0 ||
+        requestedPath.includes('\0') ||
+        requestedPath.startsWith('/') ||
+        requestedPath.startsWith('\\'))
+        throw new Error('FILE_PATH_ESCAPE');
+    const normalized = requestedPath.replaceAll('\\', '/');
+    if (normalized
+        .split('/')
+        .some((segment) => segment === '' || segment === '..' || segment === '.git'))
+        throw new Error('FILE_PATH_ESCAPE');
+    return normalized;
+}
+function gitChange(status) {
+    if (status === 'A')
+        return 'ADDED';
+    if (status === 'D')
+        return 'DELETED';
+    if (status === 'R')
+        return 'RENAMED';
+    if (status === 'C')
+        return 'COPIED';
+    if (status === 'T')
+        return 'TYPE_CHANGED';
+    return 'MODIFIED';
+}
+export class GitCommandError extends Error {
+    code;
+    stderr;
+    publicDetails;
+    publicParameters;
+    constructor(code, stderr) {
+        super('GIT_COMMAND_FAILED');
+        this.code = code;
+        this.stderr = stderr;
+        this.publicParameters = { gitExitCode: code };
+        this.publicDetails = stderr.trim().slice(0, 1_000) || `Git exited with status ${code}.`;
+    }
+}
+function gitCommandFailure(code, stderr, subcommand, durationMs, reason) {
+    logNodeCommandFailure(`git ${subcommand}`, {
+        exitCode: code,
+        stderr,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(reason === undefined ? {} : { reason })
+    });
+    return new GitCommandError(code, stderr);
+}
+async function runReadOnlyGit(workspacePath, args, options = {}) {
+    return runGit(workspacePath, args, { ...options, readOnly: true });
+}
+async function runReadOnlyGitAllowFailure(workspacePath, args, options = {}) {
+    return runGitAllowFailure(workspacePath, args, { ...options, readOnly: true });
+}
+async function runGit(workspacePath, args, options = {}) {
+    const startedAt = performance.now();
+    const result = await runGitAllowFailure(workspacePath, args, options);
+    if (result.code !== 0) {
+        throw gitCommandFailure(result.code, result.stderr, args[0] ?? 'unknown', Math.round(performance.now() - startedAt));
+    }
+    return result;
+}
+async function runGitAllowFailure(workspacePath, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const startedAt = performance.now();
+        const outputLimit = options.outputLimit ?? GIT_OUTPUT_LIMIT;
+        const child = spawn('git', [...args], {
+            cwd: workspacePath,
+            shell: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                ...gitOperationEnvironment.getStore(),
+                ...(options.readOnly === true ? { GIT_OPTIONAL_LOCKS: '0' } : {})
+            }
+        });
+        const chunks = [];
+        const errors = [];
+        let size = 0;
+        let errorSize = 0;
+        let truncated = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (process.platform === 'win32') {
+                const pid = child.pid;
+                if (pid === undefined) {
+                    child.kill('SIGKILL');
+                    return;
+                }
+                void terminateProcessTree({
+                    pid,
+                    kill: (signal) => child.kill(signal)
+                }, 'win32').catch(() => {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // The process may have exited while taskkill was starting.
+                    }
+                });
+                return;
+            }
+            child.kill('SIGKILL');
+        }, options.timeoutMs ?? GIT_TIMEOUT_MS);
+        child.stdout.on('data', (chunk) => {
+            const remaining = Math.max(0, outputLimit - size);
+            if (remaining > 0) {
+                const retained = chunk.subarray(0, remaining);
+                chunks.push(retained);
+                size += retained.length;
+            }
+            truncated ||= chunk.length > remaining;
+        });
+        child.stderr.on('data', (chunk) => {
+            const remaining = Math.max(0, 4096 - errorSize);
+            if (remaining === 0)
+                return;
+            const retained = chunk.subarray(0, remaining);
+            errors.push(retained);
+            errorSize += retained.length;
+        });
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            logNodeCommandFailure(`git ${args[0] ?? 'unknown'}`, {
+                reason: error.code ?? 'START_FAILED'
+            });
+            reject(error);
+        });
+        child.once('close', (code) => {
+            clearTimeout(timer);
+            const stderr = Buffer.concat(errors).toString('utf8');
+            if (timedOut) {
+                reject(gitCommandFailure(code === null || code === 0 ? 1 : code, `Git command timed out after ${options.timeoutMs ?? GIT_TIMEOUT_MS} ms.${stderr ? `\n${stderr}` : ''}`, args[0] ?? 'unknown', Math.round(performance.now() - startedAt), 'TIMEOUT'));
+                return;
+            }
+            const output = Buffer.concat(chunks);
+            resolve({
+                code: code ?? 1,
+                output,
+                text: output.toString('utf8'),
+                stderr,
+                truncated
+            });
+        });
+    });
+}
+function canRetryGitWorktreeListWithoutNullOutput(result) {
+    return (result.code === 129 ||
+        /(?:unknown|unrecognized|invalid)\s+(?:option|switch).*['"`]?-?z\b/iu.test(result.stderr));
+}
+function isGitUnavailable(error) {
+    return (error instanceof Error && 'code' in error && error.code === 'ENOENT');
+}
+function summarizeText(value) {
+    return JSON.stringify({
+        sha256: createHash('sha256').update(value).digest('hex'),
+        bytes: Buffer.byteLength(value)
+    });
+}