@nathapp/nax-agent 0.1.0

package/dist/internal/file-lock.js

@@ -0,0 +1,212 @@
+/**
+ * Shared single-file lock used by `withPathFileLock` and `withQueueFileLock`.
+ *
+ * Mutual exclusion derives from the atomicity of an exclusive create: the
+ * lock is ONE file at `<target>.lock`, and the writer whose
+ * `writeFile(path, pid, { flag: "wx" })` succeeds holds the lock. There is
+ * no candidate ordering, no filesystem birthtime, and no polling race.
+ *
+ * #1731: the previous design created timestamped candidate files and polled
+ * until it saw itself as the "oldest live" candidate. That protocol is only
+ * sound if candidate order matches creation order, which it did not: the
+ * sort key was `(stat().birthtimeMs, name.localeCompare)` — on Linux CI
+ * filesystems birthtimeMs is degenerate so order collapsed to the random
+ * uuid tail of the name, and a poll whose readdir completed before a
+ * competitor's create landed missed that competitor entirely. A
+ * later-created candidate could therefore sort before the holder, also
+ * conclude it was oldest, and enter — two writers inside the critical
+ * section, one write silently lost. An exclusive create cannot exhibit any
+ * of those failure modes: exactly one create ever succeeds.
+ *
+ * Staleness (BUG-10 / BUG-25, carried over from the candidate design):
+ * - The holder's pid is stored in the lock file. A waiter that loses the
+ *   create race reads the pid; a PROVEN-dead holder (ESRCH) means the lock
+ *   is abandoned and may be reclaimed.
+ * - Content that cannot be parsed (e.g. the creator crashed between the
+ *   create and the pid write) is respected until it ages past
+ *   `EMPTY_LOCK_EVICT_AGE_MS` — a live holder writes its pid within the
+ *   same tick as the create, so old unparseable content proves abandonment.
+ *   Inconclusive liveness fails closed: the waiter times out and throws
+ *   rather than entering over a possible holder.
+ *
+ * Reclamation is serialized by a claim file (`<target>.lock.claim`), whose
+ * exclusive create elects a single "gravedigger" at a time. This closes the
+ * steal race: without it, two waiters that both observed the dead holder
+ * could interleave (stealer A's create landing between stealer B's
+ * re-verification and its unlink), letting B unlink A's fresh live lock and
+ * enter over it. Under the claim:
+ * - Only the claim holder may unlink the lock file, so no unlink can make
+ *   the path absent during another gravedigger's verify→unlink window.
+ * - The gravedigger RE-VERIFIES abandonment after winning the claim (a
+ *   stale observation must not kill a lock that a new live holder has
+ *   since created) and only then unlinks.
+ * - If two gravediggers ever do overlap (only possible via the claim's own
+ *   age-based steal), both re-verify the same dead file, both unlink (the
+ *   second gets ENOENT), and the exclusive create on the fixed lock path
+ *   still admits exactly one holder.
+ * The claim itself is held for microseconds, so it is stolen purely on age
+ * (`CLAIM_MAX_AGE_MS`): a claim older than that proves its gravedigger died
+ * mid-reclaim. A crashed gravedigger otherwise pauses reclamation until
+ * then — fail closed, never fail into someone else's live lock.
+ *
+ * Release unlinks the lock file in the `finally` block. The unlink is
+ * swallowed because release runs from the same process that created the
+ * file — a double-cleanup on retry paths must not throw. A crashed holder
+ * leaks the file, which the dead-pid reclamation above reclaims.
+ *
+ * Mixed versions: the pre-#1731 design wrote `<target>.lock.<time>.<pid>.<uuid>`
+ * candidate files, which this design deliberately does NOT scan for — they
+ * are inert leftovers here (and legacy candidate files are never GC'd). An
+ * old-version process and a new-version process must therefore not run
+ * concurrently against the same target during a one-release transition
+ * window: each would see only its own lock format and could enter
+ * concurrently. This self-heals once old-version processes exit.
+ */
+import { readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { NaxError } from "#src/infra/index";
+import { isProcessAlive } from "./process-alive.js";
+const DEFAULT_RETRY_MS = 10;
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * A live holder writes its pid within the same tick as the create, so
+ * unparseable content older than this bound proves the creator died
+ * between creating the file and writing its pid (crash, kill -9).
+ */
+const EMPTY_LOCK_EVICT_AGE_MS = 10_000;
+/**
+ * A gravedigger holds the claim file for microseconds (verify + one
+ * unlink). A claim older than this bound proves its process died before
+ * releasing it. Kept comfortably above any scheduling delay a live
+ * reclaim could take.
+ */
+const CLAIM_MAX_AGE_MS = 10_000;
+export const _fileLockDeps = {
+    writeFile,
+    readFile,
+    stat,
+    unlink,
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    isPidAlive: isProcessAlive,
+};
+function unlinkQuiet(path) {
+    return _fileLockDeps.unlink(path).catch(() => { });
+}
+async function tryCreateExclusive(path) {
+    try {
+        await _fileLockDeps.writeFile(path, `${process.pid}\n`, { flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        // Any other create failure (EACCES, ENOSPC, …) is environmental, not
+        // contention — fail fast instead of burning the whole timeout as a
+        // misleading "Timed out".
+        throw error;
+    }
+}
+async function readHolderPid(path) {
+    // ENOENT/EACCES on read and empty/garbage content are deliberately
+    // conflated: both mean "no judgable holder", and both fall to the
+    // age-based reclamation bound (BUG-25 conservative rule).
+    const raw = await _fileLockDeps.readFile(path, "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+async function ageMs(path) {
+    const stats = await _fileLockDeps.stat(path).catch(() => null);
+    return stats ? _fileLockDeps.now() - stats.mtimeMs : null;
+}
+/**
+ * Judge whether the lock at `path` is provably abandoned: its holder pid is
+ * dead, or its content is unparseable and older than the empty-lock bound.
+ * Returns the observed pid (null when unparseable) so the reclamation step
+ * can detect a changed file before unlinking.
+ */
+async function judgeAbandoned(path) {
+    const pid = await readHolderPid(path);
+    if (pid !== null)
+        return { abandoned: !_fileLockDeps.isPidAlive(pid), observedPid: pid };
+    const age = await ageMs(path);
+    return { abandoned: age !== null && age >= EMPTY_LOCK_EVICT_AGE_MS, observedPid: null };
+}
+/**
+ * Elect one gravedigger via the claim file's exclusive create. A fresh
+ * claim held by someone else means reclamation is already in progress —
+ * back off. An aged claim proves its gravedigger died mid-reclaim and is
+ * stolen (age-based, so no content check is needed: a live gravedigger
+ * releases within microseconds).
+ */
+async function tryClaim(claimPath) {
+    if (await tryCreateExclusive(claimPath))
+        return true;
+    const age = await ageMs(claimPath);
+    if (age === null || age < CLAIM_MAX_AGE_MS)
+        return false;
+    await unlinkQuiet(claimPath);
+    return tryCreateExclusive(claimPath);
+}
+/**
+ * Reclaim `path` if it is STILL the abandoned lock that was observed — the
+ * observation can be stale (a new live holder may have been created since,
+ * or another gravedigger may have already removed the file). Runs under
+ * the claim, so no concurrent unlink can make the path flip between absent
+ * and present during this verification.
+ */
+async function reclaimIfStillAbandoned(path, observedPid) {
+    const pid = await readHolderPid(path);
+    if (pid !== null) {
+        if (pid === observedPid && !_fileLockDeps.isPidAlive(pid))
+            await unlinkQuiet(path);
+        return;
+    }
+    if (observedPid !== null)
+        return;
+    const age = await ageMs(path);
+    if (age !== null && age >= EMPTY_LOCK_EVICT_AGE_MS)
+        await unlinkQuiet(path);
+}
+async function acquire(lockPath, options) {
+    const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+    const deadline = _fileLockDeps.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const claimPath = `${lockPath}.claim`;
+    for (;;) {
+        if (await tryCreateExclusive(lockPath)) {
+            return () => unlinkQuiet(lockPath);
+        }
+        if (_fileLockDeps.now() >= deadline)
+            break;
+        const { abandoned, observedPid } = await judgeAbandoned(lockPath);
+        if (abandoned && (await tryClaim(claimPath))) {
+            try {
+                await reclaimIfStillAbandoned(lockPath, observedPid);
+            }
+            finally {
+                await unlinkQuiet(claimPath);
+            }
+        }
+        await _fileLockDeps.sleep(retryMs);
+    }
+    throw new NaxError(`${options.errorPrefix} Timed out acquiring ${options.lockName} lock: ${lockPath}`, "FILE_LOCK_TIMEOUT", {
+        stage: "file-lock",
+        lockName: options.lockName,
+        lockPath,
+    });
+}
+/**
+ * Serialize `operation` against any other process holding the lock at
+ * `lockPath`. See the module doc for the acquisition, staleness, and
+ * release semantics.
+ */
+export async function withFileLock(lockPath, operation, options) {
+    const release = await acquire(lockPath, options);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}

package/dist/internal/file-size.d.ts

@@ -0,0 +1,2 @@
+/** Preserve missing-file size probes without suppressing other I/O errors. */
+export declare function fileSizeOrZero(path: string): number;

package/dist/internal/file-size.js

@@ -0,0 +1,12 @@
+import { statSync } from "node:fs";
+/** Preserve missing-file size probes without suppressing other I/O errors. */
+export function fileSizeOrZero(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+}

package/dist/internal/git-add.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `git add` that never makes git recurse into a gitlink (#2210).
+ *
+ * For every gitlink (submodule entry) in the index, `git add` runs
+ * `git status` inside the nested repository to learn whether it is dirty,
+ * and that child git reads the nested repo's own `.git/config` and
+ * `.gitattributes`. A nested repo the agent created inside the sandbox write
+ * root can name a filter driver there (`filter.<x>.clean`), which nax's
+ * unsandboxed `git add` would then run. `add` ignores `diff.ignoreSubmodules`
+ * (it overrides submodule config), so the env hardening in `./git-env` cannot
+ * reach it. Instead, gitlinks are excluded from the `add` pathspec and
+ * restaged with `git update-index`, which records the nested HEAD without
+ * spawning git inside it. The staged result is the same as a plain `git add`.
+ *
+ * `git commit` with nothing staged prints a status, and that status honours a
+ * `submodule.<name>.ignore` from `.gitmodules` -- so it can recurse too. The
+ * commit sites therefore ask `hasStagedChanges` first and never run a commit
+ * that would only report "nothing to commit".
+ */
+export interface GitRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+}
+/** `gitWithTimeout`'s shape; injected so this module does not import `./git` (which imports it). */
+export type GitRunner = (args: string[], cwd: string, timeoutMs?: number) => Promise<GitRunResult>;
+export interface GitlinkSafeAddOptions {
+    /** Flags placed before `--`, e.g. `["-A"]`. */
+    readonly flags?: readonly string[];
+    /** Pathspecs to stage; empty means the whole tree (`:/`), as a bare `git add -A` does. */
+    readonly pathspecs?: readonly string[];
+    readonly timeoutMs?: number;
+}
+/** Gitlink paths from `git ls-files --stage -z` output (paths as git printed them: relative to its cwd). */
+export declare function parseGitlinks(lsFilesStageZ: string): string[];
+export declare function gitlinkSafeAdd(git: GitRunner, cwd: string, opts: GitlinkSafeAddOptions): Promise<GitRunResult>;
+/**
+ * Whether the index differs from HEAD: `diff --cached` compares index to HEAD
+ * only, so it never looks at the worktree or inside a gitlink. Undefined when
+ * git could not answer (fail closed: callers do not commit).
+ */
+export declare function hasStagedChanges(git: GitRunner, cwd: string, timeoutMs?: number): Promise<boolean | undefined>;

package/dist/internal/git-add.js

@@ -0,0 +1,59 @@
+/**
+ * `git add` that never makes git recurse into a gitlink (#2210).
+ *
+ * For every gitlink (submodule entry) in the index, `git add` runs
+ * `git status` inside the nested repository to learn whether it is dirty,
+ * and that child git reads the nested repo's own `.git/config` and
+ * `.gitattributes`. A nested repo the agent created inside the sandbox write
+ * root can name a filter driver there (`filter.<x>.clean`), which nax's
+ * unsandboxed `git add` would then run. `add` ignores `diff.ignoreSubmodules`
+ * (it overrides submodule config), so the env hardening in `./git-env` cannot
+ * reach it. Instead, gitlinks are excluded from the `add` pathspec and
+ * restaged with `git update-index`, which records the nested HEAD without
+ * spawning git inside it. The staged result is the same as a plain `git add`.
+ *
+ * `git commit` with nothing staged prints a status, and that status honours a
+ * `submodule.<name>.ignore` from `.gitmodules` -- so it can recurse too. The
+ * commit sites therefore ask `hasStagedChanges` first and never run a commit
+ * that would only report "nothing to commit".
+ */
+const GITLINK_MODE = "160000";
+const WHOLE_TREE_PATHSPEC = ":/";
+/** Gitlink paths from `git ls-files --stage -z` output (paths as git printed them: relative to its cwd). */
+export function parseGitlinks(lsFilesStageZ) {
+    const paths = lsFilesStageZ.split("\0").flatMap((record) => {
+        const tab = record.indexOf("\t");
+        if (tab < 0 || !record.startsWith(`${GITLINK_MODE} `))
+            return [];
+        return [record.slice(tab + 1)];
+    });
+    // An unmerged gitlink has one entry per stage.
+    return [...new Set(paths)];
+}
+export async function gitlinkSafeAdd(git, cwd, opts) {
+    const pathspecs = opts.pathspecs !== undefined && opts.pathspecs.length > 0 ? opts.pathspecs : [WHOLE_TREE_PATHSPEC];
+    const listed = await git(["ls-files", "--stage", "-z", "--", ...pathspecs], cwd, opts.timeoutMs);
+    if (listed.exitCode !== 0 || listed.timedOut) {
+        // Fail closed: staging without knowing the gitlinks would recurse into them.
+        return { ...listed, exitCode: listed.exitCode === 0 ? 1 : listed.exitCode };
+    }
+    const gitlinks = parseGitlinks(listed.stdout);
+    const excludes = gitlinks.map((p) => `:(exclude,literal)${p}`);
+    const added = await git(["add", ...(opts.flags ?? []), "--", ...pathspecs, ...excludes], cwd, opts.timeoutMs);
+    if (added.exitCode !== 0 || gitlinks.length === 0)
+        return added;
+    return git(["update-index", "--add", "--remove", "--", ...gitlinks], cwd, opts.timeoutMs);
+}
+/**
+ * Whether the index differs from HEAD: `diff --cached` compares index to HEAD
+ * only, so it never looks at the worktree or inside a gitlink. Undefined when
+ * git could not answer (fail closed: callers do not commit).
+ */
+export async function hasStagedChanges(git, cwd, timeoutMs) {
+    const r = await git(["diff", "--cached", "--quiet"], cwd, timeoutMs);
+    if (r.timedOut)
+        return undefined;
+    if (r.exitCode === 0)
+        return false;
+    return r.exitCode === 1 ? true : undefined;
+}

package/dist/internal/git-env.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Config overrides every nax-spawned git carries (#2198, defence in depth).
+ *
+ * `core.fsmonitor` names a program git runs on every status/diff/add; were an
+ * agent ever to get a value into a config nax's git reads (a redirected
+ * commondir, a nested repo git recurses into), nax would run it unsandboxed.
+ * nax never needs an fsmonitor, so it is always off.
+ *
+ * Submodules (#2210): for every gitlink, `git status` / `diff` / `commit`
+ * run `git status` inside the nested repo to learn whether it is dirty, and
+ * that child git reads the nested repo's own config and `.gitattributes` --
+ * files an agent can write when it creates the repo inside its write root.
+ * A filter driver (`filter.<x>.clean`) named there would run unsandboxed, and
+ * unlike fsmonitor it cannot be switched off by name. `diff.ignoreSubmodules
+ * =dirty` skips that dirty check (a moved gitlink HEAD is still reported,
+ * without spawning git in it), and `submodule.recurse=false` keeps checkout /
+ * merge from recursing. Config is only a default, though: a
+ * `submodule.<name>.ignore` in the agent-writable `.gitmodules` overrides it,
+ * so status / diff also get `--ignore-submodules=dirty` on the command line
+ * (`hardenedGitArgv`), the one form that beats `.gitmodules`. `git add`
+ * ignores both, so nax stages through `gitlinkSafeAdd` (`./git-add`), which
+ * also refuses to run a commit that would only print status.
+ *
+ * Passed through GIT_CONFIG_COUNT/KEY/VALUE (git >= 2.31; older git ignores
+ * them) rather than `-c` so argv stays unchanged, and because git forwards
+ * these to the child git processes it spawns (submodules) as well.
+ *
+ * Coverage: `gitWithTimeout` applies it, and every other site in `src/` that
+ * spawns git itself passes `env: gitSpawnEnv(...)`. The generic forge and
+ * auto-pr runners harden every command they spawn, since `gh` / `glab` run git
+ * underneath. `packages/repo-tooling/scripts/check-git-spawn-env.ts` (in `lint:checks`) fails on a
+ * `["git", ...]` argv literal that is neither inside a spawn call carrying one
+ * of these helpers nor marked `// nax-git-env-allow: <reason>` (argv handed to
+ * a runner that hardens it itself). An argv held in a variable and spawned
+ * elsewhere is beyond a textual gate; keep git argv literal at the spawn.
+ */
+/**
+ * `base` plus the hardened entries, appended after any GIT_CONFIG_COUNT
+ * entries the caller's environment already carries. A malformed existing
+ * count is left alone: git rejects it either way, and rewriting it would
+ * change which of the caller's entries apply.
+ */
+export declare function hardenedGitEnv(base: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
+/**
+ * The environment for a git nax spawns directly: `process.env`, then the
+ * caller's `overlay` (e.g. GIT_INDEX_FILE), then the hardened entries. Pass
+ * the overlay here rather than spreading the result, so a GIT_CONFIG_COUNT
+ * the overlay sets is appended to instead of overwritten.
+ */
+export declare function gitSpawnEnv(overlay?: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
+export declare const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
+/**
+ * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
+ * right after a `status` / `diff` subcommand. Unlike the config key, the flag
+ * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `--ignore-submodules` in `argv` still wins (git takes the last), which the
+ * agent-facing git tool cannot supply: it refuses every `-`-leading element.
+ */
+export declare function hardenedGitArgv(argv: readonly string[]): string[];

package/dist/internal/git-env.js

@@ -0,0 +1,93 @@
+/**
+ * Config overrides every nax-spawned git carries (#2198, defence in depth).
+ *
+ * `core.fsmonitor` names a program git runs on every status/diff/add; were an
+ * agent ever to get a value into a config nax's git reads (a redirected
+ * commondir, a nested repo git recurses into), nax would run it unsandboxed.
+ * nax never needs an fsmonitor, so it is always off.
+ *
+ * Submodules (#2210): for every gitlink, `git status` / `diff` / `commit`
+ * run `git status` inside the nested repo to learn whether it is dirty, and
+ * that child git reads the nested repo's own config and `.gitattributes` --
+ * files an agent can write when it creates the repo inside its write root.
+ * A filter driver (`filter.<x>.clean`) named there would run unsandboxed, and
+ * unlike fsmonitor it cannot be switched off by name. `diff.ignoreSubmodules
+ * =dirty` skips that dirty check (a moved gitlink HEAD is still reported,
+ * without spawning git in it), and `submodule.recurse=false` keeps checkout /
+ * merge from recursing. Config is only a default, though: a
+ * `submodule.<name>.ignore` in the agent-writable `.gitmodules` overrides it,
+ * so status / diff also get `--ignore-submodules=dirty` on the command line
+ * (`hardenedGitArgv`), the one form that beats `.gitmodules`. `git add`
+ * ignores both, so nax stages through `gitlinkSafeAdd` (`./git-add`), which
+ * also refuses to run a commit that would only print status.
+ *
+ * Passed through GIT_CONFIG_COUNT/KEY/VALUE (git >= 2.31; older git ignores
+ * them) rather than `-c` so argv stays unchanged, and because git forwards
+ * these to the child git processes it spawns (submodules) as well.
+ *
+ * Coverage: `gitWithTimeout` applies it, and every other site in `src/` that
+ * spawns git itself passes `env: gitSpawnEnv(...)`. The generic forge and
+ * auto-pr runners harden every command they spawn, since `gh` / `glab` run git
+ * underneath. `packages/repo-tooling/scripts/check-git-spawn-env.ts` (in `lint:checks`) fails on a
+ * `["git", ...]` argv literal that is neither inside a spawn call carrying one
+ * of these helpers nor marked `// nax-git-env-allow: <reason>` (argv handed to
+ * a runner that hardens it itself). An argv held in a variable and spawned
+ * elsewhere is beyond a textual gate; keep git argv literal at the spawn.
+ */
+const HARDENED_GIT_CONFIG = [
+    ["core.fsmonitor", "false"],
+    ["diff.ignoreSubmodules", "dirty"],
+    ["submodule.recurse", "false"],
+];
+const NON_NEGATIVE_INT = /^\d+$/;
+/**
+ * `base` plus the hardened entries, appended after any GIT_CONFIG_COUNT
+ * entries the caller's environment already carries. A malformed existing
+ * count is left alone: git rejects it either way, and rewriting it would
+ * change which of the caller's entries apply.
+ */
+export function hardenedGitEnv(base) {
+    const existing = base.GIT_CONFIG_COUNT;
+    if (existing !== undefined && existing !== "" && !NON_NEGATIVE_INT.test(existing))
+        return { ...base };
+    const start = existing === undefined || existing === "" ? 0 : Number.parseInt(existing, 10);
+    const env = { ...base };
+    HARDENED_GIT_CONFIG.forEach(([key, value], i) => {
+        env[`GIT_CONFIG_KEY_${start + i}`] = key;
+        env[`GIT_CONFIG_VALUE_${start + i}`] = value;
+    });
+    env.GIT_CONFIG_COUNT = String(start + HARDENED_GIT_CONFIG.length);
+    return env;
+}
+/**
+ * The environment for a git nax spawns directly: `process.env`, then the
+ * caller's `overlay` (e.g. GIT_INDEX_FILE), then the hardened entries. Pass
+ * the overlay here rather than spreading the result, so a GIT_CONFIG_COUNT
+ * the overlay sets is appended to instead of overwritten.
+ */
+export function gitSpawnEnv(overlay) {
+    return hardenedGitEnv(overlay === undefined ? process.env : { ...process.env, ...overlay });
+}
+/** Subcommands that dirty-check gitlinks, and so run git inside them unless told not to (#2210). */
+const SUBMODULE_DIRTY_CHECK_VERBS = new Set(["status", "diff"]);
+/** Global options that consume the next argument (`-C <dir>`, `-c <k=v>`). */
+const GLOBAL_OPTIONS_WITH_VALUE = new Set(["-C", "-c"]);
+export const IGNORE_DIRTY_SUBMODULES_FLAG = "--ignore-submodules=dirty";
+/**
+ * `argv` (argv[0] is the git program) with `--ignore-submodules=dirty` placed
+ * right after a `status` / `diff` subcommand. Unlike the config key, the flag
+ * overrides a `submodule.<name>.ignore` from `.gitmodules`. A later explicit
+ * `--ignore-submodules` in `argv` still wins (git takes the last), which the
+ * agent-facing git tool cannot supply: it refuses every `-`-leading element.
+ */
+export function hardenedGitArgv(argv) {
+    const out = [...argv];
+    let i = 1;
+    while (i < out.length && out[i].startsWith("-")) {
+        i += GLOBAL_OPTIONS_WITH_VALUE.has(out[i]) ? 2 : 1;
+    }
+    const verb = out[i];
+    if (verb !== undefined && SUBMODULE_DIRTY_CHECK_VERBS.has(verb))
+        out.splice(i + 1, 0, IGNORE_DIRTY_SUBMODULES_FLAG);
+    return out;
+}

package/dist/internal/git-exec.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Generic git subprocess execution, shared by nax and the move set. `_gitDeps`
+ * is defined here once; `utils/git.ts` re-exports the same object (spec section
+ * 4.3), so a test patch through either path affects both halves.
+ */
+import { getSafeLogger } from "#src/infra/index";
+/**
+ * Default timeout for git subprocess calls.
+ * Prevents git from hanging indefinitely on locked repos or network mounts.
+ */
+export declare const GIT_TIMEOUT_MS = 10000;
+/**
+ * Injectable dependencies for git subprocess calls — allows tests to intercept
+ * Bun.spawn without mock.module().
+ *
+ * `gitTimeoutMs` and `timeoutRetryGitTimeoutMs` are injectable so the hang-path
+ * tests can assert the SIGKILL contract without burning the full production
+ * timeout in wall-clock.
+ *
+ * @internal
+ */
+export declare const _gitDeps: {
+    spawn: (cmd: readonly string[], opts: import("#src/runtime/index").AgentSpawnOptions) => import("#src/runtime/index").AgentSpawnResult;
+    getSafeLogger: typeof getSafeLogger;
+    gitTimeoutMs: number;
+    timeoutRetryGitTimeoutMs: number;
+};
+/**
+ * Return the absolute path of the git repository root for the given workdir.
+ * Returns null if workdir is not inside a git repo or the command fails.
+ */
+export declare function getGitRoot(workdir: string): Promise<string | null>;
+/**
+ * Spawn a git command with a hard timeout.
+ *
+ * Kills the process with SIGKILL after GIT_TIMEOUT_MS if it hasn't exited.
+ * Returns empty stdout and exit code 1 on timeout.
+ *
+ * `timedOut` is ADDITIVE and OMITTED on every non-timeout return -- every
+ * existing caller that destructures `{ stdout, stderr, exitCode }` or asserts
+ * on that exact shape is unaffected. It exists because `exitCode === 1` is
+ * ambiguous on its own: a timeout collapses to exit code 1 (see below), which
+ * is indistinguishable from a real "git said no" exit 1 unless a caller can
+ * also see `timedOut`. A caller that treats "not exit 0" as a real, trustworthy
+ * answer (e.g. `git check-ignore`'s "not ignored") must check `timedOut` first
+ * -- see `partitionNaxOwnedPaths` in `src/tools/git-commit.ts`.
+ *
+ * @internal
+ */
+export declare function gitWithTimeout(args: string[], workdir: string, timeoutMs?: number, maxBytes?: number, 
+/** Full argv INCLUDING argv[0]. Callers that must control argv[0] pass this;
+ *  everyone else gets ["git", ...args] as before. */
+argvOverride?: readonly string[]): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+}>;

package/dist/internal/git-exec.js

@@ -0,0 +1,115 @@
+/**
+ * Generic git subprocess execution, shared by nax and the move set. `_gitDeps`
+ * is defined here once; `utils/git.ts` re-exports the same object (spec section
+ * 4.3), so a test patch through either path affects both halves.
+ */
+import { getSafeLogger } from "#src/infra/index";
+import { runtimeSpawn } from "#src/runtime/index";
+import { drainBounded } from "./bounded-io.js";
+import { hardenedGitArgv, hardenedGitEnv } from "./git-env.js";
+/**
+ * Default timeout for git subprocess calls.
+ * Prevents git from hanging indefinitely on locked repos or network mounts.
+ */
+export const GIT_TIMEOUT_MS = 10_000;
+/**
+ * Timeout for the git subprocesses captureWorkingTreeChanges spawns during
+ * timeout-retry recovery. Scoped separately from GIT_TIMEOUT_MS so it doesn't
+ * shrink the timeout for unrelated callers (captureOutputFiles, findMergeBase,
+ * etc.) — a hung git here must not stall the already-timed-out agent turn.
+ */
+const TIMEOUT_RETRY_GIT_TIMEOUT_MS = 3_000;
+/**
+ * Injectable dependencies for git subprocess calls — allows tests to intercept
+ * Bun.spawn without mock.module().
+ *
+ * `gitTimeoutMs` and `timeoutRetryGitTimeoutMs` are injectable so the hang-path
+ * tests can assert the SIGKILL contract without burning the full production
+ * timeout in wall-clock.
+ *
+ * @internal
+ */
+export const _gitDeps = {
+    spawn: runtimeSpawn,
+    getSafeLogger,
+    gitTimeoutMs: GIT_TIMEOUT_MS,
+    timeoutRetryGitTimeoutMs: TIMEOUT_RETRY_GIT_TIMEOUT_MS,
+};
+/**
+ * Return the absolute path of the git repository root for the given workdir.
+ * Returns null if workdir is not inside a git repo or the command fails.
+ */
+export async function getGitRoot(workdir) {
+    try {
+        const { stdout, exitCode } = await gitWithTimeout(["rev-parse", "--show-toplevel"], workdir);
+        if (exitCode !== 0)
+            return null;
+        const trimmed = stdout.trim();
+        return trimmed || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Spawn a git command with a hard timeout.
+ *
+ * Kills the process with SIGKILL after GIT_TIMEOUT_MS if it hasn't exited.
+ * Returns empty stdout and exit code 1 on timeout.
+ *
+ * `timedOut` is ADDITIVE and OMITTED on every non-timeout return -- every
+ * existing caller that destructures `{ stdout, stderr, exitCode }` or asserts
+ * on that exact shape is unaffected. It exists because `exitCode === 1` is
+ * ambiguous on its own: a timeout collapses to exit code 1 (see below), which
+ * is indistinguishable from a real "git said no" exit 1 unless a caller can
+ * also see `timedOut`. A caller that treats "not exit 0" as a real, trustworthy
+ * answer (e.g. `git check-ignore`'s "not ignored") must check `timedOut` first
+ * -- see `partitionNaxOwnedPaths` in `src/tools/git-commit.ts`.
+ *
+ * @internal
+ */
+export async function gitWithTimeout(args, workdir, timeoutMs = _gitDeps.gitTimeoutMs, maxBytes, 
+/** Full argv INCLUDING argv[0]. Callers that must control argv[0] pass this;
+ *  everyone else gets ["git", ...args] as before. */
+argvOverride) {
+    const proc = _gitDeps.spawn(hardenedGitArgv(argvOverride ?? ["git", ...args]), {
+        cwd: workdir,
+        env: hardenedGitEnv(process.env),
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    let timedOut = false;
+    const timerId = setTimeout(() => {
+        timedOut = true;
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            // Process may have already exited
+        }
+    }, timeoutMs);
+    // Drain stdout/stderr concurrently with awaiting exit — a process that fills
+    // either pipe's OS buffer (>64KB) before being read would otherwise block on
+    // the write and never reach `exited`, defeating the timeout's own SIGKILL.
+    // `.catch()` is attached eagerly: on the timeout path below we return without
+    // awaiting these, and an unawaited rejection (a SIGKILLed process can error its
+    // pipes) would surface as an unhandled rejection and take the process down.
+    // `maxBytes` bounds the WORK, not just the answer: the timeout caps wall
+    // clock, so without it `git log -p` on a large repository can accumulate for
+    // as long as the timeout allows. Optional, and unbounded when absent, so the
+    // callers that read a single ref keep exactly their current behaviour.
+    const drain = (stream) => (maxBytes === undefined ? new Response(stream).text() : drainBounded(stream, maxBytes)).catch(() => "");
+    const stdoutPromise = drain(proc.stdout);
+    const stderrPromise = drain(proc.stderr);
+    const exitCode = await proc.exited;
+    clearTimeout(timerId);
+    if (timedOut) {
+        // Don't await the drain promises here — a SIGKILL'd process's pipes may
+        // never close in test mocks (and are irrelevant either way since the
+        // output is discarded), so awaiting them could re-introduce a hang on
+        // the very path this timeout exists to bound.
+        return { stdout: "", stderr: "", exitCode: 1, timedOut: true };
+    }
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    return { stdout, stderr, exitCode };
+}