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

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@nathapp/nax-agent` are recorded here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). While the version is `0.x`, a minor
 release may change the public API.
 
+## [0.88.0-canary.1] - 2026-10-13
+
+- Bash guard for nax run state (#2490): `git update-index --skip-worktree` / `--assume-unchanged` (and the `--no-` forms) on a `.nax` path, `git stash` / `push` / `pop` / `apply` in a repo that holds a `.nax/` directory (unless the pathspec excludes `.nax`), and `git checkout` / `restore` of a `.nax` path are now refused in every segment of a compound command, in gated and raw mode, also behind `git -C`/`-c`, env assignments, `env`/`command`/`nice`/`timeout`/`xargs` wrappers and `bash -c`/`eval`, plus a coarse text backstop for wrappers it cannot enumerate. `RULE_SET_VERSION` is now 4 (git global options, `-c alias.*` and more wrappers are resolved when locating the subcommand).
+- Bash guard gaps closed (#2493): whole-tree reverts (`git reset --hard`, `git checkout .`, `git restore [--source=REV] .`, `:/`, `*`, the root, exclusion-only pathspecs) are refused unless a full `.nax` exclusion follows `--`; the `.nax` presence check also finds a `.nax/` up to three levels below the root (cached per compiled policy); `\git`, `GIT_WORK_TREE` / `GIT_DIR` / `GIT_CONFIG_*` assignments, `git config alias.X <verb>`, `!` aliases and aliases that begin with global options, unknown git global options (fail closed to the text backstop; `--attr-source` is now a known separate-value global), `python|node|perl|ruby -c|-e` code and verbs built by shell expansion are all read; `git checkout feature/.nax` (a branch name) is no longer a false positive. `RULE_SET_VERSION` is now 6 (`locateGit` reads `\git`, re-skips globals after an alias expansion, follows alias chains of any length and never expands an alias over a git builtin).
+- Bash guard, final pass (#2493): a shell name or `-c` cluster anywhere in a segment triggers the quoted-string scan again (`if sh -c "..."`, `find -exec sh -c`, `su -c`, `setsid bash -c` were let through by round 2); `git clean` counts as a dry run only for an `n` before any `e` in a short cluster (`-fdenx` is `-e nx`, a real clean); `--literal-pathspecs` / `GIT_LITERAL_PATHSPECS` with an exclusion pathspec on checkout, restore, stash or clean is refused (it turns every exclusion into a literal path). The command guard stops here; detect-and-repair of nax run state is tracked in #2497.
+- Bash guard, review round 2 (#2493): the covering exclusion must be the top-anchored `/**` form (real git: a glob without the `/**` matches only the `.nax` directory entry, not the files in it, and a relative glob is taken from the working directory); a `:(...)` pathspec with an `attr:` element, or whose magic is not exactly `exclude`, is no exclusion; `checkout-index`, `read-tree` and `clean` operands that name `.nax` are refused; long options are matched by any prefix git accepts (`--k`, `--f`, `--a`); the gated screen accepts the exact covering pathspec instead of rejecting its quoted `*`; the quoted-string scan covers only shells, interpreters and exec-style wrappers (`grep "git stash"`, `gh ... --body "..."`, `printf`, `sed` are no longer refused); `git clean -n` / `--dry-run` is allowed. Not covered, documented: git subcommands that execute a string (`rebase -x`, `submodule foreach`, `bisect run`, `difftool -x`, `fetch --upload-pack=`), executing environment variables (`GIT_EXTERNAL_DIFF`, `GIT_PAGER`, `GIT_EDITOR`, `GIT_SSH_COMMAND`), executing config keys beyond the listed ones (`remote.*.uploadpack`, `uploadpack.packObjectsHook`, `core.alternateRefsCommand`, `merge.*.driver`, `core.gitProxy`, `protocol.ext.allow` with `ext::` URLs), `deno eval` in raw mode, and commands built by string arithmetic in an interpreter.
+- Bash guard, review round 1 (#2493): alias chains have no depth limit (a cycle is refused); backslash-built words (`g\it`, `st\ash`) are read; `restore --staged` is index-only only when every flag is known (`--wor`, `-SW` count as worktree); more interpreters and any quoted string next to a guarded verb are scanned; git config keys that execute commands (`core.fsmonitor`, `core.hooksPath`, `diff.external`, `include.path`, ...) are refused through `-c`, `--config-env` and `git config`; an alias over a git builtin is not expanded; the covering exclusion is now `':(top,exclude,glob)**/.nax/**'` (the literal `:!.nax` only counts while the root `.nax` is the only one); `checkout -f`, `switch -f`, `reset --keep|--merge`, `clean`, `checkout-index -a -f` and `read-tree -u --reset` are refused while a `.nax/` exists; an expansion head needs a `git` token in the segment. A `.nax/` below the root, for example a test fixture within three levels, makes `git stash` refused for the whole repository. The nested scan caches a found `.nax` but re-scans an empty result after one second.
+- Native errors: a `quota` kind from `@nathapp/nax-ai` (usage-limit and token-plan 429s) now maps to
+  `fail-quota` instead of a transient rate limit.
+
 ## [0.87.1] - 2026-10-12
 
 - No changes in this package. Released in lockstep with the other nax packages.

package/dist/command-safety/rule-scorer.d.ts

@@ -1,5 +1,5 @@
 import { type RuleResult } from "./types.ts";
-export declare const RULE_SET_VERSION = 3;
+export declare const RULE_SET_VERSION = 6;
 /** Context the scorer may use; every field is optional and absent means v1 behaviour. */
 export interface RuleContext {
     /** The project root the command runs against (the Bash call's cwd). */

package/dist/command-safety/rule-scorer.js

@@ -27,14 +27,24 @@
  * hit. The existing eleven regex families stay; the new patterns live in a
  * per-segment pass.
  *
+ * v5: `locateGit` (shared with the nax-state guard, #2493) reads a
+ * backslash-prefixed `\git`, runs the global-option skip again over an
+ * expanded alias, and follows alias chains, so a discard behind any of those
+ * is now located by the v3 per-segment pass.
+ *
+ * v6: `locateGit` never expands an alias that shadows a git builtin (git ignores it) and follows alias
+ * chains of any length (a cycle is reported, not looped on), so `git -c alias.checkout=status checkout -f`
+ * is the discard it really is.
+ *
  * Frozen before the red-team corpus was written. Any pattern or behaviour
  * change bumps RULE_SET_VERSION.
  */
 import { posix } from "node:path";
 import { errorMessage } from "#src/infra/errors";
 import { lexBashCommand } from "#src/permissions/index";
+import { locateGit } from "#src/tools/git-flags/locate";
 import { QUESTION_IDS } from "./types.js";
-export const RULE_SET_VERSION = 3;
+export const RULE_SET_VERSION = 6;
 const RULES = {
     deletes_data: [
         /\brm\s+(?:\S+\s+)*?(?:-[a-zA-Z]*[rRf][a-zA-Z]*|--recursive|--force)\b/,
@@ -140,118 +150,6 @@ const FORCE_FLAGS = new Set(["-f", "--force", "--discard-changes"]);
 const STAGED_FLAGS = new Set(["--staged", "-S"]);
 /** True when `word` is a worktree-restore flag — its own pattern handles these. */
 const WORKTREE_FLAGS = new Set(["--worktree", "-W"]);
-/** `git`'s global options that take no value — pass-through, then look for
- *  the subcommand. */
-const GIT_BOOLEAN_GLOBALS = new Set([
-    "--no-pager",
-    "--no-replace-objects",
-    "--bare",
-    "--literal-pathspecs",
-    "--glob-pathspecs",
-    "--noglob-pathspecs",
-    "--icase-pathspecs",
-]);
-/** `git`'s global options that take a separate value (the next token). */
-const GIT_VALUE_GLOBALS = new Set(["-c", "-C"]);
-/** `git`'s global long options that embed their value (`--key=value`). */
-const GIT_KEY_VALUE_GLOBALS = new Set([
-    "--git-dir=",
-    "--exec-path=",
-    "--work-tree=",
-    "--namespace=",
-    "--super-prefix=",
-]);
-/** `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;
-}
-/** Find `git` in the executable position after supported shell wrappers. */
-function gitExecutableIndex(words) {
-    let i = afterEnvWrapper(words, afterPrivilegeWrapper(words));
-    if (words[i] === "command" || words[i] === "exec")
-        i += 1;
-    return words[i] === "git" ? i : undefined;
-}
-/** Locate executable `git` in `words` and advance past its global options. Returns the
-   subcommand and the index of the first argument (or `undefined` when `git`
-   isn't there or has no subcommand). Handles `sudo git`, `env VAR=x git`,
-   `git --no-pager checkout`, etc. */
-function locateGit(words) {
-    const gitIdx = gitExecutableIndex(words);
-    if (gitIdx === undefined)
-        return undefined;
-    let i = gitIdx + 1;
-    while (i < words.length) {
-        const w = words[i];
-        if (GIT_BOOLEAN_GLOBALS.has(w)) {
-            i += 1;
-            continue;
-        }
-        if (GIT_VALUE_GLOBALS.has(w)) {
-            // The value is a separate token; skip it.
-            i += 2;
-            continue;
-        }
-        if ([...GIT_KEY_VALUE_GLOBALS].some((prefix) => w.startsWith(prefix))) {
-            i += 1;
-            continue;
-        }
-        break;
-    }
-    const subcommand = words[i];
-    if (subcommand === undefined)
-        return undefined;
-    return { subcommand, args: words.slice(i + 1) };
-}
 /** True when `token` is a short-flag bundle that includes `f` (so `-f`,
  *  `-fq`, `-fb`, `-fqH`, ...). Stops at `--` so a long flag like
  *  `--force-something` is not misread as a bundle. */

package/dist/native/errors.js

@@ -17,6 +17,13 @@ const FAILURES = Object.freeze({
         outcome: "fail-rate-limit",
         retriable: true,
     },
+    // The account or plan is exhausted: waiting does not help, so not retriable.
+    quota: {
+        message: "nax-ai account or plan quota exhausted",
+        category: "availability",
+        outcome: "fail-quota",
+        retriable: false,
+    },
     auth: {
         message: "nax-ai authentication failed",
         category: "availability",

package/dist/tools/denial-redirect.d.ts

@@ -19,16 +19,31 @@
  * `grep -n x y` did not. 20 of 34 denials in the two runs after #1971 carried
  * no redirect (nax#1999). A single table cannot drift against itself.
  */
-export declare function redirectForArgv(argv: readonly string[], available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+export declare const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
 /**
- * Name the tool that serves the intent behind a denied Bash COMMAND.
+ * The sentence explaining a revert of nax's own run state, or undefined.
+ *
+ * Deliberately NOT an `Intent`: `render()` wraps every hit as "this session
+ * already has `X`", which is false here -- no tool reverts `.nax/`, and the
+ * module's header forbids naming one it does not hold. So this predicate is
+ * checked BEFORE `intentFor` in both entry points and returns its own sentence.
  *
- * Reads the first segment only: that is what the model reached for, and a
- * later segment's intent is not what to teach when the call is refused. The
- * split is deliberately its own crude one rather than the lexer's
- * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
- * still get a redirect, and the lexer returns nothing to read in that case.
+ * Verb scope is `checkout` and `restore` only; `git stash` has no operands to
+ * gate on and is handled by `nax-state-guard.ts` instead. The gate is a `.nax`
+ * path SEGMENT (split on `/`), never a substring, so `src/nax-helpers.ts` and
+ * `docs/.naxignore` stay unanswered. `--` is a separator, not an operand, and a
+ * `timeout N` wrapper is stripped the same way `intentFor` strips it.
+ */
+export declare function naxOwnedRunStateExplanation(tokens: readonly string[]): string | undefined;
+/** A `timeout N ...` prefix wraps the real command; look past it. */
+export declare function withoutTimeoutPrefix(tokens: readonly string[]): readonly string[];
+export declare function redirectForArgv(argv: readonly string[], available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
+/**
+ * The crude segment split shared by the redirect and the raw screen's fallback
+ * for a command the lexer refused. Deliberately not the lexer: it must still
+ * produce segments when the lexer returns nothing to read.
  */
+export declare function crudeCommandSegments(command: string): string[][];
 export declare function redirectForCommand(command: string, available: ReadonlySet<string>, declaredCommands: ReadonlySet<string>): string | undefined;
 /**
  * Name the tool that serves the intent behind a denied VERB call.

package/dist/tools/denial-redirect.js

@@ -32,7 +32,7 @@ const GIT_COMMIT_VERBS = new Set(["add", "commit"]);
  * intent, so the refusal teaches instead of naming one (nax#2007).
  */
 const GIT_REVERT_VERBS = new Set(["checkout", "restore"]);
-const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
+export const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written by the harness during this run. It is not part of your diff and must not be reverted.";
 /**
  * The sentence explaining a revert of nax's own run state, or undefined.
  *
@@ -41,13 +41,13 @@ const NAX_OWNED_RUN_STATE_EXPLANATION = "`.nax/` is nax's own run state, written
  * module's header forbids naming one it does not hold. So this predicate is
  * checked BEFORE `intentFor` in both entry points and returns its own sentence.
  *
- * Verb scope is `checkout` and `restore` only; `git stash` is the agent's own
- * WIP, not nax's state, and has no operands to gate on. The gate is a `.nax`
+ * Verb scope is `checkout` and `restore` only; `git stash` has no operands to
+ * gate on and is handled by `nax-state-guard.ts` instead. The gate is a `.nax`
  * path SEGMENT (split on `/`), never a substring, so `src/nax-helpers.ts` and
  * `docs/.naxignore` stay unanswered. `--` is a separator, not an operand, and a
  * `timeout N` wrapper is stripped the same way `intentFor` strips it.
  */
-function naxOwnedRunStateExplanation(tokens) {
+export function naxOwnedRunStateExplanation(tokens) {
     const av = withoutTimeoutPrefix(tokens);
     const hasGitPrefix = av[0] === "git";
     const verb = hasGitPrefix ? av[1] : av[0];
@@ -142,7 +142,7 @@ function isSingleFileDelete(tokens, from) {
     return tokens.length === from + 1 && !tokens[from]?.startsWith("-");
 }
 /** A `timeout N ...` prefix wraps the real command; look past it. */
-function withoutTimeoutPrefix(tokens) {
+export function withoutTimeoutPrefix(tokens) {
     return tokens[0] === "timeout" ? tokens.slice(2) : tokens;
 }
 /**
@@ -211,23 +211,39 @@ export function redirectForArgv(argv, available, declaredCommands) {
 /**
  * Name the tool that serves the intent behind a denied Bash COMMAND.
  *
- * Reads the first segment only: that is what the model reached for, and a
- * later segment's intent is not what to teach when the call is refused. The
+ * The intent redirect reads the first segment only: that is what the model
+ * reached for, and a later segment's intent is not what to teach when the call
+ * is refused. The
  * split is deliberately its own crude one rather than the lexer's
  * (`lexBashCommand`): a command REFUSED for an unanalysable construct must
  * still get a redirect, and the lexer returns nothing to read in that case.
  */
-export function redirectForCommand(command, available, declaredCommands) {
-    const [first = ""] = command.split(/&&|\|\||;|\||\n/);
-    const tokens = first
+function tokenize(segment) {
+    return segment
         .trim()
         .split(/\s+/)
         .filter((token) => token.length > 0);
+}
+/**
+ * The crude segment split shared by the redirect and the raw screen's fallback
+ * for a command the lexer refused. Deliberately not the lexer: it must still
+ * produce segments when the lexer returns nothing to read.
+ */
+export function crudeCommandSegments(command) {
+    return command.split(/&&|\|\||;|\||\n/).map(tokenize);
+}
+export function redirectForCommand(command, available, declaredCommands) {
+    const segments = crudeCommandSegments(command);
+    // A revert of nax's run state is explained wherever it sits in a compound
+    // command (#2490); only the intent redirect below is first-segment-only.
+    for (const segment of segments) {
+        const ownedRunState = naxOwnedRunStateExplanation(segment);
+        if (ownedRunState !== undefined)
+            return ownedRunState;
+    }
+    const tokens = segments[0] ?? [];
     if (tokens.length === 0)
         return undefined;
-    const ownedRunState = naxOwnedRunStateExplanation(tokens);
-    if (ownedRunState !== undefined)
-        return ownedRunState;
     const hit = intentFor(tokens);
     if (hit === undefined)
         return taskRunnerFallback(tokens, available, declaredCommands);

package/dist/tools/git-flags/locate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function commandHeadIndex(words: readonly string[]): number;
+/** Find `git` in the executable position after supported wrappers. */
+export declare function gitExecutableIndex(words: readonly string[]): number | undefined;
+export interface LocatedGit {
+    readonly subcommand: string;
+    readonly args: readonly string[];
+    /**
+     * Values of `-C`, `--work-tree` and `--git-dir` (both `--key value` and
+     * `--key=value`) and of leading `GIT_WORK_TREE=` / `GIT_DIR=` assignments, in order.
+     */
+    readonly dirs: readonly string[];
+    /** True when an alias is defined through `--config-env=alias.*`: its value lives in the environment and cannot be read. */
+    readonly unresolvedAlias: boolean;
+    /** True when a global option this reader does not know sat before the subcommand: the subcommand found may be that option's value. */
+    readonly uncertain: boolean;
+    /** The shell text a `!` alias runs (its value without the `!`, then the call's remaining arguments), or undefined. */
+    readonly shellAlias: string | undefined;
+    /** Lower-cased keys set by `-c key=value` and `--config-env=key=VAR`, in order. */
+    readonly configKeys: readonly string[];
+    /** True when a leading assignment sets a `GIT_CONFIG*` variable (config, including aliases, injected through the environment). */
+    readonly configEnv: boolean;
+    /** True under `--literal-pathspecs` or a non-empty, non-`0` `GIT_LITERAL_PATHSPECS`: every `:(...)` / `:!` exclusion is a literal path. */
+    readonly literalPathspecs: boolean;
+}
+/**
+ * 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 declare function locateGit(words: readonly string[]): LocatedGit | undefined;