@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/engine/runtime.js

@@ -1,2463 +0,0 @@
-import { existsSync, mkdirSync, rmSync, statSync, } from "node:fs";
-import { join, resolve } from "node:path";
-import { BuildRunSchema, } from "./execution/lib/schema.js";
-import { createRunEventId, createRunEventTimestamp, } from "./execution/events.js";
-import { loadState, } from "./build/state.js";
-import { actionProposalPath, actionProposalsRoot, byCreatedAtDesc, buildRunPath, buildRunsRoot, listJsonFiles, localJobPath, localJobsRoot, newestFirst, readActionProposalAt, readBuildRunAt, readLocalJobRunAt, readRuntimeRunHistory, readVerifyRunAt, verifyRunPath, verifyRunsRoot, timestampKey, writeJsonFile, } from "./runtime-persistence.js";
-import { BuildPlanListingCache, MtimeListingCache, ReadinessCache, RunListingCache, } from "./runtime-caches.js";
-import { applyEventToBuildRun, applyEventToLocalJob, } from "./runtime-event-applier.js";
-import { buildBuildPlanResource, buildPreparationResource, createRunId, logsForRuntimeRun, logsForStageRun, proofForStage, readinessStateToPreparationReadiness, readinessSummaryForStatus, readinessTargetResult, stageArtifactRefs, } from "./runtime-resource-builders.js";
-import { ACTION_PLANNER_CLARIFICATION_MESSAGE, actionAssistantMessage, actionCommandPreview, actionTypeFromValues, actionValueBuildPlanTaskPrompt, configuredAgentName, createActionProposalId, detachBuildPlanFromPreparation, detectedExecutorOptions, directServiceEndpointForAction, hasVerifiableContextTestTarget, buildPlanAuthoringHintFromPrompt, buildPlanAuthoringPromptFallback, buildPlanIdForProposal, buildPlanLabelFromId, numberValue, requireSelectedBuildPlan, sanitizeActionProposalPlan, stringValue, testModeFromValues, } from "./runtime-proposal-helpers.js";
-import { ReadinessSchema, } from "../contracts/lib/schema.js";
-import { discoverSourceFiles, } from "./build/discovery.js";
-import { resetBuildGeneratedState, } from "./build/reset.js";
-import { ensureVerifiableContextScaffold, readInterfConfig, } from "../project/interf.js";
-import { findSourcePreparationConfig, fingerprintReadinessChecks, listSourcePreparationConfigs, loadSourceFolderConfig, DEFAULT_BUILD_PLAN_ID, buildPlanIdForSourcePreparationConfig, resolveConfiguredSourceFolderPath, resolveSourcePreparationPath, removeSourcePreparationConfig, saveSourceFolderConfig, syncVerifiableContextInterfConfigFromSourcePreparationConfig, upsertSourcePreparationConfig, } from "../project/source-config.js";
-import { listSourceFolderChoices, } from "../project/source-folders.js";
-import { asPreparationDataDir, preparationVerifiableContextPath, userBuildPlansRoot, preparationConfigPath, preparationBuildPlanPackagePath, preparationBuildPlansRoot, } from "../contracts/lib/preparation-paths.js";
-import { getBuildPlan, listBuildPlanChoices, } from "../build-plans/package/build-plan-definitions.js";
-import { aggregateArtifactVerdict, computeArtifactStatuses, } from "./build/artifact-status.js";
-import { JsonlBillingEventSink, buildCompilationEventsForRun, defaultBillingEventLogPath, } from "./build/billing-events.js";
-import { buildPlanDefinitionPath, resolveBuildPlanPackageSourcePath, } from "../build-plans/package/local-build-plans.js";
-import { seedLocalBuildPlanPackageFromBase, } from "../build-plans/package/interf-build-plan-package.js";
-import { PACKAGE_ROOT } from "../build-plans/package/lib/package-root.js";
-import { resolveAgent, detectAgents, supportsAutomatedRuns, } from "./agents/lib/detection.js";
-import { loadUserConfig, saveUserConfig, } from "./agents/lib/user-config.js";
-import { loadAgentsRegistry, registerCustomAgent, unregisterCustomAgent, patchRoleMap, setActiveAgent, } from "./agents/registry.js";
-import { readSavedReadinessCheckRun, } from "./verify/readiness-check-run.js";
-import { createVerifiableContextTestTarget, } from "./verify/verify-targets.js";
-import { ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalPlanSchema, ActionProposalResourceSchema, ActionProposalTypeSchema, BuildRunCreateRequestSchema, BuildRunResourceSchema, LocalExecutorStatusSchema, LocalExecutorSelectRequestSchema, LocalServiceHealthSchema, LocalRunHandlerResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, SourceFileResourceSchema, VerifiableContextResourceSchema, PreparationSetupCreateRequestSchema, PreparationSetupResultSchema, BuildPlanChangeCreateRequestSchema, BuildPlanChangeResultSchema, PreparationChangeCreateRequestSchema, PreparationChangeResultSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, VerifyRunCreateRequestSchema, VerifyRunResourceSchema, BuildPlanAuthoringCreateRequestSchema, BuildPlanAuthoringResultSchema, } from "./lib/schema.js";
-import { buildLocalServiceUrl, } from "./routes.js";
-import { BuildPlanAuthoringActionValuesSchema, PreparationSetupActionValuesSchema, } from "./action-values.js";
-import { buildRunToObservability, jobRunToObservability, verifyRunToObservability, uniqueArtifacts, } from "./run-observability.js";
-import { artifactRequirementsFromRequestedArtifacts } from "./requested-artifacts.js";
-/** TTL for `POS../../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;
-const INTERRUPTED_COMPILE_RUN_MESSAGE = "Build run interrupted because the Interf engine stopped before the run reached a terminal state.";
-const INTERRUPTED_JOB_RUN_MESSAGE = "Job interrupted because the Interf engine stopped before the job reached a terminal state.";
-function isTerminalBuildRunStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
-function isTerminalJobStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "cancelled";
-}
-function countsFromVerifiableContextState(state) {
-    const counts = {};
-    for (const stage of Object.values(state.stages ?? {})) {
-        for (const [key, value] of Object.entries(stage.counts ?? {})) {
-            if (Number.isFinite(value))
-                counts[key] = Math.max(counts[key] ?? 0, value);
-        }
-        for (const [key, value] of Object.entries(stage.artifact_counts ?? {})) {
-            if (Number.isFinite(value))
-                counts[key] = Math.max(counts[key] ?? 0, value);
-        }
-    }
-    return counts;
-}
-export class LocalServiceRuntime {
-    host;
-    port;
-    startedAt;
-    packageVersion;
-    handlers;
-    /**
-     * The seed root path the runtime was constructed with. Used as a
-     * non-preparation fallback when a preparation-independent route
-     * (Build Plans, action proposals, runs listings) needs an anchor to load
-     * shared state (user-library Build Plans, bundled Build Plans, etc).
-     */
-    rootPath;
-    /**
-     * Per-instance bearer token. Mutating routes require this on the
-     * Authorization header. `null` means token-less mode (test harness).
-     */
-    authToken;
-    /** Map of prepDataDir -> PreparationContext. */
-    preparationContexts = new Map();
-    /** Hook called whenever a preparation is registered or deregistered. */
-    onRegistryChanged = null;
-    /** In-flight runs across all preparations. Used for `idle_for_seconds`. */
-    activeRunCount = 0;
-    /**
-     * Active Build run cancellation handles, keyed by run id. Populated
-     * when a Build run is launched and cleared once the run reaches a
-     * terminal state. Each entry remembers where the persisted record lives
-     * so cancel can mark it without re-resolving the Preparation.
-     *
-     * TODO(cloud): when the cloud variant lands, wire `RunLeaseStore`
-     * (see `cloud-seams.ts` B4.2) through this map. Multi-replica engines
-     * need a shared lease store so a replica can take over a run whose
-     * owning replica died.
-     */
-    activeBuildRuns = new Map();
-    /**
-     * Idempotency-key cache for `POS../../build-runs`. Outer key is the
-     * resolved preparation root; inner key is the client-supplied idempotency
-     * value. Namespacing per preparation prevents key collisions across
-     * tenants on the same engine (CSO finding: a malicious preparation could
-     * otherwise hijack another preparation's run id by reusing its key).
-     * Entries expire after `IDEMPOTENCY_TTL_MS`.
-     *
-     * TODO(cloud): when the cloud variant lands, wire `IdempotencyStore`
-     * (see `cloud-seams.ts` B4.1) through this map. Multi-replica engines
-     * need a shared store so retries that land on a different replica
-     * still hit the same dedupe entry.
-     */
-    idempotencyKeyCache = new Map();
-    /**
-     * Read-side caches. Polling clients (Interf UI, CLI status loops)
-     * hit list/get endpoints multiple times per second; without these,
-     * every request re-walks the filesystem and re-parses every JSON
-     * record through Zod. The runtime invalidates each cache on the
-     * matching write path. See {@link runtime-caches} for design notes.
-     */
-    buildRunCache = new RunListingCache();
-    verifyRunCache = new RunListingCache();
-    readinessCache = new ReadinessCache();
-    sourceFilesCache = new MtimeListingCache();
-    buildPlanListingCache = new BuildPlanListingCache();
-    /**
-     * 0.17 — sink for per-Artifact billing events. Set once at construction.
-     * Lazy-defaults to a per-run JSONL writer when no override was injected.
-     */
-    billingEventSink;
-    /**
-     * 0.17 — cloud-variant injection points. The local engine accepts
-     * these on the options surface but does not consume them yet — the
-     * in-process Maps remain authoritative for idempotency and
-     * run-lease state. The cloud variant fork will swap to these stores;
-     * the option-fields are documented here so the cloud build has a
-     * stable target. See `cloud-seams.ts` for the contracts.
-     */
-    cloudIdempotencyStore;
-    cloudRunLeaseStore;
-    cloudTokenValidator = null;
-    constructor(options) {
-        this.host = options.host;
-        this.port = options.port;
-        this.startedAt = options.startedAt ?? new Date().toISOString();
-        this.packageVersion = options.packageVersion;
-        this.handlers = options.handlers ?? {};
-        this.authToken = options.authToken ?? null;
-        this.rootPath = resolve(options.rootPath);
-        this.billingEventSink = options.billingEventSink ?? null;
-        this.cloudIdempotencyStore = options.idempotencyStore ?? null;
-        this.cloudRunLeaseStore = options.runLeaseStore ?? null;
-        // Auto-register the initial preparation so single-preparation callers
-        // (existing tests, the current `interf web` command) work without
-        // additional bootstrapping. The constructor seed is the only role
-        // `options.rootPath` plays; runtime operations take `prepDataDir`
-        // explicitly afterwards.
-        this.registerPreparation(this.rootPath);
-    }
-    setBoundPort(port) {
-        this.port = port;
-    }
-    /**
-     * 0.17 — token validator setter for cloud variants. Stored on the
-     * runtime so `isAuthorizedMutation` in `server.ts` can opt into the
-     * async per-account check when present. Local default: never set —
-     * the static bearer-token check runs.
-     */
-    setTokenValidator(validator) {
-        this.cloudTokenValidator = validator;
-    }
-    getTokenValidator() {
-        return this.cloudTokenValidator;
-    }
-    /** Set a hook that fires whenever the registered preparations change. */
-    setOnRegistryChanged(handler) {
-        this.onRegistryChanged = handler;
-    }
-    /**
-     * Register a preparation with this runtime. Returns the PreparationContext.
-     * Idempotent: re-registering an existing preparation updates `lastActivity`.
-     */
-    registerPreparation(prepDataDir) {
-        const resolved = resolve(prepDataDir);
-        const now = new Date().toISOString();
-        const existing = this.preparationContexts.get(resolved);
-        if (existing) {
-            existing.lastActivity = now;
-            this.onRegistryChanged?.();
-            return existing;
-        }
-        const context = {
-            rootPath: resolved,
-            startedAt: now,
-            lastActivity: now,
-        };
-        this.preparationContexts.set(resolved, context);
-        this.finalizeInterruptedBuildRuns(resolved);
-        this.finalizeInterruptedJobRuns(resolved);
-        this.onRegistryChanged?.();
-        return context;
-    }
-    /**
-     * Remove a preparation from the runtime. Returns true if a preparation was
-     * removed.
-     */
-    deregisterPreparation(prepDataDir) {
-        const resolved = resolve(prepDataDir);
-        const removed = this.preparationContexts.delete(resolved);
-        if (removed) {
-            this.onRegistryChanged?.();
-        }
-        return removed;
-    }
-    /**
-     * Most recently active preparation, or the first registered if none has
-     * activity yet. Server code uses this as the fallback when a request
-     * does not specify a preparation. Throws if none are registered.
-     */
-    defaultPreparationDataDir() {
-        if (this.preparationContexts.size === 0) {
-            throw new Error("Local service has no registered preparations.");
-        }
-        let best = null;
-        let bestKey = -Infinity;
-        for (const context of this.preparationContexts.values()) {
-            const key = Date.parse(context.lastActivity);
-            if (Number.isFinite(key) && key > bestKey) {
-                best = context;
-                bestKey = key;
-            }
-        }
-        return (best ?? this.preparationContexts.values().next().value).rootPath;
-    }
-    /** Look up a preparation context by rootPath. */
-    getPreparationContext(prepDataDir) {
-        return this.preparationContexts.get(resolve(prepDataDir)) ?? null;
-    }
-    /** All registered preparations, ordered by registration time. */
-    listRegisteredPreparations() {
-        return Array.from(this.preparationContexts.values()).sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
-    }
-    /** True when no preparations are registered. */
-    hasNoPreparations() {
-        return this.preparationContexts.size === 0;
-    }
-    /** Number of registered preparations. */
-    registeredPreparationCount() {
-        return this.preparationContexts.size;
-    }
-    /** Increment in-flight run counter. Call when a long-running run starts. */
-    beginActiveRun() {
-        this.activeRunCount += 1;
-    }
-    /** Decrement in-flight run counter. Pair with `beginActiveRun`. */
-    endActiveRun() {
-        if (this.activeRunCount > 0)
-            this.activeRunCount -= 1;
-    }
-    /** Sum of in-flight runs across all preparations. */
-    activeRuns() {
-        return this.activeRunCount;
-    }
-    /**
-     * Mark the preparation as recently active. Routes call this on entry so
-     * `idleForSeconds` and the registry snapshots stay in sync with the
-     * actual request cadence.
-     */
-    touchPreparation(prepDataDir) {
-        const context = this.preparationContexts.get(resolve(prepDataDir));
-        if (context) {
-            context.lastActivity = new Date().toISOString();
-        }
-    }
-    /** Seconds since the most recent preparation activity (0 if active). */
-    idleForSeconds() {
-        const all = this.listRegisteredPreparations();
-        if (all.length === 0)
-            return 0;
-        if (this.activeRunCount > 0)
-            return 0;
-        let mostRecent = 0;
-        for (const context of all) {
-            const ts = Date.parse(context.lastActivity);
-            if (Number.isFinite(ts) && ts > mostRecent)
-                mostRecent = ts;
-        }
-        if (mostRecent <= 0)
-            return 0;
-        const elapsed = Math.max(0, Date.now() - mostRecent);
-        return Math.floor(elapsed / 1000);
-    }
-    health(prepDataDir) {
-        const sourceFolderPath = prepDataDir ? resolveConfiguredSourceFolderPath(prepDataDir) : null;
-        return LocalServiceHealthSchema.parse({
-            kind: "interf-local-service-health",
-            version: 1,
-            status: "ok",
-            host: this.host,
-            port: this.port,
-            service_url: buildLocalServiceUrl({ host: this.host, port: this.port }),
-            ...(prepDataDir ? { control_path: prepDataDir } : {}),
-            source_folder_path: sourceFolderPath,
-            started_at: this.startedAt,
-            ...(this.packageVersion ? { package_version: this.packageVersion } : {}),
-            instance_started_at: this.startedAt,
-            active_runs: this.activeRunCount,
-            idle_for_seconds: this.idleForSeconds(),
-        });
-    }
-    listPreparations(prepDataDir) {
-        const config = loadSourceFolderConfig(prepDataDir);
-        return listSourcePreparationConfigs(config).map((preparation) => {
-            const buildRuns = this.listBuildRunsForPreparation(prepDataDir, preparation.name);
-            const verifyRuns = this.listVerifyRunsForPreparation(prepDataDir, preparation.name);
-            const readiness = this.computePreparationReadiness(prepDataDir, preparation);
-            return buildPreparationResource(prepDataDir, preparation, readiness, buildRuns[0]?.run_id ?? null, verifyRuns[0]?.run_id ?? null, 
-            // 0.17 — surface per-Artifact status from the latest build
-            // run so the UI can render artifact rows on the Preparation
-            // page without a separate fetch.
-            buildRuns[0]?.artifacts ?? []);
-        });
-    }
-    getPreparation(prepDataDir, preparationName) {
-        return this.listPreparations(prepDataDir).find((preparation) => preparation.name === preparationName) ?? null;
-    }
-    listPreparationReadiness(prepDataDir) {
-        return this.listReadiness(prepDataDir).map(readinessStateToPreparationReadiness);
-    }
-    getPreparationReadiness(prepDataDir, preparationName) {
-        const readiness = this.getReadiness(prepDataDir, preparationName);
-        return readiness ? readinessStateToPreparationReadiness(readiness) : null;
-    }
-    listReadiness(prepDataDir) {
-        const config = loadSourceFolderConfig(prepDataDir);
-        return listSourcePreparationConfigs(config).map((preparation) => this.computePreparationReadiness(prepDataDir, preparation));
-    }
-    getReadiness(prepDataDir, preparationName) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
-        return preparation ? this.computePreparationReadiness(prepDataDir, preparation) : null;
-    }
-    computePreparationReadiness(prepDataDir, preparation) {
-        return this.readinessCache.get(prepDataDir, preparation.name, () => this.computePreparationReadinessUncached(prepDataDir, preparation));
-    }
-    computePreparationReadinessUncached(prepDataDir, preparation) {
-        const generatedAt = new Date().toISOString();
-        const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
-        const contextExists = existsSync(verifiableContextPath);
-        const verifiableContextTarget = createVerifiableContextTestTarget(verifiableContextPath, preparation.name, buildPlanIdForSourcePreparationConfig(preparation) ?? DEFAULT_BUILD_PLAN_ID);
-        const contextReady = verifiableContextTarget.eligible;
-        const buildRun = this.listBuildRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
-        const verifyRun = this.listVerifyRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
-        const readinessRun = this.readLatestReadinessRun(prepDataDir, preparation.name);
-        const artifactStatuses = buildRun?.artifacts ?? [];
-        const hasArtifactContract = artifactStatuses.length > 0;
-        const artifactVerdict = aggregateArtifactVerdict(artifactStatuses);
-        const artifactFailures = artifactStatuses.filter((artifact) => artifact.status !== "ready");
-        const artifactProofs = artifactStatuses.flatMap((artifact) => artifact.proofs ?? []);
-        const requiredArtifactProofs = artifactProofs.filter((proof) => proof.required !== false);
-        const passedArtifactProofs = requiredArtifactProofs.filter((proof) => proof.passed);
-        const configuredChecks = preparation.checks.length;
-        const currentFingerprint = configuredChecks > 0 ? fingerprintReadinessChecks(preparation.checks) : null;
-        const readinessRunFingerprint = readinessRun?.checks_fingerprint ?? null;
-        const sourceResult = readinessTargetResult(readinessRun?.source_files, currentFingerprint, readinessRunFingerprint);
-        const contextResult = readinessTargetResult(readinessRun?.verifiable_context, currentFingerprint, readinessRunFingerprint);
-        const checksStale = Boolean(currentFingerprint && readinessRunFingerprint && currentFingerprint !== readinessRunFingerprint);
-        const buildCheck = (() => {
-            if (!buildRun) {
-                return {
-                    gate: "build-run",
-                    ok: false,
-                    status: "not-built",
-                    summary: "No Build run has built verifiable context yet.",
-                    artifact_path: contextReady ? verifiableContextPath : null,
-                };
-            }
-            if (buildRun.status === "succeeded") {
-                return {
-                    gate: "build-run",
-                    ok: contextReady,
-                    status: contextReady ? "built" : "failed",
-                    summary: contextReady
-                        ? "Latest Build run built verifiable context."
-                        : "Latest Build run finished, but verifiable context is missing.",
-                    run_id: buildRun.run_id,
-                    artifact_path: contextReady ? verifiableContextPath : null,
-                };
-            }
-            if (buildRun.status === "queued" || buildRun.status === "running") {
-                return {
-                    gate: "build-run",
-                    ok: false,
-                    status: "building",
-                    summary: "Latest Build run is still building verifiable context.",
-                    run_id: buildRun.run_id,
-                    artifact_path: contextExists ? verifiableContextPath : null,
-                };
-            }
-            return {
-                gate: "build-run",
-                ok: false,
-                status: "failed",
-                summary: buildRun.status === "cancelled"
-                    ? "Latest Build run was cancelled."
-                    : "Latest Build run failed.",
-                run_id: buildRun.run_id,
-                artifact_path: contextReady ? verifiableContextPath : null,
-            };
-        })();
-        const checks = [
-            {
-                gate: "preparation-config",
-                ok: true,
-                summary: "Preparation is saved in this control plane folder.",
-            },
-            {
-                gate: "verifiable-context",
-                ok: contextReady,
-                status: contextReady ? "built" : "not-built",
-                summary: contextReady
-                    ? "Verifiable context is built."
-                    : "Verifiable context has not been built.",
-                artifact_path: contextReady ? verifiableContextPath : null,
-            },
-            buildCheck,
-            {
-                gate: "artifact-checks",
-                ok: !hasArtifactContract || artifactVerdict === "ready",
-                status: !hasArtifactContract
-                    ? "not-configured"
-                    : artifactVerdict === "ready" ? "ready" : "not-ready",
-                summary: !hasArtifactContract
-                    ? "No Artifacts are declared by the selected Build Plan."
-                    : artifactVerdict === "ready"
-                        ? `${artifactStatuses.length} Artifact${artifactStatuses.length === 1 ? "" : "s"} ready; ${passedArtifactProofs.length}/${requiredArtifactProofs.length} required Artifact check${requiredArtifactProofs.length === 1 ? "" : "s"} passed.`
-                        : `${artifactFailures.length} Artifact${artifactFailures.length === 1 ? "" : "s"} not ready.`,
-            },
-            {
-                gate: "readiness-checks",
-                ok: true,
-                status: configuredChecks > 0 ? "built" : "not-configured",
-                summary: configuredChecks > 0
-                    ? `${configuredChecks} readiness check${configuredChecks === 1 ? "" : "s"} configured.`
-                    : "No optional readiness checks are configured.",
-            },
-            {
-                gate: "checks-current",
-                ok: !checksStale,
-                status: checksStale ? "stale" : "built",
-                summary: checksStale
-                    ? "Latest readiness result is stale for the current saved checks."
-                    : "Latest readiness result matches the current saved checks.",
-            },
-        ];
-        const status = (() => {
-            if (buildRun?.status === "queued" || buildRun?.status === "running")
-                return "building";
-            if (verifyRun?.status === "queued" || verifyRun?.status === "running")
-                return "checking";
-            if (buildRun?.status === "failed" || buildRun?.status === "cancelled")
-                return "failed";
-            if (!buildRun || !contextReady)
-                return "not-built";
-            if (hasArtifactContract && artifactVerdict !== "ready")
-                return "not-ready";
-            if (checksStale)
-                return "stale";
-            if (configuredChecks === 0)
-                return hasArtifactContract ? "ready" : "built";
-            if (!contextResult)
-                return "built";
-            return contextResult.total > 0 && contextResult.passed === contextResult.total ? "ready" : "not-ready";
-        })();
-        const ready = status === "ready";
-        return ReadinessSchema.parse({
-            kind: "interf-readiness-state",
-            version: 1,
-            generated_at: generatedAt,
-            preparation: preparation.name,
-            status,
-            ready,
-            summary: readinessSummaryForStatus(status),
-            verifiable_context_path: contextReady ? verifiableContextPath : null,
-            latest_build_run_id: buildRun?.run_id ?? null,
-            latest_test_run_id: verifyRun?.run_id ?? null,
-            build: buildCheck,
-            check_results: {
-                configured: configuredChecks,
-                fingerprint: currentFingerprint,
-                source_files: sourceResult,
-                verifiable_context: contextResult,
-            },
-            checks,
-        });
-    }
-    listSourceFiles(prepDataDir, preparationName) {
-        const config = loadSourceFolderConfig(prepDataDir);
-        const preparations = listSourcePreparationConfigs(config)
-            .filter((preparation) => !preparationName || preparation.name === preparationName);
-        // 0.13+ source binding: the source folder is the user-supplied
-        // absolute path on `source_folder.path`. `preparation.path` is the
-        // verifiable-context name inside `prepDataDir` (legacy field; in the
-        // current Preparation layout it equals `preparation.name`). Walk
-        // the actual source bytes, not the verifiable-context subdir.
-        const sourceFolderPath = resolveConfiguredSourceFolderPath(prepDataDir, config) ?? prepDataDir;
-        return preparations.flatMap((preparation) => {
-            const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
-            // Cache by source-folder root mtime so identical UI polls do not
-            // re-walk and re-stat the entire tree. The cache imposes a short
-            // TTL (see runtime-caches.ts) so deeper changes are still picked
-            // up promptly.
-            const cacheKey = `${preparation.name}\0${sourceFolderPath}\0${verifiableContextPath}`;
-            return this.sourceFilesCache.get(cacheKey, sourceFolderPath, () => {
-                return discoverSourceFiles(sourceFolderPath, verifiableContextPath).sourceFiles.map((relativePath) => {
-                    const absolutePath = join(sourceFolderPath, relativePath);
-                    let sizeBytes = 0;
-                    let modifiedAt = null;
-                    try {
-                        const stat = statSync(absolutePath);
-                        sizeBytes = stat.size;
-                        modifiedAt = stat.mtime.toISOString();
-                    }
-                    catch {
-                        sizeBytes = 0;
-                        modifiedAt = null;
-                    }
-                    return SourceFileResourceSchema.parse({
-                        preparation: preparation.name,
-                        path: relativePath,
-                        absolute_path: absolutePath,
-                        size_bytes: sizeBytes,
-                        modified_at: modifiedAt,
-                        source_folder_path: sourceFolderPath,
-                    });
-                });
-            });
-        });
-    }
-    listBuildPlans(prepDataDir) {
-        // The Build Plan choices list is dominated by repeated reads of
-        // build-plan.json + context-interface across bundled, user-library, and
-        // Preparation-local Build Plan package roots. Key the cache off mtimes; if
-        // any of them changes (a new local Build Plan, an edit to the user
-        // library, etc.) the cache misses and we re-resolve.
-        const builtinRoot = join(PACKAGE_ROOT, "public-repo", "build-plans");
-        const localRoot = preparationBuildPlansRoot(asPreparationDataDir(prepDataDir));
-        const userRoot = userBuildPlansRoot();
-        return this.buildPlanListingCache.get(prepDataDir, [builtinRoot, localRoot, userRoot], () => {
-            const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
-            const choices = listBuildPlanChoices(prepDataDir);
-            return choices.map((buildPlan) => {
-                const activeForPreparations = preparations
-                    .filter((preparation) => buildPlanIdForSourcePreparationConfig(preparation) === buildPlan.id)
-                    .map((preparation) => preparation.name);
-                return buildBuildPlanResource({
-                    id: buildPlan.id,
-                    path: resolveBuildPlanPackageSourcePath(prepDataDir, buildPlan.id) ?? buildPlan.id,
-                    label: buildPlan.label,
-                    hint: buildPlan.hint,
-                    purpose: buildPlan.purpose,
-                    inputs: buildPlan.inputs,
-                    source_kind: buildPlan.scope === "builtin" ? "builtin" : "local",
-                    built_in: buildPlan.scope === "builtin",
-                    active_for_preparations: activeForPreparations,
-                    artifacts: buildPlan.contextInterface?.artifacts ?? [],
-                    stages: buildPlan.stages.map((stage) => ({
-                        id: stage.id,
-                        label: stage.label,
-                        description: stage.description,
-                        contract_type: stage.contractType,
-                        skill_dir: stage.skillDir,
-                        role: stage.role && stage.role.trim().length > 0 ? stage.role : "general",
-                        reads: stage.reads,
-                        writes: stage.writes,
-                    })),
-                });
-            });
-        });
-    }
-    getBuildPlanResource(prepDataDir, buildPlanId) {
-        return this.listBuildPlans(prepDataDir).find((buildPlan) => buildPlan.id === buildPlanId) ?? null;
-    }
-    listJobs(prepDataDir) {
-        return byCreatedAtDesc(listJsonFiles(localJobsRoot(prepDataDir))
-            .map(readLocalJobRunAt)
-            .filter((run) => run !== null));
-    }
-    getJob(prepDataDir, runId) {
-        return this.listJobs(prepDataDir).find((run) => run.run_id === runId) ?? null;
-    }
-    getJobEvents(prepDataDir, runId) {
-        return this.getJob(prepDataDir, runId)?.events ?? null;
-    }
-    getExecutorStatus() {
-        const checkedAt = new Date().toISOString();
-        try {
-            const resolved = resolveAgent();
-            const currentName = resolved.agent?.name ?? configuredAgentName();
-            const availableExecutors = detectedExecutorOptions(currentName);
-            if (!resolved.agent) {
-                return LocalExecutorStatusSchema.parse({
-                    kind: "interf-local-executor-status",
-                    version: 1,
-                    status: "unavailable",
-                    checked_at: checkedAt,
-                    executor: null,
-                    available_executors: availableExecutors,
-                    message: resolved.error ?? "No supported local coding agent is configured.",
-                });
-            }
-            return LocalExecutorStatusSchema.parse({
-                kind: "interf-local-executor-status",
-                version: 1,
-                status: "connected",
-                checked_at: checkedAt,
-                executor: {
-                    name: resolved.agent.name,
-                    display_name: resolved.agent.displayName,
-                    command: resolved.agent.command,
-                },
-                available_executors: availableExecutors.length > 0
-                    ? availableExecutors
-                    : [{
-                            name: resolved.agent.name,
-                            display_name: resolved.agent.displayName,
-                            command: resolved.agent.command,
-                            current: true,
-                        }],
-                message: `${resolved.agent.displayName} is configured for local Interf actions.`,
-            });
-        }
-        catch (error) {
-            const currentName = configuredAgentName();
-            return LocalExecutorStatusSchema.parse({
-                kind: "interf-local-executor-status",
-                version: 1,
-                status: "unavailable",
-                checked_at: checkedAt,
-                executor: null,
-                available_executors: detectedExecutorOptions(currentName),
-                message: error instanceof Error ? error.message : String(error),
-            });
-        }
-    }
-    selectExecutor(requestValue) {
-        const request = LocalExecutorSelectRequestSchema.parse(requestValue);
-        const selected = detectAgents()
-            .filter(supportsAutomatedRuns)
-            .find((agent) => agent.name === request.agent);
-        if (!selected) {
-            throw new Error(`Local agent "${request.agent}" is not detected or cannot run Interf runs.`);
-        }
-        const current = loadUserConfig();
-        saveUserConfig({
-            agent: selected.name,
-            agentCommand: selected.command,
-            skillsInstalled: current?.skillsInstalled ?? false,
-            initialized: current?.initialized ?? new Date().toISOString(),
-        });
-        // Mirror the selection into the 0.15 role-map. `setActiveAgent`
-        // also sweeps any role still pointing at the previous active so
-        // single-active-agent setups stay coherent across CLIs.
-        try {
-            setActiveAgent(selected.name);
-        }
-        catch {
-            // Best effort — the registry update is convenience for the new
-            // role-aware path. The user_config.json write above is the
-            // source of truth for the legacy `getExecutorStatus()`.
-        }
-        return this.getExecutorStatus();
-    }
-    // ─── 0.15 connected-agents primitive ─────────────────────────────
-    /**
-     * Snapshot of the merged agents registry (built-in detected + custom)
-     * with the current role-map and resolved active agent.
-     */
-    getAgentsRegistry() {
-        const registry = loadAgentsRegistry();
-        return {
-            agents: registry.agents,
-            role_map: registry.roleMap,
-            active_agent: registry.activeAgent,
-        };
-    }
-    registerCustomAgent(input) {
-        registerCustomAgent(input);
-        return this.getAgentsRegistry();
-    }
-    unregisterCustomAgent(name) {
-        unregisterCustomAgent(name);
-        return this.getAgentsRegistry();
-    }
-    patchAgentsRoleMap(patch) {
-        patchRoleMap(patch);
-        const registry = loadAgentsRegistry();
-        return {
-            role_map: registry.roleMap,
-            active_agent: registry.activeAgent,
-        };
-    }
-    listActionProposals(prepDataDir) {
-        return byCreatedAtDesc(listJsonFiles(actionProposalsRoot(prepDataDir))
-            .map(readActionProposalAt)
-            .filter((proposal) => proposal !== null));
-    }
-    getActionProposal(prepDataDir, proposalId) {
-        return this.listActionProposals(prepDataDir).find((proposal) => proposal.proposal_id === proposalId) ?? null;
-    }
-    async createActionProposal(prepDataDir, requestValue) {
-        const request = ActionProposalCreateRequestSchema.parse(requestValue);
-        const proposal = ActionProposalResourceSchema.parse({
-            ...(await this.buildActionProposal(prepDataDir, request)),
-            client_origin: request.client_origin,
-        });
-        this.writeActionProposal(prepDataDir, proposal);
-        return proposal;
-    }
-    async decideActionProposal(prepDataDir, proposalId, requestValue) {
-        const decision = ActionProposalApprovalRequestSchema.parse(requestValue);
-        const current = this.getActionProposal(prepDataDir, proposalId);
-        if (!current)
-            return null;
-        if (current.status !== "awaiting_approval") {
-            throw new Error(`Action proposal "${proposalId}" is already ${current.status}.`);
-        }
-        const now = new Date().toISOString();
-        const decided = ActionProposalResourceSchema.parse({
-            ...current,
-            status: decision.approved ? "approved" : "denied",
-            updated_at: now,
-            approval: {
-                approved: decision.approved,
-                decided_at: now,
-                ...(decision.note ? { note: decision.note } : {}),
-            },
-        });
-        this.writeActionProposal(prepDataDir, decided);
-        if (!decision.approved)
-            return decided;
-        try {
-            const submission = await this.submitActionProposal(prepDataDir, decided);
-            const submitted = ActionProposalResourceSchema.parse({
-                ...decided,
-                status: "submitted",
-                updated_at: new Date().toISOString(),
-                submitted_run_id: submission.runId,
-                submitted_run_type: submission.runType,
-            });
-            this.writeActionProposal(prepDataDir, submitted);
-            return submitted;
-        }
-        catch (error) {
-            const failed = ActionProposalResourceSchema.parse({
-                ...decided,
-                status: "failed",
-                updated_at: new Date().toISOString(),
-                error: error instanceof Error ? error.message : String(error),
-            });
-            this.writeActionProposal(prepDataDir, failed);
-            return failed;
-        }
-    }
-    listRunObservability(prepDataDir) {
-        return [
-            ...this.listBuildRuns(prepDataDir).map((resource) => buildRunToObservability({
-                ...resource.run,
-                readiness: this.getReadiness(prepDataDir, resource.run.preparation),
-            })),
-            ...this.listVerifyRuns(prepDataDir).map(verifyRunToObservability),
-            ...this.listJobs(prepDataDir).map(jobRunToObservability),
-        ].sort((left, right) => {
-            const leftTime = timestampKey(left.started_at ?? left.created_at ?? left.finished_at);
-            const rightTime = timestampKey(right.started_at ?? right.created_at ?? right.finished_at);
-            return rightTime - leftTime;
-        });
-    }
-    getRunObservability(prepDataDir, runId) {
-        return this.listRunObservability(prepDataDir).find((run) => run.run_id === runId) ?? null;
-    }
-    /**
-     * Build Plan Activity runs: every Build Plan draft or improvement job whose
-     * Build Plan id matches `buildPlanId`. Surfaced through
-     * `GET /v1/build-plans/<id>/runs` so Build Plan detail can show the full
-     * audit trail of authoring + improvement work.
-     */
-    listBuildPlanRuns(prepDataDir, buildPlanId) {
-        return this.listRunObservability(prepDataDir).filter((run) => {
-            if (run.build_plan !== buildPlanId)
-                return false;
-            return (run.run_type === "build-plan-draft" ||
-                run.run_type === "build-plan-improvement");
-        });
-    }
-    createJobRun(prepDataDir, requestValue) {
-        const request = LocalJobRunCreateRequestSchema.parse(requestValue);
-        const runId = createRunId("job");
-        const now = new Date().toISOString();
-        const run = LocalJobRunResourceSchema.parse({
-            kind: "interf-local-job-run",
-            version: 1,
-            run_id: runId,
-            job_type: request.job_type,
-            status: "running",
-            title: request.title,
-            ...(request.preparation !== undefined ? { preparation: request.preparation } : {}),
-            ...(request.build_plan !== undefined ? { build_plan: request.build_plan } : {}),
-            ...(request.source_path !== undefined ? { source_path: request.source_path } : {}),
-            ...(request.output_path !== undefined ? { output_path: request.output_path } : {}),
-            ...(request.agent !== undefined ? { agent: request.agent } : {}),
-            created_at: now,
-            started_at: now,
-            steps: request.steps.map((step) => ({
-                ...step,
-                status: "queued",
-            })),
-            events: [
-                {
-                    type: "job.started",
-                    event_id: createRunEventId("event"),
-                    run_id: runId,
-                    timestamp: now,
-                    message: request.title,
-                },
-            ],
-        });
-        this.writeJobRun(prepDataDir, run);
-        return run;
-    }
-    appendJobRunEvent(prepDataDir, runId, requestValue) {
-        const request = LocalJobEventAppendRequestSchema.parse(requestValue);
-        const current = this.getJob(prepDataDir, runId);
-        if (!current)
-            return null;
-        const event = {
-            type: request.type,
-            event_id: createRunEventId("event"),
-            run_id: runId,
-            timestamp: new Date().toISOString(),
-            ...(request.step_id ? { step_id: request.step_id } : {}),
-            ...(request.message ? { message: request.message } : {}),
-            ...(request.artifact ? { artifact: request.artifact } : {}),
-            ...(request.input ? { input: request.input } : {}),
-            ...(request.output ? { output: request.output } : {}),
-        };
-        const next = LocalJobRunResourceSchema.parse(applyEventToLocalJob(current, event));
-        this.writeJobRun(prepDataDir, next);
-        return next;
-    }
-    async createReadinessCheckDraftRun(prepDataDir, requestValue) {
-        const request = ReadinessCheckDraftCreateRequestSchema.parse(requestValue);
-        const job = this.createJobRun(prepDataDir, {
-            job_type: "readiness-check-draft",
-            title: `Draft readiness checks for ${request.preparation}`,
-            preparation: request.preparation,
-            source_path: request.source_folder_path,
-            steps: [
-                {
-                    id: "read-source",
-                    label: "Read source files",
-                    input: {
-                        preparation: request.preparation,
-                        source_folder_path: request.source_folder_path,
-                    },
-                },
-                {
-                    id: "agent-draft",
-                    label: "Draft readiness checks",
-                    input: {
-                        about: request.about ?? null,
-                        target_count: request.target_count,
-                    },
-                },
-                {
-                    id: "normalize-checks",
-                    label: "Normalize saved readiness checks",
-                },
-            ],
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.started",
-            step_id: "read-source",
-            message: "Reading source files for readiness-check evidence.",
-            input: {
-                preparation: request.preparation,
-                source_folder_path: request.source_folder_path,
-            },
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.completed",
-            step_id: "read-source",
-            message: "Source folder is ready for drafting readiness checks.",
-            output: {
-                preparation: request.preparation,
-                source_folder_path: request.source_folder_path,
-            },
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.started",
-            step_id: "agent-draft",
-            message: "Drafting saved readiness checks from the source files.",
-            input: {
-                about: request.about ?? null,
-                target_count: request.target_count,
-            },
-        });
-        void this.runReadinessCheckDraftInBackground(prepDataDir, request, job.run_id);
-        return this.getJob(prepDataDir, job.run_id) ?? job;
-    }
-    applyBuildPlanChange(prepDataDir, requestValue) {
-        const request = BuildPlanChangeCreateRequestSchema.parse(requestValue);
-        const buildPlanId = request.build_plan;
-        const outputPath = request.operation === "duplicate"
-            ? buildPlanDefinitionPath(prepDataDir, request.new_build_plan_id)
-            : buildPlanDefinitionPath(prepDataDir, buildPlanId);
-        if (request.operation === "duplicate") {
-            if (resolveBuildPlanPackageSourcePath(prepDataDir, request.new_build_plan_id)) {
-                throw new Error(`Build Plan "${request.new_build_plan_id}" already exists.`);
-            }
-            if (!resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId)) {
-                throw new Error(`Build Plan "${buildPlanId}" does not exist.`);
-            }
-            const label = request.label ?? buildPlanLabelFromId(request.new_build_plan_id);
-            const hint = request.hint ?? `Duplicate of ${buildPlanId}`;
-            const buildPlanPath = seedLocalBuildPlanPackageFromBase({
-                prepDataDir,
-                baseBuildPlanId: buildPlanId,
-                buildPlanId: request.new_build_plan_id,
-                label,
-                hint,
-            });
-            this.buildPlanListingCache.invalidate(prepDataDir);
-            return BuildPlanChangeResultSchema.parse({
-                kind: "interf-build-plan-change-result",
-                version: 1,
-                operation: "duplicate",
-                build_plan: buildPlanId,
-                new_build_plan_id: request.new_build_plan_id,
-                updated_preparations: [],
-                build_plan_path: buildPlanPath,
-                changed: true,
-                message: `Duplicated Build Plan ${buildPlanId} as ${request.new_build_plan_id}.`,
-            });
-        }
-        if (request.confirmation !== buildPlanId) {
-            throw new Error(`Type ${buildPlanId} to confirm Build Plan removal.`);
-        }
-        const localBuildPlanPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
-        if (buildPlanId === DEFAULT_BUILD_PLAN_ID || !existsSync(localBuildPlanPath)) {
-            throw new Error(`Build Plan "${buildPlanId}" is not a removable local Build Plan.`);
-        }
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
-        const updatedPreparations = preparations
-            .filter((preparation) => buildPlanIdForSourcePreparationConfig(preparation) === buildPlanId);
-        if (updatedPreparations.length > 0) {
-            saveSourceFolderConfig(prepDataDir, {
-                preparations: preparations.map((preparation) => detachBuildPlanFromPreparation(preparation, buildPlanId)),
-            });
-            // Detaching a Build Plan changes readiness shape for those Preparations.
-            for (const preparation of updatedPreparations) {
-                this.readinessCache.invalidatePreparation(prepDataDir, preparation.name);
-            }
-        }
-        rmSync(outputPath, { recursive: true, force: true });
-        this.buildPlanListingCache.invalidate(prepDataDir);
-        return BuildPlanChangeResultSchema.parse({
-            kind: "interf-build-plan-change-result",
-            version: 1,
-            operation: "remove",
-            build_plan: buildPlanId,
-            updated_preparations: updatedPreparations.map((preparation) => preparation.name),
-            build_plan_path: outputPath,
-            changed: true,
-            message: updatedPreparations.length > 0
-                ? `Removed Build Plan ${buildPlanId} and cleared it from ${updatedPreparations.length} Preparation(s).`
-                : `Removed Build Plan ${buildPlanId}.`,
-        });
-    }
-    applyPreparationSetup(prepDataDir, requestValue) {
-        const request = PreparationSetupCreateRequestSchema.parse(requestValue);
-        const preparationConfig = request.preparation;
-        const buildPlanId = buildPlanIdForSourcePreparationConfig(preparationConfig);
-        if (request.setup_mode === "select-build-plan" && !buildPlanId) {
-            throw new Error("Build Plan is required when selecting a Build Plan for a Preparation.");
-        }
-        const normalizedPreparationConfig = buildPlanId
-            ? { ...preparationConfig, build_plan: buildPlanId }
-            : (() => {
-                const { build_plan: _ignoredBuildPlan, ...withoutBuildPlan } = preparationConfig;
-                return withoutBuildPlan;
-            })();
-        const sourceFolderPath = resolveSourcePreparationPath(prepDataDir, normalizedPreparationConfig);
-        if (!existsSync(sourceFolderPath) || !statSync(sourceFolderPath).isDirectory()) {
-            throw new Error(`Source folder "${preparationConfig.path}" is not available.`);
-        }
-        upsertSourcePreparationConfig(prepDataDir, normalizedPreparationConfig);
-        // The Preparation's bound source folder + Build Plan may have changed:
-        // bust the per-preparation readiness, runs, and Build Plan listing
-        // caches so the next read reflects the new shape.
-        this.readinessCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
-        this.buildRunCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
-        this.verifyRunCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
-        this.buildPlanListingCache.invalidate(prepDataDir);
-        const operation = request.setup_mode === "select-build-plan" ? "select-build-plan" : "create";
-        return PreparationSetupResultSchema.parse({
-            kind: "interf-preparation-setup-result",
-            version: 1,
-            operation,
-            preparation: normalizedPreparationConfig.name,
-            build_plan: buildPlanId ?? null,
-            source_folder_path: sourceFolderPath,
-            config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
-            verifiable_context_path: preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), normalizedPreparationConfig.name),
-            changed: true,
-            message: operation === "select-build-plan"
-                ? `Preparation ${normalizedPreparationConfig.name} now uses Build Plan ${buildPlanId}.`
-                : buildPlanId
-                    ? `Preparation ${normalizedPreparationConfig.name} is saved with Build Plan ${buildPlanId}.`
-                    : `Preparation ${normalizedPreparationConfig.name} is saved. Draft or select a Build Plan before building.`,
-        });
-    }
-    applyPreparationChange(prepDataDir, requestValue) {
-        const request = PreparationChangeCreateRequestSchema.parse(requestValue);
-        if (request.confirmation !== request.preparation) {
-            throw new Error(`Type ${request.preparation} to confirm Preparation removal.`);
-        }
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), request.preparation);
-        if (!preparation) {
-            throw new Error(`Preparation "${request.preparation}" is not saved.`);
-        }
-        removeSourcePreparationConfig(prepDataDir, request.preparation);
-        this.readinessCache.invalidatePreparation(prepDataDir, request.preparation);
-        this.buildRunCache.invalidatePreparation(prepDataDir, request.preparation);
-        this.verifyRunCache.invalidatePreparation(prepDataDir, request.preparation);
-        this.buildPlanListingCache.invalidate(prepDataDir);
-        return PreparationChangeResultSchema.parse({
-            kind: "interf-preparation-change-result",
-            version: 1,
-            operation: "remove",
-            preparation: request.preparation,
-            config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
-            verifiable_context_path: preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), request.preparation),
-            verifiable_context_retained: true,
-            changed: true,
-            message: `Removed Preparation ${request.preparation}. Verifiable context files were retained.`,
-        });
-    }
-    applyReset(prepDataDir, requestValue) {
-        const request = ResetRequestSchema.parse(requestValue);
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), request.preparation);
-        if (!preparation) {
-            throw new Error(`Preparation "${request.preparation}" is not saved.`);
-        }
-        const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), request.preparation);
-        if (!existsSync(verifiableContextPath)) {
-            throw new Error(`Verifiable context for Preparation "${request.preparation}" does not exist.`);
-        }
-        resetBuildGeneratedState(verifiableContextPath, request.scope);
-        // Reset wipes generated state, including saved build/test/readiness records.
-        this.buildRunCache.invalidatePreparation(prepDataDir, request.preparation);
-        this.verifyRunCache.invalidatePreparation(prepDataDir, request.preparation);
-        this.readinessCache.invalidatePreparation(prepDataDir, request.preparation);
-        return ResetResultSchema.parse({
-            kind: "interf-reset-result",
-            version: 1,
-            preparation: request.preparation,
-            scope: request.scope,
-            verifiable_context_path: verifiableContextPath,
-            changed: true,
-            message: `Reset ${request.scope} state for Preparation ${request.preparation}.`,
-        });
-    }
-    async createBuildPlanAuthoringRun(prepDataDir, requestValue, jobType = "build-plan-draft") {
-        const parsedRequest = BuildPlanAuthoringCreateRequestSchema.parse(requestValue);
-        const savedPreparation = parsedRequest.preparation
-            ? findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), parsedRequest.preparation)
-            : null;
-        const request = {
-            ...parsedRequest,
-            requested_artifacts: parsedRequest.requested_artifacts.length > 0
-                ? parsedRequest.requested_artifacts
-                : savedPreparation?.requested_artifacts ?? [],
-            source_profile: parsedRequest.source_profile ?? savedPreparation?.source_profile ?? null,
-        };
-        const isImprovement = jobType === "build-plan-improvement";
-        const job = this.createJobRun(prepDataDir, {
-            job_type: jobType,
-            title: isImprovement ? `Improve Build Plan ${request.build_plan_id}` : `Draft Build Plan ${request.build_plan_id}`,
-            preparation: request.preparation ?? null,
-            build_plan: request.build_plan_id,
-            source_path: request.source_folder_path,
-            output_path: preparationBuildPlanPackagePath(asPreparationDataDir(prepDataDir), request.build_plan_id),
-            steps: [
-                {
-                    id: "inspect-source",
-                    label: "Inspect source files",
-                    input: {
-                        preparation: request.preparation ?? null,
-                        source_folder_path: request.source_folder_path,
-                        checks: request.checks.length,
-                        requested_artifacts: request.requested_artifacts.length,
-                    },
-                },
-                {
-                    id: "draft-package",
-                    label: isImprovement ? "Improve Build Plan definition" : "Draft Build Plan definition",
-                    input: {
-                        build_plan_id: request.build_plan_id,
-                        label: request.label,
-                        task_prompt: request.task_prompt,
-                        requested_artifacts: request.requested_artifacts.length,
-                        artifact_requirements: request.artifact_requirements.length,
-                    },
-                },
-                {
-                    id: "validate-package",
-                    label: "Validate Build Plan definition",
-                    input: {
-                        build_plan_id: request.build_plan_id,
-                    },
-                },
-            ],
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.started",
-            step_id: "inspect-source",
-            message: isImprovement ? "Inspecting source files for Build Plan improvement." : "Inspecting source files for Build Plan drafting.",
-            input: {
-                preparation: request.preparation ?? null,
-                source_folder_path: request.source_folder_path,
-                checks: request.checks.length,
-                requested_artifacts: request.requested_artifacts.length,
-            },
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.completed",
-            step_id: "inspect-source",
-            message: "Source context is ready.",
-            output: {
-                source_folder_path: request.source_folder_path,
-                checks: request.checks.length,
-                requested_artifacts: request.requested_artifacts.length,
-            },
-        });
-        this.appendJobRunEvent(prepDataDir, job.run_id, {
-            type: "step.started",
-            step_id: "draft-package",
-            message: isImprovement ? "Improving Build Plan definition." : "Drafting Build Plan definition.",
-            input: {
-                build_plan_id: request.build_plan_id,
-                label: request.label,
-                task_prompt: request.task_prompt,
-                requested_artifacts: request.requested_artifacts.length,
-                artifact_requirements: request.artifact_requirements.length,
-            },
-        });
-        void this.runBuildPlanAuthoringInBackground(prepDataDir, request, job.run_id);
-        return this.getJob(prepDataDir, job.run_id) ?? job;
-    }
-    listVerifiableContexts(prepDataDir) {
-        return listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
-            .map((preparation) => this.getVerifiableContext(prepDataDir, preparation.name))
-            .filter((context) => context !== null);
-    }
-    getVerifiableContext(prepDataDir, preparationName) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
-        if (!preparation)
-            return null;
-        const path = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
-        const config = readInterfConfig(path);
-        const buildRuns = this.listBuildRunsForPreparation(prepDataDir, preparation.name);
-        const verifyRuns = this.listVerifyRunsForPreparation(prepDataDir, preparation.name);
-        const readiness = this.computePreparationReadiness(prepDataDir, preparation);
-        const buildPlan = config?.build_plan ?? buildPlanIdForSourcePreparationConfig(preparation);
-        return VerifiableContextResourceSchema.parse({
-            preparation: preparation.name,
-            path,
-            exists: existsSync(path),
-            readiness,
-            build_plan: buildPlan,
-            latest_build_run_id: buildRuns[0]?.run_id ?? null,
-            latest_test_run_id: verifyRuns[0]?.run_id ?? null,
-            artifacts: uniqueArtifacts(buildRuns[0]?.stages.flatMap((stage) => stage.artifacts) ?? []),
-        });
-    }
-    listBuildRuns(prepDataDir) {
-        return byCreatedAtDesc(listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
-            .flatMap((preparation) => this.listBuildRunsForPreparation(prepDataDir, preparation.name))).map((run) => BuildRunResourceSchema.parse({ run }));
-    }
-    listBuildRunsForPreparation(prepDataDir, preparationName) {
-        return this.buildRunCache.get(prepDataDir, preparationName, () => {
-            const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparationName);
-            return byCreatedAtDesc(listJsonFiles(buildRunsRoot(verifiableContextPath))
-                .map(readBuildRunAt)
-                .filter((run) => run !== null)).map((run) => this.hydrateBuildRunFromRuntime(prepDataDir, verifiableContextPath, run));
-        }, (run) => run.run_id);
-    }
-    getBuildRun(prepDataDir, runId) {
-        // Fast path: if the runId was seen during a recent listing, look up
-        // its owning preparation directly and return that preparation's
-        // cached entry instead of scanning every preparation on disk.
-        const known = this.buildRunCache.preparationFor(prepDataDir, runId);
-        if (known) {
-            const found = this.listBuildRunsForPreparation(prepDataDir, known).find((entry) => entry.run_id === runId);
-            if (found)
-                return BuildRunResourceSchema.parse({ run: found });
-        }
-        // Slow path: scan all preparations. Falls through after a cache
-        // miss for an in-flight run created before this process restarted.
-        for (const resource of this.listBuildRuns(prepDataDir)) {
-            if (resource.run.run_id === runId)
-                return resource;
-        }
-        return null;
-    }
-    getBuildRunEvents(prepDataDir, runId) {
-        return this.getBuildRun(prepDataDir, runId)?.run.events ?? null;
-    }
-    getBuildRunProof(prepDataDir, runId) {
-        const run = this.getBuildRun(prepDataDir, runId)?.run;
-        if (!run)
-            return null;
-        return run.stages
-            .map((stage) => stage.latest_proof ?? null)
-            .filter((proof) => proof !== null);
-    }
-    getBuildRunArtifacts(prepDataDir, runId) {
-        const run = this.getBuildRun(prepDataDir, runId)?.run;
-        if (!run)
-            return null;
-        return uniqueArtifacts(run.stages.flatMap((stage) => stage.artifacts));
-    }
-    async createBuildRun(prepDataDir, requestValue) {
-        const request = BuildRunCreateRequestSchema.parse(requestValue);
-        const preparationConfig = this.resolvePreparationConfig(prepDataDir, request.preparation, {
-            build_plan: request.build_plan,
-            max_attempts: request.max_attempts,
-            max_loops: request.max_loops,
-        });
-        const verifiableContextPath = this.ensureVerifiableContextForRun(prepDataDir, preparationConfig);
-        const runId = createRunId("build");
-        const now = new Date().toISOString();
-        const buildPlan = getBuildPlan(requireSelectedBuildPlan(preparationConfig), {
-            prepDataDir,
-        });
-        const stageTotal = buildPlan.stages.length;
-        const run = BuildRunSchema.parse({
-            kind: "interf-build-run",
-            version: 1,
-            run_id: runId,
-            status: "running",
-            preparation: preparationConfig.name,
-            build_plan: buildPlan.id,
-            backend: "native",
-            source_path: resolveSourcePreparationPath(prepDataDir, preparationConfig),
-            verifiable_context_path: verifiableContextPath,
-            created_at: now,
-            started_at: now,
-            stages: buildPlan.stages
-                .map((stage, index) => {
-                return {
-                    run_id: runId,
-                    stage_id: stage.id,
-                    stage_label: stage.label,
-                    stage_index: index,
-                    stage_total: stageTotal,
-                    status: "queued",
-                    contract: {
-                        stage_label: stage.label,
-                        stage_index: index,
-                        stage_total: stageTotal,
-                        reads: stage.reads,
-                        writes: stage.writes,
-                    },
-                    artifacts: [],
-                };
-            }),
-            events: [],
-        });
-        this.writeBuildRun(prepDataDir, verifiableContextPath, run);
-        this.activeBuildRuns.set(runId, {
-            prepDataDir,
-            verifiableContextPath,
-            preparation: preparationConfig.name,
-            cancelled: false,
-        });
-        await this.recordBuildRunEvent(prepDataDir, verifiableContextPath, runId, {
-            type: "run.started",
-            event_id: createRunEventId("event"),
-            run_id: runId,
-            timestamp: now,
-            preparation: preparationConfig.name,
-            build_plan: buildPlan.id,
-            verifiable_context_path: verifiableContextPath,
-            backend: "native",
-        });
-        const sink = {
-            emit: (event) => this.recordBuildRunEvent(prepDataDir, verifiableContextPath, runId, event),
-        };
-        void this.runBuildInBackground(prepDataDir, request, {
-            runId,
-            sourcePath: prepDataDir,
-            verifiableContextPath,
-            preparationConfig,
-            events: sink,
-        });
-        const saved = this.readBuildRun(verifiableContextPath, runId) ?? run;
-        return BuildRunResourceSchema.parse({ run: saved });
-    }
-    /**
-     * Cancel an in-flight Build run. Marks the persisted record as
-     * `cancelled`, emits a `run.cancelled` event to capture the cancellation in
-     * the run timeline, and clears the active handle so retries may start a
-     * fresh run. If the run already finished, returns
-     * `{ cancelled: false, reason: "already finished" }` and persists nothing.
-     */
-    cancelBuildRun(runId) {
-        const handle = this.activeBuildRuns.get(runId);
-        if (!handle) {
-            // Either unknown or already terminal. The server route already 404s
-            // unknown ids before calling this, so anything reaching here is a run
-            // we already finalized.
-            return { cancelled: false, reason: "already finished" };
-        }
-        if (handle.cancelled) {
-            return { cancelled: false, reason: "already cancelled" };
-        }
-        const cancelledAt = new Date().toISOString();
-        handle.cancelled = true;
-        handle.cancelledAt = cancelledAt;
-        const current = this.readBuildRun(handle.verifiableContextPath, runId);
-        if (current && !isTerminalBuildRunStatus(current.status)) {
-            this.writeBuildRun(handle.prepDataDir, handle.verifiableContextPath, applyEventToBuildRun(current, {
-                type: "run.cancelled",
-                event_id: createRunEventId("event"),
-                run_id: runId,
-                timestamp: cancelledAt,
-                reason: "Build run cancelled by request.",
-            }));
-        }
-        return { cancelled: true };
-    }
-    /**
-     * Look up the run id previously associated with this idempotency key in
-     * `prepDataDir`. Returns null when the key is unknown or its TTL has
-     * elapsed. The preparation argument is required so that the same key in
-     * two different preparations always returns two different runs.
-     */
-    findIdempotentBuildRun(prepDataDir, key) {
-        const resolvedRoot = resolve(prepDataDir);
-        const bucket = this.idempotencyKeyCache.get(resolvedRoot);
-        if (!bucket)
-            return null;
-        const entry = bucket.get(key);
-        if (!entry)
-            return null;
-        if (entry.expiresAt <= Date.now()) {
-            // Opportunistic single-key prune. The bulk prune runs on writes
-            // when the cache crosses the size threshold (see
-            // {@link recordIdempotentBuildRun}).
-            bucket.delete(key);
-            if (bucket.size === 0)
-                this.idempotencyKeyCache.delete(resolvedRoot);
-            return null;
-        }
-        return entry.runId;
-    }
-    /**
-     * Cache the run id created (or returned) for this idempotency key in
-     * `prepDataDir`. Entries expire after `IDEMPOTENCY_TTL_MS`. Pruning
-     * is opportunistic: the previous implementation walked every entry on
-     * every read AND write, which was O(N) per request. Now we only sweep
-     * when the cache grows past {@link IDEMPOTENCY_PRUNE_THRESHOLD}.
-     */
-    recordIdempotentBuildRun(prepDataDir, key, runId) {
-        const resolvedRoot = resolve(prepDataDir);
-        let bucket = this.idempotencyKeyCache.get(resolvedRoot);
-        if (!bucket) {
-            bucket = new Map();
-            this.idempotencyKeyCache.set(resolvedRoot, bucket);
-        }
-        bucket.set(key, {
-            runId,
-            expiresAt: Date.now() + IDEMPOTENCY_TTL_MS,
-        });
-        if (this.totalIdempotencyEntries() > IDEMPOTENCY_PRUNE_THRESHOLD) {
-            this.pruneIdempotencyKeyCache();
-        }
-    }
-    /** Total cached idempotency entries across all preparations. */
-    totalIdempotencyEntries() {
-        let total = 0;
-        for (const bucket of this.idempotencyKeyCache.values())
-            total += bucket.size;
-        return total;
-    }
-    pruneIdempotencyKeyCache() {
-        const now = Date.now();
-        for (const [prepDataDir, bucket] of this.idempotencyKeyCache) {
-            for (const [key, entry] of bucket) {
-                if (entry.expiresAt <= now)
-                    bucket.delete(key);
-            }
-            if (bucket.size === 0)
-                this.idempotencyKeyCache.delete(prepDataDir);
-        }
-    }
-    /**
-     * Test seam: force the cached entry for `key` in `prepDataDir` to be
-     * expired so the next lookup returns null. Returns true when an entry was
-     * found and expired. Tests use this in place of fake timers because the
-     * idempotency TTL is one hour and faking `Date.now()` would destabilize
-     * unrelated runtime state.
-     */
-    expireIdempotencyKeyForTesting(prepDataDir, key) {
-        const bucket = this.idempotencyKeyCache.get(resolve(prepDataDir));
-        if (!bucket)
-            return false;
-        const entry = bucket.get(key);
-        if (!entry)
-            return false;
-        entry.expiresAt = Date.now() - 1;
-        return true;
-    }
-    listVerifyRuns(prepDataDir) {
-        return newestFirst(listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
-            .flatMap((preparation) => this.listVerifyRunsForPreparation(prepDataDir, preparation.name)));
-    }
-    listVerifyRunsForPreparation(prepDataDir, preparationName) {
-        return this.verifyRunCache.get(prepDataDir, preparationName, () => {
-            const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparationName);
-            return newestFirst(listJsonFiles(verifyRunsRoot(verifiableContextPath))
-                .map(readVerifyRunAt)
-                .filter((run) => run !== null));
-        }, (run) => run.run_id);
-    }
-    getVerifyRun(prepDataDir, runId) {
-        const known = this.verifyRunCache.preparationFor(prepDataDir, runId);
-        if (known) {
-            const found = this.listVerifyRunsForPreparation(prepDataDir, known).find((run) => run.run_id === runId);
-            if (found)
-                return found;
-        }
-        return this.listVerifyRuns(prepDataDir).find((run) => run.run_id === runId) ?? null;
-    }
-    async createVerifyRun(prepDataDir, requestValue) {
-        const request = VerifyRunCreateRequestSchema.parse(requestValue);
-        const preparationConfig = this.resolvePreparationConfig(prepDataDir, request.preparation);
-        const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparationConfig.name);
-        const verifiableContextTarget = createVerifiableContextTestTarget(verifiableContextPath, preparationConfig.name, buildPlanIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_BUILD_PLAN_ID);
-        const runId = createRunId("verify");
-        const now = new Date().toISOString();
-        const initial = VerifyRunResourceSchema.parse({
-            run_id: runId,
-            status: "running",
-            preparation: preparationConfig.name,
-            source_path: prepDataDir,
-            verifiable_context_path: verifiableContextTarget.eligible ? verifiableContextPath : null,
-            started_at: now,
-            readiness_run: null,
-            events: [],
-        });
-        this.writeVerifyRun(prepDataDir, verifiableContextPath, initial);
-        void this.runTestInBackground(prepDataDir, request, {
-            runId,
-            sourcePath: prepDataDir,
-            verifiableContextPath,
-            preparationConfig,
-        }, initial);
-        return initial;
-    }
-    async runBuildInBackground(prepDataDir, request, context) {
-        this.beginActiveRun();
-        try {
-            if (!this.handlers.createBuildRun) {
-                throw new Error("No build-run handler is configured for this local service.");
-            }
-            const result = LocalRunHandlerResultSchema.parse(await this.handlers.createBuildRun(request, context));
-            const wasCancelled = this.activeBuildRuns.get(context.runId)?.cancelled === true;
-            if (wasCancelled) {
-                // The run was cancelled while the handler was still running. The
-                // cancellation path already wrote a `cancelled` record; just refresh
-                // observability and skip emitting a second terminal event.
-                this.refreshBuildRunFromRuntime(prepDataDir, context.verifiableContextPath, context.runId);
-                await this.emitRuntimeDerivedEvents(prepDataDir, context.verifiableContextPath, context.runId);
-                await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
-                return;
-            }
-            this.refreshBuildRunFromRuntime(prepDataDir, context.verifiableContextPath, context.runId);
-            await this.emitRuntimeDerivedEvents(prepDataDir, context.verifiableContextPath, context.runId);
-            if (!result.ok) {
-                await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, {
-                    type: "run.failed",
-                    event_id: createRunEventId("event"),
-                    run_id: context.runId,
-                    timestamp: createRunEventTimestamp(),
-                    error: result.error ?? "Build run failed.",
-                });
-            }
-            else {
-                await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, {
-                    type: "run.completed",
-                    event_id: createRunEventId("event"),
-                    run_id: context.runId,
-                    timestamp: createRunEventTimestamp(),
-                    summary: "Verifiable context ready.",
-                });
-            }
-            await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
-            // 0.17 — emit per-Artifact billing events (stub form: JSONL).
-            // Production sink (Metronome HTTP) wires in 0.18+.
-            this.emitBillingEventsForRun(prepDataDir, context);
-        }
-        catch (error) {
-            await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, {
-                type: "run.failed",
-                event_id: createRunEventId("event"),
-                run_id: context.runId,
-                timestamp: createRunEventTimestamp(),
-                error: error instanceof Error ? error.message : String(error),
-            });
-            await this.recordBuildRunEvent(prepDataDir, context.verifiableContextPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
-        }
-        finally {
-            this.activeBuildRuns.delete(context.runId);
-            this.endActiveRun();
-        }
-    }
-    async runTestInBackground(prepDataDir, request, context, initial) {
-        this.beginActiveRun();
-        try {
-            if (!this.handlers.createVerifyRun) {
-                throw new Error("No verify-run handler is configured for this local service.");
-            }
-            const result = LocalRunHandlerResultSchema.parse(await this.handlers.createVerifyRun(request, context));
-            const readinessRun = result.readiness_run ?? this.readLatestReadinessRun(prepDataDir, context.preparationConfig.name);
-            const resultEvent = readinessRun
-                ? this.checksEvaluatedEvent(context.runId, readinessRun)
-                : null;
-            const nextWithoutReadiness = VerifyRunResourceSchema.parse({
-                ...initial,
-                status: result.ok ? "succeeded" : "failed",
-                finished_at: new Date().toISOString(),
-                readiness_run: readinessRun,
-                events: resultEvent ? [resultEvent] : [],
-                ...(!result.ok ? { error: result.error ?? "Readiness check failed." } : {}),
-            });
-            this.writeVerifyRun(prepDataDir, context.verifiableContextPath, nextWithoutReadiness);
-            const readiness = this.computePreparationReadiness(prepDataDir, context.preparationConfig);
-            const next = VerifyRunResourceSchema.parse({
-                ...nextWithoutReadiness,
-                readiness,
-                events: [
-                    ...nextWithoutReadiness.events,
-                    this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness),
-                ],
-            });
-            this.writeVerifyRun(prepDataDir, context.verifiableContextPath, next);
-        }
-        catch (error) {
-            const failedWithoutReadiness = VerifyRunResourceSchema.parse({
-                ...initial,
-                status: "failed",
-                finished_at: new Date().toISOString(),
-                error: error instanceof Error ? error.message : String(error),
-            });
-            this.writeVerifyRun(prepDataDir, context.verifiableContextPath, failedWithoutReadiness);
-            const readiness = this.computePreparationReadiness(prepDataDir, context.preparationConfig);
-            const next = VerifyRunResourceSchema.parse({
-                ...failedWithoutReadiness,
-                readiness,
-                events: [this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness)],
-            });
-            this.writeVerifyRun(prepDataDir, context.verifiableContextPath, next);
-        }
-        finally {
-            this.endActiveRun();
-        }
-    }
-    async runReadinessCheckDraftInBackground(prepDataDir, request, runId) {
-        this.beginActiveRun();
-        return this.runReadinessCheckDraftInBackgroundInner(prepDataDir, request, runId).finally(() => {
-            this.endActiveRun();
-        });
-    }
-    async runReadinessCheckDraftInBackgroundInner(prepDataDir, request, runId) {
-        try {
-            if (!this.handlers.createReadinessCheckDraft) {
-                throw new Error("No readiness-check-draft handler is configured for this local service.");
-            }
-            const result = ReadinessCheckDraftResultSchema.parse(await this.handlers.createReadinessCheckDraft(request, this.jobRunContext(prepDataDir, runId)));
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.completed",
-                step_id: "agent-draft",
-                message: `Drafted ${result.checks.length} readiness checks.`,
-                output: {
-                    checks: result.checks,
-                },
-            });
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.started",
-                step_id: "normalize-checks",
-                message: "Normalizing drafted readiness checks into saved check records.",
-                input: {
-                    checks: result.checks.length,
-                },
-            });
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.completed",
-                step_id: "normalize-checks",
-                message: `${result.checks.length} readiness checks ready for review.`,
-                output: {
-                    checks: result.checks.length,
-                },
-            });
-            this.setJobRunResult(prepDataDir, runId, result);
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "job.completed",
-                message: `Drafted ${result.checks.length} readiness checks.`,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.failed",
-                step_id: "agent-draft",
-                message,
-                output: {
-                    error: message,
-                },
-            });
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "job.failed",
-                message,
-            });
-        }
-    }
-    async runBuildPlanAuthoringInBackground(prepDataDir, request, runId) {
-        this.beginActiveRun();
-        return this.runBuildPlanAuthoringInBackgroundInner(prepDataDir, request, runId).finally(() => {
-            this.endActiveRun();
-        });
-    }
-    async runBuildPlanAuthoringInBackgroundInner(prepDataDir, request, runId) {
-        try {
-            if (!this.handlers.createBuildPlanAuthoringRun) {
-                throw new Error("No Build Plan-authoring handler is configured for this local service.");
-            }
-            const result = BuildPlanAuthoringResultSchema.parse(await this.handlers.createBuildPlanAuthoringRun(request, this.jobRunContext(prepDataDir, runId)));
-            this.setJobRunResult(prepDataDir, runId, result);
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: result.status === "executor-failed" ? "step.failed" : "step.completed",
-                step_id: "draft-package",
-                message: result.summary,
-                output: {
-                    status: result.status,
-                    changed: result.changed,
-                    build_plan_path: result.build_plan_path,
-                    shell_path: result.shell_path,
-                },
-            });
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.started",
-                step_id: "validate-package",
-                message: "Validating Build Plan package structure and stage contract.",
-                input: {
-                    build_plan_path: result.build_plan_path,
-                },
-            });
-            if (result.status === "updated" || result.status === "no-change") {
-                let selectedPreparation = null;
-                if (request.preparation) {
-                    const selected = this.resolvePreparationConfig(prepDataDir, request.preparation, {
-                        build_plan: request.build_plan_id,
-                    });
-                    upsertSourcePreparationConfig(prepDataDir, selected);
-                    this.readinessCache.invalidatePreparation(prepDataDir, selected.name);
-                    this.buildRunCache.invalidatePreparation(prepDataDir, selected.name);
-                    this.verifyRunCache.invalidatePreparation(prepDataDir, selected.name);
-                    this.buildPlanListingCache.invalidate(prepDataDir);
-                    selectedPreparation = selected.name;
-                }
-                this.appendJobRunEvent(prepDataDir, runId, {
-                    type: "step.completed",
-                    step_id: "validate-package",
-                    message: selectedPreparation
-                        ? `${result.summary} Selected Build Plan ${request.build_plan_id} for Preparation ${selectedPreparation}.`
-                        : result.summary,
-                    output: {
-                        status: result.status,
-                        validation: result.validation ?? null,
-                        selected_preparation: selectedPreparation,
-                    },
-                });
-                this.appendJobRunEvent(prepDataDir, runId, {
-                    type: "job.completed",
-                    message: selectedPreparation
-                        ? `${result.summary} Selected Build Plan ${request.build_plan_id} for Preparation ${selectedPreparation}.`
-                        : result.summary,
-                });
-            }
-            else {
-                this.appendJobRunEvent(prepDataDir, runId, {
-                    type: "step.failed",
-                    step_id: "validate-package",
-                    message: result.summary,
-                    output: {
-                        status: result.status,
-                        validation: result.validation ?? null,
-                    },
-                });
-                this.appendJobRunEvent(prepDataDir, runId, {
-                    type: "job.failed",
-                    message: result.summary,
-                });
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "step.failed",
-                step_id: "draft-package",
-                message,
-                output: {
-                    error: message,
-                },
-            });
-            this.appendJobRunEvent(prepDataDir, runId, {
-                type: "job.failed",
-                message,
-            });
-        }
-    }
-    jobRunContext(prepDataDir, runId) {
-        return {
-            runId,
-            sourcePath: prepDataDir,
-            emit: (event) => {
-                this.appendJobRunEvent(prepDataDir, runId, event);
-            },
-        };
-    }
-    defaultPreparationName(prepDataDir) {
-        const preparation = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))[0];
-        if (!preparation) {
-            throw new Error("No Preparation is saved in this control plane folder.");
-        }
-        return preparation.name;
-    }
-    async planActionProposal(prepDataDir, request) {
-        if (!this.handlers.planActionProposal) {
-            return ActionProposalPlanSchema.parse({
-                action_type: "clarification",
-                ...(request.preparation ? { preparation: request.preparation } : {}),
-                assistant_message: "No local action planner is configured for this Interf instance.",
-            });
-        }
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
-        let rawPlan;
-        try {
-            rawPlan = await this.handlers.planActionProposal(request, {
-                sourcePath: prepDataDir,
-                preparations,
-                preparationHealth: preparations.map((preparation) => {
-                    const readinessChecks = preparation.checks?.length ?? 0;
-                    const verifiableContextReady = hasVerifiableContextTestTarget(prepDataDir, preparation);
-                    return {
-                        name: preparation.name,
-                        readiness_checks: readinessChecks,
-                        verifiable_context_ready: verifiableContextReady,
-                        can_check_readiness: readinessChecks > 0 && verifiableContextReady,
-                        recommended_next_actions: verifiableContextReady
-                            ? readinessChecks > 0
-                                ? ["check readiness", "improve", "prepare again"]
-                                : ["draft readiness checks", "prepare again"]
-                            : ["prepare"],
-                    };
-                }),
-                sourceFolders: listSourceFolderChoices(prepDataDir),
-                recentProposals: this.listActionProposals(prepDataDir).slice(0, 5),
-            });
-        }
-        catch {
-            return ActionProposalPlanSchema.parse({
-                action_type: "clarification",
-                ...(request.preparation ? { preparation: request.preparation } : {}),
-                assistant_message: ACTION_PLANNER_CLARIFICATION_MESSAGE,
-            });
-        }
-        const parsed = ActionProposalPlanSchema.safeParse(sanitizeActionProposalPlan(rawPlan));
-        if (parsed.success)
-            return parsed.data;
-        return ActionProposalPlanSchema.parse({
-            action_type: "clarification",
-            ...(request.preparation ? { preparation: request.preparation } : {}),
-            assistant_message: ACTION_PLANNER_CLARIFICATION_MESSAGE,
-        });
-    }
-    directServiceActionClarification(options) {
-        const endpoint = directServiceEndpointForAction(options.actionType);
-        if (!endpoint) {
-            throw new Error(`Action "${options.actionType}" is not a direct deterministic service action.`);
-        }
-        const label = options.actionType === "preparation-setup"
-            ? "Preparation setup"
-            : options.actionType === "build-plan-change"
-                ? "Build Plan change"
-                : "Preparation change";
-        const now = new Date().toISOString();
-        return ActionProposalResourceSchema.parse({
-            kind: "interf-action-proposal",
-            version: 1,
-            proposal_id: createActionProposalId(),
-            status: "needs_clarification",
-            action_type: "clarification",
-            title: `${label} uses a direct service endpoint`,
-            summary: `${label} is deterministic and is not accepted through action proposals.`,
-            assistant_message: `${label} must be submitted directly to ${endpoint}. Action proposals are only for freeform planning or async local-agent-backed work.`,
-            message: options.message,
-            preparation: options.preparation ?? null,
-            build_plan: options.buildPlan ?? null,
-            request: {
-                message: options.message,
-                endpoint,
-                action_type: options.actionType,
-                ...(options.values ? { values: options.values } : {}),
-            },
-            created_at: now,
-            updated_at: now,
-            proposed_by_executor: this.getExecutorStatus().executor,
-            approval: null,
-            submitted_run_id: null,
-            submitted_run_type: null,
-            error: null,
-        });
-    }
-    async buildActionProposal(prepDataDir, request) {
-        const structuredPreparationSetup = PreparationSetupActionValuesSchema.safeParse(request.values);
-        const structuredBuildPlanAuthoring = BuildPlanAuthoringActionValuesSchema.safeParse(request.values);
-        const structuredActionType = actionTypeFromValues(request.values);
-        const structuredDirectActionType = structuredPreparationSetup.success
-            ? "preparation-setup"
-            : structuredActionType && directServiceEndpointForAction(structuredActionType)
-                ? structuredActionType
-                : null;
-        if (structuredDirectActionType) {
-            return this.directServiceActionClarification({
-                actionType: structuredDirectActionType,
-                message: request.message,
-                buildPlan: stringValue(request.values, "build_plan") ??
-                    stringValue(request.values, "build_plan_id") ??
-                    stringValue(request.values, "new_build_plan_id"),
-                preparation: request.preparation ?? stringValue(request.values, "preparation") ?? stringValue(request.values, "name"),
-                values: request.values,
-            });
-        }
-        const structuredPlanActionType = structuredBuildPlanAuthoring.success ? "build-plan-draft" : structuredActionType;
-        // Typed UI/CLI actions already carry the service contract; only freeform chat needs planner inference.
-        const plan = structuredPlanActionType
-            ? ActionProposalPlanSchema.parse({
-                action_type: structuredPlanActionType,
-                ...(request.preparation ? { preparation: request.preparation } : {}),
-            })
-            : await this.planActionProposal(prepDataDir, request);
-        const actionType = structuredPlanActionType ?? plan.action_type;
-        if (directServiceEndpointForAction(actionType)) {
-            return this.directServiceActionClarification({
-                actionType,
-                message: request.message,
-                buildPlan: plan.build_plan ??
-                    stringValue(plan.values, "build_plan") ??
-                    stringValue(plan.values, "build_plan_id") ??
-                    stringValue(request.values, "build_plan") ??
-                    stringValue(request.values, "build_plan_id"),
-                preparation: plan.preparation ?? request.preparation ?? stringValue(plan.values, "preparation") ?? stringValue(request.values, "preparation"),
-                values: {
-                    ...(plan.values ?? {}),
-                    ...(request.values ?? {}),
-                },
-            });
-        }
-        const usePlannerText = !structuredPlanActionType && plan.action_type === actionType;
-        const now = new Date().toISOString();
-        if (actionType === "clarification") {
-            return ActionProposalResourceSchema.parse({
-                kind: "interf-action-proposal",
-                version: 1,
-                proposal_id: createActionProposalId(),
-                status: "needs_clarification",
-                action_type: actionType,
-                title: plan.title ?? "Clarify Interf action",
-                summary: plan.summary ?? "No local run was proposed because the request did not resolve to a confirmed Interf action.",
-                assistant_message: plan.assistant_message ?? ACTION_PLANNER_CLARIFICATION_MESSAGE,
-                ...(plan.command_preview ? { command_preview: plan.command_preview } : {}),
-                message: request.message,
-                preparation: plan.preparation ?? request.preparation ?? null,
-                build_plan: plan.build_plan ?? null,
-                request: {
-                    message: request.message,
-                    ...(plan.values ? { values: plan.values } : {}),
-                },
-                created_at: now,
-                updated_at: now,
-                proposed_by_executor: this.getExecutorStatus().executor,
-                approval: null,
-                submitted_run_id: null,
-                submitted_run_type: null,
-                error: null,
-            });
-        }
-        const proposalValues = {
-            ...(plan.values ?? {}),
-            ...(request.values ?? {}),
-        };
-        if (actionType === "build-plan-draft" || actionType === "build-plan-improvement") {
-            const requestedPreparationName = plan.preparation ?? request.preparation ?? null;
-            const fallbackPreparation = requestedPreparationName
-                ? null
-                : listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))[0] ?? null;
-            const preparationConfig = requestedPreparationName
-                ? this.resolvePreparationConfig(prepDataDir, requestedPreparationName)
-                : fallbackPreparation;
-            const preparationPath = preparationConfig
-                ? resolveSourcePreparationPath(prepDataDir, preparationConfig)
-                : resolveConfiguredSourceFolderPath(prepDataDir) ?? prepDataDir;
-            const requestedBuildPlanId = stringValue(request.values, "build_plan_id") ??
-                stringValue(request.values, "build_plan");
-            const plannedBuildPlanId = plan.build_plan ??
-                stringValue(plan.values, "build_plan_id") ??
-                stringValue(plan.values, "build_plan");
-            const buildPlanId = requestedBuildPlanId ?? plannedBuildPlanId ?? buildPlanIdForProposal(request.message, proposalValues);
-            const taskPrompt = actionValueBuildPlanTaskPrompt(proposalValues) ??
-                stringValue(proposalValues, "task_prompt") ??
-                buildPlanAuthoringPromptFallback(request.message, buildPlanId);
-            const hint = stringValue(proposalValues, "hint") ?? buildPlanAuthoringHintFromPrompt(taskPrompt);
-            const actionRequest = {
-                preparation: preparationConfig?.name ?? null,
-                source_folder_path: preparationPath,
-                build_plan_id: buildPlanId,
-                ...(stringValue(proposalValues, "base_build_plan_id") ?? stringValue(proposalValues, "base_build_plan_id")
-                    ? { base_build_plan_id: stringValue(proposalValues, "base_build_plan_id") ?? stringValue(proposalValues, "base_build_plan_id") }
-                    : {}),
-                ...(stringValue(proposalValues, "reference_build_plan_id") ?? stringValue(proposalValues, "reference_build_plan_id")
-                    ? { reference_build_plan_id: stringValue(proposalValues, "reference_build_plan_id") ?? stringValue(proposalValues, "reference_build_plan_id") }
-                    : {}),
-                label: stringValue(proposalValues, "label") ?? buildPlanLabelFromId(buildPlanId),
-                hint,
-                task_prompt: taskPrompt,
-                checks: preparationConfig?.checks ?? [],
-                requested_artifacts: preparationConfig?.requested_artifacts ?? [],
-                source_profile: preparationConfig?.source_profile ?? null,
-                artifact_requirements: artifactRequirementsFromRequestedArtifacts(preparationConfig?.requested_artifacts ?? []),
-            };
-            const commandPreview = (usePlannerText ? plan.command_preview : undefined) ??
-                actionCommandPreview(actionType, preparationConfig?.name ?? null, buildPlanId, proposalValues);
-            return ActionProposalResourceSchema.parse({
-                kind: "interf-action-proposal",
-                version: 1,
-                proposal_id: createActionProposalId(),
-                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 create a reusable Build Plan.",
-                assistant_message: (usePlannerText ? plan.assistant_message : undefined) ??
-                    actionAssistantMessage(actionType, preparationConfig?.name ?? null, commandPreview),
-                command_preview: commandPreview,
-                message: request.message,
-                preparation: preparationConfig?.name ?? null,
-                build_plan: buildPlanId,
-                request: actionRequest,
-                created_at: now,
-                updated_at: now,
-                proposed_by_executor: this.getExecutorStatus().executor,
-                approval: null,
-                submitted_run_id: null,
-                submitted_run_type: null,
-                error: null,
-            });
-        }
-        const preparationConfig = this.resolvePreparationConfig(prepDataDir, plan.preparation ?? request.preparation ?? this.defaultPreparationName(prepDataDir));
-        const proposalActionType = ActionProposalTypeSchema.parse(actionType);
-        const preparationPath = resolveSourcePreparationPath(prepDataDir, preparationConfig);
-        const requestedBuildPlanId = stringValue(request.values, "build_plan_id") ??
-            stringValue(request.values, "build_plan");
-        const plannedBuildPlanId = plan.build_plan ??
-            stringValue(plan.values, "build_plan_id") ??
-            stringValue(plan.values, "build_plan");
-        const buildPlanId = requestedBuildPlanId ?? plannedBuildPlanId ?? buildPlanIdForSourcePreparationConfig(preparationConfig);
-        const clarifyResolvedAction = (options) => ActionProposalResourceSchema.parse({
-            kind: "interf-action-proposal",
-            version: 1,
-            proposal_id: createActionProposalId(),
-            status: "needs_clarification",
-            action_type: "clarification",
-            title: options.title,
-            summary: options.summary,
-            assistant_message: options.assistantMessage,
-            message: request.message,
-            preparation: preparationConfig.name,
-            build_plan: buildPlanId ?? null,
-            request: {
-                message: request.message,
-                ...(proposalValues ? { values: proposalValues } : {}),
-            },
-            created_at: now,
-            updated_at: now,
-            proposed_by_executor: this.getExecutorStatus().executor,
-            approval: null,
-            submitted_run_id: null,
-            submitted_run_type: null,
-            error: null,
-        });
-        if (actionType === "test") {
-            const requestedMode = testModeFromValues(proposalValues);
-            const hasReadinessChecks = (preparationConfig.checks ?? []).length > 0;
-            const verifiableContextReady = hasVerifiableContextTestTarget(prepDataDir, preparationConfig);
-            if (!hasReadinessChecks) {
-                return clarifyResolvedAction({
-                    title: `Add readiness checks for ${preparationConfig.name}`,
-                    summary: "Readiness cannot be checked until this Preparation has saved checks.",
-                    assistantMessage: `Preparation "${preparationConfig.name}" does not have saved readiness checks yet. Ask me to draft readiness checks after the Source Folder is prepared, or add readiness guidance first.`,
-                });
-            }
-            if (!verifiableContextReady && requestedMode !== "source-files") {
-                return clarifyResolvedAction({
-                    title: `Build ${preparationConfig.name} first`,
-                    summary: "Readiness checks need verifiable context unless you explicitly ask for a source-files-only baseline.",
-                    assistantMessage: `Preparation "${preparationConfig.name}" has no built verifiable context yet. Build it first; after that Interf can check readiness. If you specifically want a source-files-only baseline, ask for source files only.`,
-                });
-            }
-        }
-        const actionRequest = (() => {
-            if (actionType === "build") {
-                return {
-                    preparation: preparationConfig.name,
-                    ...(buildPlanId ? { build_plan: buildPlanId } : {}),
-                };
-            }
-            if (actionType === "test") {
-                // 0.15 — verify runs always judge against the verifiable context
-                // verifiable context. The legacy `mode` field is gone from the
-                // wire request shape.
-                return {
-                    preparation: preparationConfig.name,
-                };
-            }
-            if (actionType === "readiness-check-draft") {
-                return {
-                    preparation: preparationConfig.name,
-                    source_folder_path: preparationPath,
-                    about: stringValue(proposalValues, "about") ?? preparationConfig.about ?? request.message,
-                    target_count: Math.max(1, Math.min(8, Math.round(numberValue(proposalValues, "target_count") ?? 4))),
-                };
-            }
-            const fallbackBuildPlanId = buildPlanId ?? buildPlanIdForProposal(request.message, proposalValues);
-            const taskPrompt = actionValueBuildPlanTaskPrompt(proposalValues) ??
-                stringValue(proposalValues, "task_prompt") ??
-                buildPlanAuthoringPromptFallback(request.message, fallbackBuildPlanId);
-            const hint = stringValue(proposalValues, "hint") ?? buildPlanAuthoringHintFromPrompt(taskPrompt);
-            return {
-                preparation: preparationConfig.name,
-                source_folder_path: preparationPath,
-                build_plan_id: fallbackBuildPlanId,
-                ...(stringValue(proposalValues, "base_build_plan_id") ?? stringValue(proposalValues, "base_build_plan_id")
-                    ? { base_build_plan_id: stringValue(proposalValues, "base_build_plan_id") ?? stringValue(proposalValues, "base_build_plan_id") }
-                    : {}),
-                ...(stringValue(proposalValues, "reference_build_plan_id") ?? stringValue(proposalValues, "reference_build_plan_id")
-                    ? { reference_build_plan_id: stringValue(proposalValues, "reference_build_plan_id") ?? stringValue(proposalValues, "reference_build_plan_id") }
-                    : {}),
-                label: stringValue(proposalValues, "label") ?? buildPlanLabelFromId(fallbackBuildPlanId),
-                hint,
-                task_prompt: taskPrompt,
-                checks: preparationConfig.checks ?? [],
-                requested_artifacts: preparationConfig.requested_artifacts ?? [],
-                source_profile: preparationConfig.source_profile ?? null,
-                artifact_requirements: artifactRequirementsFromRequestedArtifacts(preparationConfig.requested_artifacts ?? []),
-            };
-        })();
-        const title = (() => {
-            if (plan.title)
-                return plan.title;
-            if (proposalActionType === "build")
-                return `Build ${preparationConfig.name}`;
-            if (proposalActionType === "test")
-                return `Check readiness for ${preparationConfig.name}`;
-            if (proposalActionType === "readiness-check-draft")
-                return `Draft readiness checks for ${preparationConfig.name}`;
-            return `Draft Build Plan ${buildPlanId}`;
-        })();
-        const summary = (() => {
-            if (plan.summary)
-                return plan.summary;
-            if (proposalActionType === "build")
-                return "Build verifiable context agents can use.";
-            if (proposalActionType === "test")
-                return "Run readiness checks against source files and verifiable context.";
-            if (proposalActionType === "readiness-check-draft")
-                return "Ask the configured local executor to draft saved readiness checks.";
-            return "Ask the configured local executor to create a reusable Build Plan.";
-        })();
-        const previewValues = proposalValues;
-        const commandPreview = plan.command_preview ?? actionCommandPreview(proposalActionType, preparationConfig.name, buildPlanId, previewValues);
-        return ActionProposalResourceSchema.parse({
-            kind: "interf-action-proposal",
-            version: 1,
-            proposal_id: createActionProposalId(),
-            status: "awaiting_approval",
-            action_type: proposalActionType,
-            title,
-            summary,
-            assistant_message: plan.assistant_message ?? actionAssistantMessage(proposalActionType, preparationConfig.name, commandPreview),
-            command_preview: commandPreview,
-            message: request.message,
-            preparation: preparationConfig.name,
-            build_plan: buildPlanId,
-            request: actionRequest,
-            created_at: now,
-            updated_at: now,
-            proposed_by_executor: this.getExecutorStatus().executor,
-            approval: null,
-            submitted_run_id: null,
-            submitted_run_type: null,
-            error: null,
-        });
-    }
-    async submitActionProposal(prepDataDir, proposal) {
-        if (proposal.action_type === "clarification") {
-            throw new Error("Clarification proposals cannot be submitted.");
-        }
-        if (proposal.action_type === "build") {
-            const resource = await this.createBuildRun(prepDataDir, proposal.request);
-            return {
-                runId: resource.run.run_id,
-                runType: "build-run",
-            };
-        }
-        if (proposal.action_type === "test") {
-            const resource = await this.createVerifyRun(prepDataDir, proposal.request);
-            return {
-                runId: resource.run_id,
-                runType: "verify-run",
-            };
-        }
-        if (proposal.action_type === "readiness-check-draft") {
-            const job = await this.createReadinessCheckDraftRun(prepDataDir, proposal.request);
-            return {
-                runId: job.run_id,
-                runType: "job-run",
-            };
-        }
-        const directEndpoint = directServiceEndpointForAction(proposal.action_type);
-        if (directEndpoint) {
-            throw new Error(`Action "${proposal.action_type}" must be submitted directly to ${directEndpoint}.`);
-        }
-        const job = await this.createBuildPlanAuthoringRun(prepDataDir, proposal.request, proposal.action_type === "build-plan-improvement" ? "build-plan-improvement" : "build-plan-draft");
-        return {
-            runId: job.run_id,
-            runType: "job-run",
-        };
-    }
-    resolvePreparationConfig(prepDataDir, preparationName, overrides = {}) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
-        if (!preparation) {
-            throw new Error(`Preparation "${preparationName}" is not saved in this control plane folder.`);
-        }
-        const buildPlan = overrides.build_plan ?? buildPlanIdForSourcePreparationConfig(preparation) ?? undefined;
-        return {
-            ...preparation,
-            ...(buildPlan ? { build_plan: buildPlan } : {}),
-            ...(typeof overrides.max_attempts === "number" ? { max_attempts: overrides.max_attempts } : {}),
-            ...(typeof overrides.max_loops === "number" ? { max_loops: overrides.max_loops } : {}),
-        };
-    }
-    ensureVerifiableContextForRun(prepDataDir, preparationConfig) {
-        const buildPlanId = requireSelectedBuildPlan(preparationConfig);
-        const verifiableContextPath = ensureVerifiableContextScaffold(prepDataDir, preparationConfig.name, buildPlanId);
-        syncVerifiableContextInterfConfigFromSourcePreparationConfig(verifiableContextPath, preparationConfig);
-        return verifiableContextPath;
-    }
-    readBuildRun(verifiableContextPath, runId) {
-        return readBuildRunAt(buildRunPath(verifiableContextPath, runId));
-    }
-    hydrateBuildRunFromRuntime(prepDataDir, verifiableContextPath, run) {
-        if (!isTerminalBuildRunStatus(run.status))
-            return run;
-        this.refreshBuildRunFromRuntime(prepDataDir, verifiableContextPath, run.run_id);
-        return this.readBuildRun(verifiableContextPath, run.run_id) ?? run;
-    }
-    finalizeInterruptedBuildRuns(prepDataDir) {
-        let preparations;
-        try {
-            preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
-        }
-        catch {
-            return;
-        }
-        for (const preparation of preparations) {
-            const verifiableContextPath = preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
-            for (const run of listJsonFiles(buildRunsRoot(verifiableContextPath))
-                .map(readBuildRunAt)
-                .filter((entry) => entry !== null)) {
-                if (isTerminalBuildRunStatus(run.status) || this.activeBuildRuns.has(run.run_id))
-                    continue;
-                const timestamp = createRunEventTimestamp();
-                const interruptedRun = {
-                    ...run,
-                    stages: run.stages.map((stage) => {
-                        if (stage.status !== "running")
-                            return stage;
-                        return {
-                            ...stage,
-                            status: "failed",
-                            finished_at: stage.finished_at ?? timestamp,
-                            summary: stage.summary ?? INTERRUPTED_COMPILE_RUN_MESSAGE,
-                            failure: stage.failure ?? INTERRUPTED_COMPILE_RUN_MESSAGE,
-                        };
-                    }),
-                };
-                this.writeBuildRun(prepDataDir, verifiableContextPath, applyEventToBuildRun(interruptedRun, {
-                    type: "run.cancelled",
-                    event_id: createRunEventId("event"),
-                    run_id: run.run_id,
-                    timestamp,
-                    reason: INTERRUPTED_COMPILE_RUN_MESSAGE,
-                }));
-            }
-        }
-    }
-    finalizeInterruptedJobRuns(prepDataDir) {
-        for (const run of this.listJobs(prepDataDir)) {
-            if (isTerminalJobStatus(run.status))
-                continue;
-            const timestamp = createRunEventTimestamp();
-            const interruptedRun = LocalJobRunResourceSchema.parse({
-                ...run,
-                steps: run.steps.map((step) => {
-                    if (step.status !== "running")
-                        return step;
-                    return {
-                        ...step,
-                        status: "failed",
-                        finished_at: step.finished_at ?? timestamp,
-                        summary: step.summary ?? INTERRUPTED_JOB_RUN_MESSAGE,
-                    };
-                }),
-            });
-            this.writeJobRun(prepDataDir, applyEventToLocalJob(interruptedRun, {
-                type: "job.failed",
-                event_id: createRunEventId("event"),
-                run_id: run.run_id,
-                timestamp,
-                message: INTERRUPTED_JOB_RUN_MESSAGE,
-            }));
-        }
-    }
-    /**
-     * 0.17 — emit per-Artifact billing events when a Build run reaches
-     * a terminal state. STUB FORM: writes a JSONL file alongside the run
-     * record by default. Production sink (Metronome HTTP) wires in 0.18+.
-     * The JSONL output is observability/dev fixture, NOT production
-     * billing data.
-     */
-    emitBillingEventsForRun(prepDataDir, context) {
-        try {
-            const run = this.readBuildRun(context.verifiableContextPath, context.runId);
-            if (!run || run.artifacts.length === 0)
-                return;
-            const sink = this.billingEventSink ?? new JsonlBillingEventSink(defaultBillingEventLogPath({
-                preparationDataDir: prepDataDir,
-                preparationName: run.preparation,
-                runId: context.runId,
-            }));
-            const events = buildCompilationEventsForRun({
-                runId: context.runId,
-                preparation: run.preparation,
-                buildPlanId: run.build_plan,
-                accountId: null, // 0.17 — loopback only; cloud variant fills via tokenValidator (B4.3).
-                artifacts: run.artifacts,
-                startedAt: run.started_at ?? null,
-                finishedAt: run.finished_at ?? null,
-            });
-            for (const event of events) {
-                sink.emit(event);
-            }
-        }
-        catch {
-            // Billing is observability-only in 0.17; never let stub failures
-            // block a successful build.
-        }
-    }
-    writeBuildRun(prepDataDir, verifiableContextPath, run) {
-        mkdirSync(buildRunsRoot(verifiableContextPath), { recursive: true });
-        writeJsonFile(buildRunPath(verifiableContextPath, run.run_id), BuildRunSchema.parse(run));
-        // Bust per-preparation list + readiness caches so the next read
-        // reflects the write. We invalidate broadly (per-preparation, not
-        // per-record) because list recompute cost is bounded by run count
-        // and the simpler model avoids fan-out bugs.
-        this.buildRunCache.invalidatePreparation(prepDataDir, run.preparation);
-        this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
-    }
-    writeJobRun(prepDataDir, run) {
-        mkdirSync(localJobsRoot(prepDataDir), { recursive: true });
-        writeJsonFile(localJobPath(prepDataDir, run.run_id), LocalJobRunResourceSchema.parse(run));
-        if (run.preparation) {
-            // Some job runs (readiness-check drafts) flip readiness state.
-            this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
-        }
-    }
-    writeActionProposal(prepDataDir, proposal) {
-        mkdirSync(actionProposalsRoot(prepDataDir), { recursive: true });
-        writeJsonFile(actionProposalPath(prepDataDir, proposal.proposal_id), ActionProposalResourceSchema.parse(proposal));
-    }
-    setJobRunResult(prepDataDir, runId, result) {
-        const current = this.getJob(prepDataDir, runId);
-        if (!current)
-            return;
-        const normalizedResult = result && typeof result === "object" && !Array.isArray(result)
-            ? result
-            : { value: result };
-        this.writeJobRun(prepDataDir, LocalJobRunResourceSchema.parse({
-            ...current,
-            result: normalizedResult,
-        }));
-    }
-    async recordBuildRunEvent(prepDataDir, verifiableContextPath, runId, event) {
-        const current = this.readBuildRun(verifiableContextPath, runId);
-        if (!current)
-            return;
-        this.writeBuildRun(prepDataDir, verifiableContextPath, applyEventToBuildRun(current, event));
-        if (event.type === "stage.passed" || event.type === "stage.failed") {
-            this.refreshBuildRunFromRuntime(prepDataDir, verifiableContextPath, runId);
-        }
-    }
-    refreshBuildRunFromRuntime(prepDataDir, verifiableContextPath, runId) {
-        const current = this.readBuildRun(verifiableContextPath, runId);
-        if (!current)
-            return;
-        const state = loadState(verifiableContextPath);
-        if (!state?.stages)
-            return;
-        const historyByStage = new Map();
-        for (const run of readRuntimeRunHistory(verifiableContextPath)) {
-            if (run.target_name !== current.preparation)
-                continue;
-            const existing = historyByStage.get(run.stage);
-            if (!existing || timestampKey(run.updated_at) >= timestampKey(existing.updated_at)) {
-                historyByStage.set(run.stage, run);
-            }
-        }
-        const next = {
-            ...current,
-            stages: current.stages.map((stage) => {
-                const stageState = state.stages?.[stage.stage_id];
-                if (!stageState)
-                    return stage;
-                const runtimeRun = historyByStage.get(stage.stage_id);
-                const artifacts = uniqueArtifacts([
-                    ...(stage.artifacts ?? []),
-                    ...stageArtifactRefs(stage.stage_id, stageState.artifacts),
-                ]);
-                const proof = stage.latest_proof ?? proofForStage({
-                    runId,
-                    stageId: stage.stage_id,
-                    summary: stageState.summary,
-                    stageState,
-                    artifacts,
-                });
-                return {
-                    ...stage,
-                    started_at: stage.started_at ?? stageState.started_at,
-                    finished_at: stage.finished_at ?? stageState.finished_at,
-                    summary: stage.summary ?? stageState.summary ?? null,
-                    executor: stage.executor ?? runtimeRun?.executor ?? null,
-                    artifacts,
-                    logs: stage.logs ?? logsForRuntimeRun(runtimeRun) ?? logsForStageRun(stageState),
-                    latest_proof: proof,
-                };
-            }),
-        };
-        next.latest_proof = [...next.stages].reverse().find((stage) => Boolean(stage.latest_proof))?.latest_proof ?? next.latest_proof;
-        // Recompute per-Artifact status whenever the Build run is
-        // refreshed from runtime state.
-        try {
-            const buildPlan = getBuildPlan(current.build_plan, { prepDataDir });
-            next.artifacts = computeArtifactStatuses({
-                buildPlan,
-                verifiableContextPath,
-                stageRuns: next.stages,
-                counts: countsFromVerifiableContextState(state),
-            });
-        }
-        catch {
-            next.artifacts = current.artifacts ?? [];
-        }
-        this.writeBuildRun(prepDataDir, verifiableContextPath, next);
-    }
-    async emitRuntimeDerivedEvents(prepDataDir, verifiableContextPath, runId) {
-        const state = loadState(verifiableContextPath);
-        const run = this.readBuildRun(verifiableContextPath, runId);
-        if (!state?.stages || !run)
-            return;
-        for (const stage of run.stages) {
-            const stageState = state.stages[stage.stage_id];
-            if (!stageState)
-                continue;
-            const artifacts = stageArtifactRefs(stage.stage_id, stageState.artifacts);
-            for (const artifact of artifacts) {
-                await this.recordBuildRunEvent(prepDataDir, verifiableContextPath, runId, {
-                    type: "artifact.written",
-                    event_id: createRunEventId("event"),
-                    run_id: runId,
-                    timestamp: stageState.finished_at ?? createRunEventTimestamp(),
-                    stage_id: stage.stage_id,
-                    artifact,
-                });
-            }
-            await this.recordBuildRunEvent(prepDataDir, verifiableContextPath, runId, {
-                type: "proof.updated",
-                event_id: createRunEventId("event"),
-                run_id: runId,
-                timestamp: stageState.finished_at ?? createRunEventTimestamp(),
-                stage_id: stage.stage_id,
-                proof: proofForStage({
-                    runId,
-                    stageId: stage.stage_id,
-                    summary: stageState.summary,
-                    stageState,
-                    artifacts,
-                }),
-            });
-        }
-    }
-    readLatestReadinessRun(prepDataDir, preparationName) {
-        return readSavedReadinessCheckRun(prepDataDir, preparationName);
-    }
-    checksEvaluatedEvent(runId, readinessRun) {
-        const target = readinessRun.verifiable_context ?? readinessRun.source_files;
-        return {
-            type: "checks.evaluated",
-            event_id: createRunEventId("event"),
-            run_id: runId,
-            timestamp: createRunEventTimestamp(),
-            passed: target?.passed_cases ?? 0,
-            total: target?.total_cases ?? 0,
-            test_run_id: runId,
-        };
-    }
-    readinessUpdatedEvent(runId, preparation, readiness) {
-        return {
-            type: "readiness.updated",
-            event_id: createRunEventId("event"),
-            run_id: runId,
-            timestamp: createRunEventTimestamp(),
-            preparation,
-            readiness,
-        };
-    }
-    writeVerifyRun(prepDataDir, verifiableContextPath, run) {
-        mkdirSync(verifyRunsRoot(verifiableContextPath), { recursive: true });
-        writeJsonFile(verifyRunPath(verifiableContextPath, run.run_id), VerifyRunResourceSchema.parse(run));
-        this.verifyRunCache.invalidatePreparation(prepDataDir, run.preparation);
-        this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
-    }
-}
-export function createLocalServiceRuntime(options) {
-    return new LocalServiceRuntime(options);
-}