@interf/compiler 0.33.0 → 0.50.0

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

@@ -8,8 +8,8 @@ export * as client from "./client.js";
 export * as runtime from "./runtime.js";
 export * as server from "./service/server.js";
 export * as agentHandoff from "./agent-handoff.js";
-export type { BuildRunCreateRequest, BuildRunResource, BuildRunSummary, InterfMcpHandoff, InterfMcpServer, LocalServiceDiscovery, ContextGraphMapping, ProjectRunLinkage, ProjectResource, ProjectWireShape, BuildPlanResource, LocalJobAgent, LocalJobEvent, LocalJobEventAppendRequest, LocalJobEventType, LocalJobRunCreateRequest, LocalJobRunResource, LocalJobStatus, LocalRunHandlerResult, LocalJobStep, LocalJobType, LocalServiceConfig, LocalServiceError, LocalServiceHealth, LocalExecutorStatus, ActionClientOrigin, ActionProposalApproval, ActionProposalApprovalRequest, ActionProposalCreateRequest, ActionProposalListResponse, ActionProposalPlan, ActionProposalPlanActionType, ActionProposalResource, ActionProposalStatus, ActionProposalType, BuildPlanChangeResult, ProjectChangeResult, ProjectSetupResult, ResetRequest, ResetResult, ContextGraphResource, BuildEvidenceResource, ReadinessResource, SourceFileResource, BenchmarkQuestionDraftCreateRequest, BenchmarkQuestionDraftRuntimeRequest, BenchmarkQuestionDraftResult, VerifyRunCreateRequest, VerifyRunResource, VerifyRunStatus, RunObservabilityListResponse, RunObservabilityResource, RunArtifactsResponse, BuildPlanAuthoringCreateRequest, BuildPlanAuthoringRuntimeRequest, BuildPlanAuthoringResult, ProjectListResponse, BuildPlanListResponse, OpenPathRequest, OpenPathResponse, } from "./schemas/index.js";
-export { BuildRunCreateRequestSchema, BuildRunResourceSchema, BuildRunSummarySchema, InterfMcpHandoffSchema, InterfMcpServerSchema, LocalServiceDiscoverySchema, ContextGraphMappingSchema, ProjectRunLinkageSchema, ProjectResourceSchema, ProjectWireShapeSchema, BuildPlanResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceErrorSchema, LocalServiceHealthSchema, ContextGraphResourceSchema, BuildEvidenceResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, VerifyRunStatusSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, RunArtifactsResponseSchema, LocalExecutorStatusSchema, ActionClientOriginSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalPlanActionTypeSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, ResetRequestSchema, ResetResultSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, ProjectListResponseSchema, BuildPlanListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./schemas/index.js";
+export type { BuildRunCreateRequest, BuildRunResource, BuildRunSummary, InterfMcpHandoff, InterfMcpServer, LocalServiceDiscovery, ContextGraphMapping, ProjectCreateRequest, ProjectRunLinkage, ProjectResource, ProjectUpdateRequest, ProjectWireShape, BuildPlanResource, LocalJobAgent, LocalJobEvent, LocalJobEventAppendRequest, LocalJobEventType, LocalJobRunCreateRequest, LocalJobRunResource, LocalJobStatus, LocalRunHandlerResult, LocalJobStep, LocalJobType, LocalServiceConfig, LocalServiceError, LocalServiceHealth, LocalExecutorStatus, ActionClientOrigin, ActionProposalApproval, ActionProposalApprovalRequest, ActionProposalCreateRequest, ActionProposalListResponse, ActionProposalPlan, ActionProposalPlanActionType, ActionProposalResource, ActionProposalStatus, ActionProposalType, BuildPlanChangeResult, ProjectChangeResult, ProjectSetupResult, ResetRequest, ResetResult, ContextGraphResource, ContextGraphSemanticEdge, ContextGraphSemanticEdgeKind, ContextGraphSemanticGraph, ContextGraphSemanticNode, ContextGraphSemanticNodeKind, StageExecutionSession, BuildEvidenceResource, ReadinessResource, SourceFileResource, BenchmarkQuestionDraftCreateRequest, BenchmarkQuestionDraftRuntimeRequest, BenchmarkQuestionDraftResult, VerifyRunCreateRequest, VerifyRunResource, VerifyRunStatus, RunObservabilityListResponse, RunObservabilityResource, RunArtifactsResponse, BuildPlanAuthoringCreateRequest, BuildPlanAuthoringRuntimeRequest, BuildPlanAuthoringResult, ProjectListResponse, BuildPlanListResponse, OpenPathRequest, OpenPathResponse, } from "./schemas/index.js";
+export { BuildRunCreateRequestSchema, BuildRunResourceSchema, BuildRunSummarySchema, InterfMcpHandoffSchema, InterfMcpServerSchema, LocalServiceDiscoverySchema, ContextGraphMappingSchema, ProjectCreateRequestSchema, ProjectRunLinkageSchema, ProjectResourceSchema, ProjectUpdateRequestSchema, ProjectWireShapeSchema, BuildPlanResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceErrorSchema, LocalServiceHealthSchema, ContextGraphResourceSchema, ContextGraphSemanticEdgeKindSchema, ContextGraphSemanticEdgeSchema, ContextGraphSemanticGraphSchema, ContextGraphSemanticNodeKindSchema, ContextGraphSemanticNodeSchema, StageExecutionSessionSchema, BuildEvidenceResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, VerifyRunStatusSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, RunArtifactsResponseSchema, LocalExecutorStatusSchema, ActionClientOriginSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalPlanActionTypeSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, ResetRequestSchema, ResetResultSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, ProjectListResponseSchema, BuildPlanListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./schemas/index.js";
 export type { HttpMethod, ServiceOperation, ServiceOperationId, ServiceOperationParameter, ServiceOperationVisibility, } from "./service/operations.js";
 export { APP_PROFILE_OPERATION_IDS, EmptyObjectSchema, SERVICE_OPERATIONS, serviceOperationById, } from "./service/operations.js";
 export { buildOpenApiDocument, } from "./service/openapi.js";

package/dist/packages/runtime/index.js

@@ -8,7 +8,7 @@ export * as client from "./client.js";
 export * as runtime from "./runtime.js";
 export * as server from "./service/server.js";
 export * as agentHandoff from "./agent-handoff.js";
-export { BuildRunCreateRequestSchema, BuildRunResourceSchema, BuildRunSummarySchema, InterfMcpHandoffSchema, InterfMcpServerSchema, LocalServiceDiscoverySchema, ContextGraphMappingSchema, ProjectRunLinkageSchema, ProjectResourceSchema, ProjectWireShapeSchema, BuildPlanResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceErrorSchema, LocalServiceHealthSchema, ContextGraphResourceSchema, BuildEvidenceResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, VerifyRunStatusSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, RunArtifactsResponseSchema, LocalExecutorStatusSchema, ActionClientOriginSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalPlanActionTypeSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, ResetRequestSchema, ResetResultSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, ProjectListResponseSchema, BuildPlanListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./schemas/index.js";
+export { BuildRunCreateRequestSchema, BuildRunResourceSchema, BuildRunSummarySchema, InterfMcpHandoffSchema, InterfMcpServerSchema, LocalServiceDiscoverySchema, ContextGraphMappingSchema, ProjectCreateRequestSchema, ProjectRunLinkageSchema, ProjectResourceSchema, ProjectUpdateRequestSchema, ProjectWireShapeSchema, BuildPlanResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceErrorSchema, LocalServiceHealthSchema, ContextGraphResourceSchema, ContextGraphSemanticEdgeKindSchema, ContextGraphSemanticEdgeSchema, ContextGraphSemanticGraphSchema, ContextGraphSemanticNodeKindSchema, ContextGraphSemanticNodeSchema, StageExecutionSessionSchema, BuildEvidenceResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, BenchmarkQuestionDraftCreateRequestSchema, BenchmarkQuestionDraftRuntimeRequestSchema, BenchmarkQuestionDraftResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, VerifyRunStatusSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, RunArtifactsResponseSchema, LocalExecutorStatusSchema, ActionClientOriginSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalPlanActionTypeSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, ResetRequestSchema, ResetResultSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringRuntimeRequestSchema, BuildPlanAuthoringResultSchema, ProjectListResponseSchema, BuildPlanListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./schemas/index.js";
 export { APP_PROFILE_OPERATION_IDS, EmptyObjectSchema, SERVICE_OPERATIONS, serviceOperationById, } from "./service/operations.js";
 export { buildOpenApiDocument, } from "./service/openapi.js";
 export { buildInterfMcpServers, buildInterfMcpHandoff, buildInterfMcpInstructions, } from "./agent-handoff.js";

package/dist/packages/runtime/native-run-handlers.d.ts

@@ -3,11 +3,48 @@ import type { AgentExecutionProfile, AgentExecutor } from "./agents/lib/executor
 import type { ProjectConfig } from "../projects/lib/schema.js";
 import type { StageShellRetentionMode } from "./build/build-plan-runs.js";
 import { type RunEventSink } from "./execution/events.js";
+import { type SavedBenchmarkOutcome } from "./verify/benchmark-run.js";
 import type { LocalServiceRunHandlers } from "./runtime.js";
 export interface NativeLocalServiceRunHandlerOptions {
     executor?: AgentExecutor;
     testExecutor?: AgentExecutor;
 }
+export declare function testScore(outcome: SavedBenchmarkOutcome): number;
+interface BuildPlanVariationRunResult {
+    passed: boolean;
+    attemptsRun: number;
+    failedStage: string | null;
+    bestOutcome: SavedBenchmarkOutcome | null;
+    bestGraphBackupPath: string | null;
+    bestAttempt: number;
+    fatalError: string | null;
+}
+/**
+ * Single mutated accumulator for the cross-variation best-build selection.
+ *
+ * Replaces the five locals (`bestOutcome`, `bestGraphBackupPath`,
+ * `bestAttempt`, `bestVariation`, plus their adoption closure) that used to be
+ * threaded through `runConfiguredBuild`. The reader now holds one object whose
+ * fields are the selected best and whose `consider` method owns the exact
+ * adopt-or-prune lifecycle:
+ *
+ * - A variation result is adopted only when it carries both a benchmark outcome
+ *   and a captured backup AND strictly beats the current best by `testScore`.
+ * - On adoption the previously held backup is pruned and the new one is taken
+ *   over (the source result's backup ownership is transferred away).
+ * - A non-adopted result's backup is pruned immediately.
+ *
+ * `prune` is injected so the disk-free callers (tests) can observe pruning
+ * order without touching the filesystem; production passes the real `rmSync`.
+ */
+export interface VariationBestTracker {
+    outcome: SavedBenchmarkOutcome | null;
+    backupPath: string | null;
+    attempt: number;
+    variation: number;
+}
+export declare function createVariationBestTracker(): VariationBestTracker;
+export declare function considerVariationBest(tracker: VariationBestTracker, variation: number, result: BuildPlanVariationRunResult, prune: (backupPath: string) => void): void;
 export declare function runConfiguredBuild(options: {
     executor: AgentExecutor;
     testExecutor?: AgentExecutor | null;
@@ -23,3 +60,4 @@ export declare function runConfiguredBuild(options: {
     events?: RunEventSink;
 }): Promise<boolean>;
 export declare function createNativeLocalServiceRunHandlers(options?: NativeLocalServiceRunHandlerOptions): Pick<LocalServiceRunHandlers, "planActionProposal" | "createBuildRun" | "createVerifyRun" | "createBenchmarkQuestionDraft" | "createBuildPlanAuthoringRun">;
+export {};

package/dist/packages/runtime/native-run-handlers.js

@@ -19,6 +19,7 @@ import { initializeBuildRuntimeState } from "./build/state.js";
 import { benchmarkPassRate, runBenchmarkForExecutor, runSavedContextGraphBenchmark, } from "./verify/benchmark-run.js";
 import { runBuildPlanAuthoringDraft, } from "../build-plans/authoring/build-plan-authoring.js";
 import { draftBenchmarkQuestions, } from "./benchmark-question-draft.js";
+import { asProjectDataDir, projectServiceJobShellsRoot, } from "../contracts/lib/project-paths.js";
 import { planActionProposalWithExecutor, } from "./action-planner.js";
 import { ActionProposalPlanSchema, } from "./schemas/index.js";
 function printBuildFailure(contextGraphPath, failedStage) {
@@ -32,7 +33,7 @@ function printBuildFailure(contextGraphPath, failedStage) {
     }
     console.log(chalk.red(`  ${failedStageLabel} failed.`));
 }
-function testScore(outcome) {
+export function testScore(outcome) {
     return (outcome.result.passedCases * 1000) + outcome.result.passedChecks;
 }
 async function buildContextGraphWithReporter(executor, contextGraphPath, options = {}) {
@@ -132,6 +133,28 @@ function restoreBestBuildState(backupPath, contextGraphPath) {
     clearBuildRuntimeDerivedArtifacts(contextGraphPath);
     initializeBuildRuntimeState(contextGraphPath);
 }
+export function createVariationBestTracker() {
+    return { outcome: null, backupPath: null, attempt: 0, variation: 0 };
+}
+export function considerVariationBest(tracker, variation, result, prune) {
+    if (result.bestOutcome &&
+        result.bestGraphBackupPath &&
+        (!tracker.outcome || testScore(result.bestOutcome) > testScore(tracker.outcome))) {
+        if (tracker.backupPath) {
+            prune(tracker.backupPath);
+        }
+        tracker.outcome = result.bestOutcome;
+        tracker.backupPath = result.bestGraphBackupPath;
+        tracker.attempt = result.bestAttempt;
+        tracker.variation = variation;
+        result.bestGraphBackupPath = null;
+        return;
+    }
+    if (result.bestGraphBackupPath) {
+        prune(result.bestGraphBackupPath);
+        result.bestGraphBackupPath = null;
+    }
+}
 async function runBuildPlanVariation(options) {
     let bestOutcome = null;
     let bestGraphBackupPath = null;
@@ -310,12 +333,19 @@ function printSelectedBuildPlanOwnership(contextGraphPath, bestVariation) {
     console.log(chalk.dim("  Building this existing Context Graph again reuses that local Build Plan draft."));
 }
 export async function runConfiguredBuild(options) {
-    const preserveStageShells = options.preserveStageShells ?? "on-failure";
+    const preserveStageShells = options.preserveStageShells ?? "always";
     const configuredMaxAttempts = resolveBuildMaxAttempts(options.maxAttemptsOverride);
     const maxLoops = resolveBuildMaxLoops(options.maxLoopsOverride);
     const maxAttempts = configuredMaxAttempts ?? (maxLoops != null ? 1 : null);
     const loopEnabled = maxAttempts != null;
-    const projectName = options.contextGraphConfig?.name ?? readInterfConfig(options.contextGraphPath)?.name ?? "project";
+    // Read the persisted Interf config once for the entry path. `readInterfConfig`
+    // does fs I/O + JSON parse + zod validation, and nothing here mutates the
+    // config file before the improvement loop, so a single read drives the
+    // project-name fallback (below) and the improvement-loop config fallback
+    // identically. The in-loop read at the improvement step stays a live re-read
+    // because that loop edits the Build Plan/config between iterations.
+    const interfConfig = readInterfConfig(options.contextGraphPath);
+    const projectName = options.contextGraphConfig?.name ?? interfConfig?.name ?? "project";
     const benchmarkSpec = buildTestSpecFromSourceFolderConfig({
         projectDataDir: options.sourcePath,
         targetName: projectName,
@@ -360,35 +390,19 @@ export async function runConfiguredBuild(options) {
         });
         return true;
     }
-    let bestOutcome = null;
-    let bestGraphBackupPath = null;
-    let bestAttempt = 0;
-    let bestVariation = 0;
+    const best = createVariationBestTracker();
     const previousVariations = [];
     const improvementRunId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const pruneBackup = (backupPath) => rmSync(backupPath, { recursive: true, force: true });
     try {
         const contextGraphConfig = options.contextGraphConfig
             ?? loadContextGraphProjectConfig(options.contextGraphPath)
             ?? {
-                name: readInterfConfig(options.contextGraphPath)?.name ?? "project",
+                name: interfConfig?.name ?? "project",
+                intent: interfConfig?.intent ?? "",
                 path: "./source-folder",
             };
-        const adoptVariationBest = (variation, result) => {
-            if (result.bestOutcome && result.bestGraphBackupPath && (!bestOutcome || testScore(result.bestOutcome) > testScore(bestOutcome))) {
-                if (bestGraphBackupPath) {
-                    rmSync(bestGraphBackupPath, { recursive: true, force: true });
-                }
-                bestOutcome = result.bestOutcome;
-                bestGraphBackupPath = result.bestGraphBackupPath;
-                bestAttempt = result.bestAttempt;
-                bestVariation = variation;
-                result.bestGraphBackupPath = null;
-            }
-            if (result.bestGraphBackupPath) {
-                rmSync(result.bestGraphBackupPath, { recursive: true, force: true });
-                result.bestGraphBackupPath = null;
-            }
-        };
+        const adoptVariationBest = (variation, result) => considerVariationBest(best, variation, result, pruneBackup);
         const baseline = await runBuildPlanVariation({
             executor: options.executor,
             testExecutor: options.testExecutor,
@@ -480,7 +494,7 @@ export async function runConfiguredBuild(options) {
                 }));
                 if (variation.passed) {
                     printBuildPlanVariationSummary(previousVariations);
-                    printSelectedBuildPlanOwnership(options.contextGraphPath, bestVariation);
+                    printSelectedBuildPlanOwnership(options.contextGraphPath, best.variation);
                     printPostBuildNextStep({
                         contextGraphPath: options.contextGraphPath,
                         checks: benchmarkCheckCount,
@@ -490,30 +504,30 @@ export async function runConfiguredBuild(options) {
                 }
             }
         }
-        if (bestGraphBackupPath && bestVariation > 0) {
-            restoreBestBuildState(bestGraphBackupPath, options.contextGraphPath);
+        if (best.backupPath && best.variation > 0) {
+            restoreBestBuildState(best.backupPath, options.contextGraphPath);
             console.log();
-            console.log(chalk.dim(`  Restored the best-performing Context Graph from variation ${bestVariation}, attempt ${bestAttempt}.`));
+            console.log(chalk.dim(`  Restored the best-performing Context Graph from variation ${best.variation}, attempt ${best.attempt}.`));
         }
         process.exitCode = 1;
         console.log();
         printBuildPlanVariationSummary(previousVariations);
-        printSelectedBuildPlanOwnership(options.contextGraphPath, bestVariation);
+        printSelectedBuildPlanOwnership(options.contextGraphPath, best.variation);
         if (maxLoops != null) {
             console.log(chalk.red(`  Context Graph did not pass after ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"} per variation and ${maxLoops} Build Plan improvement loop${maxLoops === 1 ? "" : "s"}.`));
         }
         else {
             console.log(chalk.red(`  Context Graph did not pass within ${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}.`));
         }
-        if (bestOutcome) {
-            console.log(chalk.dim(`  Best attempt benchmark pass rate: ${benchmarkPassRate(bestOutcome)}%.`));
+        if (best.outcome) {
+            console.log(chalk.dim(`  Best attempt benchmark pass rate: ${benchmarkPassRate(best.outcome)}%.`));
         }
         printStageShellReviewHint(options.contextGraphPath, preserveStageShells, "failure");
         return false;
     }
     finally {
-        if (bestGraphBackupPath) {
-            rmSync(bestGraphBackupPath, { recursive: true, force: true });
+        if (best.backupPath) {
+            rmSync(best.backupPath, { recursive: true, force: true });
         }
     }
 }
@@ -662,6 +676,9 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
                 intent: request.intent,
                 executor,
                 targetCount: request.target_count,
+                // Preserve the drafting shell under the Project's durable job storage so
+                // the draft execution (prompt, reasoning, output, verdict) is inspectable.
+                preservedShellRoot: join(projectServiceJobShellsRoot(asProjectDataDir(context.sourcePath)), `benchmark-question-draft-${context.runId}`),
                 onStatus: (line) => context.emit({
                     type: "log.appended",
                     step_id: "agent-draft",
@@ -673,6 +690,8 @@ export function createNativeLocalServiceRunHandlers(options = {}) {
             }
             return {
                 checks: drafted.checks,
+                ...(drafted.shellPath ? { shell_path: drafted.shellPath } : {}),
+                ...(drafted.reasoningPath ? { reasoning_path: drafted.reasoningPath } : {}),
             };
         },
         async createBuildPlanAuthoringRun(request, context) {

package/dist/packages/runtime/plan-artifact-contract.js

@@ -6,7 +6,7 @@ export function artifactsForBuildPlan(projectDataDir, buildPlanId) {
         return [];
     try {
         const buildPlan = getBuildPlan(buildPlanId, { projectDataDir });
-        return [...(buildPlan.contextInterface?.artifacts ?? buildPlan.schema?.artifacts ?? [])];
+        return [...(buildPlan.contextInterface?.artifacts ?? [])];
     }
     catch {
         return [];

package/dist/packages/runtime/project-source-state.d.ts

@@ -8,14 +8,14 @@
 import type { ProjectSourceState } from "../contracts/lib/project-schema.js";
 export interface ProjectSourceStateInput {
     projectId: string;
-    sourceFolderPath: string;
     contextGraphPath: string;
     /**
      * Hash from the last successful Build (typically the latest Context
-     * Flow's file index hash). Null when no Build has produced a
-     * Context Graph yet.
+     * Graph's file index hash). Omit when computing state for the latest
+     * Context Graph itself; pass null only when no Build has produced a
+     * manifest yet.
      */
-    lastGraphIndexHash: string | null;
+    lastGraphIndexHash?: string | null;
 }
 /**
  * Compute the current `ProjectSourceState`.

package/dist/packages/runtime/project-source-state.js

@@ -29,10 +29,13 @@ export function computeProjectSourceState(input) {
     }
     const sourceFiles = sourceManifestToSourceFiles(manifest);
     const fileIndexHash = computeFileIndexHash(sourceFiles);
+    const baselineIndexHash = input.lastGraphIndexHash === undefined
+        ? fileIndexHash
+        : input.lastGraphIndexHash;
     const driftKind = (() => {
-        if (input.lastGraphIndexHash === null)
+        if (baselineIndexHash === null)
             return "unknown";
-        if (input.lastGraphIndexHash === fileIndexHash)
+        if (baselineIndexHash === fileIndexHash)
             return "fresh";
         return "drifted";
     })();

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

@@ -20,10 +20,12 @@ export interface ProjectCreateInput {
         kind: "local-folder";
         locator: string;
     };
+    intent: string;
     /** Build Plan binding. Null/undefined means "not bound yet" — bind later via update. */
     build_plan_id?: string | null;
 }
 export interface ProjectUpdateInput {
+    intent?: string;
     build_plan_id?: string | null;
 }
 export interface StoredProject {
@@ -33,6 +35,7 @@ export interface StoredProject {
         kind: "local-folder";
         locator: string;
     };
+    intent: string;
     /** Null when no Build Plan has been bound to this Project yet. */
     buildPlanId: string | null;
     config: ProjectConfig;
@@ -75,8 +78,10 @@ export declare function projectWireShape(stored: StoredProject): {
         kind: string;
         locator: string;
     };
+    intent: string;
     build_plan_id: string | null;
     config_path: string;
+    updated_at: string | null;
     context_graph: {
         kind: "local-path";
         value: string;

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

@@ -14,7 +14,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync, } from "node:fs";
 import { resolve } from "node:path";
-import { ProjectIdSchema, BuildPlanIdSchema, } from "../contracts/lib/schema.js";
+import { ProjectIdSchema, BuildPlanIdSchema, ProjectIntentSchema, } from "../contracts/lib/schema.js";
 import { projectDataDir as resolveProjectDataDir, projectConfigPath, projectContextGraphPath, projectRunContextGraphPath, projectsRoot, } from "../contracts/lib/project-paths.js";
 import { saveSourceFolderConfig, loadSourceFolderConfig, } from "../projects/source-config.js";
 import { assertCanCreateProject } from "./entitlement-guard.js";
@@ -28,9 +28,13 @@ function loadStoredProject(projectId) {
     const config = loadSourceFolderConfig(projectDataDir);
     if (!config)
         return null;
-    const project = config.projects?.find((p) => p.name === projectId);
-    if (!project)
+    const loadedProject = config.projects?.find((p) => p.name === projectId);
+    if (!loadedProject)
         return null;
+    const intent = ProjectIntentSchema.safeParse(loadedProject.intent);
+    if (!intent.success)
+        return null;
+    const project = { ...loadedProject, intent: intent.data };
     const sourceFolderPath = config.source_folder?.path;
     if (!sourceFolderPath)
         return null;
@@ -38,6 +42,7 @@ function loadStoredProject(projectId) {
         id: projectId,
         projectDataDir,
         source: { kind: "local-folder", locator: sourceFolderPath },
+        intent: project.intent,
         buildPlanId: project.build_plan ?? null,
         config: project,
         contextGraphPath: project.latest_context_graph_run_id
@@ -78,6 +83,7 @@ export function createStoredProject(runtime, input) {
     if (input.build_plan_id != null) {
         BuildPlanIdSchema.parse(input.build_plan_id);
     }
+    const intent = ProjectIntentSchema.parse(input.intent);
     const sourceLocator = resolve(input.source.locator);
     ensureProjectsRoot();
     const projectDataDir = resolveProjectDataDir(input.id);
@@ -89,6 +95,7 @@ export function createStoredProject(runtime, input) {
     mkdirSync(projectDataDir, { recursive: true });
     const project = {
         name: input.id,
+        intent,
         path: input.id,
         ...(input.build_plan_id ? { build_plan: input.build_plan_id } : {}),
     };
@@ -128,8 +135,12 @@ export function updateStoredProject(projectId, patch) {
     if (patch.build_plan_id !== undefined && patch.build_plan_id !== null) {
         BuildPlanIdSchema.parse(patch.build_plan_id);
     }
+    if (patch.intent !== undefined) {
+        ProjectIntentSchema.parse(patch.intent);
+    }
     const nextProject = {
         ...stored.config,
+        ...(patch.intent !== undefined ? { intent: ProjectIntentSchema.parse(patch.intent) } : {}),
         ...(patch.build_plan_id === null
             ? { build_plan: undefined }
             : patch.build_plan_id !== undefined
@@ -154,14 +165,30 @@ export function rehydrateProjects(runtime) {
         runtime.registerProject(stored.projectDataDir);
     }
 }
+/**
+ * Last-modified time of the Project's `interf.json`, ISO 8601. This is the
+ * Projects list recency signal: it advances on create, edit (intent / Build
+ * Plan change), and a successful Build (which writes `latest_context_graph_run_id`
+ * back into the config). Null when the mtime can't be read.
+ */
+function projectConfigUpdatedAt(configPath) {
+    try {
+        return statSync(configPath).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
 /** Build the wire shape for `GET /v1/projects/<id>` given a stored Project. */
 export function projectWireShape(stored) {
     return {
         id: stored.id,
         project_id: stored.id,
         source: stored.source,
+        intent: stored.intent,
         build_plan_id: stored.buildPlanId,
         config_path: stored.configPath,
+        updated_at: projectConfigUpdatedAt(stored.configPath),
         context_graph: { kind: "local-path", value: stored.contextGraphPath },
         context_graph_path: stored.contextGraphPath,
     };

package/dist/packages/runtime/requested-artifacts.js

@@ -42,7 +42,7 @@ function titleFromArtifactId(value) {
         .join(" ");
 }
 function labelForArtifactCheck(check) {
-    return check.description ?? titleFromArtifactId(check.id) ?? "Artifact diagnostic";
+    return check.description ?? titleFromArtifactId(check.id) ?? "Output diagnostic";
 }
 export function requestedArtifactsFromPlanArtifacts(artifacts) {
     return artifacts.map((artifact) => ({

package/dist/packages/runtime/run-observability.js

@@ -81,10 +81,15 @@ function runTraceStatus(status) {
     return "completed";
 }
 function safeTraceNamePart(value) {
+    // Keep spaces so timeline labels read as human text ("Draft Build Plan")
+    // instead of dash-joined slugs ("Draft-Build-Plan-definition"). The name is
+    // only ever split on `//` and `/` downstream, so spaces are safe; it is never
+    // used as a path or correlation key.
     return value
-        .replace(/[^a-zA-Z0-9._/-]+/g, "-")
+        .replace(/[^a-zA-Z0-9._/ -]+/g, " ")
         .replace(/\/+/g, "/")
-        .replace(/^-+|-+$/g, "")
+        .replace(/\s+/g, " ")
+        .replace(/^[\s-]+|[\s-]+$/g, "")
         || "run";
 }
 function interfTraceName(runType, name) {
@@ -277,10 +282,10 @@ export function buildRunToObservability(run) {
             { label: "Executor", value: executor?.display_name ?? run.backend },
             { label: "Stages", value: `${run.stages.filter((stage) => stage.status === "succeeded").length}/${run.stages.length}` },
             {
-                label: "Context Checks",
+                label: "Coverage goals",
                 value: `${(run.context_checks ?? []).filter((check) => check.status === "passed").length}/${(run.context_checks ?? []).length}`,
             },
-            { label: "Artifacts", value: String(artifacts.length) },
+            { label: "Outputs", value: String(artifacts.length) },
         ],
         artifacts,
         checks,

package/dist/packages/runtime/runtime-action-proposals.js

@@ -324,7 +324,7 @@ async function buildActionProposal(runtime, projectDataDir, request) {
             status: "awaiting_approval",
             action_type: actionType,
             title: (usePlannerText ? plan.title : undefined) ?? `Draft Build Plan ${buildPlanId}`,
-            summary: (usePlannerText ? plan.summary : undefined) ?? "Ask the configured local executor to draft a Build Plan for requested Artifacts and Context Checks.",
+            summary: (usePlannerText ? plan.summary : undefined) ?? "Ask the configured local executor to draft a Build Plan from Project intent, requested outputs, and coverage expectations.",
             assistant_message: (usePlannerText ? plan.assistant_message : undefined) ??
                 actionAssistantMessage(actionType, projectConfig?.name ?? null, commandPreview),
             command_preview: commandPreview,
@@ -471,12 +471,12 @@ async function buildActionProposal(runtime, projectDataDir, request) {
         if (plan.summary)
             return plan.summary;
         if (proposalActionType === "build")
-            return "Build a Context Graph with summaries, claims, links back to sources, Build evidence, and traces.";
+            return "Build a Context Graph with summaries, task-aware knowledge, graph entrypoints, coverage metrics, source links, and traces.";
         if (proposalActionType === "benchmark")
             return "Run Q&A / fact-check benchmarks against source files and Context Graph.";
         if (proposalActionType === "benchmark-question-draft")
             return "Ask the configured local executor to draft saved Q&A / fact-check evaluation questions.";
-        return "Ask the configured local executor to draft a Build Plan for requested Artifacts and Context Checks.";
+        return "Ask the configured local executor to draft a Build Plan from Project intent, requested outputs, and coverage expectations.";
     })();
     const previewValues = proposalValues;
     const commandPreview = plan.command_preview ?? actionCommandPreview(proposalActionType, projectConfig.name, buildPlanId, previewValues);

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

@@ -1,5 +1,6 @@
-import { existsSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { installUserBuildPlan, userBuildPlanExists, } from "../build-plans/package/user-build-plans.js";
 import { asProjectDataDir, projectBuildPlansRoot, userBuildPlansRoot, } from "../contracts/lib/project-paths.js";
 import { buildPlanIdForProjectConfig, DEFAULT_BUILD_PLAN_ID, listProjectConfigs, loadSourceFolderConfig, saveSourceFolderConfig, } from "../projects/source-config.js";
 import { listBuildPlanChoices, } from "../build-plans/package/build-plan-definitions.js";
@@ -31,9 +32,26 @@ export function listBuildPlans(runtime, projectDataDir) {
             const activeForProjects = projects
                 .filter((project) => buildPlanIdForProjectConfig(project) === buildPlan.id)
                 .map((project) => project.name);
+            // Package file mtime/birthtime give migration-free "last updated"/"created"
+            // signals so clients can sort Build Plans newest-first like Projects.
+            const sourcePath = resolveBuildPlanPackageSourcePath(projectDataDir, buildPlan.id);
+            let createdAt = null;
+            let updatedAt = null;
+            if (sourcePath) {
+                try {
+                    const stat = statSync(sourcePath);
+                    updatedAt = stat.mtime.toISOString();
+                    createdAt = (stat.birthtimeMs > 0 ? stat.birthtime : stat.mtime).toISOString();
+                }
+                catch {
+                    // Package file vanished between listing and stat — leave timestamps null.
+                }
+            }
             return buildBuildPlanResource({
                 id: buildPlan.id,
-                path: resolveBuildPlanPackageSourcePath(projectDataDir, buildPlan.id) ?? buildPlan.id,
+                path: sourcePath ?? buildPlan.id,
+                created_at: createdAt,
+                updated_at: updatedAt,
                 label: buildPlan.label,
                 hint: buildPlan.hint,
                 purpose: buildPlan.purpose,
@@ -41,6 +59,7 @@ export function listBuildPlans(runtime, projectDataDir) {
                 inputs: buildPlan.inputs,
                 source_kind: buildPlan.scope === "builtin" ? "builtin" : "local",
                 built_in: buildPlan.scope === "builtin",
+                scope: buildPlan.scope ?? "local",
                 active_for_projects: activeForProjects,
                 artifacts: buildPlan.contextInterface?.artifacts ?? [],
                 stages: buildPlan.stages.map((stage) => ({
@@ -95,6 +114,30 @@ export function applyBuildPlanChange(runtime, projectDataDir, requestValue) {
             message: `Duplicated Build Plan ${buildPlanId} as ${request.new_build_plan_id}.`,
         });
     }
+    if (request.operation === "save") {
+        const localPath = buildPlanDefinitionPath(projectDataDir, buildPlanId);
+        if (buildPlanId === DEFAULT_BUILD_PLAN_ID || !existsSync(localPath)) {
+            throw new Error(`Build Plan "${buildPlanId}" is not a project Build Plan that can be saved to the library.`);
+        }
+        if (userBuildPlanExists(buildPlanId)) {
+            throw new Error(`Build Plan "${buildPlanId}" is already in your reusable library.`);
+        }
+        const installed = installUserBuildPlan({ sourceDir: dirname(localPath), id: buildPlanId, overwrite: false });
+        // Move (not copy): drop the project-local package so the id lives only in
+        // the user library — same plan, now reusable, still bound to the Project.
+        rmSync(dirname(localPath), { recursive: true, force: true });
+        runtime.buildPlanListingCache.invalidate(projectDataDir);
+        return BuildPlanChangeResultSchema.parse({
+            kind: "interf-build-plan-change-result",
+            version: 1,
+            operation: "save",
+            build_plan: buildPlanId,
+            updated_projects: [],
+            build_plan_path: installed.path,
+            changed: true,
+            message: `Saved Build Plan ${buildPlanId} to your reusable library.`,
+        });
+    }
     if (request.confirmation !== buildPlanId) {
         throw new Error(`Type ${buildPlanId} to confirm Build Plan removal.`);
     }
@@ -113,6 +156,7 @@ export function applyBuildPlanChange(runtime, projectDataDir, requestValue) {
         for (const project of updatedProjects) {
             runtime.readinessCache.invalidateProject(projectDataDir, project.name);
         }
+        runtime.contextGraphResourceCache.invalidateProject(projectDataDir);
     }
     rmSync(outputPath, { recursive: true, force: true });
     runtime.buildPlanListingCache.invalidate(projectDataDir);