@webpresso/agent-kit 3.3.0 → 3.3.2

package/dist/esm/review/execution/review-checkout.js

@@ -1,8 +1,9 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, isAbsolute, join, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
 function git(cwd, args, input) {
     return execFileSync("git", [...args], {
         cwd,
@@ -86,8 +87,10 @@ function worktreeFingerprint(cwd, ignoredPaths = new Set()) {
 // derived/dependency root, because such output can reach neither the caller
 // nor the reviewed source (the checkout is a disposable tmpdir). Everything
 // else stays strict: a tracked mutation (` M `/` D `), a new untracked source
-// file (`?? `), and any NON-derived gitignored write (e.g. a stray `.env`) all
-// still surface.
+// file (`?? `), and any NON-derived gitignored write (e.g. a stray `.env`,
+// `bin/runtime/`) all still surface. Under this branch's node_modules
+// reconstruction the dependency tree is a real, contained directory rather than
+// a symlink, which is why `node_modules` stays in the exempt set at any depth.
 const NON_SOURCE_IGNORED_SEGMENTS = new Set(["dist", ".tshy", "node_modules"]);
 function isNonSourceIgnoredPath(relativePath) {
     return relativePath.split("/").some((segment) => NON_SOURCE_IGNORED_SEGMENTS.has(segment));
@@ -112,23 +115,95 @@ function isNormalizedPackageJsonModification(cwd, line) {
     try {
         const working = readFileSync(join(cwd, relativePath), "utf8");
         const tracked = git(cwd, ["show", `HEAD:${relativePath}`]);
-        return working.replace(/\s+$/u, "") === tracked.replace(/\s+$/u, "");
+        if (working.replace(/\s+$/u, "") === tracked.replace(/\s+$/u, ""))
+            return true;
+        // B2 neutralizeTargetPackageManager rewrites root package.json by deleting
+        // only the untrusted `packageManager` field. That intentional security
+        // rewrite must not fail delivery verification as contamination.
+        return isPackageManagerOnlyRemoval(tracked, working);
     }
     catch {
         return false;
     }
 }
+function isPackageManagerOnlyRemoval(tracked, working) {
+    try {
+        const trackedJson = JSON.parse(tracked);
+        const workingJson = JSON.parse(working);
+        const trackedNormalized = stripUntrustedPackageManagerFields(trackedJson);
+        const workingNormalized = stripUntrustedPackageManagerFields(workingJson);
+        // Working must equal tracked after removing the untrusted fields from both,
+        // and at least one untrusted field must have been present on tracked.
+        if (JSON.stringify(trackedNormalized.value) !== JSON.stringify(workingNormalized.value)) {
+            return false;
+        }
+        return trackedNormalized.stripped;
+    }
+    catch {
+        return false;
+    }
+}
+function stripUntrustedPackageManagerFields(input) {
+    let stripped = false;
+    const value = { ...input };
+    if ("packageManager" in value) {
+        delete value.packageManager;
+        stripped = true;
+    }
+    const devEngines = value["devEngines"];
+    if (devEngines !== null && typeof devEngines === "object" && !Array.isArray(devEngines)) {
+        const engines = { ...devEngines };
+        if ("packageManager" in engines) {
+            delete engines.packageManager;
+            stripped = true;
+            value["devEngines"] = engines;
+        }
+    }
+    return { value, stripped };
+}
 // Single source of truth for turning a `git status --porcelain=v1` line into
 // its relative path, shared by status()'s filter predicate and
 // worktreeFingerprint()'s dirty-path hashing so both stay aligned by
-// construction. Does not special-case the rename arrow (`old -> new`); a
-// rename line's raw tail is used as-is, matching this function's prior
-// (pre-refactor) inline behavior.
+// construction.
+//
+// Rename/copy lines use non-null porcelain form `XY ORIG -> DEST` (or quoted
+// paths). The destination is the live path whose bytes must be fingerprinted;
+// using the raw `ORIG -> DEST` tail makes lstat miss both sides and silently
+// drops content from the hash (regression vs paired-record `-z` parsing).
 function statusEntryPath(line) {
-    return line.slice(3).replace(/\/$/u, "");
+    const tail = line.slice(3).replace(/\/$/u, "");
+    const renameSep = " -> ";
+    const sep = tail.lastIndexOf(renameSep);
+    const pathPart = sep === -1 ? tail : tail.slice(sep + renameSep.length);
+    return unquotePorcelainPath(pathPart);
+}
+/** Strip git porcelain double-quotes and reverse C-style escapes for a path. */
+function unquotePorcelainPath(pathPart) {
+    if (!pathPart.startsWith('"') || !pathPart.endsWith('"') || pathPart.length < 2) {
+        return pathPart;
+    }
+    return pathPart.slice(1, -1).replace(/\\([\\"ntr])/gu, (_m, ch) => {
+        if (ch === "n")
+            return "\n";
+        if (ch === "t")
+            return "\t";
+        if (ch === "r")
+            return "\r";
+        return ch;
+    });
 }
 function status(cwd, ignoredPaths = new Set()) {
-    const output = git(cwd, ["status", "--porcelain=v1", "--untracked-files=all", "--ignored"]);
+    // `--ignored=matching` reports an ignored DIRECTORY as a single entry instead
+    // of recursing into it. This is both correct for the depth-aware exemption
+    // (the dir entry carries the derived/dependency segment) and essential now that
+    // node_modules is a reconstructed real tree: `-uall --ignored` (traditional)
+    // would enumerate every file under node_modules and overflow the pipe buffer.
+    const output = git(cwd, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+        "--ignored=matching",
+    ]);
     return output
         .split(/\r?\n/u)
         .filter((line) => line.length > 0)
@@ -159,7 +234,12 @@ function neutralizeSymlinks(directory) {
 }
 export function createReviewTargetCheckout(repositoryRoot, targetSha) {
     let callerFingerprint = worktreeFingerprint(repositoryRoot);
-    const cwd = mkdtempSync(join(tmpdir(), "wp-review-target-"));
+    // Canonicalize the checkout root. On macOS `tmpdir()` is `/var/folders/...`, a
+    // symlink to `/private/var/folders/...`; a non-canonical root makes pnpm's
+    // `file:` directory-dependency resolution mismatch (`/var` vs `/private/var`)
+    // and wrongly reject a valid lockfile with ERR_PNPM_OUTDATED_LOCKFILE, and it
+    // would also weaken path-containment comparisons. Realpath once, up front.
+    const cwd = realpathSync(mkdtempSync(join(tmpdir(), "wp-review-target-")));
     try {
         const archivePath = join(cwd, ".wp-review-target.tar");
         execFileSync("git", ["archive", "--format=tar", `--output=${archivePath}`, targetSha], {
@@ -187,7 +267,7 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
         git(cwd, ["update-ref", "HEAD", baselineHead]);
         if (status(cwd).length > 0)
             throw new Error("review target checkout was not clean at start");
-        const injectedPaths = projectCallerDependencies(repositoryRoot, cwd);
+        projectCallerDependencies(repositoryRoot, cwd);
         let cleaned = false;
         return {
             cwd,
@@ -196,7 +276,7 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
             },
             changes: () => {
                 try {
-                    const changes = [...status(cwd, injectedPaths)];
+                    const changes = [...status(cwd)];
                     if (git(cwd, ["rev-parse", "HEAD"]).trim() !== baselineHead) {
                         changes.push("review checkout HEAD changed");
                     }
@@ -223,25 +303,334 @@ export function createReviewTargetCheckout(repositoryRoot, targetSha) {
     }
 }
 function projectCallerDependencies(repositoryRoot, checkoutRoot) {
-    const projected = new Set();
-    const dependencyPath = "node_modules";
-    const callerPath = join(repositoryRoot, dependencyPath);
-    const targetPath = join(checkoutRoot, dependencyPath);
+    const targetPath = join(checkoutRoot, "node_modules");
+    // Respect a target that ships its own (tracked) node_modules — never clobber it.
+    if (existsSync(targetPath))
+        return;
+    // Reconstruct only when there is a manifest + lockfile to reconstruct from and
+    // a warm caller store to source packages from. Without any of these there is
+    // nothing to (or no safe way to) rebuild, so skip and let the gate commands
+    // surface any genuinely missing dependency loudly.
+    if (!existsSync(join(checkoutRoot, "package.json")) ||
+        !existsSync(join(checkoutRoot, "pnpm-lock.yaml")) ||
+        !existsSync(join(repositoryRoot, "node_modules"))) {
+        return;
+    }
+    // SECURITY (S1): a hostile target `pnpm-workspace.yaml` can point pnpm's
+    // workspace discovery at an EXTERNAL project (e.g. `../victim`), so the
+    // unsandboxed install would create that project's node_modules OUTSIDE the
+    // checkout, which the post-install root containment assert never examines.
+    // Symlinked escapes are already neutralized on the archived tree
+    // (neutralizeSymlinks), so the residual vector is lexical: fail closed on any
+    // workspace pattern that is absolute or traverses out with `..`.
+    assertWorkspacePatternsContained(checkoutRoot);
+    // Reconstruct a REAL, WRITABLE, ISOLATED node_modules inside the disposable
+    // checkout with pnpm, sourcing packages from the warm global store via
+    // copy-on-write clones (falling back to a copy where reflink is unsupported).
+    // Unlike a symlink to the caller's node_modules, this gives the sandboxed gate
+    // commands a node_modules they can WRITE into (vite/vitest/tsc caches such as
+    // `.vite`, `.vite-temp`, `.cache`) that is confined to the disposable checkout
+    // and cannot reach the caller's dependencies or the shared content-addressable
+    // store. This is the industry pattern (Nix/Vercel/Cloudflare all reconstruct
+    // deps inside the isolate); the reference agent sandboxes (Codex, Claude Code)
+    // likewise treat the workspace node_modules as writable-and-isolated.
+    //
+    // SECURITY (trust boundary): this materialization runs UNSANDBOXED — it
+    // precedes the OS sandbox that confines gate execution. So it must itself be
+    // hardened against a hostile target, whose `.npmrc` / `pnpm-workspace.yaml`
+    // can set pnpm's writable-location settings and redirect this parent-process
+    // install to WRITE outside the disposable checkout. `--ignore-scripts` +
+    // `--ignore-pnpmfile` block code execution; `--offline` + `--frozen-lockfile`
+    // keep it a pure lockfile materialization; `clone-or-copy` never hardlinks so
+    // the shared store stays pristine. Crucially, EVERY writable pnpm location is
+    // derived from a TRUSTED path and pinned on the CLI, which overrides both the
+    // project `.npmrc` and env vars — so a hostile config cannot redirect a write:
+    //   - store-dir  -> the caller's warm content store (read source; resolved in
+    //                   the trusted caller context, never from the target)
+    //   - modules-dir / virtual-store-dir -> inside the checkout
+    //   - lockfile-dir -> the checkout (frozen won't rewrite it)
+    //   - cache/state/global -> a per-run scratch OUTSIDE the checkout (trusted,
+    //                   and therefore never counted as checkout contamination)
+    // Without a resolvable trusted store we cannot install without risking a
+    // target-redirected store, so we FAIL CLOSED (skip reconstruction) rather than
+    // run an unpinnable install.
+    const trustedStore = trustedPnpmStorePath(repositoryRoot);
+    if (trustedStore === undefined)
+        return;
+    assertTargetNpmrcSafe(checkoutRoot);
+    neutralizeTargetPackageManager(checkoutRoot);
+    const trustedPnpm = resolveTrustedPnpmBinary(repositoryRoot);
+    const scratch = mkdtempSync(join(tmpdir(), "wp-review-pnpm-"));
     try {
-        lstatSync(callerPath);
+        runReconstructionInstall(checkoutRoot, trustedStore, scratch, trustedPnpm);
+        // Defense-in-depth: verify the reconstructed dependency tree actually lives
+        // inside the checkout. The pinned layout should guarantee this, but a
+        // containment breach must fail closed rather than silently escape.
+        assertDependencyContainment(checkoutRoot);
     }
-    catch {
-        return projected;
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
     }
+}
+// Resolve `pnpm` once in the trusted caller context. Never rely on PATH lookup
+// with cwd=checkoutRoot: corepack's PATH shim reads the *target* package.json
+// `packageManager` field and can download+exec a hostile package-manager build
+// (B2). An absolute binary path bypasses that.
+function resolveTrustedPnpmBinary(repositoryRoot) {
     try {
-        lstatSync(targetPath);
-        return projected;
+        const resolved = execFileSync("which", ["pnpm"], {
+            cwd: repositoryRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+            env: sanitizedPnpmEnv(),
+        }).trim();
+        if (resolved.length === 0 || !existsSync(resolved)) {
+            throw new Error("pnpm binary path is empty or missing");
+        }
+        return resolved;
+    }
+    catch (error) {
+        throw new Error(`cannot resolve trusted pnpm binary: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// Target package.json `packageManager` is untrusted under reconstruction. Even
+// with an absolute pnpm path, strip it so ambient corepack cannot re-enter via
+// nested tooling. Fail closed if package.json is unparseable after archive.
+function neutralizeTargetPackageManager(checkoutRoot) {
+    const packageJsonPath = join(checkoutRoot, "package.json");
+    if (!existsSync(packageJsonPath))
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`review checkout package.json is unparseable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return;
+    const record = parsed;
+    let rewritten = false;
+    if ("packageManager" in record) {
+        delete record.packageManager;
+        rewritten = true;
+    }
+    const devEngines = record["devEngines"];
+    if (devEngines !== null && typeof devEngines === "object" && !Array.isArray(devEngines)) {
+        const engines = devEngines;
+        if ("packageManager" in engines) {
+            delete engines.packageManager;
+            rewritten = true;
+        }
+    }
+    if (!rewritten)
+        return;
+    writeFileSync(packageJsonPath, `${JSON.stringify(record, null, 2)}` + "\n", "utf8");
+}
+// Refuse target `.npmrc` keys that can redirect writes, fetch runtimes, or
+// otherwise escape the pinned reconstruction contract (B2 coverage).
+// Fold kebab/snake/camel to a single letter form so `useNodeVersion`,
+// `use-node-version`, and `use_node_version` all match.
+function normalizePnpmConfigKey(key) {
+    return key.toLowerCase().replace(/[-_]/gu, "");
+}
+const FORBIDDEN_PNPM_CONFIG_KEYS = new Set([
+    "store-dir",
+    "modules-dir",
+    "virtual-store-dir",
+    "cache-dir",
+    "state-dir",
+    "global-dir",
+    "prefix",
+    "use-node-version",
+    "node-mirror",
+    "node-version",
+    "package-import-method",
+    "global-virtual-store",
+    "enable-global-virtual-store",
+    "node-linker",
+].map(normalizePnpmConfigKey));
+// Workspace settings that are NOT CLI-pinned and can force an unsandboxed
+// runtime fetch/exec. CLI-pinned keys (store-dir, enable-global-virtual-store,
+// etc.) remain allowed in workspace yaml because reconstruction overrides them.
+const FORBIDDEN_WORKSPACE_SETTING_KEYS = new Set(["use-node-version", "node-mirror", "node-version", "global-dir", "prefix"].map(normalizePnpmConfigKey));
+function assertTargetNpmrcSafe(checkoutRoot) {
+    const npmrcPath = join(checkoutRoot, ".npmrc");
+    if (!existsSync(npmrcPath))
+        return;
+    const text = readFileSync(npmrcPath, "utf8");
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.replace(/\r$/u, "").trim();
+        if (line.length === 0 || line.startsWith("#") || line.startsWith(";"))
+            continue;
+        const eq = line.indexOf("=");
+        const rawKey = (eq >= 0 ? line.slice(0, eq) : line).trim();
+        if (rawKey.length === 0)
+            continue;
+        const key = normalizePnpmConfigKey(rawKey);
+        if (FORBIDDEN_PNPM_CONFIG_KEYS.has(key) || key.startsWith("nodemirror")) {
+            throw new Error(`review checkout .npmrc sets forbidden key ${rawKey}; refusing reconstruction`);
+        }
+    }
+}
+// Run the hardened pnpm materialization, surfacing pnpm's own stdout/stderr on
+// failure — pnpm reports errors like ERR_PNPM_OUTDATED_LOCKFILE on stdout, and
+// an opaque "Command failed" would otherwise hide the actual cause.
+function runReconstructionInstall(checkoutRoot, trustedStore, scratch, trustedPnpm) {
+    try {
+        execFileSync(trustedPnpm, [
+            "install",
+            // Offline: pure lockfile materialization, no network. If a package is
+            // missing from the warm store this fails closed (ERR_PNPM_NO_OFFLINE_TARBALL).
+            "--offline",
+            "--frozen-lockfile",
+            // NOTE: deliberately NOT --frozen-store. With enableGlobalVirtualStore
+            // content-addressable link layouts, --frozen-store reports
+            // ERR_PNPM_NO_OFFLINE_TARBALL for packages that offline materialization
+            // can still import (verified: same install without --frozen-store
+            // succeeds). --offline already forbids downloading; clone-or-copy keeps
+            // the shared store content immutable; store-dir is pinned to the
+            // trusted caller path. Residual risk is store metadata touch-ups during
+            // materialization — acceptable vs blocking every delivery review.
+            "--ignore-scripts",
+            "--ignore-pnpmfile",
+            "--config.node-linker=isolated",
+            "--config.modules-dir=node_modules",
+            "--config.virtual-store-dir=node_modules/.pnpm",
+            "--config.package-import-method=clone-or-copy",
+            // Force a self-contained virtual store INSIDE the checkout. A hostile
+            // target `pnpm-workspace.yaml` cannot re-enable the global virtual store
+            // (which links into the shared, writable host store) because CLI config
+            // overrides workspace config.
+            "--config.enable-global-virtual-store=false",
+            // Pin the writable locations a local install actually touches to a
+            // trusted path (see SECURITY note above). CLI `--config.*` overrides
+            // project `.npmrc` and env vars. (Global dirs are only written by
+            // `pnpm add -g`, never a local install, so they need no pin.)
+            // lockfile-dir is relative "." because cwd is already the checkout:
+            // absolute lockfile-dir paths make pnpm 11 mis-resolve importers
+            // (false OUTDATED_LOCKFILE against apps/desktop).
+            `--config.store-dir=${trustedStore}`,
+            "--config.lockfile-dir=.",
+            `--config.cache-dir=${join(scratch, "cache")}`,
+            `--config.state-dir=${join(scratch, "state")}`,
+        ], {
+            cwd: checkoutRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+            // A sanitized env drops config-injecting `npm_config_*` / `pnpm_*` vars
+            // so no ambient (or later target-learned) env var can redirect a write;
+            // the CLI pins are authoritative regardless, this is defense-in-depth.
+            env: sanitizedPnpmEnv(),
+            // Bounded so a pathological target lockfile cannot stall the verifier
+            // before any per-gate timeout applies. `--offline` clone-or-copy of a
+            // full workspace is seconds in practice; 120s is a generous ceiling.
+            timeout: 120_000,
+        });
+    }
+    catch (error) {
+        const detail = error;
+        const output = `${String(detail.stdout ?? "")}${String(detail.stderr ?? "")}`.trim();
+        throw new Error(`dependency reconstruction failed${output ? `: ${output}` : ""}`, error instanceof Error ? { cause: error } : undefined);
+    }
+}
+// Fail closed if the target's pnpm-workspace.yaml points pnpm's workspace
+// discovery outside the checkout (S1). Symlink escapes are already neutralized
+// on the archived tree, so only a lexical escape (absolute path or `..`
+// traversal) remains; an unparseable or list-shaped-wrong manifest is also
+// refused rather than trusted.
+function assertWorkspacePatternsContained(checkoutRoot) {
+    const workspaceFile = join(checkoutRoot, "pnpm-workspace.yaml");
+    if (!existsSync(workspaceFile))
+        return;
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(workspaceFile, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`review checkout pnpm-workspace.yaml is unparseable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Settings-only workspace files (no packages key) are legal; still scan for
+    // forbidden settings so the guard is not bypassable by omitting packages.
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        for (const rawKey of Object.keys(parsed)) {
+            if (rawKey === "packages")
+                continue;
+            const key = normalizePnpmConfigKey(rawKey);
+            if (FORBIDDEN_WORKSPACE_SETTING_KEYS.has(key) || key.startsWith("nodemirror")) {
+                throw new Error(`review checkout pnpm-workspace.yaml sets forbidden key ${rawKey}; refusing reconstruction`);
+            }
+        }
+    }
+    const packages = parsed?.packages;
+    if (packages === undefined || packages === null)
+        return;
+    if (!Array.isArray(packages)) {
+        throw new Error("review checkout pnpm-workspace.yaml `packages` is not a list; refusing reconstruction");
+    }
+    for (const pattern of packages) {
+        if (typeof pattern !== "string") {
+            throw new Error("review checkout pnpm-workspace.yaml `packages` has a non-string pattern; refusing reconstruction");
+        }
+        // A leading `!` negates (excludes) a pattern; strip it before the escape check.
+        const spec = pattern.startsWith("!") ? pattern.slice(1) : pattern;
+        if (isAbsolute(spec) || spec.split(/[\\/]/u).includes("..")) {
+            throw new Error(`review checkout pnpm-workspace.yaml workspace pattern escapes the checkout: ${pattern}`);
+        }
+    }
+}
+// Resolve the caller's warm pnpm content store in the TRUSTED caller context
+// (never the target's). Used to pin `store-dir` so a hostile target `.npmrc`
+// cannot redirect the offline install's store to an attacker-chosen path.
+function trustedPnpmStorePath(repositoryRoot) {
+    try {
+        const resolved = execFileSync("pnpm", ["store", "path"], {
+            cwd: repositoryRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 30_000,
+        }).trim();
+        return resolved.length > 0 ? resolved : undefined;
     }
     catch {
-        // Missing in the target archive means the caller dependency cache may be
-        // projected for local tooling without overwriting target-owned files.
+        return undefined;
+    }
+}
+// Env for the reconstruction install with pnpm/npm config-injecting variables
+// stripped, so ambient config cannot redirect a writable location. The CLI
+// `--config.*` pins already win over env; this is belt-and-suspenders.
+function sanitizedPnpmEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (/^(npm_config_|pnpm_)/iu.test(key))
+            continue;
+        env[key] = value;
+    }
+    // Real corepack knobs (COREPACK_ENABLE is not a corepack variable).
+    env["COREPACK_ENABLE_NETWORK"] = "0";
+    env["COREPACK_ENABLE_PROJECT_SPEC"] = "0";
+    env["COREPACK_ENABLE_STRICT"] = "0";
+    env["COREPACK_ENABLE_DOWNLOAD_PROMPT"] = "0";
+    return env;
+}
+// Assert the reconstructed dependency tree is contained within the disposable
+// checkout. Resolves symlinks so a redirected node_modules/virtual store that
+// points at the caller (or anywhere outside checkoutRoot) fails closed.
+export function assertDependencyContainment(checkoutRoot) {
+    const boundary = realpathSync(checkoutRoot);
+    for (const relative of ["node_modules", join("node_modules", ".pnpm")]) {
+        const target = join(checkoutRoot, relative);
+        if (!existsSync(target))
+            continue;
+        const resolved = realpathSync(target);
+        if (resolved !== boundary && !resolved.startsWith(boundary + sep)) {
+            throw new Error(`projected dependency path escapes the review checkout: ${relative} -> ${resolved}`);
+        }
     }
-    symlinkSync(callerPath, targetPath, "dir");
-    projected.add(dependencyPath);
-    return projected;
 }
+/** Test-only surface for porcelain path parsing. */
+export const reviewCheckoutInternals = {
+    statusEntryPath,
+};

package/dist/esm/review/execution/sandbox/adapter.d.ts

@@ -0,0 +1,37 @@
+import type { GateSandboxPolicy, SandboxedInvocation } from "#review/execution/sandbox/types.js";
+export type SrtWrapResult = {
+    readonly argv: readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+};
+export type SrtSandboxManager = {
+    wrapWithSandboxArgv(command: string, binShell: undefined, customConfig: unknown): Promise<SrtWrapResult>;
+    cleanupAfterCommand(): void | Promise<void>;
+    isSupportedPlatform(): boolean;
+    checkDependencies(): {
+        readonly errors: readonly string[];
+        readonly warnings: readonly string[];
+    };
+};
+export type SrtModule = {
+    readonly SandboxManager: SrtSandboxManager;
+};
+/**
+ * Dynamically imports srt so an unresolvable module (e.g. under the bun-compiled
+ * `wp` binary, where srt's prebuilt vendor assets are unreachable) degrades to a
+ * probe failure instead of crashing the CLI at load time.
+ */
+export declare function loadSrt(): Promise<SrtModule>;
+/**
+ * Wraps a resolved gate invocation for sandboxed execution using srt's
+ * no-initialize pattern: the full policy is passed as `customConfig`, so srt
+ * starts no proxies or lifecycle and the wrapped command is safe to run under a
+ * blocking spawn. The returned env is the caller-provided allowlist (srt injects
+ * its sandbox markers via argv, not env).
+ */
+export declare function wrapGateForSandbox(invocation: {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+}, policy: GateSandboxPolicy, srt?: SrtModule): Promise<SandboxedInvocation>;
+/** Decrements srt's per-process active-sandbox counter (Linux mount cleanup). */
+export declare function cleanupSandboxCommand(srt?: SrtModule): Promise<void>;

package/dist/esm/review/execution/sandbox/adapter.js

@@ -0,0 +1,39 @@
+import { buildGateSandboxConfig } from "#review/execution/sandbox/policy.js";
+import { shellQuoteArgv } from "#review/execution/sandbox/shell-quote.js";
+import { withSandboxTmpdir } from "#review/execution/sandbox/tmpdir.js";
+let srtModulePromise;
+/**
+ * Dynamically imports srt so an unresolvable module (e.g. under the bun-compiled
+ * `wp` binary, where srt's prebuilt vendor assets are unreachable) degrades to a
+ * probe failure instead of crashing the CLI at load time.
+ */
+export function loadSrt() {
+    srtModulePromise ??= import("@anthropic-ai/sandbox-runtime");
+    return srtModulePromise;
+}
+/**
+ * Wraps a resolved gate invocation for sandboxed execution using srt's
+ * no-initialize pattern: the full policy is passed as `customConfig`, so srt
+ * starts no proxies or lifecycle and the wrapped command is safe to run under a
+ * blocking spawn. The returned env is the caller-provided allowlist (srt injects
+ * its sandbox markers via argv, not env).
+ */
+export async function wrapGateForSandbox(invocation, policy, srt) {
+    const { SandboxManager } = srt ?? (await loadSrt());
+    const config = buildGateSandboxConfig(policy);
+    const commandString = shellQuoteArgv([invocation.command, ...invocation.args]);
+    // Serialize only the wrap (srt reads CLAUDE_CODE_TMPDIR here to bake the
+    // child's per-run TMPDIR into the argv); the returned argv carries it, so the
+    // subsequent gate run needs no shared process state.
+    const wrapped = await withSandboxTmpdir(policy.runTmpDir, () => SandboxManager.wrapWithSandboxArgv(commandString, undefined, config));
+    const [command, ...args] = wrapped.argv;
+    if (command === undefined) {
+        throw new Error("sandbox wrap returned an empty argv");
+    }
+    return { command, args, env: invocation.env };
+}
+/** Decrements srt's per-process active-sandbox counter (Linux mount cleanup). */
+export async function cleanupSandboxCommand(srt) {
+    const { SandboxManager } = srt ?? (await loadSrt());
+    await SandboxManager.cleanupAfterCommand();
+}

package/dist/esm/review/execution/sandbox/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds the allowlist environment for a sandboxed gate spawn. This REPLACES
+ * the caller's `process.env` (the secret-leak fix): only non-sensitive,
+ * toolchain-required variables are copied. `PATH` is passed through here and
+ * the checkout `bin` dir is prepended by `resolveAllowedWpInvocation`. `HOME`
+ * and `TMPDIR` point into the disposable run dir so a gate that writes to
+ * either cannot reach the caller's real home or a shared host tmp.
+ *
+ * Secrets and injection vectors (`NODE_OPTIONS`, `BASH_ENV`, `LD_PRELOAD`,
+ * `DYLD_INSERT_LIBRARIES`, cloud tokens, …) are simply never copied.
+ */
+export declare function buildSandboxedGateEnv(runTmpDir: string): NodeJS.ProcessEnv;

package/dist/esm/review/execution/sandbox/env.js

@@ -0,0 +1,37 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+const ENV_PASSTHROUGH = ["LANG", "LC_ALL"];
+/**
+ * Builds the allowlist environment for a sandboxed gate spawn. This REPLACES
+ * the caller's `process.env` (the secret-leak fix): only non-sensitive,
+ * toolchain-required variables are copied. `PATH` is passed through here and
+ * the checkout `bin` dir is prepended by `resolveAllowedWpInvocation`. `HOME`
+ * and `TMPDIR` point into the disposable run dir so a gate that writes to
+ * either cannot reach the caller's real home or a shared host tmp.
+ *
+ * Secrets and injection vectors (`NODE_OPTIONS`, `BASH_ENV`, `LD_PRELOAD`,
+ * `DYLD_INSERT_LIBRARIES`, cloud tokens, …) are simply never copied.
+ */
+export function buildSandboxedGateEnv(runTmpDir) {
+    const home = join(runTmpDir, "home");
+    const temp = join(runTmpDir, "tmp");
+    mkdirSync(home, { recursive: true });
+    mkdirSync(temp, { recursive: true });
+    const env = {
+        HOME: home,
+        TMPDIR: temp,
+        TERM: "dumb",
+        CI: "1",
+        NO_COLOR: "1",
+        WP_FORCE_SOURCE: "1",
+    };
+    const path = process.env["PATH"];
+    if (path !== undefined)
+        env["PATH"] = path;
+    for (const key of ENV_PASSTHROUGH) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}

package/dist/esm/review/execution/sandbox/index.d.ts

@@ -0,0 +1,5 @@
+export type { SandboxAvailability, GateSandboxPolicy, SandboxedInvocation, } from "#review/execution/sandbox/types.js";
+export { resolveSandboxAvailability, resetSandboxAvailabilityCache, } from "#review/execution/sandbox/probe.js";
+export { wrapGateForSandbox, cleanupSandboxCommand, loadSrt, } from "#review/execution/sandbox/adapter.js";
+export { buildSandboxedGateEnv } from "#review/execution/sandbox/env.js";
+export { buildGateSandboxConfig } from "#review/execution/sandbox/policy.js";

package/dist/esm/review/execution/sandbox/index.js

@@ -0,0 +1,4 @@
+export { resolveSandboxAvailability, resetSandboxAvailabilityCache, } from "#review/execution/sandbox/probe.js";
+export { wrapGateForSandbox, cleanupSandboxCommand, loadSrt, } from "#review/execution/sandbox/adapter.js";
+export { buildSandboxedGateEnv } from "#review/execution/sandbox/env.js";
+export { buildGateSandboxConfig } from "#review/execution/sandbox/policy.js";