@nathapp/nax-agent 0.87.0 → 0.88.0-canary.1

package/dist/tools/git-flags/locate.js

@@ -0,0 +1,361 @@
+/**
+ * Locating `git` and its subcommand inside a command line.
+ *
+ * A leaf module with NO imports, like `./index.ts`, so both `command-safety`
+ * and `tools` can use it without a cycle. Shared by the command-safety scorer
+ * and the Bash guard for nax's run state (#2490), so a wrapper or global
+ * option that hides `git` from one cannot hide it from the other.
+ */
+/** `sudo` options whose values occupy the next shell word. */
+const SUDO_VALUE_OPTIONS = new Set([
+    "-u",
+    "-g",
+    "-h",
+    "-D",
+    "-C",
+    "-p",
+    "-r",
+    "-t",
+    "-U",
+    "--user",
+    "--group",
+    "--host",
+    "--chdir",
+    "--close-from",
+    "--prompt",
+    "--role",
+    "--type",
+    "--other-user",
+]);
+/** Skip a sudo/doas prefix, including options with a separate value. */
+function afterPrivilegeWrapper(words) {
+    if (words[0] !== "sudo" && words[0] !== "doas")
+        return 0;
+    let i = 1;
+    while (words[i]?.startsWith("-")) {
+        const option = words[i++];
+        if (option === "--")
+            break;
+        if (option !== undefined && SUDO_VALUE_OPTIONS.has(option))
+            i += 1;
+    }
+    return i;
+}
+/** Skip an env prefix and its assignments and options. */
+function afterEnvWrapper(words, start) {
+    if (words[start] !== "env")
+        return start;
+    let i = start + 1;
+    while (i < words.length) {
+        const word = words[i];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || word === "-i" || word === "--ignore-environment") {
+            i += 1;
+        }
+        else if (word === "-u" || word === "--unset") {
+            i += 2;
+        }
+        else
+            break;
+    }
+    return i;
+}
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** `xargs` options that take a separate value. */
+const XARGS_VALUE_OPTIONS = new Set(["-I", "-n", "-P", "-L", "-d", "-E", "-s", "-a"]);
+function afterNice(words, start) {
+    let i = start + 1;
+    if (words[i] === "-n" || words[i] === "--adjustment")
+        i += 2;
+    else if (words[i]?.startsWith("-") && words[i] !== "--")
+        i += 1;
+    return i;
+}
+function afterTimeout(words, start) {
+    let i = start + 1;
+    while (words[i]?.startsWith("-"))
+        i += words[i] === "-k" || words[i] === "-s" ? 2 : 1;
+    return i + 1;
+}
+function afterXargs(words, start) {
+    let i = start + 1;
+    while (words[i]?.startsWith("-") && words[i] !== "--")
+        i += XARGS_VALUE_OPTIONS.has(words[i]) ? 2 : 1;
+    return i;
+}
+/**
+ * Index of the word that actually names the command, after leading `VAR=x`
+ * assignments and the wrappers that pass through to it (`sudo`, `env`,
+ * `command`, `exec`, `nice`, `timeout`, `xargs`).
+ */
+export function commandHeadIndex(words) {
+    let i = 0;
+    for (let guard = 0; guard < words.length; guard += 1) {
+        const before = i;
+        while (words[i] !== undefined && ASSIGNMENT.test(words[i]))
+            i += 1;
+        const word = words[i];
+        if (word === "sudo" || word === "doas")
+            i = afterPrivilegeWrapper(words.slice(i)) + i;
+        else if (word === "env")
+            i = afterEnvWrapper(words, i);
+        else if (word === "command" || word === "exec")
+            i += 1;
+        else if (word === "nice")
+            i = afterNice(words, i);
+        else if (word === "timeout")
+            i = afterTimeout(words, i);
+        else if (word === "xargs")
+            i = afterXargs(words, i);
+        if (i === before)
+            break;
+    }
+    return i;
+}
+/** `git`, or `\\git` (a leading backslash only suppresses shell aliases, so it still runs git). */
+function isGitWord(word) {
+    return word === "git" || word === "\\git";
+}
+/** Find `git` in the executable position after supported wrappers. */
+export function gitExecutableIndex(words) {
+    const i = commandHeadIndex(words);
+    return isGitWord(words[i]) ? i : undefined;
+}
+/** Long global options whose value is the NEXT word (`--git-dir X`); `--key=value` forms are skipped as one word. */
+const GIT_SEPARATE_VALUE_LONG = new Set([
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--super-prefix",
+    "--config-env",
+    "--attr-source",
+]);
+/** Global options that take no value, or only an `=value` (`git help git`). Anything else before the subcommand is unknown. */
+const GIT_KNOWN_FLAG_GLOBALS = new Set([
+    "-v",
+    "--version",
+    "-h",
+    "--help",
+    "--exec-path",
+    "--html-path",
+    "--man-path",
+    "--info-path",
+    "-p",
+    "--paginate",
+    "-P",
+    "--no-pager",
+    "--no-replace-objects",
+    "--no-lazy-fetch",
+    "--no-optional-locks",
+    "--no-advice",
+    "--bare",
+    "--literal-pathspecs",
+    "--glob-pathspecs",
+    "--noglob-pathspecs",
+    "--icase-pathspecs",
+    "--list-cmds",
+]);
+/** Global options whose value redirects git to another directory. */
+const GIT_DIR_OPTIONS = new Set(["-C", "--git-dir", "--work-tree"]);
+/**
+ * Subcommands git runs itself: an alias of the same name is NEVER expanded (`git -c alias.stash=status
+ * stash` really stashes). Every guarded verb plus the common builtins; a name missing here is expanded,
+ * which can only over-refuse.
+ */
+const GIT_BUILTINS = new Set([
+    "add",
+    "am",
+    "apply",
+    "archive",
+    "bisect",
+    "blame",
+    "branch",
+    "bundle",
+    "checkout",
+    "checkout-index",
+    "cherry",
+    "cherry-pick",
+    "clean",
+    "clone",
+    "commit",
+    "config",
+    "describe",
+    "diff",
+    "fetch",
+    "format-patch",
+    "gc",
+    "grep",
+    "init",
+    "log",
+    "ls-files",
+    "ls-tree",
+    "merge",
+    "mv",
+    "notes",
+    "pull",
+    "push",
+    "rebase",
+    "reflog",
+    "remote",
+    "reset",
+    "restore",
+    "revert",
+    "rm",
+    "show",
+    "sparse-checkout",
+    "stash",
+    "status",
+    "submodule",
+    "switch",
+    "tag",
+    "update-index",
+    "update-ref",
+    "worktree",
+    "read-tree",
+    "write-tree",
+    "rev-parse",
+    "rev-list",
+    "symbolic-ref",
+    "show-ref",
+    "for-each-ref",
+    "hash-object",
+    "cat-file",
+    "help",
+]);
+/** Skip global options from `start`; returns the index of the first word that is not one. */
+function skipGlobals(words, start, state) {
+    let i = start;
+    while (i < words.length && words[i].startsWith("-") && words[i] !== "--") {
+        i = consumeGlobal(words, i, state);
+    }
+    return i;
+}
+/** Alias value words, with a leading `!` and a leading `git` removed. */
+function aliasWords(value) {
+    const words = value
+        .replace(/^!/, "")
+        .split(/\s+/)
+        .filter((word) => word.length > 0);
+    if (isGitWord(words[0]))
+        words.shift();
+    return words;
+}
+/**
+ * Expand `-c alias.NAME=VALUE` while `subcommand` names such an alias (never a builtin, see GIT_BUILTINS).
+ * A name met twice is a cycle: `cycle` is set and the chain stops. The
+ * expanded words are run through the global-option skip again (an alias may
+ * start with `-C .` or `--no-pager`), and a `!` value is also returned as shell text.
+ */
+function resolveAliases(subcommand, args, state) {
+    let current = { subcommand, args, shellAlias: undefined, cycle: false };
+    const seen = new Set();
+    for (;;) {
+        const name = current.subcommand.toLowerCase();
+        const value = GIT_BUILTINS.has(name) ? undefined : state.aliases.get(name);
+        if (value === undefined)
+            break;
+        if (seen.has(name))
+            return { ...current, cycle: true };
+        seen.add(name);
+        const shellAlias = value.startsWith("!") ? `${value.slice(1)} ${current.args.join(" ")}`.trim() : undefined;
+        const merged = [...aliasWords(value), ...current.args];
+        const next = skipGlobals(merged, 0, state);
+        const head = merged[next];
+        if (head === undefined)
+            break;
+        current = {
+            subcommand: head,
+            args: merged.slice(next + 1),
+            shellAlias: current.shellAlias ?? shellAlias,
+            cycle: false,
+        };
+    }
+    return current;
+}
+/** Directory and config environment set by leading assignments (also those of an `env` wrapper). */
+function leadingGitEnv(words, gitIdx) {
+    const dirs = [];
+    let configEnv = false;
+    let literalPathspecs = false;
+    for (const word of words.slice(0, gitIdx)) {
+        const literal = /^GIT_LITERAL_PATHSPECS=(.*)$/.exec(word);
+        if (literal !== null)
+            literalPathspecs = literal[1] !== "" && literal[1] !== "0";
+        const match = /^(GIT_WORK_TREE|GIT_DIR|GIT_CONFIG[A-Z0-9_]*)=(.*)$/.exec(word);
+        if (match === null)
+            continue;
+        if (match[1]?.startsWith("GIT_CONFIG"))
+            configEnv = true;
+        else
+            dirs.push(match[2]);
+    }
+    return { dirs, configEnv, literalPathspecs };
+}
+/**
+ * Locate executable `git` in `words` and advance past its global options.
+ * Returns the subcommand (alias-expanded), its arguments, and the directories
+ * the global options point git at, or `undefined` when `git` isn't there or has
+ * no subcommand. Handles `sudo git`, `env VAR=x git`, a backslash-prefixed
+ * `git`, `git --no-pager checkout`, and an UNKNOWN `-x` / `--xxx` global
+ * (skipped as one word and flagged `uncertain`, so a new git option cannot
+ * hide the subcommand silently).
+ */
+export function locateGit(words) {
+    const gitIdx = gitExecutableIndex(words);
+    if (gitIdx === undefined)
+        return undefined;
+    const env = leadingGitEnv(words, gitIdx);
+    const state = { dirs: [...env.dirs], aliases: new Map(), configKeys: [], uncertain: false };
+    const i = skipGlobals(words, gitIdx + 1, state);
+    const unresolvedAlias = words.slice(gitIdx + 1, i).some((word, k, globals) => isConfigEnvAlias(word, globals[k + 1]));
+    const subcommand = words[i];
+    if (subcommand === undefined)
+        return undefined;
+    const resolved = resolveAliases(subcommand, words.slice(i + 1), state);
+    return {
+        subcommand: resolved.subcommand,
+        args: resolved.args,
+        dirs: state.dirs,
+        unresolvedAlias: unresolvedAlias || resolved.cycle,
+        configKeys: state.configKeys,
+        uncertain: state.uncertain,
+        shellAlias: resolved.shellAlias,
+        configEnv: env.configEnv,
+        literalPathspecs: env.literalPathspecs || words.slice(gitIdx + 1, i).includes("--literal-pathspecs"),
+    };
+}
+/** `--config-env=alias.x=VAR` or `--config-env alias.x=VAR` (git config keys are case-insensitive). */
+function isConfigEnvAlias(word, next) {
+    if (word.startsWith("--config-env="))
+        return /^alias\./i.test(word.slice("--config-env=".length));
+    return word === "--config-env" && /^alias\./i.test(next ?? "");
+}
+/** Consume one global option at `i`, recording directory values and `-c alias.*` definitions; returns the next index. */
+function consumeGlobal(words, i, state) {
+    const w = words[i];
+    if (w === "-c") {
+        const configKey = /^([^=]+)=/.exec(words[i + 1] ?? "")?.[1];
+        if (configKey !== undefined)
+            state.configKeys.push(configKey.toLowerCase());
+        const alias = /^alias\.([^=]+)=(.*)$/is.exec(words[i + 1] ?? "");
+        if (alias !== null)
+            state.aliases.set(alias[1].toLowerCase(), alias[2]);
+        return i + 2;
+    }
+    const eq = w.indexOf("=");
+    const key = eq === -1 ? w : w.slice(0, eq);
+    const separate = GIT_DIR_OPTIONS.has(key) || GIT_SEPARATE_VALUE_LONG.has(key);
+    if (!separate) {
+        if (!GIT_KNOWN_FLAG_GLOBALS.has(key))
+            state.uncertain = true;
+        return i + 1;
+    }
+    const value = eq === -1 ? words[i + 1] : w.slice(eq + 1);
+    if (key === "--config-env") {
+        const envKey = /^([^=]+)=/.exec(value ?? "")?.[1];
+        if (envKey !== undefined)
+            state.configKeys.push(envKey.toLowerCase());
+    }
+    if (GIT_DIR_OPTIONS.has(key) && value !== undefined)
+        state.dirs.push(value);
+    return eq === -1 ? i + 2 : i + 1;
+}

