@rmyndharis/aimhooman 0.1.1 → 0.1.2

package/src/githooks.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { GIT_TIMEOUT_MS } from './git-environment.mjs';
 import {
     accessSync,
     chmodSync,
@@ -38,13 +39,19 @@ function hooksDir(repo) {
 
     const scope = configScope(repo, 'core.hooksPath');
     const localScope = ['local', 'worktree'].includes(scope);
-    const repositoryOwned = localScope && repositoryOwnsPath(repo, dir);
+    const inside = localScope && repositoryOwnsPath(repo, dir);
+    // Inside the worktree is not the same as ours. A hooks directory Git tracks
+    // (husky, the vanilla .githooks pattern) is repository content: a dispatcher
+    // written there stages this machine's absolute CLI, Node, and PATH for
+    // everyone who clones.
+    const tracked = inside && trackedPath(repo, dir);
+    const repositoryOwned = inside && !tracked;
     const shared = !repositoryOwned || resolve(dir) === resolve(globalHooksDir());
     if (shared) {
         const where = scope ? `${scope} scope` : 'a non-local scope';
-        const reason = localScope && !repositoryOwned
-            ? `${where}, outside this repository`
-            : where;
+        let reason = where;
+        if (tracked) reason = `${where}, tracked by this repository`;
+        else if (localScope && !inside) reason = `${where}, outside this repository`;
         return {
             dir,
             shared: true,
@@ -60,16 +67,43 @@ function hooksDir(repo) {
     };
 }
 
+function pathContains(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
 function repositoryOwnsPath(repo, path) {
     const candidate = canonicalPath(path);
     return [repo.root, repo.commonDir, repo.gitDir]
         .filter(Boolean)
         .map(canonicalPath)
-        .some((root) => {
-            const rel = relative(root, candidate);
-            return rel === '' || (!rel.startsWith(`..${sep}`)
-                && rel !== '..' && !isAbsolute(rel));
-        });
+        .some((root) => pathContains(root, candidate));
+}
+
+// insideGitDir is the part of repositoryOwnsPath that cannot be shared. A .git
+// belongs to exactly one repository, while a directory in the worktree can be
+// the core.hooksPath of a second one.
+function insideGitDir(repo, path) {
+    const candidate = canonicalPath(path);
+    return [repo.commonDir, repo.gitDir]
+        .filter(Boolean)
+        .map(canonicalPath)
+        .some((root) => pathContains(root, candidate));
+}
+
+// trackedPath reports whether Git tracks anything under path. A Git that cannot
+// answer counts as tracked: refusing to install costs a warning, while guessing
+// wrong commits this machine's absolute paths into a shared repository.
+function trackedPath(repo, path) {
+    try {
+        return execFileSync(
+            'git',
+            ['--literal-pathspecs', 'ls-files', '-z', '--', String(path)],
+            { cwd: repo.root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }
+        ).length > 0;
+    } catch {
+        return true;
+    }
 }
 
 function canonicalPath(path) {
@@ -95,13 +129,14 @@ function effectiveHooksDir(repo) {
         return execFileSync(
             'git',
             ['rev-parse', '--path-format=absolute', '--git-path', 'hooks'],
-            { cwd: repo.root, encoding: 'utf8' }
+            { cwd: repo.root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS }
         ).trim();
     } catch {
         try {
             const path = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
                 cwd: repo.root,
                 encoding: 'utf8',
+                timeout: GIT_TIMEOUT_MS,
             }).trim();
             return isAbsolute(path) ? path : resolve(repo.root, path);
         } catch {
@@ -115,6 +150,7 @@ function configScope(repo, key) {
         const line = execFileSync('git', ['config', '--show-scope', '--get', key], {
             cwd: repo.root,
             encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
         }).trim();
         return line.split(/\s/, 1)[0];
     } catch {
@@ -125,6 +161,7 @@ function configScope(repo, key) {
             execFileSync('git', ['config', '--local', '--get', key], {
                 cwd: repo.root,
                 stdio: ['ignore', 'ignore', 'ignore'],
+                timeout: GIT_TIMEOUT_MS,
             });
             return 'local';
         } catch {
@@ -307,7 +344,7 @@ function installHooksLocked(repo, cliPath, options, dir, warnings) {
             continue;
         }
         if (current && ownedHook(readFileSync(dest, 'utf8'), name)
-            && !ownedForChain(readFileSync(dest, 'utf8'), name, chainedPath)) {
+            && !ownedByRepo(repo, dir, readFileSync(dest, 'utf8'), name, chainedPath)) {
             warnings.push(`${name} is managed for another repository; refusing to overwrite it`);
             unsafe = true;
         }
@@ -381,13 +418,18 @@ function uninstallHooksLocked(repo, dir, warnings) {
             const chained = join(chainedDir, name);
             const content = readFileSync(dest, 'utf8');
             if (!ownedHook(content, name)) continue;
-            if (!ownedForChain(content, name, chained)) {
-                warnings.push(`${name} is managed for another repository; refusing to remove it`);
+            if (!ownedByRepo(repo, dir, content, name, chained)) {
+                failures.push(`${name}: managed for another repository; left in place at ${dest}`);
                 continue;
             }
             const predecessor = entry(chained);
             if (predecessor?.isSymbolicLink()) {
-                warnings.push(`${name} chained backup is a symlink; refusing to restore it`);
+                // Never read or copy through the symlink, but do let go of the
+                // dispatcher: holding the repository hostage over a backup we
+                // refuse to touch helps nobody.
+                warnings.push(`${name} chained backup is a symlink; ${chained} left in place and your original hook was not restored`);
+                unlinkSync(dest);
+                removed.push(name);
                 continue;
             }
             if (predecessor) {
@@ -407,6 +449,34 @@ function uninstallHooksLocked(repo, dir, warnings) {
     return { removed: removed.sort(), restored: restored.sort(), warnings, failures };
 }
 
+// remainingDispatchers lists aimhooman dispatchers a local uninstall was meant
+// to remove and did not. uninstall checks the directory rather than trusting its
+// own report: a refusal that only produced a warning would otherwise be printed
+// under a success headline, and "uninstalled" while four dispatchers still block
+// every commit is the one lie a guard must never tell.
+//
+// A shared hooks directory is skipped because uninstallHooks does not touch one
+// either — the global directory has `uninstall --global`, and a foreign or
+// tracked one is reported by its own warning. This asks hooksDir rather than
+// comparing paths: two spellings of one directory differ on Windows, and
+// deciding ownership by string is the bug this change exists to remove.
+export function remainingDispatchers(repo) {
+    const { dir, shared } = hooksDir(repo);
+    if (shared) return [];
+    return Object.keys(MANAGED).sort().flatMap((name) => {
+        const path = join(dir, name);
+        try {
+            const stat = entry(path);
+            if (!stat || stat.isSymbolicLink()) return [];
+            return ownedHook(readFileSync(path, 'utf8'), name) ? [path] : [];
+        } catch {
+            // Unreadable: cannot prove it is gone, so report it rather than
+            // claim a clean removal.
+            return [path];
+        }
+    });
+}
+
 // hookDiagnostics reports both dispatcher integrity and whether its configured
 // command can be reached from the current environment.
 export function hookDiagnostics(repo) {
@@ -414,8 +484,12 @@ export function hookDiagnostics(repo) {
     // Global hooks (installGlobalHooks) keep chained backups in the hooks dir
     // itself; local hooks keep them in repo state via chainDir. Diagnose the
     // path the dispatcher actually embeds, not the repo-relative default.
+    // canonicalPath, not resolve: a HOME behind a symlink (Fedora Silverblue
+    // ships /home -> /var/home; NFS and autofs homes are everywhere) makes the
+    // two spellings differ, and every global dispatcher would then be diagnosed
+    // as belonging to another repository.
     const globalDir = globalHooksDir();
-    const chained = resolve(dir) === resolve(globalDir)
+    const chained = canonicalPath(dir) === canonicalPath(globalDir)
         ? join(globalDir, 'chained')
         : chainDir(repo);
     return Object.keys(MANAGED).sort().map((name) => {
@@ -458,7 +532,7 @@ export function hookDiagnostics(repo) {
                 reason: inspected.reason,
             };
         }
-        if (!ownedForChain(content, name, base.chainedPath)) {
+        if (!ownedByRepo(repo, dir, content, name, base.chainedPath)) {
             return {
                 ...base,
                 managed: false,
@@ -580,8 +654,20 @@ AIMHOOMAN_CLI=${shq(resolvedCliPath)}
 AIMHOOMAN_NODE=${shq(nodePath)}
 AIMHOOMAN_PATH=${shq(shellPathValue)}
 ${captureTree}${captureTransaction}run_aimhooman() {
-  if [ ! -f "$AIMHOOMAN_CLI" ] || [ ! -f "$AIMHOOMAN_NODE" ]; then
-    echo "aimhooman: guard unavailable (aimhooman CLI or Node is missing); allowing this operation without protection. Reinstall aimhooman or remove the managed hooks." >&2
+  if [ ! -f "$AIMHOOMAN_CLI" ]; then
+    echo "aimhooman: guard unavailable (aimhooman CLI is missing); allowing this operation without protection. Reinstall aimhooman or remove the managed hooks." >&2
+    return 0
+  fi
+  if [ ! -f "$AIMHOOMAN_NODE" ]; then
+    # Both remedies below are Node programs, so stopping is only fair when a Node
+    # exists to run them with. Without one the CLI file is inert: 'init' and
+    # 'uninstall' cannot run, and refusing would leave the repository unusable
+    # with no way to remove these hooks except deleting them by hand.
+    if command -v node >/dev/null 2>&1; then
+      echo "aimhooman: the pinned Node interpreter is missing (\$AIMHOOMAN_NODE); the operation was stopped. Run 'aimhooman init' to re-pin it, or 'aimhooman uninstall' to remove the guard." >&2
+      return 20
+    fi
+    echo "aimhooman: guard unavailable (no Node interpreter found); allowing this operation without protection. Install Node and run 'aimhooman init' to restore the guard." >&2
     return 0
   fi
   (
@@ -698,8 +784,16 @@ function ownedHook(content, name) {
     return inspected.valid || legacyHook(content, name);
 }
 
-function ownedForChain(content, name, chainedPath) {
+// ownedByRepo decides whether this repository may rewrite or remove a dispatcher.
+// Inside our own .git the fingerprint settles it: we wrote the file, and no
+// second repository can own anything there. The baked chained path only earns a
+// vote where the hooks directory can genuinely be shared — two repositories may
+// point core.hooksPath at one directory, and then it is the only way to tell the
+// installs apart. Comparing paths everywhere means a renamed repository stops
+// recognising the guard it installed itself, with no way to re-pin or remove it.
+function ownedByRepo(repo, dir, content, name, chainedPath) {
     if (!ownedHook(content, name)) return false;
+    if (insideGitDir(repo, dir)) return true;
     return assignmentValue(content, 'CHAINED') === String(chainedPath);
 }
 

package/src/gitx.mjs

@@ -12,21 +12,8 @@ import {
     rmSync,
     symlinkSync,
 } from 'node:fs';
-import { createHash, randomUUID } from 'node:crypto';
 import { isAbsolute, join } from 'node:path';
-import { gitEnvironment } from './git-environment.mjs';
-
-export class StateMigrationError extends Error {
-    constructor(detail, { stateDir, legacyStateDirs = [], diagnostics = [], cause } = {}) {
-        super(`repository state: ${detail}`);
-        this.name = 'StateMigrationError';
-        this.stateDir = stateDir;
-        this.legacyStateDirs = legacyStateDirs;
-        this.stateDiagnostics = diagnostics;
-        this.diagnostics = diagnostics;
-        if (cause) this.cause = cause;
-    }
-}
+import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 
 export class GitRevisionError extends Error {
     constructor(revision, detail, cause) {
@@ -53,6 +40,7 @@ function gitBuf(args, cwd, input) {
         env: gitEnvironment(),
         encoding: 'buffer',
         maxBuffer: 64 * 1024 * 1024,
+        timeout: GIT_TIMEOUT_MS,
         // Capture stderr into the thrown error (pipe) instead of letting git's
         // raw stderr leak to the user's terminal alongside aimhooman's own
         // diagnostics; stdin is ignored unless input is supplied.
@@ -162,257 +150,17 @@ export function openRepo(cwd = process.cwd()) {
     const gitDir = gitStr(['rev-parse', '--absolute-git-dir'], root);
     let commonDir = gitStr(['rev-parse', '--git-common-dir'], root);
     if (!isAbsolute(commonDir)) commonDir = join(root, commonDir);
-    const state = prepareSharedState(commonDir, gitDir);
     return {
         root,
         gitDir,
         commonDir,
-        stateDir: state.stateDir,
-        legacyStateDirs: state.legacyStateDirs,
-        stateDiagnostics: state.diagnostics,
+        // Shared by linked worktrees, which is why it hangs off commonDir rather
+        // than gitDir. Every released version has written here.
+        stateDir: join(commonDir, 'aimhooman'),
         excludeFile: join(commonDir, 'info', 'exclude'),
     };
 }
 
-function prepareSharedState(commonDir, gitDir) {
-    const stateDir = join(commonDir, 'aimhooman');
-    const legacyStateDirs = findLegacyStateDirs(commonDir, gitDir, stateDir);
-    const diagnostics = [];
-    if (!legacyStateDirs.length) return { stateDir, legacyStateDirs, diagnostics };
-
-    const currentExists = pathExists(stateDir);
-    let fingerprints;
-    try {
-        fingerprints = legacyStateDirs.map((path) => ({ path, fingerprint: stateFingerprint(path) }));
-        if (currentExists) {
-            const currentFingerprint = stateFingerprint(stateDir);
-            const conflicts = fingerprints.filter((entry) => entry.fingerprint !== currentFingerprint);
-            if (conflicts.length) {
-                throw stateConflict(stateDir, legacyStateDirs, conflicts.map((entry) => entry.path));
-            }
-            archiveLegacyStates(fingerprints, stateDir, diagnostics);
-            return { stateDir, legacyStateDirs, diagnostics };
-        }
-
-        const first = fingerprints[0];
-        const conflicts = fingerprints.filter((entry) => entry.fingerprint !== first.fingerprint);
-        if (conflicts.length) {
-            throw stateConflict(stateDir, legacyStateDirs, conflicts.map((entry) => entry.path));
-        }
-        try {
-            copyStateAtomically(first.path, stateDir, first.fingerprint);
-        } catch (error) {
-            if (!pathExists(stateDir)) throw error;
-            const currentFingerprint = stateFingerprint(stateDir);
-            const conflicts = fingerprints.filter((entry) => entry.fingerprint !== currentFingerprint);
-            if (conflicts.length) {
-                throw stateConflict(stateDir, legacyStateDirs, conflicts.map((entry) => entry.path));
-            }
-            diagnostics.push({
-                level: 'info',
-                code: 'legacy-state-migrated-concurrently',
-                path: first.path,
-                stateDir,
-                message: `shared state at "${stateDir}" was created by another process`,
-            });
-            archiveLegacyStates(fingerprints, stateDir, diagnostics);
-            return { stateDir, legacyStateDirs, diagnostics };
-        }
-        diagnostics.push({
-            level: 'info',
-            code: 'legacy-state-migrated',
-            path: first.path,
-            stateDir,
-            message: `copied legacy state from "${first.path}" to shared state "${stateDir}"`,
-        });
-        archiveLegacyStates(fingerprints, stateDir, diagnostics);
-        return { stateDir, legacyStateDirs, diagnostics };
-    } catch (error) {
-        if (error instanceof StateMigrationError) throw error;
-        throw new StateMigrationError(`cannot inspect or migrate legacy state: ${error.message}`, {
-            stateDir,
-            legacyStateDirs,
-            diagnostics,
-            cause: error,
-        });
-    }
-}
-
-function findLegacyStateDirs(commonDir, gitDir, stateDir) {
-    const found = new Set();
-    const adminDir = join(commonDir, 'worktrees');
-    let entries = [];
-    try {
-        entries = readdirSync(adminDir, { withFileTypes: true });
-    } catch (error) {
-        if (error?.code !== 'ENOENT') {
-            throw new StateMigrationError(`cannot list linked worktrees: ${error.message}`, {
-                stateDir,
-                cause: error,
-            });
-        }
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const candidate = join(adminDir, entry.name, 'aimhooman');
-        if (pathExists(candidate) && !isCompatibilityLink(candidate, stateDir)) found.add(candidate);
-    }
-    const currentLegacy = join(gitDir, 'aimhooman');
-    if (currentLegacy !== stateDir
-        && pathExists(currentLegacy)
-        && !isCompatibilityLink(currentLegacy, stateDir)) {
-        found.add(currentLegacy);
-    }
-    return [...found].sort();
-}
-
-function isCompatibilityLink(path, stateDir) {
-    try {
-        if (!lstatSync(path).isSymbolicLink()) return false;
-        return realpathSync(path) === realpathSync(stateDir);
-    } catch (error) {
-        if (error?.code === 'ENOENT') return false;
-        throw error;
-    }
-}
-
-function pathExists(path) {
-    try {
-        lstatSync(path);
-        return true;
-    } catch (error) {
-        if (error?.code === 'ENOENT') return false;
-        throw error;
-    }
-}
-
-function stateFingerprint(root) {
-    const hash = createHash('sha256');
-    function visit(path, relative) {
-        const stat = lstatSync(path);
-        hash.update(relative);
-        hash.update('\0');
-        hash.update(String(stat.mode & 0o777));
-        hash.update('\0');
-        if (stat.isDirectory()) {
-            hash.update('directory\0');
-            for (const name of readdirSync(path).sort()) {
-                visit(join(path, name), relative ? join(relative, name) : name);
-            }
-            return;
-        }
-        if (stat.isFile()) {
-            hash.update('file\0');
-            hash.update(readFileSync(path));
-            hash.update('\0');
-            return;
-        }
-        if (stat.isSymbolicLink()) {
-            hash.update('symlink\0');
-            hash.update(readlinkSync(path));
-            hash.update('\0');
-            return;
-        }
-        throw new Error(`unsupported state entry "${path}"`);
-    }
-    visit(root, '');
-    return hash.digest('hex');
-}
-
-function copyStateAtomically(source, destination, expectedFingerprint) {
-    const temporary = `${destination}.migrate-${process.pid}-${randomUUID()}`;
-    try {
-        cpSync(source, temporary, {
-            recursive: true,
-            dereference: false,
-            errorOnExist: true,
-            force: false,
-            preserveTimestamps: true,
-        });
-        if (stateFingerprint(temporary) !== expectedFingerprint) {
-            throw new Error(`legacy state changed while it was copied from "${source}"`);
-        }
-        renameSync(temporary, destination);
-    } catch (error) {
-        try {
-            rmSync(temporary, { recursive: true, force: true });
-        } catch {
-            // Keep the migration error when cleanup is unavailable.
-        }
-        throw error;
-    }
-}
-
-export function archiveLegacyStates(entries, stateDir, diagnostics) {
-    for (const entry of entries) {
-        // A concurrent process may have already archived this legacy state and
-        // replaced entry.path with a compatibility symlink to stateDir. Renaming
-        // that symlink would then fingerprint stateDir (mismatching the legacy
-        // fingerprint taken before the race) and spuriously fail migration. Treat
-        // an already-symlinked entry as archived-concurrently and move on.
-        if (isCompatibilityLink(entry.path, stateDir)) {
-            diagnostics.push({
-                level: 'info',
-                code: 'legacy-state-archived-concurrently',
-                path: entry.path,
-                stateDir,
-                message: `legacy state at "${entry.path}" was archived by another process`,
-            });
-            continue;
-        }
-        const archivedPath = `${entry.path}.migrated-${randomUUID()}`;
-        let renamed = false;
-        try {
-            renameSync(entry.path, archivedPath);
-            renamed = true;
-            if (stateFingerprint(archivedPath) !== entry.fingerprint) {
-                throw new Error(`legacy state changed while it was archived from "${entry.path}"`);
-            }
-            symlinkSync(stateDir, entry.path, process.platform === 'win32' ? 'junction' : 'dir');
-        } catch (error) {
-            if (!renamed && error?.code === 'ENOENT' && !pathExists(entry.path)) {
-                diagnostics.push({
-                    level: 'info',
-                    code: 'legacy-state-archived-concurrently',
-                    path: entry.path,
-                    stateDir,
-                    message: `legacy state at "${entry.path}" was archived by another process`,
-                });
-                continue;
-            }
-            try {
-                if (isCompatibilityLink(entry.path, stateDir)) rmSync(entry.path, { force: true });
-                if (!pathExists(entry.path) && pathExists(archivedPath)) renameSync(archivedPath, entry.path);
-            } catch {
-                // Keep the migration error; both locations are named in it.
-            }
-            throw error;
-        }
-        diagnostics.push({
-            level: 'info',
-            code: 'legacy-state-archived',
-            path: entry.path,
-            archivedPath,
-            stateDir,
-            message: `archived legacy state at "${archivedPath}" and linked its old path to "${stateDir}"`,
-        });
-    }
-}
-
-function stateConflict(stateDir, legacyStateDirs, conflictingPaths) {
-    const diagnostics = conflictingPaths.map((path) => ({
-        level: 'error',
-        code: 'legacy-state-conflict',
-        path,
-        stateDir,
-        message: `legacy state at "${path}" conflicts with another per-clone state`,
-    }));
-    return new StateMigrationError(
-        `conflicting legacy state found; select which state to keep at "${stateDir}"`,
-        { stateDir, legacyStateDirs, diagnostics },
-    );
-}
-
 // stagedEntries snapshots index changes, including deletion metadata. Rename
 // and copy entries use the destination path; object IDs keep blob reads stable.
 export function stagedEntries(repo) {
@@ -636,21 +384,40 @@ export function withIndexFromTree(repo, treeOid, fn) {
     }
 }
 
-// introducedCommits returns each commit added by a proposed branch update,
-// independent of reachability through other refs. Using `--not --all` here
-// would let an ignored tag/remote ref pre-poison reachability and suppress the
-// final scan. A newly created branch has no trusted old tip, so its full ancestry
-// is checked; ordinary updates scan exactly old..new.
+// gatedTips lists the local branch tips this guard has already cleared. Only
+// refs/heads/* qualifies, because it is the only namespace cmdRefcheck gates;
+// the refs under review are excluded, since Git already publishes them at the
+// `committed` phase and a ref must never serve as its own proof.
+function gatedTips(repo, reviewing) {
+    return gitBuf(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads/'], repo.root)
+        .toString('utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => line.split(' '))
+        .filter(([name, oid]) => name && oid && !reviewing.has(name))
+        .map(([, oid]) => oid);
+}
+
+// introducedCommits returns each commit added by a proposed branch update.
+// Reachability through refs/heads/* is trusted because those commits passed this
+// same guard when their branch was written; every other namespace is not. Using
+// `--not --all` would let an ignored tag or remote ref pre-poison reachability
+// and suppress the scan, so tips come from refs/heads/* alone. A newly created
+// branch is measured against those tips instead of its full ancestry, which
+// would otherwise rescan the entire repository on every `git checkout -b`;
+// ordinary updates scan exactly old..new.
 export function introducedCommits(repo, updates) {
     const commits = [];
     const seen = new Set();
+    const reviewing = new Set(updates.map((update) => update?.ref).filter(Boolean));
+    const gated = gatedTips(repo, reviewing);
     for (const update of updates) {
         const oldObjectId = update?.oldObjectId;
         const newObjectId = update?.newObjectId;
         assertOid(oldObjectId);
         assertOid(newObjectId);
         const revisions = /^0+$/.test(oldObjectId)
-            ? [newObjectId]
+            ? [newObjectId, ...(gated.length ? ['--not', ...gated] : [])]
             : [newObjectId, `^${oldObjectId}`];
         const resolved = gitBuf(['rev-list', '--reverse', ...revisions], repo.root)
             .toString('utf8')
@@ -686,12 +453,28 @@ export function unstagePaths(repo, paths) {
         cwd: repo.root,
         env: gitEnvironment(),
         input: pathspecs,
+        timeout: GIT_TIMEOUT_MS,
         stdio: ['pipe', 'ignore', 'pipe'],
     };
     let hasHead = true;
     try {
-        execFileSync('git', ['rev-parse', '--verify', 'HEAD'], opts);
-    } catch {
+        // Deliberately not `opts`: rev-parse never reads stdin, so feeding it the
+        // pathspec makes git exit before draining the pipe, and a pathspec over the
+        // ~64 KiB pipe buffer fails the write with EPIPE. That read as "no HEAD" and
+        // sent a repository that has one down the `rm --cached` branch, staging the
+        // deletion of every tracked path this was asked to restore.
+        execFileSync('git', ['rev-parse', '--verify', 'HEAD'], {
+            cwd: repo.root,
+            env: gitEnvironment(),
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+    } catch (error) {
+        // Only git's own verdict may select the branch. An unborn HEAD exits 128;
+        // a timeout or a missing git carries no exit status, and guessing "no HEAD"
+        // there would delete instead of restore. Fail closed and let the caller stop
+        // the commit rather than silently rewrite the index.
+        if (typeof error?.status !== 'number') throw error;
         hasHead = false;
     }
     if (hasHead) {

package/src/history-scan.mjs

@@ -2,7 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { GitRevisionError } from './gitx.mjs';
-import { gitEnvironment } from './git-environment.mjs';
+import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 
 export const EMPTY_HISTORY_OID = '0'.repeat(40);
 
@@ -12,6 +12,7 @@ function gitBuffer(repo, args, input) {
         env: gitEnvironment(),
         encoding: 'buffer',
         maxBuffer: 128 * 1024 * 1024,
+        timeout: GIT_TIMEOUT_MS,
         ...(input === undefined ? {} : { input }),
     });
 }
@@ -26,6 +27,7 @@ function gitStringQuiet(repo, args) {
         env: gitEnvironment(),
         encoding: 'utf8',
         maxBuffer: 128 * 1024 * 1024,
+        timeout: GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
 }
@@ -223,6 +225,7 @@ function isAncestor(repo, ancestor, descendant) {
             cwd: repo.root,
             env: gitEnvironment(),
             stdio: ['ignore', 'ignore', 'pipe'],
+            timeout: GIT_TIMEOUT_MS,
         });
         return true;
     } catch (error) {