@interf/compiler 0.33.0 → 0.50.0

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

@@ -16,13 +16,11 @@ import { BuildRunCreateRequestSchema, BuildRunResourceSchema, LocalRunHandlerRes
 import { uniqueArtifacts } from "./run-observability.js";
 import { requireSelectedBuildPlan } from "./runtime-proposal-helpers.js";
 import { readinessUpdatedEvent } from "./runtime-verify-runs.js";
+import { isTerminalStatus } from "./runtime-status.js";
 /** TTL for `POST .../build-runs` idempotency-key dedupe entries. */
 const IDEMPOTENCY_TTL_MS = 60 * 60 * 1000;
 /** Idempotency cache size at which to schedule an opportunistic prune. */
 const IDEMPOTENCY_PRUNE_THRESHOLD = 64;
-function isTerminalBuildRunStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
 function countsFromContextGraphState(state, contextGraphPath) {
     const counts = {};
     const sourceManifest = loadContextGraphSourceManifest(contextGraphPath);
@@ -60,9 +58,7 @@ export function listBuildRuns(runtime, projectDataDir) {
         .flatMap((project) => listBuildRunsForProject(runtime, projectDataDir, project.name))).map((run) => BuildRunResourceSchema.parse({ run }));
 }
 export function listBuildRunsForProject(runtime, projectDataDir, projectName) {
-    return runtime.buildRunCache.get(projectDataDir, projectName, () => {
-        return byCreatedAtDesc(readBuildRunRecordsForProject(projectDataDir, projectName)).map((run) => hydrateBuildRunFromRuntime(runtime, projectDataDir, run));
-    }, (run) => run.run_id);
+    return runtime.buildRunCache.get(projectDataDir, projectName, () => byCreatedAtDesc(readBuildRunRecordsForProject(projectDataDir, projectName)), (run) => run.run_id);
 }
 export function getBuildRun(runtime, projectDataDir, runId) {
     // Fast path: if the runId was seen during a recent listing, look up
@@ -143,7 +139,7 @@ export async function createBuildRun(runtime, projectDataDir, requestValue) {
         events: [],
         context_checks: buildPlanContextChecks({
             brief: buildPlan.brief ?? null,
-            artifacts: buildPlan.contextInterface?.artifacts ?? buildPlan.schema?.artifacts ?? [],
+            artifacts: buildPlan.contextInterface?.artifacts ?? [],
         }),
     });
     writeBuildRun(runtime, projectDataDir, run);
@@ -198,7 +194,7 @@ export function cancelBuildRun(runtime, runId) {
     handle.cancelled = true;
     handle.cancelledAt = cancelledAt;
     const current = readBuildRun(handle.projectDataDir, runId);
-    if (current && !isTerminalBuildRunStatus(current.status)) {
+    if (current && !isTerminalStatus(current.status)) {
         writeBuildRun(runtime, handle.projectDataDir, applyEventToBuildRun(current, {
             type: "run.cancelled",
             event_id: createRunEventId("event"),
@@ -352,12 +348,6 @@ async function runBuildInBackground(runtime, projectDataDir, request, context) {
 export function readBuildRun(projectDataDir, runId) {
     return readBuildRunAt(projectBuildRunPath(projectDataDir, runId));
 }
-function hydrateBuildRunFromRuntime(runtime, projectDataDir, run) {
-    if (!isTerminalBuildRunStatus(run.status))
-        return run;
-    refreshBuildRunFromRuntime(runtime, projectDataDir, run.context_graph_path, run.run_id);
-    return readBuildRun(projectDataDir, run.run_id) ?? run;
-}
 export function finalizeInterruptedBuildRuns(runtime, projectDataDir) {
     let projects;
     try {
@@ -368,7 +358,7 @@ export function finalizeInterruptedBuildRuns(runtime, projectDataDir) {
     }
     for (const project of projects) {
         for (const run of readBuildRunRecordsForProject(projectDataDir, project.name)) {
-            if (isTerminalBuildRunStatus(run.status) || runtime.activeBuildRuns.has(run.run_id))
+            if (isTerminalStatus(run.status) || runtime.activeBuildRuns.has(run.run_id))
                 continue;
             const timestamp = createRunEventTimestamp();
             const interruptedRun = {
@@ -438,6 +428,9 @@ export function writeBuildRun(runtime, projectDataDir, run) {
     // and the simpler model avoids fan-out bugs.
     runtime.buildRunCache.invalidateProject(projectDataDir, run.project);
     runtime.readinessCache.invalidateProject(projectDataDir, run.project);
+    // The Context Graph resource embeds the joined readiness verdict, so bust it
+    // whenever a Build run is written (build completion, refresh, cancel).
+    runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
 }
 async function recordBuildRunEvent(runtime, projectDataDir, contextGraphPath, runId, event) {
     const current = readBuildRun(projectDataDir, runId);
@@ -510,7 +503,7 @@ function refreshBuildRunFromRuntime(runtime, projectDataDir, contextGraphPath, r
         next.context_checks = projectContextChecksForRun({
             contextChecks: buildPlanContextChecks({
                 brief: buildPlan.brief ?? null,
-                artifacts: buildPlan.contextInterface?.artifacts ?? buildPlan.schema?.artifacts ?? [],
+                artifacts: buildPlan.contextInterface?.artifacts ?? [],
             }),
             artifactStatuses: next.artifacts,
         });

package/dist/packages/runtime/runtime-caches.d.ts

@@ -89,3 +89,29 @@ export declare class ProjectSourceStateCache<TState> {
     invalidateProject(projectId: string): void;
     invalidateAll(): void;
 }
+/**
+ * Per-Build-run Context Graph resource cache.
+ *
+ * A succeeded Build's Context Graph is immutable: its on-disk folder
+ * (`graph-manifest.json`, source manifest, stage sessions, semantic graph) is
+ * frozen once the run reaches `succeeded`. Rebuilding the full
+ * `ContextGraphResource` — readiness join, semantic graph, build evidence,
+ * validation — on every read is the dominant cost of opening a built Project.
+ *
+ * The cache keys by `(projectDataDir, runId, manifestMtimeMs)`:
+ *  - `runId` scopes a single Build's output.
+ *  - `manifestMtimeMs` is the mtime of the Build's
+ *    `.interf/runtime/graph-manifest.json`. It busts the entry if the graph is
+ *    rebuilt or edited in place; a fresh Build produces a fresh `runId`, so
+ *    those never collide either.
+ *
+ * Entries without a readable manifest mtime (mtime 0) are not cached — that
+ * only happens for an in-flight or malformed Build, where the resource is
+ * still changing and must be recomputed.
+ */
+export declare class ContextGraphResourceCache<TResource> {
+    private byKey;
+    get(projectDataDir: string, runId: string, manifestPath: string, compute: () => TResource): TResource;
+    invalidateProject(projectDataDir: string): void;
+    invalidateAll(): void;
+}

package/dist/packages/runtime/runtime-caches.js

@@ -217,3 +217,50 @@ export class ProjectSourceStateCache {
         this.byProjectId.clear();
     }
 }
+/**
+ * Per-Build-run Context Graph resource cache.
+ *
+ * A succeeded Build's Context Graph is immutable: its on-disk folder
+ * (`graph-manifest.json`, source manifest, stage sessions, semantic graph) is
+ * frozen once the run reaches `succeeded`. Rebuilding the full
+ * `ContextGraphResource` — readiness join, semantic graph, build evidence,
+ * validation — on every read is the dominant cost of opening a built Project.
+ *
+ * The cache keys by `(projectDataDir, runId, manifestMtimeMs)`:
+ *  - `runId` scopes a single Build's output.
+ *  - `manifestMtimeMs` is the mtime of the Build's
+ *    `.interf/runtime/graph-manifest.json`. It busts the entry if the graph is
+ *    rebuilt or edited in place; a fresh Build produces a fresh `runId`, so
+ *    those never collide either.
+ *
+ * Entries without a readable manifest mtime (mtime 0) are not cached — that
+ * only happens for an in-flight or malformed Build, where the resource is
+ * still changing and must be recomputed.
+ */
+export class ContextGraphResourceCache {
+    byKey = new Map();
+    get(projectDataDir, runId, manifestPath, compute) {
+        const mtimeMs = safeStat(manifestPath)?.mtimeMs ?? 0;
+        // mtime 0 means the manifest is missing/unreadable — the graph is not yet
+        // a frozen, succeeded output, so recompute every time without caching.
+        if (mtimeMs === 0)
+            return compute();
+        const cacheKey = `${resolve(projectDataDir)}${runId}`;
+        const entry = this.byKey.get(cacheKey);
+        if (entry && entry.mtimeMs === mtimeMs)
+            return entry.value;
+        const value = compute();
+        this.byKey.set(cacheKey, { mtimeMs, value });
+        return value;
+    }
+    invalidateProject(projectDataDir) {
+        const prefix = `${resolve(projectDataDir)}`;
+        for (const key of this.byKey.keys()) {
+            if (key.startsWith(prefix))
+                this.byKey.delete(key);
+        }
+    }
+    invalidateAll() {
+        this.byKey.clear();
+    }
+}

package/dist/packages/runtime/runtime-jobs.js

@@ -7,10 +7,8 @@ import { createRunId } from "./runtime-resource-builders.js";
 import { upsertProjectConfig, findProjectConfig, loadSourceFolderConfig, writeBenchmarkSpecsForProject, } from "../projects/source-config.js";
 import { BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, } from "./schemas/index.js";
 import { artifactRequirementsForPlanAuthoring, requestedArtifactsForPlanAuthoring, } from "./plan-artifact-contract.js";
+import { isTerminalStatus } from "./runtime-status.js";
 const INTERRUPTED_JOB_RUN_MESSAGE = "Job interrupted because the local service stopped before the job reached a terminal state.";
-function isTerminalJobStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
 export function listJobs(projectDataDir) {
     return byCreatedAtDesc(listJsonFiles(localJobsRoot(projectDataDir))
         .map(readLocalJobRunAt)
@@ -62,7 +60,7 @@ export function appendJobRunEvent(runtime, projectDataDir, runId, requestValue)
     const current = getJob(projectDataDir, runId);
     if (!current)
         return null;
-    if (isTerminalJobStatus(current.status))
+    if (isTerminalStatus(current.status))
         return current;
     const event = {
         type: request.type,
@@ -349,6 +347,7 @@ async function runBuildPlanAuthoringInBackgroundInner(runtime, projectDataDir, r
                 runtime.readinessCache.invalidateProject(projectDataDir, selected.name);
                 runtime.buildRunCache.invalidateProject(projectDataDir, selected.name);
                 runtime.verifyRunCache.invalidateProject(projectDataDir, selected.name);
+                runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
                 runtime.buildPlanListingCache.invalidate(projectDataDir);
                 selectedProject = selected.name;
             }
@@ -418,13 +417,14 @@ export function writeJobRun(runtime, projectDataDir, run) {
     if (run.project) {
         // Some job runs (benchmark-question drafts) flip readiness state.
         runtime.readinessCache.invalidateProject(projectDataDir, run.project);
+        runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
     }
 }
 export function setJobRunResult(runtime, projectDataDir, runId, result) {
     const current = getJob(projectDataDir, runId);
     if (!current)
         return;
-    if (isTerminalJobStatus(current.status))
+    if (isTerminalStatus(current.status))
         return;
     const normalizedResult = result && typeof result === "object" && !Array.isArray(result)
         ? result
@@ -436,7 +436,7 @@ export function setJobRunResult(runtime, projectDataDir, runId, result) {
 }
 export function finalizeInterruptedJobRuns(runtime, projectDataDir) {
     for (const run of listJobs(projectDataDir)) {
-        if (isTerminalJobStatus(run.status) || runtime.activeJobRuns.has(run.run_id))
+        if (isTerminalStatus(run.status) || runtime.activeJobRuns.has(run.run_id))
             continue;
         const timestamp = createRunEventTimestamp();
         const interruptedRun = LocalJobRunResourceSchema.parse({

package/dist/packages/runtime/runtime-project-mutations.js

@@ -23,6 +23,7 @@ export function applyReset(runtime, projectDataDir, requestValue) {
     runtime.buildRunCache.invalidateProject(projectDataDir, request.project);
     runtime.verifyRunCache.invalidateProject(projectDataDir, request.project);
     runtime.readinessCache.invalidateProject(projectDataDir, request.project);
+    runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
     return ResetResultSchema.parse({
         kind: "interf-reset-result",
         version: 1,

package/dist/packages/runtime/runtime-project-reads.d.ts

@@ -1,5 +1,6 @@
 import { type Readiness } from "../contracts/lib/schema.js";
-import { type ProjectResource, type SourceFileResource, type ContextGraphResource } from "./schemas/index.js";
+import { type ContextGraphHandoff } from "../contracts/lib/project-schema.js";
+import { type ProjectResource, type SourceFileResource, type ContextGraphResource, type StageExecutionSession } from "./schemas/index.js";
 import type { ProjectConfig } from "../projects/lib/schema.js";
 import type { LocalServiceRuntime } from "./runtime.js";
 export declare function listProjects(runtime: LocalServiceRuntime, projectDataDir: string): ProjectResource[];
@@ -13,3 +14,5 @@ export declare function listSourceFiles(runtime: LocalServiceRuntime, projectDat
 export declare function listContextGraphs(runtime: LocalServiceRuntime, projectDataDir: string, projectName?: string | null): ContextGraphResource[];
 export declare function getContextGraph(runtime: LocalServiceRuntime, projectDataDir: string, graphId: string): ContextGraphResource | null;
 export declare function getLatestContextGraph(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): ContextGraphResource | null;
+export declare function listLatestContextGraphStageSessions(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): StageExecutionSession[];
+export declare function getContextGraphHandoff(runtime: LocalServiceRuntime, projectDataDir: string, projectName: string): ContextGraphHandoff | null;

package/dist/packages/runtime/runtime-project-reads.js

@@ -1,14 +1,21 @@
-import { existsSync } from "node:fs";
-import { asProjectDataDir, projectConfigPath, } from "../contracts/lib/project-paths.js";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { asProjectDataDir, projectConfigPath, projectRunContextGraphPath, } from "../contracts/lib/project-paths.js";
+import { layerForPath } from "../contracts/lib/context-graph-layer.js";
 import { buildPlanIdForProjectConfig, buildTestSpecFromSourceFolderConfig, fingerprintSavedBenchmarkSpec, findProjectConfig, listProjectConfigs, loadSourceFolderConfig, resolveProjectSourceBindingPath, } from "../projects/source-config.js";
-import { ReadinessSchema, } from "../contracts/lib/schema.js";
+import { isInterfRelativePath, ReadinessSchema, } from "../contracts/lib/schema.js";
+import { ContextGraphHandoffSchema, } from "../contracts/lib/project-schema.js";
 import { readInterfConfig, } from "../projects/interf.js";
 import { loadContextGraphSourceManifest, } from "./build/source-manifest.js";
-import { buildProjectResource, readinessStateToProjectReadiness, readinessSummaryForStatus, readinessTargetResult, } from "./runtime-resource-builders.js";
+import { loadGraphManifest, } from "./build/stage-manifest.js";
+import { contextGraphRuntimeGraphManifestPath, } from "./build/context-graph-paths.js";
+import { listStageExecutionSessions, } from "./build/stage-session.js";
+import { buildProjectResource, readinessSummaryForStatus, readinessTargetResult, } from "./runtime-resource-builders.js";
 import { aggregateArtifactVerdict, } from "./build/artifact-status.js";
 import { buildBuildEvidence, } from "./build/build-evidence.js";
+import { buildContextGraphSemanticGraph, } from "./context-graph-semantic-graph.js";
 import { validateContextGraph } from "./build/validate.js";
-import { SourceFileResourceSchema, ContextGraphResourceSchema, } from "./schemas/index.js";
+import { SourceFileResourceSchema, ContextGraphResourceSchema, StageExecutionSessionSchema, } from "./schemas/index.js";
 import { uniqueArtifacts } from "./run-observability.js";
 import { listBuildRunsForProject, } from "./runtime-build-runs.js";
 import { readExecutionStageLedgerHistory } from "./runtime-persistence.js";
@@ -17,6 +24,18 @@ import { listContextInterfaceArtifacts } from "../build-plans/package/context-in
 import { latestTopLevelVerifyRun, listVerifyRunsForProject, readLatestBenchmarkRun, } from "./runtime-verify-runs.js";
 export function listProjects(runtime, projectDataDir) {
     const config = loadSourceFolderConfig(projectDataDir);
+    // Per-project config file mtime is a migration-free "last touched" signal —
+    // each Project owns its `~/.interf/projects/<id>/interf.json`. Clients sort
+    // the Projects list newest-first by this so a just-created Project lands on
+    // top instead of buried alphabetically.
+    const configPath = projectConfigPath(asProjectDataDir(projectDataDir));
+    let updatedAt = null;
+    try {
+        updatedAt = statSync(configPath).mtime.toISOString();
+    }
+    catch {
+        updatedAt = null;
+    }
     return listProjectConfigs(config).map((project) => {
         const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
         const verifyRuns = listVerifyRunsForProject(runtime, projectDataDir, project.name);
@@ -27,21 +46,20 @@ export function listProjects(runtime, projectDataDir) {
             latestBuildRunId: buildRuns[0]?.run_id ?? null,
             latestContextGraphBuildRunId: contextGraphRun?.run_id ?? null,
             latestTestRunId: latestVerifyRun?.run_id ?? null,
-        }, resolveProjectSourceBindingPath(projectDataDir, project, config), projectConfigPath(asProjectDataDir(projectDataDir)), 
+        }, resolveProjectSourceBindingPath(projectDataDir, project, config), configPath, 
         // Surface per-Artifact status from the latest Build run so the UI can
         // render Artifact rows on the Project page without a separate fetch.
-        contextGraphRun?.artifacts ?? []);
+        contextGraphRun?.artifacts ?? [], updatedAt);
     });
 }
 export function getProject(runtime, projectDataDir, projectName) {
     return listProjects(runtime, projectDataDir).find((project) => project.name === projectName) ?? null;
 }
 export function listProjectReadiness(runtime, projectDataDir) {
-    return listReadiness(runtime, projectDataDir).map(readinessStateToProjectReadiness);
+    return listReadiness(runtime, projectDataDir);
 }
 export function getProjectReadiness(runtime, projectDataDir, projectName) {
-    const readiness = getReadiness(runtime, projectDataDir, projectName);
-    return readiness ? readinessStateToProjectReadiness(readiness) : null;
+    return getReadiness(runtime, projectDataDir, projectName);
 }
 export function listReadiness(runtime, projectDataDir) {
     const config = loadSourceFolderConfig(projectDataDir);
@@ -60,16 +78,27 @@ function latestContextGraphBuildRun(project, buildRuns) {
         : null;
     return selected ?? buildRuns.find((run) => run.status === "succeeded") ?? null;
 }
+function contextGraphPathForBuildRun(projectDataDir, buildRun) {
+    if (!buildRun)
+        return null;
+    if (existsSync(buildRun.context_graph_path))
+        return buildRun.context_graph_path;
+    const projectOwnedPath = projectRunContextGraphPath(asProjectDataDir(projectDataDir), buildRun.run_id);
+    if (existsSync(projectOwnedPath))
+        return projectOwnedPath;
+    return buildRun.context_graph_path;
+}
 function computeProjectReadinessUncached(runtime, projectDataDir, project) {
     const generatedAt = new Date().toISOString();
     const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
     const buildRun = buildRuns[0] ?? null;
     const contextGraphRun = latestContextGraphBuildRun(project, buildRuns);
-    const contextGraphPath = contextGraphRun?.context_graph_path ?? null;
+    const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, contextGraphRun);
     const contextExists = Boolean(contextGraphPath && existsSync(contextGraphPath));
     const contextGraphValidation = contextGraphPath && contextExists
         ? validateContextGraph(contextGraphPath)
         : null;
+    const graphManifest = contextGraphPath && contextExists ? loadGraphManifest(contextGraphPath) : null;
     const contextReady = Boolean(contextGraphRun && contextGraphValidation?.ok);
     const verifyRun = latestTopLevelVerifyRun(listVerifyRunsForProject(runtime, projectDataDir, project.name));
     const benchmarkRun = readLatestBenchmarkRun(projectDataDir, project.name);
@@ -143,9 +172,45 @@ function computeProjectReadinessUncached(runtime, projectDataDir, project) {
             artifact_path: contextReady ? contextGraphPath : null,
         };
     })();
-    // Drop the tautological "Project is saved" gate — if this readiness object
-    // exists, the Project exists. Keep the Context Graph / Build / Artifact /
-    // benchmark gates in product vocabulary.
+    if (graphManifest && buildRun?.status === "succeeded" && contextReady) {
+        const status = graphManifest.readiness.ready ? "ready" : "not-ready";
+        return ReadinessSchema.parse({
+            kind: "interf-readiness-state",
+            version: 1,
+            generated_at: generatedAt,
+            project: project.name,
+            status,
+            ready: graphManifest.readiness.ready,
+            summary: graphManifest.readiness.summary,
+            context_graph_path: contextGraphPath,
+            latest_build_run_id: buildRun.run_id,
+            latest_benchmark_run_id: verifyRun?.run_id ?? null,
+            build: buildCheck,
+            check_results: {
+                configured: configuredChecks,
+                fingerprint: currentFingerprint,
+                source_files: sourceResult,
+                context_graph: contextResult,
+            },
+            checks: [
+                {
+                    gate: "context-graph",
+                    ok: graphManifest.readiness.ready,
+                    status,
+                    summary: graphManifest.readiness.summary,
+                    artifact_path: contextGraphPath,
+                },
+                buildCheck,
+            ],
+        });
+    }
+    // COMPAT fallback — reached only when no GraphManifest exists yet
+    // (pre-refactor build or build still running). The primary readiness path
+    // is the early return above that reads graphManifest.readiness directly.
+    // Keep these legacy gates so old UIs that consume readiness.checks don't
+    // crash; do not add new gates here. Removal path: once every active Build
+    // produces a GraphManifest, the early return covers all cases and this
+    // fallback can be replaced with a single "not yet built" check.
     const checks = [
         {
             gate: "context-graph",
@@ -164,7 +229,7 @@ function computeProjectReadinessUncached(runtime, projectDataDir, project) {
                 ? "not-configured"
                 : artifactVerdict === "ready" ? "ready" : "not-ready",
             summary: !hasArtifactContract
-                ? "No Artifacts declared by the selected Build Plan."
+                ? "No outputs declared by the selected Build Plan."
                 : artifactVerdict === "ready"
                     ? `${artifactStatuses.length} Artifact${artifactStatuses.length === 1 ? "" : "s"} ready; ${passedArtifactCheckResults.length}/${requiredArtifactCheckResults.length} required diagnostic${requiredArtifactCheckResults.length === 1 ? "" : "s"} passed.`
                     : `${artifactFailures.length} Artifact${artifactFailures.length === 1 ? "" : "s"} not ready.`,
@@ -176,10 +241,10 @@ function computeProjectReadinessUncached(runtime, projectDataDir, project) {
                 ? "not-configured"
                 : contextChecksPassed ? "ready" : "not-ready",
             summary: requiredContextChecks.length === 0
-                ? "No Context Checks declared by the selected Build Plan."
+                ? "No GraphManifest coverage rollup exists for this Build."
                 : contextChecksPassed
-                    ? `${requiredContextChecks.length} required Context Check${requiredContextChecks.length === 1 ? "" : "s"} passed.`
-                    : `${failedContextChecks.length} required Context Check${failedContextChecks.length === 1 ? "" : "s"} not passed.`,
+                    ? `${requiredContextChecks.length} legacy readiness check${requiredContextChecks.length === 1 ? "" : "s"} passed.`
+                    : `${failedContextChecks.length} legacy readiness check${failedContextChecks.length === 1 ? "" : "s"} not passed.`,
         },
         {
             gate: "benchmarks",
@@ -241,6 +306,25 @@ function computeProjectReadinessUncached(runtime, projectDataDir, project) {
         checks,
     });
 }
+/**
+ * Real on-disk size + mtime for a source file, read live from the source
+ * folder. The build manifest only sometimes carries `size_bytes` (older
+ * builds omit it) and never carries an mtime, so reads that trusted the
+ * manifest showed "0 B / -" for files that are really tens of KB to MBs.
+ * Returns null when the file moved or the locator isn't a local path.
+ */
+function statSourceFile(sourceLocator, relativePath) {
+    try {
+        const absolute = join(sourceLocator, relativePath);
+        if (!existsSync(absolute))
+            return null;
+        const info = statSync(absolute);
+        return info.isFile() ? { size: info.size, mtime: info.mtime } : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function listSourceFiles(runtime, projectDataDir, projectName) {
     const config = loadSourceFolderConfig(projectDataDir);
     const projects = listProjectConfigs(config)
@@ -248,22 +332,25 @@ export function listSourceFiles(runtime, projectDataDir, projectName) {
     return projects.flatMap((project) => {
         const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
         const latestRun = latestContextGraphBuildRun(project, buildRuns);
-        const contextGraphPath = latestRun?.context_graph_path ?? null;
+        const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, latestRun);
         const manifest = contextGraphPath ? loadContextGraphSourceManifest(contextGraphPath) : null;
         if (!manifest)
             return [];
-        return manifest.files.map((file) => SourceFileResourceSchema.parse({
-            project: project.name,
-            source_manifest_id: manifest.manifest_id,
-            source_file_id: file.id,
-            path: file.path,
-            locator: file.locator,
-            kind: file.kind,
-            absolute_path: file.locator,
-            size_bytes: file.size_bytes ?? 0,
-            modified_at: null,
-            source_folder_path: manifest.source.locator,
-        }));
+        return manifest.files.map((file) => {
+            const stat = statSourceFile(manifest.source.locator, file.path);
+            return SourceFileResourceSchema.parse({
+                project: project.name,
+                source_manifest_id: manifest.manifest_id,
+                source_file_id: file.id,
+                path: file.path,
+                locator: file.locator,
+                kind: file.kind,
+                absolute_path: file.locator,
+                size_bytes: stat?.size ?? file.size_bytes ?? 0,
+                modified_at: stat ? stat.mtime.toISOString() : null,
+                source_folder_path: manifest.source.locator,
+            });
+        });
     });
 }
 export function listContextGraphs(runtime, projectDataDir, projectName) {
@@ -288,6 +375,7 @@ export function getLatestContextGraph(runtime, projectDataDir, projectName) {
     const buildRunId = contextGraphRun?.run_id ?? null;
     const rows = context.build_evidence?.rows ?? [];
     const passing = rows.filter((row) => !row.issue_state || row.issue_state === "pass").length;
+    const primaryMetricCount = context.primary_metrics.length;
     return ContextGraphResourceSchema.parse({
         ...context,
         kind: "interf-context-graph",
@@ -300,11 +388,36 @@ export function getLatestContextGraph(runtime, projectDataDir, projectName) {
         build_evidence: context.build_evidence
             ? {
                 ...context.build_evidence,
-                summary: `${context.build_evidence.summary} · ${passing}/${rows.length} checks`,
+                summary: primaryMetricCount > 0
+                    ? `${context.build_evidence.summary} · ${primaryMetricCount} primary metric${primaryMetricCount === 1 ? "" : "s"}`
+                    : `${context.build_evidence.summary} · ${passing}/${rows.length} diagnostic rows`,
             }
             : context.build_evidence,
     });
 }
+export function listLatestContextGraphStageSessions(runtime, projectDataDir, projectName) {
+    const project = findProjectConfig(loadSourceFolderConfig(projectDataDir), projectName);
+    if (!project)
+        return [];
+    const latestRun = listBuildRunsForProject(runtime, projectDataDir, project.name)[0] ?? null;
+    const contextGraphPath = contextGraphPathForBuildRun(projectDataDir, latestRun);
+    if (!contextGraphPath || !existsSync(contextGraphPath))
+        return [];
+    return listStageExecutionSessions(contextGraphPath)
+        .map((session) => StageExecutionSessionSchema.parse(session));
+}
+export function getContextGraphHandoff(runtime, projectDataDir, projectName) {
+    const context = getLatestContextGraph(runtime, projectDataDir, projectName);
+    if (!context)
+        return null;
+    return ContextGraphHandoffSchema.parse({
+        kind: "interf-context-graph-handoff",
+        version: 1,
+        entrypoint: context.entrypoint_artifact ?? contextGraphEntrypointHandoff(context.path),
+        artifacts: context.artifact_handoffs,
+        ...(context.portable_handoff ? { portable: context.portable_handoff } : {}),
+    });
+}
 function listProjectContextGraphs(runtime, projectDataDir, project) {
     const buildRuns = listBuildRunsForProject(runtime, projectDataDir, project.name);
     const latest = latestContextGraphBuildRun(project, buildRuns);
@@ -317,8 +430,23 @@ function listProjectContextGraphs(runtime, projectDataDir, project) {
 function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLatest = true) {
     if (!buildRun)
         return null;
-    const path = buildRun.context_graph_path;
+    const path = contextGraphPathForBuildRun(projectDataDir, buildRun);
+    if (!path)
+        return null;
+    // A succeeded Build's Context Graph is immutable: cache the fully-built
+    // resource keyed by run id + graph-manifest mtime. Non-succeeded runs (and
+    // graphs without a readable manifest) fall through to a fresh compute every
+    // time. `isLatest` flips the `is_latest` flag but is otherwise stable per
+    // run within a request, so fold it into the cache key suffix.
+    if (buildRun.status === "succeeded") {
+        return runtime.contextGraphResourceCache.get(projectDataDir, `${buildRun.run_id}:${isLatest ? "latest" : "historical"}`, contextGraphRuntimeGraphManifestPath(path), () => buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest));
+    }
+    return buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest);
+}
+function buildProjectContextGraphResource(runtime, projectDataDir, project, buildRun, path, isLatest) {
     const config = readInterfConfig(path);
+    const sourceManifest = loadContextGraphSourceManifest(path);
+    const graphManifest = loadGraphManifest(path);
     const verifyRuns = listVerifyRunsForProject(runtime, projectDataDir, project.name);
     const latestVerifyRun = latestTopLevelVerifyRun(verifyRuns);
     const readiness = computeProjectReadiness(runtime, projectDataDir, project);
@@ -330,7 +458,7 @@ function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLa
         try {
             const activeBuildPlan = getBuildPlan(buildPlan, { projectDataDir });
             expectedStageCount = activeBuildPlan.stages.length;
-            const contextInterface = activeBuildPlan.contextInterface ?? activeBuildPlan.schema;
+            const contextInterface = activeBuildPlan.contextInterface;
             expectedOutputCount = contextInterface ? listContextInterfaceArtifacts(contextInterface).length : undefined;
         }
         catch {
@@ -338,13 +466,21 @@ function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLa
             expectedOutputCount = undefined;
         }
     }
+    const artifacts = uniqueArtifacts(buildRun.stages.flatMap((stage) => stage.artifacts));
+    const artifactHandoffs = contextGraphArtifactHandoffs(path, artifacts);
+    const createdAt = buildRun.finished_at ?? buildRun.started_at ?? buildRun.created_at ?? readiness.generated_at;
+    const semanticEntrypointPath = artifactHandoffs.find((handoff) => handoff.path?.endsWith(".md"))?.path
+        ?? artifactHandoffs[0]?.path
+        ?? null;
     return ContextGraphResourceSchema.parse({
         kind: "interf-context-graph",
         version: 1,
         graph_id: buildRun.run_id,
         project_id: project.name,
+        intent: project.intent ?? "",
         build_run_id: buildRun.run_id,
-        created_at: buildRun.finished_at ?? buildRun.started_at ?? buildRun.created_at ?? readiness.generated_at,
+        source_manifest_id: sourceManifest?.manifest_id ?? null,
+        created_at: createdAt,
         is_latest: isLatest,
         project: project.name,
         path,
@@ -353,7 +489,27 @@ function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLa
         build_plan: buildPlan,
         latest_build_run_id: buildRun.run_id,
         latest_benchmark_run_id: latestVerifyRun?.run_id ?? null,
-        artifacts: uniqueArtifacts(buildRun.stages.flatMap((stage) => stage.artifacts)),
+        entrypoint_artifact: artifactHandoffs[0] ?? null,
+        artifact_handoffs: artifactHandoffs,
+        portable_handoff: {
+            locator: { kind: "local-path", value: path },
+            instructions: "Start from home.md, then follow links into knowledge/, summaries/, and source refs.",
+        },
+        artifacts,
+        semantic_graph: buildContextGraphSemanticGraph({
+            contextGraphPath: path,
+            projectId: project.name,
+            generatedAt: createdAt,
+            sourceManifest,
+            entrypointPath: semanticEntrypointPath,
+        }),
+        graph_manifest: graphManifest,
+        primary_metrics: graphManifest?.primary_metrics ?? [],
+        stage_summaries: graphManifest?.stages ?? [],
+        entrypoints: graphManifest?.entrypoints ?? [],
+        resources: graphManifest?.resources ?? [],
+        readiness_rollup: graphManifest?.readiness ?? null,
+        stage_sessions: listStageExecutionSessions(path),
         build_evidence: buildBuildEvidence({
             projectId: project.name,
             buildRun,
@@ -362,9 +518,46 @@ function getProjectContextGraph(runtime, projectDataDir, project, buildRun, isLa
             expectedStageCount,
             expectedOutputCount,
             stageEvidence: latestStageEvidenceForContext(path),
+            primaryMetrics: graphManifest?.primary_metrics ?? [],
         }),
     });
 }
+function contextGraphArtifactHandoffs(contextGraphPath, artifacts) {
+    const entrypoint = contextGraphEntrypointHandoff(contextGraphPath);
+    const outputs = artifacts.filter((artifact) => artifact.role === "output" && isInterfRelativePath(artifact.path));
+    const artifactEntrypoints = outputs.filter((artifact) => layerForPath(artifact.path) === "artifacts");
+    const ordered = [
+        ...artifactEntrypoints,
+        ...outputs.filter((artifact) => !artifactEntrypoints.includes(artifact)),
+    ];
+    const seen = new Set([entrypoint.path]);
+    const handoffs = ordered
+        .filter((artifact) => {
+        if (seen.has(artifact.path))
+            return false;
+        seen.add(artifact.path);
+        return true;
+    })
+        .map((artifact) => ({
+        label: artifact.label ?? artifact.path,
+        locator: { kind: "local-path", value: join(contextGraphPath, artifact.path) },
+        path: artifact.path,
+        role: "artifact",
+        ...(artifact.stage_id ? { summary: `Produced by stage ${artifact.stage_id}.` } : {}),
+    }));
+    return [entrypoint, ...handoffs];
+}
+function contextGraphEntrypointHandoff(contextGraphPath) {
+    return {
+        artifact_id: "home",
+        label: "Context Graph home",
+        locator: { kind: "local-path", value: join(contextGraphPath, "home.md") },
+        path: "home.md",
+        artifact_kind: "file",
+        role: "entrypoint",
+        summary: "Primary downstream agent entrypoint. Start here before following links into knowledge/ and summaries/.",
+    };
+}
 function latestStageEvidenceForContext(contextGraphPath) {
     const latestByStage = new Map();
     for (const entry of readExecutionStageLedgerHistory(contextGraphPath)) {