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

package/dist/tools/bash.d.ts

@@ -62,8 +62,14 @@ export interface BashToolOptions {
      */
     readonly launcher?: CommandLauncher;
 }
-/** Injectable spawn seam, mirroring `_argvExecDeps`. */
+/**
+ * Injectable spawn seam, mirroring `_argvExecDeps`, plus the platform seam
+ * US-006 added: it decides whether a description carries the macOS ps note, and
+ * exists so a test can pin both platforms without touching the global
+ * `process.platform`.
+ */
 export declare const _bashToolDeps: {
     runArgv: typeof runArgv;
+    platform: () => NodeJS.Platform;
 };
 export declare function createBashTool(opts?: BashToolOptions): CodingTool;

package/dist/tools/bash.js

@@ -37,9 +37,15 @@ export const BASH_TIMEOUT_MS = 300_000;
  * even start, and a 0 would disable the deadline entirely. */
 const MIN_BASH_TIMEOUT_MS = 1_000;
 export const DEFAULT_BASH_SHELL = "/bin/sh";
-/** Injectable spawn seam, mirroring `_argvExecDeps`. */
+/**
+ * Injectable spawn seam, mirroring `_argvExecDeps`, plus the platform seam
+ * US-006 added: it decides whether a description carries the macOS ps note, and
+ * exists so a test can pin both platforms without touching the global
+ * `process.platform`.
+ */
 export const _bashToolDeps = {
     runArgv,
+    platform: () => process.platform,
 };
 function describeGrants(patterns) {
     const named = (patterns ?? []).filter((pattern) => pattern !== "*");
@@ -124,6 +130,12 @@ function rawDescription(shell, containment = RAW_UNCONTAINED) {
         "A `find` whose start path is `/`, `~` or `$HOME` is refused -- search within the repository instead. " +
         BACKGROUND_PROCESSES_KILLED_SENTENCE);
 }
+/**
+ * US-006: no `sandboxSentence` here, deliberately. This variant describes a
+ * sandbox that is NOT running, so the darwin ps note -- which explains a
+ * refusal an AVAILABLE sandbox makes -- would be a false statement about this
+ * machine. The refusal names its own reason and that every call is refused.
+ */
 function rawUnavailableDescription(shell, reason) {
     return (`Run one shell command string under ${shell} -- but on this machine ${rawBashRefusalReason(reason)} ` +
         "Under raw mode every call is refused; use the structured tools (Read, Glob, Grep, Git, RunCommand) instead. " +
@@ -131,9 +143,12 @@ function rawUnavailableDescription(shell, reason) {
 }
 function bashToolDescription(shell, opts) {
     const state = opts.launcher?.state ?? { kind: "disabled" };
+    // US-006: read ONCE, so every `sandboxSentence` call site in this description
+    // agrees on the host's platform.
+    const platform = _bashToolDeps.platform();
     if (opts.bashApproval === "raw") {
         if (state.kind === "available")
-            return rawDescription(shell, `The command runs from the repository root ${sandboxSentence(state.network, state.sharedTmp !== false)} `);
+            return rawDescription(shell, `The command runs from the repository root ${sandboxSentence(state.network, state.sharedTmp !== false, platform)} `);
         if (state.kind === "unavailable")
             return rawUnavailableDescription(shell, state.reason);
         return rawDescription(shell);
@@ -148,7 +163,7 @@ function bashToolDescription(shell, opts) {
         ? escalateDescription(shell, opts.patterns)
         : gatedDescription(shell, opts.patterns);
     if (state.kind === "available") {
-        return `${policyDescription} Commands that pass run ${sandboxSentence(state.network, state.sharedTmp !== false)}`;
+        return `${policyDescription} Commands that pass run ${sandboxSentence(state.network, state.sharedTmp !== false, platform)}`;
     }
     if (state.kind === "unavailable")
         return `${policyDescription} ${unsandboxedSentence(state.reason)}`;

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;

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

@@ -15,6 +15,7 @@ export { gitExcludePathspecsOf, gitIgnorePatternsOf } from "./protected-paths.ts
 export * from "./provider-adapt.ts";
 export * from "./provider-advertise.ts";
 export * from "./provider-grants.ts";
+export * from "./provider-instructions.ts";
 export * from "./provider-sanitize.ts";
 export * from "./provider-types.ts";
 export { readTool } from "./read.ts";

package/dist/tools/index.js

@@ -12,6 +12,7 @@ export { gitExcludePathspecsOf, gitIgnorePatternsOf } from "./protected-paths.js
 export * from "./provider-adapt.js";
 export * from "./provider-advertise.js";
 export * from "./provider-grants.js";
+export * from "./provider-instructions.js";
 export * from "./provider-sanitize.js";
 export * from "./provider-types.js";
 export { readTool } from "./read.js";

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;