@interf/compiler 0.7.3 → 0.9.3

package/dist/packages/local-service/runtime.js

@@ -0,0 +1,2263 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CompileRunSchema, } from "../execution/lib/schema.js";
+import { createRunEventId, createRunEventTimestamp, } from "../execution/events.js";
+import { compiledRuntimeRunHistoryPath, compiledRuntimeRoot, testRootForCompiled, } from "../compiler/compiled-paths.js";
+import { loadState, } from "../compiler/state.js";
+import { RuntimeRunSchema, } from "../compiler/lib/schema.js";
+import { ReadinessStateSchema, } from "../contracts/lib/schema.js";
+import { discoverSourceFiles, } from "../compiler/discovery.js";
+import { ensurePortableContextScaffold, readInterfConfig, } from "../project-model/interf.js";
+import { findSourcePreparationConfig, fingerprintReadinessChecks, listSourcePreparationConfigs, loadSourceFolderConfig, DEFAULT_METHOD_ID, methodIdForSourcePreparationConfig, resolveConfiguredSourceFolderPath, resolveSourcePreparationPath, syncCompiledInterfConfigFromSourcePreparationConfig, upsertSourcePreparationConfig, } from "../project-model/source-config.js";
+import { defaultPreparationNameForPath, listSourceFolderChoices, normalizeSourcePreparationPathForConfig, } from "../project-model/source-folders.js";
+import { portableContextPath, } from "../project-model/project-paths.js";
+import { getCompiledMethod, listCompiledMethodChoices, } from "../method-package/method-definitions.js";
+import { resolveMethodPackageSourcePath, } from "../method-package/local-methods.js";
+import { resolveAgent, detectAgents, supportsAutomatedRuns, } from "../agents/lib/detection.js";
+import { AGENTS, } from "../agents/lib/constants.js";
+import { loadUserConfig, saveUserConfig, } from "../agents/lib/user-config.js";
+import { readSavedReadinessCheckRun, } from "../testing/readiness-check-run.js";
+import { createCompiledTestTarget, } from "../testing/test-targets.js";
+import { ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalPlanSchema, ActionProposalResourceSchema, CompileRunCreateRequestSchema, CompileRunResourceSchema, MethodResourceSchema, LocalExecutorStatusSchema, LocalExecutorSelectRequestSchema, LocalServiceHealthSchema, PreparationReadinessStateSchema, LocalRunHandlerResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, SourceFileResourceSchema, WorkspaceFileResourceSchema, PortableContextResourceSchema, PreparationSetupCreateRequestSchema, PreparationResourceSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
+import { buildLocalServiceUrl, } from "./routes.js";
+import { methodAuthoringTaskPrompt, MethodAuthoringActionValuesSchema, PreparationSetupActionValuesSchema, } from "./action-values.js";
+import { compileRunToObservability, jobRunToObservability, testRunToObservability, uniqueArtifacts, } from "./run-observability.js";
+function createRunId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function createActionProposalId() {
+    return `action_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+const ACTION_PLANNER_CLARIFICATION_MESSAGE = "I can help with this Interf Workspace. Ask a question about Interf, or ask me to create a Preparation, prepare, check readiness, improve, or draft a Method and I will prepare an approval proposal.";
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonFile(filePath, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function sanitizeActionProposalPlan(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const plan = { ...value };
+    for (const key of ["preparation", "method", "title", "summary", "assistant_message", "command_preview"]) {
+        const current = plan[key];
+        if (current === null || current === undefined) {
+            delete plan[key];
+            continue;
+        }
+        if (typeof current === "string" && current.trim().length === 0) {
+            delete plan[key];
+        }
+    }
+    return plan;
+}
+function compileRunsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "compile-runs");
+}
+function compileRunPath(compiledPath, runId) {
+    return join(compileRunsRoot(compiledPath), `${runId}.json`);
+}
+function testRunsRoot(compiledPath) {
+    return join(testRootForCompiled(compiledPath), "service-runs");
+}
+function testRunPath(compiledPath, runId) {
+    return join(testRunsRoot(compiledPath), `${runId}.json`);
+}
+function localJobsRoot(rootPath) {
+    return join(rootPath, "interf", ".service", "jobs");
+}
+function localJobPath(rootPath, runId) {
+    return join(localJobsRoot(rootPath), `${runId}.json`);
+}
+function actionProposalsRoot(rootPath) {
+    return join(rootPath, "interf", ".service", "action-proposals");
+}
+function actionProposalPath(rootPath, proposalId) {
+    return join(actionProposalsRoot(rootPath), `${proposalId}.json`);
+}
+function listJsonFiles(dirPath) {
+    if (!existsSync(dirPath))
+        return [];
+    try {
+        if (!statSync(dirPath).isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    return readdirSync(dirPath)
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => join(dirPath, entry));
+}
+function readCompileRunAt(filePath) {
+    const parsed = CompileRunSchema.safeParse(readJsonFile(filePath));
+    return parsed.success ? parsed.data : null;
+}
+function readRuntimeRunHistory(compiledPath) {
+    const historyPath = compiledRuntimeRunHistoryPath(compiledPath);
+    if (!existsSync(historyPath))
+        return [];
+    try {
+        return readFileSync(historyPath, "utf8")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            try {
+                return RuntimeRunSchema.safeParse(JSON.parse(line));
+            }
+            catch {
+                return { success: false };
+            }
+        })
+            .filter((parsed) => parsed.success)
+            .map((parsed) => parsed.data);
+    }
+    catch {
+        return [];
+    }
+}
+function readTestRunAt(filePath) {
+    const parsed = TestRunResourceSchema.safeParse(readJsonFile(filePath));
+    return parsed.success ? parsed.data : null;
+}
+function readLocalJobRunAt(filePath) {
+    const parsed = LocalJobRunResourceSchema.safeParse(readJsonFile(filePath));
+    return parsed.success ? parsed.data : null;
+}
+function readActionProposalAt(filePath) {
+    const parsed = ActionProposalResourceSchema.safeParse(readJsonFile(filePath));
+    return parsed.success ? parsed.data : null;
+}
+function newestFirst(items) {
+    return [...items].sort((left, right) => {
+        const leftTime = Date.parse(left.started_at ?? left.finished_at ?? "");
+        const rightTime = Date.parse(right.started_at ?? right.finished_at ?? "");
+        return (Number.isFinite(rightTime) ? rightTime : 0) - (Number.isFinite(leftTime) ? leftTime : 0);
+    });
+}
+function newestJobFirst(items) {
+    return [...items].sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+}
+function newestActionProposalFirst(items) {
+    return [...items].sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+}
+function newestCompileFirst(items) {
+    return [...items].sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+}
+function configuredAgentName() {
+    const config = loadUserConfig();
+    if (!config)
+        return null;
+    const configured = AGENTS.find((agent) => agent.command === config.agentCommand) ??
+        AGENTS.find((agent) => agent.name === config.agent) ??
+        AGENTS.find((agent) => agent.displayName === config.agent);
+    return configured?.name ?? null;
+}
+function detectedExecutorOptions(currentAgentName) {
+    return detectAgents()
+        .filter(supportsAutomatedRuns)
+        .map((agent) => ({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        current: agent.name === currentAgentName,
+    }));
+}
+function stageArtifactRefs(stageId, artifacts) {
+    return (artifacts ?? []).map((path) => ({
+        path,
+        role: "output",
+        stage_id: stageId,
+        label: path,
+    }));
+}
+function proofForStage(options) {
+    return {
+        id: `${options.runId}-${options.stageId}-proof`,
+        run_id: options.runId,
+        stage_id: options.stageId,
+        generated_at: options.stageState.finished_at ?? new Date().toISOString(),
+        summary: options.summary ?? `${options.stageId} produced stage evidence.`,
+        files_processed: options.stageState.counts?.source_total,
+        artifacts: options.artifacts,
+        checks: [
+            {
+                id: `${options.stageId}-status`,
+                label: "stage completed",
+                ok: options.stageState.status === "succeeded",
+                ...(options.stageState.status === "succeeded"
+                    ? {}
+                    : { detail: options.stageState.summary ?? "Stage did not complete successfully." }),
+            },
+            {
+                id: `${options.stageId}-artifacts`,
+                label: "artifacts recorded",
+                ok: options.artifacts.length > 0,
+                ...(options.artifacts.length > 0
+                    ? {}
+                    : { detail: "No stage artifacts were recorded." }),
+            },
+        ],
+    };
+}
+function logsForStageRun(stageState) {
+    const runId = stageState?.run_id;
+    if (!runId)
+        return undefined;
+    return {
+        prompt_path: `.interf/runtime/logs/${runId}.prompt.txt`,
+        event_stream_path: `.interf/runtime/logs/${runId}.events.ndjson`,
+        status_path: `.interf/runtime/logs/${runId}.status.log`,
+        contract_path: `.interf/runtime/logs/${runId}.stage-contract.json`,
+    };
+}
+function logsForRuntimeRun(run) {
+    if (!run)
+        return undefined;
+    return {
+        ...(run.logs?.prompt_path ? { prompt_path: run.logs.prompt_path } : {}),
+        ...(run.logs?.event_stream_path ? { event_stream_path: run.logs.event_stream_path } : {}),
+        ...(run.logs?.status_path ? { status_path: run.logs.status_path } : {}),
+        contract_path: run.contract_path,
+    };
+}
+function timestampKey(value) {
+    const parsed = Date.parse(value ?? "");
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function applyEventToCompileRun(run, event) {
+    const now = event.timestamp;
+    const stageFor = (stageId) => {
+        const existing = run.stages.find((stage) => stage.stage_id === stageId);
+        if (existing)
+            return existing;
+        const created = {
+            run_id: run.run_id,
+            stage_id: stageId,
+            status: "queued",
+            artifacts: [],
+        };
+        run.stages.push(created);
+        return created;
+    };
+    const updateStage = (stageId, patch) => {
+        const current = stageFor(stageId);
+        Object.assign(current, patch);
+    };
+    switch (event.type) {
+        case "run.started":
+            return {
+                ...run,
+                status: "running",
+                started_at: run.started_at ?? now,
+                events: [...run.events, event],
+            };
+        case "stage.started":
+            updateStage(event.stage_id, {
+                status: "running",
+                started_at: now,
+                stage_index: event.stage_index,
+                stage_total: event.stage_total,
+            });
+            break;
+        case "artifact.written": {
+            const stage = stageFor(event.stage_id);
+            updateStage(event.stage_id, {
+                artifacts: uniqueArtifacts([...(stage.artifacts ?? []), event.artifact]),
+            });
+            break;
+        }
+        case "proof.updated":
+            if (event.stage_id) {
+                updateStage(event.stage_id, {
+                    latest_proof: event.proof,
+                });
+            }
+            return {
+                ...run,
+                latest_proof: event.proof,
+                events: [...run.events, event],
+            };
+        case "log.appended":
+            break;
+        case "stage.passed":
+            updateStage(event.stage_id, {
+                status: "succeeded",
+                finished_at: now,
+                summary: event.summary ?? null,
+                failure: null,
+            });
+            break;
+        case "stage.failed":
+            updateStage(event.stage_id, {
+                status: "failed",
+                finished_at: now,
+                summary: event.error,
+                failure: event.error,
+            });
+            break;
+        case "run.completed":
+            return {
+                ...run,
+                status: "succeeded",
+                finished_at: run.finished_at ?? now,
+                events: [...run.events, event],
+            };
+        case "run.failed":
+            return {
+                ...run,
+                status: "failed",
+                finished_at: run.finished_at ?? now,
+                events: [...run.events, event],
+            };
+        default:
+            break;
+    }
+    return {
+        ...run,
+        events: [...run.events, event],
+    };
+}
+function applyEventToLocalJob(run, event) {
+    const stepFor = (stepId) => {
+        const existing = run.steps.find((step) => step.id === stepId);
+        if (existing)
+            return existing;
+        const created = {
+            id: stepId,
+            label: stepId,
+            status: "queued",
+        };
+        run.steps.push(created);
+        return created;
+    };
+    const updateStep = (stepId, patch) => {
+        if (!stepId)
+            return;
+        Object.assign(stepFor(stepId), patch);
+    };
+    switch (event.type) {
+        case "job.started":
+            return {
+                ...run,
+                status: "running",
+                started_at: run.started_at ?? event.timestamp,
+                events: [...run.events, event],
+            };
+        case "step.started":
+            updateStep(event.step_id, {
+                status: "running",
+                started_at: event.timestamp,
+                ...(event.input ? { input: event.input } : {}),
+            });
+            break;
+        case "step.completed":
+            updateStep(event.step_id, {
+                status: "succeeded",
+                finished_at: event.timestamp,
+                summary: event.message ?? null,
+                ...(event.output ? { output: event.output } : {}),
+            });
+            break;
+        case "step.failed":
+            updateStep(event.step_id, {
+                status: "failed",
+                finished_at: event.timestamp,
+                summary: event.message ?? null,
+                ...(event.output ? { output: event.output } : {}),
+            });
+            break;
+        case "job.completed":
+            return {
+                ...run,
+                status: "succeeded",
+                finished_at: run.finished_at ?? event.timestamp,
+                events: [...run.events, event],
+            };
+        case "job.failed":
+            return {
+                ...run,
+                status: "failed",
+                finished_at: run.finished_at ?? event.timestamp,
+                error: event.message ?? "Job failed.",
+                events: [...run.events, event],
+            };
+        case "artifact.written":
+        case "log.appended":
+            break;
+        default:
+            break;
+    }
+    return {
+        ...run,
+        events: [...run.events, event],
+    };
+}
+function slugFromText(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 42)
+        .replace(/-+$/g, "");
+    return slug || "custom";
+}
+function stringValue(values, key) {
+    const value = values?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function numberValue(values, key) {
+    const value = values?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function testModeFromValues(values) {
+    const value = stringValue(values, "mode") ?? stringValue(values, "target");
+    if (value === "source-files")
+        return "raw";
+    if (value === "portable-context")
+        return "compiled";
+    return value === "raw" || value === "compiled" || value === "both" ? value : null;
+}
+function testModeValue(values, defaultMode = "both") {
+    return testModeFromValues(values) ?? defaultMode;
+}
+function testModeCliTarget(mode) {
+    if (mode === "raw")
+        return "source-files";
+    if (mode === "compiled")
+        return "portable-context";
+    return "both";
+}
+function methodIdForProposal(message, values) {
+    const explicit = stringValue(values, "method_id") ??
+        stringValue(values, "method");
+    return explicit ?? `custom-${slugFromText(message)}`;
+}
+function actionValueMethodTaskPrompt(values) {
+    const parsed = MethodAuthoringActionValuesSchema.safeParse(values);
+    return parsed.success ? methodAuthoringTaskPrompt(parsed.data) : null;
+}
+function preparationSetupPathValue(values) {
+    return stringValue(values, "path") ??
+        stringValue(values, "source_folder_path") ??
+        stringValue(values, "source_path") ??
+        stringValue(values, "source_folder") ??
+        stringValue(values, "folder");
+}
+function preparationSetupNameValue(values) {
+    const parsed = PreparationSetupActionValuesSchema.safeParse(values);
+    return parsed.success ? parsed.data.name : stringValue(values, "name") ??
+        stringValue(values, "preparation") ??
+        stringValue(values, "preparation_name");
+}
+function actionCommandPreview(actionType, preparationName, methodId, values) {
+    if (actionType === "preparation-setup") {
+        const preparationPart = preparationName ? ` # Preparation: ${preparationName}` : "";
+        const pathPart = preparationSetupPathValue(values);
+        return pathPart ? `interf init # source: ${pathPart}${preparationPart}` : `interf init${preparationPart}`;
+    }
+    if (actionType === "compile") {
+        const methodSuffix = methodId ? ` # Method: ${methodId}` : "";
+        return preparationName
+            ? `interf compile --preparation ${preparationName}${methodSuffix}`
+            : `interf compile${methodSuffix}`;
+    }
+    if (actionType === "test") {
+        const mode = testModeCliTarget(testModeValue(values));
+        return preparationName
+            ? `interf test --preparation ${preparationName} --target ${mode}`
+            : `interf test --target ${mode}`;
+    }
+    if (actionType === "readiness-check-draft") {
+        return "interf # choose Auto-create readiness checks";
+    }
+    if (actionType === "method-authoring" || actionType === "method-improvement") {
+        return "interf create method";
+    }
+    return "Try: create a Preparation, prepare, check readiness, draft readiness checks, or draft a Method.";
+}
+function hasCompiledTestTarget(sourcePath, preparationConfig) {
+    const compiledPath = portableContextPath(sourcePath, preparationConfig.name);
+    if (!existsSync(compiledPath))
+        return false;
+    return createCompiledTestTarget(compiledPath, preparationConfig.name, methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID).eligible;
+}
+function actionAssistantMessage(actionType, preparationName, commandPreview) {
+    const preparationSuffix = preparationName ? ` for Preparation "${preparationName}"` : "";
+    if (actionType === "preparation-setup") {
+        return `Interf prepared a Preparation setup proposal${preparationSuffix}. Approve to save the source folder and create the portable-context scaffold. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "compile") {
+        return `Interf prepared a prepare-run proposal${preparationSuffix}. Approve to submit it through the local Interf service and watch the run in Interf. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "test") {
+        return `Interf prepared a readiness-check proposal${preparationSuffix}. Approve to run the requested target against saved readiness checks. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "readiness-check-draft") {
+        return `Interf prepared a readiness-check draft proposal${preparationSuffix}. Approve to ask the configured local executor to draft checks as a visible run. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "method-authoring" || actionType === "method-improvement") {
+        return `Interf prepared a Method draft proposal${preparationSuffix}. Approve to draft a reusable local Method as a visible run. CLI equivalent: ${commandPreview}`;
+    }
+    return "I could not map that to a safe Interf action. Ask for one action in plain English, such as create a Preparation, prepare the data, check readiness, draft readiness checks, or draft a Method.";
+}
+function passRate(passed, total) {
+    if (total <= 0)
+        return null;
+    return Math.round((passed / total) * 100);
+}
+function readinessTargetResult(summary, currentFingerprint, comparisonFingerprint) {
+    if (!summary)
+        return null;
+    const resultFingerprint = comparisonFingerprint ?? null;
+    return {
+        passed: summary.passed_cases,
+        total: summary.total_cases,
+        pass_rate: passRate(summary.passed_cases, summary.total_cases),
+        checks_fingerprint: resultFingerprint,
+        stale: Boolean(currentFingerprint && resultFingerprint && currentFingerprint !== resultFingerprint),
+        run_id: null,
+        run_path: summary.run_path,
+    };
+}
+function readinessSummaryForStatus(status) {
+    if (status === "ready")
+        return "Ready for agent work.";
+    if (status === "not-ready")
+        return "Readiness checks did not pass.";
+    if (status === "stale")
+        return "Readiness checks are stale for the current saved checks.";
+    if (status === "checking")
+        return "Readiness checks are running.";
+    if (status === "building")
+        return "Portable context is building.";
+    if (status === "built")
+        return "Portable context is built; readiness has not been proven yet.";
+    if (status === "not-built")
+        return "Portable context has not been built yet.";
+    if (status === "not-configured")
+        return "No readiness checks are configured.";
+    return "Latest preparation failed.";
+}
+function readinessStateToPreparationReadiness(readiness) {
+    return PreparationReadinessStateSchema.parse({
+        ...readiness,
+        checks: readiness.checks.map((check) => ({ ...check })),
+    });
+}
+function buildPreparationResource(rootPath, preparation, readiness, latestCompileRunId, latestTestRunId) {
+    const methodId = methodIdForSourcePreparationConfig(preparation);
+    return PreparationResourceSchema.parse({
+        id: preparation.name,
+        name: preparation.name,
+        preparation,
+        source_path: resolveSourcePreparationPath(rootPath, preparation),
+        method_id: methodId,
+        checks: preparation.checks,
+        portable_context: {
+            preparation: preparation.name,
+            path: readiness.portable_context_path,
+            exists: readiness.portable_context_path !== null,
+            method_id: methodId,
+            latest_compile_run_id: latestCompileRunId,
+            latest_test_run_id: latestTestRunId,
+        },
+        portable_context_path: readiness.portable_context_path,
+        readiness: readinessStateToPreparationReadiness(readiness),
+        runs: {
+            latest_compile_run_id: latestCompileRunId,
+            latest_test_run_id: latestTestRunId,
+        },
+        latest_compile_run_id: latestCompileRunId,
+        latest_test_run_id: latestTestRunId,
+    });
+}
+function buildMethodResource(resource) {
+    return MethodResourceSchema.parse({
+        id: resource.id,
+        method_id: resource.id,
+        path: resource.path,
+        ...(resource.label ? { label: resource.label } : {}),
+        ...(resource.hint ? { hint: resource.hint } : {}),
+        source_kind: resource.source_kind,
+        built_in: resource.built_in,
+        active_for_preparations: resource.active_for_preparations,
+        stages: resource.stages,
+    });
+}
+export class LocalServiceRuntime {
+    rootPath;
+    host;
+    port;
+    startedAt;
+    packageVersion;
+    handlers;
+    constructor(options) {
+        this.rootPath = resolve(options.rootPath);
+        this.host = options.host;
+        this.port = options.port;
+        this.startedAt = options.startedAt ?? new Date().toISOString();
+        this.packageVersion = options.packageVersion;
+        this.handlers = options.handlers ?? {};
+    }
+    health() {
+        const sourceFolderPath = resolveConfiguredSourceFolderPath(this.rootPath);
+        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 }),
+            control_path: this.rootPath,
+            source_folder_path: sourceFolderPath,
+            started_at: this.startedAt,
+            ...(this.packageVersion ? { package_version: this.packageVersion } : {}),
+        });
+    }
+    listPreparations() {
+        const config = loadSourceFolderConfig(this.rootPath);
+        return listSourcePreparationConfigs(config).map((preparation) => {
+            const compileRuns = this.listCompileRunsForPreparation(preparation.name);
+            const testRuns = this.listTestRunsForPreparation(preparation.name);
+            const readiness = this.computePreparationReadiness(preparation);
+            return buildPreparationResource(this.rootPath, preparation, readiness, compileRuns[0]?.run_id ?? null, testRuns[0]?.run_id ?? null);
+        });
+    }
+    getPreparation(preparationName) {
+        return this.listPreparations().find((preparation) => preparation.name === preparationName) ?? null;
+    }
+    listPreparationReadiness() {
+        return this.listReadiness().map(readinessStateToPreparationReadiness);
+    }
+    getPreparationReadiness(preparationName) {
+        const readiness = this.getReadiness(preparationName);
+        return readiness ? readinessStateToPreparationReadiness(readiness) : null;
+    }
+    listReadiness() {
+        const config = loadSourceFolderConfig(this.rootPath);
+        return listSourcePreparationConfigs(config).map((preparation) => this.computePreparationReadiness(preparation));
+    }
+    getReadiness(preparationName) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
+        return preparation ? this.computePreparationReadiness(preparation) : null;
+    }
+    computePreparationReadiness(preparation) {
+        const generatedAt = new Date().toISOString();
+        const compiledPath = portableContextPath(this.rootPath, preparation.name);
+        const contextExists = existsSync(compiledPath);
+        const compiledTarget = createCompiledTestTarget(compiledPath, preparation.name, methodIdForSourcePreparationConfig(preparation) ?? DEFAULT_METHOD_ID);
+        const contextReady = compiledTarget.eligible;
+        const compileRun = this.listCompileRunsForPreparation(preparation.name)[0] ?? null;
+        const testRun = this.listTestRunsForPreparation(preparation.name)[0] ?? null;
+        const comparison = this.readLatestComparison(preparation.name);
+        const configuredChecks = preparation.checks.length;
+        const currentFingerprint = configuredChecks > 0 ? fingerprintReadinessChecks(preparation.checks) : null;
+        const comparisonFingerprint = comparison?.checks_fingerprint ?? null;
+        const sourceResult = readinessTargetResult(comparison?.raw, currentFingerprint, comparisonFingerprint);
+        const contextResult = readinessTargetResult(comparison?.compiled, currentFingerprint, comparisonFingerprint);
+        const checksStale = Boolean(currentFingerprint && comparisonFingerprint && currentFingerprint !== comparisonFingerprint);
+        const compileCheck = (() => {
+            if (!compileRun) {
+                return {
+                    gate: "compile-run",
+                    ok: false,
+                    status: "not-built",
+                    summary: "No compile run has built portable context yet.",
+                    artifact_path: contextReady ? compiledPath : null,
+                };
+            }
+            if (compileRun.status === "succeeded") {
+                return {
+                    gate: "compile-run",
+                    ok: contextReady,
+                    status: contextReady ? "built" : "failed",
+                    summary: contextReady
+                        ? "Latest compile run built portable context."
+                        : "Latest compile run finished, but portable context is missing.",
+                    run_id: compileRun.run_id,
+                    artifact_path: contextReady ? compiledPath : null,
+                };
+            }
+            if (compileRun.status === "queued" || compileRun.status === "running") {
+                return {
+                    gate: "compile-run",
+                    ok: false,
+                    status: "building",
+                    summary: "Latest compile run is still building portable context.",
+                    run_id: compileRun.run_id,
+                    artifact_path: contextExists ? compiledPath : null,
+                };
+            }
+            return {
+                gate: "compile-run",
+                ok: false,
+                status: "failed",
+                summary: compileRun.status === "cancelled"
+                    ? "Latest compile run was cancelled."
+                    : "Latest compile run failed.",
+                run_id: compileRun.run_id,
+                artifact_path: contextReady ? compiledPath : null,
+            };
+        })();
+        const checks = [
+            {
+                gate: "preparation-config",
+                ok: true,
+                summary: "Preparation is saved in this control plane folder.",
+            },
+            {
+                gate: "portable-context",
+                ok: contextReady,
+                status: contextReady ? "built" : "not-built",
+                summary: contextReady
+                    ? "Portable context is built."
+                    : "Portable context has not been built.",
+                artifact_path: contextReady ? compiledPath : null,
+            },
+            compileCheck,
+            {
+                gate: "readiness-checks",
+                ok: configuredChecks > 0,
+                status: configuredChecks > 0 ? "built" : "not-configured",
+                summary: configuredChecks > 0
+                    ? `${configuredChecks} readiness check${configuredChecks === 1 ? "" : "s"} configured.`
+                    : "No 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 (compileRun?.status === "queued" || compileRun?.status === "running")
+                return "building";
+            if (testRun?.status === "queued" || testRun?.status === "running")
+                return "checking";
+            if (compileRun?.status === "failed" || compileRun?.status === "cancelled")
+                return "failed";
+            if (!compileRun || !contextReady)
+                return "not-built";
+            if (configuredChecks === 0)
+                return "not-configured";
+            if (checksStale)
+                return "stale";
+            if (!contextResult)
+                return "built";
+            return contextResult.total > 0 && contextResult.passed === contextResult.total ? "ready" : "not-ready";
+        })();
+        const ready = status === "ready";
+        return ReadinessStateSchema.parse({
+            kind: "interf-readiness-state",
+            version: 1,
+            generated_at: generatedAt,
+            preparation: preparation.name,
+            status,
+            ready,
+            summary: readinessSummaryForStatus(status),
+            portable_context_path: contextReady ? compiledPath : null,
+            latest_compile_run_id: compileRun?.run_id ?? null,
+            latest_test_run_id: testRun?.run_id ?? null,
+            compile: compileCheck,
+            check_results: {
+                configured: configuredChecks,
+                fingerprint: currentFingerprint,
+                source_files: sourceResult,
+                portable_context: contextResult,
+                delta: comparison?.summary.pass_rate_delta ?? null,
+            },
+            checks,
+        });
+    }
+    listSourceFiles(preparationName) {
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
+            .filter((preparation) => !preparationName || preparation.name === preparationName);
+        return preparations.flatMap((preparation) => {
+            const sourceFolderPath = resolveSourcePreparationPath(this.rootPath, preparation);
+            const compiledPath = portableContextPath(this.rootPath, preparation.name);
+            return discoverSourceFiles(sourceFolderPath, compiledPath).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,
+                });
+            });
+        });
+    }
+    listWorkspaceFiles() {
+        const sourceFolderPath = resolveConfiguredSourceFolderPath(this.rootPath) ?? this.rootPath;
+        return discoverSourceFiles(sourceFolderPath, join(this.rootPath, "interf")).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 WorkspaceFileResourceSchema.parse({
+                path: relativePath,
+                absolute_path: absolutePath,
+                size_bytes: sizeBytes,
+                modified_at: modifiedAt,
+            });
+        });
+    }
+    listMethods() {
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath));
+        const choices = listCompiledMethodChoices(this.rootPath);
+        return choices.map((method) => {
+            const activeForPreparations = preparations
+                .filter((preparation) => (methodIdForSourcePreparationConfig(preparation) ?? DEFAULT_METHOD_ID) === method.id)
+                .map((preparation) => preparation.name);
+            return buildMethodResource({
+                id: method.id,
+                path: resolveMethodPackageSourcePath(this.rootPath, method.id) ?? method.id,
+                label: method.label,
+                hint: method.hint,
+                source_kind: method.scope === "builtin" ? "builtin" : "local",
+                built_in: method.scope === "builtin",
+                active_for_preparations: activeForPreparations,
+                stages: method.stages.map((stage) => ({
+                    id: stage.id,
+                    label: stage.label,
+                    description: stage.description,
+                    contract_type: stage.contractType,
+                    skill_dir: stage.skillDir,
+                    reads: stage.reads,
+                    writes: stage.writes,
+                    ...(stage.acceptance ? { acceptance: stage.acceptance } : {}),
+                })),
+            });
+        });
+    }
+    getMethod(methodId) {
+        return this.listMethods().find((method) => method.id === methodId) ?? null;
+    }
+    listJobs() {
+        return newestJobFirst(listJsonFiles(localJobsRoot(this.rootPath))
+            .map(readLocalJobRunAt)
+            .filter((run) => run !== null));
+    }
+    getJob(runId) {
+        return this.listJobs().find((run) => run.run_id === runId) ?? null;
+    }
+    getJobEvents(runId) {
+        return this.getJob(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(),
+        });
+        return this.getExecutorStatus();
+    }
+    listActionProposals() {
+        return newestActionProposalFirst(listJsonFiles(actionProposalsRoot(this.rootPath))
+            .map(readActionProposalAt)
+            .filter((proposal) => proposal !== null));
+    }
+    getActionProposal(proposalId) {
+        return this.listActionProposals().find((proposal) => proposal.proposal_id === proposalId) ?? null;
+    }
+    async createActionProposal(requestValue) {
+        const request = ActionProposalCreateRequestSchema.parse(requestValue);
+        const proposal = await this.buildActionProposal(request);
+        this.writeActionProposal(proposal);
+        return proposal;
+    }
+    async decideActionProposal(proposalId, requestValue) {
+        const decision = ActionProposalApprovalRequestSchema.parse(requestValue);
+        const current = this.getActionProposal(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(decided);
+        if (!decision.approved)
+            return decided;
+        try {
+            const submission = await this.submitActionProposal(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(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(failed);
+            return failed;
+        }
+    }
+    listRunObservability() {
+        return [
+            ...this.listCompileRuns().map((resource) => compileRunToObservability(resource.run)),
+            ...this.listTestRuns().map(testRunToObservability),
+            ...this.listJobs().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(runId) {
+        return this.listRunObservability().find((run) => run.run_id === runId) ?? null;
+    }
+    createJobRun(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.method !== undefined ? { method: request.method } : {}),
+            ...(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(run);
+        return run;
+    }
+    appendJobRunEvent(runId, requestValue) {
+        const request = LocalJobEventAppendRequestSchema.parse(requestValue);
+        const current = this.getJob(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(next);
+        return next;
+    }
+    async createReadinessCheckDraftRun(requestValue) {
+        const request = ReadinessCheckDraftCreateRequestSchema.parse(requestValue);
+        const job = this.createJobRun({
+            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(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(job.run_id, {
+            type: "step.completed",
+            step_id: "read-source",
+            message: "Source folder is ready for readiness-check drafting.",
+            output: {
+                preparation: request.preparation,
+                source_folder_path: request.source_folder_path,
+            },
+        });
+        this.appendJobRunEvent(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(request, job.run_id);
+        return this.getJob(job.run_id) ?? job;
+    }
+    async createPreparationSetupRun(requestValue) {
+        const request = PreparationSetupCreateRequestSchema.parse(requestValue);
+        const preparationConfig = request.preparation;
+        const methodId = methodIdForSourcePreparationConfig(preparationConfig) ?? "interf-default";
+        const normalizedPreparationConfig = {
+            ...preparationConfig,
+            method: methodId,
+        };
+        const sourceFolderPath = resolveSourcePreparationPath(this.rootPath, preparationConfig);
+        const outputPath = portableContextPath(this.rootPath, preparationConfig.name);
+        const job = this.createJobRun({
+            job_type: "preparation-setup",
+            title: `Create Preparation ${preparationConfig.name}`,
+            preparation: preparationConfig.name,
+            method: methodId,
+            source_path: sourceFolderPath,
+            output_path: outputPath,
+            agent: this.getExecutorStatus().executor,
+            steps: [
+                {
+                    id: "validate-source",
+                    label: "Validate source folder",
+                    input: {
+                        preparation: preparationConfig.name,
+                        path: preparationConfig.path,
+                    },
+                },
+                {
+                    id: "write-config",
+                    label: "Save Preparation config",
+                    input: {
+                        config_path: join(this.rootPath, "interf", "interf.json"),
+                    },
+                },
+                {
+                    id: "prepare-scaffold",
+                    label: "Prepare portable context",
+                    input: {
+                        output_path: outputPath,
+                        method: methodId,
+                    },
+                },
+            ],
+        });
+        let activeStep = "validate-source";
+        try {
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.started",
+                step_id: "validate-source",
+                message: "Validating source folder.",
+                input: {
+                    path: preparationConfig.path,
+                    source_folder_path: sourceFolderPath,
+                },
+            });
+            if (!existsSync(sourceFolderPath) || !statSync(sourceFolderPath).isDirectory()) {
+                throw new Error(`Source folder "${preparationConfig.path}" is not available.`);
+            }
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.completed",
+                step_id: "validate-source",
+                message: "Source folder is available.",
+                output: {
+                    source_folder_path: sourceFolderPath,
+                },
+            });
+            activeStep = "write-config";
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.started",
+                step_id: "write-config",
+                message: "Saving Preparation in the control plane config.",
+                input: {
+                    preparation: preparationConfig.name,
+                    path: preparationConfig.path,
+                },
+            });
+            upsertSourcePreparationConfig(this.rootPath, normalizedPreparationConfig);
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.completed",
+                step_id: "write-config",
+                message: "Preparation config saved.",
+                output: {
+                    config_path: join(this.rootPath, "interf", "interf.json"),
+                    preparation: preparationConfig.name,
+                },
+            });
+            activeStep = "prepare-scaffold";
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.started",
+                step_id: "prepare-scaffold",
+                message: "Preparing portable-context scaffold.",
+                input: {
+                    output_path: outputPath,
+                    method: methodId,
+                },
+            });
+            const compiledPath = ensurePortableContextScaffold(this.rootPath, normalizedPreparationConfig.name, methodId);
+            syncCompiledInterfConfigFromSourcePreparationConfig(compiledPath, normalizedPreparationConfig);
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.completed",
+                step_id: "prepare-scaffold",
+                message: "Portable-context scaffold is ready.",
+                output: {
+                    portable_context_path: compiledPath,
+                },
+            });
+            this.setJobRunResult(job.run_id, {
+                preparation: normalizedPreparationConfig,
+                source_folder_path: sourceFolderPath,
+                portable_context_path: compiledPath,
+            });
+            this.appendJobRunEvent(job.run_id, {
+                type: "job.completed",
+                message: `Preparation ${preparationConfig.name} is ready for Interf runs.`,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.appendJobRunEvent(job.run_id, {
+                type: "step.failed",
+                step_id: activeStep,
+                message,
+                output: {
+                    error: message,
+                },
+            });
+            this.appendJobRunEvent(job.run_id, {
+                type: "job.failed",
+                message,
+            });
+        }
+        return this.getJob(job.run_id) ?? job;
+    }
+    async createMethodAuthoringRun(requestValue) {
+        const request = MethodAuthoringCreateRequestSchema.parse(requestValue);
+        const job = this.createJobRun({
+            job_type: "method-authoring",
+            title: `Draft Method ${request.method_id}`,
+            preparation: request.preparation ?? null,
+            method: request.method_id,
+            source_path: request.source_folder_path,
+            output_path: join(this.rootPath, "interf", "methods", request.method_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,
+                    },
+                },
+                {
+                    id: "draft-package",
+                    label: "Draft Method package",
+                    input: {
+                        method_id: request.method_id,
+                        label: request.label,
+                        task_prompt: request.task_prompt,
+                    },
+                },
+                {
+                    id: "validate-package",
+                    label: "Validate Method package",
+                    input: {
+                        method_id: request.method_id,
+                    },
+                },
+            ],
+        });
+        this.appendJobRunEvent(job.run_id, {
+            type: "step.started",
+            step_id: "inspect-source",
+            message: "Inspecting source files for Method drafting.",
+            input: {
+                preparation: request.preparation ?? null,
+                source_folder_path: request.source_folder_path,
+                checks: request.checks.length,
+            },
+        });
+        this.appendJobRunEvent(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,
+            },
+        });
+        this.appendJobRunEvent(job.run_id, {
+            type: "step.started",
+            step_id: "draft-package",
+            message: "Drafting Method package.",
+            input: {
+                method_id: request.method_id,
+                label: request.label,
+                task_prompt: request.task_prompt,
+            },
+        });
+        void this.runMethodAuthoringInBackground(request, job.run_id);
+        return this.getJob(job.run_id) ?? job;
+    }
+    listPortableContexts() {
+        return listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
+            .map((preparation) => this.getPortableContext(preparation.name))
+            .filter((context) => context !== null);
+    }
+    getPortableContext(preparationName) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
+        if (!preparation)
+            return null;
+        const path = portableContextPath(this.rootPath, preparation.name);
+        const config = readInterfConfig(path);
+        const compileRuns = this.listCompileRunsForPreparation(preparation.name);
+        const testRuns = this.listTestRunsForPreparation(preparation.name);
+        const readiness = this.computePreparationReadiness(preparation);
+        const method = config?.method ?? methodIdForSourcePreparationConfig(preparation);
+        return PortableContextResourceSchema.parse({
+            preparation: preparation.name,
+            path,
+            exists: existsSync(path),
+            readiness,
+            method,
+            latest_compile_run_id: compileRuns[0]?.run_id ?? null,
+            latest_test_run_id: testRuns[0]?.run_id ?? null,
+            artifacts: uniqueArtifacts(compileRuns[0]?.stages.flatMap((stage) => stage.artifacts) ?? []),
+        });
+    }
+    listCompileRuns() {
+        return newestCompileFirst(listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
+            .flatMap((preparation) => this.listCompileRunsForPreparation(preparation.name))).map((run) => CompileRunResourceSchema.parse({ run }));
+    }
+    listCompileRunsForPreparation(preparationName) {
+        const compiledPath = portableContextPath(this.rootPath, preparationName);
+        return newestCompileFirst(listJsonFiles(compileRunsRoot(compiledPath))
+            .map(readCompileRunAt)
+            .filter((run) => run !== null));
+    }
+    getCompileRun(runId) {
+        for (const resource of this.listCompileRuns()) {
+            if (resource.run.run_id === runId)
+                return resource;
+        }
+        return null;
+    }
+    getCompileRunEvents(runId) {
+        return this.getCompileRun(runId)?.run.events ?? null;
+    }
+    getCompileRunProof(runId) {
+        const run = this.getCompileRun(runId)?.run;
+        if (!run)
+            return null;
+        return run.stages
+            .map((stage) => stage.latest_proof ?? null)
+            .filter((proof) => proof !== null);
+    }
+    getCompileRunArtifacts(runId) {
+        const run = this.getCompileRun(runId)?.run;
+        if (!run)
+            return null;
+        return uniqueArtifacts(run.stages.flatMap((stage) => stage.artifacts));
+    }
+    async createCompileRun(requestValue) {
+        const request = CompileRunCreateRequestSchema.parse(requestValue);
+        const preparationConfig = this.resolvePreparationConfig(request.preparation, {
+            method: request.method,
+            max_attempts: request.max_attempts,
+            max_loops: request.max_loops,
+        });
+        const compiledPath = this.ensureCompiledForRun(preparationConfig);
+        const runId = createRunId("compile");
+        const now = new Date().toISOString();
+        const method = getCompiledMethod(methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID, {
+            sourcePath: this.rootPath,
+        });
+        const stageTotal = method.stages.length;
+        const run = CompileRunSchema.parse({
+            kind: "interf-compile-run",
+            version: 1,
+            run_id: runId,
+            status: "running",
+            preparation: preparationConfig.name,
+            method: method.id,
+            backend: "native",
+            source_path: resolveSourcePreparationPath(this.rootPath, preparationConfig),
+            portable_context_path: compiledPath,
+            created_at: now,
+            started_at: now,
+            stages: method.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,
+                        ...(stage.acceptance ? { acceptance: stage.acceptance } : {}),
+                    },
+                    artifacts: [],
+                };
+            }),
+            events: [],
+        });
+        this.writeCompileRun(compiledPath, run);
+        await this.recordCompileRunEvent(compiledPath, runId, {
+            type: "run.started",
+            event_id: createRunEventId("event"),
+            run_id: runId,
+            timestamp: now,
+            preparation: preparationConfig.name,
+            method: method.id,
+            portable_context_path: compiledPath,
+            backend: "native",
+        });
+        const sink = {
+            emit: (event) => this.recordCompileRunEvent(compiledPath, runId, event),
+        };
+        void this.runCompileInBackground(request, {
+            runId,
+            sourcePath: this.rootPath,
+            compiledPath,
+            preparationConfig,
+            events: sink,
+        });
+        const saved = this.readCompileRun(compiledPath, runId) ?? run;
+        return CompileRunResourceSchema.parse({ run: saved });
+    }
+    listTestRuns() {
+        return newestFirst(listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
+            .flatMap((preparation) => this.listTestRunsForPreparation(preparation.name)));
+    }
+    listTestRunsForPreparation(preparationName) {
+        const compiledPath = portableContextPath(this.rootPath, preparationName);
+        return newestFirst(listJsonFiles(testRunsRoot(compiledPath))
+            .map(readTestRunAt)
+            .filter((run) => run !== null));
+    }
+    getTestRun(runId) {
+        return this.listTestRuns().find((run) => run.run_id === runId) ?? null;
+    }
+    async createTestRun(requestValue) {
+        const request = TestRunCreateRequestSchema.parse(requestValue);
+        const preparationConfig = this.resolvePreparationConfig(request.preparation);
+        const compiledPath = portableContextPath(this.rootPath, preparationConfig.name);
+        const compiledTarget = createCompiledTestTarget(compiledPath, preparationConfig.name, methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID);
+        const runId = createRunId("test");
+        const now = new Date().toISOString();
+        const initial = TestRunResourceSchema.parse({
+            run_id: runId,
+            status: "running",
+            preparation: preparationConfig.name,
+            mode: request.mode,
+            source_path: this.rootPath,
+            portable_context_path: compiledTarget.eligible ? compiledPath : null,
+            started_at: now,
+            comparison: null,
+            events: [],
+        });
+        this.writeTestRun(compiledPath, initial);
+        void this.runTestInBackground(request, {
+            runId,
+            sourcePath: this.rootPath,
+            compiledPath,
+            preparationConfig,
+        }, initial);
+        return initial;
+    }
+    async runCompileInBackground(request, context) {
+        try {
+            if (!this.handlers.createCompileRun) {
+                throw new Error("No compile-run handler is configured for this local service.");
+            }
+            const result = LocalRunHandlerResultSchema.parse(await this.handlers.createCompileRun(request, context));
+            this.refreshCompileRunFromRuntime(context.compiledPath, context.runId);
+            await this.emitRuntimeDerivedEvents(context.compiledPath, context.runId);
+            if (!result.ok) {
+                await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+                    type: "run.failed",
+                    event_id: createRunEventId("event"),
+                    run_id: context.runId,
+                    timestamp: createRunEventTimestamp(),
+                    error: result.error ?? "Compile run failed.",
+                });
+            }
+            else {
+                await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+                    type: "run.completed",
+                    event_id: createRunEventId("event"),
+                    run_id: context.runId,
+                    timestamp: createRunEventTimestamp(),
+                    summary: "Portable context ready.",
+                });
+            }
+        }
+        catch (error) {
+            await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+                type: "run.failed",
+                event_id: createRunEventId("event"),
+                run_id: context.runId,
+                timestamp: createRunEventTimestamp(),
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async runTestInBackground(request, context, initial) {
+        try {
+            if (!this.handlers.createTestRun) {
+                throw new Error("No test-run handler is configured for this local service.");
+            }
+            const result = LocalRunHandlerResultSchema.parse(await this.handlers.createTestRun(request, context));
+            const comparison = result.comparison ?? this.readLatestComparison(context.preparationConfig.name);
+            const resultEvent = comparison
+                ? this.checksEvaluatedEvent(context.runId, comparison)
+                : null;
+            const nextWithoutReadiness = TestRunResourceSchema.parse({
+                ...initial,
+                status: result.ok ? "succeeded" : "failed",
+                finished_at: new Date().toISOString(),
+                comparison,
+                events: resultEvent ? [resultEvent] : [],
+                ...(!result.ok ? { error: result.error ?? "Readiness check failed." } : {}),
+            });
+            this.writeTestRun(context.compiledPath, nextWithoutReadiness);
+            const readiness = this.computePreparationReadiness(context.preparationConfig);
+            const next = TestRunResourceSchema.parse({
+                ...nextWithoutReadiness,
+                readiness,
+                events: [
+                    ...nextWithoutReadiness.events,
+                    this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness),
+                ],
+            });
+            this.writeTestRun(context.compiledPath, next);
+        }
+        catch (error) {
+            const failedWithoutReadiness = TestRunResourceSchema.parse({
+                ...initial,
+                status: "failed",
+                finished_at: new Date().toISOString(),
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.writeTestRun(context.compiledPath, failedWithoutReadiness);
+            const readiness = this.computePreparationReadiness(context.preparationConfig);
+            const next = TestRunResourceSchema.parse({
+                ...failedWithoutReadiness,
+                readiness,
+                events: [this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness)],
+            });
+            this.writeTestRun(context.compiledPath, next);
+        }
+    }
+    async runReadinessCheckDraftInBackground(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(runId)));
+            this.appendJobRunEvent(runId, {
+                type: "step.completed",
+                step_id: "agent-draft",
+                message: `Drafted ${result.checks.length} readiness checks.`,
+                output: {
+                    checks: result.checks,
+                },
+            });
+            this.appendJobRunEvent(runId, {
+                type: "step.started",
+                step_id: "normalize-checks",
+                message: "Normalizing readiness-check draft into saved check records.",
+                input: {
+                    checks: result.checks.length,
+                },
+            });
+            this.appendJobRunEvent(runId, {
+                type: "step.completed",
+                step_id: "normalize-checks",
+                message: `${result.checks.length} readiness checks ready for review.`,
+                output: {
+                    checks: result.checks.length,
+                },
+            });
+            this.setJobRunResult(runId, result);
+            this.appendJobRunEvent(runId, {
+                type: "job.completed",
+                message: `Drafted ${result.checks.length} readiness checks.`,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.appendJobRunEvent(runId, {
+                type: "step.failed",
+                step_id: "agent-draft",
+                message,
+                output: {
+                    error: message,
+                },
+            });
+            this.appendJobRunEvent(runId, {
+                type: "job.failed",
+                message,
+            });
+        }
+    }
+    async runMethodAuthoringInBackground(request, runId) {
+        try {
+            if (!this.handlers.createMethodAuthoringRun) {
+                throw new Error("No Method-authoring handler is configured for this local service.");
+            }
+            const result = MethodAuthoringResultSchema.parse(await this.handlers.createMethodAuthoringRun(request, this.jobRunContext(runId)));
+            this.setJobRunResult(runId, result);
+            this.appendJobRunEvent(runId, {
+                type: result.status === "executor-failed" ? "step.failed" : "step.completed",
+                step_id: "draft-package",
+                message: result.summary,
+                output: {
+                    status: result.status,
+                    changed: result.changed,
+                    method_path: result.method_path,
+                    shell_path: result.shell_path,
+                },
+            });
+            this.appendJobRunEvent(runId, {
+                type: "step.started",
+                step_id: "validate-package",
+                message: "Validating Method package structure and stage contract.",
+                input: {
+                    method_path: result.method_path,
+                },
+            });
+            if (result.status === "updated" || result.status === "no-change") {
+                this.appendJobRunEvent(runId, {
+                    type: "step.completed",
+                    step_id: "validate-package",
+                    message: result.summary,
+                    output: {
+                        status: result.status,
+                        validation: result.validation ?? null,
+                    },
+                });
+                this.appendJobRunEvent(runId, {
+                    type: "job.completed",
+                    message: result.summary,
+                });
+            }
+            else {
+                this.appendJobRunEvent(runId, {
+                    type: "step.failed",
+                    step_id: "validate-package",
+                    message: result.summary,
+                    output: {
+                        status: result.status,
+                        validation: result.validation ?? null,
+                    },
+                });
+                this.appendJobRunEvent(runId, {
+                    type: "job.failed",
+                    message: result.summary,
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.appendJobRunEvent(runId, {
+                type: "step.failed",
+                step_id: "draft-package",
+                message,
+                output: {
+                    error: message,
+                },
+            });
+            this.appendJobRunEvent(runId, {
+                type: "job.failed",
+                message,
+            });
+        }
+    }
+    jobRunContext(runId) {
+        return {
+            runId,
+            sourcePath: this.rootPath,
+            emit: (event) => {
+                this.appendJobRunEvent(runId, event);
+            },
+        };
+    }
+    defaultPreparationName() {
+        const preparation = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))[0];
+        if (!preparation) {
+            throw new Error("No Preparation is saved in this control plane folder.");
+        }
+        return preparation.name;
+    }
+    async planActionProposal(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 Workspace.",
+            });
+        }
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath));
+        let rawPlan;
+        try {
+            rawPlan = await this.handlers.planActionProposal(request, {
+                sourcePath: this.rootPath,
+                preparations,
+                preparationHealth: preparations.map((preparation) => {
+                    const readinessChecks = preparation.checks?.length ?? 0;
+                    const portableContextReady = hasCompiledTestTarget(this.rootPath, preparation);
+                    return {
+                        name: preparation.name,
+                        readiness_checks: readinessChecks,
+                        portable_context_ready: portableContextReady,
+                        can_check_readiness: readinessChecks > 0 && portableContextReady,
+                        recommended_next_actions: portableContextReady
+                            ? readinessChecks > 0
+                                ? ["check readiness", "improve", "prepare again"]
+                                : ["draft readiness checks", "prepare again"]
+                            : ["prepare"],
+                    };
+                }),
+                sourceFolders: listSourceFolderChoices(this.rootPath),
+                recentProposals: this.listActionProposals().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,
+        });
+    }
+    buildPreparationSetupRequest(request, plan, values) {
+        const sourceFolderChoices = listSourceFolderChoices(this.rootPath);
+        const selectedPath = preparationSetupPathValue(values) ??
+            (sourceFolderChoices.length === 1 ? sourceFolderChoices[0].value : null);
+        if (!selectedPath) {
+            return {
+                error: "Tell Interf which source folder to use for the Preparation.",
+            };
+        }
+        let normalizedPath;
+        try {
+            normalizedPath = normalizeSourcePreparationPathForConfig(this.rootPath, selectedPath);
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        const explicitName = preparationSetupNameValue(values) ?? plan.preparation ?? request.preparation;
+        const preparationName = explicitName
+            ? slugFromText(explicitName)
+            : defaultPreparationNameForPath(normalizedPath);
+        const requestMethodId = stringValue(request.values, "method");
+        const valueMethodId = stringValue(values, "method");
+        const methodId = requestMethodId ?? plan.method ?? valueMethodId ?? "interf-default";
+        try {
+            return {
+                preparationName,
+                methodId,
+                request: PreparationSetupCreateRequestSchema.parse({
+                    preparation: {
+                        name: preparationName,
+                        path: normalizedPath,
+                        about: stringValue(values, "about") ?? stringValue(values, "task_prompt") ?? request.message,
+                        method: methodId,
+                        checks: [],
+                    },
+                }),
+            };
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async buildActionProposal(request) {
+        const plan = await this.planActionProposal(request);
+        const actionType = plan.action_type;
+        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,
+                method: plan.method ?? 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 === "preparation-setup") {
+            const setup = this.buildPreparationSetupRequest(request, plan, proposalValues);
+            if ("error" in setup) {
+                return ActionProposalResourceSchema.parse({
+                    kind: "interf-action-proposal",
+                    version: 1,
+                    proposal_id: createActionProposalId(),
+                    status: "needs_clarification",
+                    action_type: "clarification",
+                    title: "Clarify Preparation setup",
+                    summary: "Interf needs a source folder before it can save a Preparation.",
+                    assistant_message: setup.error,
+                    message: request.message,
+                    preparation: plan.preparation ?? request.preparation ?? null,
+                    method: plan.method ?? 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,
+                });
+            }
+            const commandPreview = plan.command_preview ??
+                actionCommandPreview(actionType, setup.preparationName, setup.methodId, {
+                    ...proposalValues,
+                    path: setup.request.preparation.path,
+                });
+            return ActionProposalResourceSchema.parse({
+                kind: "interf-action-proposal",
+                version: 1,
+                proposal_id: createActionProposalId(),
+                status: "awaiting_approval",
+                action_type: actionType,
+                title: plan.title ?? `Create Preparation ${setup.preparationName}`,
+                summary: plan.summary ?? "Save this source folder as an Interf Preparation.",
+                assistant_message: plan.assistant_message ?? actionAssistantMessage(actionType, setup.preparationName, commandPreview),
+                command_preview: commandPreview,
+                message: request.message,
+                preparation: setup.preparationName,
+                method: setup.methodId,
+                request: setup.request,
+                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(plan.preparation ?? request.preparation ?? this.defaultPreparationName());
+        const preparationPath = resolveSourcePreparationPath(this.rootPath, preparationConfig);
+        const requestedMethodId = stringValue(request.values, "method_id") ??
+            stringValue(request.values, "method");
+        const plannedMethodId = plan.method ??
+            stringValue(plan.values, "method_id") ??
+            stringValue(plan.values, "method");
+        const methodId = actionType === "method-authoring"
+            ? requestedMethodId ?? plannedMethodId ?? methodIdForProposal(request.message, proposalValues)
+            : requestedMethodId ?? plannedMethodId ?? methodIdForSourcePreparationConfig(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,
+            method: methodId ?? 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 portableContextReady = hasCompiledTestTarget(this.rootPath, 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 (!portableContextReady && requestedMode !== "raw") {
+                return clarifyResolvedAction({
+                    title: `Prepare ${preparationConfig.name} first`,
+                    summary: "Readiness checks need portable context unless you explicitly ask for a source-files-only baseline.",
+                    assistantMessage: `Preparation "${preparationConfig.name}" has no prepared portable context yet. Prepare 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 === "compile") {
+                return {
+                    preparation: preparationConfig.name,
+                    ...(methodId ? { method: methodId } : {}),
+                };
+            }
+            if (actionType === "test") {
+                const defaultMode = hasCompiledTestTarget(this.rootPath, preparationConfig) ? "both" : "raw";
+                return {
+                    preparation: preparationConfig.name,
+                    mode: testModeValue(proposalValues, defaultMode),
+                };
+            }
+            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))),
+                };
+            }
+            return {
+                preparation: preparationConfig.name,
+                source_folder_path: preparationPath,
+                method_id: methodId,
+                label: stringValue(proposalValues, "label") ?? `Custom ${preparationConfig.name}`,
+                hint: stringValue(proposalValues, "hint") ?? request.message,
+                task_prompt: actionValueMethodTaskPrompt(proposalValues) ?? stringValue(proposalValues, "task_prompt") ?? request.message,
+                checks: preparationConfig.checks ?? [],
+            };
+        })();
+        const title = (() => {
+            if (plan.title)
+                return plan.title;
+            if (actionType === "compile")
+                return `Prepare ${preparationConfig.name}`;
+            if (actionType === "test")
+                return `Check readiness for ${preparationConfig.name}`;
+            if (actionType === "readiness-check-draft")
+                return `Draft readiness checks for ${preparationConfig.name}`;
+            return `Draft Method ${methodId}`;
+        })();
+        const summary = (() => {
+            if (plan.summary)
+                return plan.summary;
+            if (actionType === "compile")
+                return "Build portable context agents can use.";
+            if (actionType === "test")
+                return "Run readiness checks against source files and portable context.";
+            if (actionType === "readiness-check-draft")
+                return "Ask the configured local executor to draft saved readiness checks.";
+            return "Ask the configured local executor to create a reusable local Method.";
+        })();
+        const previewValues = actionType === "test"
+            ? { mode: actionRequest.mode }
+            : proposalValues;
+        const commandPreview = plan.command_preview ?? actionCommandPreview(actionType, preparationConfig.name, methodId, previewValues);
+        return ActionProposalResourceSchema.parse({
+            kind: "interf-action-proposal",
+            version: 1,
+            proposal_id: createActionProposalId(),
+            status: "awaiting_approval",
+            action_type: actionType,
+            title,
+            summary,
+            assistant_message: plan.assistant_message ?? actionAssistantMessage(actionType, preparationConfig.name, commandPreview),
+            command_preview: commandPreview,
+            message: request.message,
+            preparation: preparationConfig.name,
+            method: methodId,
+            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(proposal) {
+        if (proposal.action_type === "clarification") {
+            throw new Error("Clarification proposals cannot be submitted.");
+        }
+        if (proposal.action_type === "compile") {
+            const resource = await this.createCompileRun(proposal.request);
+            return {
+                runId: resource.run.run_id,
+                runType: "compile-run",
+            };
+        }
+        if (proposal.action_type === "test") {
+            const resource = await this.createTestRun(proposal.request);
+            return {
+                runId: resource.run_id,
+                runType: "test-run",
+            };
+        }
+        if (proposal.action_type === "preparation-setup") {
+            const job = await this.createPreparationSetupRun(proposal.request);
+            return {
+                runId: job.run_id,
+                runType: "job-run",
+            };
+        }
+        if (proposal.action_type === "readiness-check-draft") {
+            const job = await this.createReadinessCheckDraftRun(proposal.request);
+            return {
+                runId: job.run_id,
+                runType: "job-run",
+            };
+        }
+        const job = await this.createMethodAuthoringRun(proposal.request);
+        return {
+            runId: job.run_id,
+            runType: "job-run",
+        };
+    }
+    resolvePreparationConfig(preparationName, overrides = {}) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
+        if (!preparation) {
+            throw new Error(`Preparation "${preparationName}" is not saved in this control plane folder.`);
+        }
+        const method = overrides.method ?? methodIdForSourcePreparationConfig(preparation) ?? undefined;
+        return {
+            ...preparation,
+            ...(method ? { method } : {}),
+            ...(typeof overrides.max_attempts === "number" ? { max_attempts: overrides.max_attempts } : {}),
+            ...(typeof overrides.max_loops === "number" ? { max_loops: overrides.max_loops } : {}),
+        };
+    }
+    ensureCompiledForRun(preparationConfig) {
+        const methodId = methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID;
+        const compiledPath = ensurePortableContextScaffold(this.rootPath, preparationConfig.name, methodId);
+        syncCompiledInterfConfigFromSourcePreparationConfig(compiledPath, preparationConfig);
+        return compiledPath;
+    }
+    readCompileRun(compiledPath, runId) {
+        return readCompileRunAt(compileRunPath(compiledPath, runId));
+    }
+    writeCompileRun(compiledPath, run) {
+        mkdirSync(compileRunsRoot(compiledPath), { recursive: true });
+        writeJsonFile(compileRunPath(compiledPath, run.run_id), CompileRunSchema.parse(run));
+    }
+    writeJobRun(run) {
+        mkdirSync(localJobsRoot(this.rootPath), { recursive: true });
+        writeJsonFile(localJobPath(this.rootPath, run.run_id), LocalJobRunResourceSchema.parse(run));
+    }
+    writeActionProposal(proposal) {
+        mkdirSync(actionProposalsRoot(this.rootPath), { recursive: true });
+        writeJsonFile(actionProposalPath(this.rootPath, proposal.proposal_id), ActionProposalResourceSchema.parse(proposal));
+    }
+    setJobRunResult(runId, result) {
+        const current = this.getJob(runId);
+        if (!current)
+            return;
+        const normalizedResult = result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { value: result };
+        this.writeJobRun(LocalJobRunResourceSchema.parse({
+            ...current,
+            result: normalizedResult,
+        }));
+    }
+    async recordCompileRunEvent(compiledPath, runId, event) {
+        const current = this.readCompileRun(compiledPath, runId);
+        if (!current)
+            return;
+        this.writeCompileRun(compiledPath, applyEventToCompileRun(current, event));
+        if (event.type === "stage.passed" || event.type === "stage.failed") {
+            this.refreshCompileRunFromRuntime(compiledPath, runId);
+        }
+    }
+    refreshCompileRunFromRuntime(compiledPath, runId) {
+        const current = this.readCompileRun(compiledPath, runId);
+        if (!current)
+            return;
+        const state = loadState(compiledPath);
+        if (!state?.stages)
+            return;
+        const historyByStage = new Map();
+        for (const run of readRuntimeRunHistory(compiledPath)) {
+            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;
+        this.writeCompileRun(compiledPath, next);
+    }
+    async emitRuntimeDerivedEvents(compiledPath, runId) {
+        const state = loadState(compiledPath);
+        const run = this.readCompileRun(compiledPath, 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.recordCompileRunEvent(compiledPath, runId, {
+                    type: "artifact.written",
+                    event_id: createRunEventId("event"),
+                    run_id: runId,
+                    timestamp: stageState.finished_at ?? createRunEventTimestamp(),
+                    stage_id: stage.stage_id,
+                    artifact,
+                });
+            }
+            await this.recordCompileRunEvent(compiledPath, 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,
+                }),
+            });
+        }
+    }
+    readLatestComparison(preparationName) {
+        return readSavedReadinessCheckRun(this.rootPath, preparationName);
+    }
+    checksEvaluatedEvent(runId, comparison) {
+        const target = comparison.compiled ?? comparison.raw;
+        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,
+        };
+    }
+    writeTestRun(compiledPath, run) {
+        mkdirSync(testRunsRoot(compiledPath), { recursive: true });
+        writeJsonFile(testRunPath(compiledPath, run.run_id), TestRunResourceSchema.parse(run));
+    }
+}
+export function createLocalServiceRuntime(options) {
+    return new LocalServiceRuntime(options);
+}