@velum-labs/routekit-eval-setup 1.3.2 → 1.5.0

package/dist/adapters/repository-command-runner.js

@@ -0,0 +1,1483 @@
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { cp, lstat, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { promisify } from "node:util";
+import { Clock, Context, Effect, Exit, Option, ScopedCache } from "effect";
+import { RepositoryFoundryError } from "../errors.js";
+import { RepositoryFoundryEvidenceReconstruction } from "../services/evidence-reconstruction/service.js";
+import { RepositoryCommandObservability } from "../services/command-observability/service.js";
+import { sanitizeRepositoryCommandOutputV1 } from "./repository-command-diagnostic.js";
+import { repositoryCommandExecutionIncompleteV1 } from "./repository-command-evidence.js";
+import { repositoryNodeTestArgumentsV1 } from "./repository-node-test-reporter.js";
+import { repositoryVitestReporterSourceV1, repositoryVitestTestArgumentsV1 } from "./repository-vitest-reporter.js";
+import { repositoryVitestPhaseAdapterV1 } from "./repository-vitest-phase-adapter.js";
+export const RepositoryCommandExecutionPort = Context.Reference("@velum-labs/routekit-eval-setup/RepositoryCommandExecutionPort", {
+    defaultValue: () => undefined
+});
+/** Host-provided, versioned pnpm store populated before an offline invocation. */
+export const RepositoryReadOnlyPnpmStore = Context.Reference("@velum-labs/routekit-eval-setup/RepositoryReadOnlyPnpmStore", { defaultValue: () => undefined });
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const MAX_OBSERVED_COMMAND_BYTES = 64 * 1024;
+const MAX_OBSERVED_CHUNK_BYTES = 2 * 1024;
+const MAX_OBSERVED_CHUNKS_PER_FLUSH = 8;
+const OBSERVED_COMMAND_FLUSH_MS = 250;
+const execFilePromise = promisify(execFile);
+const ALLOWED_EXECUTABLES = new Set([
+    "corepack",
+    "node",
+    "pnpm",
+    "python",
+    "python3",
+    "go",
+    "cargo"
+]);
+const commandPath = [dirname(process.execPath), process.env.PATH]
+    .filter((value) => value !== undefined && value.length > 0)
+    .join(delimiter);
+const corepackHome = process.env.COREPACK_HOME ??
+    (process.env.HOME === undefined
+        ? undefined
+        : join(process.env.HOME, ".cache", "node", "corepack"));
+const trustedPnpmStoreRoot = join(tmpdir(), `routekit-foundry-pnpm-store-${String(process.pid)}-${randomUUID()}`);
+const failure = (operation, detail, cause) => new RepositoryFoundryError({
+    operation,
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+const pathWithin = (root, candidate) => {
+    const path = relative(root, candidate);
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+};
+const sbplPath = (path) => JSON.stringify(path);
+const createDarwinSandboxProfiles = async (input) => {
+    const candidateProfile = join(input.root, "repository-command-candidate.sb");
+    const trustedPreparationProfile = join(input.root, "repository-command-trusted-preparation.sb");
+    const optionalReadRoots = [
+        dirname(dirname(process.execPath)),
+        process.env.PNPM_HOME,
+        corepackHome,
+        process.env.HOME === undefined ? undefined : join(process.env.HOME, "Library", "pnpm"),
+        input.trustedPnpmStore
+    ].filter((candidate) => candidate !== undefined && candidate.length > 0);
+    const readRoots = [
+        input.root,
+        "/bin",
+        "/Library/Developer/CommandLineTools",
+        "/sbin",
+        "/usr/bin",
+        "/usr/local",
+        "/opt/homebrew",
+        ...optionalReadRoots
+    ];
+    const common = [
+        "(version 1)",
+        "(deny default)",
+        '(import "system.sb")',
+        "(allow process*)",
+        // Test runners must be able to reap their own worker processes. This does
+        // not permit signals to the host, sibling candidates or unrelated jobs.
+        "(allow signal (target children))",
+        "(allow file-read-metadata file-test-existence)",
+        `(allow file-read* file-test-existence file-map-executable ${readRoots
+            .map((candidate) => `(subpath ${sbplPath(candidate)})`)
+            .join(" ")})`
+    ];
+    const writableIsolationRoots = `(allow file-write* (subpath ${sbplPath(input.checkout)}) (subpath ${sbplPath(input.home)}) (subpath ${sbplPath(input.temporary)}))`;
+    const candidateSource = [
+        ...common,
+        writableIsolationRoots,
+        `(deny file-write* (subpath ${sbplPath(join(input.checkout, ".git"))}))`,
+        "(deny network*)",
+        ""
+    ].join("\n");
+    const trustedPreparationSource = [
+        ...common,
+        `(allow file-write* (subpath ${sbplPath(input.checkout)}) (subpath ${sbplPath(input.home)}) (subpath ${sbplPath(input.temporary)})${input.trustedPnpmStore === undefined || input.trustedPnpmStoreReadOnly
+            ? ""
+            : ` (subpath ${sbplPath(input.trustedPnpmStore)})`})`,
+        `(deny file-write* (subpath ${sbplPath(join(input.checkout, ".git"))}))`,
+        "(allow network*)",
+        ""
+    ].join("\n");
+    await Promise.all([
+        writeFile(candidateProfile, candidateSource, {
+            encoding: "utf8",
+            mode: 0o600
+        }),
+        writeFile(trustedPreparationProfile, trustedPreparationSource, {
+            encoding: "utf8",
+            mode: 0o600
+        })
+    ]);
+    return {
+        candidate: candidateProfile,
+        trustedPreparation: trustedPreparationProfile
+    };
+};
+const materializeIsolatedRepository = async (input) => {
+    const startedAt = Date.now();
+    const root = await realpath(await mkdtemp(join(tmpdir(), input.preparingTemplate ? "routekit-foundry-prepared-" : "routekit-foundry-isolated-")));
+    const checkout = join(root, "repository");
+    const home = join(root, "home");
+    const temporary = join(root, "tmp");
+    const archive = join(root, "source.tar");
+    await Promise.all([
+        mkdir(checkout, { recursive: true }),
+        mkdir(home, { recursive: true }),
+        mkdir(temporary, { recursive: true })
+    ]);
+    try {
+        if (input.template !== undefined) {
+            if (process.platform === "darwin") {
+                // Native traversal avoids fs.cp's per-file JS overhead on large pnpm
+                // installations. -c uses clonefile with ordinary-copy fallback; -P keeps
+                // symlinks intact, and neither mode creates hard links to the template.
+                await execFilePromise("/bin/cp", ["-cR", "-P", `${input.template.isolated.checkout}/`, checkout], {
+                    encoding: "utf8",
+                    maxBuffer: MAX_OUTPUT_BYTES,
+                    timeout: 60000,
+                    env: { PATH: commandPath }
+                });
+            }
+            else {
+                await cp(input.template.isolated.checkout, checkout, {
+                    recursive: true,
+                    mode: constants.COPYFILE_FICLONE,
+                    dereference: false,
+                    verbatimSymlinks: true
+                });
+            }
+            // pnpm shell launchers can embed absolute NODE_PATH prefixes. A fresh clone
+            // must resolve its own dependencies, never the immutable template's files.
+            for (const path of input.template.relocatedFiles) {
+                const destination = join(checkout, path);
+                const content = await readFile(destination, "utf8");
+                await writeFile(destination, content.replaceAll(input.template.isolated.checkout, checkout));
+            }
+        }
+        else {
+            await execFilePromise("git", [
+                "-C",
+                input.repositoryRoot,
+                "archive",
+                "--format=tar",
+                `--output=${archive}`,
+                input.commit
+            ], {
+                encoding: "utf8",
+                maxBuffer: MAX_OUTPUT_BYTES,
+                windowsHide: true,
+                env: {
+                    PATH: process.env.PATH,
+                    HOME: process.env.HOME,
+                    TMPDIR: process.env.TMPDIR
+                }
+            });
+            await execFilePromise("tar", ["-xf", archive, "-C", checkout], {
+                encoding: "utf8",
+                maxBuffer: MAX_OUTPUT_BYTES,
+                windowsHide: true
+            });
+            await rm(archive);
+            const gitOptions = {
+                encoding: "utf8",
+                maxBuffer: MAX_OUTPUT_BYTES,
+                windowsHide: true
+            };
+            await execFilePromise("git", ["-C", checkout, "init", "-q"], gitOptions);
+            await execFilePromise("git", ["-C", checkout, "config", "user.name", "RouteKit Repository Foundry"], gitOptions);
+            await execFilePromise("git", ["-C", checkout, "config", "user.email", "repository-foundry@routekit.invalid"], gitOptions);
+            await execFilePromise("git", ["-C", checkout, "config", "commit.gpgsign", "false"], gitOptions);
+            await execFilePromise("git", ["-C", checkout, "add", "-A"], gitOptions);
+            await execFilePromise("git", [
+                "-C",
+                checkout,
+                "commit",
+                "-q",
+                "--no-gpg-sign",
+                "--date=2000-01-01T00:00:00Z",
+                "-m",
+                "isolated foundry baseline"
+            ], gitOptions);
+        }
+        const canonicalRoot = await realpath(root);
+        const canonicalCheckout = await realpath(checkout);
+        const canonicalHome = await realpath(home);
+        const canonicalTemporary = await realpath(temporary);
+        const sandboxProfiles = process.platform === "darwin"
+            ? await createDarwinSandboxProfiles({
+                root: canonicalRoot,
+                checkout: canonicalCheckout,
+                home: canonicalHome,
+                temporary: canonicalTemporary,
+                ...(input.trustedPnpmStore === undefined
+                    ? {}
+                    : {
+                        trustedPnpmStore: input.trustedPnpmStore,
+                        trustedPnpmStoreReadOnly: input.trustedPnpmStoreReadOnly ?? false
+                    })
+            })
+            : undefined;
+        return {
+            root: canonicalRoot,
+            checkout: canonicalCheckout,
+            home: canonicalHome,
+            temporary: canonicalTemporary,
+            materializationDurationMs: Date.now() - startedAt,
+            timings: {
+                checkoutDurationMs: Date.now() - startedAt,
+                overlayDurationMs: 0,
+                cleanupDurationMs: 0
+            },
+            ...(sandboxProfiles === undefined
+                ? {}
+                : {
+                    candidateSandboxProfile: sandboxProfiles.candidate,
+                    trustedPreparationSandboxProfile: sandboxProfiles.trustedPreparation
+                }),
+            ...(input.trustedPnpmStore === undefined
+                ? {}
+                : {
+                    trustedPnpmStore: input.trustedPnpmStore,
+                    trustedPnpmStoreReadOnly: input.trustedPnpmStoreReadOnly ?? false
+                })
+        };
+    }
+    catch (cause) {
+        await rm(root, { recursive: true, force: true });
+        throw cause;
+    }
+};
+const exactPnpmSpecifier = /^pnpm@(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+const pnpmCommandIndex = (args) => {
+    let index = 1;
+    while (args[index] === "--filter") {
+        const selector = args[index + 1];
+        if (selector === undefined || selector.length === 0 || selector.startsWith("-")) {
+            return undefined;
+        }
+        index += 2;
+    }
+    return index < args.length ? index : undefined;
+};
+const isPnpmInstallRecipe = (recipe) => recipe.executable === "corepack" &&
+    exactPnpmSpecifier.test(recipe.args[0] ?? "") &&
+    recipe.args[pnpmCommandIndex(recipe.args) ?? -1] === "install";
+const reusableFrozenInstallRecipe = (recipe) => {
+    if (recipe.executable !== "corepack" ||
+        recipe.cwd !== "." ||
+        !exactPnpmSpecifier.test(recipe.args[0] ?? "")) {
+        return false;
+    }
+    const commandIndex = pnpmCommandIndex(recipe.args);
+    if (commandIndex === undefined || recipe.args[commandIndex] !== "install")
+        return false;
+    const required = new Set(["--frozen-lockfile", "--ignore-scripts", "--ignore-pnpmfile"]);
+    for (let index = commandIndex + 1; index < recipe.args.length; index += 1) {
+        const argument = recipe.args[index];
+        if (required.delete(argument) || argument === "--prefer-offline" || argument === "--offline") {
+            continue;
+        }
+        if (argument === "--filter" &&
+            (recipe.args[index + 1]?.length ?? 0) > 0 &&
+            !recipe.args[index + 1].startsWith("-")) {
+            index += 1;
+            continue;
+        }
+        return false;
+    }
+    return required.size === 0;
+};
+const materializeExactPnpmShim = async (isolatedRoot, recipe) => {
+    const specifier = recipe.executable === "corepack" ? recipe.args[0] : undefined;
+    if (specifier === undefined || !exactPnpmSpecifier.test(specifier))
+        return undefined;
+    const directory = join(isolatedRoot, "repository-command-bin");
+    await mkdir(directory, { recursive: true });
+    if (process.platform === "win32") {
+        await writeFile(join(directory, "pnpm.cmd"), `@echo off\r\ncorepack ${specifier} %*\r\n`, {
+            encoding: "utf8",
+            mode: 0o700
+        });
+    }
+    else {
+        await writeFile(join(directory, "pnpm"), `#!/bin/sh\nexec corepack ${specifier} "$@"\n`, {
+            encoding: "utf8",
+            mode: 0o700
+        });
+    }
+    return directory;
+};
+const validateRecipe = (recipe, checkout, stage) => {
+    if (!ALLOWED_EXECUTABLES.has(recipe.executable)) {
+        throw new Error(`command executable is not allowed: ${JSON.stringify(recipe.executable)}`);
+    }
+    if (recipe.cwd.trim().length === 0 ||
+        isAbsolute(recipe.cwd) ||
+        recipe.cwd.split(/[\\/]/u).includes("..") ||
+        recipe.cwd.includes("\0")) {
+        throw new Error(`command cwd is not a canonical relative path: ${JSON.stringify(recipe.cwd)}`);
+    }
+    if (!Number.isInteger(recipe.timeoutMs) ||
+        recipe.timeoutMs < 1 ||
+        recipe.timeoutMs > 30 * 60_000) {
+        throw new Error("command timeout must be between 1 ms and 30 minutes");
+    }
+    if (recipe.args.some((arg) => arg.includes("\0") || /^(?:--cwd|-C)$/u.test(arg) || /^--cwd=/u.test(arg))) {
+        throw new Error("command arguments must not override the reviewed cwd");
+    }
+    if (stage === "trusted-preparation" &&
+        recipe.executable === "corepack" &&
+        !exactPnpmSpecifier.test(recipe.args[0] ?? "")) {
+        throw new Error("corepack commands require an exact pnpm semantic version");
+    }
+    if (stage === "trusted-preparation" &&
+        isPnpmInstallRecipe(recipe) &&
+        !reusableFrozenInstallRecipe(recipe)) {
+        throw new Error("trusted pnpm preparation requires a frozen lockfile with scripts and pnpm hooks disabled");
+    }
+    const cwd = resolve(checkout, recipe.cwd);
+    if (!pathWithin(checkout, cwd)) {
+        throw new Error("command cwd escapes the isolated checkout");
+    }
+    return cwd;
+};
+const applyCandidatePatch = (checkout, patch) => {
+    if (Buffer.byteLength(patch, "utf8") > MAX_OUTPUT_BYTES) {
+        return Effect.fail(failure("prepare-checkout", "candidate patch exceeds the 2 MiB limit"));
+    }
+    return Effect.callback((resume, interruptionSignal) => {
+        const child = spawn("git", ["-C", checkout, "apply", "--whitespace=nowarn", "--recount", "-"], {
+            stdio: ["pipe", "ignore", "pipe"],
+            env: {
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+                TMPDIR: process.env.TMPDIR
+            }
+        });
+        let settled = false;
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            if (Buffer.byteLength(stderr) < MAX_OUTPUT_BYTES)
+                stderr += chunk;
+        });
+        child.once("error", (cause) => {
+            if (settled)
+                return;
+            settled = true;
+            resume(Effect.fail(failure("prepare-checkout", "could not apply candidate patch", cause)));
+        });
+        child.once("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resume(code === 0
+                ? Effect.void
+                : Effect.fail(failure("prepare-checkout", `candidate patch did not apply: ${stderr.trim()}`)));
+        });
+        const interrupt = () => {
+            child.kill("SIGKILL");
+        };
+        interruptionSignal.addEventListener("abort", interrupt, { once: true });
+        child.stdin.end(patch, "utf8");
+        return Effect.sync(() => {
+            interruptionSignal.removeEventListener("abort", interrupt);
+            if (!settled)
+                child.kill("SIGKILL");
+        });
+    });
+};
+// Host writes are outside the candidate sandbox. A lexical path check alone
+// cannot protect the shared dependency store or host files from linked paths.
+// Each clone is private and no candidate runs while these overlays are installed.
+const assertHostOverlayDestination = async (checkout, path) => {
+    if (path.length === 0 ||
+        isAbsolute(path) ||
+        path.includes("\\") ||
+        path.includes("\0") ||
+        path.split("/").some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error("host overlay destination is not a canonical repository-relative file path");
+    }
+    const root = await lstat(checkout);
+    if (root.isSymbolicLink() || !root.isDirectory()) {
+        throw new Error("host overlay checkout root is not a regular directory");
+    }
+    let current = checkout;
+    const parts = path.split("/");
+    for (const [index, part] of parts.entries()) {
+        current = join(current, part);
+        let metadata;
+        try {
+            metadata = await lstat(current);
+        }
+        catch (cause) {
+            if (cause !== null &&
+                typeof cause === "object" &&
+                "code" in cause &&
+                cause.code === "ENOENT") {
+                return;
+            }
+            throw cause;
+        }
+        if (metadata.isSymbolicLink()) {
+            throw new Error("host overlay destination traverses a symbolic link");
+        }
+        if (index < parts.length - 1 ? !metadata.isDirectory() : !metadata.isFile()) {
+            throw new Error("host overlay destination is not a regular file beneath regular directories");
+        }
+    }
+};
+const applyOverlays = Effect.fn("RepositoryFoundry.applyCommandOverlays")(function* (input) {
+    for (const overlay of input.overlays) {
+        if (overlay.path.trim().length === 0 ||
+            isAbsolute(overlay.path) ||
+            overlay.path.split(/[\\/]/u).includes("..") ||
+            overlay.path.includes("\0")) {
+            return yield* failure("prepare-checkout", `overlay path is unsafe: ${JSON.stringify(overlay.path)}`);
+        }
+        const destination = resolve(input.checkout, overlay.path);
+        if (!pathWithin(input.checkout, destination)) {
+            return yield* failure("prepare-checkout", `overlay path escapes checkout: ${JSON.stringify(overlay.path)}`);
+        }
+        const content = yield* Effect.tryPromise({
+            try: async () => {
+                const result = await execFilePromise("git", ["-C", input.repositoryRoot, "show", `${overlay.sourceCommit}:${overlay.path}`], {
+                    encoding: "buffer",
+                    maxBuffer: MAX_OUTPUT_BYTES,
+                    windowsHide: true
+                });
+                return result.stdout;
+            },
+            catch: (cause) => failure("prepare-checkout", `could not read reviewed overlay ${overlay.sourceCommit}:${overlay.path}`, cause)
+        });
+        yield* Effect.tryPromise({
+            try: async () => {
+                await assertHostOverlayDestination(input.checkout, overlay.path);
+                await mkdir(dirname(destination), { recursive: true });
+                await writeFile(destination, content);
+            },
+            catch: (cause) => failure("prepare-checkout", `could not materialize reviewed overlay ${JSON.stringify(overlay.path)}`, cause)
+        });
+    }
+});
+const applyFileOverrides = Effect.fn("RepositoryFoundry.applyCommandFileOverrides")(function* (input) {
+    for (const override of input.overrides) {
+        if (override.path.trim().length === 0 ||
+            isAbsolute(override.path) ||
+            override.path.split(/[\\/]/u).includes("..") ||
+            override.path.includes("\0")) {
+            return yield* failure("prepare-checkout", `file override path is unsafe: ${JSON.stringify(override.path)}`);
+        }
+        const destination = resolve(input.checkout, override.path);
+        if (!pathWithin(input.checkout, destination)) {
+            return yield* failure("prepare-checkout", `file override path escapes checkout: ${JSON.stringify(override.path)}`);
+        }
+        yield* Effect.tryPromise({
+            try: async () => {
+                await assertHostOverlayDestination(input.checkout, override.path);
+                if ("delete" in override) {
+                    try {
+                        const metadata = await lstat(destination);
+                        if (metadata.isSymbolicLink() || !metadata.isFile()) {
+                            throw new Error("file deletion override can only remove a regular file");
+                        }
+                        await rm(destination);
+                    }
+                    catch (cause) {
+                        if (cause !== null &&
+                            typeof cause === "object" &&
+                            "code" in cause &&
+                            cause.code === "ENOENT") {
+                            return;
+                        }
+                        throw cause;
+                    }
+                    return;
+                }
+                await mkdir(dirname(destination), { recursive: true });
+                await writeFile(destination, override.content, "utf8");
+            },
+            catch: (cause) => failure("prepare-checkout", `could not materialize file override ${JSON.stringify(override.path)}`, cause)
+        });
+    }
+});
+const applyContentOverlays = Effect.fn("RepositoryFoundry.applyCommandContentOverlays")(function* (input) {
+    for (const overlay of input.overlays) {
+        if (overlay.path.trim().length === 0 ||
+            isAbsolute(overlay.path) ||
+            overlay.path.split(/[\\/]/u).includes("..") ||
+            overlay.path.includes("\0")) {
+            return yield* failure("prepare-checkout", `content overlay path is unsafe: ${JSON.stringify(overlay.path)}`);
+        }
+        const destination = resolve(input.checkout, overlay.path);
+        if (!pathWithin(input.checkout, destination)) {
+            return yield* failure("prepare-checkout", `content overlay path escapes checkout: ${JSON.stringify(overlay.path)}`);
+        }
+        yield* Effect.tryPromise({
+            try: async () => {
+                await assertHostOverlayDestination(input.checkout, overlay.path);
+                await mkdir(dirname(destination), { recursive: true });
+                await writeFile(destination, overlay.content, "utf8");
+            },
+            catch: (cause) => failure("prepare-checkout", `could not materialize content overlay ${JSON.stringify(overlay.path)}`, cause)
+        });
+    }
+});
+const runCommand = Effect.fn("RepositoryFoundry.runCommand")(function* (input) {
+    const cwd = yield* Effect.try({
+        try: () => validateRecipe(input.recipe, input.isolated.checkout, input.stage),
+        catch: (cause) => failure("run-command", cause instanceof Error ? cause.message : String(cause), cause)
+    });
+    const vitestReporterPath = join(input.isolated.root, `vitest-reporter-${createHash("sha256").update(input.recipe.id).digest("hex")}.mjs`);
+    const vitestArguments = input.stage === "grade"
+        ? repositoryVitestTestArgumentsV1(input.recipe, vitestReporterPath)
+        : undefined;
+    if (vitestArguments !== undefined) {
+        yield* Effect.tryPromise({
+            try: async () => {
+                const phaseAdapterPath = `${vitestReporterPath}.phase.mjs`;
+                const phase = await repositoryVitestPhaseAdapterV1({
+                    cwd,
+                    checkout: input.isolated.checkout
+                });
+                if (phase.supported) {
+                    await writeFile(phaseAdapterPath, phase.source, {
+                        encoding: "utf8",
+                        mode: 0o600,
+                        flag: "wx"
+                    });
+                }
+                await writeFile(vitestReporterPath, repositoryVitestReporterSourceV1({
+                    phaseAdapterPath,
+                    runtimeSupported: phase.supported
+                }), {
+                    encoding: "utf8",
+                    mode: 0o600,
+                    flag: "wx"
+                });
+            },
+            catch: (cause) => failure("run-command", "could not materialize the host-owned Vitest phase adapter", cause)
+        });
+    }
+    const reporterMetadata = vitestArguments === undefined ? {} : { testReporter: "vitest-v1" };
+    const commandArgs = vitestArguments ??
+        (input.stage === "grade" ? repositoryNodeTestArgumentsV1(input.recipe) : input.recipe.args);
+    const exactPnpmBin = yield* Effect.tryPromise({
+        try: () => materializeExactPnpmShim(input.isolated.root, input.recipe),
+        catch: (cause) => failure("run-command", "could not materialize the exact pnpm command shim", cause)
+    });
+    const commandObservability = yield* Effect.serviceOption(RepositoryCommandObservability);
+    const executionPort = yield* RepositoryCommandExecutionPort;
+    if (executionPort !== undefined) {
+        const startedAt = yield* Clock.currentTimeMillis;
+        const commandId = randomUUID();
+        const observe = (event) => {
+            if (Option.isSome(commandObservability)) {
+                try {
+                    commandObservability.value.observe(event);
+                }
+                catch {
+                    /* telemetry never changes scientific decisions */
+                }
+            }
+        };
+        const common = {
+            version: 1,
+            commandId,
+            recipeId: input.recipe.id,
+            repetition: input.repetition,
+            stage: input.stage
+        };
+        observe({ ...common, kind: "started", at: new Date(startedAt).toISOString() });
+        const sandboxProfile = input.stage === "trusted-preparation"
+            ? input.isolated.trustedPreparationSandboxProfile
+            : input.isolated.candidateSandboxProfile;
+        const result = yield* executionPort.run({
+            operationId: commandId,
+            cwd,
+            executable: sandboxProfile === undefined ? input.recipe.executable : "/usr/bin/sandbox-exec",
+            args: sandboxProfile === undefined
+                ? commandArgs
+                : ["-f", sandboxProfile, input.recipe.executable, ...commandArgs],
+            environment: {
+                PATH: exactPnpmBin === undefined ? commandPath : [exactPnpmBin, commandPath].join(delimiter),
+                HOME: input.isolated.home,
+                TMPDIR: input.isolated.temporary,
+                ...(corepackHome === undefined ? {} : { COREPACK_HOME: corepackHome }),
+                ...(input.isolated.trustedPnpmStore === undefined
+                    ? {}
+                    : {
+                        npm_config_store_dir: input.isolated.trustedPnpmStore,
+                        pnpm_config_store_dir: input.isolated.trustedPnpmStore,
+                        ...(input.isolated.trustedPnpmStoreReadOnly
+                            ? { pnpm_config_frozen_store: "true", npm_config_frozen_store: "true" }
+                            : {}),
+                        ...(input.stage === "trusted-preparation"
+                            ? {}
+                            : {
+                                npm_config_offline: "true",
+                                pnpm_config_offline: "true",
+                                pnpm_config_verify_deps_before_run: "false"
+                            })
+                    }),
+                CI: "1",
+                NO_COLOR: "1",
+                FORCE_COLOR: "0",
+                PORTLESS: "0"
+            },
+            timeoutMs: input.recipe.timeoutMs
+        });
+        const endedAt = yield* Clock.currentTimeMillis;
+        let sequence = 0;
+        let commandBytes = 0;
+        for (const stream of ["stdout", "stderr"]) {
+            const bytes = Buffer.from(sanitizeRepositoryCommandOutputV1(result[stream]), "utf8");
+            const decoder = new StringDecoder("utf8");
+            for (let offset = 0; offset < bytes.length; offset += MAX_OBSERVED_CHUNK_BYTES) {
+                const chunk = decoder.write(bytes.subarray(offset, offset + MAX_OBSERVED_CHUNK_BYTES)) +
+                    (offset + MAX_OBSERVED_CHUNK_BYTES >= bytes.length ? decoder.end() : "");
+                commandBytes += Buffer.byteLength(chunk);
+                sequence += 1;
+                observe({
+                    ...common,
+                    kind: "output",
+                    at: new Date(endedAt).toISOString(),
+                    stream,
+                    sequence,
+                    chunk,
+                    chunkBytes: Buffer.byteLength(chunk),
+                    commandBytes,
+                    truncated: false
+                });
+            }
+        }
+        observe({
+            ...common,
+            kind: "completed",
+            at: new Date(endedAt).toISOString(),
+            exitCode: result.exitCode,
+            timedOut: result.timedOut ?? false,
+            durationMs: endedAt - startedAt,
+            commandBytes,
+            truncated: false
+        });
+        return {
+            recipeId: input.recipe.id,
+            commit: input.commit,
+            repetition: input.repetition,
+            stage: input.stage,
+            exitCode: result.exitCode,
+            timedOut: result.timedOut ?? false,
+            outputTruncated: false,
+            stdout: sanitizeRepositoryCommandOutputV1(result.stdout),
+            stderr: sanitizeRepositoryCommandOutputV1(result.stderr),
+            durationMs: endedAt - startedAt,
+            ...reporterMetadata
+        };
+    }
+    return yield* Effect.callback((resume, interruptionSignal) => {
+        const startedAt = Date.now();
+        const commandId = randomUUID();
+        const observe = (event) => {
+            if (Option.isNone(commandObservability))
+                return;
+            try {
+                commandObservability.value.observe(event);
+            }
+            catch {
+                // Observability is best-effort and must never affect repository execution.
+            }
+        };
+        const sandboxProfile = input.stage === "trusted-preparation"
+            ? input.isolated.trustedPreparationSandboxProfile
+            : input.isolated.candidateSandboxProfile;
+        const executable = sandboxProfile === undefined ? input.recipe.executable : "/usr/bin/sandbox-exec";
+        const args = sandboxProfile === undefined
+            ? [...commandArgs]
+            : ["-f", sandboxProfile, input.recipe.executable, ...commandArgs];
+        const detached = process.platform !== "win32";
+        const child = spawn(executable, args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached,
+            env: {
+                PATH: exactPnpmBin === undefined ? commandPath : [exactPnpmBin, commandPath].join(delimiter),
+                HOME: input.isolated.home,
+                TMPDIR: input.isolated.temporary,
+                ...(corepackHome === undefined ? {} : { COREPACK_HOME: corepackHome }),
+                ...(input.isolated.trustedPnpmStore === undefined
+                    ? {}
+                    : {
+                        // pnpm 11 reads pnpm_config_ settings. Keep the npm_config_
+                        // spelling as well for repositories pinned to older pnpm.
+                        npm_config_store_dir: input.isolated.trustedPnpmStore,
+                        pnpm_config_store_dir: input.isolated.trustedPnpmStore,
+                        ...(input.isolated.trustedPnpmStoreReadOnly
+                            ? { pnpm_config_frozen_store: "true", npm_config_frozen_store: "true" }
+                            : {}),
+                        ...(input.stage === "trusted-preparation"
+                            ? {}
+                            : {
+                                npm_config_offline: "true",
+                                pnpm_config_offline: "true",
+                                pnpm_config_verify_deps_before_run: "false"
+                            })
+                    }),
+                CI: "1",
+                NO_COLOR: "1",
+                FORCE_COLOR: "0",
+                PORTLESS: "0"
+            }
+        });
+        observe({
+            version: 1,
+            kind: "started",
+            at: new Date(startedAt).toISOString(),
+            commandId,
+            recipeId: input.recipe.id,
+            repetition: input.repetition,
+            stage: input.stage
+        });
+        let stdout = "";
+        let stderr = "";
+        let outputBytes = 0;
+        let outputTruncated = false;
+        let observedCommandBytes = 0;
+        let observedSequence = 0;
+        let observedTruncated = false;
+        let observedContentDropped = false;
+        let observedTimer;
+        const observedPending = [];
+        const streamState = {
+            stdout: { decoder: new StringDecoder("utf8"), line: "", privateKey: false },
+            stderr: { decoder: new StringDecoder("utf8"), line: "", privateKey: false }
+        };
+        let timedOut = false;
+        let settled = false;
+        let forcedSettlement;
+        const takeUtf8Prefix = (value, maximumBytes) => {
+            if (Buffer.byteLength(value, "utf8") <= maximumBytes)
+                return value;
+            let bytes = 0;
+            let prefix = "";
+            for (const character of value) {
+                const width = Buffer.byteLength(character, "utf8");
+                if (bytes + width > maximumBytes)
+                    break;
+                prefix += character;
+                bytes += width;
+            }
+            return prefix;
+        };
+        const pendingBytes = () => observedPending.reduce((total, entry) => total + Buffer.byteLength(entry.text, "utf8"), 0);
+        const flushObserved = (maximumChunks = MAX_OBSERVED_CHUNKS_PER_FLUSH, scheduleRemainder = true) => {
+            observedTimer = undefined;
+            let flushed = 0;
+            while (flushed < maximumChunks) {
+                const current = observedPending[0];
+                if (current === undefined)
+                    break;
+                const chunk = takeUtf8Prefix(current.text, MAX_OBSERVED_CHUNK_BYTES);
+                if (chunk.length === 0) {
+                    observedPending.shift();
+                    continue;
+                }
+                const chunkBytes = Buffer.byteLength(chunk, "utf8");
+                current.text = current.text.slice(chunk.length);
+                if (current.text.length === 0)
+                    observedPending.shift();
+                observedCommandBytes += chunkBytes;
+                observe({
+                    version: 1,
+                    kind: "output",
+                    at: new Date().toISOString(),
+                    commandId,
+                    recipeId: input.recipe.id,
+                    repetition: input.repetition,
+                    stage: input.stage,
+                    stream: current.stream,
+                    sequence: ++observedSequence,
+                    chunk,
+                    chunkBytes,
+                    commandBytes: observedCommandBytes,
+                    truncated: observedTruncated || observedContentDropped
+                });
+                flushed += 1;
+            }
+            if (scheduleRemainder && observedPending.length > 0) {
+                observedTimer = setTimeout(flushObserved, OBSERVED_COMMAND_FLUSH_MS);
+            }
+        };
+        const scheduleObservedFlush = () => {
+            if (observedTimer !== undefined || observedPending.length === 0)
+                return;
+            observedTimer = setTimeout(flushObserved, OBSERVED_COMMAND_FLUSH_MS);
+        };
+        const enqueueObserved = (stream, value) => {
+            if (value.length === 0 || observedTruncated)
+                return;
+            const remaining = MAX_OBSERVED_COMMAND_BYTES - observedCommandBytes - pendingBytes();
+            if (remaining <= 0) {
+                observedTruncated = true;
+                return;
+            }
+            const sanitized = sanitizeRepositoryCommandOutputV1(value);
+            const accepted = takeUtf8Prefix(sanitized, remaining);
+            if (accepted.length === 0)
+                return;
+            if (Buffer.byteLength(accepted, "utf8") < Buffer.byteLength(sanitized, "utf8")) {
+                observedTruncated = true;
+            }
+            const last = observedPending.at(-1);
+            if (last?.stream === stream)
+                last.text += accepted;
+            else
+                observedPending.push({ stream, text: accepted });
+            scheduleObservedFlush();
+        };
+        const acceptObservedText = (stream, value, final = false) => {
+            if (observedTruncated)
+                return;
+            const state = streamState[stream];
+            state.line += value;
+            const pieces = state.line.split(/(?<=\n)/u);
+            state.line = final ? "" : (pieces.pop() ?? "");
+            if (Buffer.byteLength(state.line, "utf8") > MAX_OBSERVED_COMMAND_BYTES) {
+                // Never retain an unbounded unterminated line. Dropping the line is
+                // safer than cutting through a credential-shaped value.
+                state.line = "";
+                observedContentDropped = true;
+            }
+            let safe = "";
+            for (const line of pieces) {
+                if (state.privateKey) {
+                    if (/-----END [A-Z0-9 ]*PRIVATE KEY-----/u.test(line)) {
+                        safe += "[redacted]\n";
+                        state.privateKey = false;
+                    }
+                    continue;
+                }
+                if (/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/u.test(line)) {
+                    if (/-----END [A-Z0-9 ]*PRIVATE KEY-----/u.test(line)) {
+                        safe += sanitizeRepositoryCommandOutputV1(line);
+                    }
+                    else {
+                        state.privateKey = true;
+                    }
+                    continue;
+                }
+                if (Buffer.byteLength(line, "utf8") > MAX_OBSERVED_COMMAND_BYTES) {
+                    observedContentDropped = true;
+                    continue;
+                }
+                safe += line;
+            }
+            if (final && state.privateKey) {
+                safe += "[redacted]\n";
+                state.privateKey = false;
+            }
+            enqueueObserved(stream, safe);
+        };
+        const finalizeObserved = () => {
+            if (observedTimer !== undefined) {
+                clearTimeout(observedTimer);
+                observedTimer = undefined;
+            }
+            for (const stream of ["stdout", "stderr"]) {
+                const state = streamState[stream];
+                acceptObservedText(stream, state.decoder.end(), true);
+            }
+            if (observedTimer !== undefined) {
+                clearTimeout(observedTimer);
+                observedTimer = undefined;
+            }
+            flushObserved(Number.POSITIVE_INFINITY, false);
+        };
+        const observeCompleted = (exitCode, commandTimedOut) => {
+            finalizeObserved();
+            observe({
+                version: 1,
+                kind: "completed",
+                at: new Date().toISOString(),
+                commandId,
+                recipeId: input.recipe.id,
+                repetition: input.repetition,
+                stage: input.stage,
+                exitCode,
+                timedOut: commandTimedOut,
+                durationMs: Date.now() - startedAt,
+                commandBytes: observedCommandBytes,
+                truncated: observedTruncated || observedContentDropped
+            });
+        };
+        const killProcessTree = () => {
+            if (detached && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                    return;
+                }
+                catch {
+                    // Fall through if the process group already exited.
+                }
+            }
+            child.kill("SIGKILL");
+        };
+        const settleTimedOut = () => {
+            if (settled)
+                return;
+            settled = true;
+            child.stdout.destroy();
+            child.stderr.destroy();
+            observeCompleted(null, true);
+            resume(Effect.succeed({
+                recipeId: input.recipe.id,
+                commit: input.commit,
+                repetition: input.repetition,
+                stage: input.stage,
+                exitCode: null,
+                timedOut: true,
+                outputTruncated,
+                stdout,
+                stderr,
+                durationMs: Date.now() - startedAt,
+                ...reporterMetadata
+            }));
+        };
+        const append = (target, chunk) => {
+            acceptObservedText(target, streamState[target].decoder.write(chunk));
+            const remaining = MAX_OUTPUT_BYTES - outputBytes;
+            if (remaining <= 0) {
+                outputTruncated = true;
+                return;
+            }
+            const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, remaining);
+            outputBytes += accepted.byteLength;
+            if (accepted.byteLength < chunk.byteLength)
+                outputTruncated = true;
+            if (target === "stdout")
+                stdout += accepted.toString("utf8");
+            else
+                stderr += accepted.toString("utf8");
+        };
+        child.stdout.on("data", (chunk) => append("stdout", chunk));
+        child.stderr.on("data", (chunk) => append("stderr", chunk));
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            killProcessTree();
+            forcedSettlement = setTimeout(settleTimedOut, 2_000);
+        }, input.recipe.timeoutMs);
+        child.once("error", (cause) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedSettlement !== undefined)
+                clearTimeout(forcedSettlement);
+            observeCompleted(null, false);
+            resume(Effect.fail(failure("run-command", `could not start ${input.recipe.executable}`, cause)));
+        });
+        child.once("close", (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forcedSettlement !== undefined)
+                clearTimeout(forcedSettlement);
+            observeCompleted(exitCode, timedOut);
+            resume(Effect.succeed({
+                recipeId: input.recipe.id,
+                commit: input.commit,
+                repetition: input.repetition,
+                stage: input.stage,
+                exitCode,
+                timedOut,
+                outputTruncated,
+                stdout,
+                stderr,
+                durationMs: Date.now() - startedAt,
+                ...reporterMetadata
+            }));
+        });
+        const interrupt = () => {
+            killProcessTree();
+        };
+        interruptionSignal.addEventListener("abort", interrupt, { once: true });
+        return Effect.sync(() => {
+            interruptionSignal.removeEventListener("abort", interrupt);
+            clearTimeout(timeout);
+            if (forcedSettlement !== undefined)
+                clearTimeout(forcedSettlement);
+            if (observedTimer !== undefined)
+                clearTimeout(observedTimer);
+            if (!settled)
+                killProcessTree();
+        });
+    });
+});
+const commandPassed = (result) => result.exitCode === 0 && !repositoryCommandExecutionIncompleteV1(result);
+const runRecipeSequence = Effect.fn("RepositoryFoundry.runCommandRecipeSequence")(function* (input) {
+    const results = [];
+    for (const recipe of input.recipes) {
+        const result = yield* runCommand({
+            isolated: input.isolated,
+            commit: input.commit,
+            repetition: input.repetition,
+            stage: input.stage,
+            recipe
+        });
+        results.push(result);
+        if (!commandPassed(result))
+            break;
+    }
+    return results;
+});
+const terminalResult = (terminal, input) => ({
+    ...terminal,
+    gradeExecuted: input.gradeExecuted,
+    trustedPreparationResults: input.trustedPreparationResults,
+    candidateValidationResults: input.candidateValidationResults,
+    ...(input.preparation === undefined ? {} : { preparation: input.preparation }),
+    ...(input.isolationTimings === undefined ? {} : { isolationTimings: input.isolationTimings })
+});
+const acquireCheckout = (root, commit, trustedPnpmStore, template, preparingTemplate) => Effect.gen(function* () {
+    const readOnlyStore = yield* RepositoryReadOnlyPnpmStore;
+    return yield* Effect.acquireRelease(Effect.tryPromise({
+        try: () => materializeIsolatedRepository({
+            repositoryRoot: root,
+            commit,
+            ...(trustedPnpmStore === undefined
+                ? {}
+                : { trustedPnpmStore, trustedPnpmStoreReadOnly: readOnlyStore !== undefined }),
+            ...(template === undefined ? {} : { template }),
+            ...(preparingTemplate === undefined ? {} : { preparingTemplate })
+        }),
+        catch: (cause) => failure("prepare-checkout", "could not materialize isolated single-commit repository", cause)
+    }), (isolated) => Effect.tryPromise({
+        try: async () => {
+            const startedAt = Date.now();
+            try {
+                await rm(isolated.root, { recursive: true, force: true });
+            }
+            finally {
+                isolated.timings.cleanupDurationMs = Date.now() - startedAt;
+            }
+        },
+        catch: () => undefined
+    }).pipe(Effect.ignore));
+});
+const resolveTrustedPnpmStore = Effect.fn("RepositoryFoundry.resolveTrustedPnpmStore")(function* (recipes) {
+    const specifiers = [
+        ...new Set(recipes.flatMap((recipe) => isPnpmInstallRecipe(recipe)
+            ? [recipe.args[0]]
+            : []))
+    ];
+    if (specifiers.length === 0)
+        return undefined;
+    if (specifiers.length !== 1) {
+        return yield* failure("prepare-checkout", "trusted preparation must use one exact pnpm version");
+    }
+    const readOnlyStore = yield* RepositoryReadOnlyPnpmStore;
+    if (readOnlyStore !== undefined) {
+        if (!isAbsolute(readOnlyStore) ||
+            !recipes.every((recipe) => isPnpmInstallRecipe(recipe) &&
+                recipe.args.includes("--offline"))) {
+            return yield* failure("prepare-checkout", "a host-provided read-only pnpm store requires an absolute path and offline installation");
+        }
+        return yield* Effect.tryPromise({
+            try: async () => {
+                const path = await realpath(readOnlyStore);
+                if (!(await lstat(path)).isDirectory()) {
+                    throw new Error("the prehydrated pnpm store is not a directory");
+                }
+                return path;
+            },
+            catch: (cause) => failure("prepare-checkout", "the host-provided read-only pnpm store is unavailable", cause)
+        });
+    }
+    const path = yield* Effect.tryPromise({
+        try: async () => {
+            await mkdir(trustedPnpmStoreRoot, { recursive: true, mode: 0o700 });
+            const result = await execFilePromise("corepack", [specifiers[0], "store", "path", "--silent"], {
+                encoding: "utf8",
+                maxBuffer: MAX_OUTPUT_BYTES,
+                windowsHide: true,
+                env: {
+                    PATH: commandPath,
+                    HOME: process.env.HOME,
+                    TMPDIR: process.env.TMPDIR,
+                    ...(corepackHome === undefined ? {} : { COREPACK_HOME: corepackHome }),
+                    // pnpm derives its default store from the operating-system account
+                    // home, not HOME. Immutable sandbox images deliberately make that
+                    // account home read-only, so bind the trusted content-addressed
+                    // store to a private writable runtime directory explicitly.
+                    npm_config_store_dir: trustedPnpmStoreRoot,
+                    pnpm_config_store_dir: trustedPnpmStoreRoot
+                }
+            });
+            const requested = result.stdout.trim();
+            if (requested.length === 0 ||
+                !isAbsolute(requested) ||
+                !pathWithin(trustedPnpmStoreRoot, requested)) {
+                throw new Error("pnpm returned a store path outside the trusted runtime root");
+            }
+            await mkdir(requested, { recursive: true });
+            return realpath(requested);
+        },
+        catch: (cause) => failure("prepare-checkout", "could not resolve the trusted pnpm content-addressed store", cause)
+    });
+    return path;
+});
+const reusableFrozenInstall = (recipes) => {
+    return recipes.length === 1 && reusableFrozenInstallRecipe(recipes[0]);
+};
+/** Normalize generated links once, and inventory pnpm files needing clone-local prefixes. */
+const prepareTemplateRelocation = async (isolated) => {
+    const relocatedFiles = [];
+    const visit = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                const target = await readlink(path);
+                const resolved = resolve(directory, target);
+                if (pathWithin(isolated.checkout, resolved)) {
+                    if (isAbsolute(target)) {
+                        await rm(path);
+                        await symlink(relative(directory, resolved), path);
+                    }
+                }
+                else if (isolated.trustedPnpmStore === undefined ||
+                    !pathWithin(isolated.trustedPnpmStore, resolved)) {
+                    throw new Error("pristine installation contains a symlink outside its repository and trusted store");
+                }
+            }
+            else if (entry.isDirectory()) {
+                if (path !== join(isolated.checkout, ".git"))
+                    await visit(path);
+            }
+            else if (entry.isFile() &&
+                (directory.endsWith(`${sep}node_modules${sep}.bin`) ||
+                    entry.name === ".modules.yaml" ||
+                    entry.name === ".pnpm-workspace-state-v1.json")) {
+                if ((await readFile(path, "utf8")).includes(isolated.checkout)) {
+                    relocatedFiles.push(relative(isolated.checkout, path));
+                }
+            }
+        }
+    };
+    await visit(isolated.checkout);
+    return relocatedFiles;
+};
+/** Installation reuse is bounded to these immutable commits and this owning Effect scope. */
+export const makeRepositoryPreparationCacheV1 = Effect.fn("RepositoryFoundry.makePreparationCache")(function* (input) {
+    const repositoryRoot = yield* resolveRepositoryRoot(input.repositoryRoot);
+    const recipes = input.trustedPreparationRecipes;
+    const commits = new Set(input.commits);
+    const eligible = 
+    // Both supported Unix runners materialize ordinary or copy-on-write file
+    // copies, never hard links. Every repetition receives a private checkout
+    // before candidate overlays are applied, while candidate commands are
+    // forced onto the selected pnpm store in offline/frozen-store mode.
+    (process.platform === "darwin" || process.platform === "linux") &&
+        commits.size <= 2 &&
+        [...commits].every((commit) => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(commit)) &&
+        reusableFrozenInstall(recipes);
+    const recipeIdentity = JSON.stringify(recipes);
+    const cache = yield* ScopedCache.makeWith({
+        capacity: Number.POSITIVE_INFINITY, // At most the two explicitly pinned historical commits.
+        timeToLive: (exit) => (Exit.isSuccess(exit) ? "Infinity" : 0),
+        lookup: Effect.fnUntraced(function* (commit) {
+            const trustedPnpmStore = yield* resolveTrustedPnpmStore(recipes);
+            const key = createHash("sha256")
+                .update(JSON.stringify({
+                version: 1,
+                repositoryRoot,
+                commit,
+                recipes,
+                node: process.version,
+                executable: process.execPath,
+                platform: process.platform,
+                arch: process.arch,
+                commandPath,
+                corepackHome,
+                trustedPnpmStore
+            }))
+                .digest("hex");
+            const isolated = yield* acquireCheckout(repositoryRoot, commit, trustedPnpmStore, undefined, true);
+            const preparationResults = yield* runRecipeSequence({
+                isolated,
+                commit,
+                repetition: 0,
+                stage: "trusted-preparation",
+                recipes
+            });
+            if (preparationResults.some((result) => !commandPassed(result))) {
+                return yield* failure("prepare-checkout", "pristine frozen installation failed; no reusable template was published", { templateKey: key, commit, trustedPreparationResults: preparationResults });
+            }
+            const relocatedFiles = yield* Effect.tryPromise({
+                try: () => prepareTemplateRelocation(isolated),
+                catch: (cause) => failure("prepare-checkout", "pristine installation cannot be safely relocated", cause)
+            });
+            return {
+                isolated,
+                key,
+                preparationResults,
+                relocatedFiles
+            };
+        })
+    });
+    const preparationCache = {
+        get: (requested) => eligible &&
+            requested.repositoryRoot === repositoryRoot &&
+            commits.has(requested.commit) &&
+            JSON.stringify(requested.recipes) === recipeIdentity
+            ? ScopedCache.get(cache, requested.commit)
+            : Effect.succeed(undefined)
+    };
+    return preparationCache;
+});
+const prepareCheckout = Effect.fn("RepositoryFoundry.prepareCommandCheckout")(function* (input) {
+    if (input.patch !== undefined) {
+        yield* applyCandidatePatch(input.checkout, input.patch);
+    }
+    yield* applyFileOverrides({
+        checkout: input.checkout,
+        overrides: input.fileOverrides
+    });
+    yield* applyOverlays({
+        repositoryRoot: input.repositoryRoot,
+        checkout: input.checkout,
+        overlays: input.overlays
+    });
+    yield* applyContentOverlays({
+        checkout: input.checkout,
+        overlays: input.contentOverlays
+    });
+});
+const resolveRepositoryRoot = (repositoryRoot) => Effect.tryPromise({
+    try: () => realpath(repositoryRoot),
+    catch: (cause) => failure("resolve-repository", `failed to resolve ${JSON.stringify(repositoryRoot)}`, cause)
+});
+export const replayRepositoryCommandsV1 = Effect.fn("RepositoryFoundry.replayRepositoryCommands")(function* (input) {
+    const reconstruction = yield* Effect.serviceOption(RepositoryFoundryEvidenceReconstruction);
+    if (Option.isSome(reconstruction))
+        return yield* reconstruction.value.commands(input);
+    if (input.recipes.length === 0 ||
+        new Set(input.recipes.map((recipe) => recipe.id)).size !== input.recipes.length) {
+        return yield* failure("run-command", "repository replay requires one or more uniquely identified grade recipes");
+    }
+    const root = yield* resolveRepositoryRoot(input.repositoryRoot);
+    const template = input.preparationCache === undefined
+        ? undefined
+        : yield* input.preparationCache.get({
+            repositoryRoot: root,
+            commit: input.commit,
+            recipes: input.trustedPreparationRecipes ?? []
+        });
+    const trustedPnpmStore = template === undefined
+        ? yield* resolveTrustedPnpmStore(input.trustedPreparationRecipes ?? [])
+        : template.isolated.trustedPnpmStore;
+    const repetitions = Math.max(1, Math.min(input.repetitions ?? 2, 5));
+    const repetitionStart = Math.max(1, Math.min(Math.trunc(input.repetitionStart ?? 1), 5));
+    const results = [];
+    for (let repetition = repetitionStart; repetition < repetitionStart + repetitions; repetition += 1) {
+        results.push(...(yield* Effect.scoped(Effect.gen(function* () {
+            const isolated = yield* acquireCheckout(root, input.commit, trustedPnpmStore, template);
+            const checkout = isolated.checkout;
+            const preparation = template === undefined
+                ? undefined
+                : {
+                    kind: "pristine-install-template",
+                    templateKey: template.key,
+                    sourceCommit: input.commit,
+                    cloneDurationMs: isolated.materializationDurationMs,
+                    sharedResults: template.preparationResults
+                };
+            const trustedPreparationResults = template === undefined
+                ? yield* runRecipeSequence({
+                    isolated,
+                    commit: input.commit,
+                    repetition,
+                    stage: "trusted-preparation",
+                    recipes: input.trustedPreparationRecipes ?? []
+                })
+                : [];
+            const failedPreparation = trustedPreparationResults.find((result) => !commandPassed(result));
+            if (failedPreparation !== undefined) {
+                return [
+                    terminalResult(failedPreparation, {
+                        gradeExecuted: false,
+                        trustedPreparationResults,
+                        candidateValidationResults: [],
+                        preparation,
+                        isolationTimings: isolated.timings
+                    })
+                ];
+            }
+            const overlayStartedAt = Date.now();
+            yield* prepareCheckout({
+                repositoryRoot: root,
+                checkout,
+                ...(input.patch === undefined ? {} : { patch: input.patch }),
+                overlays: input.overlays ?? [],
+                contentOverlays: input.contentOverlays ?? [],
+                fileOverrides: input.fileOverrides ?? []
+            });
+            isolated.timings.overlayDurationMs = Date.now() - overlayStartedAt;
+            const candidateValidationResults = yield* runRecipeSequence({
+                isolated,
+                commit: input.commit,
+                repetition,
+                stage: "candidate-validation",
+                recipes: input.candidateValidationRecipes ?? []
+            });
+            const failedValidation = candidateValidationResults.find((result) => !commandPassed(result));
+            if (failedValidation !== undefined) {
+                return [
+                    terminalResult(failedValidation, {
+                        gradeExecuted: false,
+                        trustedPreparationResults,
+                        candidateValidationResults,
+                        preparation,
+                        isolationTimings: isolated.timings
+                    })
+                ];
+            }
+            const grades = [];
+            for (const recipe of input.recipes) {
+                const grade = yield* runCommand({
+                    isolated,
+                    commit: input.commit,
+                    repetition,
+                    stage: "grade",
+                    recipe
+                });
+                grades.push(terminalResult(grade, {
+                    gradeExecuted: true,
+                    trustedPreparationResults,
+                    candidateValidationResults,
+                    preparation,
+                    isolationTimings: isolated.timings
+                }));
+                // A killed process or incomplete capture cannot yield a grade.
+                // Retain it, release this checkout, and leave queued work unstarted.
+                if (repositoryCommandExecutionIncompleteV1(grade) &&
+                    input.continueAfterIncompleteGrade !== true)
+                    break;
+            }
+            return grades;
+        }))));
+    }
+    return results;
+});
+export const replayRepositoryCommandV1 = Effect.fn("RepositoryFoundry.replayRepositoryCommand")(function* (input) {
+    return yield* replayRepositoryCommandsV1({
+        repositoryRoot: input.repositoryRoot,
+        commit: input.commit,
+        recipes: [input.recipe],
+        ...(input.repetitions === undefined ? {} : { repetitions: input.repetitions }),
+        ...(input.overlays === undefined ? {} : { overlays: input.overlays }),
+        ...(input.contentOverlays === undefined ? {} : { contentOverlays: input.contentOverlays }),
+        ...(input.fileOverrides === undefined ? {} : { fileOverrides: input.fileOverrides }),
+        ...(input.patch === undefined ? {} : { patch: input.patch }),
+        ...(input.trustedPreparationRecipes === undefined
+            ? {}
+            : {
+                trustedPreparationRecipes: input.trustedPreparationRecipes
+            }),
+        ...(input.candidateValidationRecipes === undefined
+            ? {}
+            : {
+                candidateValidationRecipes: input.candidateValidationRecipes
+            })
+    });
+});
+const inspectPath = async (checkout, repositoryPath) => {
+    if (repositoryPath.trim().length === 0 ||
+        isAbsolute(repositoryPath) ||
+        repositoryPath.includes("\\") ||
+        repositoryPath.includes("\0") ||
+        repositoryPath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+        throw new Error(`inspection path is not a canonical repository-relative path: ${JSON.stringify(repositoryPath)}`);
+    }
+    const destination = resolve(checkout, repositoryPath);
+    if (!pathWithin(checkout, destination)) {
+        throw new Error(`inspection path escapes checkout: ${JSON.stringify(repositoryPath)}`);
+    }
+    let current = checkout;
+    const parts = repositoryPath.split("/");
+    for (let index = 0; index < parts.length; index += 1) {
+        current = join(current, parts[index]);
+        let metadata;
+        try {
+            metadata = await lstat(current);
+        }
+        catch (cause) {
+            if (cause !== null &&
+                typeof cause === "object" &&
+                "code" in cause &&
+                cause.code === "ENOENT") {
+                return "missing";
+            }
+            throw cause;
+        }
+        const final = index === parts.length - 1;
+        if (metadata.isSymbolicLink()) {
+            if (final)
+                return "symlink";
+            throw new Error(`inspection path traverses a symbolic link: ${JSON.stringify(repositoryPath)}`);
+        }
+        if (!final && !metadata.isDirectory())
+            return "missing";
+        if (final) {
+            if (metadata.isFile())
+                return "file";
+            if (metadata.isDirectory())
+                return "directory";
+            return "missing";
+        }
+    }
+    return "missing";
+};
+export const inspectRepositorySolutionPathsV1 = Effect.fn("RepositoryFoundry.inspectRepositorySolutionPaths")(function* (input) {
+    if (input.paths.length === 0) {
+        return yield* failure("prepare-checkout", "repository path inspection requires at least one path");
+    }
+    const paths = [...new Set(input.paths)];
+    const root = yield* resolveRepositoryRoot(input.repositoryRoot);
+    const repetitions = Math.max(1, Math.min(input.repetitions ?? 2, 5));
+    const results = [];
+    for (let repetition = 1; repetition <= repetitions; repetition += 1) {
+        results.push(...(yield* Effect.scoped(Effect.gen(function* () {
+            const isolated = yield* acquireCheckout(root, input.commit);
+            const checkout = isolated.checkout;
+            yield* prepareCheckout({
+                repositoryRoot: root,
+                checkout,
+                ...(input.patch === undefined ? {} : { patch: input.patch }),
+                overlays: [],
+                contentOverlays: [],
+                fileOverrides: input.fileOverrides ?? []
+            });
+            const inspected = [];
+            for (const repositoryPath of paths) {
+                const kind = yield* Effect.tryPromise({
+                    try: () => inspectPath(checkout, repositoryPath),
+                    catch: (cause) => failure("prepare-checkout", cause instanceof Error ? cause.message : String(cause), cause)
+                });
+                inspected.push({
+                    commit: input.commit,
+                    repetition,
+                    path: repositoryPath,
+                    kind
+                });
+            }
+            return inspected;
+        }))));
+    }
+    return results;
+});