@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/engine/agents/lib/shells.js

@@ -1,1052 +0,0 @@
-import { cpSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, symlinkSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, join, relative, sep as pathSep } from "node:path";
-import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { buildVerifiableContextSourceFiles } from "../../build/source-files.js";
-import { BUILD_PLAN_PACKAGE_DIR } from "../../../project/interf-detect.js";
-import { CHECK_KINDS, } from "../../../contracts/lib/schema.js";
-import { CONTEXT_INTERFACE_FILE as BUILD_PLAN_SCHEMA_FILE, contextInterfaceArtifactAbsolutePath as verifiableContextArtifactAbsolutePath, listContextInterfaceArtifacts, readContextInterface as readBuildPlanContextFile, resolveContextInterfacePath as resolveBuildPlanSchemaPath, } from "../../../build-plans/package/context-interface.js";
-import { stageExecutionShellsRoot, buildPlanImprovementLoopRoot, buildPlanPackagePathForVerifiableContext, verifiableContextInterfConfigPath, verifiableContextRuntimeRoot, verifiableContextRuntimeSourceSnapshotPath, verifiableContextRuntimeStageInputsPath, } from "../../build/verifiable-context-paths.js";
-import { ensureBuildPlanArtifactTargets } from "../../build/verifiable-context-schema.js";
-import { listFilesRecursive } from "../../../contracts/utils/filesystem.js";
-import { resolveBuildPlanImprovementReviewSourcePaths } from "../../../build-plans/package/build-plan-review-paths.js";
-const LOCAL_SKILL_ROOTS = [
-    ".claude/skills",
-    ".codex/skills",
-    ".agents/skills",
-    ".cursor/skills",
-];
-export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skillContent) {
-    let changed = false;
-    changed = writeIfChanged(join(rootPath, "AGENTS.md"), `${agentsContent.trimEnd()}\n`) || changed;
-    changed =
-        writeIfChanged(join(rootPath, "CLAUDE.md"), renderClaudeBootstrap(agentsContent)) || changed;
-    changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
-    return changed;
-}
-function verifiableContextQuerySkillSourcePath(verifiableContextPath) {
-    return join(buildPlanPackagePathForVerifiableContext(verifiableContextPath), "use", "query", "SKILL.md");
-}
-function verifiableContextArtifactSummaryLines(verifiableContextPath) {
-    const schema = readBuildPlanContextFile(buildPlanPackagePathForVerifiableContext(verifiableContextPath));
-    if (!schema)
-        return ["- No Build Plan schema is available yet."];
-    return listContextInterfaceArtifacts(schema)
-        .filter((artifact) => artifact.kind !== "runtime")
-        .map((artifact) => `- \`${artifact.id}\` -> \`${artifact.path}\` (${artifact.role} ${artifact.kind})`);
-}
-export function renderVerifiableContextAgents(verifiableContextPath, name, buildPlanId, about, options = {}) {
-    const buildPlanOriginSelected = options.buildPlanOriginSelected ?? buildPlanId;
-    const buildPlanLocalDraft = options.buildPlanLocalDraft === true;
-    const artifactLines = verifiableContextArtifactSummaryLines(verifiableContextPath);
-    return [
-        `# ${name}`,
-        "",
-        "This is verifiable context built by Interf.",
-        "This folder gives agents prepared evidence, structure, and cross-file connections so they do not have to rediscover the full picture from source files during the job.",
-        "",
-        ...(about
-            ? [
-                `About: ${about}`,
-                "",
-            ]
-            : []),
-        "## How to use this verifiable context",
-        "",
-        "1. Use the local native `interf-query` skill that Interf generated for this verifiable context.",
-        "2. Let the Build Plan docs and declared Artifacts guide retrieval instead of assuming a fixed note layout.",
-        "3. Use `.interf/runtime/source-snapshot.json` when you need to inspect the source references behind the output.",
-        "",
-        "## How this verifiable context works",
-        "",
-        "- The Build Plan defines the context interface this verifiable context implements on disk.",
-        "- `.interf/interf.json` records the selected Source binding and Preparation metadata.",
-        `- Build Plan seed: \`${buildPlanOriginSelected}\`.`,
-        ...(buildPlanLocalDraft
-            ? ["- This verifiable context now carries a local Build Plan draft improved from that seed. Rebuilding this verifiable context reuses the local `.interf/build-plan/` package."]
-            : []),
-        `- Selected Build Plan id: \`${buildPlanId}\`.`,
-        "- `.interf/build-plan/` is the local editable Build Plan package for this verifiable context.",
-        `- \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` is the deterministic context interface for this verifiable context.`,
-        "- `.interf/build-plan/improve/` is the editable source for Build Plan improvement loops.",
-        "- `.interf/build-plan/use/query/` is the editable source for the generated native query shell.",
-        "- `.interf/build-plan/build/stages/` defines stage-specific docs that Interf projects into native execution shells for automated runs.",
-        "- Native local query skills are generated under local agent skill directories such as `.claude/skills/` and `.codex/skills/`.",
-        "- `.interf/runtime/source-snapshot.json` records the source files assigned to the latest runtime snapshot.",
-        `- Build Plan Artifacts are declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\`.`,
-        ...artifactLines,
-        "- `.interf/runtime/` holds runtime artifacts written by Interf.",
-        "- `.interf/tests/` mirrors the latest saved readiness-check run and keeps detailed target runs plus preserved sandboxes.",
-        "- `.interf/tests/targets/` holds detailed source-files and verifiable-context target runs plus preserved test sandboxes.",
-        "",
-        "## Manual query rules",
-        "",
-        "- Prefer the Build Plan-declared context outputs before source re-checks.",
-        "- Use the generated native `interf-query` skill for manual querying. The editable source lives at `.interf/build-plan/use/query/SKILL.md`.",
-        "- Treat `.interf/` as Build Plan/runtime metadata, not answer evidence, unless explicitly asked to inspect Build Plan or test history.",
-        "- Use `.interf/runtime/source-snapshot.json` to find source references for quotes, verification, ambiguity, or evidence the verifiable context does not expose well.",
-        "- If exact chart, table, or image-derived evidence matters, inspect the source reference and say whether the answer was text-derived, table-derived, or chart-derived.",
-        "",
-        "## Commands",
-        "",
-        "```",
-        "interf build <prep-id>    build this verifiable context",
-        "interf test               run readiness checks against this verifiable context",
-        "interf status             show deterministic health",
-        "```",
-        "",
-        "## Rules",
-        "",
-        "- Do not modify source files while answering from this verifiable context.",
-        "- Treat prepared notes as working context, not final truth.",
-        "- When confidence is low, verify against the source references before answering strongly.",
-        "",
-    ].join("\n");
-}
-export function renderVerifiableContextQuerySkill() {
-    return [
-        "# Manual Query Loop",
-        "",
-        "This file is the editable authoring source for the generated native local `interf-query` skill.",
-        "",
-        "Default loop:",
-        "1. Read `.interf/build-plan/README.md` and this file first.",
-        `2. Use the Build Plan Artifacts declared in \`.interf/build-plan/${BUILD_PLAN_SCHEMA_FILE}\` before consulting source references.`,
-        "3. Use `.interf/runtime/source-snapshot.json` for direct quotes, verification, exact lookups, and cases where the verifiable context is missing the needed evidence or is ambiguous.",
-        "",
-        "Answering rule:",
-        "- do not modify source files while answering",
-        "- treat the Build Plan as the verifiable-context contract and use its Artifacts as the working retrieval surface",
-        "- say explicitly when an answer depends on approximation, bounded inference, or a source re-check",
-        "- use source references to confirm source page, metric family, provenance, or exact wording when the verifiable context is missing the needed evidence or is ambiguous",
-        "- do not invent navigation or note structure beyond what this Build Plan declares",
-        "- when the verifiable context is insufficient, verify against source references and then answer",
-        "",
-        "You can edit this file to bias manual question-answering behavior for this verifiable context.",
-        "",
-    ].join("\n");
-}
-function renderSourceFilesTestAgents() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note) => `- ${note}`);
-    return [
-        "# Source Files Test Shell",
-        "",
-        "This is an isolated source-files test shell generated by Interf.",
-        "There is no verifiable context in this shell.",
-        "",
-        "## How to use this shell",
-        "",
-        "1. Read this file first.",
-        "2. Use the local native `interf-query` skill available in this shell.",
-        "3. Read `runtime/source-files.json` and use only the listed source references.",
-        "",
-        "## Rules",
-        "",
-        "- Answer only from source files listed in `runtime/source-files.json`.",
-        "- There is no verifiable context here, so do not assume any verifiable-context Artifacts exist.",
-        "- Do not treat hidden runtime files or test artifacts as evidence.",
-        ...chartNotes,
-        "- Write the requested answer and trace files, then stop.",
-        "",
-    ].join("\n");
-}
-function renderSourceFilesTestQuerySkill() {
-    const chartNotes = CHART_APPROXIMATION_NOTES.map((note, index) => `${index + 3}. ${note}`);
-    return [
-        "---",
-        "name: interf-query",
-        "description: >",
-        "  Native local query skill for an Interf source-files test shell. Use it only",
-        "  to answer source-files readiness checks from `runtime/source-files.json` references.",
-        "---",
-        "",
-        "# Interf Source Files Test Query",
-        "",
-        "This is the native local query skill for an isolated source-files test shell.",
-        "",
-        "Loop:",
-        "1. Read `runtime/source-files.json`.",
-        "2. Verify exact claims against the listed source locators before answering strongly.",
-        ...chartNotes,
-        "8. Do not rely on verifiable-context artifacts because they do not exist in this shell.",
-        "",
-    ].join("\n");
-}
-function readVerifiableContextQuerySkillSource(verifiableContextPath) {
-    const filePath = verifiableContextQuerySkillSourcePath(verifiableContextPath);
-    if (!existsSync(filePath)) {
-        throw new Error(`Missing verifiable-context query skill source at ${filePath}. Interf build runs the local Build Plan package directly, so reseed or repair this verifiable context instead of auto-healing query docs.`);
-    }
-    return readFileSync(filePath, "utf8").trim();
-}
-function stageShellBuildPlanRoot(shellRoot) {
-    return join(shellRoot, BUILD_PLAN_PACKAGE_DIR);
-}
-function shellInputArtifactPath(shellRoot, artifactId) {
-    return join(shellRoot, "inputs", artifactId);
-}
-function shellOutputArtifactPath(shellRoot, artifactId) {
-    return join(shellRoot, "outputs", artifactId);
-}
-function shellArtifactAliasMountPath(shellRoot, artifact, mountKind) {
-    const mountRoot = mountKind === "inputs"
-        ? shellInputArtifactPath(shellRoot, artifact.id)
-        : shellOutputArtifactPath(shellRoot, artifact.id);
-    return artifact.kind === "file"
-        ? join(mountRoot, basename(artifact.path))
-        : mountRoot;
-}
-function describeShellArtifactAliasMountPath(artifact, mountKind) {
-    return artifact.kind === "file"
-        ? `${mountKind}/${artifact.id}/${basename(artifact.path)}`
-        : `${mountKind}/${artifact.id}`;
-}
-function shellRuntimePath(shellRoot, relativePath) {
-    return join(shellRoot, "runtime", relativePath);
-}
-function writeIfChanged(path, content) {
-    if (existsSync(path) && readFileSync(path, "utf8") === content) {
-        return false;
-    }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content);
-    return true;
-}
-function writeNativeSkillCopies(rootPath, skillName, content) {
-    let changed = false;
-    for (const skillsRoot of LOCAL_SKILL_ROOTS) {
-        const skillPath = join(rootPath, skillsRoot, skillName, "SKILL.md");
-        changed = writeIfChanged(skillPath, content) || changed;
-    }
-    return changed;
-}
-function linkPath(targetPath, linkPathname) {
-    mkdirSync(dirname(linkPathname), { recursive: true });
-    symlinkSync(targetPath, linkPathname);
-}
-function linkIfExists(targetPath, linkPathname) {
-    if (!existsSync(targetPath))
-        return;
-    linkPath(targetPath, linkPathname);
-}
-function linkRelativePath(targetPath, linkPathname) {
-    mkdirSync(dirname(linkPathname), { recursive: true });
-    symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
-}
-function loadVerifiableContextSchema(verifiableContextPath) {
-    const buildPlanRoot = buildPlanPackagePathForVerifiableContext(verifiableContextPath);
-    const schema = readBuildPlanContextFile(buildPlanRoot);
-    if (!schema) {
-        throw new Error(`Missing Build Plan schema at ${join(buildPlanRoot, BUILD_PLAN_SCHEMA_FILE)}`);
-    }
-    return schema;
-}
-function artifactMap(schema) {
-    return new Map(listContextInterfaceArtifacts(schema).map((artifact) => [artifact.id, artifact]));
-}
-function artifactOrThrow(artifacts, artifactId) {
-    const artifact = artifacts.get(artifactId);
-    if (!artifact) {
-        throw new Error(`Missing Build Plan schema Artifact "${artifactId}" for stage shell projection.`);
-    }
-    return artifact;
-}
-function normalizeArtifactRelativePath(path) {
-    return path
-        .replaceAll("\\", "/")
-        .replace(/^\.?\//, "")
-        .replace(/\/+$/g, "");
-}
-function relativePathEqualsOrWithin(basePath, candidatePath) {
-    const base = normalizeArtifactRelativePath(basePath);
-    const candidate = normalizeArtifactRelativePath(candidatePath);
-    if (base.length === 0 || candidate.length === 0)
-        return false;
-    return candidate === base || candidate.startsWith(`${base}/`);
-}
-function stageWriteArtifactSet(schema, stage) {
-    const artifacts = listContextInterfaceArtifacts(schema);
-    return new Set(stage.writes.filter((artifactId) => artifacts.some((artifact) => artifact.id === artifactId)));
-}
-function stageMaterializedArtifactSet(schema, stage, writeArtifacts = []) {
-    const materialized = stageWriteArtifactSet(schema, stage);
-    for (const artifact of listContextInterfaceArtifacts(schema)) {
-        if (artifact.kind === "runtime" && stage.reads.includes(artifact.id)) {
-            materialized.add(artifact.id);
-        }
-    }
-    for (const artifactPath of writeArtifacts) {
-        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
-        if (normalizedArtifactPath.length === 0)
-            continue;
-        const owner = listContextInterfaceArtifacts(schema).find((artifact) => relativePathEqualsOrWithin(artifact.path, normalizedArtifactPath));
-        if (owner) {
-            materialized.add(owner.id);
-        }
-    }
-    return materialized;
-}
-function ensureShellLocalProjection(sourcePath, targetPath, artifact) {
-    if (existsSync(sourcePath)) {
-        copyResolvedTree({
-            sourcePath,
-            targetPath,
-            shellType: "stage-execution",
-        });
-        return;
-    }
-    if (artifact.kind === "file") {
-        mkdirSync(dirname(targetPath), { recursive: true });
-        return;
-    }
-    mkdirSync(targetPath, { recursive: true });
-}
-function ensureBuildExecutionSurface(verifiableContextPath) {
-    mkdirSync(verifiableContextRuntimeRoot(verifiableContextPath), { recursive: true });
-    mkdirSync(buildPlanPackagePathForVerifiableContext(verifiableContextPath), { recursive: true });
-    const schema = loadVerifiableContextSchema(verifiableContextPath);
-    ensureBuildPlanArtifactTargets(verifiableContextPath, schema);
-    return schema;
-}
-function readStageBuildPlanDoc(verifiableContextPath, stage) {
-    const path = join(buildPlanPackagePathForVerifiableContext(verifiableContextPath), "build", "stages", stage.skillDir, "SKILL.md");
-    if (!existsSync(path))
-        return null;
-    return readFileSync(path, "utf8").trim();
-}
-function stageBuildPlanDocsPath(verifiableContextPath, stage) {
-    return join(buildPlanPackagePathForVerifiableContext(verifiableContextPath), "build", "stages", stage.skillDir);
-}
-function renderStageExecutionAgents(verifiableContextName, buildPlanId, stage) {
-    return [
-        `# ${verifiableContextName} — ${stage.label} Execution Shell`,
-        "",
-        "This is an ephemeral stage-execution shell generated by Interf.",
-        "It is for automated pipeline execution only, not for manual querying.",
-        "",
-        "## Start Here",
-        "",
-        "1. Read `runtime/stage-contract.json` now.",
-        "2. Read `runtime/source-snapshot.json` and `runtime/stage-inputs.json` now.",
-        "3. Read `runtime/paths.json` now.",
-        "4. Use the local native `interf-stage` skill now.",
-        `5. Execute only the current stage: \`${stage.id}\` (${stage.label}).`,
-        "",
-        "## Shell ABI",
-        "",
-        "- `inputs/<artifact-id>/` = read mounts for the current stage.",
-        "- `outputs/<artifact-id>/` = write mounts for the current stage.",
-        "- For file Artifacts, `runtime/paths.json` points to the exact file path inside those mount roots.",
-        "- `runtime/source-snapshot.json` = source references captured for this run.",
-        "- `runtime/stage-inputs.json` = exact source references assigned to this stage.",
-        "- declared Artifact paths are also projected at the shell root so Build Plan-relative contract paths stay valid.",
-        "- `runtime/` = stage contract and machine-readable path map for this shell.",
-        "- `build-plan/` = Build Plan metadata, `build-plan.schema.json`, and docs for the current stage only.",
-        "",
-        "## Boundaries",
-        "",
-        `- Build Plan: \`${buildPlanId}\`.`,
-        `- Contract type: \`${stage.contractType}\`.`,
-        "- This shell has its own AGENTS/CLAUDE/native skills. It does not inherit the verifiable-context query shell.",
-        "- The verifiable-context root itself is not linked into this shell.",
-        "- Do not switch into query mode or act like a user-facing assistant.",
-        "- Do not modify files under `inputs/` unless the same Artifact is also mounted under `outputs/`.",
-        "",
-        "## Current Stage Artifacts",
-        "",
-        `- reads: ${stage.reads.join(", ")}`,
-        `- writes: ${stage.writes.join(", ")}`,
-        "",
-        "## Goal",
-        "",
-        "- complete the current stage",
-        "- honor the deterministic contract",
-        "- write outputs through the declared Artifact mounts",
-        "- stop when the stage is complete",
-        "",
-    ].join("\n");
-}
-function renderStageExecutionSkill(stage, stageBuildPlanDoc) {
-    return [
-        "---",
-        "name: interf-stage",
-        "description: >",
-        `  Native local execution skill for the ${stage.label} stage in this`,
-        "  Interf run. Use it only inside an automated stage execution shell.",
-        "---",
-        "",
-        `# Interf Stage Execution — ${stage.label}`,
-        "",
-        "This local native skill exists for automated Interf stage execution.",
-        "Read `runtime/stage-contract.json` first.",
-        "Then read `runtime/source-snapshot.json`, `runtime/stage-inputs.json`, and `runtime/paths.json`.",
-        "Use the assigned source references and the mounted `inputs/` and `outputs/` Artifacts for this stage.",
-        "Do not switch into manual query mode.",
-        "",
-        "## Current Stage",
-        "",
-        `- id: \`${stage.id}\``,
-        `- label: ${stage.label}`,
-        `- contract type: \`${stage.contractType}\``,
-        `- reads: ${stage.reads.join(", ")}`,
-        `- writes: ${stage.writes.join(", ")}`,
-        `- editable source: \`build-plan/build/stages/${stage.skillDir}/SKILL.md\``,
-        "",
-        ...(stageBuildPlanDoc
-            ? [
-                "## Stage Build Plan",
-                "",
-                stageBuildPlanDoc,
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-function renderVerifiableContextQueryNativeSkill(querySkillContent) {
-    return [
-        "---",
-        "name: interf-query",
-        "description: >",
-        "  Native local query skill for verifiable context built by Interf.",
-        "  Use it for manual questions against verifiable context and source references.",
-        "---",
-        "",
-        "# Interf Query",
-        "",
-        "This is the native local query skill for verifiable context built by Interf.",
-        "Use it when reading this verifiable context manually.",
-        "Editable source: `.interf/build-plan/use/query/SKILL.md`.",
-        "",
-        querySkillContent.trim(),
-        "",
-    ].join("\n");
-}
-function projectBuildPlanMetadata(verifiableContextPath, shellRoot, stage) {
-    const shellBuildPlanRoot = stageShellBuildPlanRoot(shellRoot);
-    mkdirSync(join(shellBuildPlanRoot, "build", "stages"), { recursive: true });
-    const verifiableContextBuildPlanRoot = buildPlanPackagePathForVerifiableContext(verifiableContextPath);
-    const buildPlanJsonPath = join(verifiableContextBuildPlanRoot, "build-plan.json");
-    if (existsSync(buildPlanJsonPath)) {
-        linkPath(buildPlanJsonPath, join(shellBuildPlanRoot, "build-plan.json"));
-    }
-    const buildPlanSchemaPath = resolveBuildPlanSchemaPath(verifiableContextBuildPlanRoot);
-    if (buildPlanSchemaPath) {
-        linkPath(buildPlanSchemaPath, join(shellBuildPlanRoot, BUILD_PLAN_SCHEMA_FILE));
-    }
-    const readmePath = join(verifiableContextBuildPlanRoot, "README.md");
-    if (existsSync(readmePath)) {
-        linkPath(readmePath, join(shellBuildPlanRoot, "README.md"));
-    }
-    const stageDocsPath = stageBuildPlanDocsPath(verifiableContextPath, stage);
-    if (existsSync(stageDocsPath)) {
-        linkPath(stageDocsPath, join(shellBuildPlanRoot, "build", "stages", stage.skillDir));
-    }
-}
-function projectVerifiableContextSchemaArtifacts(verifiableContextPath, shellRoot, schema, artifactIds, materializedArtifactIds) {
-    const allowedArtifactIds = artifactIds ? new Set(artifactIds) : null;
-    for (const artifact of listContextInterfaceArtifacts(schema)) {
-        if (allowedArtifactIds && !allowedArtifactIds.has(artifact.id))
-            continue;
-        const sourcePath = verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact);
-        const targetPath = join(shellRoot, artifact.path);
-        if (materializedArtifactIds?.has(artifact.id)) {
-            ensureShellLocalProjection(sourcePath, targetPath, artifact);
-            continue;
-        }
-        linkPath(sourcePath, targetPath);
-    }
-}
-function buildStageArtifactMounts(verifiableContextPath, shellRoot, stage, schema) {
-    const artifacts = artifactMap(schema);
-    const mountFor = (artifactId) => {
-        const artifact = artifactOrThrow(artifacts, artifactId);
-        return {
-            artifact_id: artifact.id,
-            artifact_path: artifact.path,
-            shell_root_path: artifact.path,
-            input_mount_path: stage.reads.includes(artifactId)
-                ? describeShellArtifactAliasMountPath(artifact, "inputs")
-                : null,
-            output_mount_path: stage.writes.includes(artifactId)
-                ? describeShellArtifactAliasMountPath(artifact, "outputs")
-                : null,
-        };
-    };
-    return {
-        reads: stage.reads.map(mountFor),
-        writes: stage.writes.map(mountFor),
-    };
-}
-function projectStageArtifactMountAliases(shellRoot, stage, schema) {
-    const artifacts = artifactMap(schema);
-    for (const artifactId of new Set([...stage.reads, ...stage.writes])) {
-        const artifact = artifactOrThrow(artifacts, artifactId);
-        const targetPath = join(shellRoot, artifact.path);
-        if (stage.reads.includes(artifactId)) {
-            linkRelativePath(targetPath, shellArtifactAliasMountPath(shellRoot, artifact, "inputs"));
-        }
-        if (stage.writes.includes(artifactId)) {
-            linkRelativePath(targetPath, shellArtifactAliasMountPath(shellRoot, artifact, "outputs"));
-        }
-    }
-}
-function writeExecutionShellPathsFile(shellRoot, buildPlanId, stage, mounts) {
-    const paths = {
-        kind: "interf-execution-shell",
-        version: 1,
-        build_plan: buildPlanId,
-        stage: stage.id,
-        reads: mounts.reads,
-        writes: mounts.writes,
-    };
-    writeFileSync(shellRuntimePath(shellRoot, "paths.json"), `${JSON.stringify(paths, null, 2)}\n`);
-}
-export function syncStageExecutionShellWrites(verifiableContextPath, shellRoot, stage, writeArtifacts = []) {
-    const schema = ensureBuildExecutionSurface(verifiableContextPath);
-    const artifacts = artifactMap(schema);
-    const stageWriteArtifacts = Array.from(stageWriteArtifactSet(schema, stage))
-        .map((artifactId) => artifactOrThrow(artifacts, artifactId));
-    for (const artifact of stageWriteArtifacts) {
-        const canonicalShellArtifactPath = join(shellRoot, artifact.path);
-        const outputAliasPath = shellArtifactAliasMountPath(shellRoot, artifact, "outputs");
-        const shellArtifactPath = artifact.kind === "file" &&
-            existsSync(outputAliasPath) &&
-            !lstatSync(outputAliasPath).isSymbolicLink()
-            ? outputAliasPath
-            : canonicalShellArtifactPath;
-        if (!existsSync(shellArtifactPath))
-            continue;
-        const shellArtifactStat = lstatSync(shellArtifactPath);
-        if (shellArtifactStat.isSymbolicLink())
-            continue;
-        const verifiableContextArtifactPath = verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact);
-        if (shellArtifactStat.isDirectory()) {
-            const shellArtifactFiles = listFilesRecursive(shellArtifactPath);
-            const verifiableContextArtifactFiles = existsSync(verifiableContextArtifactPath)
-                ? listFilesRecursive(verifiableContextArtifactPath)
-                : [];
-            if (shellArtifactFiles.length === 0 && verifiableContextArtifactFiles.length > 0) {
-                continue;
-            }
-            rmSync(verifiableContextArtifactPath, { recursive: true, force: true });
-            mkdirSync(dirname(verifiableContextArtifactPath), { recursive: true });
-            cpSync(shellArtifactPath, verifiableContextArtifactPath, {
-                recursive: true,
-                force: true,
-            });
-            continue;
-        }
-        mkdirSync(dirname(verifiableContextArtifactPath), { recursive: true });
-        copyFileSync(shellArtifactPath, verifiableContextArtifactPath);
-    }
-    for (const artifactPath of writeArtifacts) {
-        const normalizedArtifactPath = normalizeArtifactRelativePath(artifactPath);
-        if (normalizedArtifactPath.length === 0 ||
-            stageWriteArtifacts.some((artifact) => relativePathEqualsOrWithin(artifact.path, normalizedArtifactPath))) {
-            continue;
-        }
-        const shellArtifactPath = join(shellRoot, normalizedArtifactPath);
-        if (!existsSync(shellArtifactPath))
-            continue;
-        const verifiableContextArtifactPath = join(verifiableContextPath, normalizedArtifactPath);
-        const shellArtifactStat = lstatSync(shellArtifactPath);
-        if (shellArtifactStat.isSymbolicLink())
-            continue;
-        if (shellArtifactStat.isDirectory()) {
-            rmSync(verifiableContextArtifactPath, { recursive: true, force: true });
-            mkdirSync(dirname(verifiableContextArtifactPath), { recursive: true });
-            cpSync(shellArtifactPath, verifiableContextArtifactPath, {
-                recursive: true,
-                force: true,
-            });
-            continue;
-        }
-        mkdirSync(dirname(verifiableContextArtifactPath), { recursive: true });
-        copyFileSync(shellArtifactPath, verifiableContextArtifactPath);
-    }
-}
-function preservedShellManifestPath(rootPath) {
-    return shellRuntimePath(rootPath, "preserved-shell.json");
-}
-function shouldSkipFrozenStageShellRelativePath(relativePath) {
-    const normalized = relativePath.replaceAll("\\", "/");
-    return normalized === "execution-shells" ||
-        normalized.endsWith("/execution-shells") ||
-        normalized.includes("/execution-shells/") ||
-        normalized === "improvement-loops" ||
-        normalized.endsWith("/improvement-loops") ||
-        normalized.includes("/improvement-loops/");
-}
-/**
- * System path prefixes a malicious symlink in a Build Plan package must
- * never reach. Without this, the freeze-snapshot logic could be
- * tricked into copying anything the running user has access to —
- * `/etc/passwd`, `~/.ssh/id_rsa`, etc. (CSO finding).
- *
- * We deliberately allow targets that escape the immediate freeze
- * root: legitimate execution shells contain symlinks pointing back
- * to the parent Preparation's `interf.json`. The threat is only links
- * that resolve into truly system-level paths.
- */
-const FORBIDDEN_SYMLINK_TARGET_PREFIXES = [
-    "/etc",
-    "/sys",
-    "/proc",
-    "/dev",
-    "/var/run",
-    "/var/lib",
-    "/usr",
-    "/bin",
-    "/sbin",
-    "/boot",
-    "/root",
-];
-function ensureSymlinkTargetSafe(realTarget, symlinkPath) {
-    for (const prefix of FORBIDDEN_SYMLINK_TARGET_PREFIXES) {
-        if (realTarget === prefix || realTarget.startsWith(`${prefix}${pathSep}`)) {
-            throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
-                `resolves into system directory ${prefix}.`);
-        }
-    }
-    // Also refuse links that escape into another user's SSH directory
-    // even if the path is not on the literal forbidden list.
-    if (/\/\.ssh(\/|$)/.test(realTarget)) {
-        throw new Error(`Refusing to follow symlink ${symlinkPath} → ${realTarget}: ` +
-            `targets a .ssh directory.`);
-    }
-}
-function copyResolvedTree(options) {
-    const relativePath = options.relativePath ?? "";
-    if (options.shellType === "stage-execution" && shouldSkipFrozenStageShellRelativePath(relativePath)) {
-        return { materializedSymlinks: 0 };
-    }
-    const stat = lstatSync(options.sourcePath);
-    if (stat.isSymbolicLink()) {
-        // existsSync follows symlinks, so a dangling link (target absent)
-        // returns false. Skip those entries: realpathSync would throw
-        // ENOENT, and the freeze step is best-effort review material —
-        // losing one unresolvable link is better than aborting the whole
-        // snapshot. Production trigger: createStageExecutionShell links
-        // runtime/stage-contract.json before writeStageContract runs, so
-        // any failure between those two points leaves a dangling link
-        // that the per-stage finally-block freeze would otherwise hit.
-        if (!existsSync(options.sourcePath)) {
-            return { materializedSymlinks: 0 };
-        }
-        const realTarget = realpathSync(options.sourcePath);
-        // Refuse symlinks resolving into system paths (CSO finding). We
-        // deliberately allow links that escape the immediate freeze root
-        // because legitimate execution shells contain links back to the
-        // parent Preparation's interf.json — the only thing we care about
-        // is that the realpath does not land in /etc, /sys, /proc, etc.
-        ensureSymlinkTargetSafe(realTarget, options.sourcePath);
-        const realStat = statSync(realTarget);
-        if (realStat.isDirectory()) {
-            const mappedTarget = options.materializedRealPaths?.get(realTarget);
-            if (mappedTarget) {
-                linkRelativePath(mappedTarget, options.targetPath);
-                return { materializedSymlinks: 1 };
-            }
-            return {
-                materializedSymlinks: 1 + copyResolvedTree({
-                    sourcePath: realTarget,
-                    targetPath: options.targetPath,
-                    shellType: options.shellType,
-                    relativePath,
-                    activeRealPaths: options.activeRealPaths,
-                    materializedRealPaths: options.materializedRealPaths,
-                }).materializedSymlinks,
-            };
-        }
-        mkdirSync(dirname(options.targetPath), { recursive: true });
-        copyFileSync(realTarget, options.targetPath);
-        return { materializedSymlinks: 1 };
-    }
-    if (stat.isDirectory()) {
-        const realSource = realpathSync(options.sourcePath);
-        const mappedTarget = options.materializedRealPaths?.get(realSource);
-        if (mappedTarget && mappedTarget !== options.targetPath) {
-            linkRelativePath(mappedTarget, options.targetPath);
-            return { materializedSymlinks: 0 };
-        }
-        const nextRealPaths = new Set([...(options.activeRealPaths ?? []), realSource]);
-        const nextMaterializedRealPaths = new Map(options.materializedRealPaths ?? []);
-        nextMaterializedRealPaths.set(realSource, options.targetPath);
-        mkdirSync(options.targetPath, { recursive: true });
-        let materializedSymlinks = 0;
-        for (const entry of readdirSync(options.sourcePath)) {
-            const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry}` : entry;
-            const copied = copyResolvedTree({
-                sourcePath: join(options.sourcePath, entry),
-                targetPath: join(options.targetPath, entry),
-                shellType: options.shellType,
-                relativePath: childRelativePath,
-                activeRealPaths: nextRealPaths,
-                materializedRealPaths: nextMaterializedRealPaths,
-            });
-            materializedSymlinks += copied.materializedSymlinks;
-        }
-        return { materializedSymlinks };
-    }
-    mkdirSync(dirname(options.targetPath), { recursive: true });
-    copyFileSync(options.sourcePath, options.targetPath);
-    return { materializedSymlinks: 0 };
-}
-function freezePreservedShell(rootPath, shellType) {
-    if (!existsSync(rootPath))
-        return null;
-    const manifestPath = preservedShellManifestPath(rootPath);
-    if (existsSync(manifestPath))
-        return manifestPath;
-    const tempRoot = `${rootPath}.frozen-${Date.now().toString(36)}`;
-    const copied = copyResolvedTree({
-        sourcePath: rootPath,
-        targetPath: tempRoot,
-        shellType,
-    });
-    const manifest = {
-        kind: "interf-preserved-shell",
-        version: 1,
-        shell_type: shellType,
-        generated_at: new Date().toISOString(),
-        root_path: rootPath,
-        materialized_symlinks: copied.materializedSymlinks,
-    };
-    writeFileSync(preservedShellManifestPath(tempRoot), `${JSON.stringify(manifest, null, 2)}\n`);
-    rmSync(rootPath, { recursive: true, force: true });
-    renameSync(tempRoot, rootPath);
-    return manifestPath;
-}
-export function renderClaudeBootstrap(content) {
-    return [
-        "<!-- Generated mirror of AGENTS.md. Interf may rewrite this file. -->",
-        "",
-        content.trimEnd(),
-        "",
-    ].join("\n");
-}
-function renderBuildPlanAuthoringAgents(options) {
-    return [
-        `# ${options.label} — Build Plan Authoring Shell`,
-        "",
-        "This is an automated Build Plan authoring shell generated by Interf.",
-        "It exists to create one standalone Build Plan package from the source data, desired verifiable-context outputs, and proof requirements in this task.",
-        "",
-        "## Start Here",
-        "",
-        "1. Read `runtime/authoring-context.json` now.",
-        `2. Read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` now.`,
-        "3. Read `runtime/source-files.json` and review the listed source locators.",
-        "4. Use the local native `interf-build-plan-author` skill now.",
-        "",
-        "## Boundaries",
-        "",
-        `- New Build Plan id: \`${options.buildPlanId}\`.`,
-        "- Authoring mode: from scratch.",
-        ...(options.referenceBuildPlanId
-            ? [`- Reference Build Plan id: \`${options.referenceBuildPlanId}\` (context only, not a seed).`]
-            : []),
-        "- Edit only files under `build-plan/`.",
-        "- Do not edit source artifacts.",
-        "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "- Use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids. Never use underscores.",
-        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
-        "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
-        "- Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
-        "",
-        "## Goal",
-        "",
-        "- produce one standalone Build Plan package tuned to the source data, desired outputs, and checks in this task",
-        "- replace the neutral scaffold topology with the stage graph this agent work needs",
-        "- define Artifacts and checks so Interf can show whether the data is ready",
-        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
-        "- otherwise draft the Build Plan Artifacts from every `requested_artifacts[]` entry; do not ignore or truncate them",
-        "- preserve deterministic stage and context-interface contracts",
-        "- stop once the Build Plan edits are complete",
-        "",
-    ].join("\n");
-}
-function renderBuildPlanAuthoringSkill() {
-    return [
-        "---",
-        "name: interf-build-plan-author",
-        "description: >",
-        "  Native local Build Plan authoring skill for an automated Interf Build Plan draft run.",
-        "---",
-        "",
-        "# Interf Build Plan Authoring",
-        "",
-        "Read `runtime/authoring-context.json` first.",
-        "Then review the neutral Build Plan package scaffold under `build-plan/`, read `runtime/source-files.json`, and inspect the listed source locators when needed.",
-        "",
-        "Rules:",
-        "- edit only `build-plan/`",
-        `- keep \`build-plan.json\`, \`${BUILD_PLAN_SCHEMA_FILE}\`, and any changed stage docs aligned`,
-        "- put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks",
-        "- use only CheckKind values listed in `runtime/authoring-context.json`; do not invent aliases",
-        "- keep Artifact checks aligned with produced outputs; use stage docs to describe the output contract without requiring exact source-specific phrases in the stage docs",
-        "- satisfy every `artifact_requirements[]` entry from `runtime/authoring-context.json` when entries are present",
-        "- otherwise draft the Build Plan Artifacts from every `requested_artifacts[]` entry; do not ignore or truncate them",
-        "- design the stage graph from the source data and preparation-and-evidence brief",
-        "- use kebab-case ids everywhere: stage ids, skill_dir values, Artifact ids, reads/writes values, and package ids; never use underscores",
-        "- replace the placeholder `prepare` stage unless that exact stage is truly the final Build Plan",
-        "- keep the package standalone; do not introduce runtime inheritance or hidden source-package assumptions",
-        "- do not introduce wikilinks unless the Build Plan also creates the target note by exact basename or explicit relative path",
-        "- respect stage boundaries: do not make structure outputs link to notes or entrypoints first created by later stages",
-        "- prefer conservative routing changes over speculative note sprawl",
-        "- prefer direct file-reading and search tools over shell commands for routine file inspection",
-        "- do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files",
-        "- do not hardcode readiness-check answers into reusable Build Plan docs",
-        "- do not edit source artifacts",
-        "",
-    ].join("\n");
-}
-function improvementBuildPlanDocsPath(verifiableContextPath) {
-    return join(buildPlanPackagePathForVerifiableContext(verifiableContextPath), "improve");
-}
-export function createBuildPlanAuthoringShell(options) {
-    const shellRoot = mkdtempSync(join(tmpdir(), `interf-build-plan-author-${options.buildPlanId}-`));
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
-    mkdirSync(join(shellRoot, "logs"), { recursive: true });
-    const context = {
-        kind: "interf-build-plan-authoring",
-        version: 1,
-        generated_at: new Date().toISOString(),
-        authoring_mode: "from-scratch",
-        build_plan_id: options.buildPlanId,
-        build_plan_label: options.label,
-        ...(options.referenceBuildPlanId ? { reference_build_plan_id: options.referenceBuildPlanId } : {}),
-        task_prompt: options.taskPrompt,
-        allowed_check_kinds: CHECK_KINDS,
-        requested_artifacts: options.requestedArtifacts ?? [],
-        artifact_requirements: options.artifactRequirements ?? [],
-        preparation: {
-            source_folder_path: options.sourceFolderPath,
-            source_profile: options.sourceProfile ?? null,
-            checks: {
-                count: options.checks.length,
-                questions: options.checks.map((check, index) => ({
-                    id: check.id ?? `check-${index + 1}`,
-                    question: check.question,
-                })),
-            },
-        },
-    };
-    writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
-    writeFileSync(join(shellRoot, "runtime", "source-files.json"), `${JSON.stringify(buildVerifiableContextSourceFiles(shellRoot, options.sourceFolderPath), null, 2)}\n`);
-    copyResolvedTree({
-        sourcePath: options.buildPlanPath,
-        targetPath: join(shellRoot, "build-plan"),
-        shellType: "build-plan-authoring",
-    });
-    writeNativeAgentSurface(shellRoot, renderBuildPlanAuthoringAgents({
-        buildPlanId: options.buildPlanId,
-        label: options.label,
-        referenceBuildPlanId: options.referenceBuildPlanId ?? null,
-    }), "interf-build-plan-author", renderBuildPlanAuthoringSkill());
-    return {
-        rootPath: shellRoot,
-        buildPlanBeforePath: join(shellRoot, "artifacts", "build-plan-before"),
-        buildPlanAfterPath: join(shellRoot, "artifacts", "build-plan-after"),
-        promptLogPath: join(shellRoot, "logs", "build-plan-author.prompt.txt"),
-        eventLogPath: join(shellRoot, "logs", "build-plan-author.events.ndjson"),
-        statusLogPath: join(shellRoot, "logs", "build-plan-author.status.log"),
-    };
-}
-function renderBuildPlanImprovementAgents(verifiableContextName, buildPlanId, loopIndex) {
-    return [
-        `# ${verifiableContextName} — Build Plan Improvement Shell`,
-        "",
-        "This is an automated Build Plan improvement shell generated by Interf.",
-        "It exists to review failed Build/check runs and edit the Build Plan package for the next variation.",
-        "",
-        "## Start Here",
-        "",
-        "1. Read `runtime/loop-context.json` now.",
-        `2. Read \`build-plan/README.md\`, \`build-plan/build-plan.json\`, and \`build-plan/${BUILD_PLAN_SCHEMA_FILE}\` now.`,
-        "3. Read `build-plan/improve/SKILL.md` now.",
-        "4. Use the local native `interf-build-plan-improver` skill now.",
-        "",
-        "## Boundaries",
-        "",
-        `- Build Plan: \`${buildPlanId}\`.`,
-        `- Improvement loop: ${loopIndex}.`,
-        "- Edit only files under `build-plan/`.",
-        "- Do not edit checks, test specs, source files, or generated context outputs.",
-        "- Review verifiable-context outputs under `artifacts/verifiable-context-view/` and test/runtime evidence under `artifacts/`.",
-        "- Keep the Build Plan package valid for the current build API and `build-plan.schema.json`.",
-        "- Put deterministic validation on Artifact `checks[]`; do not add stage `acceptance` blocks.",
-        "",
-        "## Goal",
-        "",
-        "- create a better Build Plan variation for this kind of agent work",
-        "- preserve deterministic verifiable-context structure",
-        "- stop after the Build Plan edits are complete",
-        "",
-    ].join("\n");
-}
-function readBuildPlanImprovementDoc(verifiableContextPath) {
-    const path = join(improvementBuildPlanDocsPath(verifiableContextPath), "SKILL.md");
-    if (!existsSync(path))
-        return null;
-    return readFileSync(path, "utf8").trim();
-}
-function renderBuildPlanImprovementSkill(buildPlanId, loopIndex, improvementDoc) {
-    return [
-        "---",
-        "name: interf-build-plan-improver",
-        "description: >",
-        "  Native local Build Plan improvement skill for this Interf run.",
-        "  Use it only inside an automated Build Plan improvement shell.",
-        "---",
-        "",
-        `# Interf Build Plan Improvement — ${buildPlanId}`,
-        "",
-        "This local native skill exists for automated Build Plan improvement loops.",
-        "Read `runtime/loop-context.json` first.",
-        "Then review the linked Build Plan package, `artifacts/verifiable-context-view/`, preserved stage shells, runtime logs, and saved test outputs before editing `build-plan/`.",
-        "",
-        "## Current Loop",
-        "",
-        `- Build Plan: \`${buildPlanId}\``,
-        `- loop index: ${loopIndex}`,
-        "- editable source: `build-plan/improve/SKILL.md`",
-        "",
-        ...(improvementDoc
-            ? [
-                "## Improvement Guidance",
-                "",
-                improvementDoc,
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-function projectVerifiableContextReviewArtifactsSnapshot(verifiableContextPath, shellRoot, schema) {
-    const verifiableContextViewRoot = join(shellRoot, "artifacts", "verifiable-context-view");
-    mkdirSync(verifiableContextViewRoot, { recursive: true });
-    for (const artifact of listContextInterfaceArtifacts(schema)) {
-        if (artifact.kind === "runtime" || artifact.path === "source-files")
-            continue;
-        const sourcePath = verifiableContextArtifactAbsolutePath(verifiableContextPath, artifact);
-        if (!existsSync(sourcePath))
-            continue;
-        copyResolvedTree({
-            sourcePath,
-            targetPath: join(verifiableContextViewRoot, artifact.path),
-            shellType: "build-plan-improvement",
-        });
-    }
-}
-function copyIfExists(sourcePath, targetPath, shellType) {
-    if (!existsSync(sourcePath))
-        return;
-    copyResolvedTree({
-        sourcePath,
-        targetPath,
-        shellType,
-    });
-}
-function projectVerifiableContextRuntimeArtifacts(verifiableContextPath, shellRoot) {
-    const runtimeTarget = join(shellRoot, "artifacts", "verifiable-context-runtime");
-    mkdirSync(runtimeTarget, { recursive: true });
-    const runtimeRoot = verifiableContextRuntimeRoot(verifiableContextPath);
-    const artifactNames = [
-        "run.json",
-        "run-history.jsonl",
-        "state.json",
-        "health.json",
-        "view-spec.json",
-        "source-files.json",
-        "source-snapshot.json",
-        "stages",
-        "logs",
-    ];
-    for (const artifactName of artifactNames) {
-        copyIfExists(join(runtimeRoot, artifactName), join(runtimeTarget, artifactName), "build-plan-improvement");
-    }
-}
-export function pruneStageExecutionShells(verifiableContextPath) {
-    rmSync(stageExecutionShellsRoot(verifiableContextPath), { recursive: true, force: true });
-}
-export function projectVerifiableContextQueryShell(verifiableContextPath, verifiableContextName, buildPlanId, about, options) {
-    const agentsContent = renderVerifiableContextAgents(verifiableContextPath, verifiableContextName, buildPlanId, about, options);
-    const querySkillContent = readVerifiableContextQuerySkillSource(verifiableContextPath);
-    return writeNativeAgentSurface(verifiableContextPath, agentsContent, "interf-query", renderVerifiableContextQueryNativeSkill(querySkillContent));
-}
-export function projectSourceFilesTestQueryShell(rootPath) {
-    return writeNativeAgentSurface(rootPath, renderSourceFilesTestAgents(), "interf-query", renderSourceFilesTestQuerySkill());
-}
-export function createStageExecutionShell(verifiableContextPath, verifiableContextName, buildPlanId, stage, writeArtifacts = []) {
-    const schema = ensureBuildExecutionSurface(verifiableContextPath);
-    const materializedArtifacts = stageMaterializedArtifactSet(schema, stage, writeArtifacts);
-    const shellsRoot = stageExecutionShellsRoot(verifiableContextPath);
-    const shellRoot = join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
-    mkdirSync(shellRoot, { recursive: true });
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, ".interf", "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "inputs"), { recursive: true });
-    mkdirSync(join(shellRoot, "outputs"), { recursive: true });
-    linkPath(verifiableContextInterfConfigPath(verifiableContextPath), join(shellRoot, "interf.json"));
-    linkPath(join(verifiableContextRuntimeRoot(verifiableContextPath), "stage-contract.json"), shellRuntimePath(shellRoot, "stage-contract.json"));
-    linkIfExists(verifiableContextRuntimeSourceSnapshotPath(verifiableContextPath), shellRuntimePath(shellRoot, "source-snapshot.json"));
-    linkIfExists(verifiableContextRuntimeStageInputsPath(verifiableContextPath, stage.id), shellRuntimePath(shellRoot, "stage-inputs.json"));
-    projectVerifiableContextSchemaArtifacts(verifiableContextPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedArtifacts);
-    projectBuildPlanMetadata(verifiableContextPath, shellRoot, stage);
-    projectStageArtifactMountAliases(shellRoot, stage, schema);
-    writeExecutionShellPathsFile(shellRoot, buildPlanId, stage, buildStageArtifactMounts(verifiableContextPath, shellRoot, stage, schema));
-    const agentsContent = renderStageExecutionAgents(verifiableContextName, buildPlanId, stage);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageBuildPlanDoc(verifiableContextPath, stage)));
-    return {
-        rootPath: shellRoot,
-    };
-}
-export function freezeStageExecutionShell(rootPath) {
-    return freezePreservedShell(rootPath, "stage-execution");
-}
-export function createBuildPlanImprovementShell(options) {
-    const schema = ensureBuildExecutionSurface(options.verifiableContextPath);
-    const loopRootPath = buildPlanImprovementLoopRoot(options.verifiableContextPath, options.runId, options.loopIndex);
-    const shellRoot = join(loopRootPath, "shell");
-    mkdirSync(shellRoot, { recursive: true });
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
-    mkdirSync(join(loopRootPath, "logs"), { recursive: true });
-    writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
-    projectVerifiableContextReviewArtifactsSnapshot(options.verifiableContextPath, shellRoot, schema);
-    copyResolvedTree({
-        sourcePath: buildPlanPackagePathForVerifiableContext(options.verifiableContextPath),
-        targetPath: join(shellRoot, "build-plan"),
-        shellType: "build-plan-improvement",
-    });
-    copyIfExists(verifiableContextInterfConfigPath(options.verifiableContextPath), join(shellRoot, "interf.json"), "build-plan-improvement");
-    projectVerifiableContextRuntimeArtifacts(options.verifiableContextPath, shellRoot);
-    const reviewSources = resolveBuildPlanImprovementReviewSourcePaths(options.verifiableContextPath);
-    if (reviewSources.executionShells) {
-        copyIfExists(reviewSources.executionShells, join(shellRoot, "artifacts", "execution-shells"), "build-plan-improvement");
-    }
-    if (reviewSources.readinessRuns) {
-        copyIfExists(reviewSources.readinessRuns, join(shellRoot, "artifacts", "readiness-runs"), "build-plan-improvement");
-    }
-    if (reviewSources.targetTestRuns) {
-        copyIfExists(reviewSources.targetTestRuns, join(shellRoot, "artifacts", "test-runs"), "build-plan-improvement");
-    }
-    if (reviewSources.targetTestSandboxes) {
-        copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "build-plan-improvement");
-    }
-    const agentsContent = renderBuildPlanImprovementAgents(options.verifiableContextName, options.buildPlanId, options.loopIndex);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-build-plan-improver", renderBuildPlanImprovementSkill(options.buildPlanId, options.loopIndex, readBuildPlanImprovementDoc(options.verifiableContextPath)));
-    return {
-        rootPath: shellRoot,
-        loopRootPath,
-        buildPlanBeforePath: join(loopRootPath, "build-plan-before"),
-        buildPlanAfterPath: join(loopRootPath, "build-plan-after"),
-        promptLogPath: join(loopRootPath, "logs", "build-plan-improver.prompt.txt"),
-        eventLogPath: join(loopRootPath, "logs", "build-plan-improver.events.ndjson"),
-        statusLogPath: join(loopRootPath, "logs", "build-plan-improver.status.log"),
-    };
-}
-export function freezeBuildPlanImprovementShell(rootPath) {
-    return freezePreservedShell(rootPath, "build-plan-improvement");
-}