@interf/compiler 0.22.2 → 0.50.0

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

@@ -1,4 +1,5 @@
 import { resolveAgent } from "./detection.js";
+import { resolveEffectiveAgentExecutionProfile } from "./execution-profile.js";
 import { spawnAgent } from "./execution.js";
 import { ensureAgentAutomatedRunReady } from "./preflight.js";
 export function buildRuntimeExecutorInfo(executor) {
@@ -14,17 +15,25 @@ export function buildRuntimeExecutorInfo(executor) {
     };
 }
 export function createLocalAgentExecutor(agent, executionProfile = {}) {
+    // Resolve the EFFECTIVE profile (per-run override ∨ saved agent prefs) ONCE,
+    // here, at construction. The executor then carries this single resolved value
+    // as `executionProfile`, so the model `buildRuntimeExecutorInfo` records and
+    // the model `buildAgentArgs` runs are sourced from the same object and can
+    // never disagree (F1). `spawnAgent` no longer re-merges prefs — it consumes
+    // this resolved profile as-is.
+    const effectiveProfile = resolveEffectiveAgentExecutionProfile(agent, executionProfile);
     return {
         kind: "local-agent",
         name: agent.name,
         displayName: agent.displayName,
         command: agent.command,
-        executionProfile,
+        executionProfile: effectiveProfile,
         execute(rootPath, prompt, options) {
             return spawnAgent(agent, rootPath, prompt, {
                 eventLogPath: options?.eventLogPath,
                 statusLogPath: options?.statusLogPath,
-                executionProfile,
+                reasoningLogPath: options?.reasoningLogPath,
+                executionProfile: effectiveProfile,
                 completionCheck: options?.completionCheck,
                 onStatus: options?.onStatus,
             });

package/dist/packages/runtime/agents/lib/logs.d.ts

@@ -0,0 +1,12 @@
+export declare function appendAgentEventLog(eventLogPath: string | null | undefined, event: Record<string, unknown>): void;
+export declare function appendAgentStatusLog(statusLogPath: string | null | undefined, text: string): void;
+/**
+ * Append one reasoning/thinking span to the best-effort reasoning transcript
+ * (one JSON object per line). Reasoning capture must never block or fail a run,
+ * so any write error is swallowed — a missing reasoning line is acceptable, a
+ * crashed Build is not.
+ */
+export declare function appendAgentReasoningLog(reasoningLogPath: string | null | undefined, span: {
+    kind: string;
+    text: string;
+}): void;

package/dist/packages/runtime/agents/lib/logs.js

@@ -0,0 +1,41 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Append one line to a run log file, creating its directory on demand.
+ *
+ * Run log writes are observability, never run control: a mid-run disk hiccup
+ * (mkdir/append failure) must record a recoverable session, not throw an
+ * unhandled rejection that crashes the Build and dangles the session's
+ * `logs.event_stream_path`/`logs.status_path`. The single explicit policy for
+ * every agent run log is therefore best-effort — a missing log line is
+ * acceptable, a crashed run is not. A null/empty path is a no-op.
+ */
+function ensureLogFile(path, content) {
+    if (!path)
+        return;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, content);
+    }
+    catch {
+        // Best-effort only: log writes must never block or fail a run.
+    }
+}
+export function appendAgentEventLog(eventLogPath, event) {
+    ensureLogFile(eventLogPath, `${JSON.stringify({
+        timestamp: new Date().toISOString(),
+        ...event,
+    })}\n`);
+}
+export function appendAgentStatusLog(statusLogPath, text) {
+    ensureLogFile(statusLogPath, `${new Date().toISOString()} ${text}\n`);
+}
+/**
+ * Append one reasoning/thinking span to the best-effort reasoning transcript
+ * (one JSON object per line). Reasoning capture must never block or fail a run,
+ * so any write error is swallowed — a missing reasoning line is acceptable, a
+ * crashed Build is not.
+ */
+export function appendAgentReasoningLog(reasoningLogPath, span) {
+    ensureLogFile(reasoningLogPath, `${JSON.stringify({ timestamp: new Date().toISOString(), ...span })}\n`);
+}

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

@@ -2,7 +2,8 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { CODEX_NOISE_PATTERNS } from "./constants.js";
+import { getBuiltInProvider } from "../providers/index.js";
+import { loadAgentPrefs } from "../registry.js";
 import { buildAgentArgs, buildAgentEnv } from "./args.js";
 const successfulPreflightAgents = new Set();
 export function buildAgentPreflightPrompt() {
@@ -19,15 +20,18 @@ export function runAgentPreflight(agent, options = {}) {
     const spawnSyncImpl = options.spawnSyncImpl ?? spawnSync;
     const dirPath = mkdtempSync(join(tmpdir(), "interf-doctor-"));
     try {
+        const prefs = loadAgentPrefs()[agent.name];
+        const baseEnv = buildAgentEnv(agent);
+        const env = prefs?.env_vars ? { ...baseEnv, ...prefs.env_vars } : baseEnv;
         const result = spawnSyncImpl(agent.command, buildAgentArgs(agent, buildAgentPreflightPrompt()), {
             cwd: dirPath,
             encoding: "utf8",
-            env: buildAgentEnv(agent),
+            env,
             input: "",
             timeout: timeoutMs,
         });
         const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
-        const stderr = sanitizeAgentStderr(typeof result.stderr === "string" ? result.stderr : "");
+        const stderr = sanitizeAgentStderr(agent, typeof result.stderr === "string" ? result.stderr : "");
         const timedOut = result.error?.name === "Error" && result.error.message.includes("timed out");
         if (result.error) {
             return {
@@ -65,7 +69,7 @@ export function ensureAgentAutomatedRunReady(agent, options = {}) {
             successfulPreflightAgents.add(agent.name);
             return { ok: true };
         }
-        if (!isTransientCodexPreflightFailure(agent, result) || attempt === 3) {
+        if (!isTransientPreflightFailure(agent, result) || attempt === 3) {
             break;
         }
         sleepSync(retryDelayMs * attempt);
@@ -73,25 +77,26 @@ export function ensureAgentAutomatedRunReady(agent, options = {}) {
     const details = result ? [result.error, result.stderr].filter(Boolean).join(" ") : "";
     return {
         ok: false,
-        error: `${agent.displayName} failed Interf executor preflight. Run \`interf doctor --live\` for details.${details ? ` ${details}` : ""}`,
+        error: `${agent.displayName} failed Interf executor preflight. ` +
+            `Run \`interf doctor --live\` for details, or switch active agent with \`interf agents use <name>\` ` +
+            `(e.g. \`interf agents use claude-code\`).` +
+            (details ? ` ${details}` : ""),
     };
 }
-function sanitizeAgentStderr(stderr) {
+function sanitizeAgentStderr(agent, stderr) {
+    const filters = getBuiltInProvider(agent.name)?.noiseFilters ?? [];
     return stderr
         .split("\n")
         .filter((line) => line.trim().length > 0)
-        .filter((line) => !CODEX_NOISE_PATTERNS.some((pattern) => pattern.test(line)))
+        .filter((line) => !filters.some((pattern) => pattern.test(line)))
         .join("\n")
         .trim();
 }
-function isTransientCodexPreflightFailure(agent, result) {
-    if (agent.name !== "codex")
+function isTransientPreflightFailure(agent, result) {
+    const provider = getBuiltInProvider(agent.name);
+    if (!provider?.isTransientPreflightFailure)
         return false;
-    const text = `${result.error ?? ""}\n${result.stderr ?? ""}`;
-    if (/usage limit/i.test(text))
-        return false;
-    return /failed to record rollout items/i.test(text) ||
-        /thread\s+[0-9a-f-]+\s+not found/i.test(text);
+    return provider.isTransientPreflightFailure(result.stderr ?? "", result.error ?? "");
 }
 function sleepSync(ms) {
     if (ms <= 0)

package/dist/packages/runtime/agents/lib/render.d.ts

@@ -0,0 +1,26 @@
+export interface VisibleTextState {
+    current: string | null;
+    terminated?: boolean;
+    terminalStatus?: string | null;
+}
+export declare function emitVisibleAgentText(text: string, statusLogPath: string | null | undefined, lastVisibleText?: VisibleTextState, onStatus?: (line: string) => void): boolean;
+export declare function displayAgentEvent(event: Record<string, unknown>, statusLogPath: string | null | undefined, lastVisibleText: VisibleTextState, onStatus?: (line: string) => void): boolean;
+/**
+ * One reasoning/thinking span lifted from an agent event, for the best-effort
+ * reasoning transcript. `kind` records where it came from so the transcript
+ * stays inspectable across executors.
+ */
+export interface AgentReasoningSpan {
+    kind: "thinking" | "reasoning";
+    text: string;
+}
+/**
+ * Extract any reasoning/thinking spans from a single parsed agent event. The
+ * event stream is already parsed for display; this lifts the reasoning the
+ * display path discards (it never renders thinking) so it can be teed to a
+ * runtime file. Covers Claude Code `assistant` messages carrying `thinking`
+ * content blocks and Codex `item.*` reasoning items. Returns `[]` for events
+ * with no reasoning — callers must treat reasoning capture as best-effort.
+ */
+export declare function extractAgentReasoning(event: Record<string, unknown>): AgentReasoningSpan[];
+export declare function summarizeAgentToolActivity(event: Record<string, unknown>): string | null;

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

@@ -2,6 +2,7 @@ import { basename } from "node:path";
 import chalk from "chalk";
 import { SHOW_AGENT_TOOL_EVENTS, VISIBLE_STATUS_PREFIXES, } from "./constants.js";
 import { appendAgentStatusLog } from "./logs.js";
+import { extractInputPath, pickString } from "./string-utils.js";
 export function emitVisibleAgentText(text, statusLogPath, lastVisibleText, onStatus) {
     if (lastVisibleText?.terminated) {
         return false;
@@ -37,7 +38,7 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
         const input = event.input;
         let detail = "";
         if (input) {
-            const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+            const path = extractInputPath(input);
             if (path)
                 detail = chalk.dim(` ${path.slice(0, 80)}`);
         }
@@ -58,7 +59,7 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
                     const input = block.input;
                     let detail = "";
                     if (input) {
-                        const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+                        const path = extractInputPath(input);
                         if (path)
                             detail = chalk.dim(` ${path.slice(0, 80)}`);
                     }
@@ -95,6 +96,45 @@ export function displayAgentEvent(event, statusLogPath, lastVisibleText, onStatu
     }
     return displayed;
 }
+/**
+ * Extract any reasoning/thinking spans from a single parsed agent event. The
+ * event stream is already parsed for display; this lifts the reasoning the
+ * display path discards (it never renders thinking) so it can be teed to a
+ * runtime file. Covers Claude Code `assistant` messages carrying `thinking`
+ * content blocks and Codex `item.*` reasoning items. Returns `[]` for events
+ * with no reasoning — callers must treat reasoning capture as best-effort.
+ */
+export function extractAgentReasoning(event) {
+    const type = event.type;
+    const spans = [];
+    if (type === "assistant") {
+        const message = event.message;
+        const content = message?.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block.type === "thinking" || block.type === "redacted_thinking") {
+                    const text = pickString(block.thinking) ?? pickString(block.text);
+                    if (text)
+                        spans.push({ kind: "thinking", text });
+                }
+            }
+        }
+    }
+    if (type === "item.started" || type === "item.completed") {
+        const item = event.item;
+        if (item?.type === "reasoning") {
+            const text = pickString(item.text) ?? pickString(item.summary) ?? pickString(item.content);
+            if (text)
+                spans.push({ kind: "reasoning", text });
+        }
+    }
+    if (type === "reasoning") {
+        const text = pickString(event.text) ?? pickString(event.summary) ?? pickString(event.content);
+        if (text)
+            spans.push({ kind: "reasoning", text });
+    }
+    return spans;
+}
 export function summarizeAgentToolActivity(event) {
     const type = event.type;
     if (type === "assistant") {
@@ -116,20 +156,6 @@ export function summarizeAgentToolActivity(event) {
     }
     return null;
 }
-function pickString(value) {
-    if (typeof value === "string")
-        return value;
-    if (!Array.isArray(value))
-        return null;
-    for (const entry of value) {
-        if (typeof entry === "string")
-            return entry;
-        if (entry && typeof entry === "object" && "text" in entry && typeof entry.text === "string") {
-            return entry.text;
-        }
-    }
-    return null;
-}
 function displayItemEvent(type, item, statusLogPath, lastVisibleText, onStatus) {
     const itemType = item.type;
     if (itemType === "agent_message") {
@@ -159,7 +185,7 @@ function displayItemEvent(type, item, statusLogPath, lastVisibleText, onStatus)
     return false;
 }
 function describeInput(input) {
-    const path = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? "");
+    const path = extractInputPath(input);
     return path ? chalk.dim(` ${path.slice(0, 80)}`) : "";
 }
 function summarizeToolUse(name, input) {
@@ -168,14 +194,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:
@@ -185,7 +211,7 @@ function summarizeToolUse(name, input) {
 function summarizeToolTarget(input) {
     if (!input)
         return null;
-    const raw = (input.file_path ?? input.path ?? input.pattern ?? input.command ?? input.notebook_path);
+    const raw = extractInputPath(input);
     if (!raw || raw.length === 0)
         return null;
     if (raw.includes("\n")) {

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;