@nathapp/nax-agent 0.87.1 → 0.88.0-canary.2

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;

package/dist/tools/nax-revert.js

@@ -0,0 +1,233 @@
+/**
+ * Reverts of nax's run state (`.nax/`) through git, for the Bash guard
+ * (#2490, #2493).
+ *
+ * Three ways a revert reaches `.nax/`:
+ * 1. an operand that names a `.nax` path (`git checkout -- .nax/x`);
+ * 2. a WHOLE-TREE pathspec (`git checkout .`, `git restore --source=HEAD~1 .`,
+ *    `:/`, `*`, the root directory itself, a pathspec made only of exclusions),
+ *    unless a full `.nax` exclusion follows `--`;
+ * 3. `git reset --hard`, which has no pathspec form at all.
+ *
+ * For `git checkout` an operand is a PATH only after `--`, when it exists on
+ * disk relative to a frame, or when it resolves into `.nax` from the root; so
+ * `git checkout feature/.nax` (a branch whose name has a `.nax` segment) is
+ * not a revert. `git restore` has no branch operand, so all its operands are paths.
+ */
+import { existsSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { NAX_OWNED_RUN_STATE_EXPLANATION } from "./denial-redirect.js";
+import { findNaxDirs } from "./nax-dirs.js";
+/**
+ * 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 const COVERING_EXCLUSION = "':(top,exclude,glob)**/.nax/**'";
+/** `:(a,b)body` split on commas; git does not abbreviate long magic names. */
+function parseMagic(spec) {
+    const match = /^:\(([^)]*)\)(.*)$/s.exec(spec);
+    return match === null ? undefined : { elements: match[1].split(","), body: match[2] };
+}
+/**
+ * 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 function exclusionBody(spec) {
+    const short = /^:[!^](.*)$/s.exec(spec);
+    if (short !== null)
+        return short[1];
+    const magic = parseMagic(spec);
+    if (magic === undefined || !magic.elements.includes("exclude"))
+        return undefined;
+    return magic.elements.some((e) => e.startsWith("attr")) ? undefined : magic.body;
+}
+export const isExclusionSpec = (spec) => exclusionBody(spec) !== undefined;
+/** Exactly the covering form, magic in any order. */
+export function isCoveringExclusion(spec) {
+    const magic = parseMagic(spec);
+    if (magic === undefined || magic.body !== "**/.nax/**" || magic.elements.length !== 3)
+        return false;
+    return ["top", "exclude", "glob"].every((e) => magic.elements.includes(e));
+}
+/** `--force` -> true for `--f`, `--fo`, `--force`: any option abbreviation of `long` (`--x=v` too). */
+export function isLongPrefix(word, long) {
+    const name = word.split("=")[0];
+    return name.startsWith("--") && name.length >= 3 && long.startsWith(name);
+}
+/** True when `.nax` is a path segment of `path`. */
+export function hasNaxSegment(path) {
+    return path.split(/[\\/]/).includes(".nax");
+}
+/** True when `operand`, resolved from any frame, lands on or under a `.nax` directory. */
+export function operandTouchesNax(operand, ctx) {
+    if (hasNaxSegment(operand))
+        return true;
+    return ctx.frames.some((frame) => {
+        const rel = relative(ctx.root, resolve(frame, operand));
+        return !rel.startsWith("..") && hasNaxSegment(rel);
+    });
+}
+/**
+ * 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 function isFullNaxExclusion(spec, ctx) {
+    if (isCoveringExclusion(spec))
+        return true;
+    const target = exclusionBody(spec);
+    if (target === undefined)
+        return false;
+    const rootNax = join(ctx.root, ".nax");
+    if (findNaxDirs(ctx).some((dir) => dir !== rootNax))
+        return false;
+    const path = target.replace(/\/(?:\*\*)?$/, "");
+    const top = parseMagic(spec)?.elements.includes("top") === true;
+    return (top ? [ctx.root] : ctx.frames).every((frame) => resolve(frame, path) === rootNax);
+}
+/** Options whose value occupies the next word, per verb. */
+const VALUE_FLAGS = {
+    checkout: new Set(["-b", "-B", "--orphan", "--pathspec-from-file"]),
+    restore: new Set(["-s", "--source", "--pathspec-from-file"]),
+    clean: new Set(["-e", "--exclude"]),
+};
+function splitOperands(verb, args) {
+    const valueFlags = VALUE_FLAGS[verb] ?? new Set();
+    const before = [];
+    const after = [];
+    const flags = [];
+    let hasSeparator = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const word = args[i];
+        if (hasSeparator)
+            after.push(word);
+        else if (word === "--")
+            hasSeparator = true;
+        else if (word.startsWith("-") && word !== "-") {
+            flags.push(word);
+            if (valueFlags.has(word))
+                i += 1;
+        }
+        else
+            before.push(word);
+    }
+    return { before, after, hasSeparator, flags };
+}
+/** A checkout operand that is a path although no `--` marks it: it exists on disk, or lands in `.nax` from the root. */
+function isUnmarkedCheckoutPath(word, ctx) {
+    return ctx.frames.some((frame) => {
+        const target = resolve(frame, word);
+        if (existsSync(target))
+            return true;
+        return relative(ctx.root, target).split(/[\\/]/)[0] === ".nax";
+    });
+}
+function pathOperands(verb, ops, ctx) {
+    if (verb === "restore")
+        return [...ops.before, ...ops.after];
+    return [...ops.after, ...ops.before.filter((word) => isUnmarkedCheckoutPath(word, ctx))];
+}
+/** True when `spec` selects a directory that holds one of the `.nax` directories (or all of them, from the top). */
+function coversNax(spec, ctx, nax) {
+    if (isExclusionSpec(spec))
+        return false;
+    const magic = /^:(?:\(([^)]*)\)|\/)?(.*)$/s.exec(spec);
+    const top = magic !== null && (spec.startsWith(":/") || /(?:^|,)top(?:,|$)/.test(magic[1] ?? ""));
+    const body = (magic === null ? spec : magic[2]).replace(/(?:^|\/)\*{1,2}$/, "");
+    const bases = top ? [ctx.root] : ctx.frames;
+    return bases.some((base) => {
+        const dir = resolve(base, body === "" ? "." : body);
+        return nax.some((candidate) => candidate === dir || candidate.startsWith(`${dir}${sep}`));
+    });
+}
+/** `--staged` and every unambiguous abbreviation git accepts (`--st`), or a short cluster of only `S`. */
+const STAGED_FLAG = /^(?:--st|-S+$)/;
+/** Flags that change nothing about WHAT is restored. */
+const NEUTRAL_RESTORE_FLAG = /^(?:-q|--quiet|--progress|--no-progress)$/;
+/**
+ * `restore --staged` touches only the index. Fails closed: every flag must be `--staged` (or an
+ * abbreviation) or a neutral one, so `--wor` / `-SW` / `--source=...` / an unknown flag all count as
+ * touching the worktree.
+ */
+function touchesIndexOnly(flags) {
+    return (flags.some((f) => STAGED_FLAG.test(f)) && flags.every((f) => STAGED_FLAG.test(f) || NEUTRAL_RESTORE_FLAG.test(f)));
+}
+const treeRefusal = (verb) => `${NAX_OWNED_RUN_STATE_EXPLANATION} A whole-tree \`git ${verb}\` reverts it too. ` +
+    `Exclude it: \`git ${verb} -- . ${COVERING_EXCLUSION}\`.`;
+const RESET_REFUSAL = `${NAX_OWNED_RUN_STATE_EXPLANATION} \`git reset --hard\` (and \`--keep\` / \`--merge\`) resets the whole tree, ` +
+    "`.nax/` included, and has no pathspec form. " +
+    `To discard changes outside it use \`git checkout -- . ${COVERING_EXCLUSION}\`; to unstage use plain \`git reset\`.`;
+const DISCARD_REFUSAL = `${NAX_OWNED_RUN_STATE_EXPLANATION} This command discards or deletes working-tree changes across the whole tree, ` +
+    `\`.nax/\` included. Name the files, or exclude it: \`-- . ${COVERING_EXCLUSION}\` (not available for forced checkouts and switches).`;
+function wholeTreeRefusal(verb, ops, ctx) {
+    const nax = findNaxDirs(ctx);
+    if (nax.length === 0 || (verb === "restore" && touchesIndexOnly(ops.flags)))
+        return undefined;
+    if (ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx)))
+        return undefined;
+    const specs = ops.hasSeparator ? ops.after : ops.before;
+    const exclusionOnly = specs.length > 0 && specs.every(isExclusionSpec);
+    return exclusionOnly || specs.some((spec) => coversNax(spec, ctx, nax)) ? treeRefusal(verb) : undefined;
+}
+/** `-f` (alone or in a cluster) or `--force` and its abbreviations. */
+const isForceFlag = (word) => isLongPrefix(word, "--force") || (/^-[A-Za-z]+$/.test(word) && word.includes("f"));
+/** A forced checkout throws local changes away whatever it names. */
+function forcedCheckoutRefusal(verb, ops, ctx) {
+    if (verb !== "checkout" || !ops.flags.some(isForceFlag) || findNaxDirs(ctx).length === 0)
+        return undefined;
+    return ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx)) ? undefined : DISCARD_REFUSAL;
+}
+/** The refusal for `git checkout` / `git restore` with these arguments, or undefined. */
+export function revertRefusal(verb, args, ctx) {
+    const ops = splitOperands(verb, args);
+    // An exclusion NAMES `.nax` to keep it out; it is not an operand that touches it.
+    const names = pathOperands(verb, ops, ctx).some((word) => !isExclusionSpec(word) && operandTouchesNax(word, ctx));
+    if (names)
+        return NAX_OWNED_RUN_STATE_EXPLANATION;
+    return wholeTreeRefusal(verb, ops, ctx) ?? forcedCheckoutRefusal(verb, ops, ctx);
+}
+/** `git reset --hard` / `--keep` / `--merge` (any abbreviation git accepts) while a `.nax/` exists. */
+export function resetRefusal(args, ctx) {
+    const dangerous = ["--hard", "--keep", "--merge"];
+    if (!args.some((word) => dangerous.some((long) => isLongPrefix(word, long))))
+        return undefined;
+    return findNaxDirs(ctx).length > 0 ? RESET_REFUSAL : undefined;
+}
+const hasFlag = (flags, long, short) => flags.some((f) => isLongPrefix(f, long) || (/^-[A-Za-z]+$/.test(f) && f.includes(short)));
+/**
+ * `git clean -n` / `--dry-run`. In a short cluster `-e` takes the rest of the cluster as its value
+ * (`-fdenx` is `-f -d -e nx`, a real clean), so only an `n` before any `e` counts.
+ */
+const isCleanDryRun = (flags) => flags.some((f) => isLongPrefix(f, "--dry-run") || (/^-[A-Za-z]+$/.test(f) && f.slice(1).split("e")[0].includes("n")));
+/** Operands (and `--opt=value` values) of a discard verb that name a `.nax` path. */
+function namesNax(ops, ctx) {
+    const values = ops.flags.filter((f) => f.includes("=")).map((f) => f.slice(f.indexOf("=") + 1));
+    return [...ops.before, ...ops.after, ...values].some((word) => !isExclusionSpec(word) && operandTouchesNax(word, ctx));
+}
+/** Does this switch / clean / checkout-index / read-tree invocation wipe the tree (given no covering exclusion)? */
+function wipesTree(verb, ops, ctx) {
+    const f = ops.flags;
+    if (verb === "switch")
+        return f.some(isForceFlag) || f.some((w) => isLongPrefix(w, "--discard-changes"));
+    if (verb === "clean") {
+        const covered = ops.hasSeparator && ops.after.some((spec) => isFullNaxExclusion(spec, ctx));
+        return !covered && !isCleanDryRun(f);
+    }
+    if (verb === "checkout-index")
+        return hasFlag(f, "--all", "a") && hasFlag(f, "--force", "f");
+    if (verb === "read-tree")
+        return f.some((w) => isLongPrefix(w, "--reset")) && hasFlag(f, "--update", "u");
+    return false;
+}
+const NAMED_PATH_VERBS = new Set(["checkout-index", "read-tree", "clean"]);
+/** `switch -f`, `clean`, `checkout-index -a -f`, `read-tree -u --reset`: other ways to wipe the tree. */
+export function discardRefusal(verb, args, ctx) {
+    const ops = splitOperands(verb, args);
+    if (NAMED_PATH_VERBS.has(verb) && namesNax(ops, ctx))
+        return NAX_OWNED_RUN_STATE_EXPLANATION;
+    if (findNaxDirs(ctx).length === 0)
+        return undefined;
+    return wipesTree(verb, ops, ctx) ? DISCARD_REFUSAL : undefined;
+}