package/dist/tools/index.d.ts

@@ -28,7 +28,7 @@ export type { CodingToolOutcome, CodingToolRuntime, ToolCallContext } from "./ru
 export { _codingToolDeps, _resetBuiltinsForTest, createCodingToolRuntime, DEFAULT_TOOL_MAX_BYTES, DEFAULT_TOOL_MAX_FILE_BYTES, registerBuiltinCodingTools, } from "./runtime.ts";
 export { SCRATCHPAD_DIR, scratchpadListTool, scratchpadReadTool, scratchpadWriteTool } from "./scratchpad.ts";
 export { _spillDeps, applyModelTruncationPolicy, type ModelTruncationOptions, SPILL_DIR, type SpillRequest, spillRelativePath, writeSpill, } from "./spill.ts";
-export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord } from "./tool-audit.ts";
+export type { RegisteredSink, ToolAuditHeader, ToolAuditSink, ToolCallRecord, ToolSurfaceDraft, ToolSurfaceRecord, } from "./tool-audit.ts";
 export { createNoOpToolAuditSink, createToolAuditSink, flushOpenToolAuditSinks, registerToolAuditSink, unregisterToolAuditSink, } from "./tool-audit.ts";
 export { cutBufferToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, type TruncateForModelOptions, type TruncationDirection, type TruncationResult, truncateForModel, truncationDirectionFor, } from "./truncate.ts";
 export type { CodingToolName, PolicyVerdict, ToolGrant, ToolPolicy, ToolScope } from "./types.ts";

