@interf/compiler 0.9.5 → 0.13.0

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

@@ -1,714 +1,233 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, rmSync, statSync, } from "node:fs";
+import { 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 { actionProposalPath, actionProposalsRoot, byCreatedAtDesc, compileRunPath, compileRunsRoot, listJsonFiles, localJobPath, localJobsRoot, newestFirst, readActionProposalAt, readCompileRunAt, readLocalJobRunAt, readRuntimeRunHistory, readTestRunAt, testRunPath, testRunsRoot, timestampKey, writeJsonFile, } from "./runtime-persistence.js";
+import { MethodListingCache, MtimeListingCache, ReadinessCache, RunListingCache, } from "./runtime-caches.js";
+import { applyEventToCompileRun, applyEventToLocalJob, } from "./runtime-event-applier.js";
+import { buildMethodResource, buildPreparationResource, createRunId, logsForRuntimeRun, logsForStageRun, proofForStage, readinessStateToPreparationReadiness, readinessSummaryForStatus, readinessTargetResult, stageArtifactRefs, } from "./runtime-resource-builders.js";
+import { ACTION_PLANNER_CLARIFICATION_MESSAGE, actionAssistantMessage, actionCommandPreview, actionTypeFromValues, actionValueMethodTaskPrompt, configuredAgentName, createActionProposalId, detachMethodFromPreparation, detectedExecutorOptions, directServiceEndpointForAction, hasCompiledTestTarget, methodAuthoringHintFromPrompt, methodAuthoringPromptFallback, methodIdForProposal, methodLabelFromId, numberValue, requireSelectedMethod, sanitizeActionProposalPlan, stringValue, testModeFromValues, testModeValue, } from "./runtime-proposal-helpers.js";
 import { ReadinessStateSchema, } from "../contracts/lib/schema.js";
 import { discoverSourceFiles, } from "../compiler/discovery.js";
 import { resetCompiledGeneratedState, } from "../compiler/reset.js";
 import { ensurePortableContextScaffold, readInterfConfig, } from "../project-model/interf.js";
 import { findSourcePreparationConfig, fingerprintReadinessChecks, listSourcePreparationConfigs, loadSourceFolderConfig, DEFAULT_METHOD_ID, methodIdForSourcePreparationConfig, resolveConfiguredSourceFolderPath, resolveSourcePreparationPath, removeSourcePreparationConfig, saveSourceFolderConfig, syncCompiledInterfConfigFromSourcePreparationConfig, upsertSourcePreparationConfig, } from "../project-model/source-config.js";
 import { listSourceFolderChoices, } from "../project-model/source-folders.js";
-import { portableContextPath, } from "../project-model/project-paths.js";
+import { asPreparationDataDir, preparationPortableContextPath, userMethodsRoot, preparationConfigPath, preparationMethodPackagePath, preparationMethodsRoot, } from "../contracts/lib/preparation-paths.js";
 import { getCompiledMethod, listCompiledMethodChoices, } from "../method-package/method-definitions.js";
 import { contextInterfaceArtifactPath, } from "../method-package/context-interface.js";
-import { methodDefinitionPath, resolveMethodPackageSourcePath, } from "../method-package/local-methods.js";
+import { methodDefinitionPath, resolveMethodPackageSourcePath, seedLocalDefaultMethod, } from "../method-package/local-methods.js";
 import { seedLocalMethodPackageFromBase, } from "../method-package/interf-method-package.js";
+import { PACKAGE_ROOT } from "../method-package/lib/package-root.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, ActionProposalPlanActionTypeSchema, ActionProposalTypeSchema, CompileRunCreateRequestSchema, CompileRunResourceSchema, MethodResourceSchema, LocalExecutorStatusSchema, LocalExecutorSelectRequestSchema, LocalServiceHealthSchema, PreparationReadinessStateSchema, LocalRunHandlerResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, SourceFileResourceSchema, WorkspaceFileResourceSchema, PortableContextResourceSchema, PreparationSetupCreateRequestSchema, PreparationSetupResultSchema, PreparationResourceSchema, MethodChangeCreateRequestSchema, MethodChangeResultSchema, PreparationChangeCreateRequestSchema, PreparationChangeResultSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
+import { ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalPlanSchema, ActionProposalResourceSchema, ActionProposalTypeSchema, CompileRunCreateRequestSchema, CompileRunResourceSchema, LocalExecutorStatusSchema, LocalExecutorSelectRequestSchema, LocalServiceHealthSchema, LocalRunHandlerResultSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, SourceFileResourceSchema, WorkspaceFileResourceSchema, PortableContextResourceSchema, PreparationSetupCreateRequestSchema, PreparationSetupResultSchema, WorkspaceBootstrapCreateRequestSchema, WorkspaceBootstrapResultSchema, MethodChangeCreateRequestSchema, MethodChangeResultSchema, PreparationChangeCreateRequestSchema, PreparationChangeResultSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, ServiceRegistryWorkspaceSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
 import { buildLocalServiceUrl, } from "./routes.js";
-import { methodAuthoringTaskPrompt, MethodAuthoringActionValuesSchema, PreparationSetupActionValuesSchema, } from "./action-values.js";
+import { 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],
-            };
-        case "readiness.updated":
-            return {
-                ...run,
-                readiness: event.readiness,
-                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 escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function stringValue(values, key) {
-    const value = values?.[key];
-    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-}
-function actionTypeFromValues(values) {
-    const explicit = stringValue(values, "action_type") ?? stringValue(values, "service_action");
-    if (explicit) {
-        const parsed = ActionProposalPlanActionTypeSchema.safeParse(explicit);
-        if (parsed.success && parsed.data !== "clarification")
-            return parsed.data;
-    }
-    const action = stringValue(values, "action");
-    if (action === "compile" || action === "prepare-run" || action === "run-preparation")
-        return "compile";
-    if (action === "test" || action === "check-readiness")
-        return "test";
-    if (action === "draft-readiness-checks" || action === "readiness-check-draft")
-        return "readiness-check-draft";
-    if (action === "create-method" || action === "method-authoring")
-        return "method-authoring";
-    if (action === "method-duplicate" || action === "method-remove" || action === "method-change")
-        return "method-change";
-    if (action === "preparation-remove" || action === "preparation-change")
-        return "preparation-change";
-    if (action === "improve-preparation" || action === "method-improvement")
-        return "method-improvement";
-    return null;
-}
-function directServiceEndpointForAction(actionType) {
-    if (actionType === "preparation-setup")
-        return "/v1/preparation-setups";
-    if (actionType === "method-change")
-        return "/v1/method-changes";
-    if (actionType === "preparation-change")
-        return "/v1/preparation-changes";
-    return 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");
-    const fromMessage = message.match(/\b(?:create|reate|eate|draft|author|build|make)\s+(?:a\s+new\s+)?(?:interf\s+)?method\s+([a-z0-9][a-z0-9-]{0,79})\b/i)?.[1];
-    return explicit ?? fromMessage ?? `custom-${slugFromText(message)}`;
-}
-function actionValueMethodTaskPrompt(values) {
-    const parsed = MethodAuthoringActionValuesSchema.safeParse(values);
-    return parsed.success ? methodAuthoringTaskPrompt(parsed.data) : null;
-}
-const METHOD_AUTHORING_INTERNAL_INSTRUCTION = /Use the attached values as the Method authoring request before proposing the action\.?/gi;
-const METHOD_AUTHORING_LABELS = [
-    "Agent work",
-    "Portable-context output",
-    "Readiness checks",
-    "CLI preview",
-];
-function normalizeMethodAuthoringText(value) {
-    return value
-        .replace(/[│]+/g, " ")
-        .replace(METHOD_AUTHORING_INTERNAL_INSTRUCTION, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-}
-function extractMethodAuthoringSection(value, label) {
-    const otherLabels = METHOD_AUTHORING_LABELS
-        .filter((candidate) => candidate !== label)
-        .map(escapeRegExp)
-        .join("|");
-    const match = value.match(new RegExp(`${escapeRegExp(label)}\\s*:\\s*([\\s\\S]*?)(?=\\s*(?:${otherLabels})\\s*:|$)`, "i"));
-    return match?.[1] ? normalizeMethodAuthoringText(match[1]) : null;
-}
-function stripMethodCommandPrefix(value, methodId) {
-    const specific = new RegExp(`^(?:create|reate|eate|draft|author|build|make)\\s+(?:a\\s+new\\s+)?(?:interf\\s+)?method\\s+${escapeRegExp(methodId)}\\.?\\s*`, "i");
-    const generic = /^(?:create|reate|eate|draft|author|build|make)\s+(?:a\s+new\s+)?(?:interf\s+)?method\b[^.]{0,180}\.\s*/i;
-    const stripped = normalizeMethodAuthoringText(value)
-        .replace(specific, "")
-        .replace(generic, "")
-        .trim();
-    return stripped || normalizeMethodAuthoringText(value);
-}
-function methodAuthoringPromptFallback(message, methodId) {
-    const cleaned = message
-        .replace(/[│]+/g, " ")
-        .replace(METHOD_AUTHORING_INTERNAL_INSTRUCTION, " ")
-        .trim();
-    const agentWork = extractMethodAuthoringSection(cleaned, "Agent work");
-    const portableOutput = extractMethodAuthoringSection(cleaned, "Portable-context output");
-    const readinessNotes = extractMethodAuthoringSection(cleaned, "Readiness checks");
-    const lines = [
-        agentWork ? `Agent work: ${stripMethodCommandPrefix(agentWork, methodId)}` : null,
-        portableOutput ? `Portable-context output: ${portableOutput}` : null,
-        readinessNotes ? `Readiness checks: ${readinessNotes}` : null,
-    ].filter((line) => Boolean(line));
-    if (lines.length > 0)
-        return lines.join("\n");
-    return stripMethodCommandPrefix(cleaned, methodId);
-}
-function methodAuthoringHintFromPrompt(prompt) {
-    const plain = normalizeMethodAuthoringText(prompt.replace(/\b(?:Agent work|Portable-context output|Readiness checks)\s*:/gi, " "));
-    if (plain.length <= 180)
-        return plain || "Custom Method";
-    const clipped = plain.slice(0, 177).replace(/\s+\S*$/, "").trim();
-    return `${clipped || plain.slice(0, 177)}...`;
-}
-function methodLabelFromId(methodId) {
-    return methodId
-        .split("-")
-        .filter(Boolean)
-        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
-        .join(" ") || methodId;
-}
-function detachMethodFromPreparation(preparation, methodId) {
-    if (methodIdForSourcePreparationConfig(preparation) !== methodId)
-        return preparation;
-    const { method: _removedMethod, ...detachedPreparation } = preparation;
-    return detachedPreparation;
-}
-function requireSelectedMethod(preparation) {
-    const methodId = methodIdForSourcePreparationConfig(preparation);
-    if (methodId)
-        return methodId;
-    throw new Error(`Select a Method for Preparation "${preparation.name}" before preparing it.`);
-}
-function actionCommandPreview(actionType, preparationName, methodId, values) {
-    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 === "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 proposal to draft readiness checks${preparationSuffix}. Approve to ask the configured local executor to draft saved 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, readinessRunFingerprint) {
-    if (!summary)
-        return null;
-    const resultFingerprint = readinessRunFingerprint ?? 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,
-        output_paths: resource.output_paths,
-        stages: resource.stages,
-    });
-}
+/** TTL for `POST /v1/compile-runs` idempotency-key dedupe entries. */
+const IDEMPOTENCY_TTL_MS = 60 * 60 * 1000;
+/** Idempotency cache size at which to schedule an opportunistic prune. */
+const IDEMPOTENCY_PRUNE_THRESHOLD = 64;
 export class LocalServiceRuntime {
-    rootPath;
     host;
     port;
     startedAt;
     packageVersion;
     handlers;
+    /**
+     * The seed root path the runtime was constructed with. Used as a
+     * non-preparation fallback when a preparation-independent route
+     * (methods, action proposals, runs listings) needs an anchor to load
+     * shared state (user-library methods, bundled methods, etc).
+     */
+    rootPath;
+    /**
+     * Per-instance bearer token. Mutating routes require this on the
+     * Authorization header. `null` means token-less mode (test harness).
+     */
+    authToken;
+    /** Map of prepDataDir -> PreparationContext. */
+    workspaces = new Map();
+    /** Hook called whenever a workspace is registered or deregistered. */
+    onRegistryChanged = null;
+    /** In-flight runs across all workspaces. Used for `idle_for_seconds`. */
+    activeRunCount = 0;
+    /**
+     * Active compile-run cancellation handles, keyed by run id. Populated
+     * when a compile run is launched and cleared once the run reaches a
+     * terminal state. Each entry remembers where the persisted record lives
+     * so cancel can mark it without re-resolving the Preparation.
+     */
+    activeCompileRuns = new Map();
+    /**
+     * Idempotency-key cache for `POST /v1/compile-runs`. Outer key is the
+     * resolved workspace root; inner key is the client-supplied idempotency
+     * value. Namespacing per workspace prevents key collisions across
+     * tenants on the same engine (CSO finding: a malicious workspace could
+     * otherwise hijack another workspace's run id by reusing its key).
+     * Entries expire after `IDEMPOTENCY_TTL_MS`.
+     */
+    idempotencyKeyCache = new Map();
+    /**
+     * Read-side caches. Polling clients (Compiler UI, CLI status loops)
+     * hit list/get endpoints multiple times per second; without these,
+     * every request re-walks the filesystem and re-parses every JSON
+     * record through Zod. The runtime invalidates each cache on the
+     * matching write path. See {@link runtime-caches} for design notes.
+     */
+    compileRunCache = new RunListingCache();
+    testRunCache = new RunListingCache();
+    readinessCache = new ReadinessCache();
+    sourceFilesCache = new MtimeListingCache();
+    methodListingCache = new MethodListingCache();
     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 ?? {};
+        this.authToken = options.authToken ?? null;
+        this.rootPath = resolve(options.rootPath);
+        // Auto-register the initial workspace so single-workspace callers
+        // (existing tests, the current `interf web` command) work without
+        // additional bootstrapping. The constructor seed is the only role
+        // `options.rootPath` plays; runtime methods take `prepDataDir`
+        // explicitly afterwards.
+        this.registerPreparation(this.rootPath);
+    }
+    setBoundPort(port) {
+        this.port = port;
+    }
+    /** Set a hook that fires whenever the registered workspaces change. */
+    setOnRegistryChanged(handler) {
+        this.onRegistryChanged = handler;
+    }
+    /**
+     * Register a workspace with this runtime. Returns the PreparationContext.
+     * Idempotent: re-registering an existing workspace updates `lastActivity`.
+     */
+    registerPreparation(prepDataDir) {
+        const resolved = resolve(prepDataDir);
+        const now = new Date().toISOString();
+        const existing = this.workspaces.get(resolved);
+        if (existing) {
+            existing.lastActivity = now;
+            this.onRegistryChanged?.();
+            return existing;
+        }
+        const context = {
+            rootPath: resolved,
+            startedAt: now,
+            lastActivity: now,
+        };
+        this.workspaces.set(resolved, context);
+        this.onRegistryChanged?.();
+        return context;
+    }
+    /**
+     * Remove a workspace from the runtime. Returns true if a workspace was
+     * removed.
+     */
+    deregisterPreparation(prepDataDir) {
+        const resolved = resolve(prepDataDir);
+        const removed = this.workspaces.delete(resolved);
+        if (removed) {
+            this.onRegistryChanged?.();
+        }
+        return removed;
+    }
+    /**
+     * Most recently active workspace, or the first registered if none has
+     * activity yet. Server code uses this as the fallback when a request
+     * omits the workspace header. Throws if no workspace is registered.
+     */
+    defaultPreparationDataDir() {
+        if (this.workspaces.size === 0) {
+            throw new Error("Local service has no registered workspaces.");
+        }
+        let best = null;
+        let bestKey = -Infinity;
+        for (const context of this.workspaces.values()) {
+            const key = Date.parse(context.lastActivity);
+            if (Number.isFinite(key) && key > bestKey) {
+                best = context;
+                bestKey = key;
+            }
+        }
+        return (best ?? this.workspaces.values().next().value).rootPath;
+    }
+    /** Look up a workspace context by rootPath. */
+    getPreparationContext(prepDataDir) {
+        return this.workspaces.get(resolve(prepDataDir)) ?? null;
+    }
+    /** All registered workspaces, ordered by registration time. */
+    listRegisteredPreparations() {
+        return Array.from(this.workspaces.values()).sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
+    }
+    /** True when no workspaces are registered. */
+    hasNoWorkspaces() {
+        return this.workspaces.size === 0;
+    }
+    /** Number of registered workspaces. */
+    registeredPreparationCount() {
+        return this.workspaces.size;
+    }
+    /** Increment in-flight run counter. Call when a long-running run starts. */
+    beginActiveRun() {
+        this.activeRunCount += 1;
+    }
+    /** Decrement in-flight run counter. Pair with `beginActiveRun`. */
+    endActiveRun() {
+        if (this.activeRunCount > 0)
+            this.activeRunCount -= 1;
+    }
+    /** Sum of in-flight runs across all workspaces. */
+    activeRuns() {
+        return this.activeRunCount;
+    }
+    /**
+     * Mark the workspace as recently active. Routes call this on entry so
+     * `idleForSeconds` and the registry snapshots stay in sync with the
+     * actual request cadence.
+     */
+    touchPreparation(prepDataDir) {
+        const context = this.workspaces.get(resolve(prepDataDir));
+        if (context) {
+            context.lastActivity = new Date().toISOString();
+        }
+    }
+    /** Snapshot of registered workspaces for the registry / status output. */
+    registeredPreparationSnapshots() {
+        return this.listRegisteredPreparations().map((context) => ServiceRegistryWorkspaceSchema.parse({
+            control_path: context.rootPath,
+            registered_at: context.startedAt,
+            last_activity: context.lastActivity,
+        }));
+    }
+    /** Seconds since the most recent workspace activity (0 if active). */
+    idleForSeconds() {
+        const all = this.listRegisteredPreparations();
+        if (all.length === 0)
+            return 0;
+        if (this.activeRunCount > 0)
+            return 0;
+        let mostRecent = 0;
+        for (const context of all) {
+            const ts = Date.parse(context.lastActivity);
+            if (Number.isFinite(ts) && ts > mostRecent)
+                mostRecent = ts;
+        }
+        if (mostRecent <= 0)
+            return 0;
+        const elapsed = Math.max(0, Date.now() - mostRecent);
+        return Math.floor(elapsed / 1000);
     }
-    health() {
-        const sourceFolderPath = resolveConfiguredSourceFolderPath(this.rootPath);
+    health(prepDataDir) {
+        const sourceFolderPath = prepDataDir ? resolveConfiguredSourceFolderPath(prepDataDir) : null;
         return LocalServiceHealthSchema.parse({
             kind: "interf-local-service-health",
             version: 1,
@@ -716,52 +235,59 @@ export class LocalServiceRuntime {
             host: this.host,
             port: this.port,
             service_url: buildLocalServiceUrl({ host: this.host, port: this.port }),
-            control_path: this.rootPath,
+            ...(prepDataDir ? { control_path: prepDataDir } : {}),
             source_folder_path: sourceFolderPath,
             started_at: this.startedAt,
             ...(this.packageVersion ? { package_version: this.packageVersion } : {}),
+            instance_started_at: this.startedAt,
+            registered_workspaces: this.registeredPreparationSnapshots(),
+            active_runs: this.activeRunCount,
+            idle_for_seconds: this.idleForSeconds(),
         });
     }
-    listPreparations() {
-        const config = loadSourceFolderConfig(this.rootPath);
+    listPreparations(prepDataDir) {
+        const config = loadSourceFolderConfig(prepDataDir);
         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);
+            const compileRuns = this.listCompileRunsForPreparation(prepDataDir, preparation.name);
+            const testRuns = this.listTestRunsForPreparation(prepDataDir, preparation.name);
+            const readiness = this.computePreparationReadiness(prepDataDir, preparation);
+            return buildPreparationResource(prepDataDir, preparation, readiness, compileRuns[0]?.run_id ?? null, testRuns[0]?.run_id ?? null);
         });
     }
-    getPreparation(preparationName) {
-        return this.listPreparations().find((preparation) => preparation.name === preparationName) ?? null;
+    getPreparation(prepDataDir, preparationName) {
+        return this.listPreparations(prepDataDir).find((preparation) => preparation.name === preparationName) ?? null;
     }
-    listPreparationReadiness() {
-        return this.listReadiness().map(readinessStateToPreparationReadiness);
+    listPreparationReadiness(prepDataDir) {
+        return this.listReadiness(prepDataDir).map(readinessStateToPreparationReadiness);
     }
-    getPreparationReadiness(preparationName) {
-        const readiness = this.getReadiness(preparationName);
+    getPreparationReadiness(prepDataDir, preparationName) {
+        const readiness = this.getReadiness(prepDataDir, preparationName);
         return readiness ? readinessStateToPreparationReadiness(readiness) : null;
     }
-    listReadiness() {
-        const config = loadSourceFolderConfig(this.rootPath);
-        return listSourcePreparationConfigs(config).map((preparation) => this.computePreparationReadiness(preparation));
+    listReadiness(prepDataDir) {
+        const config = loadSourceFolderConfig(prepDataDir);
+        return listSourcePreparationConfigs(config).map((preparation) => this.computePreparationReadiness(prepDataDir, preparation));
+    }
+    getReadiness(prepDataDir, preparationName) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
+        return preparation ? this.computePreparationReadiness(prepDataDir, preparation) : null;
     }
-    getReadiness(preparationName) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
-        return preparation ? this.computePreparationReadiness(preparation) : null;
+    computePreparationReadiness(prepDataDir, preparation) {
+        return this.readinessCache.get(prepDataDir, preparation.name, () => this.computePreparationReadinessUncached(prepDataDir, preparation));
     }
-    computePreparationReadiness(preparation) {
+    computePreparationReadinessUncached(prepDataDir, preparation) {
         const generatedAt = new Date().toISOString();
-        const compiledPath = portableContextPath(this.rootPath, preparation.name);
+        const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), 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 readinessRun = this.readLatestReadinessRun(preparation.name);
+        const compileRun = this.listCompileRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
+        const testRun = this.listTestRunsForPreparation(prepDataDir, preparation.name)[0] ?? null;
+        const readinessRun = this.readLatestReadinessRun(prepDataDir, preparation.name);
         const configuredChecks = preparation.checks.length;
         const currentFingerprint = configuredChecks > 0 ? fingerprintReadinessChecks(preparation.checks) : null;
         const readinessRunFingerprint = readinessRun?.checks_fingerprint ?? null;
-        const sourceResult = readinessTargetResult(readinessRun?.raw, currentFingerprint, readinessRunFingerprint);
+        const sourceResult = readinessTargetResult(readinessRun?.source_files, currentFingerprint, readinessRunFingerprint);
         const contextResult = readinessTargetResult(readinessRun?.compiled, currentFingerprint, readinessRunFingerprint);
         const checksStale = Boolean(currentFingerprint && readinessRunFingerprint && currentFingerprint !== readinessRunFingerprint);
         const compileCheck = (() => {
@@ -879,39 +405,46 @@ export class LocalServiceRuntime {
             checks,
         });
     }
-    listSourceFiles(preparationName) {
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
+    listSourceFiles(prepDataDir, preparationName) {
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
             .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,
+            const sourceFolderPath = resolveSourcePreparationPath(prepDataDir, preparation);
+            const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
+            // Cache by source-folder root mtime so identical UI polls do not
+            // re-walk and re-stat the entire tree. The cache imposes a short
+            // TTL (see runtime-caches.ts) so deeper changes are still picked
+            // up promptly.
+            const cacheKey = `${preparation.name}\0${sourceFolderPath}\0${compiledPath}`;
+            return this.sourceFilesCache.get(cacheKey, sourceFolderPath, () => {
+                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) => {
+    listWorkspaceFiles(prepDataDir) {
+        const sourceFolderPath = resolveConfiguredSourceFolderPath(prepDataDir) ?? prepDataDir;
+        return discoverSourceFiles(sourceFolderPath, prepDataDir).sourceFiles.map((relativePath) => {
             const absolutePath = join(sourceFolderPath, relativePath);
             let sizeBytes = 0;
             let modifiedAt = null;
@@ -932,51 +465,61 @@ export class LocalServiceRuntime {
             });
         });
     }
-    listMethods() {
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath));
-        const choices = listCompiledMethodChoices(this.rootPath);
-        return choices.map((method) => {
-            const activeForPreparations = preparations
-                .filter((preparation) => methodIdForSourcePreparationConfig(preparation) === 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,
-                output_paths: (method.contextInterface?.zones ?? [])
-                    .filter((zone) => zone.role === "output")
-                    .map((zone) => contextInterfaceArtifactPath(zone))
-                    .sort(),
-                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 } : {}),
-                })),
+    listMethods(prepDataDir) {
+        // The Method choices list is dominated by repeated reads of
+        // method.json + context-interface across builtin / user / workspace
+        // method roots. Key the cache off mtimes for the three roots; if
+        // any of them changes (a new local Method, an edit to the user
+        // library, etc.) the cache misses and we re-resolve.
+        const builtinRoot = join(PACKAGE_ROOT, "builtin-methods");
+        const localRoot = preparationMethodsRoot(asPreparationDataDir(prepDataDir));
+        const userRoot = userMethodsRoot();
+        return this.methodListingCache.get(prepDataDir, [builtinRoot, localRoot, userRoot], () => {
+            const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
+            const choices = listCompiledMethodChoices(prepDataDir);
+            return choices.map((method) => {
+                const activeForPreparations = preparations
+                    .filter((preparation) => methodIdForSourcePreparationConfig(preparation) === method.id)
+                    .map((preparation) => preparation.name);
+                return buildMethodResource({
+                    id: method.id,
+                    path: resolveMethodPackageSourcePath(prepDataDir, 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,
+                    output_paths: (method.contextInterface?.zones ?? [])
+                        .filter((zone) => zone.role === "output")
+                        .map((zone) => contextInterfaceArtifactPath(zone))
+                        .sort(),
+                    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;
+    getMethod(prepDataDir, methodId) {
+        return this.listMethods(prepDataDir).find((method) => method.id === methodId) ?? null;
     }
-    listJobs() {
-        return newestJobFirst(listJsonFiles(localJobsRoot(this.rootPath))
+    listJobs(prepDataDir) {
+        return byCreatedAtDesc(listJsonFiles(localJobsRoot(prepDataDir))
             .map(readLocalJobRunAt)
             .filter((run) => run !== null));
     }
-    getJob(runId) {
-        return this.listJobs().find((run) => run.run_id === runId) ?? null;
+    getJob(prepDataDir, runId) {
+        return this.listJobs(prepDataDir).find((run) => run.run_id === runId) ?? null;
     }
-    getJobEvents(runId) {
-        return this.getJob(runId)?.events ?? null;
+    getJobEvents(prepDataDir, runId) {
+        return this.getJob(prepDataDir, runId)?.events ?? null;
     }
     getExecutorStatus() {
         const checkedAt = new Date().toISOString();
@@ -1046,26 +589,26 @@ export class LocalServiceRuntime {
         });
         return this.getExecutorStatus();
     }
-    listActionProposals() {
-        return newestActionProposalFirst(listJsonFiles(actionProposalsRoot(this.rootPath))
+    listActionProposals(prepDataDir) {
+        return byCreatedAtDesc(listJsonFiles(actionProposalsRoot(prepDataDir))
             .map(readActionProposalAt)
             .filter((proposal) => proposal !== null));
     }
-    getActionProposal(proposalId) {
-        return this.listActionProposals().find((proposal) => proposal.proposal_id === proposalId) ?? null;
+    getActionProposal(prepDataDir, proposalId) {
+        return this.listActionProposals(prepDataDir).find((proposal) => proposal.proposal_id === proposalId) ?? null;
     }
-    async createActionProposal(requestValue) {
+    async createActionProposal(prepDataDir, requestValue) {
         const request = ActionProposalCreateRequestSchema.parse(requestValue);
         const proposal = ActionProposalResourceSchema.parse({
-            ...(await this.buildActionProposal(request)),
+            ...(await this.buildActionProposal(prepDataDir, request)),
             client_origin: request.client_origin,
         });
-        this.writeActionProposal(proposal);
+        this.writeActionProposal(prepDataDir, proposal);
         return proposal;
     }
-    async decideActionProposal(proposalId, requestValue) {
+    async decideActionProposal(prepDataDir, proposalId, requestValue) {
         const decision = ActionProposalApprovalRequestSchema.parse(requestValue);
-        const current = this.getActionProposal(proposalId);
+        const current = this.getActionProposal(prepDataDir, proposalId);
         if (!current)
             return null;
         if (current.status !== "awaiting_approval") {
@@ -1082,11 +625,11 @@ export class LocalServiceRuntime {
                 ...(decision.note ? { note: decision.note } : {}),
             },
         });
-        this.writeActionProposal(decided);
+        this.writeActionProposal(prepDataDir, decided);
         if (!decision.approved)
             return decided;
         try {
-            const submission = await this.submitActionProposal(decided);
+            const submission = await this.submitActionProposal(prepDataDir, decided);
             const submitted = ActionProposalResourceSchema.parse({
                 ...decided,
                 status: "submitted",
@@ -1094,7 +637,7 @@ export class LocalServiceRuntime {
                 submitted_run_id: submission.runId,
                 submitted_run_type: submission.runType,
             });
-            this.writeActionProposal(submitted);
+            this.writeActionProposal(prepDataDir, submitted);
             return submitted;
         }
         catch (error) {
@@ -1104,25 +647,25 @@ export class LocalServiceRuntime {
                 updated_at: new Date().toISOString(),
                 error: error instanceof Error ? error.message : String(error),
             });
-            this.writeActionProposal(failed);
+            this.writeActionProposal(prepDataDir, failed);
             return failed;
         }
     }
-    listRunObservability() {
+    listRunObservability(prepDataDir) {
         return [
-            ...this.listCompileRuns().map((resource) => compileRunToObservability(resource.run)),
-            ...this.listTestRuns().map(testRunToObservability),
-            ...this.listJobs().map(jobRunToObservability),
+            ...this.listCompileRuns(prepDataDir).map((resource) => compileRunToObservability(resource.run)),
+            ...this.listTestRuns(prepDataDir).map(testRunToObservability),
+            ...this.listJobs(prepDataDir).map(jobRunToObservability),
         ].sort((left, right) => {
             const leftTime = timestampKey(left.started_at ?? left.created_at ?? left.finished_at);
             const rightTime = timestampKey(right.started_at ?? right.created_at ?? right.finished_at);
             return rightTime - leftTime;
         });
     }
-    getRunObservability(runId) {
-        return this.listRunObservability().find((run) => run.run_id === runId) ?? null;
+    getRunObservability(prepDataDir, runId) {
+        return this.listRunObservability(prepDataDir).find((run) => run.run_id === runId) ?? null;
     }
-    createJobRun(requestValue) {
+    createJobRun(prepDataDir, requestValue) {
         const request = LocalJobRunCreateRequestSchema.parse(requestValue);
         const runId = createRunId("job");
         const now = new Date().toISOString();
@@ -1154,12 +697,12 @@ export class LocalServiceRuntime {
                 },
             ],
         });
-        this.writeJobRun(run);
+        this.writeJobRun(prepDataDir, run);
         return run;
     }
-    appendJobRunEvent(runId, requestValue) {
+    appendJobRunEvent(prepDataDir, runId, requestValue) {
         const request = LocalJobEventAppendRequestSchema.parse(requestValue);
-        const current = this.getJob(runId);
+        const current = this.getJob(prepDataDir, runId);
         if (!current)
             return null;
         const event = {
@@ -1174,12 +717,12 @@ export class LocalServiceRuntime {
             ...(request.output ? { output: request.output } : {}),
         };
         const next = LocalJobRunResourceSchema.parse(applyEventToLocalJob(current, event));
-        this.writeJobRun(next);
+        this.writeJobRun(prepDataDir, next);
         return next;
     }
-    async createReadinessCheckDraftRun(requestValue) {
+    async createReadinessCheckDraftRun(prepDataDir, requestValue) {
         const request = ReadinessCheckDraftCreateRequestSchema.parse(requestValue);
-        const job = this.createJobRun({
+        const job = this.createJobRun(prepDataDir, {
             job_type: "readiness-check-draft",
             title: `Draft readiness checks for ${request.preparation}`,
             preparation: request.preparation,
@@ -1207,7 +750,7 @@ export class LocalServiceRuntime {
                 },
             ],
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.started",
             step_id: "read-source",
             message: "Reading source files for readiness-check evidence.",
@@ -1216,7 +759,7 @@ export class LocalServiceRuntime {
                 source_folder_path: request.source_folder_path,
             },
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.completed",
             step_id: "read-source",
             message: "Source folder is ready for drafting readiness checks.",
@@ -1225,7 +768,7 @@ export class LocalServiceRuntime {
                 source_folder_path: request.source_folder_path,
             },
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.started",
             step_id: "agent-draft",
             message: "Drafting saved readiness checks from the source files.",
@@ -1234,30 +777,31 @@ export class LocalServiceRuntime {
                 target_count: request.target_count,
             },
         });
-        void this.runReadinessCheckDraftInBackground(request, job.run_id);
-        return this.getJob(job.run_id) ?? job;
+        void this.runReadinessCheckDraftInBackground(prepDataDir, request, job.run_id);
+        return this.getJob(prepDataDir, job.run_id) ?? job;
     }
-    applyMethodChange(requestValue) {
+    applyMethodChange(prepDataDir, requestValue) {
         const request = MethodChangeCreateRequestSchema.parse(requestValue);
         const outputPath = request.operation === "duplicate"
-            ? methodDefinitionPath(this.rootPath, request.new_method_id)
-            : methodDefinitionPath(this.rootPath, request.method);
+            ? methodDefinitionPath(prepDataDir, request.new_method_id)
+            : methodDefinitionPath(prepDataDir, request.method);
         if (request.operation === "duplicate") {
-            if (resolveMethodPackageSourcePath(this.rootPath, request.new_method_id)) {
+            if (resolveMethodPackageSourcePath(prepDataDir, request.new_method_id)) {
                 throw new Error(`Method "${request.new_method_id}" already exists.`);
             }
-            if (!resolveMethodPackageSourcePath(this.rootPath, request.method)) {
+            if (!resolveMethodPackageSourcePath(prepDataDir, request.method)) {
                 throw new Error(`Method "${request.method}" does not exist.`);
             }
             const label = request.label ?? methodLabelFromId(request.new_method_id);
             const hint = request.hint ?? `Duplicate of ${request.method}`;
             const methodPath = seedLocalMethodPackageFromBase({
-                sourcePath: this.rootPath,
+                prepDataDir,
                 baseMethodId: request.method,
                 methodId: request.new_method_id,
                 label,
                 hint,
             });
+            this.methodListingCache.invalidate(prepDataDir);
             return MethodChangeResultSchema.parse({
                 kind: "interf-method-change-result",
                 version: 1,
@@ -1273,19 +817,24 @@ export class LocalServiceRuntime {
         if (request.confirmation !== request.method) {
             throw new Error(`Type ${request.method} to confirm Method removal.`);
         }
-        const localMethodPath = methodDefinitionPath(this.rootPath, request.method);
+        const localMethodPath = methodDefinitionPath(prepDataDir, request.method);
         if (request.method === DEFAULT_METHOD_ID || !existsSync(localMethodPath)) {
             throw new Error(`Method "${request.method}" is not a removable local Method.`);
         }
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath));
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
         const updatedPreparations = preparations
             .filter((preparation) => methodIdForSourcePreparationConfig(preparation) === request.method);
         if (updatedPreparations.length > 0) {
-            saveSourceFolderConfig(this.rootPath, {
+            saveSourceFolderConfig(prepDataDir, {
                 preparations: preparations.map((preparation) => detachMethodFromPreparation(preparation, request.method)),
             });
+            // Detaching a Method changes readiness shape for those Preparations.
+            for (const preparation of updatedPreparations) {
+                this.readinessCache.invalidatePreparation(prepDataDir, preparation.name);
+            }
         }
         rmSync(outputPath, { recursive: true, force: true });
+        this.methodListingCache.invalidate(prepDataDir);
         return MethodChangeResultSchema.parse({
             kind: "interf-method-change-result",
             version: 1,
@@ -1299,7 +848,75 @@ export class LocalServiceRuntime {
                 : `Removed Method ${request.method}.`,
         });
     }
-    applyPreparationSetup(requestValue) {
+    /**
+     * Bootstrap the workspace's source-folder binding and seed the default
+     * Method. Idempotent: re-running with the same source folder preserves
+     * existing preparations and reports `changed: false`.
+     *
+     * The CLI calls this in place of writing `interf.json` directly, so the
+     * operation is recorded by the service (and visible to other clients).
+     */
+    bootstrapWorkspace(prepDataDir, requestValue) {
+        const request = WorkspaceBootstrapCreateRequestSchema.parse(requestValue);
+        const requestedPath = request.source_folder?.path?.trim() ?? null;
+        const existing = loadSourceFolderConfig(prepDataDir);
+        const existingSourcePath = existing?.source_folder?.path ?? null;
+        const preparations = existing?.preparations ?? [];
+        let sourceFolderPath = existingSourcePath;
+        let sourceChanged = false;
+        if (requestedPath && requestedPath.length > 0) {
+            // Validate that the source folder exists relative to the workspace.
+            const resolvedSourcePath = resolve(prepDataDir, requestedPath);
+            if (!existsSync(resolvedSourcePath) || !statSync(resolvedSourcePath).isDirectory()) {
+                throw new Error(`Source folder "${requestedPath}" is not available.`);
+            }
+            if (existingSourcePath !== requestedPath) {
+                sourceFolderPath = requestedPath;
+                sourceChanged = true;
+            }
+        }
+        const writeNeeded = !existing || sourceChanged;
+        if (writeNeeded) {
+            saveSourceFolderConfig(prepDataDir, {
+                ...(sourceFolderPath ? { source_folder: { path: sourceFolderPath } } : {}),
+                preparations,
+            });
+            // Source folder rebound: drop every cached read for this workspace.
+            this.readinessCache.invalidateWorkspace(prepDataDir);
+            this.compileRunCache.invalidateWorkspace(prepDataDir);
+            this.testRunCache.invalidateWorkspace(prepDataDir);
+            this.sourceFilesCache.invalidateAll();
+            this.methodListingCache.invalidate(prepDataDir);
+        }
+        let seededMethodId = null;
+        let seededDefaultMethod = false;
+        if (request.seed_default_method) {
+            const seeded = seedLocalDefaultMethod({ prepDataDir });
+            seededMethodId = seeded.methodId;
+            seededDefaultMethod = !seeded.alreadyExisted;
+            if (seededDefaultMethod) {
+                this.methodListingCache.invalidate(prepDataDir);
+            }
+        }
+        const changed = writeNeeded || seededDefaultMethod;
+        return WorkspaceBootstrapResultSchema.parse({
+            kind: "interf-workspace-bootstrap-result",
+            version: 1,
+            control_path: prepDataDir,
+            config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
+            source_folder_path: sourceFolderPath,
+            preparations: preparations.length,
+            seeded_default_method: seededDefaultMethod,
+            default_method_id: seededMethodId,
+            changed,
+            message: changed
+                ? sourceFolderPath
+                    ? `Workspace ready. Source Folder: ${sourceFolderPath}.`
+                    : `Workspace ready.`
+                : `Workspace already initialized.`,
+        });
+    }
+    applyPreparationSetup(prepDataDir, requestValue) {
         const request = PreparationSetupCreateRequestSchema.parse(requestValue);
         const preparationConfig = request.preparation;
         const methodId = methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID;
@@ -1307,11 +924,18 @@ export class LocalServiceRuntime {
             ...preparationConfig,
             method: methodId,
         };
-        const sourceFolderPath = resolveSourcePreparationPath(this.rootPath, normalizedPreparationConfig);
+        const sourceFolderPath = resolveSourcePreparationPath(prepDataDir, normalizedPreparationConfig);
         if (!existsSync(sourceFolderPath) || !statSync(sourceFolderPath).isDirectory()) {
             throw new Error(`Source folder "${preparationConfig.path}" is not available.`);
         }
-        upsertSourcePreparationConfig(this.rootPath, normalizedPreparationConfig);
+        upsertSourcePreparationConfig(prepDataDir, normalizedPreparationConfig);
+        // The Preparation's bound source folder + Method may have changed:
+        // bust the per-preparation readiness, runs, and method-listing
+        // caches so the next read reflects the new shape.
+        this.readinessCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
+        this.compileRunCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
+        this.testRunCache.invalidatePreparation(prepDataDir, normalizedPreparationConfig.name);
+        this.methodListingCache.invalidate(prepDataDir);
         const operation = request.setup_mode === "select-method" ? "select-method" : "create";
         return PreparationSetupResultSchema.parse({
             kind: "interf-preparation-setup-result",
@@ -1320,47 +944,55 @@ export class LocalServiceRuntime {
             preparation: normalizedPreparationConfig.name,
             method: methodId,
             source_folder_path: sourceFolderPath,
-            config_path: join(this.rootPath, "interf", "interf.json"),
-            portable_context_path: portableContextPath(this.rootPath, normalizedPreparationConfig.name),
+            config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
+            portable_context_path: preparationPortableContextPath(asPreparationDataDir(prepDataDir), normalizedPreparationConfig.name),
             changed: true,
             message: operation === "select-method"
                 ? `Preparation ${normalizedPreparationConfig.name} now uses Method ${methodId}.`
                 : `Preparation ${normalizedPreparationConfig.name} is saved.`,
         });
     }
-    applyPreparationChange(requestValue) {
+    applyPreparationChange(prepDataDir, requestValue) {
         const request = PreparationChangeCreateRequestSchema.parse(requestValue);
         if (request.confirmation !== request.preparation) {
             throw new Error(`Type ${request.preparation} to confirm Preparation removal.`);
         }
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), request.preparation);
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), request.preparation);
         if (!preparation) {
             throw new Error(`Preparation "${request.preparation}" is not saved.`);
         }
-        removeSourcePreparationConfig(this.rootPath, request.preparation);
+        removeSourcePreparationConfig(prepDataDir, request.preparation);
+        this.readinessCache.invalidatePreparation(prepDataDir, request.preparation);
+        this.compileRunCache.invalidatePreparation(prepDataDir, request.preparation);
+        this.testRunCache.invalidatePreparation(prepDataDir, request.preparation);
+        this.methodListingCache.invalidate(prepDataDir);
         return PreparationChangeResultSchema.parse({
             kind: "interf-preparation-change-result",
             version: 1,
             operation: "remove",
             preparation: request.preparation,
-            config_path: join(this.rootPath, "interf", "interf.json"),
-            portable_context_path: portableContextPath(this.rootPath, request.preparation),
+            config_path: preparationConfigPath(asPreparationDataDir(prepDataDir)),
+            portable_context_path: preparationPortableContextPath(asPreparationDataDir(prepDataDir), request.preparation),
             portable_context_retained: true,
             changed: true,
             message: `Removed Preparation ${request.preparation}. Portable Context files were retained.`,
         });
     }
-    applyReset(requestValue) {
+    applyReset(prepDataDir, requestValue) {
         const request = ResetRequestSchema.parse(requestValue);
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), request.preparation);
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), request.preparation);
         if (!preparation) {
             throw new Error(`Preparation "${request.preparation}" is not saved.`);
         }
-        const compiledPath = portableContextPath(this.rootPath, request.preparation);
+        const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), request.preparation);
         if (!existsSync(compiledPath)) {
             throw new Error(`Portable Context for Preparation "${request.preparation}" does not exist.`);
         }
         resetCompiledGeneratedState(compiledPath, request.scope);
+        // Reset wipes generated state, including saved compile/test/readiness records.
+        this.compileRunCache.invalidatePreparation(prepDataDir, request.preparation);
+        this.testRunCache.invalidatePreparation(prepDataDir, request.preparation);
+        this.readinessCache.invalidatePreparation(prepDataDir, request.preparation);
         return ResetResultSchema.parse({
             kind: "interf-reset-result",
             version: 1,
@@ -1371,16 +1003,16 @@ export class LocalServiceRuntime {
             message: `Reset ${request.scope} state for Preparation ${request.preparation}.`,
         });
     }
-    async createMethodAuthoringRun(requestValue, jobType = "method-authoring") {
+    async createMethodAuthoringRun(prepDataDir, requestValue, jobType = "method-authoring") {
         const request = MethodAuthoringCreateRequestSchema.parse(requestValue);
         const isImprovement = jobType === "method-improvement";
-        const job = this.createJobRun({
+        const job = this.createJobRun(prepDataDir, {
             job_type: jobType,
             title: isImprovement ? `Improve Method ${request.method_id}` : `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),
+            output_path: preparationMethodPackagePath(asPreparationDataDir(prepDataDir), request.method_id),
             steps: [
                 {
                     id: "inspect-source",
@@ -1409,7 +1041,7 @@ export class LocalServiceRuntime {
                 },
             ],
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.started",
             step_id: "inspect-source",
             message: isImprovement ? "Inspecting source files for Method improvement." : "Inspecting source files for Method drafting.",
@@ -1419,7 +1051,7 @@ export class LocalServiceRuntime {
                 checks: request.checks.length,
             },
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.completed",
             step_id: "inspect-source",
             message: "Source context is ready.",
@@ -1428,7 +1060,7 @@ export class LocalServiceRuntime {
                 checks: request.checks.length,
             },
         });
-        this.appendJobRunEvent(job.run_id, {
+        this.appendJobRunEvent(prepDataDir, job.run_id, {
             type: "step.started",
             step_id: "draft-package",
             message: isImprovement ? "Improving Method package." : "Drafting Method package.",
@@ -1438,23 +1070,23 @@ export class LocalServiceRuntime {
                 task_prompt: request.task_prompt,
             },
         });
-        void this.runMethodAuthoringInBackground(request, job.run_id);
-        return this.getJob(job.run_id) ?? job;
+        void this.runMethodAuthoringInBackground(prepDataDir, request, job.run_id);
+        return this.getJob(prepDataDir, job.run_id) ?? job;
     }
-    listPortableContexts() {
-        return listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))
-            .map((preparation) => this.getPortableContext(preparation.name))
+    listPortableContexts(prepDataDir) {
+        return listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
+            .map((preparation) => this.getPortableContext(prepDataDir, preparation.name))
             .filter((context) => context !== null);
     }
-    getPortableContext(preparationName) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
+    getPortableContext(prepDataDir, preparationName) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
         if (!preparation)
             return null;
-        const path = portableContextPath(this.rootPath, preparation.name);
+        const path = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparation.name);
         const config = readInterfConfig(path);
-        const compileRuns = this.listCompileRunsForPreparation(preparation.name);
-        const testRuns = this.listTestRunsForPreparation(preparation.name);
-        const readiness = this.computePreparationReadiness(preparation);
+        const compileRuns = this.listCompileRunsForPreparation(prepDataDir, preparation.name);
+        const testRuns = this.listTestRunsForPreparation(prepDataDir, preparation.name);
+        const readiness = this.computePreparationReadiness(prepDataDir, preparation);
         const method = config?.method ?? methodIdForSourcePreparationConfig(preparation);
         return PortableContextResourceSchema.parse({
             preparation: preparation.name,
@@ -1467,52 +1099,65 @@ export class LocalServiceRuntime {
             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()) {
+    listCompileRuns(prepDataDir) {
+        return byCreatedAtDesc(listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
+            .flatMap((preparation) => this.listCompileRunsForPreparation(prepDataDir, preparation.name))).map((run) => CompileRunResourceSchema.parse({ run }));
+    }
+    listCompileRunsForPreparation(prepDataDir, preparationName) {
+        return this.compileRunCache.get(prepDataDir, preparationName, () => {
+            const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparationName);
+            return byCreatedAtDesc(listJsonFiles(compileRunsRoot(compiledPath))
+                .map(readCompileRunAt)
+                .filter((run) => run !== null));
+        }, (run) => run.run_id);
+    }
+    getCompileRun(prepDataDir, runId) {
+        // Fast path: if the runId was seen during a recent listing, look up
+        // its owning preparation directly and return that preparation's
+        // cached entry instead of scanning every preparation on disk.
+        const known = this.compileRunCache.preparationFor(prepDataDir, runId);
+        if (known) {
+            const found = this.listCompileRunsForPreparation(prepDataDir, known).find((entry) => entry.run_id === runId);
+            if (found)
+                return CompileRunResourceSchema.parse({ run: found });
+        }
+        // Slow path: scan all preparations. Falls through after a cache
+        // miss for an in-flight run created before this process restarted.
+        for (const resource of this.listCompileRuns(prepDataDir)) {
             if (resource.run.run_id === runId)
                 return resource;
         }
         return null;
     }
-    getCompileRunEvents(runId) {
-        return this.getCompileRun(runId)?.run.events ?? null;
+    getCompileRunEvents(prepDataDir, runId) {
+        return this.getCompileRun(prepDataDir, runId)?.run.events ?? null;
     }
-    getCompileRunProof(runId) {
-        const run = this.getCompileRun(runId)?.run;
+    getCompileRunProof(prepDataDir, runId) {
+        const run = this.getCompileRun(prepDataDir, 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;
+    getCompileRunArtifacts(prepDataDir, runId) {
+        const run = this.getCompileRun(prepDataDir, runId)?.run;
         if (!run)
             return null;
         return uniqueArtifacts(run.stages.flatMap((stage) => stage.artifacts));
     }
-    async createCompileRun(requestValue) {
+    async createCompileRun(prepDataDir, requestValue) {
         const request = CompileRunCreateRequestSchema.parse(requestValue);
-        const preparationConfig = this.resolvePreparationConfig(request.preparation, {
+        const preparationConfig = this.resolvePreparationConfig(prepDataDir, request.preparation, {
             method: request.method,
             max_attempts: request.max_attempts,
             max_loops: request.max_loops,
         });
-        const compiledPath = this.ensureCompiledForRun(preparationConfig);
+        const compiledPath = this.ensureCompiledForRun(prepDataDir, preparationConfig);
         const runId = createRunId("compile");
         const now = new Date().toISOString();
         const method = getCompiledMethod(requireSelectedMethod(preparationConfig), {
-            sourcePath: this.rootPath,
+            prepDataDir,
         });
         const stageTotal = method.stages.length;
         const run = CompileRunSchema.parse({
@@ -1523,7 +1168,7 @@ export class LocalServiceRuntime {
             preparation: preparationConfig.name,
             method: method.id,
             backend: "native",
-            source_path: resolveSourcePreparationPath(this.rootPath, preparationConfig),
+            source_path: resolveSourcePreparationPath(prepDataDir, preparationConfig),
             portable_context_path: compiledPath,
             created_at: now,
             started_at: now,
@@ -1549,8 +1194,14 @@ export class LocalServiceRuntime {
             }),
             events: [],
         });
-        this.writeCompileRun(compiledPath, run);
-        await this.recordCompileRunEvent(compiledPath, runId, {
+        this.writeCompileRun(prepDataDir, compiledPath, run);
+        this.activeCompileRuns.set(runId, {
+            prepDataDir,
+            compiledPath,
+            preparation: preparationConfig.name,
+            cancelled: false,
+        });
+        await this.recordCompileRunEvent(prepDataDir, compiledPath, runId, {
             type: "run.started",
             event_id: createRunEventId("event"),
             run_id: runId,
@@ -1561,11 +1212,11 @@ export class LocalServiceRuntime {
             backend: "native",
         });
         const sink = {
-            emit: (event) => this.recordCompileRunEvent(compiledPath, runId, event),
+            emit: (event) => this.recordCompileRunEvent(prepDataDir, compiledPath, runId, event),
         };
-        void this.runCompileInBackground(request, {
+        void this.runCompileInBackground(prepDataDir, request, {
             runId,
-            sourcePath: this.rootPath,
+            sourcePath: prepDataDir,
             compiledPath,
             preparationConfig,
             events: sink,
@@ -1573,23 +1224,155 @@ export class LocalServiceRuntime {
         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)));
+    /**
+     * Cancel an in-flight compile run. Marks the persisted record as
+     * `cancelled`, emits a `run.failed` event to capture the cancellation in
+     * the run timeline, and clears the active handle so retries may start a
+     * fresh run. If the run already finished, returns
+     * `{ cancelled: false, reason: "already finished" }` and persists nothing.
+     */
+    cancelCompileRun(runId) {
+        const handle = this.activeCompileRuns.get(runId);
+        if (!handle) {
+            // Either unknown or already terminal. The server route already 404s
+            // unknown ids before calling this, so anything reaching here is a run
+            // we already finalized.
+            return { cancelled: false, reason: "already finished" };
+        }
+        if (handle.cancelled) {
+            return { cancelled: false, reason: "already cancelled" };
+        }
+        const cancelledAt = new Date().toISOString();
+        handle.cancelled = true;
+        handle.cancelledAt = cancelledAt;
+        const current = this.readCompileRun(handle.compiledPath, runId);
+        if (current && current.status !== "succeeded" && current.status !== "failed" && current.status !== "cancelled") {
+            const cancelledRun = {
+                ...current,
+                status: "cancelled",
+                finished_at: current.finished_at ?? cancelledAt,
+                events: [
+                    ...current.events,
+                    {
+                        type: "run.failed",
+                        event_id: createRunEventId("event"),
+                        run_id: runId,
+                        timestamp: cancelledAt,
+                        error: "Compile run cancelled by request.",
+                    },
+                ],
+            };
+            this.writeCompileRun(handle.prepDataDir, handle.compiledPath, cancelledRun);
+        }
+        return { cancelled: true };
+    }
+    /**
+     * Look up the run id previously associated with this idempotency key in
+     * `prepDataDir`. Returns null when the key is unknown or its TTL has
+     * elapsed. The workspace argument is required so that the same key in
+     * two different workspaces always returns two different runs.
+     */
+    findIdempotentCompileRun(prepDataDir, key) {
+        const resolvedRoot = resolve(prepDataDir);
+        const bucket = this.idempotencyKeyCache.get(resolvedRoot);
+        if (!bucket)
+            return null;
+        const entry = bucket.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= Date.now()) {
+            // Opportunistic single-key prune. The bulk prune runs on writes
+            // when the cache crosses the size threshold (see
+            // {@link recordIdempotentCompileRun}).
+            bucket.delete(key);
+            if (bucket.size === 0)
+                this.idempotencyKeyCache.delete(resolvedRoot);
+            return null;
+        }
+        return entry.runId;
+    }
+    /**
+     * Cache the run id created (or returned) for this idempotency key in
+     * `prepDataDir`. Entries expire after `IDEMPOTENCY_TTL_MS`. Pruning
+     * is opportunistic: the previous implementation walked every entry on
+     * every read AND write, which was O(N) per request. Now we only sweep
+     * when the cache grows past {@link IDEMPOTENCY_PRUNE_THRESHOLD}.
+     */
+    recordIdempotentCompileRun(prepDataDir, key, runId) {
+        const resolvedRoot = resolve(prepDataDir);
+        let bucket = this.idempotencyKeyCache.get(resolvedRoot);
+        if (!bucket) {
+            bucket = new Map();
+            this.idempotencyKeyCache.set(resolvedRoot, bucket);
+        }
+        bucket.set(key, {
+            runId,
+            expiresAt: Date.now() + IDEMPOTENCY_TTL_MS,
+        });
+        if (this.totalIdempotencyEntries() > IDEMPOTENCY_PRUNE_THRESHOLD) {
+            this.pruneIdempotencyKeyCache();
+        }
     }
-    listTestRunsForPreparation(preparationName) {
-        const compiledPath = portableContextPath(this.rootPath, preparationName);
-        return newestFirst(listJsonFiles(testRunsRoot(compiledPath))
-            .map(readTestRunAt)
-            .filter((run) => run !== null));
+    /** Total cached idempotency entries across all workspaces. */
+    totalIdempotencyEntries() {
+        let total = 0;
+        for (const bucket of this.idempotencyKeyCache.values())
+            total += bucket.size;
+        return total;
+    }
+    pruneIdempotencyKeyCache() {
+        const now = Date.now();
+        for (const [prepDataDir, bucket] of this.idempotencyKeyCache) {
+            for (const [key, entry] of bucket) {
+                if (entry.expiresAt <= now)
+                    bucket.delete(key);
+            }
+            if (bucket.size === 0)
+                this.idempotencyKeyCache.delete(prepDataDir);
+        }
     }
-    getTestRun(runId) {
-        return this.listTestRuns().find((run) => run.run_id === runId) ?? null;
+    /**
+     * Test seam: force the cached entry for `key` in `prepDataDir` to be
+     * expired so the next lookup returns null. Returns true when an entry was
+     * found and expired. Tests use this in place of fake timers because the
+     * idempotency TTL is one hour and faking `Date.now()` would destabilize
+     * unrelated runtime state.
+     */
+    expireIdempotencyKeyForTesting(prepDataDir, key) {
+        const bucket = this.idempotencyKeyCache.get(resolve(prepDataDir));
+        if (!bucket)
+            return false;
+        const entry = bucket.get(key);
+        if (!entry)
+            return false;
+        entry.expiresAt = Date.now() - 1;
+        return true;
+    }
+    listTestRuns(prepDataDir) {
+        return newestFirst(listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))
+            .flatMap((preparation) => this.listTestRunsForPreparation(prepDataDir, preparation.name)));
+    }
+    listTestRunsForPreparation(prepDataDir, preparationName) {
+        return this.testRunCache.get(prepDataDir, preparationName, () => {
+            const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparationName);
+            return newestFirst(listJsonFiles(testRunsRoot(compiledPath))
+                .map(readTestRunAt)
+                .filter((run) => run !== null));
+        }, (run) => run.run_id);
+    }
+    getTestRun(prepDataDir, runId) {
+        const known = this.testRunCache.preparationFor(prepDataDir, runId);
+        if (known) {
+            const found = this.listTestRunsForPreparation(prepDataDir, known).find((run) => run.run_id === runId);
+            if (found)
+                return found;
+        }
+        return this.listTestRuns(prepDataDir).find((run) => run.run_id === runId) ?? null;
     }
-    async createTestRun(requestValue) {
+    async createTestRun(prepDataDir, requestValue) {
         const request = TestRunCreateRequestSchema.parse(requestValue);
-        const preparationConfig = this.resolvePreparationConfig(request.preparation);
-        const compiledPath = portableContextPath(this.rootPath, preparationConfig.name);
+        const preparationConfig = this.resolvePreparationConfig(prepDataDir, request.preparation);
+        const compiledPath = preparationPortableContextPath(asPreparationDataDir(prepDataDir), preparationConfig.name);
         const compiledTarget = createCompiledTestTarget(compiledPath, preparationConfig.name, methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID);
         const runId = createRunId("test");
         const now = new Date().toISOString();
@@ -1598,31 +1381,42 @@ export class LocalServiceRuntime {
             status: "running",
             preparation: preparationConfig.name,
             mode: request.mode,
-            source_path: this.rootPath,
+            source_path: prepDataDir,
             portable_context_path: compiledTarget.eligible ? compiledPath : null,
             started_at: now,
             readiness_run: null,
             events: [],
         });
-        this.writeTestRun(compiledPath, initial);
-        void this.runTestInBackground(request, {
+        this.writeTestRun(prepDataDir, compiledPath, initial);
+        void this.runTestInBackground(prepDataDir, request, {
             runId,
-            sourcePath: this.rootPath,
+            sourcePath: prepDataDir,
             compiledPath,
             preparationConfig,
         }, initial);
         return initial;
     }
-    async runCompileInBackground(request, context) {
+    async runCompileInBackground(prepDataDir, request, context) {
+        this.beginActiveRun();
         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);
+            const wasCancelled = this.activeCompileRuns.get(context.runId)?.cancelled === true;
+            if (wasCancelled) {
+                // The run was cancelled while the handler was still running. The
+                // cancellation path already wrote a `cancelled` record; just refresh
+                // observability and skip emitting a second terminal event.
+                this.refreshCompileRunFromRuntime(prepDataDir, context.compiledPath, context.runId);
+                await this.emitRuntimeDerivedEvents(prepDataDir, context.compiledPath, context.runId);
+                await this.recordCompileRunEvent(prepDataDir, context.compiledPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
+                return;
+            }
+            this.refreshCompileRunFromRuntime(prepDataDir, context.compiledPath, context.runId);
+            await this.emitRuntimeDerivedEvents(prepDataDir, context.compiledPath, context.runId);
             if (!result.ok) {
-                await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+                await this.recordCompileRunEvent(prepDataDir, context.compiledPath, context.runId, {
                     type: "run.failed",
                     event_id: createRunEventId("event"),
                     run_id: context.runId,
@@ -1631,7 +1425,7 @@ export class LocalServiceRuntime {
                 });
             }
             else {
-                await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+                await this.recordCompileRunEvent(prepDataDir, context.compiledPath, context.runId, {
                     type: "run.completed",
                     event_id: createRunEventId("event"),
                     run_id: context.runId,
@@ -1639,26 +1433,31 @@ export class LocalServiceRuntime {
                     summary: "Portable context ready.",
                 });
             }
-            await this.recordCompileRunEvent(context.compiledPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(context.preparationConfig)));
+            await this.recordCompileRunEvent(prepDataDir, context.compiledPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
         }
         catch (error) {
-            await this.recordCompileRunEvent(context.compiledPath, context.runId, {
+            await this.recordCompileRunEvent(prepDataDir, 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),
             });
-            await this.recordCompileRunEvent(context.compiledPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(context.preparationConfig)));
+            await this.recordCompileRunEvent(prepDataDir, context.compiledPath, context.runId, this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, this.computePreparationReadiness(prepDataDir, context.preparationConfig)));
+        }
+        finally {
+            this.activeCompileRuns.delete(context.runId);
+            this.endActiveRun();
         }
     }
-    async runTestInBackground(request, context, initial) {
+    async runTestInBackground(prepDataDir, request, context, initial) {
+        this.beginActiveRun();
         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 readinessRun = result.readiness_run ?? this.readLatestReadinessRun(context.preparationConfig.name);
+            const readinessRun = result.readiness_run ?? this.readLatestReadinessRun(prepDataDir, context.preparationConfig.name);
             const resultEvent = readinessRun
                 ? this.checksEvaluatedEvent(context.runId, readinessRun)
                 : null;
@@ -1670,8 +1469,8 @@ export class LocalServiceRuntime {
                 events: resultEvent ? [resultEvent] : [],
                 ...(!result.ok ? { error: result.error ?? "Readiness check failed." } : {}),
             });
-            this.writeTestRun(context.compiledPath, nextWithoutReadiness);
-            const readiness = this.computePreparationReadiness(context.preparationConfig);
+            this.writeTestRun(prepDataDir, context.compiledPath, nextWithoutReadiness);
+            const readiness = this.computePreparationReadiness(prepDataDir, context.preparationConfig);
             const next = TestRunResourceSchema.parse({
                 ...nextWithoutReadiness,
                 readiness,
@@ -1680,7 +1479,7 @@ export class LocalServiceRuntime {
                     this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness),
                 ],
             });
-            this.writeTestRun(context.compiledPath, next);
+            this.writeTestRun(prepDataDir, context.compiledPath, next);
         }
         catch (error) {
             const failedWithoutReadiness = TestRunResourceSchema.parse({
@@ -1689,23 +1488,32 @@ export class LocalServiceRuntime {
                 finished_at: new Date().toISOString(),
                 error: error instanceof Error ? error.message : String(error),
             });
-            this.writeTestRun(context.compiledPath, failedWithoutReadiness);
-            const readiness = this.computePreparationReadiness(context.preparationConfig);
+            this.writeTestRun(prepDataDir, context.compiledPath, failedWithoutReadiness);
+            const readiness = this.computePreparationReadiness(prepDataDir, context.preparationConfig);
             const next = TestRunResourceSchema.parse({
                 ...failedWithoutReadiness,
                 readiness,
                 events: [this.readinessUpdatedEvent(context.runId, context.preparationConfig.name, readiness)],
             });
-            this.writeTestRun(context.compiledPath, next);
+            this.writeTestRun(prepDataDir, context.compiledPath, next);
+        }
+        finally {
+            this.endActiveRun();
         }
     }
-    async runReadinessCheckDraftInBackground(request, runId) {
+    async runReadinessCheckDraftInBackground(prepDataDir, request, runId) {
+        this.beginActiveRun();
+        return this.runReadinessCheckDraftInBackgroundInner(prepDataDir, request, runId).finally(() => {
+            this.endActiveRun();
+        });
+    }
+    async runReadinessCheckDraftInBackgroundInner(prepDataDir, request, runId) {
         try {
             if (!this.handlers.createReadinessCheckDraft) {
                 throw new Error("No readiness-check-draft handler is configured for this local service.");
             }
-            const result = ReadinessCheckDraftResultSchema.parse(await this.handlers.createReadinessCheckDraft(request, this.jobRunContext(runId)));
-            this.appendJobRunEvent(runId, {
+            const result = ReadinessCheckDraftResultSchema.parse(await this.handlers.createReadinessCheckDraft(request, this.jobRunContext(prepDataDir, runId)));
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.completed",
                 step_id: "agent-draft",
                 message: `Drafted ${result.checks.length} readiness checks.`,
@@ -1713,7 +1521,7 @@ export class LocalServiceRuntime {
                     checks: result.checks,
                 },
             });
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.started",
                 step_id: "normalize-checks",
                 message: "Normalizing drafted readiness checks into saved check records.",
@@ -1721,7 +1529,7 @@ export class LocalServiceRuntime {
                     checks: result.checks.length,
                 },
             });
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.completed",
                 step_id: "normalize-checks",
                 message: `${result.checks.length} readiness checks ready for review.`,
@@ -1729,15 +1537,15 @@ export class LocalServiceRuntime {
                     checks: result.checks.length,
                 },
             });
-            this.setJobRunResult(runId, result);
-            this.appendJobRunEvent(runId, {
+            this.setJobRunResult(prepDataDir, runId, result);
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "job.completed",
                 message: `Drafted ${result.checks.length} readiness checks.`,
             });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.failed",
                 step_id: "agent-draft",
                 message,
@@ -1745,20 +1553,26 @@ export class LocalServiceRuntime {
                     error: message,
                 },
             });
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "job.failed",
                 message,
             });
         }
     }
-    async runMethodAuthoringInBackground(request, runId) {
+    async runMethodAuthoringInBackground(prepDataDir, request, runId) {
+        this.beginActiveRun();
+        return this.runMethodAuthoringInBackgroundInner(prepDataDir, request, runId).finally(() => {
+            this.endActiveRun();
+        });
+    }
+    async runMethodAuthoringInBackgroundInner(prepDataDir, 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, {
+            const result = MethodAuthoringResultSchema.parse(await this.handlers.createMethodAuthoringRun(request, this.jobRunContext(prepDataDir, runId)));
+            this.setJobRunResult(prepDataDir, runId, result);
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: result.status === "executor-failed" ? "step.failed" : "step.completed",
                 step_id: "draft-package",
                 message: result.summary,
@@ -1769,7 +1583,7 @@ export class LocalServiceRuntime {
                     shell_path: result.shell_path,
                 },
             });
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.started",
                 step_id: "validate-package",
                 message: "Validating Method package structure and stage contract.",
@@ -1778,7 +1592,7 @@ export class LocalServiceRuntime {
                 },
             });
             if (result.status === "updated" || result.status === "no-change") {
-                this.appendJobRunEvent(runId, {
+                this.appendJobRunEvent(prepDataDir, runId, {
                     type: "step.completed",
                     step_id: "validate-package",
                     message: result.summary,
@@ -1787,13 +1601,13 @@ export class LocalServiceRuntime {
                         validation: result.validation ?? null,
                     },
                 });
-                this.appendJobRunEvent(runId, {
+                this.appendJobRunEvent(prepDataDir, runId, {
                     type: "job.completed",
                     message: result.summary,
                 });
             }
             else {
-                this.appendJobRunEvent(runId, {
+                this.appendJobRunEvent(prepDataDir, runId, {
                     type: "step.failed",
                     step_id: "validate-package",
                     message: result.summary,
@@ -1802,7 +1616,7 @@ export class LocalServiceRuntime {
                         validation: result.validation ?? null,
                     },
                 });
-                this.appendJobRunEvent(runId, {
+                this.appendJobRunEvent(prepDataDir, runId, {
                     type: "job.failed",
                     message: result.summary,
                 });
@@ -1810,7 +1624,7 @@ export class LocalServiceRuntime {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "step.failed",
                 step_id: "draft-package",
                 message,
@@ -1818,29 +1632,29 @@ export class LocalServiceRuntime {
                     error: message,
                 },
             });
-            this.appendJobRunEvent(runId, {
+            this.appendJobRunEvent(prepDataDir, runId, {
                 type: "job.failed",
                 message,
             });
         }
     }
-    jobRunContext(runId) {
+    jobRunContext(prepDataDir, runId) {
         return {
             runId,
-            sourcePath: this.rootPath,
+            sourcePath: prepDataDir,
             emit: (event) => {
-                this.appendJobRunEvent(runId, event);
+                this.appendJobRunEvent(prepDataDir, runId, event);
             },
         };
     }
-    defaultPreparationName() {
-        const preparation = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))[0];
+    defaultPreparationName(prepDataDir) {
+        const preparation = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))[0];
         if (!preparation) {
             throw new Error("No Preparation is saved in this control plane folder.");
         }
         return preparation.name;
     }
-    async planActionProposal(request) {
+    async planActionProposal(prepDataDir, request) {
         if (!this.handlers.planActionProposal) {
             return ActionProposalPlanSchema.parse({
                 action_type: "clarification",
@@ -1848,15 +1662,15 @@ export class LocalServiceRuntime {
                 assistant_message: "No local action planner is configured for this Interf Workspace.",
             });
         }
-        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath));
+        const preparations = listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir));
         let rawPlan;
         try {
             rawPlan = await this.handlers.planActionProposal(request, {
-                sourcePath: this.rootPath,
+                sourcePath: prepDataDir,
                 preparations,
                 preparationHealth: preparations.map((preparation) => {
                     const readinessChecks = preparation.checks?.length ?? 0;
-                    const portableContextReady = hasCompiledTestTarget(this.rootPath, preparation);
+                    const portableContextReady = hasCompiledTestTarget(prepDataDir, preparation);
                     return {
                         name: preparation.name,
                         readiness_checks: readinessChecks,
@@ -1869,8 +1683,8 @@ export class LocalServiceRuntime {
                             : ["prepare"],
                     };
                 }),
-                sourceFolders: listSourceFolderChoices(this.rootPath),
-                recentProposals: this.listActionProposals().slice(0, 5),
+                sourceFolders: listSourceFolderChoices(prepDataDir),
+                recentProposals: this.listActionProposals(prepDataDir).slice(0, 5),
             });
         }
         catch {
@@ -1927,7 +1741,7 @@ export class LocalServiceRuntime {
             error: null,
         });
     }
-    async buildActionProposal(request) {
+    async buildActionProposal(prepDataDir, request) {
         const structuredPreparationSetup = PreparationSetupActionValuesSchema.safeParse(request.values);
         const structuredMethodAuthoring = MethodAuthoringActionValuesSchema.safeParse(request.values);
         const structuredActionType = actionTypeFromValues(request.values);
@@ -1952,7 +1766,7 @@ export class LocalServiceRuntime {
                 action_type: structuredPlanActionType,
                 ...(request.preparation ? { preparation: request.preparation } : {}),
             })
-            : await this.planActionProposal(request);
+            : await this.planActionProposal(prepDataDir, request);
         const actionType = structuredPlanActionType ?? plan.action_type;
         if (directServiceEndpointForAction(actionType)) {
             return this.directServiceActionClarification({
@@ -2003,13 +1817,13 @@ export class LocalServiceRuntime {
             const requestedPreparationName = plan.preparation ?? request.preparation ?? null;
             const fallbackPreparation = requestedPreparationName
                 ? null
-                : listSourcePreparationConfigs(loadSourceFolderConfig(this.rootPath))[0] ?? null;
+                : listSourcePreparationConfigs(loadSourceFolderConfig(prepDataDir))[0] ?? null;
             const preparationConfig = requestedPreparationName
-                ? this.resolvePreparationConfig(requestedPreparationName)
+                ? this.resolvePreparationConfig(prepDataDir, requestedPreparationName)
                 : fallbackPreparation;
             const preparationPath = preparationConfig
-                ? resolveSourcePreparationPath(this.rootPath, preparationConfig)
-                : resolveConfiguredSourceFolderPath(this.rootPath) ?? this.rootPath;
+                ? resolveSourcePreparationPath(prepDataDir, preparationConfig)
+                : resolveConfiguredSourceFolderPath(prepDataDir) ?? prepDataDir;
             const requestedMethodId = stringValue(request.values, "method_id") ??
                 stringValue(request.values, "method");
             const plannedMethodId = plan.method ??
@@ -2057,9 +1871,9 @@ export class LocalServiceRuntime {
                 error: null,
             });
         }
-        const preparationConfig = this.resolvePreparationConfig(plan.preparation ?? request.preparation ?? this.defaultPreparationName());
+        const preparationConfig = this.resolvePreparationConfig(prepDataDir, plan.preparation ?? request.preparation ?? this.defaultPreparationName(prepDataDir));
         const proposalActionType = ActionProposalTypeSchema.parse(actionType);
-        const preparationPath = resolveSourcePreparationPath(this.rootPath, preparationConfig);
+        const preparationPath = resolveSourcePreparationPath(prepDataDir, preparationConfig);
         const requestedMethodId = stringValue(request.values, "method_id") ??
             stringValue(request.values, "method");
         const plannedMethodId = plan.method ??
@@ -2093,7 +1907,7 @@ export class LocalServiceRuntime {
         if (actionType === "test") {
             const requestedMode = testModeFromValues(proposalValues);
             const hasReadinessChecks = (preparationConfig.checks ?? []).length > 0;
-            const portableContextReady = hasCompiledTestTarget(this.rootPath, preparationConfig);
+            const portableContextReady = hasCompiledTestTarget(prepDataDir, preparationConfig);
             if (!hasReadinessChecks) {
                 return clarifyResolvedAction({
                     title: `Add readiness checks for ${preparationConfig.name}`,
@@ -2101,7 +1915,7 @@ export class LocalServiceRuntime {
                     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") {
+            if (!portableContextReady && requestedMode !== "source-files") {
                 return clarifyResolvedAction({
                     title: `Prepare ${preparationConfig.name} first`,
                     summary: "Readiness checks need portable context unless you explicitly ask for a source-files-only baseline.",
@@ -2117,7 +1931,7 @@ export class LocalServiceRuntime {
                 };
             }
             if (actionType === "test") {
-                const defaultMode = hasCompiledTestTarget(this.rootPath, preparationConfig) ? "both" : "raw";
+                const defaultMode = hasCompiledTestTarget(prepDataDir, preparationConfig) ? "both" : "source-files";
                 return {
                     preparation: preparationConfig.name,
                     mode: testModeValue(proposalValues, defaultMode),
@@ -2197,26 +2011,26 @@ export class LocalServiceRuntime {
             error: null,
         });
     }
-    async submitActionProposal(proposal) {
+    async submitActionProposal(prepDataDir, 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);
+            const resource = await this.createCompileRun(prepDataDir, proposal.request);
             return {
                 runId: resource.run.run_id,
                 runType: "compile-run",
             };
         }
         if (proposal.action_type === "test") {
-            const resource = await this.createTestRun(proposal.request);
+            const resource = await this.createTestRun(prepDataDir, proposal.request);
             return {
                 runId: resource.run_id,
                 runType: "test-run",
             };
         }
         if (proposal.action_type === "readiness-check-draft") {
-            const job = await this.createReadinessCheckDraftRun(proposal.request);
+            const job = await this.createReadinessCheckDraftRun(prepDataDir, proposal.request);
             return {
                 runId: job.run_id,
                 runType: "job-run",
@@ -2226,14 +2040,14 @@ export class LocalServiceRuntime {
         if (directEndpoint) {
             throw new Error(`Action "${proposal.action_type}" must be submitted directly to ${directEndpoint}.`);
         }
-        const job = await this.createMethodAuthoringRun(proposal.request, proposal.action_type === "method-improvement" ? "method-improvement" : "method-authoring");
+        const job = await this.createMethodAuthoringRun(prepDataDir, proposal.request, proposal.action_type === "method-improvement" ? "method-improvement" : "method-authoring");
         return {
             runId: job.run_id,
             runType: "job-run",
         };
     }
-    resolvePreparationConfig(preparationName, overrides = {}) {
-        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(this.rootPath), preparationName);
+    resolvePreparationConfig(prepDataDir, preparationName, overrides = {}) {
+        const preparation = findSourcePreparationConfig(loadSourceFolderConfig(prepDataDir), preparationName);
         if (!preparation) {
             throw new Error(`Preparation "${preparationName}" is not saved in this control plane folder.`);
         }
@@ -2245,49 +2059,59 @@ export class LocalServiceRuntime {
             ...(typeof overrides.max_loops === "number" ? { max_loops: overrides.max_loops } : {}),
         };
     }
-    ensureCompiledForRun(preparationConfig) {
+    ensureCompiledForRun(prepDataDir, preparationConfig) {
         const methodId = requireSelectedMethod(preparationConfig);
-        const compiledPath = ensurePortableContextScaffold(this.rootPath, preparationConfig.name, methodId);
+        const compiledPath = ensurePortableContextScaffold(prepDataDir, preparationConfig.name, methodId);
         syncCompiledInterfConfigFromSourcePreparationConfig(compiledPath, preparationConfig);
         return compiledPath;
     }
     readCompileRun(compiledPath, runId) {
         return readCompileRunAt(compileRunPath(compiledPath, runId));
     }
-    writeCompileRun(compiledPath, run) {
+    writeCompileRun(prepDataDir, compiledPath, run) {
         mkdirSync(compileRunsRoot(compiledPath), { recursive: true });
         writeJsonFile(compileRunPath(compiledPath, run.run_id), CompileRunSchema.parse(run));
+        // Bust per-preparation list + readiness caches so the next read
+        // reflects the write. We invalidate broadly (per-preparation, not
+        // per-record) because list recompute cost is bounded by run count
+        // and the simpler model avoids fan-out bugs.
+        this.compileRunCache.invalidatePreparation(prepDataDir, run.preparation);
+        this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
+    }
+    writeJobRun(prepDataDir, run) {
+        mkdirSync(localJobsRoot(prepDataDir), { recursive: true });
+        writeJsonFile(localJobPath(prepDataDir, run.run_id), LocalJobRunResourceSchema.parse(run));
+        if (run.preparation) {
+            // Some job runs (readiness-check drafts) flip readiness state.
+            this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
+        }
     }
-    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));
+    writeActionProposal(prepDataDir, proposal) {
+        mkdirSync(actionProposalsRoot(prepDataDir), { recursive: true });
+        writeJsonFile(actionProposalPath(prepDataDir, proposal.proposal_id), ActionProposalResourceSchema.parse(proposal));
     }
-    setJobRunResult(runId, result) {
-        const current = this.getJob(runId);
+    setJobRunResult(prepDataDir, runId, result) {
+        const current = this.getJob(prepDataDir, runId);
         if (!current)
             return;
         const normalizedResult = result && typeof result === "object" && !Array.isArray(result)
             ? result
             : { value: result };
-        this.writeJobRun(LocalJobRunResourceSchema.parse({
+        this.writeJobRun(prepDataDir, LocalJobRunResourceSchema.parse({
             ...current,
             result: normalizedResult,
         }));
     }
-    async recordCompileRunEvent(compiledPath, runId, event) {
+    async recordCompileRunEvent(prepDataDir, compiledPath, runId, event) {
         const current = this.readCompileRun(compiledPath, runId);
         if (!current)
             return;
-        this.writeCompileRun(compiledPath, applyEventToCompileRun(current, event));
+        this.writeCompileRun(prepDataDir, compiledPath, applyEventToCompileRun(current, event));
         if (event.type === "stage.passed" || event.type === "stage.failed") {
-            this.refreshCompileRunFromRuntime(compiledPath, runId);
+            this.refreshCompileRunFromRuntime(prepDataDir, compiledPath, runId);
         }
     }
-    refreshCompileRunFromRuntime(compiledPath, runId) {
+    refreshCompileRunFromRuntime(prepDataDir, compiledPath, runId) {
         const current = this.readCompileRun(compiledPath, runId);
         if (!current)
             return;
@@ -2334,9 +2158,9 @@ export class LocalServiceRuntime {
             }),
         };
         next.latest_proof = [...next.stages].reverse().find((stage) => Boolean(stage.latest_proof))?.latest_proof ?? next.latest_proof;
-        this.writeCompileRun(compiledPath, next);
+        this.writeCompileRun(prepDataDir, compiledPath, next);
     }
-    async emitRuntimeDerivedEvents(compiledPath, runId) {
+    async emitRuntimeDerivedEvents(prepDataDir, compiledPath, runId) {
         const state = loadState(compiledPath);
         const run = this.readCompileRun(compiledPath, runId);
         if (!state?.stages || !run)
@@ -2347,7 +2171,7 @@ export class LocalServiceRuntime {
                 continue;
             const artifacts = stageArtifactRefs(stage.stage_id, stageState.artifacts);
             for (const artifact of artifacts) {
-                await this.recordCompileRunEvent(compiledPath, runId, {
+                await this.recordCompileRunEvent(prepDataDir, compiledPath, runId, {
                     type: "artifact.written",
                     event_id: createRunEventId("event"),
                     run_id: runId,
@@ -2356,7 +2180,7 @@ export class LocalServiceRuntime {
                     artifact,
                 });
             }
-            await this.recordCompileRunEvent(compiledPath, runId, {
+            await this.recordCompileRunEvent(prepDataDir, compiledPath, runId, {
                 type: "proof.updated",
                 event_id: createRunEventId("event"),
                 run_id: runId,
@@ -2372,11 +2196,11 @@ export class LocalServiceRuntime {
             });
         }
     }
-    readLatestReadinessRun(preparationName) {
-        return readSavedReadinessCheckRun(this.rootPath, preparationName);
+    readLatestReadinessRun(prepDataDir, preparationName) {
+        return readSavedReadinessCheckRun(prepDataDir, preparationName);
     }
     checksEvaluatedEvent(runId, readinessRun) {
-        const target = readinessRun.compiled ?? readinessRun.raw;
+        const target = readinessRun.compiled ?? readinessRun.source_files;
         return {
             type: "checks.evaluated",
             event_id: createRunEventId("event"),
@@ -2397,9 +2221,11 @@ export class LocalServiceRuntime {
             readiness,
         };
     }
-    writeTestRun(compiledPath, run) {
+    writeTestRun(prepDataDir, compiledPath, run) {
         mkdirSync(testRunsRoot(compiledPath), { recursive: true });
         writeJsonFile(testRunPath(compiledPath, run.run_id), TestRunResourceSchema.parse(run));
+        this.testRunCache.invalidatePreparation(prepDataDir, run.preparation);
+        this.readinessCache.invalidatePreparation(prepDataDir, run.preparation);
     }
 }
 export function createLocalServiceRuntime(options) {