@nathapp/nax-agent 0.1.0

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

@@ -0,0 +1,53 @@
+/**
+ * The I/O half of the sandbox policy: what exists on disk right now.
+ * Kept apart from policy-builder.ts so the builder stays pure.
+ */
+import { readdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+export type GitLayout = {
+    readonly kind: "none";
+} | {
+    readonly kind: "main";
+    readonly gitDir: string;
+} | {
+    readonly kind: "worktree";
+    readonly gitDir: string;
+    readonly commonDir: string;
+};
+export declare const _policyInputDeps: {
+    git: (args: string[], cwd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        timedOut?: boolean;
+    }>;
+    readdir: typeof readdir;
+    homedir: typeof homedir;
+    tmpdir: typeof tmpdir;
+    platform: () => NodeJS.Platform;
+};
+/** Resolved once per session. A worktree's git dir differs from its common dir. */
+export declare function resolveGitLayout(root: string): Promise<GitLayout>;
+/**
+ * Top-level entry names under `<root>/<stateDir>` right now (nax#2260;
+ * `stateDir` is `.nax` for nax). An entry with a glob character is skipped:
+ * nax never creates one, and a glob in the policy would make every build
+ * throw (F1) -- an agent could otherwise switch the sandbox off by creating
+ * `.nax/a*b`.
+ */
+export declare function listNaxEntries(root: string, stateDir: string): Promise<string[]>;
+/** Every `credentials*` file in `dir` (the host's credential dir), expanded to literals (F1: no globs). */
+export declare function listCredentialFiles(dir: string): Promise<string[]>;
+/** `os.tmpdir()` plus `/tmp` (Linux tools fall back to it; srt sets no TMPDIR there -- spec F3). */
+export declare function defaultTempRoots(): string[];
+/**
+ * US-002: the temp roots a CONFINED session gets -- the run's own root, plus
+ * the host tmpdir only when that is not the shared one. `os.tmpdir()` is
+ * `/tmp` on most Linux hosts and keeping it would re-grant exactly the shared
+ * directory the confinement exists to remove; a tmpdir of `/private/tmp` is
+ * the same directory seen through macOS's symlink.
+ */
+export declare function runTempRoots(opts: {
+    runTmpRoot: string;
+    tmpdir: string;
+}): string[];

package/dist/sandbox/policy-inputs.js

@@ -0,0 +1,76 @@
+/**
+ * The I/O half of the sandbox policy: what exists on disk right now.
+ * Kept apart from policy-builder.ts so the builder stays pure.
+ */
+import { readdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { gitWithTimeout } from "#src/internal/git-exec";
+import { realOrRaw } from "#src/internal/realpath";
+import { SANDBOX_GLOB_CHARS } from "../config/schemas-sandbox.js";
+const GIT_LAYOUT_TIMEOUT_MS = 10_000;
+export const _policyInputDeps = {
+    git: (args, cwd) => gitWithTimeout(args, cwd, GIT_LAYOUT_TIMEOUT_MS),
+    readdir,
+    homedir,
+    tmpdir,
+    platform: () => process.platform,
+};
+async function gitPath(flag, root) {
+    const r = await _policyInputDeps.git(["rev-parse", flag], root);
+    if (r.exitCode !== 0)
+        return undefined;
+    const out = r.stdout.trim();
+    return realOrRaw(isAbsolute(out) ? out : resolve(root, out));
+}
+/** Resolved once per session. A worktree's git dir differs from its common dir. */
+export async function resolveGitLayout(root) {
+    const gitDir = await gitPath("--git-dir", root);
+    const commonDir = await gitPath("--git-common-dir", root);
+    if (gitDir === undefined || commonDir === undefined)
+        return { kind: "none" };
+    return gitDir === commonDir ? { kind: "main", gitDir } : { kind: "worktree", gitDir, commonDir };
+}
+/**
+ * Top-level entry names under `<root>/<stateDir>` right now (nax#2260;
+ * `stateDir` is `.nax` for nax). An entry with a glob character is skipped:
+ * nax never creates one, and a glob in the policy would make every build
+ * throw (F1) -- an agent could otherwise switch the sandbox off by creating
+ * `.nax/a*b`.
+ */
+export async function listNaxEntries(root, stateDir) {
+    try {
+        const names = await _policyInputDeps.readdir(join(root, stateDir));
+        return names.filter((name) => !SANDBOX_GLOB_CHARS.test(name));
+    }
+    catch {
+        return [];
+    }
+}
+/** Every `credentials*` file in `dir` (the host's credential dir), expanded to literals (F1: no globs). */
+export async function listCredentialFiles(dir) {
+    try {
+        const entries = await _policyInputDeps.readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.name.startsWith("credentials")).map((e) => join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** `os.tmpdir()` plus `/tmp` (Linux tools fall back to it; srt sets no TMPDIR there -- spec F3). */
+export function defaultTempRoots() {
+    return [_policyInputDeps.tmpdir(), "/tmp"];
+}
+/** The shared temp root under both spellings: `/tmp`, and its macOS realpath. */
+const SHARED_TMP_ROOTS = ["/tmp", "/private/tmp"];
+/**
+ * US-002: the temp roots a CONFINED session gets -- the run's own root, plus
+ * the host tmpdir only when that is not the shared one. `os.tmpdir()` is
+ * `/tmp` on most Linux hosts and keeping it would re-grant exactly the shared
+ * directory the confinement exists to remove; a tmpdir of `/private/tmp` is
+ * the same directory seen through macOS's symlink.
+ */
+export function runTempRoots(opts) {
+    const shared = SHARED_TMP_ROOTS.some((root) => opts.tmpdir === root || opts.tmpdir.startsWith(`${root}/`));
+    return shared ? [opts.runTmpRoot] : [opts.tmpdir, opts.runTmpRoot];
+}

package/dist/sandbox/probe.d.ts

@@ -0,0 +1,8 @@
+import { tmpdir } from "node:os";
+import { runArgv } from "#src/internal/argv-exec";
+import type { ProbeResult, SandboxBackend } from "./types.ts";
+export declare const _probeDeps: {
+    tmpdir: typeof tmpdir;
+    runArgv: typeof runArgv;
+};
+export declare function probeSandbox(backend: SandboxBackend): Promise<ProbeResult>;

package/dist/sandbox/probe.js

@@ -0,0 +1,66 @@
+/**
+ * Is the sandbox actually working here? Decided by RUNNING one wrapped
+ * command, never by a dependency check: in stock Docker bwrap is installed
+ * and every command fails (spec F4), and a sandbox that runs but does not
+ * enforce must count as absent, not present.
+ *
+ * The denied marker sits under the probe's own write root and is listed in
+ * denyWrite: srt's deny-within-allow wins on both platforms (spec 5.4). A
+ * marker merely "outside the roots" would be inside a tmp write root in
+ * production and falsely read as a leak.
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runArgv } from "#src/internal/argv-exec";
+import { realOrRaw } from "#src/internal/realpath";
+const PROBE_TIMEOUT_MS = 30_000;
+export const _probeDeps = { tmpdir, runArgv };
+function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+export async function probeSandbox(backend) {
+    if (!(await backend.isSupportedPlatform())) {
+        return { available: false, reason: `platform ${process.platform} is not supported by the ${backend.name} sandbox` };
+    }
+    const dir = realOrRaw(mkdtempSync(join(_probeDeps.tmpdir(), "nax-sandbox-probe-")));
+    mkdirSync(join(dir, "allowed"));
+    mkdirSync(join(dir, "denied"));
+    const allowed = join(dir, "allowed", "marker");
+    const denied = join(dir, "denied", "marker");
+    try {
+        let argv;
+        try {
+            argv = await backend.wrap({
+                command: `echo ok > ${allowed}; echo leak > ${denied}; exit 0`,
+                shell: "/bin/sh",
+                policy: { writeRoots: [dir], denyWrite: [denied], denyRead: [], network: {} },
+                cwd: dir,
+                commandId: "nax-sandbox-probe",
+            });
+        }
+        catch (err) {
+            return { available: false, reason: `sandbox wrap failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        let result;
+        try {
+            result = await _probeDeps.runArgv({ argv, cwd: dir, timeoutMs: PROBE_TIMEOUT_MS });
+        }
+        finally {
+            // Exactly once per successful wrap, even when the spawn itself throws.
+            backend.commandFinished();
+        }
+        if (!existsSync(allowed)) {
+            return {
+                available: false,
+                reason: `sandbox could not run a command: ${firstLine(result.stderr) || `exit ${result.exitCode}`}`,
+            };
+        }
+        if (existsSync(denied))
+            return { available: false, reason: "sandbox ran a command but did not enforce a write deny" };
+        return { available: true };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/sandbox/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Process-level sandbox state: one backend (srt's manager is a singleton), one
+ * probe result, and the once-per-process log lines (spec 5.7). One nax process
+ * serves one project, so one network config per process holds.
+ */
+import type { SandboxConfig } from "../config/schemas-sandbox.ts";
+import type { ProbeResult, SandboxBackend } from "./types.ts";
+export declare const _sandboxRegistryDeps: {
+    createBackend: (network: SandboxConfig["network"]) => SandboxBackend;
+    probe: (backend: SandboxBackend) => Promise<ProbeResult>;
+};
+export declare function sandboxBackendFor(config: SandboxConfig): SandboxBackend;
+export declare function probeSandboxOnce(target: SandboxBackend, storyId?: string): Promise<ProbeResult>;
+export declare function warnSandboxUnavailableOnce(reason: string, storyId?: string): void;
+/** Run cleanup. The probe result is kept: the platform does not change. */
+export declare function resetSandboxBackend(): Promise<void>;
+export declare function _resetSandboxRegistryForTests(): void;

package/dist/sandbox/registry.js

@@ -0,0 +1,57 @@
+/**
+ * Process-level sandbox state: one backend (srt's manager is a singleton), one
+ * probe result, and the once-per-process log lines (spec 5.7). One nax process
+ * serves one project, so one network config per process holds.
+ */
+import { getSafeLogger } from "#src/infra/index";
+import { probeSandbox } from "./probe.js";
+import { createSrtBackend } from "./srt-backend.js";
+export const _sandboxRegistryDeps = {
+    createBackend: (network) => createSrtBackend(network),
+    probe: (backend) => probeSandbox(backend),
+};
+let backend;
+let probed;
+let warnedUnavailable = false;
+export function sandboxBackendFor(config) {
+    backend ??= _sandboxRegistryDeps.createBackend(config.network);
+    return backend;
+}
+export function probeSandboxOnce(target, storyId = "_sandbox") {
+    probed ??= _sandboxRegistryDeps.probe(target).then((result) => {
+        getSafeLogger()?.info("sandbox", "Sandbox probe", {
+            storyId,
+            backend: target.name,
+            available: result.available,
+            ...(result.available ? {} : { reason: result.reason }),
+        });
+        return result;
+    }, (err) => {
+        const reason = `sandbox probe failed: ${err instanceof Error ? err.message : String(err)}`;
+        getSafeLogger()?.warn("sandbox", "Sandbox probe threw; treating as unavailable", { storyId, reason });
+        const unavailable = { available: false, reason };
+        return unavailable;
+    });
+    return probed;
+}
+export function warnSandboxUnavailableOnce(reason, storyId = "_sandbox") {
+    if (warnedUnavailable)
+        return;
+    warnedUnavailable = true;
+    getSafeLogger()?.warn("sandbox", "Sandbox unavailable: raw bash is refused; gated/escalate commands run unwrapped", {
+        storyId,
+        reason,
+    });
+}
+/** Run cleanup. The probe result is kept: the platform does not change. */
+export async function resetSandboxBackend() {
+    const current = backend;
+    backend = undefined;
+    if (current !== undefined)
+        await current.reset();
+}
+export function _resetSandboxRegistryForTests() {
+    backend = undefined;
+    probed = undefined;
+    warnedUnavailable = false;
+}

package/dist/sandbox/session-tmp.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The three synchronous host calls {@link runTmpRoot} resolves its parent
+ * through. Injectable so tests can pin a host (see docs/architecture/conventions.md §2).
+ */
+export declare const _sessionTmpDeps: {
+    lstat: (path: string) => import("node:fs").Stats;
+    access: (path: string, mode: number) => void;
+    uid: () => number;
+};
+/** `<parent>/<runId>` — the per-run parent of every session temp directory. */
+export declare function runTmpRoot(runId: string): string;
+/**
+ * `<root>/<sessionName>`, the session part reduced to [A-Za-z0-9_.-] (others
+ * become "_"). Takes an ALREADY-RESOLVED run root so a caller that needs the
+ * root too (the sandbox policy) resolves the parent once and cannot observe it
+ * flip between two calls.
+ */
+export declare function sessionTmpDirUnder(root: string, sessionName: string): string;
+/** `<parent>/<runId>/<sessionName>`, each part reduced to [A-Za-z0-9_.-] (others become "_"). */
+export declare function sessionTmpDir(runId: string, sessionName: string): string;

package/dist/sandbox/session-tmp.js

@@ -0,0 +1,95 @@
+/**
+ * Per-session temp directories under a run-owned root (US-001, US-004).
+ *
+ * A stray `/tmp/tsconfig.json` survived an NBF restore and turned a later
+ * story's full-suite gate red. Launcher-driven Bash/Exec commands now run with
+ * `TMPDIR`/`TMP`/`TEMP` pointing at `<parent>/<runId>/<sessionName>`, which the
+ * run deletes when it ends. The directory is a flat child of the run root, so
+ * the run's own `runTmpRoot(runId)` is the only prefix a cleanup needs to
+ * remove — never a `/tmp/nax*` sweep, because a concurrent run's live
+ * directories share that prefix.
+ *
+ * The parent is `/tmp/nax`, one shared directory that is easier to find and
+ * list than a flat `/tmp/nax-<runId>`. It is shared, so it cannot be created
+ * once and trusted: a `/tmp/nax` made by one OS user is not writable by
+ * another. The parent is therefore re-resolved on EVERY call from three host
+ * facts the `_sessionTmpDeps` seam exposes, with no cache, and anything nax
+ * cannot vouch for falls back to a per-user `/tmp/nax-<uid>`.
+ *
+ * The root is the literal `/tmp` (not `os.tmpdir()`): callers record and assert
+ * this machine-stable location, and the OS inherits the rest.
+ */
+import { accessSync, constants, lstatSync } from "node:fs";
+/** The literal temp root both parents hang off. */
+const TMP_ROOT = "/tmp";
+/** The shared parent every resolvable case nests under; `mkdir -p` in the launcher creates it. */
+const SHARED_TMP_PARENT = `${TMP_ROOT}/nax`;
+/**
+ * The three synchronous host calls {@link runTmpRoot} resolves its parent
+ * through. Injectable so tests can pin a host (see docs/architecture/conventions.md §2).
+ */
+export const _sessionTmpDeps = {
+    lstat: (path) => lstatSync(path),
+    access: (path, mode) => {
+        accessSync(path, mode);
+    },
+    // `process.getuid` is POSIX-only and this module's `/tmp` paths already assume
+    // POSIX; the fallback keeps the type total without claiming a real uid.
+    uid: () => process.getuid?.() ?? 0,
+};
+/**
+ * True when `/tmp/nax` is a real directory the current user can write and
+ * search. Absence is NOT this case: an absent parent is a usable shared parent
+ * (the launcher creates it), and every other failure means the path is there in
+ * a shape nax cannot vouch for.
+ */
+function isUsableSharedParent() {
+    try {
+        const stats = _sessionTmpDeps.lstat(SHARED_TMP_PARENT);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return false;
+    }
+    catch (err) {
+        // ENOENT is the one failure that means "create /tmp/nax".
+        return err.code === "ENOENT";
+    }
+    try {
+        _sessionTmpDeps.access(SHARED_TMP_PARENT, constants.W_OK | constants.X_OK);
+        return true;
+    }
+    catch {
+        // Unwritable or unsearchable by this user: the fallback covers it, so the
+        // errno carries no decision the caller does not already make.
+        return false;
+    }
+}
+/** `/tmp/nax` when the shared parent is usable, `/tmp/nax-<uid>` otherwise. */
+function tmpParent() {
+    return isUsableSharedParent() ? SHARED_TMP_PARENT : `${TMP_ROOT}/nax-${_sessionTmpDeps.uid()}`;
+}
+/**
+ * Any character outside `[A-Za-z0-9_.-]` collapses to `_`, so a part can never
+ * contain a separator. `.` survives because real run ids carry one (the
+ * millisecond field of `buildRunId`'s ISO stamp), but a part that is nothing
+ * BUT dots would name the parent — so it collapses to `_` as well.
+ */
+function sanitizePart(part) {
+    return part.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/^\.+$/, "_");
+}
+/** `<parent>/<runId>` — the per-run parent of every session temp directory. */
+export function runTmpRoot(runId) {
+    return `${tmpParent()}/${sanitizePart(runId)}`;
+}
+/**
+ * `<root>/<sessionName>`, the session part reduced to [A-Za-z0-9_.-] (others
+ * become "_"). Takes an ALREADY-RESOLVED run root so a caller that needs the
+ * root too (the sandbox policy) resolves the parent once and cannot observe it
+ * flip between two calls.
+ */
+export function sessionTmpDirUnder(root, sessionName) {
+    return `${root}/${sanitizePart(sessionName)}`;
+}
+/** `<parent>/<runId>/<sessionName>`, each part reduced to [A-Za-z0-9_.-] (others become "_"). */
+export function sessionTmpDir(runId, sessionName) {
+    return sessionTmpDirUnder(runTmpRoot(runId), sessionName);
+}

package/dist/sandbox/srt-backend.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The ONLY importer of @anthropic-ai/sandbox-runtime (enforced by
+ * packages/repo-tooling/scripts/check-sandbox-imports.ts). Loaded by dynamic import so a run that
+ * never sandboxes never loads it.
+ *
+ * srt's SandboxManager is a process-wide singleton; per-call customConfig
+ * carries each story's roots, so parallel worktree stories share it (spike:
+ * concurrent roots isolated). The returned `env` of wrapWithSandboxArgv is
+ * process.env itself and is DISCARDED here (spec F6).
+ */
+import { mkdir } from "node:fs/promises";
+import type { SandboxConfig } from "../config/schemas-sandbox.ts";
+import type { SandboxBackend } from "./types.ts";
+type SrtModule = typeof import("@anthropic-ai/sandbox-runtime");
+export declare const _srtBackendDeps: {
+    load: () => Promise<SrtModule>;
+    platform: () => NodeJS.Platform;
+    mkdir: typeof mkdir;
+};
+export declare function createSrtBackend(network: SandboxConfig["network"]): SandboxBackend;
+export {};

package/dist/sandbox/srt-backend.js

@@ -0,0 +1,99 @@
+/**
+ * The ONLY importer of @anthropic-ai/sandbox-runtime (enforced by
+ * packages/repo-tooling/scripts/check-sandbox-imports.ts). Loaded by dynamic import so a run that
+ * never sandboxes never loads it.
+ *
+ * srt's SandboxManager is a process-wide singleton; per-call customConfig
+ * carries each story's roots, so parallel worktree stories share it (spike:
+ * concurrent roots isolated). The returned `env` of wrapWithSandboxArgv is
+ * process.env itself and is DISCARDED here (spec F6).
+ */
+import { mkdir } from "node:fs/promises";
+import { SRT_MACOS_TMPDIR } from "./defaults.js";
+export const _srtBackendDeps = {
+    load: () => import("@anthropic-ai/sandbox-runtime"),
+    platform: () => process.platform,
+    mkdir,
+};
+/**
+ * Open network = `network` WITHOUT `allowedDomains`. srt's type requires the
+ * field, but its runtime decides restriction on `allowedDomains !== undefined`
+ * (sandbox-manager.js, `hasNetworkConfig`), and `initialize` dereferences
+ * `network`, so the object must exist. This is the one cast in the module; the
+ * live suite pins the behaviour (open => no proxy variables in the argv), so
+ * an srt bump that changes it fails a test rather than silently restricting.
+ */
+function srtNetwork(allowedDomains) {
+    if (allowedDomains !== undefined)
+        return { allowedDomains: [...allowedDomains], deniedDomains: [] };
+    const open = { deniedDomains: [] };
+    return open;
+}
+function customConfig(policy) {
+    return {
+        filesystem: {
+            denyRead: [...policy.denyRead],
+            allowWrite: [...policy.writeRoots],
+            denyWrite: [...policy.denyWrite],
+        },
+        ...(policy.network.allowedDomains !== undefined ? { network: srtNetwork(policy.network.allowedDomains) } : {}),
+    };
+}
+export function createSrtBackend(network) {
+    let initialized;
+    let loaded;
+    let inFlight = 0;
+    function initialize() {
+        initialized ??= (async () => {
+            const mod = await _srtBackendDeps.load();
+            if (_srtBackendDeps.platform() === "darwin")
+                await _srtBackendDeps.mkdir(SRT_MACOS_TMPDIR, { recursive: true });
+            await mod.SandboxManager.initialize({
+                network: srtNetwork(network.allowedDomains),
+                filesystem: { denyRead: [], allowWrite: [], denyWrite: [] },
+            });
+            loaded = mod;
+            return mod;
+        })();
+        return initialized;
+    }
+    return {
+        name: "srt",
+        async isSupportedPlatform() {
+            const mod = await _srtBackendDeps.load();
+            return mod.SandboxManager.isSupportedPlatform();
+        },
+        async wrap(req) {
+            const mod = await initialize();
+            inFlight += 1;
+            try {
+                const { argv } = await mod.SandboxManager.wrapWithSandboxArgv(req.command, req.shell, customConfig(req.policy), undefined, req.cwd, { commandId: req.commandId });
+                return argv;
+            }
+            catch (err) {
+                inFlight -= 1;
+                throw err;
+            }
+        },
+        annotate(commandId, stderr) {
+            if (loaded === undefined)
+                return "";
+            const annotated = loaded.SandboxManager.annotateStderrWithSandboxFailures(commandId, stderr);
+            return annotated.startsWith(stderr) ? annotated.slice(stderr.length).trim() : "";
+        },
+        commandFinished() {
+            inFlight = Math.max(0, inFlight - 1);
+            // Removes bwrap mount placeholders (Linux). Never while another wrapped
+            // command runs: a running sandbox may still depend on them.
+            if (inFlight === 0)
+                loaded?.SandboxManager.cleanupAfterCommand();
+        },
+        async reset() {
+            if (loaded !== undefined)
+                await loaded.SandboxManager.reset();
+            initialized = undefined;
+            loaded = undefined;
+            inFlight = 0;
+        },
+    };
+}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Types for the OS sandbox around agent-authored commands (P4).
+ *
+ * Every path in a SandboxPolicy is absolute, literal and realpath-resolved:
+ * srt on Linux silently DROPS any denyWrite entry containing a glob
+ * (spec F1), and resolves only paths that already exist (spec 12, finding 3).
+ */
+import type { ArgvExecResult } from "#src/internal/argv-exec";
+export type SandboxBackendName = "srt";
+export interface SandboxNetworkPolicy {
+    /** Absent = unrestricted. */
+    readonly allowedDomains?: readonly string[];
+}
+export interface SandboxPolicy {
+    readonly writeRoots: readonly string[];
+    readonly denyWrite: readonly string[];
+    readonly denyRead: readonly string[];
+    readonly network: SandboxNetworkPolicy;
+}
+export type ProbeResult = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+export interface SandboxWrapRequest {
+    readonly command: string;
+    readonly shell: string;
+    readonly policy: SandboxPolicy;
+    readonly cwd: string;
+    readonly commandId: string;
+}
+export interface SandboxBackend {
+    readonly name: SandboxBackendName;
+    isSupportedPlatform(): Promise<boolean>;
+    /** Argv ONLY. The backend's env never crosses this boundary (spec F6). */
+    wrap(req: SandboxWrapRequest): Promise<readonly string[]>;
+    /** Extra violation text for this command, or "" when there is none. */
+    annotate(commandId: string, stderr: string): string;
+    /** Called once per finished wrapped command (in-flight bookkeeping). */
+    commandFinished(): void;
+    reset(): Promise<void>;
+}
+export type SandboxState = {
+    readonly kind: "disabled";
+} | {
+    readonly kind: "available";
+    readonly backend: SandboxBackendName;
+    readonly network: "open" | readonly string[];
+    /**
+     * US-002: `false` when temp writes are confined to this run's own temp
+     * root. Absent means the shared temp roots are writable (today's
+     * behaviour), so every pre-US-002 construction of this variant holds.
+     */
+    readonly sharedTmp?: boolean;
+} | {
+    readonly kind: "unavailable";
+    readonly backend: SandboxBackendName;
+    readonly reason: string;
+};
+export interface SandboxRecord {
+    readonly backend: SandboxBackendName | "none";
+    readonly wrapped: boolean;
+    readonly reason?: string;
+    readonly denialHint?: true;
+    /**
+     * Wrapped calls only: the argv the sandbox backend returned and runArgv
+     * executed. Absent when nothing was wrapped, where `executed` is already
+     * what ran. Never a substitute for `executed`, which stays the logical argv.
+     */
+    readonly argv?: readonly string[];
+}
+export type LaunchSpec = {
+    readonly kind: "shell";
+    readonly shell: string;
+    readonly command: string;
+} | {
+    readonly kind: "argv";
+    readonly argv: readonly string[];
+};
+export interface LaunchRequest {
+    readonly spec: LaunchSpec;
+    /** The policy root (`ctx.root`); write roots derive from it. */
+    readonly root: string;
+    /** Where the command starts; the PACKAGE dir for an Exec `target: "package"` call. */
+    readonly cwd: string;
+    readonly timeoutMs: number;
+    readonly stripEnvVars: readonly string[];
+    /** The CALLER's own overlay (Exec's Yarn no-scripts env). Never the backend's. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Aborts the run: forwarded to runArgv, which SIGKILLs the process group. US-001. */
+    readonly signal?: AbortSignal;
+}
+export interface LaunchResult extends ArgvExecResult {
+    /** The logical argv (what the tool asked to run), not the sandbox wrapper argv. */
+    readonly executed: readonly string[];
+    readonly sandbox: SandboxRecord;
+}
+export interface CommandLauncher {
+    readonly state: SandboxState;
+    run(req: LaunchRequest): Promise<LaunchResult>;
+}

package/dist/sandbox/types.js

@@ -0,0 +1 @@
+export {};