@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/agents/lib/source-context-scan.js

@@ -0,0 +1,388 @@
+import { opendirSync, realpathSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+/**
+ * Cheap, contents-free Source scan for Build Plan authoring.
+ *
+ * The Build Plan authoring agent locks a plan skeleton before reading any
+ * Source file. Without an inventory it defaults to a generic 4-stage plan
+ * for every Source. This scan gives the draft agent a real, task-agnostic
+ * map of the Source up front so it can shape stages to what is actually
+ * there.
+ *
+ * Guarantees:
+ * - Never opens or reads file contents. It only lists directory entries and
+ *   parses names/extensions. Source files stay read-only and unread.
+ * - Generic: no intent keywords, no task taxonomy, no per-Project answers.
+ *   It works for a folder of calls, PDFs, a codebase, or anything else.
+ * - O(file-listing) with hard caps so a pathological tree (deep nesting,
+ *   huge fan-out) can never turn the scan into a recursion or time bomb.
+ */
+const MAX_ENTRIES = 20000;
+const MAX_DEPTH = 6;
+const MAX_FOLDER_ITEMS = 40;
+const MAX_SAMPLE_NAMES = 6;
+const MAX_OBSERVATIONS = 24;
+const IGNORED_ENTRY_NAMES = new Set([
+    ".git",
+    ".interf",
+    "node_modules",
+    ".DS_Store",
+    ".cache",
+    "__pycache__",
+    ".venv",
+    ".svn",
+    ".hg",
+]);
+// Canonical, task-agnostic file kinds. Mirrors the Source Manifest kind
+// vocabulary (pdf, document, spreadsheet, presentation, image, text, other)
+// plus coarse buckets that are useful for plan shaping (code, data, audio,
+// video, archive). No kind is intent-specific.
+function classifyKind(extension) {
+    const ext = extension.replace(/^\./, "").toLowerCase();
+    if (!ext)
+        return "no-extension";
+    if (ext === "pdf")
+        return "pdf";
+    if (["doc", "docx", "rtf", "odt", "pages"].includes(ext))
+        return "document";
+    if (["csv", "tsv", "xls", "xlsx", "ods", "numbers", "parquet"].includes(ext)) {
+        return "spreadsheet";
+    }
+    if (["ppt", "pptx", "odp", "key"].includes(ext))
+        return "presentation";
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg", "heic", "tiff", "bmp"].includes(ext)) {
+        return "image";
+    }
+    if (["mp3", "wav", "m4a", "aac", "flac", "ogg", "aiff"].includes(ext))
+        return "audio";
+    if (["mp4", "mov", "avi", "mkv", "webm", "m4v"].includes(ext))
+        return "video";
+    if (["zip", "tar", "gz", "tgz", "bz2", "7z", "rar"].includes(ext))
+        return "archive";
+    if (["md", "markdown", "txt", "text"].includes(ext))
+        return "text";
+    if (["json", "ndjson", "yaml", "yml", "xml", "toml", "ini"].includes(ext))
+        return "data";
+    if ([
+        "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java",
+        "kt", "c", "h", "cpp", "hpp", "cs", "php", "swift", "sh", "sql", "html",
+        "css", "scss", "vue", "svelte",
+    ].includes(ext)) {
+        return "code";
+    }
+    return "other";
+}
+// Bare year (2019), year-month (2024-03, 2024_03), or full date
+// (2024-03-15, 20240315) appearing in a filename. Filename-only; we never
+// read file contents to find dates.
+const DATE_TOKEN = /\b(19|20)\d{2}([-_./]?(0[1-9]|1[0-2]))?([-_./]?(0[1-9]|[12]\d|3[01]))?\b/g;
+function extractDateTokens(name) {
+    const matches = name.match(DATE_TOKEN);
+    if (!matches)
+        return [];
+    return matches.filter((token) => /^(19|20)\d{2}/.test(token));
+}
+function makeFolder() {
+    return { fileCount: 0, kinds: new Map(), sampleNames: [] };
+}
+function recordFile(folder, name) {
+    folder.fileCount += 1;
+    const kind = classifyKind(extname(name));
+    folder.kinds.set(kind, (folder.kinds.get(kind) ?? 0) + 1);
+    if (folder.sampleNames.length < MAX_SAMPLE_NAMES) {
+        folder.sampleNames.push(name);
+    }
+}
+function kindSummary(kinds) {
+    return [...kinds.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([kind, count]) => `${count} ${kind}`)
+        .join(", ");
+}
+/**
+ * Resolve a directory entry to a coarse type, following symlinks.
+ *
+ * `Dirent` reports the type of the entry itself, so a symlink is neither a
+ * file nor a directory and would be dropped. The Source can legitimately be
+ * (or contain) symlinked files and dirs — mirroring the repo walker in
+ * contracts/utils/filesystem.ts, we stat the link target and classify the
+ * entry as the target's type. Broken or inaccessible links resolve to
+ * "other" and are skipped. We never read file contents here.
+ */
+function resolveEntryType(fullPath, isSymlink, isDir, isFile) {
+    if (isDir)
+        return { type: "dir", realDir: null };
+    if (isFile)
+        return { type: "file", realDir: null };
+    if (!isSymlink)
+        return { type: "other", realDir: null };
+    // Symlink: stat (follows the link) to learn the target's real type.
+    try {
+        const target = statSync(fullPath);
+        if (target.isDirectory()) {
+            // Need the canonical target path to guard against symlink cycles.
+            let realDir = null;
+            try {
+                realDir = realpathSync(fullPath);
+            }
+            catch {
+                realDir = null;
+            }
+            return { type: "dir", realDir };
+        }
+        if (target.isFile())
+            return { type: "file", realDir: null };
+        return { type: "other", realDir: null };
+    }
+    catch {
+        // Broken or inaccessible link.
+        return { type: "other", realDir: null };
+    }
+}
+/**
+ * Walk the Source tree shallowly and group counts by the top-level folder
+ * (files directly under the root group under "."). Bounded by MAX_ENTRIES
+ * and MAX_DEPTH so the cost is always O(file-listing) with a ceiling.
+ *
+ * Directories are streamed via `opendirSync` and read one entry at a time so
+ * a pathological directory with hundreds of thousands of entries can never be
+ * materialized into a single array — the MAX_ENTRIES ceiling is enforced
+ * while iterating, and iteration stops the moment it is hit. Symlinked files
+ * and directories are followed (with cycle protection) so a Source built from
+ * symlinks is counted instead of silently yielding an empty inventory.
+ */
+function scan(sourceFolderPath) {
+    const folders = new Map();
+    const totalKinds = new Map();
+    const dateTokens = [];
+    let totalFiles = 0;
+    let visited = 0;
+    let truncated = false;
+    // A read failure on the Source root itself (permission denied, path is a
+    // file, etc.) means a real Source may exist but Interf could not enumerate
+    // it. That is distinct from an empty-but-readable Source and must not be
+    // silently flattened into the same "no inventory" result. ENOENT (the root
+    // is simply not there) is treated as empty, not as a read failure.
+    let rootReadError = null;
+    // Canonical paths of directories already walked. Following symlinked dirs
+    // can introduce cycles; this set keeps the walk finite. Seeded lazily with
+    // each directory's realpath as it is opened.
+    const visitedDirs = new Set();
+    // Stack-based shallow walk. Each entry carries the absolute dir path, its
+    // depth, and the top-level group it rolls up into.
+    const stack = [
+        { dir: sourceFolderPath, depth: 0, group: "." },
+    ];
+    while (stack.length > 0) {
+        if (visited >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        const { dir, depth, group } = stack.pop();
+        // Cycle guard: skip a directory whose canonical path we have already
+        // walked (reached again through a symlink).
+        let canonicalDir;
+        try {
+            canonicalDir = realpathSync(dir);
+        }
+        catch {
+            canonicalDir = dir;
+        }
+        if (visitedDirs.has(canonicalDir))
+            continue;
+        visitedDirs.add(canonicalDir);
+        // Stream the directory: opendirSync yields one Dirent at a time so a
+        // directory with 100k+ entries is never materialized as an array. We
+        // stop reading as soon as the MAX_ENTRIES budget is exhausted.
+        let handle;
+        try {
+            handle = opendirSync(dir);
+        }
+        catch (error) {
+            // A failure to open the Source root is a read failure we must surface,
+            // not swallow — otherwise an unreadable Source produces the same empty
+            // inventory as a genuinely empty one and the draft silently goes
+            // generic. ENOENT (root absent) is left as the empty/null case so an
+            // unbound or missing Source still degrades quietly. Failures on nested
+            // directories during the walk stay tolerated: they yield a partial
+            // inventory, which the truncation note already covers.
+            if (depth === 0) {
+                const errno = error;
+                if (errno?.code !== "ENOENT")
+                    rootReadError = errno;
+            }
+            continue;
+        }
+        try {
+            let entry = handle.readSync();
+            while (entry !== null) {
+                if (visited >= MAX_ENTRIES) {
+                    truncated = true;
+                    break;
+                }
+                const name = entry.name;
+                if (IGNORED_ENTRY_NAMES.has(name) || name.startsWith(".")) {
+                    entry = handle.readSync();
+                    continue;
+                }
+                visited += 1;
+                const resolved = resolveEntryType(join(dir, name), entry.isSymbolicLink(), entry.isDirectory(), entry.isFile());
+                if (resolved.type === "dir") {
+                    // At the root, each subfolder becomes its own top-level group.
+                    const childGroup = depth === 0 ? name : group;
+                    if (!folders.has(childGroup))
+                        folders.set(childGroup, makeFolder());
+                    if (depth + 1 <= MAX_DEPTH) {
+                        if (!(resolved.realDir !== null && visitedDirs.has(resolved.realDir))) {
+                            stack.push({ dir: join(dir, name), depth: depth + 1, group: childGroup });
+                        }
+                    }
+                    else {
+                        truncated = true;
+                    }
+                }
+                else if (resolved.type === "file") {
+                    const folder = folders.get(group) ?? makeFolder();
+                    if (!folders.has(group))
+                        folders.set(group, folder);
+                    recordFile(folder, name);
+                    totalFiles += 1;
+                    const kind = classifyKind(extname(name));
+                    totalKinds.set(kind, (totalKinds.get(kind) ?? 0) + 1);
+                    for (const token of extractDateTokens(name))
+                        dateTokens.push(token);
+                }
+                entry = handle.readSync();
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+    }
+    return { folders, totalFiles, totalKinds, dateTokens, truncated, rootReadError };
+}
+function dateRange(tokens) {
+    if (tokens.length === 0)
+        return null;
+    // Compare on a normalized digits-only key so 2024-03 sorts against
+    // 20240315 consistently; report the original tokens for the bounds.
+    // Drop any token whose normalized key is not a YYYY[MMDD] digit key — a
+    // malformed or separator-only token must never become a reported date
+    // bound, which would feed the draft a misleading "Filenames span X to Y".
+    const keyed = tokens
+        .map((token) => ({
+        token,
+        key: token.replace(/[-_./]/g, "").padEnd(8, "0"),
+    }))
+        .filter(({ key }) => /^(19|20)\d{6}$/.test(key));
+    if (keyed.length === 0)
+        return null;
+    keyed.sort((a, b) => a.key.localeCompare(b.key));
+    return { min: keyed[0].token, max: keyed[keyed.length - 1].token };
+}
+/**
+ * Build the SourceContext returned when the Source root could not be read.
+ *
+ * A read failure is NOT the empty/null case: returning null here would let the
+ * draft go generic as if the Source had no files, hiding a real Source that
+ * Interf simply could not enumerate (permission denied, path is a file, etc.).
+ * Instead we surface a populated SourceContext whose limitations make the
+ * failure explicit, so the authoring agent sees it and does not lock a generic
+ * plan on a false "empty Source" reading. No file is ever opened or read.
+ */
+function readErrorContext(sourceFolderPath, error) {
+    const code = error?.code ? ` (${error.code})` : "";
+    return {
+        summary: "Contents-free Source scan could not read the Source root" +
+            `${code}; no inventory was produced.`,
+        items: [],
+        observations: [
+            `Interf could not enumerate the Source at ${sourceFolderPath}${code}.`,
+        ],
+        limitations: [
+            "Interf could not read the Source root, so this is NOT an empty Source. " +
+                "Do not lock a generic plan: inspect the Source through your own tools " +
+                "and confirm access before shaping stages.",
+        ],
+    };
+}
+/**
+ * Produce a populated SourceContext for the authoring agent from a cheap,
+ * contents-free scan. Returns null when the Source has no readable files so
+ * callers can fall back to the existing null (no fabricated inventory). A
+ * genuine read failure on the Source root returns an explicit read-error
+ * SourceContext instead, so an unreadable Source never silently degrades into
+ * a generic plan.
+ */
+export function scanSourceContext(sourceFolderPath) {
+    let result;
+    try {
+        result = scan(sourceFolderPath);
+    }
+    catch (error) {
+        // scan() handles its own root-open failure, so a throw here is unexpected.
+        // Classify it the same way: a non-ENOENT errno is a read failure that must
+        // be surfaced, not flattened into the empty/null result; ENOENT (or a
+        // non-errno) stays the quiet empty case.
+        const errno = error;
+        if (errno?.code && errno.code !== "ENOENT") {
+            return readErrorContext(sourceFolderPath, errno);
+        }
+        return null;
+    }
+    // A read failure on the Source root with nothing enumerated is distinct from
+    // a genuinely empty Source: surface it loudly so the draft never goes generic
+    // on a false "empty" reading.
+    if (result.totalFiles === 0 && result.rootReadError) {
+        return readErrorContext(sourceFolderPath, result.rootReadError);
+    }
+    if (result.totalFiles === 0)
+        return null;
+    const items = [];
+    const sortedFolders = [...result.folders.entries()]
+        .filter(([, folder]) => folder.fileCount > 0)
+        .sort((a, b) => b[1].fileCount - a[1].fileCount)
+        .slice(0, MAX_FOLDER_ITEMS);
+    for (const [folderName, folder] of sortedFolders) {
+        const sample = folder.sampleNames.join(", ");
+        const noteParts = [
+            `${folder.fileCount} file(s)`,
+            kindSummary(folder.kinds),
+        ].filter((part) => part.length > 0);
+        if (sample)
+            noteParts.push(`e.g. ${sample}`);
+        items.push({
+            name: folderName === "." ? "(root)" : folderName,
+            path: folderName === "." ? "." : folderName,
+            kind: "folder",
+            note: noteParts.join(" — "),
+        });
+    }
+    const observations = [];
+    observations.push(`${result.totalFiles} file(s) across ${result.folders.size} top-level group(s).`);
+    const totalKindSummary = kindSummary(result.totalKinds);
+    if (totalKindSummary) {
+        observations.push(`File kinds by extension: ${totalKindSummary}.`);
+    }
+    const range = dateRange(result.dateTokens);
+    if (range) {
+        observations.push(range.min === range.max
+            ? `Filenames reference the period ${range.min}.`
+            : `Filenames span ${range.min} to ${range.max} (parsed from names, not contents).`);
+    }
+    const limitations = [
+        "Inventory is filename- and extension-only; Interf did not open or read any Source file. Inspect the Source through your own tools before locking stages.",
+    ];
+    if (result.truncated) {
+        limitations.push("Scan was capped for cost; some files or deep folders were not enumerated. Treat counts as a lower bound.");
+    }
+    return {
+        summary: `Contents-free Source scan: ${result.totalFiles} file(s) in ` +
+            `${result.folders.size} top-level group(s)` +
+            (totalKindSummary ? ` (${totalKindSummary})` : "") +
+            ".",
+        items,
+        observations: observations.slice(0, MAX_OBSERVATIONS),
+        limitations,
+    };
+}

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

@@ -1,3 +1,4 @@
+import { pickString } from "./string-utils.js";
 export function extractAgentFailureStatus(event) {
     const candidates = [];
     const directMessage = pickString(event.message) ??
@@ -42,17 +43,3 @@ export function classifyTerminalVisibleStatus(text) {
 export function hasAgentStalled(lastActivityAt, now, stallTimeoutMs) {
     return typeof stallTimeoutMs === "number" && stallTimeoutMs > 0 && now - lastActivityAt >= stallTimeoutMs;
 }
-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;
-}

package/dist/packages/runtime/agents/lib/string-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pick the first usable string out of a value that may be a bare string or an
+ * array of strings / `{ text }` content blocks. Agent event payloads carry
+ * message/text/content/output/summary fields in either shape across executors,
+ * so status-determination and render paths both reach for this.
+ */
+export declare function pickString(value: unknown): string | null;
+/**
+ * Pull the primary path-like field out of a tool-use `input` record for display
+ * summaries. Tools name the same concept differently — `file_path` (Read/Write/
+ * Edit), `path`, `pattern` (Glob/Grep), `command` (Bash), `notebook_path`
+ * (notebook tools) — so every render site collapses them with the same
+ * precedence. Returns an empty string when no field is present, matching the
+ * `?? ""` default the call sites relied on.
+ */
+export declare function extractInputPath(input: Record<string, unknown>): string;

package/dist/packages/runtime/agents/lib/string-utils.js

@@ -0,0 +1,36 @@
+/**
+ * Pick the first usable string out of a value that may be a bare string or an
+ * array of strings / `{ text }` content blocks. Agent event payloads carry
+ * message/text/content/output/summary fields in either shape across executors,
+ * so status-determination and render paths both reach for this.
+ */
+export 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;
+}
+/**
+ * Pull the primary path-like field out of a tool-use `input` record for display
+ * summaries. Tools name the same concept differently — `file_path` (Read/Write/
+ * Edit), `path`, `pattern` (Glob/Grep), `command` (Bash), `notebook_path`
+ * (notebook tools) — so every render site collapses them with the same
+ * precedence. Returns an empty string when no field is present, matching the
+ * `?? ""` default the call sites relied on.
+ */
+export function extractInputPath(input) {
+    return (input.file_path ??
+        input.path ??
+        input.pattern ??
+        input.command ??
+        input.notebook_path ??
+        "");
+}

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

@@ -25,6 +25,7 @@ export interface AgentAutomationReadiness {
 export interface SpawnAgentOptions {
     eventLogPath?: string | null;
     statusLogPath?: string | null;
+    reasoningLogPath?: string | null;
     executionProfile?: AgentExecutionProfile;
     completionCheck?: (() => boolean) | null;
     onStatus?: (line: string) => void;

package/dist/packages/runtime/agents/providers/codex.js

@@ -36,6 +36,8 @@ export const codexProvider = {
             "-s",
             SANDBOX_MODE,
             "--skip-git-repo-check",
+            "-c",
+            'service_tier="fast"',
         ];
         if (profile.model) {
             args.push("--model", profile.model);

package/dist/packages/runtime/agents/role-executors.js

@@ -40,9 +40,10 @@ function agentRecordToAgent(record) {
  */
 export function buildRoleExecutorBundle(input) {
     const executors = new Map();
+    const executionProfile = input.executionProfile ?? input.defaultExecutor.executionProfile;
     for (const record of input.agents) {
         const agent = agentRecordToAgent(record);
-        executors.set(record.name, createLocalAgentExecutor(agent, input.executionProfile));
+        executors.set(record.name, createLocalAgentExecutor(agent, executionProfile));
     }
     // Make sure the active / default executor is reachable by name
     // even when the active agent isn't formally in the registry yet

package/dist/packages/runtime/auth/session-store.js

@@ -9,7 +9,7 @@
  * tests can swap `~/.interf/` via the `INTERF_USER_HOME` env var and
  * exercise auth flows without touching the real home dir.
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { interfHomeRoot } from "../../contracts/lib/project-paths.js";
@@ -66,7 +66,14 @@ export function readSession() {
 /** Persist a session. Creates the auth dir if it does not exist. */
 export function writeSession(account) {
     const path = sessionPath();
-    mkdirSync(dirname(path), { recursive: true });
+    const dir = dirname(path);
+    // `mode` on mkdir/writeFile only applies when the entry is *created*; node
+    // ignores it when the dir/file already exists. A session file (or auth dir)
+    // left over from an earlier run with looser perms (e.g. 0o644) would never be
+    // re-tightened. chmod after the write so the PII session file is always 0o600
+    // inside a 0o700 dir, even when it pre-existed.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
     const file = {
         kind: "interf-session",
         version: 1,
@@ -77,7 +84,8 @@ export function writeSession(account) {
         refreshed_at: account.refreshed_at,
     };
     const validated = SessionFileSchema.parse(file);
-    writeFileSync(path, `${JSON.stringify(validated, null, 2)}\n`);
+    writeFileSync(path, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
 }
 /** Clear the session (logout). Idempotent. */
 export function clearSession() {

package/dist/packages/runtime/benchmark-question-draft.d.ts

@@ -14,7 +14,10 @@ export declare function draftBenchmarkQuestions(options: {
     executor: AgentExecutor;
     targetCount?: number;
     onStatus?: (line: string) => void;
+    preservedShellRoot?: string;
 }): Promise<{
     checks: BenchmarkCheck[] | null;
     error?: string;
+    shellPath?: string;
+    reasoningPath?: string;
 }>;

package/dist/packages/runtime/benchmark-question-draft.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
+import { freezePreservedShell } from "./agents/lib/shell-fs.js";
 const DraftBenchmarkQuestionSchema = z.object({
     question: z.string().min(1),
     answer: z.string().min(1),
@@ -54,11 +55,20 @@ export function buildBenchmarkQuestionDraftPrompt(options) {
     ].join("\n");
 }
 export async function draftBenchmarkQuestions(options) {
-    const tempDir = mkdtempSync(join(tmpdir(), "interf-benchmark-question-draft-"));
-    mkdirSync(join(tempDir, "runtime"), { recursive: true });
-    const outputPath = join(tempDir, "questions.json");
-    const promptPath = join(tempDir, "prompt.txt");
-    writeFileSync(join(tempDir, "runtime", "source-locator.json"), `${JSON.stringify({
+    const preserve = Boolean(options.preservedShellRoot);
+    const shellRoot = options.preservedShellRoot
+        ? (mkdirSync(options.preservedShellRoot, { recursive: true }), options.preservedShellRoot)
+        : mkdtempSync(join(tmpdir(), "interf-benchmark-question-draft-"));
+    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
+    const outputPath = join(shellRoot, "questions.json");
+    const promptPath = join(shellRoot, "prompt.txt");
+    // Same canonical convention as the stage path: reasoning is teed into the
+    // shell's runtime/ dir so it is preserved when the shell is frozen.
+    const reasoningLogPath = join(shellRoot, "runtime", "agent-reasoning.jsonl");
+    const statusLogPath = join(shellRoot, "runtime", "draft.status.log");
+    const eventLogPath = join(shellRoot, "runtime", "draft.events.ndjson");
+    const verdictPath = join(shellRoot, "runtime", "verdict.json");
+    writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
         kind: "interf-source-locator",
         version: 1,
         generated_at: new Date().toISOString(),
@@ -77,48 +87,67 @@ export async function draftBenchmarkQuestions(options) {
         targetCount: options.targetCount ?? 4,
     });
     writeFileSync(promptPath, `${prompt}\n`);
+    // Record the parse/validate verdict as a structured field in the shell (the
+    // graph-less analogue of a stage's terminal verdict), so a reader inspecting
+    // the preserved shell sees WHY the draft passed or failed, not just its output.
+    const writeVerdict = (verdict) => {
+        if (!preserve)
+            return;
+        try {
+            writeFileSync(verdictPath, `${JSON.stringify({ kind: "interf-benchmark-question-draft-verdict", version: 1, ...verdict }, null, 2)}\n`);
+        }
+        catch {
+            // Best-effort: a missing verdict file must never fail the draft.
+        }
+    };
+    const finishPaths = preserve ? { shellPath: shellRoot, reasoningPath: reasoningLogPath } : {};
     try {
-        const code = await options.executor.execute(tempDir, prompt, {
+        const code = await options.executor.execute(shellRoot, prompt, {
+            eventLogPath: preserve ? eventLogPath : null,
+            statusLogPath: preserve ? statusLogPath : null,
+            reasoningLogPath: preserve ? reasoningLogPath : null,
             completionCheck: () => existsSync(outputPath),
             onStatus: options.onStatus,
         });
         if (!existsSync(outputPath)) {
-            return {
-                checks: null,
-                error: code === 0
-                    ? "The local agent finished without writing draft benchmark questions."
-                    : "The local agent did not produce draft benchmark questions.",
-            };
+            const error = code === 0
+                ? "The local agent finished without writing draft benchmark questions."
+                : "The local agent did not produce draft benchmark questions.";
+            writeVerdict({ ok: false, summary: error });
+            return { checks: null, error, ...finishPaths };
         }
         let parsed;
         try {
             parsed = JSON.parse(readFileSync(outputPath, "utf8"));
         }
         catch (error) {
-            return {
-                checks: null,
-                error: `Draft benchmark questions were not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
-            };
+            const summary = `Draft benchmark questions were not valid JSON: ${error instanceof Error ? error.message : String(error)}`;
+            writeVerdict({ ok: false, summary });
+            return { checks: null, error: summary, ...finishPaths };
         }
         const validated = DraftBenchmarkQuestionsSchema.safeParse(parsed);
         if (!validated.success) {
             const detail = validated.error.issues[0]?.message ?? "invalid draft benchmark questions";
-            return {
-                checks: null,
-                error: `Draft benchmark questions did not match the required shape: ${detail}`,
-            };
+            const summary = `Draft benchmark questions did not match the required shape: ${detail}`;
+            writeVerdict({ ok: false, summary });
+            return { checks: null, error: summary, ...finishPaths };
         }
-        return {
-            checks: validated.data,
-        };
+        writeVerdict({ ok: true, summary: `Drafted ${validated.data.length} benchmark question(s).` });
+        return { checks: validated.data, ...finishPaths };
     }
     catch (error) {
-        return {
-            checks: null,
-            error: error instanceof Error ? error.message : String(error),
-        };
+        const summary = error instanceof Error ? error.message : String(error);
+        writeVerdict({ ok: false, summary });
+        return { checks: null, error: summary, ...finishPaths };
     }
     finally {
-        rmSync(tempDir, { recursive: true, force: true });
+        // Preserve a durable shell (freeze materializes symlinks + writes the
+        // preserved-shell manifest, path unchanged); only remove an ephemeral one.
+        if (preserve) {
+            freezePreservedShell(shellRoot, "benchmark-question-draft");
+        }
+        else {
+            rmSync(shellRoot, { recursive: true, force: true });
+        }
     }
 }