acker-dacker 0.1.0

package/src/git-handoff-selection.ts

@@ -0,0 +1,255 @@
+import type { Stats } from 'node:fs';
+import { lstat, readlink, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { detectXcodeProject, isSensitiveUntrackedPath, isUntrackedSafetyExcludedPath } from './file-policy';
+import { decodeGitPathList, requireSuccessfulCommand, runExternalCommand } from './git';
+import {
+    compareStableStrings,
+    globPatternToRegexSource,
+    isPathWithin,
+    normalizeArchivePath,
+} from './path-patterns';
+
+export type FileSnapshot = {
+    readonly ctimeMs: number;
+    readonly dev: number;
+    readonly ino: number;
+    readonly mode: number;
+    readonly mtimeMs: number;
+    readonly size: number;
+};
+
+export type GitHandoffCandidate = {
+    readonly archivePath: string;
+    readonly initialSnapshot: FileSnapshot;
+    readonly isTracked: boolean;
+    readonly relativePath: string;
+    readonly sourcePath: string;
+};
+
+export type GitHandoffExclusion = {
+    readonly count: number;
+    readonly pattern: string;
+};
+
+export type GitHandoffProfile = 'rust-stage3';
+
+export type GitHandoffSelection = {
+    readonly candidates: readonly GitHandoffCandidate[];
+    readonly explicitExclusions: readonly GitHandoffExclusion[];
+    readonly explicitExclusionTotal: number;
+    readonly filterCount: number;
+    readonly gitSelectedCount: number;
+    readonly profile: GitHandoffProfile | null;
+    readonly profileFilteredCount: number;
+    readonly sensitiveUntrackedCount: number;
+    readonly safetyFilteredUntrackedCount: number;
+};
+
+type HandoffExcludeMatcher = {
+    readonly matcher: RegExp;
+    readonly pattern: string;
+};
+
+const validateGitRelativePath = (relativePath: string): string => {
+    const normalized = normalizeArchivePath(relativePath);
+    const segments = normalized.split('/');
+    if (
+        normalized.length === 0 ||
+        normalized.includes('\0') ||
+        normalized.startsWith('/') ||
+        normalized === '.' ||
+        normalized === '..' ||
+        normalized.startsWith('../') ||
+        normalized.includes('/../') ||
+        segments.some((segment) => segment.length === 0 || segment === '.')
+    ) {
+        throw new Error(`Git handoff refused unsafe repository path: ${JSON.stringify(relativePath)}`);
+    }
+    return normalized;
+};
+
+const compileHandoffExclude = (pattern: string): HandoffExcludeMatcher => {
+    let normalized = pattern;
+    if (normalized.startsWith('./')) {
+        normalized = normalized.slice(2);
+    }
+    if (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    const segments = normalized.split('/');
+    if (
+        normalized.length === 0 ||
+        normalized.includes('\0') ||
+        normalized.startsWith('/') ||
+        path.isAbsolute(normalized) ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')
+    ) {
+        throw new Error(`--exclude must be a root-relative path or glob: ${JSON.stringify(pattern)}`);
+    }
+
+    return {
+        matcher: new RegExp(`^${globPatternToRegexSource(normalized)}(?:/.*)?$`),
+        pattern,
+    };
+};
+
+export const snapshotFile = (fileStats: Stats): FileSnapshot => ({
+    ctimeMs: fileStats.ctimeMs,
+    dev: fileStats.dev,
+    ino: fileStats.ino,
+    mode: fileStats.mode,
+    mtimeMs: fileStats.mtimeMs,
+    size: fileStats.size,
+});
+
+export const resolveGitHandoffProfile = (profile: string | null): GitHandoffProfile | null => {
+    if (profile === null) {
+        return null;
+    }
+    if (profile === 'rust-stage3') {
+        return profile;
+    }
+    throw new Error(`Unknown Git handoff profile: ${profile}`);
+};
+
+// Named profiles use validated root-relative paths. Generic --filter matching intentionally
+// retains the historical path-or-basename behavior in collectGitHandoffSelection.
+const matchesRustStage3Profile = (relativePath: string): boolean => {
+    return (
+        relativePath === 'AGENTS.md' ||
+        relativePath === '.gitignore' ||
+        relativePath === 'justfile' ||
+        relativePath === 'scripts/format.py' ||
+        relativePath === 'scripts/just-shell.py' ||
+        relativePath === 'codex-rs' ||
+        relativePath.startsWith('codex-rs/')
+    );
+};
+
+const matchesGitHandoffProfile = (profile: GitHandoffProfile, relativePath: string): boolean => {
+    return profile === 'rust-stage3' && matchesRustStage3Profile(relativePath);
+};
+
+// Relative symlinks are preserved only when their resolved target exists inside the worktree.
+export const validateHandoffSymlink = async (
+    rootDir: string,
+    sourcePath: string,
+    linkTarget: string,
+): Promise<void> => {
+    if (linkTarget.length === 0 || linkTarget.includes('\0') || path.isAbsolute(linkTarget)) {
+        throw new Error(`Git handoff refused unsafe symlink ${sourcePath}`);
+    }
+
+    const lexicalTarget = path.resolve(path.dirname(sourcePath), linkTarget);
+    if (!isPathWithin(lexicalTarget, rootDir)) {
+        throw new Error(`Git handoff refused escaping symlink ${sourcePath}`);
+    }
+
+    const resolvedTarget = await realpath(sourcePath).catch(() => null);
+    if (!resolvedTarget || !isPathWithin(resolvedTarget, rootDir)) {
+        throw new Error(`Git handoff refused unresolved or escaping symlink ${sourcePath}`);
+    }
+};
+
+export const collectGitHandoffSelection = async (
+    rootDir: string,
+    filters: readonly RegExp[],
+    excludePatterns: readonly string[],
+    profile: GitHandoffProfile | null,
+): Promise<GitHandoffSelection> => {
+    const excludeMatchers = excludePatterns.map(compileHandoffExclude);
+    const allArgs = ['-C', rootDir, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'];
+    const allResult = await runExternalCommand('git', allArgs, rootDir);
+    const allPaths = [...new Set(decodeGitPathList(requireSuccessfulCommand('git', allArgs, allResult)))];
+
+    const trackedArgs = ['-C', rootDir, 'ls-files', '--cached', '-z'];
+    const trackedResult = await runExternalCommand('git', trackedArgs, rootDir);
+    const trackedPaths = new Set(decodeGitPathList(requireSuccessfulCommand('git', trackedArgs, trackedResult)));
+
+    const untrackedArgs = ['-C', rootDir, 'ls-files', '--others', '--exclude-standard', '-z'];
+    const untrackedResult = await runExternalCommand('git', untrackedArgs, rootDir);
+    const untrackedPaths = new Set(decodeGitPathList(requireSuccessfulCommand('git', untrackedArgs, untrackedResult)));
+    const isXcodeProject = await detectXcodeProject(rootDir);
+    const exclusionCounts = new Map<string, number>(excludePatterns.map((pattern) => [pattern, 0]));
+    const candidates: GitHandoffCandidate[] = [];
+    let explicitExclusionTotal = 0;
+    let filterCount = 0;
+    let profileFilteredCount = 0;
+    let sensitiveUntrackedCount = 0;
+    let safetyFilteredUntrackedCount = 0;
+
+    for (const rawPath of allPaths) {
+        const relativePath = validateGitRelativePath(rawPath);
+        const isTracked = trackedPaths.has(rawPath);
+        if (!isTracked && !untrackedPaths.has(rawPath)) {
+            throw new Error(`Git handoff could not classify selected path: ${JSON.stringify(relativePath)}`);
+        }
+
+        const matchingExclude = excludeMatchers.find((exclude) => exclude.matcher.test(relativePath));
+        if (matchingExclude) {
+            exclusionCounts.set(matchingExclude.pattern, (exclusionCounts.get(matchingExclude.pattern) ?? 0) + 1);
+            explicitExclusionTotal += 1;
+            continue;
+        }
+
+        if (profile && !matchesGitHandoffProfile(profile, relativePath)) {
+            profileFilteredCount += 1;
+            continue;
+        }
+
+        if (
+            filters.length > 0 &&
+            !filters.some(
+                (matcher) => matcher.test(relativePath) || matcher.test(path.posix.basename(relativePath)),
+            )
+        ) {
+            filterCount += 1;
+            continue;
+        }
+
+        if (!isTracked && isUntrackedSafetyExcludedPath(relativePath, isXcodeProject)) {
+            safetyFilteredUntrackedCount += 1;
+            if (isSensitiveUntrackedPath(relativePath)) {
+                sensitiveUntrackedCount += 1;
+            }
+            continue;
+        }
+
+        const sourcePath = path.join(rootDir, relativePath);
+        const sourceStats = await lstat(sourcePath).catch((error) => {
+            throw new Error(`Git handoff could not read selected path ${relativePath}: ${error}`);
+        });
+        if (!sourceStats.isFile() && !sourceStats.isSymbolicLink()) {
+            throw new Error(`Git handoff refuses special or directory path: ${relativePath}`);
+        }
+        if (sourceStats.isSymbolicLink()) {
+            await validateHandoffSymlink(rootDir, sourcePath, await readlink(sourcePath));
+        }
+
+        candidates.push({
+            archivePath: normalizeArchivePath(path.join(path.basename(rootDir), relativePath)),
+            initialSnapshot: snapshotFile(sourceStats),
+            isTracked,
+            relativePath,
+            sourcePath,
+        });
+    }
+
+    candidates.sort((left, right) => compareStableStrings(left.relativePath, right.relativePath));
+    const explicitExclusions = [...exclusionCounts.entries()]
+        .sort(([left], [right]) => compareStableStrings(left, right))
+        .map(([pattern, count]) => ({ count, pattern }));
+
+    return {
+        candidates,
+        explicitExclusionTotal,
+        explicitExclusions,
+        filterCount,
+        gitSelectedCount: allPaths.length,
+        profile,
+        profileFilteredCount,
+        safetyFilteredUntrackedCount,
+        sensitiveUntrackedCount,
+    };
+};

package/src/git-handoff.ts

@@ -0,0 +1,294 @@
+import { chmod, lstat, mkdir, mkdtemp, readlink, realpath, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { resolveGitWorktree } from './git';
+import {
+    collectGitHandoffSelection,
+    resolveGitHandoffProfile,
+    snapshotFile,
+    validateHandoffSymlink,
+} from './git-handoff-selection';
+import type {
+    FileSnapshot,
+    GitHandoffCandidate,
+    GitHandoffExclusion,
+    GitHandoffProfile,
+    GitHandoffSelection,
+} from './git-handoff-selection';
+import { compareStableStrings, isPathWithin } from './path-patterns';
+import { createZipFile } from './zip';
+
+type GitHandoffReport = {
+    readonly excluded: {
+        readonly explicit: {
+            readonly total: number;
+            readonly patterns: readonly GitHandoffExclusion[];
+        };
+        readonly filterCount: number;
+        readonly profileFilteredCount: number;
+        readonly sensitiveUntrackedCount: number;
+        readonly safetyFilteredUntrackedCount: number;
+    };
+    readonly included: {
+        readonly bytes: number;
+        readonly count: number;
+        readonly executableCount: number;
+        readonly symlinkCount: number;
+        readonly trackedCount: number;
+        readonly untrackedCount: number;
+    };
+    readonly includedPaths: readonly string[];
+    readonly gitSelectionCount: number;
+    readonly mode: 'git-handoff';
+    readonly profile: GitHandoffProfile | null;
+    readonly version: 1;
+};
+
+type GitHandoffStats = {
+    bytes: number;
+    executableCount: number;
+    includedPaths: string[];
+    symlinkCount: number;
+    trackedCount: number;
+    untrackedCount: number;
+};
+
+export type GitHandoffOptions = {
+    readonly excludes: readonly string[];
+    readonly filters: readonly RegExp[];
+    readonly outputFile: string | null;
+    readonly profile: string | null;
+    readonly reportFile: string | null;
+    readonly targetDir: string;
+};
+
+type StagedHandoffEntry = {
+    readonly bytes: number;
+    readonly isSymlink: boolean;
+    readonly mode: number;
+};
+
+const snapshotsMatch = (left: FileSnapshot, right: FileSnapshot): boolean => {
+    return (
+        left.ctimeMs === right.ctimeMs &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.mtimeMs === right.mtimeMs &&
+        left.size === right.size
+    );
+};
+
+const assertSourceUnchanged = (sourcePath: string, before: FileSnapshot, after: FileSnapshot): void => {
+    if (!snapshotsMatch(before, after)) {
+        throw new Error(`Git handoff aborted because a source changed during packaging: ${sourcePath}`);
+    }
+};
+
+const stageGitHandoffEntry = async (
+    rootDir: string,
+    candidate: GitHandoffCandidate,
+    destinationPath: string,
+): Promise<StagedHandoffEntry> => {
+    const sourceStats = await lstat(candidate.sourcePath).catch((error) => {
+        throw new Error(`Git handoff could not read selected path ${candidate.relativePath}: ${error}`);
+    });
+    const before = snapshotFile(sourceStats);
+    assertSourceUnchanged(candidate.sourcePath, candidate.initialSnapshot, before);
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+
+    if (sourceStats.isSymbolicLink()) {
+        const linkTarget = await readlink(candidate.sourcePath);
+        await validateHandoffSymlink(rootDir, candidate.sourcePath, linkTarget);
+        const afterStats = await lstat(candidate.sourcePath);
+        const afterTarget = await readlink(candidate.sourcePath);
+        assertSourceUnchanged(candidate.sourcePath, before, snapshotFile(afterStats));
+        assertSourceUnchanged(candidate.sourcePath, candidate.initialSnapshot, snapshotFile(afterStats));
+        if (linkTarget !== afterTarget) {
+            throw new Error(`Git handoff aborted because a symlink changed during packaging: ${candidate.sourcePath}`);
+        }
+        await symlink(linkTarget, destinationPath);
+        return {
+            bytes: new TextEncoder().encode(linkTarget).byteLength,
+            isSymlink: true,
+            mode: sourceStats.mode,
+        };
+    }
+
+    if (!sourceStats.isFile()) {
+        throw new Error(`Git handoff refuses special or directory path: ${candidate.relativePath}`);
+    }
+
+    await Bun.write(destinationPath, Bun.file(candidate.sourcePath));
+    const afterStats = await lstat(candidate.sourcePath);
+    assertSourceUnchanged(candidate.sourcePath, before, snapshotFile(afterStats));
+    assertSourceUnchanged(candidate.sourcePath, candidate.initialSnapshot, snapshotFile(afterStats));
+    await chmod(destinationPath, sourceStats.mode & 0o7777);
+    return {
+        bytes: sourceStats.size,
+        isSymlink: false,
+        mode: sourceStats.mode,
+    };
+};
+
+const stageGitHandoffFiles = async (
+    rootDir: string,
+    stagingRoot: string,
+    candidates: readonly GitHandoffCandidate[],
+): Promise<GitHandoffStats> => {
+    const stats: GitHandoffStats = {
+        bytes: 0,
+        executableCount: 0,
+        includedPaths: [],
+        symlinkCount: 0,
+        trackedCount: 0,
+        untrackedCount: 0,
+    };
+    const archiveRoot = path.join(stagingRoot, path.basename(rootDir));
+
+    for (const candidate of candidates) {
+        const destinationPath = path.join(archiveRoot, candidate.relativePath);
+        const staged = await stageGitHandoffEntry(rootDir, candidate, destinationPath);
+        stats.bytes += staged.bytes;
+        stats.includedPaths.push(candidate.archivePath);
+        if (candidate.isTracked) {
+            stats.trackedCount += 1;
+        } else {
+            stats.untrackedCount += 1;
+        }
+        if (staged.isSymlink) {
+            stats.symlinkCount += 1;
+        } else if ((staged.mode & 0o111) !== 0) {
+            stats.executableCount += 1;
+        }
+    }
+
+    return stats;
+};
+
+const makeGitHandoffReport = (
+    selection: GitHandoffSelection,
+    stats: GitHandoffStats,
+): GitHandoffReport => ({
+    excluded: {
+        explicit: {
+            patterns: selection.explicitExclusions,
+            total: selection.explicitExclusionTotal,
+        },
+        filterCount: selection.filterCount,
+        profileFilteredCount: selection.profileFilteredCount,
+        safetyFilteredUntrackedCount: selection.safetyFilteredUntrackedCount,
+        sensitiveUntrackedCount: selection.sensitiveUntrackedCount,
+    },
+    gitSelectionCount: selection.gitSelectedCount,
+    included: {
+        bytes: stats.bytes,
+        count: stats.trackedCount + stats.untrackedCount,
+        executableCount: stats.executableCount,
+        symlinkCount: stats.symlinkCount,
+        trackedCount: stats.trackedCount,
+        untrackedCount: stats.untrackedCount,
+    },
+    includedPaths: [...stats.includedPaths].sort(compareStableStrings),
+    mode: 'git-handoff',
+    profile: selection.profile,
+    version: 1,
+});
+
+const emitGitHandoffReport = async (report: GitHandoffReport, reportFile: string | null): Promise<void> => {
+    console.log(
+        `[git-handoff] Included ${report.included.count} files (${report.included.trackedCount} tracked, ${report.included.untrackedCount} untracked, ${report.included.bytes} bytes).`,
+    );
+    console.log(
+        `[git-handoff] Metadata: ${report.included.executableCount} executable files, ${report.included.symlinkCount} symlinks.`,
+    );
+    console.log(
+        `[git-handoff] Omitted ${report.excluded.explicit.total} explicit, ${report.excluded.filterCount} filter, ${report.excluded.profileFilteredCount} profile, ${report.excluded.sensitiveUntrackedCount} sensitive untracked, and ${report.excluded.safetyFilteredUntrackedCount} total safety-filtered untracked paths.`,
+    );
+    if (reportFile) {
+        await mkdir(path.dirname(reportFile), { recursive: true });
+        await Bun.write(reportFile, `${JSON.stringify(report, null, 2)}\n`);
+        console.log(`[git-handoff] Report: ${reportFile}`);
+    }
+};
+
+const validateHandoffArtifactPath = async (
+    rootDir: string,
+    artifactPath: string,
+    label: string,
+): Promise<void> => {
+    const resolvedArtifactPath = path.resolve(artifactPath);
+    const existingStats = await lstat(resolvedArtifactPath).catch(() => null);
+    if (existingStats?.isSymbolicLink()) {
+        throw new Error(`Git handoff refuses a symlink ${label} path: ${resolvedArtifactPath}`);
+    }
+
+    const resolvedParent = await realpath(path.dirname(resolvedArtifactPath)).catch(() =>
+        path.dirname(resolvedArtifactPath),
+    );
+    const canonicalArtifactPath = path.join(resolvedParent, path.basename(resolvedArtifactPath));
+    if (isPathWithin(resolvedArtifactPath, rootDir) || isPathWithin(canonicalArtifactPath, rootDir)) {
+        throw new Error(`Git handoff ${label} must be outside the Git worktree: ${resolvedArtifactPath}`);
+    }
+};
+
+export const runGitHandoff = async ({
+    excludes,
+    filters,
+    outputFile,
+    profile,
+    reportFile,
+    targetDir,
+}: GitHandoffOptions): Promise<void> => {
+    const resolvedProfile = resolveGitHandoffProfile(profile);
+    const rootDir = await resolveGitWorktree(targetDir);
+    const resolvedOutputFile = path.resolve(
+        outputFile ?? path.join(process.cwd(), `${path.basename(rootDir)}-git-handoff.zip`),
+    );
+    const resolvedReportFile = reportFile ? path.resolve(reportFile) : null;
+    if (resolvedReportFile === resolvedOutputFile) {
+        throw new Error('Git handoff output and report paths must be different.');
+    }
+    await validateHandoffArtifactPath(rootDir, resolvedOutputFile, 'output');
+    if (resolvedReportFile) {
+        await validateHandoffArtifactPath(rootDir, resolvedReportFile, 'report');
+    }
+    console.log(`[git-handoff] Git worktree: ${rootDir}`);
+    if (filters.length > 0) {
+        console.log(`[git-handoff] File filters applied: ${filters.join(', ')}`);
+    }
+    if (excludes.length > 0) {
+        console.log(`[git-handoff] Explicit exclusions: ${excludes.join(', ')}`);
+    }
+    if (resolvedProfile) {
+        console.log(`[git-handoff] Profile selected: ${resolvedProfile}`);
+    }
+
+    const selection = await collectGitHandoffSelection(rootDir, filters, excludes, resolvedProfile);
+    console.log(
+        `[git-handoff] Git selected ${selection.gitSelectedCount} paths; ${selection.candidates.length} remain after filters and exclusions.`,
+    );
+
+    const stagingRoot = await mkdtemp(path.join(tmpdir(), 'pack-repo-git-handoff-'));
+    try {
+        const stats = await stageGitHandoffFiles(rootDir, stagingRoot, selection.candidates);
+        const report = makeGitHandoffReport(selection, stats);
+        if (report.included.count === 0) {
+            await emitGitHandoffReport(report, resolvedReportFile);
+            console.warn('[git-handoff] No files matched the requested handoff criteria; ZIP was not created.');
+            return;
+        }
+
+        console.log(`[git-handoff] Creating ZIP at: ${resolvedOutputFile}`);
+        await createZipFile(stagingRoot, resolvedOutputFile, {
+            preserveSymlinks: true,
+            preserveUnixMetadata: true,
+        });
+        await emitGitHandoffReport(report, resolvedReportFile);
+        const zipStats = await stat(resolvedOutputFile);
+        console.log(`[git-handoff] ZIP size: ${zipStats.size} bytes`);
+        console.log(`[git-handoff] Output archive: ${resolvedOutputFile}`);
+    } finally {
+        await rm(stagingRoot, { force: true, recursive: true });
+    }
+};

package/src/git.ts

@@ -0,0 +1,84 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+export type ExternalCommandResult = {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: Uint8Array;
+};
+
+export const runExternalCommand = async (
+    command: string,
+    args: readonly string[],
+    cwd: string,
+): Promise<ExternalCommandResult> => {
+    const processHandle = (() => {
+        try {
+            return Bun.spawn([command, ...args], { cwd, stderr: 'pipe', stdout: 'pipe' } as const);
+        } catch (error) {
+            throw new Error(`Unable to run ${command}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })();
+
+    const stdoutPromise = new Response(processHandle.stdout).arrayBuffer();
+    const stderrPromise = new Response(processHandle.stderr).text();
+    await processHandle.exited;
+    return {
+        exitCode: processHandle.exitCode ?? -1,
+        stderr: await stderrPromise,
+        stdout: new Uint8Array(await stdoutPromise),
+    };
+};
+
+export const requireSuccessfulCommand = (
+    command: string,
+    args: readonly string[],
+    result: ExternalCommandResult,
+): Uint8Array => {
+    if (result.exitCode !== 0) {
+        const detail = result.stderr.trim();
+        throw new Error(`${command} ${args.join(' ')} failed${detail.length > 0 ? `: ${detail}` : ''}`);
+    }
+    return result.stdout;
+};
+
+export const decodeGitPathList = (bytes: Uint8Array): readonly string[] => {
+    let contents: string;
+    try {
+        contents = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch (error) {
+        throw new Error(`Git returned a non-UTF-8 path: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    if (contents.length === 0) {
+        return [];
+    }
+    if (!contents.endsWith('\0')) {
+        throw new Error('Git returned an unterminated path list');
+    }
+    return contents.split('\0').filter((entry) => entry.length > 0);
+};
+
+export const resolveGitWorktree = async (targetDir: string): Promise<string> => {
+    const resolvedTarget = await realpath(path.resolve(targetDir)).catch(() => path.resolve(targetDir));
+    const worktreeResult = await runExternalCommand(
+        'git',
+        ['-C', resolvedTarget, 'rev-parse', '--is-inside-work-tree'],
+        resolvedTarget,
+    );
+    if (worktreeResult.exitCode !== 0) {
+        throw new Error(`Git handoff requires a Git worktree: ${resolvedTarget}`);
+    }
+    const worktreeValue = new TextDecoder().decode(worktreeResult.stdout).trim();
+    if (worktreeValue !== 'true') {
+        throw new Error(`Git handoff requires a Git worktree: ${resolvedTarget}`);
+    }
+
+    const rootArgs = ['-C', resolvedTarget, 'rev-parse', '--show-toplevel'];
+    const rootResult = await runExternalCommand('git', rootArgs, resolvedTarget);
+    const rootOutput = new TextDecoder().decode(requireSuccessfulCommand('git', rootArgs, rootResult)).trim();
+    if (rootOutput.length === 0 || rootOutput.includes('\n') || rootOutput.includes('\0')) {
+        throw new Error(`Git returned an unsafe worktree root for ${resolvedTarget}`);
+    }
+    return await realpath(path.resolve(rootOutput));
+};