@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/engine/server.js

@@ -1,1399 +0,0 @@
-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, PreparationCreateRequestSchema, PreparationUpdateRequestSchema, ServiceRegistryEntrySchema, BuildPlanSaveRequestSchema, } 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 { userBuildPlansRoot } from "./instance-paths.js";
-import { builtinBuildPlanPackagePath, buildPlanDefinitionPath, } from "../build-plans/package/local-build-plans.js";
-import { installUserBuildPlan, userBuildPlanPath, userBuildPlanExists } from "../build-plans/package/user-build-plans.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 resolveInterfUiStaticRoot(rootPath = packageRoot()) {
-    const distRoot = join(rootPath, "dist", "interf-ui");
-    const sourceExportRoot = join(rootPath, "src", "apps", "interf-ui", "out");
-    if (existsSync(join(distRoot, "index.html")))
-        return distRoot;
-    if (existsSync(join(sourceExportRoot, "index.html")))
-        return sourceExportRoot;
-    return distRoot;
-}
-function interfUiStaticRoot() {
-    const explicit = process.env.INTERF_UI_STATIC_ROOT?.trim();
-    if (explicit)
-        return resolve(explicit);
-    return resolveInterfUiStaticRoot();
-}
-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 Build Plan id. Used by the
- * `/v1/build-plans/<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 Build Plan id resolves
- * nowhere.
- */
-function resolveBuildPlanPackageRoot(buildPlanId, prepDataDir) {
-    if (prepDataDir) {
-        const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
-        if (existsSync(join(localPath, "build-plan.json")))
-            return localPath;
-    }
-    if (userBuildPlanExists(buildPlanId)) {
-        return userBuildPlanPath(buildPlanId);
-    }
-    const builtinPath = builtinBuildPlanPackagePath(buildPlanId);
-    if (existsSync(join(builtinPath, "build-plan.json")))
-        return builtinPath;
-    return null;
-}
-function sendFile(res, filePath) {
-    if (!existsSync(filePath))
-        return false;
-    try {
-        if (!statSync(filePath).isFile())
-            return false;
-        const type = contentType(filePath);
-        const headers = { "content-type": type };
-        // 0.17 — never cache HTML responses. UI deploys ship a fresh
-        // dist via `npm run web:build` and a restart; without `no-store`,
-        // a browser sitting on a stale `index.html` would keep loading
-        // hashed asset paths that no longer exist. Hashed Next.js bundles
-        // under `_next/static/<hash>/` keep the default long-cache
-        // because the filename itself changes when content changes.
-        if (type.startsWith("text/html")) {
-            headers["cache-control"] = "no-store";
-        }
-        writeHeaders(res, 200, headers);
-        res.end(readFileSync(filePath));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function isUsableInterfUiIndexHtml(filePath) {
-    if (!existsSync(filePath))
-        return false;
-    const html = readFileSync(filePath, "utf8");
-    return html.includes("</html>")
-        && html.includes("</script>")
-        && html.includes("_next/static/");
-}
-/**
- * Reject any path that contains `..` or absolute segments — used by the
- * 0.16 file-serving endpoints (`/v1/build-plans/<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 sendInterfUiAsset(req, res, _runtime) {
-    const staticRoot = interfUiStaticRoot();
-    const url = parseRequestUrl(req);
-    if (url.pathname === "/") {
-        const indexPath = join(staticRoot, "index.html");
-        if (!isUsableInterfUiIndexHtml(indexPath)) {
-            sendText(res, 503, "Interf UI assets are invalid. Run `npm run web:build`, then restart `interf web`.\n");
-            return true;
-        }
-        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);
-    const prepDataDirsForInstance = () => {
-        const dirs = listStoredPreparations().map((prep) => prep.prepDataDir);
-        return dirs.length > 0 ? dirs : [runtime.rootPath];
-    };
-    const listInstanceRuns = () => {
-        return prepDataDirsForInstance()
-            .flatMap((prepDataDir) => runtime.listRunObservability(prepDataDir))
-            .sort((left, right) => {
-            const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
-            const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
-            return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
-        });
-    };
-    const findInstanceRun = (runId) => {
-        for (const prepDataDir of prepDataDirsForInstance()) {
-            const run = runtime.getRunObservability(prepDataDir, runId);
-            if (run)
-                return run;
-        }
-        return null;
-    };
-    const findInstanceJob = (runId) => {
-        for (const prepDataDir of prepDataDirsForInstance()) {
-            const job = runtime.getJob(prepDataDir, runId);
-            if (job)
-                return { job, prepDataDir };
-        }
-        return null;
-    };
-    const listInstanceBuildPlans = () => {
-        const byId = new Map();
-        for (const prepDataDir of prepDataDirsForInstance()) {
-            for (const buildPlanResource of runtime.listBuildPlans(prepDataDir)) {
-                const existing = byId.get(buildPlanResource.id);
-                if (!existing) {
-                    byId.set(buildPlanResource.id, buildPlanResource);
-                    continue;
-                }
-                const preferred = existing.built_in && !buildPlanResource.built_in
-                    ? buildPlanResource
-                    : existing;
-                byId.set(buildPlanResource.id, {
-                    ...preferred,
-                    active_for_preparations: Array.from(new Set([
-                        ...existing.active_for_preparations,
-                        ...buildPlanResource.active_for_preparations,
-                    ])).sort(),
-                });
-            }
-        }
-        return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
-    };
-    const findInstanceBuildPlan = (buildPlanId) => {
-        return listInstanceBuildPlans().find((buildPlanResource) => buildPlanResource.id === buildPlanId) ?? null;
-    };
-    const listInstanceBuildPlanRuns = (buildPlanId) => {
-        return prepDataDirsForInstance()
-            .flatMap((prepDataDir) => runtime.listBuildPlanRuns(prepDataDir, buildPlanId))
-            .sort((left, right) => {
-            const leftMs = Date.parse(left.started_at ?? left.created_at ?? left.finished_at ?? "");
-            const rightMs = Date.parse(right.started_at ?? right.created_at ?? right.finished_at ?? "");
-            return (Number.isFinite(rightMs) ? rightMs : 0) - (Number.isFinite(leftMs) ? leftMs : 0);
-        });
-    };
-    const resolveInstanceBuildPlanPackageRoot = (buildPlanId) => {
-        for (const prepDataDir of prepDataDirsForInstance()) {
-            const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
-            if (existsSync(join(localPath, "build-plan.json")))
-                return localPath;
-        }
-        return resolveBuildPlanPackageRoot(buildPlanId);
-    };
-    // 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,
-                build_plans: LOCAL_SERVICE_ROUTES.buildPlans,
-                build_runs: LOCAL_SERVICE_ROUTES.buildRuns,
-                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 = PreparationCreateRequestSchema.parse(await readJsonBody(req));
-            // TODO(cloud): activate remote-folder validator branch when the
-            // cloud variant lands. The local binary only knows how to read
-            // bytes from a local path; a `remote-folder` binding requires
-            // the cloud variant's per-account object-storage mount layer.
-            // Until then, reject any kind other than `local-folder` so the
-            // wire shape and runtime stay consistent.
-            if (body.source.kind !== "local-folder") {
-                sendError(res, 400, `Unsupported source kind: ${body.source.kind}. The local engine only accepts local-folder bindings; remote-folder requires the cloud variant.`);
-                return true;
-            }
-            const stored = createStoredPreparation(runtime, {
-                id: body.id,
-                source: { kind: "local-folder", locator: body.source.locator },
-                build_plan_id: body.build_plan_id,
-                about: body.about,
-                requested_artifacts: body.requested_artifacts,
-                source_profile: body.source_profile,
-                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") {
-                const preparation = runtime.getPreparation(storedPrep.prepDataDir, storedPrep.id);
-                sendJson(res, 200, preparation
-                    ? {
-                        ...preparation,
-                        source: storedPrep.source,
-                        about: storedPrep.about,
-                        config_path: storedPrep.configPath,
-                    }
-                    : preparationWireShape(storedPrep));
-                return true;
-            }
-            if (method === "PATCH") {
-                try {
-                    const body = PreparationUpdateRequestSchema.parse(await readJsonBody(req));
-                    const updated = updateStoredPreparation(decodedPrepId, {
-                        build_plan_id: body.build_plan_id,
-                        about: body.about,
-                        ...(body.checks !== undefined ? { checks: body.checks } : {}),
-                        ...(body.requested_artifacts !== undefined ? { requested_artifacts: body.requested_artifacts } : {}),
-                        ...(body.source_profile !== undefined ? { source_profile: body.source_profile } : {}),
-                    });
-                    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.buildRuns) {
-            if (method === "POST") {
-                if (!storedPrep.buildPlanId) {
-                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "build_plan_id": "<id>" } before building.`);
-                    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.findIdempotentBuildRun(storedPrep.prepDataDir, trimmedKey)
-                        : null;
-                    if (dedupedRunId) {
-                        const existing = runtime.getBuildRun(storedPrep.prepDataDir, dedupedRunId);
-                        if (existing) {
-                            sendJson(res, 200, existing);
-                            return true;
-                        }
-                    }
-                    const resource = await runtime.createBuildRun(storedPrep.prepDataDir, request);
-                    if (trimmedKey) {
-                        runtime.recordIdempotentBuildRun(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.buildPlanId) {
-                    sendError(res, 400, `Preparation ${storedPrep.id} has no Build Plan selected. Select one via PATCH /v1/preparations/${storedPrep.id} { "build_plan_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.buildPlanDraftRuns) {
-            if (method === "POST") {
-                try {
-                    const body = (await readJsonBody(req));
-                    const job = await runtime.createBuildPlanAuthoringRun(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.buildPlanImprovementRuns) {
-            if (method === "POST") {
-                try {
-                    const body = (await readJsonBody(req));
-                    const job = await runtime.createBuildPlanAuthoringRun(storedPrep.prepDataDir, body, "build-plan-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: "build", ...(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.listBuildRunsForPreparation(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.verifiableContext) {
-            if (method === "GET") {
-                const context = runtime.getVerifiableContext(storedPrep.prepDataDir, storedPrep.id);
-                if (!context)
-                    sendError(res, 404, "Verifiable 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 verifiable-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 verifiable-context root.");
-                    return true;
-                }
-                const safePath = safeStaticPath(storedPrep.verifiableContextPath, relPath);
-                if (!safePath) {
-                    sendError(res, 400, "File path escapes verifiable-context root.");
-                    return true;
-                }
-                if (!sendFile(res, safePath)) {
-                    sendError(res, 404, `File not found: ${relPath}`);
-                }
-                return true;
-            }
-        }
-        else if (subPath.startsWith(`${PREPARATION_SUBRESOURCES.artifacts}/`)) {
-            // GET /v1/preparations/<id>/artifacts/<artifact-id> — per-Artifact
-            // status from the latest Build run.
-            if (method === "GET") {
-                const rawArtifactId = subPath.slice(PREPARATION_SUBRESOURCES.artifacts.length + 1);
-                let artifactId;
-                try {
-                    artifactId = decodeURIComponent(rawArtifactId);
-                }
-                catch {
-                    sendError(res, 400, "Artifact id is not valid URI-encoded UTF-8.");
-                    return true;
-                }
-                const preparation = runtime.getPreparation(storedPrep.prepDataDir, storedPrep.id);
-                const status = preparation?.artifacts.find((entry) => entry.artifact_id === artifactId);
-                if (!status) {
-                    sendError(res, 404, `Artifact not found: ${artifactId}`);
-                    return true;
-                }
-                sendJson(res, 200, status);
-                return true;
-            }
-        }
-        sendError(res, 404, `Unknown preparation sub-route: ${subPath}`);
-        return true;
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // Build Plan resources — preparation-independent (Preparation-local + user lib + bundled).
-    // ─────────────────────────────────────────────────────────────────────────
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
-        sendJson(res, 200, { build_plans: listInstanceBuildPlans() });
-        return true;
-    }
-    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
-        try {
-            const body = BuildPlanSaveRequestSchema.parse(await readJsonBody(req));
-            const installed = installUserBuildPlan({
-                sourceDir: body.source_path,
-                id: body.id,
-                overwrite: body.overwrite,
-            });
-            sendJson(res, 201, {
-                build_plan_id: installed.id,
-                installed: true,
-                path: installed.path,
-            });
-        }
-        catch (error) {
-            sendError(res, 400, error instanceof Error ? error.message : String(error));
-        }
-        return true;
-    }
-    const buildPlanMatch = path.match(/^\/v1\/build-plans\/([^/]+)$/);
-    if (method === "GET" && buildPlanMatch?.[1]) {
-        const buildPlanResource = findInstanceBuildPlan(decodeURIComponent(buildPlanMatch[1]));
-        if (!buildPlanResource)
-            sendError(res, 404, "Build Plan not found.");
-        else
-            sendJson(res, 200, buildPlanResource);
-        return true;
-    }
-    const buildPlanRunsMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/runs$/);
-    if (method === "GET" && buildPlanRunsMatch?.[1]) {
-        const runs = listInstanceBuildPlanRuns(decodeURIComponent(buildPlanRunsMatch[1]));
-        sendJson(res, 200, { runs });
-        return true;
-    }
-    // GET /v1/build-plans/<id>/files/<relpath> — read-only file serving inside
-    // the Build Plan package 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 buildPlanFilesMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/files\/(.+)$/);
-    if (method === "GET" && buildPlanFilesMatch?.[1] && buildPlanFilesMatch[2]) {
-        const buildPlanId = decodeURIComponent(buildPlanFilesMatch[1]);
-        let relPath;
-        try {
-            relPath = decodeURIComponent(buildPlanFilesMatch[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 Build Plan root.");
-            return true;
-        }
-        const root = resolveInstanceBuildPlanPackageRoot(buildPlanId);
-        if (!root) {
-            sendError(res, 404, `Build Plan not found: ${buildPlanId}`);
-            return true;
-        }
-        const safePath = safeStaticPath(root, relPath);
-        if (!safePath) {
-            sendError(res, 400, "File path escapes Build Plan root.");
-            return true;
-        }
-        if (!sendFile(res, safePath)) {
-            sendError(res, 404, `File not found: ${relPath}`);
-        }
-        return true;
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // Run observability — instance-wide. The runtime takes a "first prep" hint
-    // to scan registered Preparations.
-    // ─────────────────────────────────────────────────────────────────────────
-    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.runs) {
-        sendJson(res, 200, { runs: listInstanceRuns() });
-        return true;
-    }
-    const observableRunMatch = path.match(/^\/v1\/runs\/([^/]+)$/);
-    if (method === "GET" && observableRunMatch?.[1]) {
-        const run = findInstanceRun(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;
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // Build-run sub-resources (instance-wide; runs are addressable by run_id).
-    // ─────────────────────────────────────────────────────────────────────────
-    const buildRunMatch = path.match(/^\/v1\/build-runs\/([^/]+)(?:\/([^/]+))?$/);
-    if (buildRunMatch?.[1]) {
-        const runId = decodeURIComponent(buildRunMatch[1]);
-        const child = buildRunMatch[2];
-        const firstPrep = listStoredPreparations()[0];
-        const prepDataDir = firstPrep?.prepDataDir ?? runtime.rootPath;
-        if (method === "GET" && !child) {
-            const run = runtime.getBuildRun(prepDataDir, runId);
-            if (!run)
-                sendError(res, 404, "Build run not found.");
-            else
-                sendJson(res, 200, run);
-            return true;
-        }
-        if (method === "GET" && child === "events") {
-            const events = runtime.getBuildRunEvents(prepDataDir, runId);
-            if (!events)
-                sendError(res, 404, "Build run not found.");
-            else
-                sendJson(res, 200, { events });
-            return true;
-        }
-        if (method === "GET" && child === "proof") {
-            const proof = runtime.getBuildRunProof(prepDataDir, runId);
-            if (!proof)
-                sendError(res, 404, "Build run not found.");
-            else
-                sendJson(res, 200, { proof });
-            return true;
-        }
-        if (method === "GET" && child === "artifacts") {
-            const artifacts = runtime.getBuildRunArtifacts(prepDataDir, runId);
-            if (!artifacts)
-                sendError(res, 404, "Build run not found.");
-            else
-                sendJson(res, 200, { artifacts });
-            return true;
-        }
-        if (method === "POST" && child === "cancel") {
-            const existing = runtime.getBuildRun(prepDataDir, runId);
-            if (!existing) {
-                sendError(res, 404, "Build run not found.");
-                return true;
-            }
-            const result = runtime.cancelBuildRun(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 found = findInstanceJob(runId);
-        if (method === "GET" && !child) {
-            if (!found)
-                sendError(res, 404, "Job run not found.");
-            else
-                sendJson(res, 200, found.job);
-            return true;
-        }
-        if (method === "GET" && child === "events") {
-            const events = found ? runtime.getJobEvents(found.prepDataDir, runId) : null;
-            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 buildPlan library at `~/.interf/build-plans/`
-        //  - the bundled built-in buildPlan 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(userBuildPlansRoot());
-        allowedRoots.push(packageRoot()); // covers <pkg>/public-repo/build-plans/...
-        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-buildPlan 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 (sendInterfUiAsset(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 } : {}),
-        // 0.17 — forward cloud-variant injection points. Local default
-        // ignores idempotencyStore / runLeaseStore (the runtime's
-        // in-process maps stay authoritative); they're accepted on the
-        // options surface so cloud forks have a stable target.
-        ...(options.billingEventSink ? { billingEventSink: options.billingEventSink } : {}),
-        ...(options.idempotencyStore ? { idempotencyStore: options.idempotencyStore } : {}),
-        ...(options.runLeaseStore ? { runLeaseStore: options.runLeaseStore } : {}),
-    });
-    // 0.17 — token validator (B4.3). Local default: undefined. Cloud
-    // variants pass an async per-account validator. Stashed on the
-    // runtime via `setTokenValidator` so `isAuthorizedMutation` can
-    // pick it up; the local engine ignores it (the static bearer
-    // check still runs).
-    if (options.tokenValidator) {
-        runtime.setTokenValidator(options.tokenValidator);
-    }
-    // Rehydrate saved preparations so subsequent
-    // build / 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,
-                ...(authToken ? { auth_token: authToken } : {}),
-            }));
-        }
-        catch {
-            // best effort: registry corruption shouldn't take the service down
-        }
-    };
-    writeRegistryEntry();
-    runtime.setOnRegistryChanged(writeRegistryEntry);
-    // Write the single-record CLI connection so `interf prep`,
-    // `interf build`, 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();
-            });
-        }),
-    };
-}