@nathapp/nax-agent 0.1.0

package/dist/sandbox/git-guards.js

@@ -0,0 +1,161 @@
+/**
+ * The I/O half of the sandbox's git guards (#2198): the git-read files that
+ * redirect where git finds its config and hooks, as they exist on disk now.
+ *
+ * A sandboxed command that repoints one of these at an agent-authored
+ * directory (its own `config` with core.hooksPath / core.fsmonitor) makes
+ * nax's next UNSANDBOXED git run agent code. The redirecting files are:
+ * `<common>/commondir`, and for every linked worktree `worktrees/<id>/`
+ * `{gitdir, commondir, config.worktree}` plus the worktree's `.git` pointer.
+ *
+ * Only files that EXIST are denied here: srt on Linux stubs an absent deny
+ * with an empty file (host-side too, while the command runs), and git dies
+ * reading an empty `commondir` / `gitdir` -- inside the sandbox and in any
+ * concurrent nax git. An absent `<common>/commondir` is therefore guarded by
+ * a tripwire instead (strayCommonDirTripwire). `config.worktree` is the
+ * exception: an empty one is valid config, so it is always denied.
+ *
+ * The tripwire is what protects a main checkout, whose git dir sits inside the
+ * root write root. In a linked worktree the common dir is not a write root at
+ * all (WORKTREE_COMMON_WRITE_DIRS, #2211), so the file cannot be created there
+ * and the tripwire is only a second line.
+ */
+import { lstat, readdir, readFile, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { realOrRaw } from "#src/internal/realpath";
+import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
+const WORKTREES_DIR = "worktrees";
+const COMMONDIR_FILE = "commondir";
+const GITDIR_FILE = "gitdir";
+export const WORKTREE_CONFIG_FILE = "config.worktree";
+/**
+ * What a linked worktree's git writes in the SHARED common dir (#2211): loose
+ * and packed objects, refs and their reflogs (`reftable/` holds both when
+ * `extensions.refStorage=reftable`, git >= 2.45), and git-lfs's object store.
+ * Only these are write roots, never the common dir itself, so the redirecting
+ * files at its top level (`commondir`, `config`, `hooks/`) and every sibling
+ * worktree's admin dir lie outside the sandbox's writes. `modules/` is left
+ * out on purpose: it holds submodule git dirs, each with its own config.
+ *
+ * Cost: a lock file at the common dir's top level cannot be created, so a
+ * sandboxed command cannot rewrite `packed-refs` (deleting a packed branch or
+ * tag) or take the `gc --auto` lock; commits, loose ref updates and fetches
+ * into loose objects are unaffected. (A reftable repo locks inside
+ * `reftable/`, so it keeps ref deletion too.)
+ */
+export const WORKTREE_COMMON_WRITE_DIRS = ["objects", "refs", "logs", "reftable", "lfs"];
+const DOT_GIT = ".git";
+export const _gitGuardDeps = {
+    readdir,
+    exists: async (p) => {
+        try {
+            await lstat(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    readText: (p) => readFile(p, "utf8"),
+    remove: (p) => rm(p, { recursive: true, force: true }),
+};
+/** The directory holding the shared config/hooks: the git dir itself for a main checkout. */
+export function commonDirOf(git) {
+    if (git.kind === "none")
+        return undefined;
+    return git.kind === "worktree" ? git.commonDir : git.gitDir;
+}
+/** A glob-named path would make every policy build throw (F1), so it is skipped, not emitted. */
+function isLiteral(p) {
+    return !SANDBOX_GLOB_CHARS.test(realOrRaw(p));
+}
+/**
+ * The `<wt>/.git` pointer a `gitdir` file names -- only a literal `.git` path.
+ *
+ * git >= 2.48 with `worktree.useRelativePaths` (or `worktree add
+ * --relative-paths`) writes it relative to the admin dir `<common>/worktrees/<id>`
+ * -- computed from that dir's realpath, and read back by joining onto it -- so a
+ * relative target resolves against the admin dir's realpath. Resolving against
+ * the unresolved spelling would walk `..` lexically and miss a symlinked
+ * common dir.
+ */
+async function pointerOf(gitdirFile) {
+    try {
+        const raw = (await _gitGuardDeps.readText(gitdirFile)).trim();
+        if (raw === "")
+            return [];
+        const target = isAbsolute(raw) ? raw : resolve(realOrRaw(dirname(gitdirFile)), raw);
+        return basename(target) === DOT_GIT && isLiteral(target) ? [target] : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function existing(paths) {
+    const present = await Promise.all(paths.map((p) => _gitGuardDeps.exists(p)));
+    return paths.filter((_, i) => present[i]);
+}
+async function worktreeEntryFiles(adminDir) {
+    const gitdirFile = join(adminDir, GITDIR_FILE);
+    const pointers = await existing([gitdirFile, join(adminDir, COMMONDIR_FILE), ...(await pointerOf(gitdirFile))]);
+    return [...pointers, join(adminDir, WORKTREE_CONFIG_FILE)];
+}
+/**
+ * Every redirecting git file for the repo that `git` describes, for every
+ * worktree registered when the policy is built (literal paths: srt on Linux
+ * drops glob denies).
+ */
+export async function listGitGuardFiles(git) {
+    const common = commonDirOf(git);
+    if (common === undefined)
+        return [];
+    const worktrees = join(common, WORKTREES_DIR);
+    let names = [];
+    try {
+        const entries = await _gitGuardDeps.readdir(worktrees, { withFileTypes: true });
+        names = entries.filter((e) => e.isDirectory() && isLiteral(join(worktrees, e.name))).map((e) => e.name);
+    }
+    catch {
+        // no linked worktrees
+    }
+    const perWorktree = await Promise.all(names.map((name) => worktreeEntryFiles(join(worktrees, name))));
+    // Filtered again as a whole: an agent-made symlink can resolve a literal name to a glob path.
+    return [...(await existing([join(common, COMMONDIR_FILE)])), ...perWorktree.flat()].filter(isLiteral);
+}
+/**
+ * `<common>/commondir` never legitimately exists (git reads it only from a
+ * linked worktree's own git dir), and an absent one cannot be denied on Linux
+ * (see the header). So when it is absent at session start, one created by a
+ * sandboxed command is removed after that command, before nax's next git.
+ * Returns undefined when there is nothing to guard (no repo, or the file
+ * already exists -- listGitGuardFiles then denies it outright).
+ */
+export async function strayCommonDirTripwire(git, storyId) {
+    const common = commonDirOf(git);
+    if (common === undefined)
+        return undefined;
+    const target = join(common, COMMONDIR_FILE);
+    if (await _gitGuardDeps.exists(target))
+        return undefined;
+    return async () => {
+        if (!(await _gitGuardDeps.exists(target)))
+            return;
+        const logger = getSafeLogger();
+        try {
+            await _gitGuardDeps.remove(target);
+            logger?.error("sandbox", "A sandboxed command created a git commondir redirect; removed it", {
+                storyId,
+                path: target,
+            });
+        }
+        catch (err) {
+            logger?.error("sandbox", "A sandboxed command created a git commondir redirect that could not be removed", {
+                storyId,
+                path: target,
+                error: errorMessage(err),
+            });
+        }
+    };
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,11 @@
+export { quoteArgvForShell } from "./argv-quote.ts";
+export { _gitGuardDeps, listGitGuardFiles, strayCommonDirTripwire } from "./git-guards.ts";
+export { _launcherDeps, type CommandLauncherOptions, createCommandLauncher, DISABLED_SANDBOX_STATE, } from "./launcher.ts";
+export { denialHintLine, LIKELY_SANDBOX_DENIAL, rawBashRefusalReason, sandboxSentence, unsandboxedSentence, } from "./messages.ts";
+export { buildSandboxPolicy, type SandboxPolicyInput } from "./policy-builder.ts";
+export { _policyInputDeps, defaultTempRoots, type GitLayout, listCredentialFiles, listNaxEntries, resolveGitLayout, runTempRoots, } from "./policy-inputs.ts";
+export { _probeDeps, probeSandbox } from "./probe.ts";
+export { _resetSandboxRegistryForTests, _sandboxRegistryDeps, probeSandboxOnce, resetSandboxBackend, sandboxBackendFor, warnSandboxUnavailableOnce, } from "./registry.ts";
+export { _sessionTmpDeps, runTmpRoot, sessionTmpDir, sessionTmpDirUnder } from "./session-tmp.ts";
+export { _srtBackendDeps, createSrtBackend } from "./srt-backend.ts";
+export type { CommandLauncher, LaunchRequest, LaunchResult, LaunchSpec, ProbeResult, SandboxBackend, SandboxBackendName, SandboxNetworkPolicy, SandboxPolicy, SandboxRecord, SandboxState, SandboxWrapRequest, } from "./types.ts";

package/dist/sandbox/index.js

@@ -0,0 +1,10 @@
+export { quoteArgvForShell } from "./argv-quote.js";
+export { _gitGuardDeps, listGitGuardFiles, strayCommonDirTripwire } from "./git-guards.js";
+export { _launcherDeps, createCommandLauncher, DISABLED_SANDBOX_STATE, } from "./launcher.js";
+export { denialHintLine, LIKELY_SANDBOX_DENIAL, rawBashRefusalReason, sandboxSentence, unsandboxedSentence, } from "./messages.js";
+export { buildSandboxPolicy } from "./policy-builder.js";
+export { _policyInputDeps, defaultTempRoots, listCredentialFiles, listNaxEntries, resolveGitLayout, runTempRoots, } from "./policy-inputs.js";
+export { _probeDeps, probeSandbox } from "./probe.js";
+export { _resetSandboxRegistryForTests, _sandboxRegistryDeps, probeSandboxOnce, resetSandboxBackend, sandboxBackendFor, warnSandboxUnavailableOnce, } from "./registry.js";
+export { _sessionTmpDeps, runTmpRoot, sessionTmpDir, sessionTmpDirUnder } from "./session-tmp.js";
+export { _srtBackendDeps, createSrtBackend } from "./srt-backend.js";

package/dist/sandbox/launcher.d.ts

@@ -0,0 +1,37 @@
+import { runArgv } from "#src/internal/argv-exec";
+import type { CommandLauncher, SandboxBackend, SandboxPolicy, SandboxState } from "./types.ts";
+export declare const DISABLED_SANDBOX_STATE: SandboxState;
+export declare const _launcherDeps: {
+    runArgv: typeof runArgv;
+    newCommandId: () => string;
+    mkdir: (path: string) => Promise<void>;
+};
+export interface CommandLauncherOptions {
+    readonly state: SandboxState;
+    readonly backend?: SandboxBackend;
+    /**
+     * Build the policy for one command.
+     *
+     * `tmpDirInForce` says whether THIS command gets the session's own `TMPDIR`
+     * override: the launcher declared a `tmpDir` and the per-run `ensureTmpDir`
+     * recreated it, so `runWrapped` will apply the `export TMPDIR=…` prefix. It is
+     * false when the override is dropped, and srt's own forced `TMPDIR` applies
+     * instead — a builder that denies that directory would then hand the session a
+     * `TMPDIR` its own sandbox refuses to write (#2301, SPEC-tmp-confinement.md:132).
+     *
+     * Reported separately from `state` on purpose: `state.sharedTmp === false` is
+     * the construction-time answer (did the session RESOLVE as confined) and never
+     * changes, while this is re-decided on every run. A session dir that recreates
+     * for one run and not the next is confined by the first and not the second.
+     */
+    readonly policyFor?: (root: string, tmpDirInForce: boolean) => Promise<SandboxPolicy>;
+    /** Runs after every wrapped command, before control returns to nax (e.g. a git tripwire, #2198). */
+    readonly afterWrapped?: () => Promise<void>;
+    /**
+     * US-004 — the session's temp directory. Created before every run, then handed
+     * to the child as `TMPDIR`/`TMP`/`TEMP` so stray files land under the run's own
+     * root instead of the shared `/tmp`.
+     */
+    readonly tmpDir?: string;
+}
+export declare function createCommandLauncher(opts: CommandLauncherOptions): CommandLauncher;

package/dist/sandbox/launcher.js

@@ -0,0 +1,160 @@
+/**
+ * How an agent-authored command runs (spec 5.1). Never WHETHER -- that is the
+ * policy's call (single-gate rule). Handed only to Bash and RunCommand's Exec
+ * branch, so a user-authored command can never be wrapped (D14).
+ *
+ * Two rules with teeth:
+ * - F6: the backend returns argv only; runArgv receives the CALLER's env
+ *   overlay and strips from process.env exactly as today.
+ * - A wrap that throws is an error. The command never runs unwrapped: what
+ *   stops is the command, never the sandbox.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger, NaxError } from "#src/infra/index";
+import { runArgv } from "#src/internal/argv-exec";
+import { quoteArgvForShell } from "./argv-quote.js";
+import { denialHintLine, LIKELY_SANDBOX_DENIAL } from "./messages.js";
+export const DISABLED_SANDBOX_STATE = { kind: "disabled" };
+export const _launcherDeps = {
+    runArgv,
+    newCommandId: () => randomUUID(),
+    mkdir: (path) => mkdir(path, { recursive: true }).then(() => undefined),
+};
+function logicalArgv(req) {
+    return req.spec.kind === "shell" ? [req.spec.shell, "-c", req.spec.command] : req.spec.argv;
+}
+/** POSIX single-quoting: wrap in `'`, turning an embedded `'` into `'\''`. */
+function shellSingleQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** `export TMPDIR=… TMP=… TEMP=…; ` — the prefix a wrapped command carries, since srt replaces the child env. */
+function tmpEnvPrefix(tmpDir) {
+    const q = shellSingleQuote(tmpDir);
+    return `export TMPDIR=${q} TMP=${q} TEMP=${q}; `;
+}
+/** The TMPDIR/TMP/TEMP overlay for an unwrapped run; the request's own env wins per key. */
+function withTmpEnv(req, tmpDir) {
+    if (tmpDir === undefined)
+        return req.env;
+    return { TMPDIR: tmpDir, TMP: tmpDir, TEMP: tmpDir, ...(req.env ?? {}) };
+}
+async function ensureTmpDir(tmpDir) {
+    try {
+        await _launcherDeps.mkdir(tmpDir);
+        return true;
+    }
+    catch (err) {
+        getSafeLogger()?.warn("sandbox", "could not create session temp dir — running without TMPDIR override", {
+            tmpDir,
+            error: errorMessage(err),
+        });
+        return false;
+    }
+}
+async function runUnwrapped(req, sandbox, env) {
+    const argv = logicalArgv(req);
+    const overlay = env.tmpDir !== undefined ? withTmpEnv(req, env.tmpDir) : req.env;
+    const result = await _launcherDeps.runArgv({
+        argv,
+        cwd: req.cwd,
+        timeoutMs: req.timeoutMs,
+        stripEnvVars: [...req.stripEnvVars],
+        ...(overlay !== undefined ? { env: overlay } : {}),
+        ...(req.signal !== undefined ? { signal: req.signal } : {}),
+    });
+    return { ...result, executed: argv, sandbox };
+}
+async function runWrapped(req, backend, policy, env) {
+    const rawCommand = req.spec.kind === "shell" ? req.spec.command : quoteArgvForShell(req.spec.argv);
+    // srt replaces the child environment wholesale, so a TMPDIR override cannot
+    // ride an `env` overlay — it has to be part of the shell command itself.
+    // Other overlay keys DO survive: the live suite proves it (`AGENT=1` reaches
+    // a wrapped child — see test/integration/sandbox/sandbox-live.test.ts
+    // "US-004 — the AGENT=1 overlay reaches a wrapped child"). `executed` below
+    // stays the unprefixed logical argv, so the ledger records what the agent
+    // wrote, not this shim.
+    const command = env.tmpDir !== undefined ? `${tmpEnvPrefix(env.tmpDir)}${rawCommand}` : rawCommand;
+    const shell = req.spec.kind === "shell" ? req.spec.shell : "/bin/sh";
+    const commandId = _launcherDeps.newCommandId();
+    let argv;
+    try {
+        argv = await backend.wrap({ command, shell, policy, cwd: req.cwd, commandId });
+    }
+    catch (err) {
+        throw new NaxError(`[sandbox] could not wrap the command: ${errorMessage(err)}`, "SANDBOX_WRAP_FAILED", {
+            stage: "sandbox",
+            backend: backend.name,
+            commandId,
+            cause: err,
+        });
+    }
+    try {
+        const result = await _launcherDeps.runArgv({
+            argv,
+            cwd: req.cwd,
+            timeoutMs: req.timeoutMs,
+            stripEnvVars: [...req.stripEnvVars],
+            ...(req.env !== undefined ? { env: req.env } : {}),
+            ...(req.signal !== undefined ? { signal: req.signal } : {}),
+        });
+        const denied = result.exitCode !== 0 && LIKELY_SANDBOX_DENIAL.test(result.stderr);
+        const violations = backend.annotate(commandId, result.stderr);
+        const extra = [
+            ...(denied ? [denialHintLine(policy.writeRoots, env.sharedTmp)] : []),
+            ...(violations !== "" ? [violations] : []),
+        ];
+        return {
+            ...result,
+            stderr: extra.length > 0 ? `${result.stderr}\n${extra.join("\n")}` : result.stderr,
+            executed: logicalArgv(req),
+            sandbox: {
+                backend: backend.name,
+                wrapped: true,
+                argv,
+                ...(denied ? { denialHint: true } : {}),
+            },
+        };
+    }
+    finally {
+        backend.commandFinished();
+    }
+}
+export function createCommandLauncher(opts) {
+    const { state } = opts;
+    const env = {
+        tmpDir: opts.tmpDir,
+        // A confined session's denial hint points at $TMPDIR instead of /tmp; a
+        // shared-temp session's hint must not contradict the policy it runs under.
+        sharedTmp: state.kind !== "available" || state.sharedTmp !== false,
+    };
+    return {
+        state,
+        async run(req) {
+            const tmpDir = env.tmpDir !== undefined && (await ensureTmpDir(env.tmpDir)) ? env.tmpDir : undefined;
+            if (state.kind === "disabled")
+                return runUnwrapped(req, { backend: "none", wrapped: false }, { ...env, tmpDir });
+            if (state.kind === "unavailable") {
+                return runUnwrapped(req, { backend: state.backend, wrapped: false, reason: state.reason }, { ...env, tmpDir });
+            }
+            if (opts.backend === undefined || opts.policyFor === undefined) {
+                throw new NaxError("[sandbox] an available launcher needs a backend and a policy", "SANDBOX_NOT_CONFIGURED", {
+                    stage: "sandbox",
+                });
+            }
+            try {
+                // `runWrapped` is handed this same `tmpDir` and applies the
+                // `export TMPDIR=…` prefix only when it is defined, so `tmpDir !== undefined`
+                // is exactly the "the override is in force for this command" fact.
+                return await runWrapped(req, opts.backend, await opts.policyFor(req.root, tmpDir !== undefined), {
+                    ...env,
+                    tmpDir,
+                });
+            }
+            finally {
+                await opts.afterWrapped?.();
+            }
+        },
+    };
+}

package/dist/sandbox/messages.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Every sentence the agent reads about the sandbox (spec 5.5), in one place so
+ * descriptions, refusals and result notes cannot drift apart. The agent must
+ * always know whether it is sandboxed and what it may write (spec S5).
+ */
+export declare const LIKELY_SANDBOX_DENIAL: RegExp;
+export declare function sandboxSentence(network: "open" | readonly string[], sharedTmp?: boolean): string;
+export declare function unsandboxedSentence(reason: string): string;
+export declare function rawBashRefusalReason(reason: string): string;
+/**
+ * US-003: the denial path is exactly where an agent discovers the sandbox
+ * refuses a `/tmp` write, so the hint names the two roots that do work -- the
+ * session temp dir and the scratchpad -- rather than only listing the policy's
+ * write roots. A shared-temp session (`allowSharedTmp: true`) can write `/tmp`,
+ * so its hint omits the "not /tmp" clause that would contradict its policy.
+ */
+export declare function denialHintLine(writeRoots: readonly string[], sharedTmp?: boolean): string;

package/dist/sandbox/messages.js

@@ -0,0 +1,46 @@
+/**
+ * Every sentence the agent reads about the sandbox (spec 5.5), in one place so
+ * descriptions, refusals and result notes cannot drift apart. The agent must
+ * always know whether it is sandboxed and what it may write (spec S5).
+ */
+export const LIKELY_SANDBOX_DENIAL = /Operation not permitted|Read-only file system/;
+function describeNetwork(network) {
+    if (network === "open")
+        return "network access is unrestricted";
+    if (network.length === 0)
+        return "network access is disabled";
+    return `network access is limited to ${network.join(", ")}`;
+}
+/**
+ * US-003: the writable temp root the sentence advertises. A confined session
+ * (`sharedTmp: false`) can only write under the run's own temp directory, so
+ * promising "the system temp directories" would send the agent at a denied
+ * write; a shared-temp session keeps the wording it had before.
+ */
+const tempRootsPhrase = (sharedTmp) => sharedTmp ? "the system temp directories" : "this run's temp directory ($TMPDIR)";
+export function sandboxSentence(network, sharedTmp = true) {
+    return (`inside an OS sandbox: writes are allowed only under the repository root, ${tempRootsPhrase(sharedTmp)} and ` +
+        "package-manager caches -- and nothing under .nax/ except .nax/scratchpad/, since .nax/ is nax's own state " +
+        "(change a feature's acceptance test with the Edit tool); credential files (~/.ssh, ~/.aws, ~/.npmrc, nax credentials and similar) are unreadable; " +
+        `${describeNetwork(network)}. A write anywhere else fails with "Operation not permitted" or "Read-only file system" ` +
+        "-- that is the sandbox, not a bug in your command.");
+}
+export function unsandboxedSentence(reason) {
+    return `Commands are NOT sandboxed on this machine (${reason}).`;
+}
+export function rawBashRefusalReason(reason) {
+    return (`sandbox unavailable (${reason}): raw bash requires the sandbox when execution.sandbox.enabled is true -- ` +
+        "set this stage's bashApproval to gated or escalate, or disable the sandbox.");
+}
+/**
+ * US-003: the denial path is exactly where an agent discovers the sandbox
+ * refuses a `/tmp` write, so the hint names the two roots that do work -- the
+ * session temp dir and the scratchpad -- rather than only listing the policy's
+ * write roots. A shared-temp session (`allowSharedTmp: true`) can write `/tmp`,
+ * so its hint omits the "not /tmp" clause that would contradict its policy.
+ */
+export function denialHintLine(writeRoots, sharedTmp = false) {
+    const tempClause = sharedTmp ? "" : " For temporary files use $TMPDIR or .nax/scratchpad/, not /tmp.";
+    return (`note: this command ran in the nax sandbox; that failure may be a sandbox denial -- writable roots: ${writeRoots.join(", ")}.` +
+        tempClause);
+}

package/dist/sandbox/policy-builder.d.ts

@@ -0,0 +1,44 @@
+import { type SandboxConfig } from "../config/schemas-sandbox.ts";
+import type { GitLayout } from "./policy-inputs.ts";
+import type { SandboxPolicy } from "./types.ts";
+export interface SandboxPolicyInput {
+    readonly root: string;
+    readonly git: GitLayout;
+    /** Redirecting git files present now, every worktree included (listGitGuardFiles, #2198). */
+    readonly gitGuardFiles: readonly string[];
+    /** Top-level entry names under `<root>/.nax` right now (listNaxEntries). */
+    readonly naxEntries: readonly string[];
+    readonly credentialFiles: readonly string[];
+    readonly approvalsFile?: string;
+    /** US-006 — the trust store (`trustStorePath()`), denied so a command cannot rewrite its own trust. */
+    readonly trustStoreFile?: string;
+    readonly home: string;
+    readonly tempRoots: readonly string[];
+    /**
+     * #2301: whether THIS command's temp writes stay confined — the RESOLVE-time
+     * answer ANDed with the fact that this launch's `TMPDIR` override is in force.
+     *
+     * It governs srt's forced TMPDIR on BOTH sides, not only the deny. On darwin,
+     * `true` drops `/tmp/claude` from `writeRoots` and adds both of its spellings
+     * to `denyWrite`; `false` does the reverse, so a command that did not confine
+     * keeps `/tmp/claude` writable as a plain grant. `input.tempRoots` is passed
+     * through either way: the flag moves srt's `/tmp/claude` grant, never the
+     * session's own temp roots.
+     *
+     * Deliberately NOT the value behind `SandboxState.sharedTmp === false` or
+     * `isTempConfined`. Those are the resolve-time answer, fixed when the launcher
+     * is built, while this is re-decided on every launch by ANDing that answer with
+     * whether the session temp dir was re-created. The two are MEANT to disagree: a
+     * session whose dir fails to re-create keeps `sharedTmp: false` and
+     * `isTempConfined() === true` while this reads `false` for that one command. Do
+     * not reconcile them by making either one follow the other.
+     *
+     * Absent means it confined neither way, so every construction outside
+     * `resolveSessionSandbox` keeps today's behaviour; the only other builder in
+     * the tree, the probe, writes its policy as a literal and never reaches here.
+     */
+    readonly confined?: boolean;
+    readonly platform: NodeJS.Platform;
+    readonly config: SandboxConfig;
+}
+export declare function buildSandboxPolicy(input: SandboxPolicyInput): SandboxPolicy;

package/dist/sandbox/policy-builder.js

@@ -0,0 +1,149 @@
+/**
+ * Pure: everything the sandbox allows and denies for one command (spec 5.3).
+ *
+ * Rebuilt per call so a `.nax/` entry created mid-run gets its deny (nax#2260).
+ * Every emitted path goes through realOrRaw -- srt realpaths only paths
+ * that exist, so a deny for a not-yet-created file under a symlinked temp dir
+ * would otherwise keep a spelling the kernel never sees (spec 12, finding 3).
+ */
+import { isAbsolute, join, resolve } from "node:path";
+import { NaxError } from "#src/infra/index";
+import { realOrRaw } from "#src/internal/realpath";
+import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
+import { NAX_ALWAYS_DENIED_ENTRIES, NAX_SCRATCHPAD_ENTRY, naxWriteOptIns, QUEUE_CONTROL_FILES, } from "../tools/nax-owned-writes.js";
+import { BUILTIN_CACHE_WRITE_ROOTS, BUILTIN_CREDENTIAL_READ_DENIES, MACOS_CACHE_WRITE_ROOT, SRT_MACOS_TMPDIR, SRT_MACOS_TMPDIR_DENIES, } from "./defaults.js";
+import { WORKTREE_COMMON_WRITE_DIRS, WORKTREE_CONFIG_FILE } from "./git-guards.js";
+function expandHome(p, home) {
+    if (p === "~")
+        return home;
+    return p.startsWith("~/") ? join(home, p.slice(2)) : p;
+}
+/** Throws on a glob: a Linux backend would drop it silently (F1), so fail closed instead. */
+function literal(paths) {
+    const resolved = [...new Set(paths.map((p) => realOrRaw(p)))];
+    const glob = resolved.find((p) => SANDBOX_GLOB_CHARS.test(p));
+    if (glob !== undefined) {
+        throw new NaxError(`[sandbox] policy path is not literal (glob character): ${glob}`, "SANDBOX_POLICY_NOT_LITERAL", {
+            stage: "sandbox",
+            path: glob,
+        });
+    }
+    return resolved;
+}
+function gitDenies(root, git) {
+    if (git.kind === "none")
+        return [];
+    const common = git.kind === "worktree" ? git.commonDir : git.gitDir;
+    // config.worktree is read when extensions.worktreeConfig is on; an absent one
+    // is safe to deny (srt stubs it empty, and empty is valid config) (#2198).
+    const shared = [join(common, "hooks"), join(common, "config"), join(common, WORKTREE_CONFIG_FILE)];
+    if (git.kind === "main")
+        return shared;
+    // A worktree's `.git` is a pointer FILE, and gitdir/commondir point back;
+    // repointing any of them at an agent-written config (core.hooksPath) would
+    // make nax's own unsandboxed git run hooks (spec 12, finding 4).
+    return [
+        ...shared,
+        join(root, ".git"),
+        join(git.gitDir, "gitdir"),
+        join(git.gitDir, "commondir"),
+        join(git.gitDir, WORKTREE_CONFIG_FILE),
+    ];
+}
+/**
+ * A worktree's own admin dir plus the shared subdirs its git writes -- never
+ * the whole common dir, whose top-level `commondir` would otherwise be a live
+ * redirect for concurrent unsandboxed git while the command runs (#2211).
+ * srt skips a write root that does not exist yet.
+ */
+function worktreeGitWriteRoots(git) {
+    if (git.kind !== "worktree")
+        return [];
+    return [git.gitDir, ...WORKTREE_COMMON_WRITE_DIRS.map((dir) => join(git.commonDir, dir))];
+}
+/**
+ * nax#2260: every top-level `.nax/` entry, whole, plus the ones nax reads even
+ * when absent -- except the scratchpad and entries opted in via allowWrite.
+ * srt applies deny over allow and on Linux turns every literal deny into a
+ * bind mount, so whole entries (one `features` deny, not one per PRD) keep
+ * both the protection and the per-command cost bounded.
+ *
+ * Only `<root>/.nax` is covered. A monorepo package's own `.nax/`
+ * (`packages/<pkg>/.nax/`) is deliberately excluded: what lives there --
+ * cache/, scratchpad/, status.json, the features' acceptance tests and run
+ * artifacts -- is gitignored and rebuilt or regenerated, so deleting it is
+ * harmless, and the package's config sits under the root's protected `mono/`.
+ * The exception is an optional `packages/<pkg>/.nax/rules/`, which nax loads
+ * into prompts; covering it needs package discovery, because a `.nax/` at any
+ * depth also matches test-fixture projects (`test/fixtures/<p>/.nax/`).
+ */
+function naxDenies(root, entries, allowWrite) {
+    const optIns = naxWriteOptIns(root, allowWrite);
+    return [...new Set([...entries, ...NAX_ALWAYS_DENIED_ENTRIES])]
+        .filter((name) => name !== NAX_SCRATCHPAD_ENTRY && !optIns.has(name))
+        .map((name) => join(root, ".nax", name));
+}
+export function buildSandboxPolicy(input) {
+    const { root, home, config } = input;
+    const darwin = input.platform === "darwin";
+    // #2301: a CONFINED session does not need srt's forced TMPDIR. srt always
+    // allows `/tmp/claude` (`SANDBOX_OWN_WRITE_PATHS`) and hands the child a
+    // `TMPDIR` of `/tmp/claude` (sandbox-utils.js:630), and in a macOS Seatbelt
+    // profile it renders the allow rules before the deny rules, where the later deny
+    // wins — so the only way to take the write back is an explicit deny, which is
+    // what a confined session gets.
+    //
+    // Both spellings, because `realOrRaw` resolves the nearest EXISTING ancestor and
+    // `/tmp` exists: on a stock macOS host `/tmp` is a symlink to `/private/tmp`, so
+    // `literal()` collapses the pair to one entry and it costs nothing there. The
+    // pair still matters on a host where `/tmp` is a real directory, or a symlink
+    // somewhere other than `/private/tmp`: there the two resolve apart and a single
+    // spelling would leave srt's other one writable.
+    //
+    // Nothing needs the grant instead: a session is confined only when it HAS a temp
+    // dir, and `runWrapped` prefixes the command with
+    // `export TMPDIR=<that dir> TMP=… TEMP=…` (src/sandbox/launcher.ts:138),
+    // replacing srt's value before the agent's command runs. That prefix rides on
+    // `createCommandLauncher`'s per-run mkdir (src/sandbox/launcher.ts:194), so it is
+    // conditional — when the mkdir fails the override is dropped and the agent's
+    // `TMPDIR` is srt's `/tmp/claude` again, which is why that case needs deciding
+    // before a deny can be relied on.
+    //
+    // A session that did NOT confine keeps the grant: its temp roots are
+    // `defaultTempRoots`, which allows `/tmp` outright, so `/tmp/claude` is inside an
+    // allowed root anyway and a deny would contradict the session's own denial hint
+    // (`denialHintLine`).
+    //
+    // darwin only, deliberately: srt's `SANDBOX_OWN_WRITE_PATHS` is
+    // platform-independent, so a confined LINUX session still gets `/tmp/claude`.
+    // Left open on purpose — on bwrap a literal deny becomes a bind mount, a
+    // different mechanism that needs its own check before a deny is added there.
+    const confined = input.confined === true;
+    const writeRoots = literal([
+        root,
+        ...worktreeGitWriteRoots(input.git),
+        ...input.tempRoots,
+        ...(darwin ? [...(confined ? [] : [SRT_MACOS_TMPDIR]), join(home, MACOS_CACHE_WRITE_ROOT)] : []),
+        ...BUILTIN_CACHE_WRITE_ROOTS.map((rel) => join(home, rel)),
+        ...config.filesystem.allowWrite.map((p) => {
+            const expanded = expandHome(p, home);
+            return isAbsolute(expanded) ? expanded : resolve(root, expanded);
+        }),
+    ]);
+    const denyWrite = literal([
+        ...naxDenies(root, input.naxEntries, config.filesystem.allowWrite),
+        ...[...QUEUE_CONTROL_FILES].map((name) => join(root, name)),
+        ...gitDenies(root, input.git),
+        ...input.gitGuardFiles,
+        ...(input.approvalsFile !== undefined ? [input.approvalsFile] : []),
+        ...(input.trustStoreFile !== undefined ? [input.trustStoreFile] : []),
+        ...(darwin && confined ? SRT_MACOS_TMPDIR_DENIES : []),
+    ]);
+    const denyRead = literal([
+        ...BUILTIN_CREDENTIAL_READ_DENIES.map((rel) => join(home, rel)),
+        ...input.credentialFiles,
+        ...config.filesystem.denyRead.map((p) => resolve(root, expandHome(p, home))),
+    ]);
+    const allowed = config.network.allowedDomains;
+    return { writeRoots, denyWrite, denyRead, network: allowed === undefined ? {} : { allowedDomains: [...allowed] } };
+}