package/dist/tools/nax-dirs.d.ts

@@ -0,0 +1,22 @@
+/** Where a segment runs: every live working-directory frame, and the permitted root. */
+export interface NaxGuardContext {
+    readonly frames: readonly string[];
+    readonly root: string;
+    /** Shared downward-scan cache; absent means every lookup scans afresh. */
+    readonly naxDirs?: NaxDirIndex;
+}
+/** Every `.nax` directory at or below `root`, within the depth bound. */
+export declare function scanNaxDirs(root: string): readonly string[];
+/** Lazily scanned, per-root cache of the `.nax` directories at or below a root. */
+export interface NaxDirIndex {
+    below(root: string): readonly string[];
+}
+/**
+ * A found `.nax` is cached for the index's lifetime (a deleted one may keep refusing, which is safe); an
+ * empty result only for {@link NEGATIVE_TTL_MS}, so one created mid-run is not invisible for ever.
+ */
+export declare function createNaxDirIndex(now?: () => number): NaxDirIndex;
+/** Every known `.nax` directory: on the way from a frame to the root, at the root, or nested below it. */
+export declare function findNaxDirs(ctx: NaxGuardContext): readonly string[];
+/** True when a `.nax/` exists at a frame, between a frame and the root, at the root, or nested below it. */
+export declare function hasNaxDirNear(ctx: NaxGuardContext): boolean;

