@interf/compiler 0.22.2 → 0.33.0

package/dist/packages/{engine → runtime}/agents/lib/render.js

@@ -168,14 +168,14 @@ function summarizeToolUse(name, input) {
     const target = summarizeToolTarget(input);
     switch (name) {
         case "Read":
-            return target ? `reading ${target}` : "reading verifiable context files";
+            return target ? `reading ${target}` : "reading context graph files";
         case "Write":
-            return target ? `writing ${target}` : "writing verifiable context files";
+            return target ? `writing ${target}` : "writing context graph files";
         case "Edit":
-            return target ? `editing ${target}` : "editing verifiable context files";
+            return target ? `editing ${target}` : "editing context graph files";
         case "Glob":
         case "Grep":
-            return target ? `${name.toLowerCase()} on ${target}` : `${name.toLowerCase()}ing verifiable context files`;
+            return target ? `${name.toLowerCase()} on ${target}` : `${name.toLowerCase()}ing context graph files`;
         case "Bash":
             return target ? `running ${target}` : "running a local helper";
         default:

package/dist/packages/runtime/agents/lib/shell-fs.d.ts

@@ -0,0 +1,18 @@
+import type { PreservedShellType } from "../../build/lib/schema.js";
+export declare function writeIfChanged(path: string, content: string): boolean;
+export declare function writeNativeSkillCopies(rootPath: string, skillName: string, content: string): boolean;
+export declare function linkPath(targetPath: string, linkPathname: string): void;
+export declare function linkIfExists(targetPath: string, linkPathname: string): void;
+export declare function linkRelativePath(targetPath: string, linkPathname: string): void;
+export declare function copyResolvedTree(options: {
+    sourcePath: string;
+    targetPath: string;
+    shellType: PreservedShellType;
+    relativePath?: string;
+    activeRealPaths?: Set<string>;
+    materializedRealPaths?: Map<string, string>;
+}): {
+    materializedSymlinks: number;
+};
+export declare function copyIfExists(sourcePath: string, targetPath: string, shellType: PreservedShellType): void;
+export declare function freezePreservedShell(rootPath: string, shellType: PreservedShellType): string | null;

package/dist/packages/runtime/agents/lib/shell-fs.js

@@ -0,0 +1,190 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, lstatSync, } from "node:fs";
+import { dirname, join, relative, sep as pathSep } from "node:path";
+import { LOCAL_SKILL_ROOTS, preservedShellManifestPath, } from "./shell-paths.js";
+export function writeIfChanged(path, content) {
+    if (existsSync(path) && readFileSync(path, "utf8") === content) {
+        return false;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return true;
+}
+export 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;
+}
+export function linkPath(targetPath, linkPathname) {
+    mkdirSync(dirname(linkPathname), { recursive: true });
+    symlinkSync(targetPath, linkPathname);
+}
+export function linkIfExists(targetPath, linkPathname) {
+    if (!existsSync(targetPath))
+        return;
+    linkPath(targetPath, linkPathname);
+}
+export function linkRelativePath(targetPath, linkPathname) {
+    mkdirSync(dirname(linkPathname), { recursive: true });
+    symlinkSync(relative(dirname(linkPathname), targetPath), linkPathname);
+}
+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 preserved-shell 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 Project'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.`);
+    }
+}
+export 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
+        // preserved shell. 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 Project'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 };
+}
+export function copyIfExists(sourcePath, targetPath, shellType) {
+    if (!existsSync(sourcePath))
+        return;
+    copyResolvedTree({
+        sourcePath,
+        targetPath,
+        shellType,
+    });
+}
+export 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;
+}

package/dist/packages/runtime/agents/lib/shell-paths.d.ts

