@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/engine/server.js

@@ -0,0 +1,1257 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+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 { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceConfigSchema, LocalServiceDiscoverySchema, LocalServiceErrorSchema, OpenPathRequestSchema, ServiceRegistryEntrySchema, } from "./lib/schema.js";
+import { assertPathWithinRoot, } from "../contracts/utils/path-guards.js";
+import { createLocalServiceRuntime, } from "./runtime.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, updateStoredPreparation, } from "./preparation-store.js";
+import { clearConnection, readActiveConnection, writeConnection, } from "./connection-config.js";
+import { userMethodsRoot } from "./instance-paths.js";
+import { builtinMethodPackagePath, methodDefinitionPath, } from "../methods/package/local-methods.js";
+import { userMethodPath, userMethodExists } from "../methods/package/user-methods.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-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)), "..", "..", "..");
+}
+export function resolveCompilerUiStaticRoot(rootPath = packageRoot()) {
+    const distRoot = join(rootPath, "dist", "compiler-ui");
+    const sourceExportRoot = join(rootPath, "apps", "compiler-ui", "out");
+    if (existsSync(join(distRoot, "index.html")))
+        return distRoot;
+    if (existsSync(join(sourceExportRoot, "index.html")))
+        return sourceExportRoot;
+    return distRoot;
+}
+function compilerUiStaticRoot() {
+    const explicit = process.env.INTERF_COMPILER_UI_STATIC_ROOT?.trim();
+    if (explicit)
+        return resolve(explicit);
+    return resolveCompilerUiStaticRoot();
+}
+function contentType(filePath) {
+    switch (extname(filePath)) {
+        case ".html":
+            return "text/html; charset=utf-8";
+        case ".js":
+            return "text/javascript; charset=utf-8";
+        case ".css":
+            return "text/css; charset=utf-8";
+        case ".json":
+            return "application/json; charset=utf-8";
+        case ".svg":
+            return "image/svg+xml";
+        case ".png":
+            return "image/png";
+        case ".ico":
+            return "image/x-icon";
+        case ".txt":
+            return "text/plain; charset=utf-8";
+        case ".md":
+            return "text/markdown; charset=utf-8";
+        case ".yml":
+        case ".yaml":
+            return "application/yaml; charset=utf-8";
+        case ".map":
+            return "application/json; charset=utf-8";
+        case ".webmanifest":
+            return "application/manifest+json; charset=utf-8";
+        case ".woff2":
+            return "font/woff2";
+        default:
+            return "application/octet-stream";
+    }
+}
+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, {
+        ...context.cors,
+        ...extraHeaders,
+    });
+}
+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, 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, 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,
+        },
+    }));
+}
+function resolveOpenPath(allowedRoots, pathValue) {
+    const roots = allowedRoots.map((root) => resolve(root));
+    const targetPath = resolve(pathValue);
+    for (const root of roots) {
+        try {
+            return assertPathWithinRoot(root, targetPath, "Open path");
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error(`Open path must stay inside ${roots.join(" or ")}: ${targetPath}`);
+}
+async function openLocalPath(allowedRoots, pathValue) {
+    const targetPath = resolveOpenPath(allowedRoots, pathValue);
+    if (!existsSync(targetPath)) {
+        throw new Error(`Path does not exist: ${targetPath}`);
+    }
+    if (process.env.INTERF_OPEN_PATH_DRY_RUN === "1") {
+        return targetPath;
+    }
+    const isDirectory = statSync(targetPath).isDirectory();
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "explorer.exe"
+            : "xdg-open";
+    const args = process.platform === "darwin"
+        ? (isDirectory ? [targetPath] : ["-R", targetPath])
+        : process.platform === "win32"
+            ? (isDirectory ? [targetPath] : ["/select,", targetPath])
+            : [isDirectory ? targetPath : dirname(targetPath)];
+    await new Promise((resolveOpen, rejectOpen) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", rejectOpen);
+        child.once("spawn", () => {
+            child.unref();
+            resolveOpen();
+        });
+    });
+    return targetPath;
+}
+function parseRequestUrl(req) {
+    return new URL(req.url ?? "/", "http://127.0.0.1");
+}
+function safeStaticPath(root, relativePath) {
+    const normalized = normalize(relativePath).replace(/^(\.\.(?:\/|\\|$))+/, "");
+    const absolute = resolve(root, normalized);
+    const resolvedRoot = resolve(root);
+    if (absolute !== resolvedRoot && !absolute.startsWith(`${resolvedRoot}${sep}`)) {
+        return null;
+    }
+    return absolute;
+}
+/**
+ * Resolve the on-disk root path for a method id. Used by the
+ * `/v1/methods/<id>/files/<relpath>` route. Resolution order matches
+ * the runtime: preparation-draft (if a prep id is supplied) → user
+ * library → built-in. Returns `null` when the method id resolves
+ * nowhere.
+ */
+function resolveMethodPackageRoot(methodId, prepDataDir) {
+    if (prepDataDir) {
+        const localPath = methodDefinitionPath(prepDataDir, methodId);
+        if (existsSync(join(localPath, "method.json")))
+            return localPath;
+    }
+    if (userMethodExists(methodId)) {
+        return userMethodPath(methodId);
+    }
+    const builtinPath = builtinMethodPackagePath(methodId);
+    if (existsSync(join(builtinPath, "method.json")))
+        return builtinPath;
+    return null;
+}
+function sendFile(res, filePath) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        if (!statSync(filePath).isFile())
+            return false;
+        writeHeaders(res, 200, {
+            "content-type": contentType(filePath),
+        });
+        res.end(readFileSync(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reject any path that contains `..` or absolute segments — used by the
+ * 0.16 file-serving endpoints (`/v1/methods/<id>/files/...`,
+ * `/v1/preparations/<id>/files/...`). The `safeStaticPath` helper used
+ * by the static-asset path silently strips traversal segments; for the
+ * API endpoints we want a hard reject so the response is unambiguous.
+ */
+function isTraversalRelativePath(relPath) {
+    if (relPath.length === 0)
+        return true;
+    const segments = relPath.split(/[\\/]+/);
+    for (const segment of segments) {
+        if (segment === ".." || segment === "")
+            return true;
+    }
+    if (relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath))
+        return true;
+    return false;
+}
+function sendCompilerUiAsset(req, res, _runtime) {
+    const staticRoot = compilerUiStaticRoot();
+    const url = parseRequestUrl(req);
+    if (url.pathname === "/") {
+        const indexPath = join(staticRoot, "index.html");
+        if (sendFile(res, indexPath))
+            return true;
+        sendText(res, 503, "Interf UI assets are missing. Run `npm run web:build`, then restart `interf web`.\n");
+        return true;
+    }
+    if (url.pathname.startsWith("/_next/static/")) {
+        const relativePath = url.pathname.slice("/_next/static/".length);
+        const assetPath = safeStaticPath(join(staticRoot, "_next", "static"), relativePath);
+        if (assetPath && sendFile(res, assetPath))
+            return true;
+    }
+    const assetPath = safeStaticPath(staticRoot, url.pathname.slice(1));
+    if (assetPath && sendFile(res, assetPath))
+        return true;
+    return false;
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw)
+        return {};
+    return JSON.parse(raw);
+}
+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;
+    }
+    // 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,
+                action_proposals: LOCAL_SERVICE_ROUTES.actionProposals,
+                executor: LOCAL_SERVICE_ROUTES.executor,
+                agents: LOCAL_SERVICE_ROUTES.agents,
+                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;
+        const agentSnapshot = runtime.getAgentsRegistry();
+        // 0.16 — `connection_kind` lets the UI know whether OS-open is even
+        // possible. A loopback bind means the engine has filesystem access
+        // to the same host as the user; non-loopback (cloud) returns
+        // "remote" so the UI routes to api-served / signed-URL paths
+        // instead. The current binary refuses non-loopback binds (see the
+        // host whitelist below), so the value is "local" today; the field
+        // is in place so the UI can read it without a CLI version sniff.
+        const isLoopback = LOCAL_SERVICE_LOOPBACK_HOSTS.includes(runtime.host);
+        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),
+            // 0.15 connected-agents fields:
+            agent_count: agentSnapshot.agents.length,
+            default_agent: agentSnapshot.active_agent?.name ?? null,
+            // 0.16 connection-mode flag:
+            connection_kind: isLoopback ? "local" : "remote",
+        });
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Preparation collection routes
+    // ─────────────────────────────────────────────────────────────────────────
+    // GET /v1/preparations — list every preparation on the instance.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.preparations) {
+        const items = listStoredPreparations().map(preparationWireShape);
+        sendJson(res, 200, { preparations: items });
+        return true;
+    }
+    // POST /v1/preparations — create a new preparation.
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.preparations) {
+        try {
+            const body = (await readJsonBody(req));
+            if (!body || typeof body !== "object") {
+                sendError(res, 400, "Request body must be a JSON object.");
+                return true;
+            }
+            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, 400, error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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;
+        }
+        runtime.touchPreparation(storedPrep.prepDataDir);
+        if (subPath === "") {
+            // Bare /v1/preparations/{id}
+            if (method === "GET") {
+                sendJson(res, 200, preparationWireShape(storedPrep));
+                return true;
+            }
+            if (method === "PATCH") {
+                try {
+                    const body = (await readJsonBody(req));
+                    if (!body || typeof body !== "object") {
+                        sendError(res, 400, "Request body must be a JSON object.");
+                        return true;
+                    }
+                    const updated = updateStoredPreparation(decodedPrepId, {
+                        method_id: body.method_id,
+                        about: body.about,
+                    });
+                    sendJson(res, 200, preparationWireShape(updated));
+                }
+                catch (error) {
+                    sendError(res, 400, error instanceof Error ? error.message : String(error));
+                }
+                return true;
+            }
+            if (method === "DELETE") {
+                deleteStoredPreparation(runtime, decodedPrepId);
+                sendJson(res, 200, { id: decodedPrepId, deleted: true });
+                return true;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.compileRuns) {
+            if (method === "POST") {
+                if (!storedPrep.methodId) {
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no method bound. Set one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before compiling.`);
+                    return true;
+                }
+                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;
+            }
+        }
+        else if (subPath === PREPARATION_SUBRESOURCES.verifyRuns) {
+            if (method === "POST") {
+                if (!storedPrep.methodId) {
+                    sendError(res, 400, `Preparation ${storedPrep.id} has no method bound. Set one via PATCH /v1/preparations/${storedPrep.id} { "method_id": "<id>" } before verifying.`);
+                    return true;
+                }
+                try {
+                    const body = (await readJsonBody(req));
+                    const request = { preparation: storedPrep.id, ...(body ?? {}) };
+                    const resource = await runtime.createVerifyRun(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;
+            }
+        }
+        else if (subPath.startsWith(`${PREPARATION_SUBRESOURCES.files}/`)) {
+            // GET /v1/preparations/<id>/files/<relpath> — read-only file
+            // serving inside the prep's portable-context root. Used by the
+            // locator pattern's `api-served` kind.
+            if (method === "GET") {
+                const rawRelPath = subPath.slice(PREPARATION_SUBRESOURCES.files.length + 1);
+                let relPath;
+                try {
+                    relPath = decodeURIComponent(rawRelPath);
+                }
+                catch {
+                    sendError(res, 400, "File path is not valid URI-encoded UTF-8.");
+                    return true;
+                }
+                if (isTraversalRelativePath(relPath)) {
+                    sendError(res, 400, "File path escapes portable-context root.");
+                    return true;
+                }
+                const safePath = safeStaticPath(storedPrep.portableContextPath, relPath);
+                if (!safePath) {
+                    sendError(res, 400, "File path escapes portable-context root.");
+                    return true;
+                }
+                if (!sendFile(res, safePath)) {
+                    sendError(res, 404, `File not found: ${relPath}`);
+                }
+                return true;
+            }
+        }
+        sendError(res, 404, `Unknown preparation sub-route: ${subPath}`);
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Method resources — preparation-independent (workspace draft + user lib + bundled).
+    // ─────────────────────────────────────────────────────────────────────────
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.methods) {
+        // 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 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;
+    }
+    const methodRunsMatch = path.match(/^\/v1\/methods\/([^/]+)\/runs$/);
+    if (method === "GET" && methodRunsMatch?.[1]) {
+        const firstPrep = listStoredPreparations()[0];
+        const runs = runtime.listMethodRuns(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(methodRunsMatch[1]));
+        sendJson(res, 200, { runs });
+        return true;
+    }
+    // GET /v1/methods/<id>/files/<relpath> — read-only file serving inside
+    // the method root. Used by the locator pattern's `api-served` kind so
+    // the UI can render SKILL.md / contract files in a side drawer over a
+    // remote engine. Resolution: prep-draft (when first prep exists) →
+    // user library → built-in. Path-guard rejects any traversal outside
+    // the resolved root.
+    const methodFilesMatch = path.match(/^\/v1\/methods\/([^/]+)\/files\/(.+)$/);
+    if (method === "GET" && methodFilesMatch?.[1] && methodFilesMatch[2]) {
+        const methodId = decodeURIComponent(methodFilesMatch[1]);
+        let relPath;
+        try {
+            relPath = decodeURIComponent(methodFilesMatch[2]);
+        }
+        catch {
+            sendError(res, 400, "File path is not valid URI-encoded UTF-8.");
+            return true;
+        }
+        if (isTraversalRelativePath(relPath)) {
+            sendError(res, 400, "File path escapes method root.");
+            return true;
+        }
+        const firstPrep = listStoredPreparations()[0];
+        const root = resolveMethodPackageRoot(methodId, firstPrep?.prepDataDir);
+        if (!root) {
+            sendError(res, 404, `Method not found: ${methodId}`);
+            return true;
+        }
+        const safePath = safeStaticPath(root, relPath);
+        if (!safePath) {
+            sendError(res, 400, "File path escapes method root.");
+            return true;
+        }
+        if (!sendFile(res, safePath)) {
+            sendError(res, 404, `File not found: ${relPath}`);
+        }
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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;
+    }
+    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) {
+        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);
+        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(prepDataDir, proposalId);
+            if (!proposal)
+                sendError(res, 404, "Action proposal not found.");
+            else
+                sendJson(res, 200, proposal);
+            return true;
+        }
+        if (method === "POST" && child === "decision") {
+            const body = await readJsonBody(req);
+            const proposal = await runtime.decideActionProposal(prepDataDir, proposalId, body);
+            if (!proposal)
+                sendError(res, 404, "Action proposal not found.");
+            else
+                sendJson(res, 202, proposal);
+            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(prepDataDir, runId);
+            if (!run)
+                sendError(res, 404, "Compile run not found.");
+            else
+                sendJson(res, 200, run);
+            return true;
+        }
+        if (method === "GET" && child === "events") {
+            const events = runtime.getCompileRunEvents(prepDataDir, runId);
+            if (!events)
+                sendError(res, 404, "Compile run not found.");
+            else
+                sendJson(res, 200, { events });
+            return true;
+        }
+        if (method === "GET" && child === "proof") {
+            const proof = runtime.getCompileRunProof(prepDataDir, runId);
+            if (!proof)
+                sendError(res, 404, "Compile run not found.");
+            else
+                sendJson(res, 200, { proof });
+            return true;
+        }
+        if (method === "GET" && child === "artifacts") {
+            const artifacts = runtime.getCompileRunArtifacts(prepDataDir, runId);
+            if (!artifacts)
+                sendError(res, 404, "Compile run not found.");
+            else
+                sendJson(res, 200, { artifacts });
+            return true;
+        }
+        if (method === "POST" && child === "cancel") {
+            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;
+        }
+    }
+    const verifyRunMatch = path.match(/^\/v1\/verify-runs\/([^/]+)$/);
+    if (method === "GET" && verifyRunMatch?.[1]) {
+        const firstPrep = listStoredPreparations()[0];
+        const run = runtime.getVerifyRun(firstPrep?.prepDataDir ?? runtime.rootPath, decodeURIComponent(verifyRunMatch[1]));
+        if (!run)
+            sendError(res, 404, "Verify 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];
+        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;
+    }
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.executor) {
+        const body = await readJsonBody(req);
+        sendJson(res, 202, runtime.selectExecutor(body));
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Connected agents (0.15) — registry, role-map, role list.
+    // ─────────────────────────────────────────────────────────────────────────
+    if (path === LOCAL_SERVICE_ROUTES.agents) {
+        if (method === "GET") {
+            sendJson(res, 200, runtime.getAgentsRegistry());
+            return true;
+        }
+        if (method === "POST") {
+            try {
+                const body = (await readJsonBody(req));
+                if (!body || typeof body !== "object") {
+                    sendError(res, 400, "Request body must be a JSON object.");
+                    return true;
+                }
+                if (!body.name || typeof body.name !== "string") {
+                    sendError(res, 400, "Missing required field: name");
+                    return true;
+                }
+                if (!body.display_name || typeof body.display_name !== "string") {
+                    sendError(res, 400, "Missing required field: display_name");
+                    return true;
+                }
+                if (!body.command || typeof body.command !== "string") {
+                    sendError(res, 400, "Missing required field: command");
+                    return true;
+                }
+                const updated = runtime.registerCustomAgent({
+                    name: body.name,
+                    display_name: body.display_name,
+                    command: body.command,
+                });
+                sendJson(res, 201, updated);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (method === "GET" && path === `${LOCAL_SERVICE_ROUTES.agents}/roles`) {
+        sendJson(res, 200, {
+            kind: "interf-canonical-roles",
+            version: 1,
+            roles: ["extractor", "summarizer", "structurer", "verifier", "general"],
+        });
+        return true;
+    }
+    if (path === `${LOCAL_SERVICE_ROUTES.agents}/role-map`) {
+        if (method === "GET") {
+            const snapshot = runtime.getAgentsRegistry();
+            sendJson(res, 200, {
+                role_map: snapshot.role_map,
+                active_agent: snapshot.active_agent,
+            });
+            return true;
+        }
+        if (method === "PATCH") {
+            try {
+                const body = (await readJsonBody(req));
+                if (!body || typeof body !== "object") {
+                    sendError(res, 400, "Request body must be a JSON object.");
+                    return true;
+                }
+                const patch = {};
+                for (const [role, value] of Object.entries(body)) {
+                    if (typeof value !== "string") {
+                        sendError(res, 400, `Role-map values must be strings (or "" to clear). Got ${typeof value} for role "${role}".`);
+                        return true;
+                    }
+                    patch[role] = value;
+                }
+                const updated = runtime.patchAgentsRoleMap(patch);
+                sendJson(res, 200, updated);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    // /v1/agents/<name> — only DELETE; built-in names return 400.
+    const agentMatch = path.match(/^\/v1\/agents\/([^/]+)$/);
+    if (agentMatch?.[1] && method === "DELETE") {
+        const name = decodeURIComponent(agentMatch[1]);
+        try {
+            const updated = runtime.unregisterCustomAgent(name);
+            sendJson(res, 200, updated);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Rejecting a built-in unregister is a 400 (bad request, the
+            // caller is asking for something the contract doesn't allow).
+            const status = /built-in agent/.test(message) ? 400 : 404;
+            sendError(res, status, message);
+        }
+        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
+        //  - the user method library at `~/.interf/methods/`
+        //  - the bundled built-in method root inside the installed package
+        //    (so SKILL.md / contract files in `interf-default` open correctly)
+        const allowedRoots = [];
+        for (const stored of listStoredPreparations()) {
+            allowedRoots.push(stored.prepDataDir);
+            if (stored.source.locator)
+                allowedRoots.push(stored.source.locator);
+        }
+        allowedRoots.push(userMethodsRoot());
+        allowedRoots.push(packageRoot()); // covers <pkg>/builtin-methods/...
+        const openedPath = await openLocalPath(allowedRoots, body.path);
+        sendJson(res, 202, { opened: true, path: openedPath });
+        return true;
+    }
+    return false;
+}
+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)
+                    return;
+                if (sendCompilerUiAsset(req, res, runtime))
+                    return;
+                sendText(res, 404, "Not found.\n");
+            }
+            catch (error) {
+                sendError(res, 500, error instanceof Error ? error.message : String(error));
+            }
+        })();
+    });
+}
+function resolvePort(optionPort) {
+    if (typeof optionPort === "number")
+        return { port: optionPort, pinned: true };
+    const envPort = Number.parseInt(process.env.INTERF_SERVICE_PORT ?? "", 10);
+    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: 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: 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);
+    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;
+                }
+                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();
+            });
+        }),
+    };
+}