package/dist/tools/nax-dirs.js

@@ -0,0 +1,89 @@
+/**
+ * Where nax's run state (`.nax/`) lives, for the Bash guard (#2490, #2493).
+ *
+ * A `.nax/` is looked for at the root, at every working-directory frame and
+ * between a frame and the root, and BELOW the root: a package-level `.nax`
+ * (monorepo workdir) is nax state just as much as the root one. The downward
+ * scan is bounded (depth 3 under the root, never into `node_modules` or a
+ * dot-directory other than `.nax`) and cached in a `NaxDirIndex` that the
+ * policy creates once per compile.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/** How deep below the root a nested `.nax` is looked for. */
+const MAX_NESTED_DEPTH = 3;
+/** Directory names the downward scan never enters. */
+function isSkipped(name) {
+    return name === "node_modules" || (name.startsWith(".") && name !== ".nax");
+}
+/** `.nax` directories in `dir` (at `depth` below the root) and in its subdirectories, within the bound. */
+function scanDown(dir, depth, found) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === ".nax")
+            found.push(join(dir, entry.name));
+        else if (depth < MAX_NESTED_DEPTH && !isSkipped(entry.name))
+            scanDown(join(dir, entry.name), depth + 1, found);
+    }
+}
+/** Every `.nax` directory at or below `root`, within the depth bound. */
+export function scanNaxDirs(root) {
+    const found = [];
+    scanDown(root, 0, found);
+    return found;
+}
+/** How long an EMPTY scan result is trusted: a `.nax/` created later is seen within this. */
+const NEGATIVE_TTL_MS = 1_000;
+/**
+ * A found `.nax` is cached for the index's lifetime (a deleted one may keep refusing, which is safe); an
+ * empty result only for {@link NEGATIVE_TTL_MS}, so one created mid-run is not invisible for ever.
+ */
+export function createNaxDirIndex(now = Date.now) {
+    const byRoot = new Map();
+    return {
+        below(root) {
+            const cached = byRoot.get(root);
+            if (cached !== undefined && (cached.dirs.length > 0 || now() - cached.at < NEGATIVE_TTL_MS)) {
+                return cached.dirs;
+            }
+            const dirs = scanNaxDirs(root);
+            byRoot.set(root, { dirs, at: now() });
+            return dirs;
+        },
+    };
+}
+/** The root, every frame, and every directory between a frame and the root. */
+function candidateDirs(ctx) {
+    const candidates = new Set([ctx.root]);
+    for (const frame of ctx.frames) {
+        let dir = frame;
+        candidates.add(dir);
+        while (dir !== ctx.root && dir.startsWith(`${ctx.root}${sep}`)) {
+            dir = resolve(dir, "..");
+            candidates.add(dir);
+        }
+    }
+    return candidates;
+}
+function nearNaxDirs(ctx) {
+    return [...candidateDirs(ctx)].map((dir) => join(dir, ".nax")).filter((dir) => existsSync(dir));
+}
+function nestedNaxDirs(ctx) {
+    return (ctx.naxDirs ?? { below: scanNaxDirs }).below(ctx.root);
+}
+/** Every known `.nax` directory: on the way from a frame to the root, at the root, or nested below it. */
+export function findNaxDirs(ctx) {
+    return [...new Set([...nearNaxDirs(ctx), ...nestedNaxDirs(ctx)])];
+}
+/** True when a `.nax/` exists at a frame, between a frame and the root, at the root, or nested below it. */
+export function hasNaxDirNear(ctx) {
+    return nearNaxDirs(ctx).length > 0 || nestedNaxDirs(ctx).length > 0;
+}

