@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

package/src/developer-agent/git-inspection.js

@@ -0,0 +1,815 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeveloperAgentGitInspectionError = exports.DEVELOPER_AGENT_GIT_MAX_WORKTREES = exports.DEVELOPER_AGENT_GIT_MAX_PATH_BYTES = exports.DEVELOPER_AGENT_GIT_MAX_PATHS = exports.DEVELOPER_AGENT_GIT_MAX_RESULT_BYTES = exports.DEVELOPER_AGENT_GIT_MAX_TOTAL_OUTPUT_BYTES = exports.DEVELOPER_AGENT_GIT_MAX_COMMAND_BYTES = exports.DEVELOPER_AGENT_GIT_INSPECTION_SCHEMA_VERSION = void 0;
+exports.createDeveloperAgentGitEnvironment = createDeveloperAgentGitEnvironment;
+exports.assertDeveloperAgentReadOnlyGitInvocation = assertDeveloperAgentReadOnlyGitInvocation;
+exports.inspectDeveloperAgentGit = inspectDeveloperAgentGit;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.DEVELOPER_AGENT_GIT_INSPECTION_SCHEMA_VERSION = 1;
+exports.DEVELOPER_AGENT_GIT_MAX_COMMAND_BYTES = 256 * 1024;
+exports.DEVELOPER_AGENT_GIT_MAX_TOTAL_OUTPUT_BYTES = 1024 * 1024;
+exports.DEVELOPER_AGENT_GIT_MAX_RESULT_BYTES = 256 * 1024;
+exports.DEVELOPER_AGENT_GIT_MAX_PATHS = 2_048;
+exports.DEVELOPER_AGENT_GIT_MAX_PATH_BYTES = 4_096;
+exports.DEVELOPER_AGENT_GIT_MAX_WORKTREES = 64;
+const GIT_COMMAND_TIMEOUT_MS = 10_000;
+const NO_OPTIONAL_LOCKS = '--no-optional-locks';
+const DISABLE_FS_MONITOR = ['-c', 'core.fsmonitor=false'];
+const SHA = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const SAFE_REF_CHARACTERS = /^[A-Za-z0-9][A-Za-z0-9._/@+-]{0,255}$/;
+class DeveloperAgentGitInspectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DeveloperAgentGitInspectionError';
+    }
+}
+exports.DeveloperAgentGitInspectionError = DeveloperAgentGitInspectionError;
+function fail(code, message) {
+    throw new DeveloperAgentGitInspectionError(code, message);
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint !== undefined && (codePoint <= 0x1f || codePoint === 0x7f)) {
+            return true;
+        }
+    }
+    return false;
+}
+function sameArgs(args, expected) {
+    return (args.length === expected.length &&
+        args.every((value, index) => value === expected[index]));
+}
+function createDeveloperAgentGitEnvironment(source = process.env) {
+    const environment = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (!key.toUpperCase().startsWith('GIT_') && value !== undefined) {
+            environment[key] = value;
+        }
+    }
+    environment.GIT_OPTIONAL_LOCKS = '0';
+    environment.GIT_TERMINAL_PROMPT = '0';
+    return environment;
+}
+function safeRef(value) {
+    if (!SAFE_REF_CHARACTERS.test(value) ||
+        value === '@' ||
+        value.startsWith('-') ||
+        value.startsWith('/') ||
+        value.endsWith('/') ||
+        value.endsWith('.') ||
+        value.includes('..') ||
+        value.includes('//') ||
+        value.includes('@{') ||
+        hasControlCharacter(value)) {
+        return false;
+    }
+    const components = value.split('/');
+    return components.every((component) => component !== '' &&
+        component !== '.' &&
+        component !== '..' &&
+        !component.startsWith('.') &&
+        !component.endsWith('.lock'));
+}
+function requireSafeRef(value, label) {
+    if (!safeRef(value)) {
+        return fail('invalid-input', `${label} must be a literal bounded Git ref or full object ID.`);
+    }
+    return value;
+}
+function commitExpression(value) {
+    return value.endsWith('^{commit}') && safeRef(value.slice(0, -9));
+}
+function exactCommitRange(value) {
+    const separator = value.indexOf('...');
+    return (separator > 0 &&
+        value.indexOf('...', separator + 3) === -1 &&
+        SHA.test(value.slice(0, separator)) &&
+        SHA.test(value.slice(separator + 3)));
+}
+/**
+ * The inspector calls this gate before every process invocation. It is exported
+ * so adapters can preserve the same fail-closed command boundary.
+ */
+function assertDeveloperAgentReadOnlyGitInvocation(args) {
+    if (args[0] !== NO_OPTIONAL_LOCKS) {
+        return fail('git-command-not-allowed', 'Git inspection requires --no-optional-locks.');
+    }
+    const allowed = sameArgs(args, [
+        NO_OPTIONAL_LOCKS,
+        'rev-parse',
+        '--path-format=absolute',
+        '--show-toplevel',
+    ]) ||
+        sameArgs(args, [
+            NO_OPTIONAL_LOCKS,
+            'rev-parse',
+            '--path-format=absolute',
+            '--git-common-dir',
+        ]) ||
+        (args.length === 5 &&
+            args[1] === 'rev-parse' &&
+            args[2] === '--verify' &&
+            args[3] === '--end-of-options' &&
+            commitExpression(args[4] ?? '')) ||
+        sameArgs(args, [
+            NO_OPTIONAL_LOCKS,
+            'symbolic-ref',
+            '--quiet',
+            '--short',
+            'HEAD',
+        ]) ||
+        sameArgs(args, [
+            NO_OPTIONAL_LOCKS,
+            ...DISABLE_FS_MONITOR,
+            'status',
+            '--porcelain=v1',
+            '-z',
+            '--untracked-files=all',
+            '--no-renames',
+        ]) ||
+        sameArgs(args, [
+            NO_OPTIONAL_LOCKS,
+            'worktree',
+            'list',
+            '--porcelain',
+            '-z',
+        ]) ||
+        (args.length === 5 &&
+            args[1] === 'for-each-ref' &&
+            args[2] === '--format=%(upstream:short)' &&
+            args[3] === '--count=1' &&
+            args[4]?.startsWith('refs/heads/') === true &&
+            safeRef(args[4])) ||
+        (args.length === 5 &&
+            args[1] === 'rev-list' &&
+            args[2] === '--left-right' &&
+            args[3] === '--count' &&
+            exactCommitRange(args[4] ?? '')) ||
+        (args.length === 8 &&
+            args[1] === 'diff' &&
+            args[2] === '--name-only' &&
+            args[3] === '-z' &&
+            args[4] === '--no-renames' &&
+            SHA.test(args[5] ?? '') &&
+            SHA.test(args[6] ?? '') &&
+            args[7] === '--') ||
+        (args.length === 5 &&
+            args[1] === 'merge-base' &&
+            args[2] === '--is-ancestor' &&
+            SHA.test(args[3] ?? '') &&
+            SHA.test(args[4] ?? '')) ||
+        (args.length === 5 &&
+            args[1] === 'merge-base' &&
+            args[2] === '--all' &&
+            SHA.test(args[3] ?? '') &&
+            SHA.test(args[4] ?? ''));
+    if (!allowed) {
+        return fail('git-command-not-allowed', 'Git inspection attempted a command outside the read-only allowlist.');
+    }
+}
+const defaultExecFile = (executable, args, options) => new Promise((resolve, reject) => {
+    (0, node_child_process_1.execFile)(executable, [...args], options, (error, stdout, stderr) => {
+        if (error &&
+            error.code ===
+                'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            reject(new DeveloperAgentGitInspectionError('git-output-too-large', 'Git inspection command output exceeded its byte bound.'));
+            return;
+        }
+        if (error && typeof error.code !== 'number') {
+            reject(error);
+            return;
+        }
+        resolve({
+            exitCode: error && typeof error.code === 'number' ? error.code : 0,
+            stderr,
+            stdout,
+        });
+    });
+});
+class ReadOnlyGit {
+    execFile;
+    defaultCwd;
+    #totalOutputBytes = 0;
+    #environment = createDeveloperAgentGitEnvironment();
+    constructor(execFile, defaultCwd) {
+        this.execFile = execFile;
+        this.defaultCwd = defaultCwd;
+    }
+    async run(args, options = {}) {
+        assertDeveloperAgentReadOnlyGitInvocation(args);
+        let result;
+        try {
+            result = await this.execFile('git', args, {
+                cwd: options.cwd ?? this.defaultCwd,
+                encoding: 'utf8',
+                env: { ...this.#environment },
+                maxBuffer: exports.DEVELOPER_AGENT_GIT_MAX_COMMAND_BYTES,
+                shell: false,
+                timeout: GIT_COMMAND_TIMEOUT_MS,
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            if (error instanceof DeveloperAgentGitInspectionError)
+                throw error;
+            return fail('git-command-failed', 'A read-only Git inspection command could not be executed.');
+        }
+        if (!result ||
+            typeof result !== 'object' ||
+            typeof result.stdout !== 'string' ||
+            typeof result.stderr !== 'string' ||
+            !Number.isInteger(result.exitCode) ||
+            result.exitCode < 0) {
+            return fail('git-output-invalid', 'Git inspection runner returned an invalid command result.');
+        }
+        const outputBytes = Buffer.byteLength(result.stdout, 'utf8') +
+            Buffer.byteLength(result.stderr, 'utf8');
+        this.#totalOutputBytes += outputBytes;
+        if (outputBytes > exports.DEVELOPER_AGENT_GIT_MAX_COMMAND_BYTES ||
+            this.#totalOutputBytes > exports.DEVELOPER_AGENT_GIT_MAX_TOTAL_OUTPUT_BYTES) {
+            return fail('git-output-too-large', 'Git inspection command output exceeded its byte bound.');
+        }
+        const allowedExitCodes = options.allowedExitCodes ?? [0];
+        if (!allowedExitCodes.includes(result.exitCode)) {
+            return fail('git-command-failed', `Read-only Git inspection command failed with exit code ${result.exitCode}.`);
+        }
+        return result;
+    }
+}
+function stripLineEnding(value) {
+    return value.endsWith('\r\n')
+        ? value.slice(0, -2)
+        : value.endsWith('\n')
+            ? value.slice(0, -1)
+            : value;
+}
+function singleSafeLine(value, label, options = {}) {
+    const line = stripLineEnding(value);
+    if ((!options.allowEmpty && line.length === 0) ||
+        line.includes('\n') ||
+        line.includes('\r') ||
+        hasControlCharacter(line) ||
+        line.includes('\uFFFD')) {
+        return fail('git-output-invalid', `${label} returned invalid text.`);
+    }
+    return line;
+}
+function requireCommit(value, label) {
+    const commit = singleSafeLine(value, label);
+    if (!SHA.test(commit)) {
+        return fail('git-output-invalid', `${label} did not resolve one exact commit.`);
+    }
+    return commit;
+}
+function realDirectory(path, label, code) {
+    try {
+        const real = (0, node_fs_1.realpathSync)(path);
+        if (!(0, node_fs_1.statSync)(real).isDirectory())
+            throw new Error('not a directory');
+        return real;
+    }
+    catch {
+        return fail(code, `${label} is not a readable directory.`);
+    }
+}
+function requireAbsoluteDirectoryOutput(value, label, code) {
+    const path = singleSafeLine(value, label);
+    if (!(0, node_path_1.isAbsolute)(path)) {
+        return fail('git-output-invalid', `${label} did not return an absolute path.`);
+    }
+    try {
+        const real = (0, node_fs_1.realpathSync)(path);
+        if (!(0, node_fs_1.statSync)(real).isDirectory())
+            throw new Error('not a directory');
+        return real;
+    }
+    catch {
+        return fail(code, `${label} did not resolve to a readable directory.`);
+    }
+}
+function consumePath(path, label, budget) {
+    budget.count += 1;
+    if (budget.count > exports.DEVELOPER_AGENT_GIT_MAX_PATHS) {
+        return fail('git-path-limit-exceeded', 'Git inspection exceeded its total path-count bound.');
+    }
+    if (path.length === 0 ||
+        Buffer.byteLength(path, 'utf8') > exports.DEVELOPER_AGENT_GIT_MAX_PATH_BYTES ||
+        hasControlCharacter(path) ||
+        path.includes('\uFFFD') ||
+        path.includes('\\') ||
+        (0, node_path_1.isAbsolute)(path) ||
+        path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+        return fail('git-output-invalid', `${label} returned an unsafe path.`);
+    }
+    return path;
+}
+function nulTokens(value, label) {
+    if (value === '')
+        return [];
+    if (!value.endsWith('\0')) {
+        return fail('git-output-invalid', `${label} did not use a complete NUL-delimited result.`);
+    }
+    const tokens = value.split('\0');
+    tokens.pop();
+    return tokens;
+}
+function parseChangedPaths(value, label, budget) {
+    const tokens = nulTokens(value, label);
+    if (tokens.some((token) => token === '')) {
+        return fail('git-output-invalid', `${label} returned an empty path.`);
+    }
+    const paths = tokens.map((path) => consumePath(path, label, budget));
+    return [...new Set(paths)].sort(compareStrings);
+}
+function parseDirtyPaths(value, budget) {
+    const tokens = nulTokens(value, 'Git status');
+    const paths = [];
+    for (const token of tokens) {
+        if (token.length < 4 ||
+            token[2] !== ' ' ||
+            !/^[ MADUT?!]{2}$/u.test(token.slice(0, 2)) ||
+            token.slice(0, 2) === '  ') {
+            return fail('git-output-invalid', 'Git status returned malformed porcelain output.');
+        }
+        if (token.slice(0, 2) === '!!')
+            continue;
+        paths.push(consumePath(token.slice(3), 'Git status', budget));
+    }
+    return [...new Set(paths)].sort(compareStrings);
+}
+function worktreeField(token) {
+    const separator = token.indexOf(' ');
+    const key = separator === -1 ? token : token.slice(0, separator);
+    const value = separator === -1 ? undefined : token.slice(separator + 1);
+    if (key.length === 0 ||
+        hasControlCharacter(key) ||
+        value?.includes('\uFFFD') ||
+        (value !== undefined && hasControlCharacter(value))) {
+        return fail('git-output-invalid', 'Git worktree inventory returned invalid text.');
+    }
+    return value === undefined ? { key } : { key, value };
+}
+function parseWorktreeList(value) {
+    const tokens = nulTokens(value, 'Git worktree inventory');
+    const worktrees = [];
+    let current;
+    const finish = () => {
+        if (!current) {
+            return fail('git-output-invalid', 'Git worktree inventory contained an empty record.');
+        }
+        worktrees.push(current);
+        current = undefined;
+        if (worktrees.length > exports.DEVELOPER_AGENT_GIT_MAX_WORKTREES) {
+            return fail('git-path-limit-exceeded', 'Git worktree inventory exceeded its worktree-count bound.');
+        }
+    };
+    for (const token of tokens) {
+        if (token === '') {
+            finish();
+            continue;
+        }
+        const { key, value: fieldValue } = worktreeField(token);
+        if (key === 'worktree') {
+            if (current || !fieldValue) {
+                return fail('git-output-invalid', 'Git worktree inventory has an ambiguous record boundary.');
+            }
+            current = {
+                bare: false,
+                detached: false,
+                locked: false,
+                path: fieldValue,
+                prunable: false,
+            };
+            continue;
+        }
+        if (!current) {
+            return fail('git-output-invalid', 'Git worktree inventory did not begin with a worktree path.');
+        }
+        if (key === 'HEAD') {
+            if (current.head !== undefined || !fieldValue) {
+                return fail('git-output-invalid', 'Git worktree inventory contains duplicate HEAD state.');
+            }
+            current.head = fieldValue;
+        }
+        else if (key === 'branch') {
+            if (current.branchRef !== undefined || current.detached || !fieldValue) {
+                return fail('git-output-invalid', 'Git worktree inventory contains ambiguous branch state.');
+            }
+            current.branchRef = fieldValue;
+        }
+        else if (key === 'detached') {
+            if (fieldValue !== undefined || current.detached || current.branchRef) {
+                return fail('git-output-invalid', 'Git worktree inventory contains ambiguous detached state.');
+            }
+            current.detached = true;
+        }
+        else if (key === 'bare') {
+            if (fieldValue !== undefined || current.bare) {
+                return fail('git-output-invalid', 'Git worktree inventory contains duplicate bare state.');
+            }
+            current.bare = true;
+        }
+        else if (key === 'locked') {
+            if (current.locked) {
+                return fail('git-output-invalid', 'Git worktree inventory contains duplicate lock state.');
+            }
+            current.locked = true;
+        }
+        else if (key === 'prunable') {
+            if (current.prunable) {
+                return fail('git-output-invalid', 'Git worktree inventory contains duplicate prunable state.');
+            }
+            current.prunable = true;
+        }
+        else {
+            return fail('git-output-invalid', `Git worktree inventory returned unsupported field ${key}.`);
+        }
+    }
+    if (current) {
+        return fail('git-output-invalid', 'Git worktree inventory omitted its final record boundary.');
+    }
+    if (worktrees.length === 0) {
+        return fail('git-output-invalid', 'Git worktree inventory returned no worktrees.');
+    }
+    return worktrees;
+}
+function prepareWorktrees(raw) {
+    const prepared = raw.map((worktree, index) => {
+        if (worktree.bare) {
+            return fail('git-worktree-unreadable', 'Bare repositories are outside linked-worktree inspection.');
+        }
+        if (!(0, node_path_1.isAbsolute)(worktree.path) || hasControlCharacter(worktree.path)) {
+            return fail('git-output-invalid', 'Git worktree inventory returned an unsafe worktree path.');
+        }
+        const realRoot = realDirectory(worktree.path, `Linked worktree ${index}`, 'git-worktree-unreadable');
+        if (!worktree.head || !SHA.test(worktree.head)) {
+            return fail('git-output-invalid', 'Git worktree inventory did not bind an exact commit.');
+        }
+        if ((worktree.branchRef === undefined) === !worktree.detached) {
+            return fail('git-output-invalid', 'Git worktree inventory did not bind exactly one branch state.');
+        }
+        let branch = null;
+        if (worktree.branchRef !== undefined) {
+            if (!worktree.branchRef.startsWith('refs/heads/') ||
+                !safeRef(worktree.branchRef)) {
+                return fail('git-output-invalid', 'Git worktree inventory returned an unsafe local branch ref.');
+            }
+            branch = worktree.branchRef.slice('refs/heads/'.length);
+            if (!safeRef(branch)) {
+                return fail('git-output-invalid', 'Git worktree inventory returned an unsafe local branch name.');
+            }
+        }
+        return {
+            ...worktree,
+            branch,
+            head: worktree.head,
+            realRoot,
+        };
+    });
+    const roots = prepared.map(({ realRoot }) => realRoot);
+    if (new Set(roots).size !== roots.length) {
+        return fail('git-worktree-ambiguous', 'Multiple linked-worktree records resolve to the same directory.');
+    }
+    const branches = prepared
+        .map(({ branch }) => branch)
+        .filter((branch) => branch !== null);
+    if (new Set(branches).size !== branches.length) {
+        return fail('git-worktree-ambiguous', 'Multiple linked worktrees claim the same local branch.');
+    }
+    return {
+        primaryRoot: prepared[0]?.realRoot,
+        worktrees: prepared.sort((left, right) => compareStrings(left.realRoot, right.realRoot)),
+    };
+}
+async function resolveCommit(git, ref, cwd) {
+    const result = await git.run([
+        NO_OPTIONAL_LOCKS,
+        'rev-parse',
+        '--verify',
+        '--end-of-options',
+        `${ref}^{commit}`,
+    ], { cwd });
+    return requireCommit(result.stdout, `Git ref ${ref}`);
+}
+async function resolveDirectory(git, kind, cwd) {
+    const result = await git.run([NO_OPTIONAL_LOCKS, 'rev-parse', '--path-format=absolute', kind], { cwd });
+    return requireAbsoluteDirectoryOutput(result.stdout, kind === '--show-toplevel' ? 'Git worktree root' : 'Git common directory', kind === '--show-toplevel'
+        ? 'git-worktree-unreadable'
+        : 'git-output-invalid');
+}
+async function resolveBranch(git, cwd) {
+    const result = await git.run([NO_OPTIONAL_LOCKS, 'symbolic-ref', '--quiet', '--short', 'HEAD'], { allowedExitCodes: [0, 1], cwd });
+    if (result.exitCode === 1) {
+        if (singleSafeLine(result.stdout, 'Detached branch state', {
+            allowEmpty: true,
+        })) {
+            return fail('git-output-invalid', 'Detached branch inspection unexpectedly returned a branch.');
+        }
+        return { branch: null, detached: true };
+    }
+    const branch = singleSafeLine(result.stdout, 'Current Git branch');
+    if (!safeRef(branch)) {
+        return fail('git-output-invalid', 'Current Git branch is outside the safe ref grammar.');
+    }
+    return { branch, detached: false };
+}
+async function verifyWorktree(git, commonDirectory, worktree, budget) {
+    const discoveredRoot = await resolveDirectory(git, '--show-toplevel', worktree.realRoot);
+    const discoveredCommon = await resolveDirectory(git, '--git-common-dir', worktree.realRoot);
+    if (discoveredRoot !== worktree.realRoot ||
+        discoveredCommon !== commonDirectory) {
+        return fail('git-worktree-ambiguous', 'Linked worktree identity does not match the inspected repository.');
+    }
+    const commit = await resolveCommit(git, 'HEAD', worktree.realRoot);
+    const branchState = await resolveBranch(git, worktree.realRoot);
+    if (commit !== worktree.head ||
+        branchState.branch !== worktree.branch ||
+        branchState.detached !== worktree.detached) {
+        return fail('git-worktree-ambiguous', 'Linked worktree state changed during inspection.');
+    }
+    const status = await git.run([
+        NO_OPTIONAL_LOCKS,
+        ...DISABLE_FS_MONITOR,
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--untracked-files=all',
+        '--no-renames',
+    ], { cwd: worktree.realRoot });
+    return {
+        branch: branchState.branch,
+        commit,
+        detached: branchState.detached,
+        dirtyPaths: parseDirtyPaths(status.stdout, budget),
+        locked: worktree.locked,
+        prunable: worktree.prunable,
+        root: worktree.realRoot,
+    };
+}
+async function inspectUpstream(git, current) {
+    if (!current.branch)
+        return undefined;
+    const upstreamResult = await git.run([
+        NO_OPTIONAL_LOCKS,
+        'for-each-ref',
+        '--format=%(upstream:short)',
+        '--count=1',
+        `refs/heads/${current.branch}`,
+    ], { cwd: current.root });
+    const ref = singleSafeLine(upstreamResult.stdout, 'Git upstream', {
+        allowEmpty: true,
+    });
+    if (!ref)
+        return undefined;
+    if (!safeRef(ref)) {
+        return fail('git-output-invalid', 'Git upstream is outside the safe ref grammar.');
+    }
+    const commit = await resolveCommit(git, ref, current.root);
+    const counts = await git.run([
+        NO_OPTIONAL_LOCKS,
+        'rev-list',
+        '--left-right',
+        '--count',
+        `${current.commit}...${commit}`,
+    ], { cwd: current.root });
+    const countLine = stripLineEnding(counts.stdout);
+    const match = countLine.match(/^([0-9]+)[\t ]+([0-9]+)$/u);
+    if (!match ||
+        countLine.includes('\n') ||
+        countLine.includes('\r') ||
+        Number(match[1]) > Number.MAX_SAFE_INTEGER ||
+        Number(match[2]) > Number.MAX_SAFE_INTEGER) {
+        return fail('git-output-invalid', 'Git upstream divergence returned invalid counts.');
+    }
+    return {
+        ahead: Number(match[1]),
+        behind: Number(match[2]),
+        commit,
+        ref,
+    };
+}
+async function inspectComparison(git, root, base, head, budget) {
+    const baseCommit = await resolveCommit(git, base, root);
+    const headCommit = await resolveCommit(git, head, root);
+    const changed = await git.run([
+        NO_OPTIONAL_LOCKS,
+        'diff',
+        '--name-only',
+        '-z',
+        '--no-renames',
+        baseCommit,
+        headCommit,
+        '--',
+    ], { cwd: root });
+    const ancestry = await git.run([NO_OPTIONAL_LOCKS, 'merge-base', '--is-ancestor', baseCommit, headCommit], { allowedExitCodes: [0, 1], cwd: root });
+    const baseIsAncestorOfHead = ancestry.exitCode === 0;
+    return {
+        base: { commit: baseCommit, ref: base },
+        baseIsAncestorOfHead,
+        changedPaths: parseChangedPaths(changed.stdout, 'Git base/head comparison', budget),
+        head: { commit: headCommit, ref: head },
+        staleBase: !baseIsAncestorOfHead,
+    };
+}
+function dirtyOverlapWarnings(worktrees) {
+    const rootsByPath = new Map();
+    for (const worktree of worktrees) {
+        for (const path of worktree.dirtyPaths) {
+            const roots = rootsByPath.get(path) ?? [];
+            roots.push(worktree.root);
+            rootsByPath.set(path, roots);
+        }
+    }
+    return [...rootsByPath.entries()]
+        .filter(([, roots]) => roots.length > 1)
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([path, roots]) => ({
+        code: 'dirty-path-overlap',
+        path,
+        worktreeRoots: roots.sort(compareStrings),
+    }));
+}
+function pathCollisionKey(path) {
+    return path.normalize('NFC').toLocaleLowerCase('en-US');
+}
+async function inspectConcurrentChanges(git, current, worktrees, budget) {
+    const changes = new Map();
+    const record = (path, root, source) => {
+        const key = pathCollisionKey(path);
+        const existing = changes.get(key) ?? {
+            committedRoots: new Set(),
+            dirtyRoots: new Set(),
+            path,
+        };
+        if (compareStrings(path, existing.path) < 0)
+            existing.path = path;
+        (source === 'committed'
+            ? existing.committedRoots
+            : existing.dirtyRoots).add(root);
+        changes.set(key, existing);
+    };
+    let complete = true;
+    for (const worktree of worktrees) {
+        if (worktree.root === current.root)
+            continue;
+        for (const path of worktree.dirtyPaths)
+            record(path, worktree.root, 'dirty');
+        if (worktree.commit === current.commit)
+            continue;
+        const mergeBase = await git.run([
+            NO_OPTIONAL_LOCKS,
+            'merge-base',
+            '--all',
+            current.commit,
+            worktree.commit,
+        ], { allowedExitCodes: [0, 1], cwd: current.root });
+        if (mergeBase.exitCode === 1) {
+            complete = false;
+            continue;
+        }
+        const mergeBases = stripLineEnding(mergeBase.stdout).split(/\r?\n/u);
+        if (mergeBases.length !== 1 ||
+            !SHA.test(mergeBases[0] ?? '') ||
+            mergeBases[0] === '') {
+            complete = false;
+            continue;
+        }
+        const base = mergeBases[0];
+        if (base === worktree.commit)
+            continue;
+        const changed = await git.run([
+            NO_OPTIONAL_LOCKS,
+            'diff',
+            '--name-only',
+            '-z',
+            '--no-renames',
+            base,
+            worktree.commit,
+            '--',
+        ], { cwd: current.root });
+        for (const path of parseChangedPaths(changed.stdout, 'Concurrent linked-worktree comparison', budget)) {
+            record(path, worktree.root, 'committed');
+        }
+    }
+    return {
+        complete,
+        paths: [...changes.values()]
+            .map(({ committedRoots, dirtyRoots, path }) => ({
+            committed: committedRoots.size > 0,
+            dirty: dirtyRoots.size > 0,
+            path,
+            worktreeRoots: [...new Set([...committedRoots, ...dirtyRoots])].sort(compareStrings),
+        }))
+            .sort((left, right) => compareStrings(pathCollisionKey(left.path), pathCollisionKey(right.path))),
+    };
+}
+function validateInput(options) {
+    if (!options ||
+        typeof options !== 'object' ||
+        typeof options.cwd !== 'string' ||
+        options.cwd.length === 0 ||
+        hasControlCharacter(options.cwd) ||
+        !(0, node_path_1.isAbsolute)(options.cwd)) {
+        return fail('invalid-input', 'Git inspection requires an absolute control-free cwd.');
+    }
+    if ((options.base === undefined) !== (options.head === undefined)) {
+        return fail('invalid-input', 'Git comparison requires both explicit base and head refs.');
+    }
+    if (options.base !== undefined && options.head !== undefined) {
+        return {
+            base: requireSafeRef(options.base, 'Git comparison base'),
+            ...(options.defaultBase !== undefined
+                ? {
+                    defaultBase: requireSafeRef(options.defaultBase, 'Git default base'),
+                }
+                : {}),
+            head: requireSafeRef(options.head, 'Git comparison head'),
+        };
+    }
+    return options.defaultBase !== undefined
+        ? {
+            defaultBase: requireSafeRef(options.defaultBase, 'Git default base'),
+        }
+        : {};
+}
+async function inspectDeveloperAgentGit(options) {
+    const comparisonInput = validateInput(options);
+    const invocationCwd = realDirectory(options.cwd, 'Git inspection cwd', 'invalid-input');
+    const git = new ReadOnlyGit(options.execFile ?? defaultExecFile, invocationCwd);
+    const currentRoot = await resolveDirectory(git, '--show-toplevel', invocationCwd);
+    const commonDirectory = await resolveDirectory(git, '--git-common-dir', invocationCwd);
+    const worktreeList = await git.run([NO_OPTIONAL_LOCKS, 'worktree', 'list', '--porcelain', '-z'], { cwd: currentRoot });
+    const { primaryRoot, worktrees: prepared } = prepareWorktrees(parseWorktreeList(worktreeList.stdout));
+    if (!prepared.some(({ realRoot }) => realRoot === currentRoot)) {
+        return fail('git-worktree-ambiguous', 'Current worktree is absent from the repository worktree inventory.');
+    }
+    const budget = { count: 0 };
+    const linkedWorktrees = [];
+    for (const worktree of prepared) {
+        linkedWorktrees.push(await verifyWorktree(git, commonDirectory, worktree, budget));
+    }
+    const current = linkedWorktrees.find(({ root }) => root === currentRoot);
+    if (!current) {
+        return fail('git-worktree-ambiguous', 'Current worktree could not be resolved uniquely.');
+    }
+    const upstream = await inspectUpstream(git, current);
+    const defaultBase = comparisonInput.defaultBase !== undefined
+        ? {
+            commit: await resolveCommit(git, comparisonInput.defaultBase, currentRoot),
+            ref: comparisonInput.defaultBase,
+        }
+        : undefined;
+    const comparison = comparisonInput.base !== undefined && comparisonInput.head !== undefined
+        ? await inspectComparison(git, currentRoot, comparisonInput.base, comparisonInput.head, budget)
+        : undefined;
+    const concurrent = await inspectConcurrentChanges(git, current, linkedWorktrees, budget);
+    const warnings = dirtyOverlapWarnings(linkedWorktrees);
+    if (comparison?.staleBase) {
+        warnings.push({
+            baseRef: comparison.base.ref,
+            code: 'stale-base',
+            headRef: comparison.head.ref,
+        });
+    }
+    warnings.sort((left, right) => {
+        const leftKey = left.code === 'dirty-path-overlap'
+            ? `${left.code}:${left.path}`
+            : `${left.code}:${left.baseRef}:${left.headRef}`;
+        const rightKey = right.code === 'dirty-path-overlap'
+            ? `${right.code}:${right.path}`
+            : `${right.code}:${right.baseRef}:${right.headRef}`;
+        return compareStrings(leftKey, rightKey);
+    });
+    const result = {
+        ...(comparison ? { comparison } : {}),
+        concurrentChangeInspectionComplete: concurrent.complete,
+        concurrentChanges: concurrent.paths,
+        ...(defaultBase ? { defaultBase } : {}),
+        kind: 'developer-agent-git-inspection',
+        linkedWorktrees,
+        repository: {
+            commonDirectory,
+            root: primaryRoot,
+        },
+        schemaVersion: exports.DEVELOPER_AGENT_GIT_INSPECTION_SCHEMA_VERSION,
+        warnings,
+        worktree: {
+            ...current,
+            ...(upstream ? { upstream } : {}),
+        },
+    };
+    if (Buffer.byteLength(JSON.stringify(result), 'utf8') >
+        exports.DEVELOPER_AGENT_GIT_MAX_RESULT_BYTES) {
+        return fail('git-output-too-large', 'Git inspection result exceeded its serialized byte bound.');
+    }
+    return result;
+}
+//# sourceMappingURL=git-inspection.js.map