@@ -0,0 +1,16 @@
+import type { ContextInterfaceArtifact as BuildPlanArtifact } from "../../../build-plans/package/context-interface.js";
+export declare const LOCAL_SKILL_ROOTS: readonly [".claude/skills", ".codex/skills", ".agents/skills", ".cursor/skills"];
+export declare function contextGraphQuerySkillSourcePath(contextGraphPath: string): string;
+export declare function stageShellBuildPlanRoot(shellRoot: string): string;
+export declare function shellArtifactAliasMountPath(shellRoot: string, artifact: BuildPlanArtifact, mountKind: "inputs" | "outputs"): string;
+export declare function describeShellArtifactAliasMountPath(artifact: BuildPlanArtifact, mountKind: "inputs" | "outputs"): string;
+export declare function shellRuntimePath(shellRoot: string, relativePath: string): string;
+export declare function shellLogsPath(shellRoot: string, relativePath?: string): string;
+export declare function shellPromptLogPath(shellRoot: string, runId: string): string;
+export declare function shellEventLogPath(shellRoot: string, runId: string): string;
+export declare function shellStatusLogPath(shellRoot: string, runId: string): string;
+export declare function shellWorkspaceManifestPath(shellRoot: string): string;
+export declare function preservedShellManifestPath(rootPath: string): string;
+export declare function improvementBuildPlanDocsPath(contextGraphPath: string): string;
+export declare function normalizeArtifactRelativePath(path: string): string;
+export declare function relativePathEqualsOrWithin(basePath: string, candidatePath: string): boolean;

package/dist/packages/runtime/agents/lib/shell-paths.js