package/dist/tools/nax-evasion.d.ts

@@ -0,0 +1,19 @@
+/** True when `text` names a guarded git verb as a word (`alias.s=stash` and `` stash` `` count). */
+export declare function mentionsGuardedVerb(text: string): boolean;
+export declare const CONFIG_ALIAS_REFUSAL: string;
+export declare const CONFIG_ENV_REFUSAL: string;
+export declare const EXPANSION_REFUSAL: string;
+export declare function isExecConfigKey(key: string): boolean;
+export declare const EXEC_CONFIG_REFUSAL: string;
+/** `git config [scope flags] alias.<name> <value>` (also `--add`, `--replace-all`, `set`) with a dangerous VALUE, or an executing key. */
+export declare function configAliasRefusal(args: readonly string[]): string | undefined;
+/**
+ * True when some command of `command` (split coarsely on `; & |` and newlines)
+ * has an expansion as its head or as its git subcommand AND mentions a guarded
+ * verb: the verb is then probably what the expansion builds.
+ */
+export declare function buildsVerbByExpansion(command: string): boolean;
+/** The code string of `python -c`, `node -e`, `perl -e`, `ruby -e` (behind wrappers), or undefined. */
+export declare function interpreterCode(words: readonly string[]): string | undefined;
+/** Code reduced to shell-like words: quotes, brackets, parentheses and commas become spaces. */
+export declare function flattenCode(code: string): string;

package/dist/tools/nax-evasion.js

