@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/build/runtime-runs.js

@@ -5,12 +5,15 @@ import { stageExecutionWorkspaceLogPaths, writeStageExecutionWorkspaceManifest,
 import { ExecutionStageLedgerSchema, } from "./lib/schema.js";
 import { supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
 import { getBuildPlanStageDefinition, getBuildPlanStagePosition, getBuildPlanStages, } from "../../build-plans/package/build-plan-definitions.js";
-import { archivedStageContractPath, eventLogPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+import { InterfIdPattern, } from "../../contracts/lib/schema.js";
+import { contextGraphRuntimeArchivedStageContractPath, contextGraphExecutionStageLedgerHistoryPath, contextGraphExecutionStageLedgerPath, contextGraphRuntimeStageContractPath, } from "./context-graph-paths.js";
+import { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
 import { warnInterf } from "../../contracts/utils/logger.js";
 import { appendJsonlAtomic, writeFileAtomic, writeJsonAtomic } from "./atomic-fs.js";
-import { loadState, saveState, } from "./state.js";
+import { initContextGraphState, loadState, saveState, } from "./state.js";
+import { projectSessionFinishedFromLedger, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
 export function loadExecutionStageLedger(dirPath) {
-    const path = runPath(dirPath);
+    const path = contextGraphExecutionStageLedgerPath(dirPath);
     if (!existsSync(path))
         return null;
     try {
@@ -27,16 +30,16 @@ export function loadExecutionStageLedger(dirPath) {
     }
 }
 export function saveExecutionStageLedger(dirPath, run) {
-    writeJsonAtomic(runPath(dirPath), run);
+    writeJsonAtomic(contextGraphExecutionStageLedgerPath(dirPath), run);
 }
 export function writeStageContract(dirPath, contract) {
-    mkdirSync(dirname(stageContractPath(dirPath)), { recursive: true });
-    const path = stageContractPath(dirPath);
+    mkdirSync(dirname(contextGraphRuntimeStageContractPath(dirPath)), { recursive: true });
+    const path = contextGraphRuntimeStageContractPath(dirPath);
     writeJsonAtomic(path, contract);
     return path;
 }
 function writeArchivedStageContract(dirPath, runId, contract) {
-    const path = archivedStageContractPath(dirPath, runId);
+    const path = contextGraphRuntimeArchivedStageContractPath(dirPath, runId);
     writeJsonAtomic(path, contract);
     return path;
 }
@@ -51,10 +54,28 @@ export async function runExecutorStage(options) {
     }
     const prompt = options.buildPrompt(startedRun.activeContractPath);
     writeExecutionStageLedgerPrompt(startedRun.logPaths.promptLogPath, prompt);
+    writeStageExecutionSessionStartedFromLedger({
+        contextGraphPath: options.contextGraphPath,
+        run: startedRun.run,
+        contract: startedRun.contract,
+        buildRunId: options.buildRunId ?? null,
+        shellRoot: options.executionPath ?? null,
+        promptPath: startedRun.logPaths.promptLogPath,
+        eventStreamPath: startedRun.logPaths.eventLogPath,
+        statusPath: startedRun.logPaths.statusLogPath,
+    });
     const executionPath = options.executionPath ?? options.contextGraphPath;
+    // Reasoning lands in the shell's runtime/ dir so it sits beside the other
+    // inspectable runtime files, is referenced by the session's reasoning_path,
+    // and is preserved when the shell is frozen. Without a shell there is nowhere
+    // durable to keep it, so reasoning capture is skipped (null).
+    const reasoningLogPath = options.executionPath
+        ? join(options.executionPath, "runtime", "agent-reasoning.jsonl")
+        : null;
     const code = await options.executor.execute(executionPath, prompt, {
         eventLogPath: startedRun.logPaths.eventLogPath,
         statusLogPath: startedRun.logPaths.statusLogPath,
+        reasoningLogPath,
         completionCheck: options.completionCheck,
         onStatus: options.onStatus,
     });
@@ -99,6 +120,27 @@ function updateContextGraphStageTerminalState(dirPath, run, options) {
         },
     });
 }
+function updateContextGraphStageStartedState(dirPath, run) {
+    const state = loadState(dirPath) ?? initContextGraphState();
+    const currentStage = state.stages?.[run.stage] ?? {};
+    saveState(dirPath, {
+        ...state,
+        stages: {
+            ...(state.stages ?? {}),
+            [run.stage]: {
+                ...currentStage,
+                contract_type: run.contract_type,
+                status: "running",
+                started_at: run.started_at,
+                finished_at: null,
+                counts: { ...run.counts },
+                artifacts: [...run.output_artifacts],
+                summary: run.summary,
+                run_id: run.run_id,
+            },
+        },
+    });
+}
 export function markExecutionStageLedgerFailedAfterValidation(dirPath, summary) {
     const current = loadExecutionStageLedger(dirPath);
     if (!current)
@@ -119,7 +161,8 @@ export function markExecutionStageLedgerFailedAfterValidation(dirPath, summary)
         summary,
         finishedAt,
     });
-    appendJsonlAtomic(runHistoryPath(dirPath), next);
+    projectSessionFinishedFromLedger(dirPath, next);
+    appendJsonlAtomic(contextGraphExecutionStageLedgerHistoryPath(dirPath), next);
     return next;
 }
 export function markExecutionStageLedgerSucceededAfterValidation(dirPath, summary) {
@@ -142,7 +185,8 @@ export function markExecutionStageLedgerSucceededAfterValidation(dirPath, summar
         summary,
         finishedAt,
     });
-    appendJsonlAtomic(runHistoryPath(dirPath), next);
+    projectSessionFinishedFromLedger(dirPath, next);
+    appendJsonlAtomic(contextGraphExecutionStageLedgerHistoryPath(dirPath), next);
     return next;
 }
 function startExecutionStageLedger(options) {
@@ -151,6 +195,10 @@ function startExecutionStageLedger(options) {
     const buildPlanStages = getBuildPlanStages(options.buildPlan, options.buildPlanSourcePath);
     const stagePosition = getBuildPlanStagePosition(options.buildPlan, options.stage, options.buildPlanSourcePath);
     const stageDefinition = getBuildPlanStageDefinition(options.buildPlan, options.stage, options.buildPlanSourcePath);
+    const project = options.contract.project ?? {
+        id: InterfIdPattern.test(options.contextGraphName) ? options.contextGraphName : "project",
+        intent: null,
+    };
     const contract = {
         kind: "interf-stage-contract",
         version: 1,
@@ -158,6 +206,7 @@ function startExecutionStageLedger(options) {
         run_id: runId,
         target_type: "context-graph",
         target_name: options.contextGraphName,
+        project,
         build_plan: {
             id: options.buildPlan,
             stage_index: stagePosition?.stageIndex ?? null,
@@ -171,6 +220,7 @@ function startExecutionStageLedger(options) {
         instructions: options.contract.instructions,
         counts: options.contract.counts,
         artifacts: options.contract.artifacts,
+        context_checks: options.contract.context_checks,
         policies: options.contract.policies,
     };
     const activeContractPath = writeStageContract(options.contextGraphPath, contract);
@@ -214,6 +264,7 @@ function startExecutionStageLedger(options) {
         error: null,
     };
     const startedRun = beginExecutionStageLedger(options.contextGraphPath, run);
+    updateContextGraphStageStartedState(options.contextGraphPath, startedRun);
     if (options.executionPath) {
         writeStageExecutionWorkspaceManifest({
             contextGraphPath: options.contextGraphPath,
@@ -243,9 +294,10 @@ function finalizeExecutionStageLedger(dirPath, code) {
     if (!current)
         return null;
     const finishedAt = new Date().toISOString();
+    const status = code === 0 ? "succeeded" : "failed";
     const next = {
         ...current,
-        status: code === 0 ? "succeeded" : "failed",
+        status,
         updated_at: finishedAt,
         finished_at: finishedAt,
         exit_code: code,
@@ -255,6 +307,7 @@ function finalizeExecutionStageLedger(dirPath, code) {
             : `${current.stage_label} failed with exit code ${code}.`,
     };
     saveExecutionStageLedger(dirPath, next);
+    projectSessionFinishedFromLedger(dirPath, next);
     return next;
 }
 function writeExecutionStageLedgerPrompt(path, prompt) {

package/dist/packages/runtime/build/runtime-types.d.ts

@@ -1,5 +1,5 @@
 import { type AgentExecutor } from "../agents/lib/executors.js";
-import { type ExecutionStageLedger, type RuntimeStageContract, type RuntimeStageInstructions } from "./lib/schema.js";
+import { type ExecutionStageLedger, type RuntimeProjectContext, type RuntimeStageContract, type RuntimeStageInstructions } from "./lib/schema.js";
 import type { Check, BuildPlanId, RuntimeContractType, RuntimeStage } from "../../contracts/lib/schema.js";
 export type ExecutionStageLedgerStatus = "running" | "succeeded" | "failed";
 export type RuntimeStageContractDraft = Omit<RuntimeStageContract, "kind" | "version" | "generated_at" | "run_id" | "target_type" | "target_name" | "build_plan" | "stage" | "stage_label" | "contract_type" | "executor">;
@@ -10,6 +10,7 @@ export interface RuntimeStageExecutionOptions {
     contextGraphName: string;
     buildPlan: BuildPlanId;
     buildPlanSourcePath?: string;
+    buildRunId?: string | null;
     stage: RuntimeStage;
     stageLabel: string;
     contractType: RuntimeContractType;
@@ -21,6 +22,7 @@ export interface RuntimeStageExecutionOptions {
 }
 export interface RuntimeStageContractOptions {
     contextGraphName: string;
+    project: RuntimeProjectContext;
     stageId: string;
     stageLabel: string;
     counts?: Record<string, number>;
@@ -32,6 +34,7 @@ export interface RuntimeStageContractOptions {
         path: string;
         checks: Check[];
     }>;
+    contextChecks?: RuntimeStageContract["context_checks"];
     buildPlanNotes?: string[];
     localSkillDocs?: string[];
     instructions: RuntimeStageInstructions;

package/dist/packages/runtime/build/runtime.d.ts

@@ -1,6 +1,8 @@
 export type { ExecutionStageLedgerPatch, ExecutionStageLedgerStatus, RuntimeStageContractDraft, RuntimeStageExecutionOptions, RuntimeStageContractOptions, } from "./runtime-types.js";
-export { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+export { contextGraphRuntimeArchivedStageContractPath as archivedStageContractPath, contextGraphRuntimeLogsRoot as logsDirPath, contextGraphExecutionStageLedgerHistoryPath as runHistoryPath, contextGraphExecutionStageLedgerPath as runPath, contextGraphRuntimeStageContractPath as stageContractPath, } from "./context-graph-paths.js";
+export { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
 export { buildStagePrompt } from "./runtime-prompt.js";
 export { buildRuntimeStageContract, } from "./runtime-contracts.js";
 export { reconcileStageEvidence, supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
+export { listStageExecutionSessions, markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
 export { beginExecutionStageLedger, loadExecutionStageLedger, markExecutionStageLedgerFailedAfterValidation, markExecutionStageLedgerSucceededAfterValidation, runExecutorStage, saveExecutionStageLedger, updateExecutionStageLedger, writeStageContract, } from "./runtime-runs.js";

package/dist/packages/runtime/build/runtime.js

@@ -1,5 +1,7 @@
-export { archivedStageContractPath, eventLogPath, logsDirPath, promptLogPath, runHistoryPath, runPath, stageContractPath, statusLogPath, } from "./runtime-paths.js";
+export { contextGraphRuntimeArchivedStageContractPath as archivedStageContractPath, contextGraphRuntimeLogsRoot as logsDirPath, contextGraphExecutionStageLedgerHistoryPath as runHistoryPath, contextGraphExecutionStageLedgerPath as runPath, contextGraphRuntimeStageContractPath as stageContractPath, } from "./context-graph-paths.js";
+export { eventLogPath, promptLogPath, statusLogPath, } from "./runtime-log-paths.js";
 export { buildStagePrompt } from "./runtime-prompt.js";
 export { buildRuntimeStageContract, } from "./runtime-contracts.js";
 export { reconcileStageEvidence, supportsStageEvidenceHarness, writeStageHarnessProjection, } from "./stage-evidence.js";
+export { listStageExecutionSessions, markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, writeStageExecutionSessionStartedFromLedger, } from "./stage-session.js";
 export { beginExecutionStageLedger, loadExecutionStageLedger, markExecutionStageLedgerFailedAfterValidation, markExecutionStageLedgerSucceededAfterValidation, runExecutorStage, saveExecutionStageLedger, updateExecutionStageLedger, writeStageContract, } from "./runtime-runs.js";

package/dist/packages/runtime/build/source-files.js

@@ -14,7 +14,16 @@ function shortHash(value, length = 16) {
         .digest("hex")
         .slice(0, length);
 }
-function normalizeRelativePath(path) {
+/**
+ * Canonicalize ONLY the path separators (`\` -> `/`) so a file's stable hash id
+ * is identical on Windows and POSIX. This is deliberately NOT the canonical
+ * `normalizeLayerPath` (`contracts/lib/context-graph-layer.ts`): it must NOT
+ * strip a leading `./` or a trailing slash, because the resulting string is
+ * stored as `SourceFile.path` and fed verbatim into the file-id hash. Touching
+ * the leading/trailing characters here would change every existing source-file
+ * id. Separators-only is the intended, stable difference.
+ */
+function normalizeSeparatorsForFileId(path) {
     return path.replaceAll("\\", "/");
 }
 /**
@@ -40,7 +49,7 @@ function buildSource(sourcePath) {
     };
 }
 function buildSourceFile(source, sourcePath, relativePath) {
-    const normalizedPath = normalizeRelativePath(relativePath);
+    const normalizedPath = normalizeSeparatorsForFileId(relativePath);
     const absolutePath = resolve(sourcePath, relativePath);
     return {
         id: `file-${shortHash(`${source.id}\0${normalizedPath}`)}`,

package/dist/packages/runtime/build/source-inventory.d.ts

@@ -15,6 +15,7 @@ export declare function runSourceInventory(options: {
     executor: AgentExecutor;
     contextGraphPath: string;
     project: string;
+    projectIntent?: string | null;
     sourceLocator: string;
     buildPlanId: string;
     stageIds: string[];

package/dist/packages/runtime/build/source-inventory.js

@@ -3,9 +3,14 @@ import { join, relative } from "node:path";
 import { SourceManifestSchema, } from "../../contracts/lib/schema.js";
 import { buildRuntimeExecutorInfo } from "../agents/lib/executors.js";
 import { shellEventLogPath, shellPromptLogPath, shellStatusLogPath, } from "../agents/lib/shell-paths.js";
+import { renderClaudeBootstrap, } from "../agents/lib/shell-templates.js";
+import { freezePreservedShell, writeIfChanged, writeNativeSkillCopies, } from "../agents/lib/shell-fs.js";
+import { writeStageExecutionWorkspaceManifest, } from "../agents/lib/shell-workspace.js";
 import { contextGraphRuntimeSourceManifestPath, stageExecutionShellsRoot, } from "./context-graph-paths.js";
-import { loadContextGraphSourceManifest, writeBuildSourceRuntimeFromManifest, } from "./source-manifest.js";
+import { dropFilesystemArtifacts, loadContextGraphSourceManifest, writeBuildSourceRuntimeFromManifest, } from "./source-manifest.js";
+import { writeSourceStageManifest, } from "./stage-manifest.js";
 import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
+import { markStageExecutionSessionsShellPreserved, recordStageExecutionSessionValidationAttempt, writeStageExecutionSessionFinished, writeStageExecutionSessionStarted, } from "./stage-session.js";
 function sourceInventoryShellRoot(contextGraphPath, attempt) {
     return join(stageExecutionShellsRoot(contextGraphPath), `source-inventory-${Date.now().toString(36)}-${attempt}`);
 }
@@ -54,10 +59,13 @@ function sourceInventoryPrompt(options) {
         "You are the Interf Source inventory agent.",
         "Interf does not read or copy the user's Source files. You own Source access through your normal tools.",
         `Project: ${options.project}`,
+        ...(options.projectIntent ? [`Project intent: ${options.projectIntent}`] : []),
         `Source locator: ${options.sourceLocator}`,
         "Read `runtime/source-locator.json` first.",
         "List every Source file you can access. Use paths relative to the Source locator.",
-        "For PDFs, decks, sheets, and other multi-unit files, record page/slide/sheet units when you can.",
+        "Use canonical file kinds only: pdf, document, spreadsheet, presentation, image, text, other. Markdown, txt, and plain-text files must use kind `text`.",
+        "For plain text or markdown files, use an inspectable unit like `{ \"kind\": \"file\", \"index\": 1, \"label\": \"whole file\" }` when useful.",
+        "For PDFs, decks, sheets, and other multi-unit files, record page/slide/sheet/table/image/section units when you can.",
         "Do not copy Source files into this shell.",
         "Write exactly one JSON file at runtime/source-manifest.json.",
         "The JSON must match this shape, with real values replacing the example:",
@@ -67,10 +75,116 @@ function sourceInventoryPrompt(options) {
         "Emit DONE: source inventory complete after runtime/source-manifest.json is written.",
     ].join("\n");
 }
+function renderSourceInventoryAgents(options) {
+    return [
+        `# ${options.project} — Source Inventory Execution Shell`,
+        "",
+        "This is an isolated Interf execution shell for Source inventory.",
+        "It is a replayable stage workspace: prompts, logs, contract, input locator, and output manifest live here.",
+        "",
+        "## Start Here",
+        "",
+        "1. Read `runtime/stage-contract.json` now.",
+        "2. Read `runtime/source-locator.json` now.",
+        "3. Use the local native `interf-stage` skill now.",
+        "4. Write exactly one output: `runtime/source-manifest.json`.",
+        "",
+        "## Boundaries",
+        "",
+        `- Build Plan: \`${options.buildPlanId}\`.`,
+        "- Stage: `source-inventory`.",
+        "- Do not copy Source files into this shell.",
+        "- Source files remain read-only and external to Interf.",
+        "- Record every accessible Source file, inspectable units, and human-readable evidence.",
+        "",
+        "## Goal",
+        "",
+        "- produce a Source Manifest that future stages can use deterministically",
+        "- preserve Source file paths relative to the Source locator",
+        "- stop once `runtime/source-manifest.json` is valid",
+        "",
+    ].join("\n");
+}
+function renderSourceInventorySkill() {
+    return [
+        "---",
+        "name: interf-stage",
+        "description: >",
+        "  Native local execution skill for the Interf Source inventory stage.",
+        "  Use it only inside an automated Source inventory execution shell.",
+        "---",
+        "",
+        "# Interf Source Inventory",
+        "",
+        "Read `runtime/stage-contract.json` and `runtime/source-locator.json` first.",
+        "Inspect the Source through your own tools. Do not copy Source files into the shell.",
+        "Write `runtime/source-manifest.json` with every accessible Source file, Source-relative path, inspectable units, and evidence.",
+        "Emit DONE only after the manifest exists and matches the contract.",
+        "",
+    ].join("\n");
+}
+function writeSourceInventoryShellSurface(options) {
+    const agents = renderSourceInventoryAgents({
+        project: options.project,
+        buildPlanId: options.buildPlanId,
+    });
+    writeIfChanged(join(options.shellRoot, "AGENTS.md"), `${agents.trimEnd()}\n`);
+    writeIfChanged(join(options.shellRoot, "CLAUDE.md"), renderClaudeBootstrap(agents));
+    writeNativeSkillCopies(options.shellRoot, "interf-stage", renderSourceInventorySkill());
+}
 function readShellManifest(shellRoot) {
     const manifestPath = join(shellRoot, "runtime", "source-manifest.json");
     const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
-    return SourceManifestSchema.parse(raw);
+    return SourceManifestSchema.parse(normalizeSourceManifestCandidate(raw));
+}
+function normalizeSourceManifestCandidate(value) {
+    if (!value || typeof value !== "object" || !Array.isArray(value.files)) {
+        return value;
+    }
+    return {
+        ...value,
+        files: (value.files).map((file) => {
+            if (!file || typeof file !== "object")
+                return file;
+            const candidate = file;
+            return {
+                ...candidate,
+                kind: normalizeSourceFileKind(candidate.kind, candidate.path),
+            };
+        }),
+    };
+}
+function normalizeSourceFileKind(kind, path) {
+    const raw = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+    const normalized = raw.replaceAll("_", "-").replace(/\s+/g, "-");
+    if (["pdf", "document", "spreadsheet", "presentation", "image", "text", "other"].includes(normalized)) {
+        return normalized;
+    }
+    if (["markdown", "md", "txt", "plain-text", "text-file", "source-text"].includes(normalized))
+        return "text";
+    if (["doc", "docx", "word"].includes(normalized))
+        return "document";
+    if (["sheet", "sheets", "table", "csv", "tsv", "xls", "xlsx"].includes(normalized))
+        return "spreadsheet";
+    if (["deck", "slide", "slides", "ppt", "pptx"].includes(normalized))
+        return "presentation";
+    if (["jpg", "jpeg", "png", "gif", "webp", "svg"].includes(normalized))
+        return "image";
+    if (typeof path === "string") {
+        if (/\.(md|markdown|txt|text)$/i.test(path))
+            return "text";
+        if (/\.(doc|docx|rtf|odt)$/i.test(path))
+            return "document";
+        if (/\.(csv|tsv|xls|xlsx)$/i.test(path))
+            return "spreadsheet";
+        if (/\.(ppt|pptx|odp)$/i.test(path))
+            return "presentation";
+        if (/\.(jpe?g|png|gif|webp|svg)$/i.test(path))
+            return "image";
+        if (/\.pdf$/i.test(path))
+            return "pdf";
+    }
+    return kind === undefined ? undefined : "other";
 }
 function contextGraphRelativePath(contextGraphPath, filePath) {
     return relative(contextGraphPath, filePath).replaceAll("\\", "/");
@@ -154,11 +268,18 @@ export async function runSourceInventory(options) {
             sourceManifest: existing,
             runId: options.runId ?? existing.run_id,
         });
+        const existingContent = dropFilesystemArtifacts(existing);
+        writeSourceStageManifest({
+            contextGraphPath: options.contextGraphPath,
+            buildPlanId: options.buildPlanId,
+            sourceManifest: existingContent,
+            runId: options.runId ?? existingContent.run_id,
+        });
         return {
             ok: true,
             code: 0,
-            summary: `Source Manifest already exists with ${existing.source_total} file(s).`,
-            manifest: existing,
+            summary: `Source Manifest already exists with ${existingContent.source_total} file(s).`,
+            manifest: existingContent,
         };
     }
     const maxAttempts = Math.max(1, Math.min(5, Math.trunc(options.maxAttempts ?? 2)));
@@ -168,11 +289,17 @@ export async function runSourceInventory(options) {
         const inventoryRunId = `${options.runId ?? "source-inventory"}-source-inventory-${attempt}`;
         mkdirSync(join(shellRoot, "runtime"), { recursive: true });
         mkdirSync(join(shellRoot, "logs"), { recursive: true });
+        writeSourceInventoryShellSurface({
+            shellRoot,
+            project: options.project,
+            buildPlanId: options.buildPlanId,
+        });
         writeFileSync(join(shellRoot, "runtime", "source-locator.json"), `${JSON.stringify({
             kind: "interf-source-locator",
             version: 1,
             generated_at: new Date().toISOString(),
             project: options.project,
+            project_intent: options.projectIntent ?? null,
             source: {
                 kind: "local-folder",
                 locator: options.sourceLocator,
@@ -185,6 +312,7 @@ export async function runSourceInventory(options) {
             generated_at: new Date().toISOString(),
             run_id: options.runId ?? null,
             project: options.project,
+            project_intent: options.projectIntent ?? null,
             source: {
                 kind: "local-folder",
                 locator: options.sourceLocator,
@@ -200,8 +328,17 @@ export async function runSourceInventory(options) {
                 "manifest paths are relative to the Source locator",
             ],
         }, null, 2)}\n`);
+        writeFileSync(join(shellRoot, "runtime", "paths.json"), `${JSON.stringify({
+            kind: "interf-execution-shell",
+            version: 1,
+            build_plan: options.buildPlanId,
+            stage: "source-inventory",
+            reads: [],
+            writes: [],
+        }, null, 2)}\n`);
         const prompt = sourceInventoryPrompt({
             project: options.project,
+            projectIntent: options.projectIntent ?? null,
             sourceLocator: options.sourceLocator,
             runId: options.runId ?? null,
             executor: options.executor,
@@ -216,14 +353,74 @@ export async function runSourceInventory(options) {
         writeFileSync(shellPromptLogPath(shellRoot, inventoryRunId), prompt);
         writeFileSync(shellEventLogPath(shellRoot, inventoryRunId), "");
         writeFileSync(shellStatusLogPath(shellRoot, inventoryRunId), "");
+        writeStageExecutionWorkspaceManifest({
+            contextGraphPath: options.contextGraphPath,
+            shellRoot,
+            buildPlanId: options.buildPlanId,
+            stage: {
+                id: "source-inventory",
+                label: "Source Inventory",
+                contractType: "source-inventory",
+            },
+            logPaths: {
+                promptLogPath: shellPromptLogPath(shellRoot, inventoryRunId),
+                eventLogPath: shellEventLogPath(shellRoot, inventoryRunId),
+                statusLogPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            },
+        });
+        writeStageExecutionSessionStarted({
+            contextGraphPath: options.contextGraphPath,
+            jobType: "source-inventory",
+            project: options.project,
+            projectIntent: options.projectIntent ?? null,
+            buildPlanId: options.buildPlanId,
+            buildRunId: options.runId ?? null,
+            stageId: "source-inventory",
+            stageLabel: "Source Inventory",
+            contractType: "source-inventory",
+            stageRunId: inventoryRunId,
+            attempt,
+            executor: options.executor,
+            shellRoot,
+            contractPath: join(shellRoot, "runtime", "stage-contract.json"),
+            promptPath: shellPromptLogPath(shellRoot, inventoryRunId),
+            eventStreamPath: shellEventLogPath(shellRoot, inventoryRunId),
+            statusPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            summary: "Collecting Source Manifest.",
+        });
         await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.started", undefined, logs);
         const code = await options.executor.execute(shellRoot, prompt, {
             eventLogPath: shellEventLogPath(shellRoot, inventoryRunId),
             statusLogPath: shellStatusLogPath(shellRoot, inventoryRunId),
+            // Tee reasoning to the shell's runtime/ dir, the same convention the
+            // shared stage path uses (runtime-runs.ts). The session reader resolves
+            // reasoning_path to this file only when it exists, so a scan that emits
+            // no reasoning leaves it null. This makes the source-inventory session as
+            // legible as every other agent job (policy rule 6) without re-routing it
+            // through the shared stage path.
+            reasoningLogPath: join(shellRoot, "runtime", "agent-reasoning.jsonl"),
             completionCheck: () => existsSync(join(shellRoot, "runtime", "source-manifest.json")),
         });
         if (code !== 0) {
             feedback = `source inventory executor exited with code ${code}`;
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "failed",
+                summary: feedback,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "failed",
+                summary: feedback,
+                error: feedback,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
             continue;
         }
         try {
@@ -234,10 +431,10 @@ export async function runSourceInventory(options) {
                 executor: options.executor,
                 attempt,
             });
-            const written = SourceManifestSchema.parse({
+            const written = dropFilesystemArtifacts(SourceManifestSchema.parse({
                 ...manifest,
                 run_id: options.runId ?? manifest.run_id,
-            });
+            }));
             writeBuildSourceRuntimeFromManifest({
                 contextGraphPath: options.contextGraphPath,
                 buildPlanId: options.buildPlanId,
@@ -247,7 +444,31 @@ export async function runSourceInventory(options) {
                 sourceManifest: written,
                 runId: options.runId ?? null,
             });
+            writeSourceStageManifest({
+                contextGraphPath: options.contextGraphPath,
+                buildPlanId: options.buildPlanId,
+                sourceManifest: written,
+                runId: options.runId ?? null,
+            });
             await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.passed", `Source Manifest captured ${written.source_total} file(s).`);
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "succeeded",
+                summary: `Source Manifest captured ${written.source_total} file(s).`,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "succeeded",
+                summary: `Source Manifest captured ${written.source_total} file(s).`,
+                error: null,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
             return {
                 ok: true,
                 code: 0,
@@ -258,6 +479,24 @@ export async function runSourceInventory(options) {
         }
         catch (error) {
             feedback = error instanceof Error ? error.message : String(error);
+            recordStageExecutionSessionValidationAttempt({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                attempt,
+                status: "failed",
+                summary: feedback,
+            });
+            writeStageExecutionSessionFinished({
+                contextGraphPath: options.contextGraphPath,
+                stageId: "source-inventory",
+                stageRunId: inventoryRunId,
+                status: "failed",
+                summary: feedback,
+                error: feedback,
+            });
+            freezePreservedShell(shellRoot, "stage-execution");
+            markStageExecutionSessionsShellPreserved({ contextGraphPath: options.contextGraphPath, shellRoot });
         }
     }
     await emitInventoryEvent(options.events, options.runId ?? undefined, "stage.failed", feedback ?? "Source inventory failed.");

package/dist/packages/runtime/build/source-manifest.d.ts

@@ -7,6 +7,17 @@ export declare function materializeStageSourceSlice(options: {
     stageInputs: StageInputs;
 }): StageInputs;
 export declare function buildShellSourceState(sourceState: SourceState, stageInputs: StageInputs): SourceState;
+/**
+ * Drop OS-generated filesystem junk (`.DS_Store`, AppleDouble forks, `Thumbs.db`,
+ * etc.) from the Source Manifest before it is materialized into runtime coverage
+ * inputs. These are not Source content, so they must never become required
+ * `expected` inputs — otherwise a Source folder shows "not ready" purely because
+ * Finder/Explorer left a sidecar behind. Matched by filename only (provable),
+ * never by an agent's `not-relevant` label, so a genuinely skipped content file
+ * still counts toward readiness. `source_total` is recomputed to stay equal to
+ * the filtered file count.
+ */
+export declare function dropFilesystemArtifacts(manifest: SourceManifest): SourceManifest;
 export declare function sourceManifestToSourceFiles(manifest: SourceManifest): SourceFiles;
 export declare function sourceManifestToSourceState(manifest: SourceManifest): SourceState;
 /**