@@ -0,0 +1,63 @@
+import { basename, join } from "node:path";
+import { BUILD_PLAN_PACKAGE_DIR } from "../../../projects/interf-detect.js";
+import { buildPlanPackagePathForContextGraph } from "../../build/context-graph-paths.js";
+export const LOCAL_SKILL_ROOTS = [
+    ".claude/skills",
+    ".codex/skills",
+    ".agents/skills",
+    ".cursor/skills",
+];
+export function contextGraphQuerySkillSourcePath(contextGraphPath) {
+    return join(buildPlanPackagePathForContextGraph(contextGraphPath), "use", "query", "SKILL.md");
+}
+export function stageShellBuildPlanRoot(shellRoot) {
+    return join(shellRoot, BUILD_PLAN_PACKAGE_DIR);
+}
+export function shellArtifactAliasMountPath(shellRoot, artifact, mountKind) {
+    const mountRoot = join(shellRoot, mountKind, artifact.id);
+    return artifact.kind === "file"
+        ? join(mountRoot, basename(artifact.path))
+        : mountRoot;
+}
+export function describeShellArtifactAliasMountPath(artifact, mountKind) {
+    return artifact.kind === "file"
+        ? `${mountKind}/${artifact.id}/${basename(artifact.path)}`
+        : `${mountKind}/${artifact.id}`;
+}
+export function shellRuntimePath(shellRoot, relativePath) {
+    return join(shellRoot, "runtime", relativePath);
+}
+export function shellLogsPath(shellRoot, relativePath = "") {
+    return relativePath ? join(shellRoot, "logs", relativePath) : join(shellRoot, "logs");
+}
+export function shellPromptLogPath(shellRoot, runId) {
+    return shellLogsPath(shellRoot, `${runId}.prompt.txt`);
+}
+export function shellEventLogPath(shellRoot, runId) {
+    return shellLogsPath(shellRoot, `${runId}.events.ndjson`);
+}
+export function shellStatusLogPath(shellRoot, runId) {
+    return shellLogsPath(shellRoot, `${runId}.status.log`);
+}
+export function shellWorkspaceManifestPath(shellRoot) {
+    return shellRuntimePath(shellRoot, "workspace.json");
+}
+export function preservedShellManifestPath(rootPath) {
+    return shellRuntimePath(rootPath, "preserved-shell.json");
+}
+export function improvementBuildPlanDocsPath(contextGraphPath) {
+    return join(buildPlanPackagePathForContextGraph(contextGraphPath), "improve");
+}
+export function normalizeArtifactRelativePath(path) {
+    return path
+        .replaceAll("\\", "/")
+        .replace(/^\.?\//, "")
+        .replace(/\/+$/g, "");
+}
+export 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}/`);
+}

package/dist/packages/runtime/agents/lib/shell-projection.d.ts

@@ -0,0 +1,25 @@
+import { type ContextInterface as BuildPlanContextSchema, type ContextInterfaceArtifact as BuildPlanArtifact, type ContextInterfaceArtifactId as BuildPlanArtifactId } from "../../../build-plans/package/context-interface.js";
+import type { ExecutionShellArtifactMount } from "../../build/lib/schema.js";
+import type { NativeStageDefinition } from "./shell-templates.js";
+export declare function loadContextGraphSchema(contextGraphPath: string): BuildPlanContextSchema;
+export declare function artifactMap(schema: BuildPlanContextSchema): Map<BuildPlanArtifactId, BuildPlanArtifact>;
+export declare function artifactOrThrow(artifacts: Map<BuildPlanArtifactId, BuildPlanArtifact>, artifactId: BuildPlanArtifactId): BuildPlanArtifact;
+export declare function stageWriteArtifactSet(schema: BuildPlanContextSchema, stage: NativeStageDefinition): Set<BuildPlanArtifactId>;
+export declare function stageMaterializedArtifactSet(schema: BuildPlanContextSchema, stage: NativeStageDefinition, writeArtifacts?: readonly string[]): Set<BuildPlanArtifactId>;
+export declare function ensureBuildExecutionSurface(contextGraphPath: string): BuildPlanContextSchema;
+export declare function readStageBuildPlanDoc(contextGraphPath: string, stage: NativeStageDefinition): string | null;
+export declare function stageBuildPlanDocsPath(contextGraphPath: string, stage: NativeStageDefinition): string;
+export declare function projectBuildPlanMetadata(contextGraphPath: string, shellRoot: string, stage: NativeStageDefinition): void;
+export declare function projectContextGraphSchemaArtifacts(contextGraphPath: string, shellRoot: string, schema: BuildPlanContextSchema, artifactIds?: Iterable<BuildPlanArtifactId>, materializedArtifactIds?: ReadonlySet<BuildPlanArtifactId>, cleanMaterializedArtifactIds?: ReadonlySet<BuildPlanArtifactId>): void;
+export declare function buildStageArtifactMounts(_contextGraphPath: string, _shellRoot: string, stage: NativeStageDefinition, schema: BuildPlanContextSchema): {
+    reads: ExecutionShellArtifactMount[];
+    writes: ExecutionShellArtifactMount[];
+};
+export declare function projectStageArtifactMountAliases(shellRoot: string, stage: NativeStageDefinition, schema: BuildPlanContextSchema): void;
+export declare function writeExecutionShellPathsFile(shellRoot: string, buildPlanId: string, stage: NativeStageDefinition, mounts: {
+    reads: ExecutionShellArtifactMount[];
+    writes: ExecutionShellArtifactMount[];
+}): void;
+export declare function syncStageExecutionShellWrites(contextGraphPath: string, shellRoot: string, stage: NativeStageDefinition, writeArtifacts?: readonly string[]): void;
+export declare function projectContextGraphReviewArtifactsState(contextGraphPath: string, shellRoot: string, schema: BuildPlanContextSchema): void;
+export declare function projectContextGraphRuntimeArtifacts(contextGraphPath: string, shellRoot: string): void;

package/dist/packages/runtime/agents/lib/shell-projection.js

@@ -0,0 +1,314 @@
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { buildPlanPackagePathForContextGraph, contextGraphRuntimeRoot, } from "../../build/context-graph-paths.js";
+import { ensureBuildPlanArtifactTargets } from "../../build/context-graph-schema.js";
+import { listFilesRecursive } from "../../../contracts/utils/filesystem.js";
+import { CONTEXT_INTERFACE_FILE as BUILD_PLAN_SCHEMA_FILE, contextInterfaceArtifactAbsolutePath as contextGraphArtifactAbsolutePath, listContextInterfaceArtifacts, readContextInterface as readBuildPlanContextFile, resolveContextInterfacePath as resolveBuildPlanSchemaPath, } from "../../../build-plans/package/context-interface.js";
+import { copyResolvedTree, linkPath, linkRelativePath, } from "./shell-fs.js";
+import { describeShellArtifactAliasMountPath, normalizeArtifactRelativePath, relativePathEqualsOrWithin, shellArtifactAliasMountPath, shellRuntimePath, stageShellBuildPlanRoot, } from "./shell-paths.js";
+export function loadContextGraphSchema(contextGraphPath) {
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(contextGraphPath);
+    const schema = readBuildPlanContextFile(buildPlanRoot);
+    if (!schema) {
+        throw new Error(`Missing Build Plan schema at ${join(buildPlanRoot, BUILD_PLAN_SCHEMA_FILE)}`);
+    }
+    return schema;
+}
+export function artifactMap(schema) {
+    return new Map(listContextInterfaceArtifacts(schema).map((artifact) => [artifact.id, artifact]));
+}
+export 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;
+}
+export function stageWriteArtifactSet(schema, stage) {
+    const artifacts = listContextInterfaceArtifacts(schema);
+    return new Set(stage.writes.filter((artifactId) => artifacts.some((artifact) => artifact.id === artifactId)));
+}
+export function stageMaterializedArtifactSet(schema, stage, writeArtifacts = []) {
+    const materialized = stageWriteArtifactSet(schema, stage);
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (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 });
+}
+export function ensureBuildExecutionSurface(contextGraphPath) {
+    mkdirSync(contextGraphRuntimeRoot(contextGraphPath), { recursive: true });
+    mkdirSync(buildPlanPackagePathForContextGraph(contextGraphPath), { recursive: true });
+    const schema = loadContextGraphSchema(contextGraphPath);
+    ensureBuildPlanArtifactTargets(contextGraphPath, schema);
+    return schema;
+}
+export function readStageBuildPlanDoc(contextGraphPath, stage) {
+    const buildPlanRoot = buildPlanPackagePathForContextGraph(contextGraphPath);
+    const path = join(buildPlanRoot, "build", "stages", stage.skillDir, "SKILL.md");
+    if (!isRegularBuildPlanFile(buildPlanRoot, path))
+        return null;
+    return readFileSync(path, "utf8").trim();
+}
+export function stageBuildPlanDocsPath(contextGraphPath, stage) {
+    return join(buildPlanPackagePathForContextGraph(contextGraphPath), "build", "stages", stage.skillDir);
+}
+function isInsideRealRoot(realRoot, path) {
+    try {
+        const realPath = realpathSync(path);
+        return realPath === realRoot || realPath.startsWith(`${realRoot}${sep}`);
+    }
+    catch {
+        return false;
+    }
+}
+function isRegularBuildPlanFile(buildPlanRoot, path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        return lstatSync(path).isFile() && isInsideRealRoot(realpathSync(buildPlanRoot), path);
+    }
+    catch {
+        return false;
+    }
+}
+function copyBuildPlanPath(buildPlanRoot, sourcePath, targetPath) {
+    if (!existsSync(sourcePath))
+        return;
+    const realRoot = realpathSync(buildPlanRoot);
+    if (!isInsideRealRoot(realRoot, sourcePath))
+        return;
+    const stat = lstatSync(sourcePath);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        mkdirSync(targetPath, { recursive: true });
+        for (const entry of readdirSync(sourcePath)) {
+            copyBuildPlanPath(buildPlanRoot, join(sourcePath, entry), join(targetPath, entry));
+        }
+        return;
+    }
+    if (!stat.isFile())
+        return;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    copyFileSync(sourcePath, targetPath);
+}
+export function projectBuildPlanMetadata(contextGraphPath, shellRoot, stage) {
+    const shellBuildPlanRoot = stageShellBuildPlanRoot(shellRoot);
+    mkdirSync(join(shellBuildPlanRoot, "build", "stages"), { recursive: true });
+    const contextGraphBuildPlanRoot = buildPlanPackagePathForContextGraph(contextGraphPath);
+    const buildPlanJsonPath = join(contextGraphBuildPlanRoot, "build-plan.json");
+    copyBuildPlanPath(contextGraphBuildPlanRoot, buildPlanJsonPath, join(shellBuildPlanRoot, "build-plan.json"));
+    const buildPlanSchemaPath = resolveBuildPlanSchemaPath(contextGraphBuildPlanRoot);
+    if (buildPlanSchemaPath) {
+        copyBuildPlanPath(contextGraphBuildPlanRoot, buildPlanSchemaPath, join(shellBuildPlanRoot, BUILD_PLAN_SCHEMA_FILE));
+    }
+    const readmePath = join(contextGraphBuildPlanRoot, "README.md");
+    copyBuildPlanPath(contextGraphBuildPlanRoot, readmePath, join(shellBuildPlanRoot, "README.md"));
+    const stageDocsPath = stageBuildPlanDocsPath(contextGraphPath, stage);
+    copyBuildPlanPath(contextGraphBuildPlanRoot, stageDocsPath, join(shellBuildPlanRoot, "build", "stages", stage.skillDir));
+}
+export function projectContextGraphSchemaArtifacts(contextGraphPath, shellRoot, schema, artifactIds, materializedArtifactIds, cleanMaterializedArtifactIds) {
+    const allowedArtifactIds = artifactIds ? new Set(artifactIds) : null;
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (allowedArtifactIds && !allowedArtifactIds.has(artifact.id))
+            continue;
+        const sourcePath = contextGraphArtifactAbsolutePath(contextGraphPath, artifact);
+        const targetPath = join(shellRoot, artifact.path);
+        if (cleanMaterializedArtifactIds?.has(artifact.id)) {
+            rmSync(targetPath, { recursive: true, force: true });
+            if (artifact.kind === "file") {
+                mkdirSync(dirname(targetPath), { recursive: true });
+            }
+            else {
+                mkdirSync(targetPath, { recursive: true });
+            }
+            continue;
+        }
+        if (materializedArtifactIds?.has(artifact.id)) {
+            ensureShellLocalProjection(sourcePath, targetPath, artifact);
+            continue;
+        }
+        linkPath(sourcePath, targetPath);
+    }
+}
+export function buildStageArtifactMounts(_contextGraphPath, _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),
+    };
+}
+export 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"));
+        }
+    }
+}
+export 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(contextGraphPath, shellRoot, stage, writeArtifacts = []) {
+    const schema = ensureBuildExecutionSurface(contextGraphPath);
+    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 contextGraphArtifactPath = contextGraphArtifactAbsolutePath(contextGraphPath, artifact);
+        if (shellArtifactStat.isDirectory()) {
+            const shellArtifactFiles = listFilesRecursive(shellArtifactPath);
+            const contextGraphArtifactFiles = existsSync(contextGraphArtifactPath)
+                ? listFilesRecursive(contextGraphArtifactPath)
+                : [];
+            if (shellArtifactFiles.length === 0 && contextGraphArtifactFiles.length > 0) {
+                continue;
+            }
+            rmSync(contextGraphArtifactPath, { recursive: true, force: true });
+            mkdirSync(dirname(contextGraphArtifactPath), { recursive: true });
+            cpSync(shellArtifactPath, contextGraphArtifactPath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(contextGraphArtifactPath), { recursive: true });
+        copyFileSync(shellArtifactPath, contextGraphArtifactPath);
+    }
+    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 contextGraphArtifactPath = join(contextGraphPath, normalizedArtifactPath);
+        const shellArtifactStat = lstatSync(shellArtifactPath);
+        if (shellArtifactStat.isSymbolicLink())
+            continue;
+        if (shellArtifactStat.isDirectory()) {
+            rmSync(contextGraphArtifactPath, { recursive: true, force: true });
+            mkdirSync(dirname(contextGraphArtifactPath), { recursive: true });
+            cpSync(shellArtifactPath, contextGraphArtifactPath, {
+                recursive: true,
+                force: true,
+            });
+            continue;
+        }
+        mkdirSync(dirname(contextGraphArtifactPath), { recursive: true });
+        copyFileSync(shellArtifactPath, contextGraphArtifactPath);
+    }
+}
+export function projectContextGraphReviewArtifactsState(contextGraphPath, shellRoot, schema) {
+    const contextGraphViewRoot = join(shellRoot, "artifacts", "context-graph-view");
+    mkdirSync(contextGraphViewRoot, { recursive: true });
+    for (const artifact of listContextInterfaceArtifacts(schema)) {
+        if (artifact.path === "source-files")
+            continue;
+        const sourcePath = contextGraphArtifactAbsolutePath(contextGraphPath, artifact);
+        if (!existsSync(sourcePath))
+            continue;
+        copyResolvedTree({
+            sourcePath,
+            targetPath: join(contextGraphViewRoot, artifact.path),
+            shellType: "build-plan-improvement",
+        });
+    }
+}
+export function projectContextGraphRuntimeArtifacts(contextGraphPath, shellRoot) {
+    const runtimeTarget = join(shellRoot, "artifacts", "context-graph-runtime");
+    mkdirSync(runtimeTarget, { recursive: true });
+    const runtimeRoot = contextGraphRuntimeRoot(contextGraphPath);
+    const artifactNames = [
+        "run.json",
+        "run-history.jsonl",
+        "state.json",
+        "health.json",
+        "view-spec.json",
+        "source-manifest.json",
+        "source-manifest.audit.json",
+        "source-files.json",
+        "source-state.json",
+        "stages",
+        "logs",
+    ];
+    for (const artifactName of artifactNames) {
+        copyIfExistsLocal(join(runtimeRoot, artifactName), join(runtimeTarget, artifactName));
+    }
+}
+function copyIfExistsLocal(sourcePath, targetPath) {
+    if (!existsSync(sourcePath))
+        return;
+    copyResolvedTree({
+        sourcePath,
+        targetPath,
+        shellType: "build-plan-improvement",
+    });
+}