@@ -0,0 +1,88 @@
+/**
+ * Ways a git verb is hidden from the Bash guard for nax's run state (#2493):
+ * an alias defined with `git config`, an interpreter's code string, and a verb
+ * or command head built by shell expansion. Pure text helpers; the guard
+ * decides, from whether a `.nax/` exists, whether a hit is a refusal.
+ */
+import { commandHeadIndex, gitExecutableIndex, locateGit } from "./git-flags/locate.js";
+/**
+ * The verbs the guard protects `.nax/` from. A verb inside a file name or path (`reset.test.ts`,
+ * `src/reset`) is not a mention.
+ */
+const GUARDED_VERB = /(?<![\w./-])(?:stash|update-index|checkout|restore|reset|clean|switch)(?![\w./-])/;
+/** True when `text` names a guarded git verb as a word (`alias.s=stash` and `` stash` `` count). */
+export function mentionsGuardedVerb(text) {
+    return GUARDED_VERB.test(text);
+}
+export const CONFIG_ALIAS_REFUSAL = "Defining a git alias whose value runs stash, update-index, checkout, restore or reset is refused while the " +
+    "repository holds nax's run state under `.nax/`: the alias would run that verb where it cannot be inspected. " +
+    "Run the git verb directly.";
+export const CONFIG_ENV_REFUSAL = "Git configuration injected through `GIT_CONFIG_*` cannot be inspected while the repository holds nax's run " +
+    "state under `.nax/`. Run the git verb directly, without `GIT_CONFIG_*`.";
+export const EXPANSION_REFUSAL = "A git verb or command built by shell expansion (`$VAR`, `$(...)`, backticks) cannot be inspected while the " +
+    "repository holds nax's run state under `.nax/`. Write the command out literally.";
+/** An alias value is dangerous when it names a guarded verb; `reset` only when it discards (`reset HEAD --` unstages). */
+function aliasValueDangerous(value) {
+    const withoutReset = value.replace(/(?<![\w./-])reset(?![\w./-])/g, " ");
+    if (mentionsGuardedVerb(withoutReset))
+        return true;
+    return /(?<![\w./-])reset(?![\w./-])/.test(value) && /(?:^|\s)--(?:ha|ke|me)/.test(value);
+}
+/** Config keys whose value git EXECUTES (or reads more config from): an agent can run any verb through them. */
+const EXEC_CONFIG_KEY = /^(?:include\.path|includeif\..+|core\.(?:fsmonitor|hookspath|pager|editor|sshcommand|askpass)|diff\.external|sequence\.editor|.+\.textconv|.+\.process|filter\..+\.(?:clean|smudge|process)|credential\.helper|gpg\.program|sendemail\.smtpserver)$/;
+export function isExecConfigKey(key) {
+    return EXEC_CONFIG_KEY.test(key.toLowerCase());
+}
+export const EXEC_CONFIG_REFUSAL = "Setting a git config key whose value git executes (core.fsmonitor, core.hooksPath, core.pager, core.editor, " +
+    "core.sshCommand, diff.external, sequence.editor, include.path, *.textconv, filter.*.clean/smudge, ...) is refused " +
+    "while the repository holds nax's run state under `.nax/`: it can run any git verb where it cannot be inspected.";
+/** `git config [flags] KEY VALUE` / `--add` / `set` of an executing key; a read or `--unset` (key only) is fine. */
+function configWritesExecKey(args) {
+    const operands = args.filter((word) => !word.startsWith("-") && word !== "set");
+    const at = operands.findIndex(isExecConfigKey);
+    return at !== -1 && at < operands.length - 1 && !args.some((a) => /^--(?:unset|get)/.test(a));
+}
+/** `git config [scope flags] alias.<name> <value>` (also `--add`, `--replace-all`, `set`) with a dangerous VALUE, or an executing key. */
+export function configAliasRefusal(args) {
+    if (configWritesExecKey(args))
+        return EXEC_CONFIG_REFUSAL;
+    const at = args.findIndex((word) => /^alias\./i.test(word));
+    if (at === -1)
+        return undefined;
+    return aliasValueDangerous(args.slice(at + 1).join(" ")) ? CONFIG_ALIAS_REFUSAL : undefined;
+}
+const EXPANSION = /[$`]/;
+/**
+ * True when some command of `command` (split coarsely on `; & |` and newlines)
+ * has an expansion as its head or as its git subcommand AND mentions a guarded
+ * verb: the verb is then probably what the expansion builds.
+ */
+export function buildsVerbByExpansion(command) {
+    return command.split(/[;&|\n]+/).some((part) => {
+        if (!GUARDED_VERB.test(part))
+            return false;
+        const words = part.trim().split(/\s+/).filter(Boolean);
+        // Without a git token (or an alias definition) in the segment the verb is not git's: `$RUNNER test reset.ts`.
+        if (!words.some((w) => w === "git" || w === "\\git" || w.endsWith("/git") || w.includes("alias.")))
+            return false;
+        const head = words[commandHeadIndex(words)];
+        if (head !== undefined && EXPANSION.test(head))
+            return true;
+        return gitExecutableIndex(words) !== undefined && EXPANSION.test(locateGit(words)?.subcommand ?? "");
+    });
+}
+const INTERPRETER = /^(?:python[\d.]*|node(?:js)?|perl|ruby|bun|deno|php|lua[\d.]*|osascript|pwsh|powershell)$/;
+const CODE_FLAG = /^-[A-Za-z]*[ceEpr]$|^--eval$|^eval$|^-(?:Command|command)$/;
+/** The code string of `python -c`, `node -e`, `perl -e`, `ruby -e` (behind wrappers), or undefined. */
+export function interpreterCode(words) {
+    const head = commandHeadIndex(words);
+    const name = words[head]?.split("/").pop();
+    if (name === undefined || !INTERPRETER.test(name))
+        return undefined;
+    const flag = words.findIndex((word, i) => i > head && CODE_FLAG.test(word));
+    return flag === -1 || flag + 1 >= words.length ? undefined : words.slice(flag + 1).join(" ");
+}
+/** Code reduced to shell-like words: quotes, brackets, parentheses and commas become spaces. */
+export function flattenCode(code) {
+    return code.replace(/["'`[\](),]/g, " ");
+}

