@interf/compiler 0.9.5 → 0.13.0

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

@@ -1,12 +1,121 @@
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { existsSync, statSync, readFileSync } from "node:fs";
 import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { LocalServiceConfigSchema, LocalServiceDiscoverySchema, LocalServiceErrorSchema, LocalServicePointerSchema, OpenPathRequestSchema, PreparationSetupCreateRequestSchema, } from "./lib/schema.js";
+import { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceConfigSchema, LocalServiceDiscoverySchema, LocalServiceErrorSchema, OpenPathRequestSchema, ServiceRegistryEntrySchema, } from "./lib/schema.js";
 import { assertPathWithinRoot, } from "../shared/path-guards.js";
 import { createLocalServiceRuntime, } from "./runtime.js";
-import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_POINTER_PATH, LOCAL_SERVICE_ROUTES, } from "./routes.js";
+import { buildLocalServiceUrl, LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_ROUTES, PREPARATION_SUBRESOURCES, } from "./routes.js";
+import { registerServiceLocally, unregisterService, } from "./service-registry.js";
+import { createStoredPreparation, deleteStoredPreparation, getStoredPreparation, listStoredPreparations, preparationWireShape, rehydratePreparations, } from "./preparation-store.js";
+import { clearConnection, readActiveConnection, writeConnection, } from "./connection-config.js";
+/** HTTP methods that require an authenticated bearer token + Origin guard. */
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** Generate a fresh per-instance bearer token. */
+export function createLocalServiceAuthToken() {
+    return randomBytes(32).toString("hex");
+}
+/**
+ * Build the per-instance CORS / Origin allowlist. Only the loopback
+ * hostnames bound to the active port count as same-origin. `null` and
+ * absent Origin are also accepted (Electron / file:// / CLI tools).
+ */
+function buildAllowedOrigins(host, port) {
+    const hostnames = Array.from(new Set([host, ...LOCAL_SERVICE_LOOPBACK_HOSTS]));
+    return {
+        hostnames,
+        ports: [port],
+        hostUrls: hostnames.map((hostname) => {
+            const wrapped = hostname.includes(":") ? `[${hostname}]` : hostname;
+            return `http://${wrapped}:${port}`;
+        }),
+    };
+}
+function originHeaderValue(req) {
+    const raw = req.headers.origin;
+    if (raw === undefined)
+        return null;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function authorizationHeaderValue(req) {
+    const raw = req.headers.authorization;
+    if (!raw)
+        return null;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function isOriginAllowed(origin, allowed) {
+    if (origin === null)
+        return true; // CLI / Node fetch / native app — no Origin sent.
+    if (origin === "null")
+        return true; // Electron / sandboxed / file:// page.
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return false;
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+    if (!allowed.hostnames.includes(hostname))
+        return false;
+    // Default ports (no explicit port in URL) cannot be the local service.
+    if (!parsed.port)
+        return false;
+    const portNumber = Number.parseInt(parsed.port, 10);
+    if (!Number.isInteger(portNumber))
+        return false;
+    return allowed.ports.includes(portNumber);
+}
+function corsHeadersFor(origin, allowed) {
+    if (!isOriginAllowed(origin, allowed))
+        return { vary: "origin" };
+    return {
+        "access-control-allow-origin": origin ?? allowed.hostUrls[0] ?? "",
+        "access-control-allow-credentials": "false",
+        "access-control-allow-methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "access-control-allow-headers": "content-type, authorization, x-interf-workspace, x-interf-idempotency-key",
+        vary: "origin",
+    };
+}
+function isMutatingMethod(method) {
+    return method !== undefined && MUTATING_METHODS.has(method.toUpperCase());
+}
+/**
+ * Validate the bearer token on a mutating request. Returns true when:
+ * - the runtime has no token (test harness mode), or
+ * - the request includes `Authorization: Bearer <token>` matching the runtime token.
+ */
+function isAuthorizedMutation(req, runtime) {
+    if (!runtime.authToken)
+        return true;
+    const authorization = authorizationHeaderValue(req);
+    if (!authorization)
+        return false;
+    const match = /^Bearer\s+([A-Za-z0-9._\-]+)$/.exec(authorization);
+    if (!match)
+        return false;
+    const presented = match[1];
+    if (!presented || presented.length !== runtime.authToken.length)
+        return false;
+    // Constant-time compare to avoid timing oracles.
+    let mismatch = 0;
+    for (let index = 0; index < runtime.authToken.length; index += 1) {
+        mismatch |= presented.charCodeAt(index) ^ runtime.authToken.charCodeAt(index);
+    }
+    return mismatch === 0;
+}
 function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 }
@@ -25,29 +134,6 @@ function compilerUiStaticRoot() {
         return resolve(explicit);
     return resolveCompilerUiStaticRoot();
 }
-function localServicePointerPath(rootPath) {
-    return join(rootPath, ...LOCAL_SERVICE_POINTER_PATH);
-}
-function writeLocalServicePointer(rootPath, pointer) {
-    const pointerPath = localServicePointerPath(rootPath);
-    mkdirSync(dirname(pointerPath), { recursive: true });
-    const parsed = LocalServicePointerSchema.parse(pointer);
-    writeFileSync(pointerPath, `${JSON.stringify(parsed, null, 2)}\n`);
-}
-function removeLocalServicePointer(rootPath, serviceUrl) {
-    const pointerPath = localServicePointerPath(rootPath);
-    if (!existsSync(pointerPath))
-        return;
-    try {
-        const pointer = LocalServicePointerSchema.parse(JSON.parse(readFileSync(pointerPath, "utf8")));
-        if (pointer.service_url !== serviceUrl || pointer.pid !== process.pid)
-            return;
-        rmSync(pointerPath, { force: true });
-    }
-    catch {
-        return;
-    }
-}
 function contentType(filePath) {
     switch (extname(filePath)) {
         case ".html":
@@ -76,28 +162,56 @@ function contentType(filePath) {
             return "application/octet-stream";
     }
 }
-function writeHeaders(res, statusCode, headers = {}) {
+const NO_ORIGIN_RESPONSE_CONTEXT = { cors: { vary: "origin" } };
+/** Stash slot on the response object that holds the per-request CORS headers. */
+const RESPONSE_CONTEXT_KEY = Symbol.for("interf.localService.responseContext");
+function attachResponseContext(res, ctx) {
+    res[RESPONSE_CONTEXT_KEY] = ctx;
+}
+function activeResponseContext(res) {
+    const ctx = res[RESPONSE_CONTEXT_KEY];
+    return ctx ?? NO_ORIGIN_RESPONSE_CONTEXT;
+}
+function writeHeaders(res, statusCode, contextOrHeaders, headers = {}) {
+    // Compatibility shim while call sites migrate. Older callers pass a
+    // plain headers record as the third argument; new callers thread a
+    // `ResponseContext`. When neither is supplied (or only headers are),
+    // we read the per-request context the entry-point handler stashed on
+    // the response.
+    const isContext = contextOrHeaders !== undefined && "cors" in contextOrHeaders;
+    const context = isContext ? contextOrHeaders : activeResponseContext(res);
+    const extraHeaders = isContext ? headers : (contextOrHeaders ?? {});
     res.writeHead(statusCode, {
-        "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET,POST,PATCH,OPTIONS",
-        "access-control-allow-headers": "content-type",
-        ...headers,
+        ...context.cors,
+        ...extraHeaders,
     });
 }
-function sendJson(res, statusCode, value) {
-    writeHeaders(res, statusCode, {
+function sendJson(res, statusCode, contextOrValue, maybeValue) {
+    const usingContext = contextOrValue !== null
+        && typeof contextOrValue === "object"
+        && "cors" in contextOrValue
+        && maybeValue !== undefined;
+    const context = usingContext ? contextOrValue : activeResponseContext(res);
+    const value = usingContext ? maybeValue : contextOrValue;
+    writeHeaders(res, statusCode, context, {
         "content-type": "application/json; charset=utf-8",
     });
     res.end(`${JSON.stringify(value, null, 2)}\n`);
 }
-function sendText(res, statusCode, value) {
-    writeHeaders(res, statusCode, {
+function sendText(res, statusCode, contextOrValue, maybeValue) {
+    const usingContext = typeof contextOrValue === "object" && contextOrValue !== null && "cors" in contextOrValue;
+    const context = usingContext ? contextOrValue : activeResponseContext(res);
+    const value = usingContext ? (maybeValue ?? "") : contextOrValue;
+    writeHeaders(res, statusCode, context, {
         "content-type": "text/plain; charset=utf-8",
     });
     res.end(value);
 }
-function sendError(res, statusCode, message) {
-    sendJson(res, statusCode, LocalServiceErrorSchema.parse({
+function sendError(res, statusCode, contextOrMessage, maybeMessage) {
+    const usingContext = typeof contextOrMessage === "object" && contextOrMessage !== null && "cors" in contextOrMessage;
+    const context = usingContext ? contextOrMessage : activeResponseContext(res);
+    const message = usingContext ? (maybeMessage ?? "") : contextOrMessage;
+    sendJson(res, statusCode, context, LocalServiceErrorSchema.parse({
         error: {
             message,
         },
@@ -211,185 +325,368 @@ async function routeApi(req, res, runtime) {
     const url = parseRequestUrl(req);
     const path = url.pathname;
     const method = req.method ?? "GET";
+    const origin = originHeaderValue(req);
+    const allowed = buildAllowedOrigins(runtime.host, runtime.port);
+    // CORS preflight — answered for allowed origins, refused otherwise.
     if (method === "OPTIONS") {
+        if (!isOriginAllowed(origin, allowed)) {
+            attachResponseContext(res, NO_ORIGIN_RESPONSE_CONTEXT);
+            sendError(res, 403, "Origin not allowed.");
+            return true;
+        }
+        attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
         writeHeaders(res, 204);
         res.end();
         return true;
     }
-    if (method === "GET" && path === "/health") {
+    // For non-OPTIONS, attach the CORS context once.
+    attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
+    // Mutating requests must:
+    //   1. Have an Origin that's local OR no Origin at all (CLI),
+    //   2. Carry a valid Authorization: Bearer <token> if the runtime issued one.
+    // Read-only GETs stay open so dev tooling can still inspect state.
+    if (isMutatingMethod(method)) {
+        if (!isOriginAllowed(origin, allowed)) {
+            sendError(res, 403, "Origin not allowed.");
+            return true;
+        }
+        if (!isAuthorizedMutation(req, runtime)) {
+            writeHeaders(res, 401, { "www-authenticate": "Bearer realm=\"interf-local-service\"" });
+            res.end(`${JSON.stringify(LocalServiceErrorSchema.parse({
+                error: { message: "Missing or invalid bearer token." },
+            }), null, 2)}\n`);
+            return true;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Top-level engine routes — instance metadata, health, discovery.
+    // ─────────────────────────────────────────────────────────────────────────
+    // GET /health — liveness probe used by the CLI bootstrap.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.health) {
         sendJson(res, 200, runtime.health());
         return true;
     }
+    // GET /v1 — discovery list of available resources.
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.api) {
         sendJson(res, 200, LocalServiceDiscoverySchema.parse({
             kind: "interf-local-service-discovery",
             version: 1,
             resources: {
+                instance: LOCAL_SERVICE_ROUTES.instance,
                 preparations: LOCAL_SERVICE_ROUTES.preparations,
                 methods: LOCAL_SERVICE_ROUTES.methods,
                 runs: LOCAL_SERVICE_ROUTES.runs,
-                readiness: LOCAL_SERVICE_ROUTES.readiness,
-                portable_contexts: LOCAL_SERVICE_ROUTES.portableContexts,
-                source_files: LOCAL_SERVICE_ROUTES.sourceFiles,
-                workspace_files: LOCAL_SERVICE_ROUTES.workspaceFiles,
                 action_proposals: LOCAL_SERVICE_ROUTES.actionProposals,
-                preparation_setups: LOCAL_SERVICE_ROUTES.preparationSetups,
-                preparation_changes: LOCAL_SERVICE_ROUTES.preparationChanges,
-                method_changes: LOCAL_SERVICE_ROUTES.methodChanges,
-                readiness_check_drafts: LOCAL_SERVICE_ROUTES.readinessCheckDrafts,
-                method_authoring_runs: LOCAL_SERVICE_ROUTES.methodAuthoringRuns,
-                method_improvement_runs: LOCAL_SERVICE_ROUTES.methodImprovementRuns,
-                compile_runs: LOCAL_SERVICE_ROUTES.compileRuns,
-                test_runs: LOCAL_SERVICE_ROUTES.testRuns,
-                reset: LOCAL_SERVICE_ROUTES.reset,
                 executor: LOCAL_SERVICE_ROUTES.executor,
+                open_path: LOCAL_SERVICE_ROUTES.openPath,
             },
         }));
         return true;
     }
+    // GET /v1/instance — engine metadata.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.instance) {
+        const startedAtIso = runtime.startedAt ?? new Date().toISOString();
+        const startedMs = Date.parse(startedAtIso);
+        const uptimeSeconds = Number.isFinite(startedMs)
+            ? Math.max(0, Math.floor((Date.now() - startedMs) / 1000))
+            : 0;
+        sendJson(res, 200, {
+            kind: "interf-instance",
+            version: 1,
+            url: buildLocalServiceUrl({ host: runtime.host, port: runtime.port }),
+            host: runtime.host,
+            port: runtime.port,
+            pid: process.pid,
+            started_at: startedAtIso,
+            uptime_seconds: uptimeSeconds,
+            package_version: runtime.packageVersion ?? null,
+            preparation_count: listStoredPreparations().length,
+            auth_required: Boolean(runtime.authToken),
+        });
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Preparation collection routes
+    // ─────────────────────────────────────────────────────────────────────────
+    // GET /v1/preparations — list every preparation on the instance.
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.preparations) {
-        sendJson(res, 200, { preparations: runtime.listPreparations() });
+        const items = listStoredPreparations().map(preparationWireShape);
+        sendJson(res, 200, { preparations: items });
         return true;
     }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.preparationSetups) {
+    // POST /v1/preparations — create a new preparation.
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.preparations) {
         try {
-            const body = await readJsonBody(req);
-            const request = PreparationSetupCreateRequestSchema.parse(body);
-            const result = runtime.applyPreparationSetup(request);
-            if (request.prepare_after_setup) {
-                const resource = await runtime.createCompileRun({
-                    preparation: result.preparation,
-                    method: result.method,
-                });
-                sendJson(res, 202, {
-                    ...result,
-                    submitted_run_id: resource.run.run_id,
-                    submitted_run_type: "compile-run",
-                    message: `${result.message} Prepare run started.`,
-                });
+            const body = (await readJsonBody(req));
+            if (!body || typeof body !== "object") {
+                sendError(res, 400, "Request body must be a JSON object.");
+                return true;
             }
-            else {
-                sendJson(res, 202, result);
+            if (!body.id || typeof body.id !== "string") {
+                sendError(res, 400, "Missing required field: id");
+                return true;
             }
+            if (!body.method_id || typeof body.method_id !== "string") {
+                sendError(res, 400, "Missing required field: method_id");
+                return true;
+            }
+            if (!body.source || typeof body.source !== "object" || !body.source.locator) {
+                sendError(res, 400, "Missing required field: source.locator");
+                return true;
+            }
+            const stored = createStoredPreparation(runtime, {
+                id: body.id,
+                source: { kind: "local-folder", locator: body.source.locator },
+                method_id: body.method_id,
+                about: body.about,
+                checks: body.checks,
+                max_attempts: body.max_attempts,
+                max_loops: body.max_loops,
+            });
+            sendJson(res, 201, preparationWireShape(stored));
         }
         catch (error) {
-            sendError(res, 409, error instanceof Error ? error.message : String(error));
+            sendError(res, 400, error instanceof Error ? error.message : String(error));
         }
         return true;
     }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.reset) {
-        try {
-            const body = await readJsonBody(req);
-            sendJson(res, 202, runtime.applyReset(body));
+    // ─────────────────────────────────────────────────────────────────────────
+    // Per-preparation routes (under /v1/preparations/{id}/…)
+    // ─────────────────────────────────────────────────────────────────────────
+    if (path.startsWith(`${LOCAL_SERVICE_ROUTES.preparations}/`)) {
+        const tail = path.slice(LOCAL_SERVICE_ROUTES.preparations.length + 1);
+        const slashIndex = tail.indexOf("/");
+        const prepId = slashIndex === -1 ? tail : tail.slice(0, slashIndex);
+        const subPath = slashIndex === -1 ? "" : tail.slice(slashIndex + 1);
+        const decodedPrepId = decodeURIComponent(prepId);
+        const storedPrep = getStoredPreparation(decodedPrepId);
+        if (!storedPrep) {
+            sendError(res, 404, `Preparation not found: ${decodedPrepId}`);
+            return true;
         }
-        catch (error) {
-            sendError(res, 409, error instanceof Error ? error.message : String(error));
+        runtime.touchPreparation(storedPrep.prepDataDir);
+        if (subPath === "") {
+            // Bare /v1/preparations/{id}
+            if (method === "GET") {
+                sendJson(res, 200, preparationWireShape(storedPrep));
+                return true;
+            }
+            if (method === "DELETE") {
+                deleteStoredPreparation(runtime, decodedPrepId);
+                sendJson(res, 200, { id: decodedPrepId, deleted: true });
+                return true;
+            }
         }
-        return true;
-    }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.preparationChanges) {
-        try {
-            const body = await readJsonBody(req);
-            sendJson(res, 202, runtime.applyPreparationChange(body));
+        else if (subPath === PREPARATION_SUBRESOURCES.compileRuns) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const request = { preparation: storedPrep.id, ...(body ?? {}) };
+                    const idempotencyKeyRaw = req.headers["x-interf-idempotency-key"];
+                    const idempotencyKey = Array.isArray(idempotencyKeyRaw)
+                        ? idempotencyKeyRaw[0]
+                        : idempotencyKeyRaw;
+                    const trimmedKey = typeof idempotencyKey === "string" ? idempotencyKey.trim() : "";
+                    const dedupedRunId = trimmedKey
+                        ? runtime.findIdempotentCompileRun(storedPrep.prepDataDir, trimmedKey)
+                        : null;
+                    if (dedupedRunId) {
+                        const existing = runtime.getCompileRun(storedPrep.prepDataDir, dedupedRunId);
+                        if (existing) {
+                            sendJson(res, 200, existing);
+                            return true;
+                        }
+                    }
+                    const resource = await runtime.createCompileRun(storedPrep.prepDataDir, request);
+                    if (trimmedKey) {
+                        runtime.recordIdempotentCompileRun(storedPrep.prepDataDir, trimmedKey, resource.run.run_id);
+                    }
+                    sendJson(res, 201, resource);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
         }
-        catch (error) {
-            sendError(res, 409, error instanceof Error ? error.message : String(error));
+        else if (subPath === PREPARATION_SUBRESOURCES.testRuns) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const request = { preparation: storedPrep.id, ...(body ?? {}) };
+                    const resource = await runtime.createTestRun(storedPrep.prepDataDir, request);
+                    sendJson(res, 201, resource);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
         }
+        else if (subPath === PREPARATION_SUBRESOURCES.methodAuthoringRuns) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const job = await runtime.createMethodAuthoringRun(storedPrep.prepDataDir, body);
+                    sendJson(res, 202, job);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.methodImprovementRuns) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const job = await runtime.createMethodAuthoringRun(storedPrep.prepDataDir, body, "method-improvement");
+                    sendJson(res, 202, job);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.readinessCheckDrafts) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const job = await runtime.createReadinessCheckDraftRun(storedPrep.prepDataDir, body);
+                    sendJson(res, 202, job);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.changes) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    sendJson(res, 202, runtime.applyPreparationChange(storedPrep.prepDataDir, body));
+                }
+                catch (error) {
+                    sendError(res, 409, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.reset) {
+            if (method === "POST") {
+                try {
+                    const body = (await readJsonBody(req));
+                    const request = { preparation: storedPrep.id, scope: "compile", ...(body ?? {}) };
+                    const result = runtime.applyReset(storedPrep.prepDataDir, request);
+                    sendJson(res, 200, result);
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.readiness) {
+            if (method === "GET") {
+                const readiness = runtime.getReadiness(storedPrep.prepDataDir, storedPrep.id);
+                sendJson(res, 200, readiness);
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.runs) {
+            if (method === "GET") {
+                const runs = runtime.listCompileRunsForPreparation(storedPrep.prepDataDir, storedPrep.id);
+                sendJson(res, 200, { runs });
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.sourceFiles) {
+            if (method === "GET") {
+                sendJson(res, 200, {
+                    source_files: runtime.listSourceFiles(storedPrep.prepDataDir, storedPrep.id),
+                });
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.portableContext) {
+            if (method === "GET") {
+                const context = runtime.getPortableContext(storedPrep.prepDataDir, storedPrep.id);
+                if (!context)
+                    sendError(res, 404, "Portable context not found.");
+                else
+                    sendJson(res, 200, context);
+                return true;
+            }
+        }
+        sendError(res, 404, `Unknown preparation sub-route: ${subPath}`);
         return true;
     }
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.workspaceFiles) {
-        sendJson(res, 200, { workspace_files: runtime.listWorkspaceFiles() });
-        return true;
-    }
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.readiness) {
-        sendJson(res, 200, { readiness: runtime.listPreparationReadiness() });
-        return true;
-    }
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.sourceFiles) {
-        const preparation = url.searchParams.get("preparation");
-        sendJson(res, 200, { source_files: runtime.listSourceFiles(preparation) });
-        return true;
-    }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.openPath) {
-        const body = OpenPathRequestSchema.parse(await readJsonBody(req));
-        const health = runtime.health();
-        const allowedRoots = [
-            runtime.rootPath,
-            ...(health.source_folder_path ? [health.source_folder_path] : []),
-        ];
-        const openedPath = await openLocalPath(allowedRoots, body.path);
-        sendJson(res, 202, { opened: true, path: openedPath });
-        return true;
-    }
-    const preparationMatch = path.match(/^\/v1\/preparations\/([^/]+)$/);
-    if (method === "GET" && preparationMatch?.[1]) {
-        const preparation = runtime.getPreparation(decodeURIComponent(preparationMatch[1]));
-        if (!preparation)
-            sendError(res, 404, "Preparation not found.");
-        else
-            sendJson(res, 200, preparation);
-        return true;
-    }
-    const preparationReadinessMatch = path.match(/^\/v1\/preparations\/([^/]+)\/readiness$/);
-    if (method === "GET" && preparationReadinessMatch?.[1]) {
-        const readiness = runtime.getPreparationReadiness(decodeURIComponent(preparationReadinessMatch[1]));
-        if (!readiness)
-            sendError(res, 404, "Preparation not found.");
-        else
-            sendJson(res, 200, readiness);
-        return true;
-    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Method resources — preparation-independent (workspace draft + user lib + bundled).
+    // ─────────────────────────────────────────────────────────────────────────
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.methods) {
-        sendJson(res, 200, { methods: runtime.listMethods() });
-        return true;
-    }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.methodChanges) {
-        try {
-            const body = await readJsonBody(req);
-            sendJson(res, 202, runtime.applyMethodChange(body));
-        }
-        catch (error) {
-            sendError(res, 409, error instanceof Error ? error.message : String(error));
-        }
+        // The runtime needs SOME prep data dir to discover preparation-draft methods.
+        // Fall back to the first registered preparation (if any) so user-library
+        // and bundled methods still surface even when no preparation has drafts.
+        const firstPrep = listStoredPreparations()[0];
+        sendJson(res, 200, { methods: runtime.listMethods(firstPrep?.prepDataDir ?? runtime.rootPath) });
         return true;
     }
     const methodMatch = path.match(/^\/v1\/methods\/([^/]+)$/);
     if (method === "GET" && methodMatch?.[1]) {
-        const methodResource = runtime.getMethod(decodeURIComponent(methodMatch[1]));
+        const firstPrep = listStoredPreparations()[0];
+        const methodResource = runtime.getMethod(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(methodMatch[1]));
         if (!methodResource)
             sendError(res, 404, "Method not found.");
         else
             sendJson(res, 200, methodResource);
         return true;
     }
-    if (method === "GET" && path === "/v1/jobs") {
-        sendJson(res, 200, { jobs: runtime.listJobs() });
-        return true;
-    }
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.executor) {
-        sendJson(res, 200, runtime.getExecutorStatus());
+    // ─────────────────────────────────────────────────────────────────────────
+    // Run observability — instance-wide. Each run record carries a workspace,
+    // so the runtime takes a "first prep" hint to scan registered preparations.
+    // ─────────────────────────────────────────────────────────────────────────
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.runs) {
+        const firstPrep = listStoredPreparations()[0];
+        sendJson(res, 200, { runs: runtime.listRunObservability(firstPrep?.prepDataDir ?? runtime.rootPath) });
         return true;
     }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.executor) {
-        const body = await readJsonBody(req);
-        sendJson(res, 202, runtime.selectExecutor(body));
+    const observableRunMatch = path.match(/^\/v1\/runs\/([^/]+)$/);
+    if (method === "GET" && observableRunMatch?.[1]) {
+        const firstPrep = listStoredPreparations()[0];
+        const run = runtime.getRunObservability(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(observableRunMatch[1]));
+        if (!run)
+            sendError(res, 404, "Run not found.");
+        else
+            sendJson(res, 200, run);
         return true;
     }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Action proposals (chat / wizard) — instance-wide.
+    // ─────────────────────────────────────────────────────────────────────────
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.actionProposals) {
-        sendJson(res, 200, { action_proposals: runtime.listActionProposals() });
+        const firstPrep = listStoredPreparations()[0];
+        sendJson(res, 200, {
+            action_proposals: runtime.listActionProposals(firstPrep?.prepDataDir ?? runtime.rootPath),
+        });
         return true;
     }
     if (method === "POST" && path === LOCAL_SERVICE_ROUTES.actionProposals) {
         const body = await readJsonBody(req);
-        sendJson(res, 202, await runtime.createActionProposal(body));
+        const firstPrep = listStoredPreparations()[0];
+        sendJson(res, 202, await runtime.createActionProposal(firstPrep?.prepDataDir ?? runtime.rootPath, body));
         return true;
     }
     const actionProposalMatch = path.match(/^\/v1\/action-proposals\/([^/]+)(?:\/([^/]+))?$/);
     if (actionProposalMatch?.[1]) {
         const proposalId = decodeURIComponent(actionProposalMatch[1]);
         const child = actionProposalMatch[2];
+        const firstPrep = listStoredPreparations()[0];
+        const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
         if (method === "GET" && !child) {
-            const proposal = runtime.getActionProposal(proposalId);
+            const proposal = runtime.getActionProposal(prepDataDir, proposalId);
             if (!proposal)
                 sendError(res, 404, "Action proposal not found.");
             else
@@ -398,7 +695,7 @@ async function routeApi(req, res, runtime) {
         }
         if (method === "POST" && child === "decision") {
             const body = await readJsonBody(req);
-            const proposal = await runtime.decideActionProposal(proposalId, body);
+            const proposal = await runtime.decideActionProposal(prepDataDir, proposalId, body);
             if (!proposal)
                 sendError(res, 404, "Action proposal not found.");
             else
@@ -406,81 +703,17 @@ async function routeApi(req, res, runtime) {
             return true;
         }
     }
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.runs) {
-        sendJson(res, 200, { runs: runtime.listRunObservability() });
-        return true;
-    }
-    const observableRunMatch = path.match(/^\/v1\/runs\/([^/]+)$/);
-    if (method === "GET" && observableRunMatch?.[1]) {
-        const run = runtime.getRunObservability(decodeURIComponent(observableRunMatch[1]));
-        if (!run)
-            sendError(res, 404, "Run not found.");
-        else
-            sendJson(res, 200, run);
-        return true;
-    }
-    const jobMatch = path.match(/^\/v1\/jobs\/([^/]+)(?:\/([^/]+))?$/);
-    if (jobMatch?.[1]) {
-        const runId = decodeURIComponent(jobMatch[1]);
-        const child = jobMatch[2];
-        if (method === "GET" && !child) {
-            const job = runtime.getJob(runId);
-            if (!job)
-                sendError(res, 404, "Job run not found.");
-            else
-                sendJson(res, 200, job);
-            return true;
-        }
-        if (method === "GET" && child === "events") {
-            const events = runtime.getJobEvents(runId);
-            if (!events)
-                sendError(res, 404, "Job run not found.");
-            else
-                sendJson(res, 200, { events });
-            return true;
-        }
-    }
-    if (method === "POST" && path === "/v1/readiness-check-drafts") {
-        const body = await readJsonBody(req);
-        const job = await runtime.createReadinessCheckDraftRun(body);
-        sendJson(res, 202, job);
-        return true;
-    }
-    if (method === "POST" &&
-        path === LOCAL_SERVICE_ROUTES.methodAuthoringRuns) {
-        const body = await readJsonBody(req);
-        const job = await runtime.createMethodAuthoringRun(body);
-        sendJson(res, 202, job);
-        return true;
-    }
-    if (method === "POST" &&
-        path === LOCAL_SERVICE_ROUTES.methodImprovementRuns) {
-        const body = await readJsonBody(req);
-        const job = await runtime.createMethodAuthoringRun(body, "method-improvement");
-        sendJson(res, 202, job);
-        return true;
-    }
-    if (method === "GET" && path === "/v1/compile-runs") {
-        sendJson(res, 200, { compile_runs: runtime.listCompileRuns() });
-        return true;
-    }
-    if (method === "POST" && path === "/v1/compile-runs") {
-        try {
-            const body = await readJsonBody(req);
-            const resource = await runtime.createCompileRun(body);
-            sendJson(res, 202, resource);
-        }
-        catch (error) {
-            sendError(res, 409, error instanceof Error ? error.message : String(error));
-        }
-        return true;
-    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Compile-run sub-resources (instance-wide; runs are addressable by run_id).
+    // ─────────────────────────────────────────────────────────────────────────
     const compileRunMatch = path.match(/^\/v1\/compile-runs\/([^/]+)(?:\/([^/]+))?$/);
     if (compileRunMatch?.[1]) {
         const runId = decodeURIComponent(compileRunMatch[1]);
         const child = compileRunMatch[2];
+        const firstPrep = listStoredPreparations()[0];
+        const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
         if (method === "GET" && !child) {
-            const run = runtime.getCompileRun(runId);
+            const run = runtime.getCompileRun(prepDataDir, runId);
             if (!run)
                 sendError(res, 404, "Compile run not found.");
             else
@@ -488,7 +721,7 @@ async function routeApi(req, res, runtime) {
             return true;
         }
         if (method === "GET" && child === "events") {
-            const events = runtime.getCompileRunEvents(runId);
+            const events = runtime.getCompileRunEvents(prepDataDir, runId);
             if (!events)
                 sendError(res, 404, "Compile run not found.");
             else
@@ -496,7 +729,7 @@ async function routeApi(req, res, runtime) {
             return true;
         }
         if (method === "GET" && child === "proof") {
-            const proof = runtime.getCompileRunProof(runId);
+            const proof = runtime.getCompileRunProof(prepDataDir, runId);
             if (!proof)
                 sendError(res, 404, "Compile run not found.");
             else
@@ -504,7 +737,7 @@ async function routeApi(req, res, runtime) {
             return true;
         }
         if (method === "GET" && child === "artifacts") {
-            const artifacts = runtime.getCompileRunArtifacts(runId);
+            const artifacts = runtime.getCompileRunArtifacts(prepDataDir, runId);
             if (!artifacts)
                 sendError(res, 404, "Compile run not found.");
             else
@@ -512,40 +745,76 @@ async function routeApi(req, res, runtime) {
             return true;
         }
         if (method === "POST" && child === "cancel") {
-            sendError(res, 501, "Compile-run cancellation is not implemented yet.");
+            const existing = runtime.getCompileRun(prepDataDir, runId);
+            if (!existing) {
+                sendError(res, 404, "Compile run not found.");
+                return true;
+            }
+            const result = runtime.cancelCompileRun(runId);
+            sendJson(res, 200, result);
             return true;
         }
     }
-    if (method === "GET" && path === "/v1/test-runs") {
-        sendJson(res, 200, { test_runs: runtime.listTestRuns() });
-        return true;
-    }
-    if (method === "POST" && path === "/v1/test-runs") {
-        const body = await readJsonBody(req);
-        const resource = await runtime.createTestRun(body);
-        sendJson(res, 202, resource);
-        return true;
-    }
     const testRunMatch = path.match(/^\/v1\/test-runs\/([^/]+)$/);
     if (method === "GET" && testRunMatch?.[1]) {
-        const run = runtime.getTestRun(decodeURIComponent(testRunMatch[1]));
+        const firstPrep = listStoredPreparations()[0];
+        const run = runtime.getTestRun(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(testRunMatch[1]));
         if (!run)
             sendError(res, 404, "Readiness check run not found.");
         else
             sendJson(res, 200, run);
         return true;
     }
-    if (method === "GET" && path === "/v1/portable-contexts") {
-        sendJson(res, 200, { portable_contexts: runtime.listPortableContexts() });
+    const jobMatch = path.match(/^\/v1\/jobs\/([^/]+)(?:\/([^/]+))?$/);
+    if (jobMatch?.[1]) {
+        const runId = decodeURIComponent(jobMatch[1]);
+        const child = jobMatch[2];
+        const firstPrep = listStoredPreparations()[0];
+        const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
+        if (method === "GET" && !child) {
+            const job = runtime.getJob(prepDataDir, runId);
+            if (!job)
+                sendError(res, 404, "Job run not found.");
+            else
+                sendJson(res, 200, job);
+            return true;
+        }
+        if (method === "GET" && child === "events") {
+            const events = runtime.getJobEvents(prepDataDir, runId);
+            if (!events)
+                sendError(res, 404, "Job run not found.");
+            else
+                sendJson(res, 200, { events });
+            return true;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Executor + open-path — instance-wide.
+    // ─────────────────────────────────────────────────────────────────────────
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.executor) {
+        sendJson(res, 200, runtime.getExecutorStatus());
         return true;
     }
-    const portableContextMatch = path.match(/^\/v1\/portable-contexts\/([^/]+)$/);
-    if (method === "GET" && portableContextMatch?.[1]) {
-        const context = runtime.getPortableContext(decodeURIComponent(portableContextMatch[1]));
-        if (!context)
-            sendError(res, 404, "Portable context not found.");
-        else
-            sendJson(res, 200, context);
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.executor) {
+        const body = await readJsonBody(req);
+        sendJson(res, 202, runtime.selectExecutor(body));
+        return true;
+    }
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.openPath) {
+        const body = OpenPathRequestSchema.parse(await readJsonBody(req));
+        // Permit opening any registered preparation root or its bound source folder.
+        const allowedRoots = [];
+        for (const stored of listStoredPreparations()) {
+            allowedRoots.push(stored.prepDataDir);
+            if (stored.source.locator)
+                allowedRoots.push(stored.source.locator);
+        }
+        if (allowedRoots.length === 0) {
+            sendError(res, 400, "No preparation registered; nothing to open.");
+            return true;
+        }
+        const openedPath = await openLocalPath(allowedRoots, body.path);
+        sendJson(res, 202, { opened: true, path: openedPath });
         return true;
     }
     return false;
@@ -553,6 +822,13 @@ async function routeApi(req, res, runtime) {
 export function createLocalServiceServer(runtime) {
     return createServer((req, res) => {
         void (async () => {
+            // Pre-attach a CORS context so static-asset GETs and the 404
+            // fallback emit the right headers even before routeApi has a
+            // chance to set its own. The OPTIONS preflight handling and the
+            // mutating-method guards still happen inside routeApi.
+            const origin = originHeaderValue(req);
+            const allowed = buildAllowedOrigins(runtime.host, runtime.port);
+            attachResponseContext(res, { cors: corsHeadersFor(origin, allowed) });
             try {
                 const routed = await routeApi(req, res, runtime);
                 if (routed)
@@ -569,57 +845,149 @@ export function createLocalServiceServer(runtime) {
 }
 function resolvePort(optionPort) {
     if (typeof optionPort === "number")
-        return optionPort;
+        return { port: optionPort, pinned: true };
     const envPort = Number.parseInt(process.env.INTERF_SERVICE_PORT ?? "", 10);
-    return Number.isInteger(envPort) ? envPort : LOCAL_SERVICE_DEFAULT_PORT;
+    if (Number.isInteger(envPort))
+        return { port: envPort, pinned: true };
+    return { port: LOCAL_SERVICE_DEFAULT_PORT, pinned: false };
+}
+const LOCAL_SERVICE_PORT_FALLBACK_RANGE = 50;
+async function listenWithFallback(server, host, startPort, pinned) {
+    const maxPort = pinned ? startPort : startPort + LOCAL_SERVICE_PORT_FALLBACK_RANGE;
+    for (let port = startPort; port <= maxPort; port += 1) {
+        try {
+            await new Promise((resolveListen, rejectListen) => {
+                const onError = (error) => {
+                    server.off("listening", onListening);
+                    rejectListen(error);
+                };
+                const onListening = () => {
+                    server.off("error", onError);
+                    resolveListen();
+                };
+                server.once("error", onError);
+                server.once("listening", onListening);
+                server.listen(port, host);
+            });
+            return port;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EADDRINUSE" || port === maxPort)
+                throw error;
+            // Retry on the next port; the server will emit a fresh "listening" event on the next attempt.
+        }
+    }
+    throw new Error(`Could not bind a free port between ${startPort} and ${maxPort}.`);
 }
 export async function startLocalService(options = {}) {
+    const requestedPort = typeof options.searchFromPort === "number"
+        ? { port: options.searchFromPort, pinned: false }
+        : resolvePort(options.port);
+    const requestedHost = options.host ?? process.env.INTERF_SERVICE_HOST ?? LOCAL_SERVICE_DEFAULT_HOST;
+    // Reject non-loopback host bindings before we even configure anything.
+    // This guards against `INTERF_SERVICE_HOST=0.0.0.0` env injection or a
+    // call site that passes a LAN IP. The schema-level refinement also
+    // rejects, but we want a clearer error message.
+    if (!LOCAL_SERVICE_LOOPBACK_HOSTS.includes(requestedHost)) {
+        throw new Error(`Refusing to bind local service to non-loopback host '${requestedHost}'. ` +
+            `Use one of ${LOCAL_SERVICE_LOOPBACK_HOSTS.join(", ")} ` +
+            `(adjust the --host flag or INTERF_SERVICE_HOST env var).`);
+    }
     const config = LocalServiceConfigSchema.parse({
-        host: options.host ?? process.env.INTERF_SERVICE_HOST ?? LOCAL_SERVICE_DEFAULT_HOST,
-        port: resolvePort(options.port),
+        host: requestedHost,
+        port: requestedPort.port,
     });
     const rootPath = options.rootPath ?? process.cwd();
+    const resolvedRoot = resolve(rootPath);
+    // 0.13 auth-token policy: default to `null` (no token) on loopback. CORS
+    // + loopback bind enforces the security boundary. Callers can opt in by
+    // passing `"auto"` (generate fresh) or a pinned string (tests).
+    const authToken = (() => {
+        if (options.authToken === null)
+            return null;
+        if (options.authToken === "auto")
+            return createLocalServiceAuthToken();
+        if (typeof options.authToken === "string")
+            return options.authToken;
+        return null;
+    })();
     const runtime = createLocalServiceRuntime({
-        rootPath,
+        rootPath: resolvedRoot,
         host: config.host,
         port: config.port,
         packageVersion: options.packageVersion,
         handlers: options.handlers,
+        ...(authToken ? { authToken } : {}),
     });
+    // Rehydrate 0.13 preparations as synthetic workspaces so subsequent
+    // compile / test / readiness calls find them after a service restart.
+    try {
+        rehydratePreparations(runtime);
+    }
+    catch {
+        // best effort
+    }
     const server = createLocalServiceServer(runtime);
-    await new Promise((resolveListen, rejectListen) => {
-        const onError = (error) => {
-            server.off("listening", onListening);
-            rejectListen(error);
-        };
-        const onListening = () => {
-            server.off("error", onError);
-            resolveListen();
-        };
-        server.once("error", onError);
-        server.once("listening", onListening);
-        server.listen(config.port, config.host);
-    });
-    const url = runtime.health().service_url;
-    writeLocalServicePointer(rootPath, {
-        service_url: url,
-        host: config.host,
-        port: config.port,
-        pid: process.pid,
-        control_path: resolve(rootPath),
-        started_at: new Date().toISOString(),
-    });
+    const boundPort = await listenWithFallback(server, config.host, config.port, requestedPort.pinned);
+    runtime.setBoundPort(boundPort);
+    const health = runtime.health();
+    const url = health.service_url;
+    const startedAt = health.instance_started_at ?? new Date().toISOString();
+    // Central stop-lookup registry — one entry per running instance.
+    // (Server-side write only; CLI no longer reads this.)
+    const writeRegistryEntry = () => {
+        try {
+            registerServiceLocally(ServiceRegistryEntrySchema.parse({
+                pid: process.pid,
+                host: config.host,
+                port: boundPort,
+                url,
+                started_at: startedAt,
+                workspaces: runtime.registeredPreparationSnapshots(),
+                ...(authToken ? { auth_token: authToken } : {}),
+            }));
+        }
+        catch {
+            // best effort: registry corruption shouldn't take the service down
+        }
+    };
+    writeRegistryEntry();
+    runtime.setOnRegistryChanged(writeRegistryEntry);
+    // Write the 0.13 single-record CLI connection so `interf prep`,
+    // `interf compile`, etc. can find this engine without a pointer file.
+    try {
+        writeConnection({ url, auth_token: authToken });
+    }
+    catch {
+        // best effort: connection file is convenience, not correctness
+    }
     return {
         runtime,
         server,
         url,
         close: () => new Promise((resolveClose, rejectClose) => {
+            runtime.setOnRegistryChanged(null);
             server.close((error) => {
                 if (error) {
                     rejectClose(error);
                     return;
                 }
-                removeLocalServicePointer(rootPath, url);
+                try {
+                    unregisterService(process.pid);
+                }
+                catch {
+                    // best effort
+                }
+                try {
+                    // Clear connection record only if it still points at us.
+                    const current = readActiveConnection();
+                    if (current?.url === url)
+                        clearConnection();
+                }
+                catch {
+                    // best effort
+                }
                 resolveClose();
             });
         }),