package/dist/tools/nax-stash-restore.d.ts

@@ -0,0 +1,7 @@
+import type { NaxGuardContext } from "./nax-dirs.ts";
+export declare const _naxStateGuardDeps: {
+    /** stdout on success, undefined on a spawn error, timeout or non-zero exit. */
+    git(cwd: string, args: readonly string[]): string | undefined;
+};
+/** Stash mutations that can be proved not to capture or replay nax state. */
+export declare function stashIsExempt(args: readonly string[], ctx: NaxGuardContext): boolean;

package/dist/tools/nax-stash-restore.js

@@ -0,0 +1,92 @@
+// Synchronous policy checks cannot use the asynchronous runtime spawn slot (#2539).
+import { spawnSync } from "node:child_process";
+import { lstatSync } from "node:fs";
+import { resolve } from "node:path";
+import { gitSpawnEnv } from "#src/internal/git-env";
+import { GIT_TIMEOUT_MS } from "#src/internal/git-exec";
+import { isFullNaxExclusion, operandTouchesNax } from "./nax-revert.js";
+export const _naxStateGuardDeps = {
+    /** stdout on success, undefined on a spawn error, timeout or non-zero exit. */
+    git(cwd, args) {
+        const out = spawnSync("git", [...args], {
+            cwd,
+            env: gitSpawnEnv(),
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf8",
+        });
+        return out.status === 0 && out.error === undefined ? out.stdout : undefined;
+    },
+};
+/** Parse only [--index] [-q|--quiet] [<numeric stash ref>], before doing any I/O. */
+function restoreRequest(args) {
+    const index = args[0] === "--index";
+    let i = index ? 1 : 0;
+    if (args[i] === "-q" || args[i] === "--quiet")
+        i += 1;
+    if (i === args.length)
+        return { ref: "stash@{0}", index };
+    const ref = args[i];
+    return i + 1 === args.length && ref !== undefined && /^(?:stash@\{\d+\}|\d+)$/.test(ref) ? { ref, index } : undefined;
+}
+/** Git -z output is unquoted; a .nax segment at ANY depth protects the whole operation. */
+function listingIsClean(cwd, args) {
+    const listing = _naxStateGuardDeps.git(cwd, args);
+    return listing !== undefined && !listing.split("\0").some((path) => path.split("/").includes(".nax"));
+}
+/** The listing of the stash's WORKING-TREE snapshot: what a plain `pop` / `apply` writes back. */
+function worktreeListingIsClean(cwd, ref) {
+    return listingIsClean(cwd, ["stash", "show", "-z", "--name-only", "--no-renames", "--include-untracked", ref]);
+}
+/**
+ * The stash's INDEX snapshot (B1): a stash commit has one parent for the base and
+ * one for the index, and `--index` writes that second parent back into the index.
+ * It is NOT the tree `stash show` lists — a `.nax` change that was staged and then
+ * reverted in the working tree appears in the index parent alone, so a listing-only
+ * check would let `pop --index` replay stale nax state over what nax has written
+ * since. Any failure to read it refuses.
+ */
+function indexSnapshotIsClean(cwd, ref) {
+    // A bare `N` resolves inside `git stash` only, so the diff — a plain revision —
+    // needs the `stash@{N}` spelling git itself resolves the number to.
+    const rev = ref.includes("@{") ? ref : `stash@{${ref}}`;
+    return listingIsClean(cwd, ["diff", "-z", "--name-only", "--no-renames", `${rev}^1`, `${rev}^2`]);
+}
+/** Every frame must list the stash successfully and clean, index snapshot included for `--index`. */
+function restoreIsExempt(args, ctx) {
+    const request = restoreRequest(args);
+    if (request === undefined)
+        return false;
+    return ctx.frames.every((frame) => worktreeListingIsClean(frame, request.ref) && (!request.index || indexSnapshotIsClean(frame, request.ref)));
+}
+/** Literal existing files or directories only; never symlinks, magic or globs. */
+function pathIsClean(spec, ctx) {
+    if (spec.startsWith(":") || /[*?[]/.test(spec) || operandTouchesNax(spec, ctx))
+        return false;
+    return ctx.frames.every((frame) => {
+        try {
+            const path = resolve(frame, spec);
+            const stat = lstatSync(path);
+            if (stat.isFile())
+                return true;
+            if (!stat.isDirectory() || path === ctx.root)
+                return false;
+            return listingIsClean(frame, ["ls-files", "-z", "--cached", "--others", "--", spec]);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Stash mutations that can be proved not to capture or replay nax state. */
+export function stashIsExempt(args, ctx) {
+    if (args[0] === "pop" || args[0] === "apply")
+        return restoreIsExempt(args.slice(1), ctx);
+    const separator = args.indexOf("--");
+    if (args[0] !== "push" || separator === -1)
+        return false;
+    const specs = args.slice(separator + 1);
+    if (specs.some((spec) => isFullNaxExclusion(spec, ctx)))
+        return true;
+    return specs.length > 0 && specs.every((spec) => pathIsClean(spec, ctx));
+}

package/dist/tools/nax-state-guard.d.ts

@@ -0,0 +1,18 @@
+import { type NaxGuardContext } from "./nax-dirs.ts";
+export type { NaxDirIndex, NaxGuardContext } from "./nax-dirs.ts";
+export { createNaxDirIndex } from "./nax-dirs.ts";
+/**
+ * The refusal for one command segment (its words, `git` possibly behind
+ * wrappers and global options), or undefined. A segment whose git invocation
+ * cannot be located is NOT judged here; see the BACKSTOP in the header. One
+ * that CAN be located but met a global option this reader does not know is
+ * judged by the structured rules and then, with a `.nax/` present, by the BACKSTOP.
+ */
+export declare function naxStateRefusal(segment: readonly string[], ctx: NaxGuardContext): string | undefined;
+/**
+ * `naxStateRefusal` over command TEXT: the raw command string in every Bash
+ * mode, and the string behind `bash -c` / `eval`. Tracks `cd` itself, applies
+ * the structured rules to each segment, and the coarse BACKSTOP (see the
+ * header) to segments whose git invocation it could not read.
+ */
+export declare function naxStateRefusalInText(command: string, ctx: NaxGuardContext): string | undefined;