package/dist/tools/nax-revert.d.ts

@@ -0,0 +1,34 @@
+import { type NaxGuardContext } from "./nax-dirs.ts";
+/**
+ * The pathspec that covers EVERY `.nax` directory AND the files inside them, named in advice texts. Real git:
+ * the glob must end in `/**` (the bare `.nax` glob matches only the directory entry) and be anchored at the
+ * top (a relative glob is taken from the working directory).
+ */
+export declare const COVERING_EXCLUSION = "':(top,exclude,glob)**/.nax/**'";
+/**
+ * The path an exclusion pathspec excludes, or undefined when `spec` is not one: `:!X`, `:^X`, or a long form
+ * with an element exactly `exclude` and no `attr:` element (an `attr:` spec is an attribute filter whatever
+ * else it says).
+ */
+export declare function exclusionBody(spec: string): string | undefined;
+export declare const isExclusionSpec: (spec: string) => boolean;
+/** Exactly the covering form, magic in any order. */
+export declare function isCoveringExclusion(spec: string): boolean;
+/** `--force` -> true for `--f`, `--fo`, `--force`: any option abbreviation of `long` (`--x=v` too). */
+export declare function isLongPrefix(word: string, long: string): boolean;
+/** True when `.nax` is a path segment of `path`. */
+export declare function hasNaxSegment(path: string): boolean;
+/** True when `operand`, resolved from any frame, lands on or under a `.nax` directory. */
+export declare function operandTouchesNax(operand: string, ctx: NaxGuardContext): boolean;
+/**
+ * An exclusion that covers EVERY `.nax` the guard knows of. The covering glob always does. The literal forms
+ * (`:!.nax`, `:^.nax/`, `:(exclude).nax`) name only `<root>/.nax` (resolved from EVERY frame, or from the root
+ * under `top`), so they count only while that is the single `.nax` there is.
+ */
+export declare function isFullNaxExclusion(spec: string, ctx: NaxGuardContext): boolean;
+/** The refusal for `git checkout` / `git restore` with these arguments, or undefined. */
+export declare function revertRefusal(verb: string, args: readonly string[], ctx: NaxGuardContext): string | undefined;
+/** `git reset --hard` / `--keep` / `--merge` (any abbreviation git accepts) while a `.nax/` exists. */
+export declare function resetRefusal(args: readonly string[], ctx: NaxGuardContext): string | undefined;
+/** `switch -f`, `clean`, `checkout-index -a -f`, `read-tree -u --reset`: other ways to wipe the tree. */
+export declare function discardRefusal(verb: string, args: readonly string[], ctx: NaxGuardContext): string | undefined;