@interf/compiler 0.33.0 → 0.50.0

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

@@ -14,6 +14,31 @@ export declare function validateStageExecutionShellInputs(options: {
     summary: string;
 };
 export declare function writeNativeAgentSurface(rootPath: string, agentsContent: string, skillName: string, skillContent: string): boolean;
+/**
+ * One data-driven shell constructor shared by every agent job (stage execution,
+ * Build Plan authoring, Build Plan improvement). The shared skeleton lives here
+ * exactly once: create the shell root, create the requested subdirectories, and
+ * write the native agent surface (AGENTS.md / CLAUDE.md / SKILL.md) the agent
+ * boots from. Job-specific projection (runtime inputs, source locators, build
+ * plan trees, artifact mounts) stays in each caller — `createAgentShell` only
+ * owns the skeleton, so a reader traces shell setup through one function instead
+ * of three near-identical ones.
+ *
+ * `rootPath` is resolved by the caller (the three job kinds keep their distinct
+ * storage roots: stage shells under the Context Graph, improvement loops under
+ * the loop root, authoring shells under the Project's service job storage).
+ */
+export declare function createAgentShell(options: {
+    rootPath: string;
+    subdirs: readonly string[];
+    nativeSurface: {
+        agentsContent: string;
+        skillName: string;
+        skillContent: string;
+    };
+}): {
+    rootPath: string;
+};
 export declare function pruneStageExecutionShells(contextGraphPath: string): void;
 export declare function projectContextGraphQueryShell(contextGraphPath: string, contextGraphName: string, buildPlanId: string, options?: {
     buildPlanOriginSelected?: string | null;
@@ -36,6 +61,7 @@ export declare function createBuildPlanAuthoringShell(options: {
     requestedArtifacts?: RequestedArtifact[];
     sourceContext?: SourceContext | null;
     artifactRequirements?: BuildPlanAuthoringArtifactRequirement[];
+    shellRoot?: string;
 }): {
     rootPath: string;
     buildPlanBeforePath: string;
@@ -43,7 +69,9 @@ export declare function createBuildPlanAuthoringShell(options: {
     promptLogPath: string;
     eventLogPath: string;
     statusLogPath: string;
+    reasoningLogPath: string;
 };
+export declare function freezeBuildPlanAuthoringShell(rootPath: string): string | null;
 export declare function createBuildPlanImprovementShell(options: {
     contextGraphPath: string;
     contextGraphName: string;
@@ -59,5 +87,6 @@ export declare function createBuildPlanImprovementShell(options: {
     promptLogPath: string;
     eventLogPath: string;
     statusLogPath: string;
+    reasoningLogPath: string;
 };
 export declare function freezeBuildPlanImprovementShell(rootPath: string): string | null;

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

@@ -2,12 +2,14 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import { buildShellSourceState, loadBuildStageInputs, loadContextGraphSourceManifest, loadContextGraphSourceState, } from "../../build/source-manifest.js";
+import { writeStageExpectedInputs, } from "../../build/stage-manifest.js";
+import { resolveBuildContext, } from "../../build/build-target.js";
 import { CHECK_PARAM_CONTRACTS, CHECK_KINDS, SourceManifestSchema, StageInputsSchema, } from "../../../contracts/lib/schema.js";
-import { stageExecutionShellsRoot, buildPlanImprovementLoopRoot, buildPlanPackagePathForContextGraph, contextGraphInterfConfigPath, contextGraphRuntimeSourceManifestPath, contextGraphRuntimeRoot, } from "../../build/context-graph-paths.js";
+import { stageExecutionShellsRoot, buildPlanImprovementLoopRoot, buildPlanPackagePathForContextGraph, contextGraphInterfConfigPath, contextGraphRuntimeSourceManifestPath, contextGraphRuntimeStageExpectedInputsPath, contextGraphRuntimeRoot, } from "../../build/context-graph-paths.js";
 import { writeFileAtomic, writeJsonAtomic } from "../../build/atomic-fs.js";
 import { resolveBuildPlanImprovementReviewSourcePaths } from "../../../build-plans/package/build-plan-review-paths.js";
 import { copyIfExists, copyResolvedTree, freezePreservedShell, writeIfChanged, writeNativeSkillCopies, } from "./shell-fs.js";
-import { shellLogsPath, shellRuntimePath, } from "./shell-paths.js";
+import { shellRuntimePath, } from "./shell-paths.js";
 import { writeStageExecutionWorkspaceManifest, } from "./shell-workspace.js";
 import { readBuildPlanImprovementDoc, readContextGraphQuerySkillSource, renderBuildPlanAuthoringAgents, renderBuildPlanAuthoringSkill, renderBuildPlanImprovementAgents, renderBuildPlanImprovementSkill, renderClaudeBootstrap, renderSourceFilesTestAgents, renderSourceFilesTestQuerySkill, renderStageExecutionAgents, renderStageExecutionSkill, renderContextGraphAgents, renderContextGraphQueryNativeSkill, renderContextGraphQuerySkill, } from "./shell-templates.js";
 import { buildStageArtifactMounts, ensureBuildExecutionSurface, projectBuildPlanMetadata, projectStageArtifactMountAliases, projectContextGraphReviewArtifactsState, projectContextGraphRuntimeArtifacts, projectContextGraphSchemaArtifacts, readStageBuildPlanDoc, stageMaterializedArtifactSet, syncStageExecutionShellWrites, writeExecutionShellPathsFile, } from "./shell-projection.js";
@@ -97,6 +99,28 @@ export function writeNativeAgentSurface(rootPath, agentsContent, skillName, skil
     changed = writeNativeSkillCopies(rootPath, skillName, skillContent) || changed;
     return changed;
 }
+/**
+ * One data-driven shell constructor shared by every agent job (stage execution,
+ * Build Plan authoring, Build Plan improvement). The shared skeleton lives here
+ * exactly once: create the shell root, create the requested subdirectories, and
+ * write the native agent surface (AGENTS.md / CLAUDE.md / SKILL.md) the agent
+ * boots from. Job-specific projection (runtime inputs, source locators, build
+ * plan trees, artifact mounts) stays in each caller — `createAgentShell` only
+ * owns the skeleton, so a reader traces shell setup through one function instead
+ * of three near-identical ones.
+ *
+ * `rootPath` is resolved by the caller (the three job kinds keep their distinct
+ * storage roots: stage shells under the Context Graph, improvement loops under
+ * the loop root, authoring shells under the Project's service job storage).
+ */
+export function createAgentShell(options) {
+    mkdirSync(options.rootPath, { recursive: true });
+    for (const subdir of options.subdirs) {
+        mkdirSync(join(options.rootPath, subdir), { recursive: true });
+    }
+    writeNativeAgentSurface(options.rootPath, options.nativeSurface.agentsContent, options.nativeSurface.skillName, options.nativeSurface.skillContent);
+    return { rootPath: options.rootPath };
+}
 export function pruneStageExecutionShells(contextGraphPath) {
     rmSync(stageExecutionShellsRoot(contextGraphPath), { recursive: true, force: true });
 }
@@ -113,13 +137,15 @@ export function createStageExecutionShell(contextGraphPath, contextGraphName, bu
     const materializedArtifacts = stageMaterializedArtifactSet(schema, stage, writeArtifacts);
     const cleanWriteArtifacts = new Set(stage.writes.filter((artifactId) => !stage.reads.includes(artifactId)));
     const shellsRoot = stageExecutionShellsRoot(contextGraphPath);
-    const shellRoot = join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
-    mkdirSync(shellRoot, { recursive: true });
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, ".interf", "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "inputs"), { recursive: true });
-    mkdirSync(join(shellRoot, "outputs"), { recursive: true });
-    mkdirSync(shellLogsPath(shellRoot), { recursive: true });
+    const { rootPath: shellRoot } = createAgentShell({
+        rootPath: join(shellsRoot, `${stage.id}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`),
+        subdirs: ["runtime", join(".interf", "runtime"), "inputs", "outputs", "logs"],
+        nativeSurface: {
+            agentsContent: renderStageExecutionAgents(contextGraphName, buildPlanId, stage),
+            skillName: "interf-stage",
+            skillContent: renderStageExecutionSkill(stage, readStageBuildPlanDoc(contextGraphPath, stage)),
+        },
+    });
     copyResolvedTree({
         sourcePath: contextGraphInterfConfigPath(contextGraphPath),
         targetPath: join(shellRoot, "interf.json"),
@@ -129,6 +155,17 @@ export function createStageExecutionShell(contextGraphPath, contextGraphName, bu
     const sourceState = loadContextGraphSourceState(contextGraphPath);
     const stageInputs = loadBuildStageInputs(contextGraphPath, stage.id);
     const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
+    if (!existsSync(contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stage.id))) {
+        writeStageExpectedInputs({ contextGraphPath, stage });
+    }
+    const buildContext = resolveBuildContext(contextGraphPath);
+    writeJsonAtomic(shellRuntimePath(shellRoot, "project.json"), {
+        kind: "interf-stage-project-context",
+        version: 1,
+        project: buildContext.project,
+        build_plan: buildPlanId,
+        stage: stage.id,
+    });
     if (sourceManifest) {
         writeJsonAtomic(shellRuntimePath(shellRoot, "source-manifest.json"), sourceManifest);
         copyIfExists(contextGraphRuntimeSourceManifestPath(contextGraphPath), join(shellRoot, ".interf", "runtime", "source-manifest.json"), "stage-execution");
@@ -137,13 +174,12 @@ export function createStageExecutionShell(contextGraphPath, contextGraphName, bu
         writeJsonAtomic(shellRuntimePath(shellRoot, "stage-inputs.json"), stageInputs);
         writeJsonAtomic(shellRuntimePath(shellRoot, "source-state.json"), buildShellSourceState(sourceState, stageInputs));
     }
+    copyIfExists(contextGraphRuntimeStageExpectedInputsPath(contextGraphPath, stage.id), shellRuntimePath(shellRoot, "expected-inputs.json"), "stage-execution");
     writeStageSelfCheckScript(shellRoot);
     projectContextGraphSchemaArtifacts(contextGraphPath, shellRoot, schema, new Set([...stage.reads, ...stage.writes]), materializedArtifacts, cleanWriteArtifacts);
     projectBuildPlanMetadata(contextGraphPath, shellRoot, stage);
     projectStageArtifactMountAliases(shellRoot, stage, schema);
     writeExecutionShellPathsFile(shellRoot, buildPlanId, stage, buildStageArtifactMounts(contextGraphPath, shellRoot, stage, schema));
-    const agentsContent = renderStageExecutionAgents(contextGraphName, buildPlanId, stage);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-stage", renderStageExecutionSkill(stage, readStageBuildPlanDoc(contextGraphPath, stage)));
     writeStageExecutionWorkspaceManifest({
         contextGraphPath,
         shellRoot,
@@ -166,7 +202,7 @@ function writeStageSelfCheckScript(shellRoot) {
         "",
         `const { evaluateChecks } = await import(${JSON.stringify(checkEvaluatorModuleUrl)});`,
         `const { RuntimeStageContractSchema } = await import(${JSON.stringify(runtimeSchemaModuleUrl)});`,
-        `const { SourceManifestSchema, StageEvidenceSchema, StageInputsSchema } = await import(${JSON.stringify(contractsSchemaModuleUrl)});`,
+        `const { ResourceRefSchema, ReviewedInputSchema, SourceManifestSchema, StageEvidenceSchema, StageInputsSchema } = await import(${JSON.stringify(contractsSchemaModuleUrl)});`,
         "",
         "const shellRoot = resolve(dirname(fileURLToPath(import.meta.url)), \"..\");",
         "const contractPath = resolve(shellRoot, \"runtime\", \"stage-contract.json\");",
@@ -174,6 +210,7 @@ function writeStageSelfCheckScript(shellRoot) {
         "const artifactResults = [];",
         "const evidenceFailures = [];",
         "const inputFailures = [];",
+        "const coverageFailures = [];",
         "const stageInputsPath = resolve(shellRoot, \"runtime\", \"stage-inputs.json\");",
         "",
         "if (!existsSync(stageInputsPath)) {",
@@ -198,6 +235,62 @@ function writeStageSelfCheckScript(shellRoot) {
         "  }",
         "}",
         "",
+        "const expectedInputsPath = resolve(shellRoot, \"runtime\", \"expected-inputs.json\");",
+        "const reviewedInputsPath = resolve(shellRoot, \"runtime\", \"reviewed-inputs.json\");",
+        "let expectedInputs = [];",
+        "if (!existsSync(expectedInputsPath)) {",
+        "  coverageFailures.push(\"runtime/expected-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const file = JSON.parse(readFileSync(expectedInputsPath, \"utf8\"));",
+        "    if (file.kind !== \"interf-stage-expected-inputs\" || file.stage_id !== contract.stage) {",
+        "      coverageFailures.push(`expected inputs file is not for stage ${contract.stage}.`);",
+        "    }",
+        "    expectedInputs = Array.isArray(file.expected)",
+        "      ? file.expected.map((entry) => ResourceRefSchema.parse(entry))",
+        "      : [];",
+        "    if (!Array.isArray(file.expected)) {",
+        "      coverageFailures.push(\"expected inputs file must contain an expected array.\");",
+        "    }",
+        "  } catch (error) {",
+        "    coverageFailures.push(`expected inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
+        "if (!existsSync(reviewedInputsPath)) {",
+        "  coverageFailures.push(\"runtime/reviewed-inputs.json was not written.\");",
+        "} else {",
+        "  try {",
+        "    const file = JSON.parse(readFileSync(reviewedInputsPath, \"utf8\"));",
+        "    if (file.kind !== \"interf-stage-reviewed-inputs\" || file.stage_id !== contract.stage) {",
+        "      coverageFailures.push(`reviewed inputs file is not for stage ${contract.stage}.`);",
+        "    }",
+        "    const reviewed = Array.isArray(file.reviewed)",
+        "      ? file.reviewed.map((entry) => ReviewedInputSchema.parse(entry))",
+        "      : [];",
+        "    if (!Array.isArray(file.reviewed)) {",
+        "      coverageFailures.push(\"reviewed inputs file must contain a reviewed array.\");",
+        "    }",
+        "    const expectedIds = new Set(expectedInputs.map((entry) => entry.id));",
+        "    const reviewedIds = new Set(reviewed.map((entry) => entry.resource_id));",
+        "    for (const entry of reviewed) {",
+        "      if (!expectedIds.has(entry.resource_id)) {",
+        "        coverageFailures.push(`reviewed input ${entry.resource_id} is not in runtime/expected-inputs.json.`);",
+        "      }",
+        "      if ((entry.decision === \"missing\" || entry.decision === \"blocked\" || entry.decision === \"not-relevant\") && !entry.reason) {",
+        "        coverageFailures.push(`reviewed input ${entry.resource_id} needs a reason for decision ${entry.decision}.`);",
+        "      }",
+        "    }",
+        "    for (const input of expectedInputs) {",
+        "      if (input.required !== false && !reviewedIds.has(input.id)) {",
+        "        coverageFailures.push(`required expected input ${input.id} was not reviewed.`);",
+        "      }",
+        "    }",
+        "  } catch (error) {",
+        "    coverageFailures.push(`reviewed inputs JSON is invalid: ${error instanceof Error ? error.message : String(error)}`);",
+        "  }",
+        "}",
+        "",
         "for (const writeContract of contract.artifacts.write_contracts) {",
         "  const result = evaluateChecks(writeContract.checks, {",
         "    rootPath: shellRoot,",
@@ -238,7 +331,10 @@ function writeStageSelfCheckScript(shellRoot) {
         "      if (evidenceItemsWithRefs.length === 0) {",
         "        evidenceFailures.push(\"stage evidence needs at least one source/output evidence item.\");",
         "      }",
-        "      const writableArtifacts = new Set(contract.artifacts.writes);",
+        "      const writableArtifacts = new Set([",
+        "        ...contract.artifacts.writes,",
+        "        ...contract.artifacts.write_contracts.map((writeContract) => writeContract.artifact_id),",
+        "      ]);",
         "      for (const item of evidence.items) {",
         "        for (const ref of item.output_refs) {",
         "          if (!writableArtifacts.has(ref.artifact_id)) {",
@@ -255,12 +351,12 @@ function writeStageSelfCheckScript(shellRoot) {
         "  }",
         "}",
         "",
-        "if (failures.length === 0 && evidenceFailures.length === 0 && inputFailures.length === 0) {",
+        "if (failures.length === 0 && evidenceFailures.length === 0 && inputFailures.length === 0 && coverageFailures.length === 0) {",
         "  console.log(`VALID: ${contract.stage} stage outputs satisfy ${passedChecks}/${totalChecks} deterministic check(s).`);",
         "  process.exit(0);",
         "}",
         "",
-        "console.log(`INVALID: ${failures.length + evidenceFailures.length + inputFailures.length} required deterministic check(s) failed for stage ${contract.stage}.`);",
+        "console.log(`INVALID: ${failures.length + evidenceFailures.length + inputFailures.length + coverageFailures.length} required deterministic check(s) failed for stage ${contract.stage}.`);",
         "for (const { artifact, failure } of failures) {",
         "  console.log(`- ${artifact.artifact_id} (${artifact.path}) / ${failure.check_id}: ${failure.summary}`);",
         "  if (failure.details) {",
@@ -273,6 +369,9 @@ function writeStageSelfCheckScript(shellRoot) {
         "for (const failure of inputFailures) {",
         "  console.log(`- stage input: ${failure}`);",
         "}",
+        "for (const failure of coverageFailures) {",
+        "  console.log(`- stage coverage: ${failure}`);",
+        "}",
         "process.exit(1);",
         "",
     ].join("\n");
@@ -282,10 +381,28 @@ export function freezeStageExecutionShell(rootPath) {
     return freezePreservedShell(rootPath, "stage-execution");
 }
 export function createBuildPlanAuthoringShell(options) {
-    const shellRoot = mkdtempSync(join(tmpdir(), `interf-build-plan-author-${options.buildPlanId}-`));
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
-    mkdirSync(join(shellRoot, "logs"), { recursive: true });
+    const { rootPath: shellRoot } = createAgentShell({
+        // Durable Project job storage in the launched path; ephemeral /tmp only when
+        // no durable root was supplied (unit tests of the draft/parse path).
+        rootPath: options.shellRoot ??
+            mkdtempSync(join(tmpdir(), `interf-build-plan-author-${options.buildPlanId}-`)),
+        subdirs: ["runtime", "artifacts", "logs"],
+        nativeSurface: {
+            agentsContent: renderBuildPlanAuthoringAgents({
+                buildPlanId: options.buildPlanId,
+                label: options.label,
+                referenceBuildPlanId: options.referenceBuildPlanId ?? null,
+            }),
+            skillName: "interf-build-plan-author",
+            skillContent: renderBuildPlanAuthoringSkill(),
+        },
+    });
+    // source_context is resolved ONCE by the caller (runBuildPlanAuthoringDraft):
+    // caller-supplied context wins, else the cheap contents-free Source scan,
+    // else null. The shell is a pure consumer here so authoring-context.json and
+    // the persisted authoring brief always carry the SAME value. Do not re-derive
+    // or re-scan it in the shell.
+    const sourceContext = options.sourceContext ?? null;
     const context = {
         kind: "interf-build-plan-authoring",
         version: 1,
@@ -303,7 +420,7 @@ export function createBuildPlanAuthoringShell(options) {
         artifact_requirements: options.artifactRequirements ?? [],
         project: {
             source_folder_path: options.sourceFolderPath,
-            source_context: options.sourceContext ?? null,
+            source_context: sourceContext,
         },
     };
     writeFileSync(join(shellRoot, "runtime", "authoring-context.json"), `${JSON.stringify(context, null, 2)}\n`);
@@ -315,18 +432,13 @@ export function createBuildPlanAuthoringShell(options) {
             kind: "local-folder",
             locator: options.sourceFolderPath,
         },
-        note: "Interf does not pre-scan Source files for Build Plan authoring. The authoring agent inspects this locator through its own Source access.",
+        note: "Interf attaches a cheap, contents-free Source scan (folder names, file counts, file kinds, sampled filenames, filename date ranges) to runtime/authoring-context.json.project.source_context. It never reads file contents. Use it to shape stages, then inspect this locator through your own Source access before locking the plan.",
     }, null, 2)}\n`);
     copyResolvedTree({
         sourcePath: options.buildPlanPath,
         targetPath: join(shellRoot, "build-plan"),
         shellType: "build-plan-authoring",
     });
-    writeNativeAgentSurface(shellRoot, renderBuildPlanAuthoringAgents({
-        buildPlanId: options.buildPlanId,
-        label: options.label,
-        referenceBuildPlanId: options.referenceBuildPlanId ?? null,
-    }), "interf-build-plan-author", renderBuildPlanAuthoringSkill());
     return {
         rootPath: shellRoot,
         buildPlanBeforePath: join(shellRoot, "artifacts", "build-plan-before"),
@@ -334,15 +446,28 @@ export function createBuildPlanAuthoringShell(options) {
         promptLogPath: join(shellRoot, "logs", "build-plan-author.prompt.txt"),
         eventLogPath: join(shellRoot, "logs", "build-plan-author.events.ndjson"),
         statusLogPath: join(shellRoot, "logs", "build-plan-author.status.log"),
+        // 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.
+        reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
     };
 }
+export function freezeBuildPlanAuthoringShell(rootPath) {
+    return freezePreservedShell(rootPath, "build-plan-authoring");
+}
 export function createBuildPlanImprovementShell(options) {
     const schema = ensureBuildExecutionSurface(options.contextGraphPath);
     const loopRootPath = buildPlanImprovementLoopRoot(options.contextGraphPath, options.runId, options.loopIndex);
-    const shellRoot = join(loopRootPath, "shell");
-    mkdirSync(shellRoot, { recursive: true });
-    mkdirSync(join(shellRoot, "runtime"), { recursive: true });
-    mkdirSync(join(shellRoot, "artifacts"), { recursive: true });
+    const { rootPath: shellRoot } = createAgentShell({
+        rootPath: join(loopRootPath, "shell"),
+        subdirs: ["runtime", "artifacts"],
+        nativeSurface: {
+            agentsContent: renderBuildPlanImprovementAgents(options.contextGraphName, options.buildPlanId, options.loopIndex),
+            skillName: "interf-build-plan-improver",
+            skillContent: renderBuildPlanImprovementSkill(options.buildPlanId, options.loopIndex, readBuildPlanImprovementDoc(options.contextGraphPath)),
+        },
+    });
+    // Improvement logs live one level up in the loop root (not the shell), so the
+    // loop record can index them beside build-plan-before/after.
     mkdirSync(join(loopRootPath, "logs"), { recursive: true });
     writeFileSync(join(shellRoot, "runtime", "loop-context.json"), `${JSON.stringify(options.context, null, 2)}\n`);
     projectContextGraphReviewArtifactsState(options.contextGraphPath, shellRoot, schema);
@@ -366,8 +491,6 @@ export function createBuildPlanImprovementShell(options) {
     if (reviewSources.targetTestSandboxes) {
         copyIfExists(reviewSources.targetTestSandboxes, join(shellRoot, "artifacts", "test-sandboxes"), "build-plan-improvement");
     }
-    const agentsContent = renderBuildPlanImprovementAgents(options.contextGraphName, options.buildPlanId, options.loopIndex);
-    writeNativeAgentSurface(shellRoot, agentsContent, "interf-build-plan-improver", renderBuildPlanImprovementSkill(options.buildPlanId, options.loopIndex, readBuildPlanImprovementDoc(options.contextGraphPath)));
     return {
         rootPath: shellRoot,
         loopRootPath,
@@ -376,6 +499,9 @@ export function createBuildPlanImprovementShell(options) {
         promptLogPath: join(loopRootPath, "logs", "build-plan-improver.prompt.txt"),
         eventLogPath: join(loopRootPath, "logs", "build-plan-improver.events.ndjson"),
         statusLogPath: join(loopRootPath, "logs", "build-plan-improver.status.log"),
+        // Reasoning is teed into the shell's runtime/ dir (same convention as the
+        // stage path) so it is preserved when the improvement shell is frozen.
+        reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
     };
 }
 export function freezeBuildPlanImprovementShell(rootPath) {

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

@@ -0,0 +1,10 @@
+import type { SourceContext } from "../../../build-plans/authoring/brief.js";
+/**
+ * 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 declare function scanSourceContext(sourceFolderPath: string): SourceContext | null;