summer-engine 2.8.2 → 3.1.0

package/dist/core/feedback/client.js

@@ -0,0 +1,182 @@
+/**
+ * Library-feedback client (CONTRACT.md §10, v1 = mailbox).
+ *
+ * Fire-and-forget POST of batched library-entry outcome reports to the
+ * Summer gateway. Structurally leak-proof by schema (enums + hard caps —
+ * no field can carry project files, chat content, or code), 1s timeout,
+ * silent failure, never throws, never retries, never blocks the agent
+ * for more than the timeout.
+ *
+ * Consent (SELF_IMPROVING_LIBRARY.md §3.4):
+ * - SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1 → nothing is ever sent.
+ * - First-run notice BEFORE the first event (CONTRACT §10): the first call
+ *   ever made on a machine sends NOTHING and returns a one-paragraph notice
+ *   of what a report contains + the opt-out env vars; sending starts on the
+ *   next call.
+ * - Authenticated installs attribute via the auth bearer; anonymous
+ *   installs use a random persisted install id (a uuid — no hardware,
+ *   user, or project identity).
+ *
+ * No stdout writes anywhere in this module (stdio MCP protocol);
+ * nothing is logged on failure — silence is the contract.
+ */
+import { randomUUID } from "node:crypto";
+import { getAuthToken } from "../auth.js";
+import { resolveGatewayUrl } from "../config.js";
+import { readStoreText, writeStoreText } from "../store.js";
+import { TOOLKIT_VERSION } from "../version.js";
+const FEEDBACK_PATH = "/api/mcp/library-feedback";
+const TIMEOUT_MS = 1000;
+const INSTALL_ID_FILE = "feedback-install-id";
+const FIRST_RUN_MARKER_FILE = "feedback-first-run";
+/** Random per-MCP-server-process session id. Never persisted. */
+let sessionId = null;
+export function getFeedbackSessionId() {
+    if (!sessionId)
+        sessionId = randomUUID();
+    return sessionId;
+}
+/** Test-only seam. */
+export function _resetFeedbackSessionForTests() {
+    sessionId = null;
+}
+async function feedbackUrl() {
+    return `${await resolveGatewayUrl()}${FEEDBACK_PATH}`;
+}
+/** Kill switches: send NOTHING when either is set to "1". */
+export function isFeedbackDisabled() {
+    return (process.env.SUMMER_NO_TELEMETRY === "1" || process.env.DO_NOT_TRACK === "1");
+}
+/**
+ * Anonymous install id: a random uuid persisted once in ~/.summer/.
+ * Falls back to an ephemeral uuid if the store is unreadable/unwritable —
+ * feedback must never fail because the store does.
+ */
+export async function getInstallId() {
+    try {
+        const existing = await readStoreText(INSTALL_ID_FILE);
+        if (existing?.trim())
+            return existing.trim();
+        const created = randomUUID();
+        await writeStoreText(INSTALL_ID_FILE, created);
+        return created;
+    }
+    catch {
+        return randomUUID();
+    }
+}
+/**
+ * First-run notice gate: returns true exactly once per machine — the first
+ * time the feedback tool is ever called — and writes the marker so every
+ * later call returns false. That first call sends nothing (the notice must
+ * precede the first event). Errors → false (no notice beats a crash, and
+ * the disclosure also lives in the tool description).
+ */
+export async function consumeFirstRunNotice() {
+    try {
+        const marker = await readStoreText(FIRST_RUN_MARKER_FILE);
+        if (marker !== null)
+            return false;
+        await writeStoreText(FIRST_RUN_MARKER_FILE, new Date().toISOString());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Every field a report POST carries, in one place so the tool description,
+ *  the first-run notice and the tests cannot disagree about what is sent. */
+export const FEEDBACK_FIELDS_SENT = "the library entry ids you used (entry_id), one outcome word per entry, your optional note and deviation " +
+    "(280 characters max each, about the entry itself), engine_version, agent_model (your self-reported model id), " +
+    "toolkit_version (this CLI's version), client (the host app name/version from the MCP handshake), " +
+    "session_id (a random id per MCP server process, never persisted), and — only when not logged in — " +
+    "install_id (a random uuid stored in ~/.summer/; no hardware, user, or project identity). When logged in, " +
+    "the Summer account bearer token is sent instead of install_id.";
+export const FIRST_RUN_NOTICE = "First use of summer_library_feedback on this machine — NOTHING has been sent yet, including this batch. " +
+    "Call the tool again with the same reports to send them; this notice appears only once. " +
+    `What every report sends to Summer (POST ${FEEDBACK_PATH}): ${FEEDBACK_FIELDS_SENT} ` +
+    "The report schema has no field for project files, chat content, or code. Reports are used to fix and " +
+    "re-rank library entries, so this user's own future sessions load better ones. Opt out any time by setting " +
+    "SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1 — then nothing is ever sent.";
+/** Classify a non-2xx response. Exported for tests. */
+export function dropReasonForStatus(status) {
+    if (status === 404)
+        return "endpoint_missing";
+    if (status >= 500)
+        return "server_error";
+    return "rejected";
+}
+/**
+ * Send one batched feedback report. Never throws. Blocks at most TIMEOUT_MS.
+ *
+ * Result matrix:
+ * - env kill switch          → { recorded: false, disabled: true }     (nothing sent)
+ * - first call on machine    → { recorded: false, first_run: true, notice } (nothing sent)
+ * - gateway accepted (2xx)   → { recorded: true }
+ * - non-2xx                  → { recorded: false, dropped: true, status, reason } (no retry exists)
+ * - fetch threw / timed out  → { recorded: false, dropped: true, reason: "network" }
+ */
+export async function sendLibraryFeedback(input) {
+    if (isFeedbackDisabled()) {
+        return { recorded: false, disabled: true };
+    }
+    // The notice must precede the first event: the first call on a machine
+    // returns the disclosure and sends nothing at all.
+    if (await consumeFirstRunNotice()) {
+        return { recorded: false, first_run: true, notice: FIRST_RUN_NOTICE };
+    }
+    try {
+        let token = null;
+        try {
+            token = await getAuthToken();
+        }
+        catch {
+            token = null;
+        }
+        const body = {
+            reports: input.reports,
+            engine_version: input.engine_version,
+            agent_model: input.agent_model,
+            session_id: getFeedbackSessionId(),
+            toolkit_version: TOOLKIT_VERSION,
+        };
+        if (input.client)
+            body.client = input.client;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        else {
+            body.install_id = await getInstallId();
+        }
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(await feedbackUrl(), {
+                method: "POST",
+                signal: ctrl.signal,
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                return {
+                    recorded: false,
+                    dropped: true,
+                    status: res.status,
+                    reason: dropReasonForStatus(res.status),
+                };
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        // Silent failure is the contract: no retry, no log, no throw. The reason
+        // is for the caller's result only — nothing is sent about it.
+        return { recorded: false, dropped: true, reason: "network" };
+    }
+    return { recorded: true };
+}

package/dist/{lib → core}/format.d.ts

@@ -1,4 +1,3 @@
-export declare function useColor(): boolean;
 export declare const c: {
     bold: (s: string) => string;
     dim: (s: string) => string;

package/dist/{lib → core}/format.js

@@ -10,7 +10,7 @@ const ANSI = {
     // Summer brand orange (matches banner.ts mid gradient)
     brand: "\x1b[38;2;255;143;23m",
 };
-export function useColor() {
+function useColor() {
     if (process.env.NO_COLOR)
         return false;
     if (process.env.FORCE_COLOR)

package/dist/core/headless/connection.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-project routing layer — shared contract types.
+ *
+ * A ProjectConnection is a uniform handle to "whatever process currently
+ * serves this project": either the live editor (today's HTTP transport,
+ * unchanged) or a headless worker (TCP newline-delimited JSON).
+ *
+ * This module is deliberately self-contained: nothing under src/core/headless/ is
+ * imported by the existing MCP/CLI code paths except behind the opt-in env
+ * flag SUMMER_HEADLESS_ROUTING=1 (see src/mcp/server.ts getClient and
+ * ./mcp-routing.ts). See docs/HEADLESS_ROUTING.md for the full
+ * contract this implements.
+ */
+export type ProjectConnectionKind = "editor" | "worker";
+/** Stage that failed, for structured timeout/transport errors. */
+export type HeadlessStage = "connect" | "auth" | "op" | "spawn";
+/**
+ * Timeout (and stage-tagged failure) error for the headless layer. `stage`
+ * names exactly which step gave up, so callers and logs can distinguish
+ * "could not reach the worker" from "the worker went quiet mid-import".
+ * NEVER put tokens in these messages — they surface verbatim in tool results.
+ */
+export declare class HeadlessTimeoutError extends Error {
+    readonly stage: HeadlessStage;
+    constructor(stage: HeadlessStage, message: string);
+}
+/** Read a positive-integer env override with a sane default. */
+export declare function envMs(name: string, fallback: number, env?: NodeJS.ProcessEnv): number;
+/** Ops that may legitimately run for minutes (first import, game boot). */
+export declare const LONG_RUNNING_OPS: ReadonlySet<string>;
+/** Ops that MUTATE project or process state. When one of these times out the
+ *  connection is QUARANTINED (destroyed + evicted via credentialsChanged)
+ *  because the mutation's outcome is UNKNOWN and a blind retry could
+ *  double-apply. Read-only ops that time out leave the connection usable. */
+export declare const MUTATING_OPS: ReadonlySet<string>;
+/**
+ * Remove secret material from any string that can reach an error message or
+ * log line. Applied to worker-supplied error text and spawn stderr tails —
+ * defense in depth on top of "the raw token never crosses the wire" (v1.1
+ * mutual auth) and "this module never interpolates tokens itself".
+ */
+export declare function scrubSecrets(text: string, secrets: ReadonlyArray<string | undefined>): string;
+/**
+ * Error for an op the WORKER answered with ok:false. `code` is the leading
+ * snake_case classifier when the worker sent a structured error (e.g.
+ * "sha256_mismatch: content changed since read", "already_exists",
+ * "needs_display"), so guard failures are distinguishable from generic
+ * transport throws.
+ */
+export declare class WorkerOpError extends Error {
+    readonly code?: string;
+    constructor(message: string);
+}
+export interface CallOptions {
+    /** Client-side INACTIVITY budget for this op: the timer restarts on every
+     *  progress line, so a chatty long import stays alive while a silent hang
+     *  still fails. Defaults: SUMMER_WORKER_OP_TIMEOUT_MS (30s) for normal ops,
+     *  SUMMER_WORKER_LONG_OP_TIMEOUT_MS (300s) for LONG_RUNNING_OPS. */
+    timeoutMs?: number;
+    /** Interim progress lines ({"id","event":"progress","progress"}) for this
+     *  request are surfaced here. Editor connections never emit progress. */
+    onProgress?: (progress: unknown) => void;
+}
+/**
+ * Uniform per-project backend handle.
+ *
+ * `call(op, params)` uses the WORKER op vocabulary as the canonical surface:
+ *   ping, status, import, fs.list, fs.read, fs.write, uid.resolve,
+ *   scene.read, game.run, game.stop, game.logs, game.screenshot
+ * EditorConnection adapts that vocabulary onto the existing EngineApiClient;
+ * WorkerConnection speaks it natively over TCP.
+ */
+export interface ProjectConnection {
+    readonly kind: ProjectConnectionKind;
+    /** Canonical absolute project path this connection serves. */
+    readonly projectPath: string;
+    call(op: string, params?: Record<string, unknown>, options?: CallOptions): Promise<unknown>;
+    /** True while the underlying transport is usable. A dropped worker socket
+     *  flips this to false permanently — reconnect-on-drop is NOT attempted;
+     *  callers re-resolve via resolveProjectConnection instead. */
+    isAlive(): boolean;
+    close(): void;
+}
+/** Ops the headless worker implements (mirror of the worker agent's brief). */
+export declare const WORKER_OPS: readonly ["ping", "status", "import", "fs.list", "fs.read", "fs.write", "uid.resolve", "scene.read", "game.run", "game.stop", "game.logs", "game.screenshot"];
+export type WorkerOp = (typeof WORKER_OPS)[number];

package/dist/core/headless/connection.js

@@ -0,0 +1,97 @@
+/**
+ * Per-project routing layer — shared contract types.
+ *
+ * A ProjectConnection is a uniform handle to "whatever process currently
+ * serves this project": either the live editor (today's HTTP transport,
+ * unchanged) or a headless worker (TCP newline-delimited JSON).
+ *
+ * This module is deliberately self-contained: nothing under src/core/headless/ is
+ * imported by the existing MCP/CLI code paths except behind the opt-in env
+ * flag SUMMER_HEADLESS_ROUTING=1 (see src/mcp/server.ts getClient and
+ * ./mcp-routing.ts). See docs/HEADLESS_ROUTING.md for the full
+ * contract this implements.
+ */
+/**
+ * Timeout (and stage-tagged failure) error for the headless layer. `stage`
+ * names exactly which step gave up, so callers and logs can distinguish
+ * "could not reach the worker" from "the worker went quiet mid-import".
+ * NEVER put tokens in these messages — they surface verbatim in tool results.
+ */
+export class HeadlessTimeoutError extends Error {
+    stage;
+    constructor(stage, message) {
+        super(`[headless:${stage}] ${message}`);
+        this.name = "HeadlessTimeoutError";
+        this.stage = stage;
+    }
+}
+/** Read a positive-integer env override with a sane default. */
+export function envMs(name, fallback, env = process.env) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+/** Ops that may legitimately run for minutes (first import, game boot). */
+export const LONG_RUNNING_OPS = new Set([
+    "import",
+    "game.run",
+]);
+/** Ops that MUTATE project or process state. When one of these times out the
+ *  connection is QUARANTINED (destroyed + evicted via credentialsChanged)
+ *  because the mutation's outcome is UNKNOWN and a blind retry could
+ *  double-apply. Read-only ops that time out leave the connection usable. */
+export const MUTATING_OPS = new Set([
+    "import",
+    "fs.write",
+    "game.run",
+    "game.stop",
+]);
+/**
+ * Remove secret material from any string that can reach an error message or
+ * log line. Applied to worker-supplied error text and spawn stderr tails —
+ * defense in depth on top of "the raw token never crosses the wire" (v1.1
+ * mutual auth) and "this module never interpolates tokens itself".
+ */
+export function scrubSecrets(text, secrets) {
+    let scrubbed = text;
+    for (const secret of secrets) {
+        if (secret && secret.length > 0) {
+            scrubbed = scrubbed.split(secret).join("[redacted]");
+        }
+    }
+    return scrubbed;
+}
+/**
+ * Error for an op the WORKER answered with ok:false. `code` is the leading
+ * snake_case classifier when the worker sent a structured error (e.g.
+ * "sha256_mismatch: content changed since read", "already_exists",
+ * "needs_display"), so guard failures are distinguishable from generic
+ * transport throws.
+ */
+export class WorkerOpError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = "WorkerOpError";
+        const match = /^([a-z][a-z0-9_]*)(?::|$)/.exec(message);
+        if (match)
+            this.code = match[1];
+    }
+}
+/** Ops the headless worker implements (mirror of the worker agent's brief). */
+export const WORKER_OPS = [
+    "ping",
+    "status",
+    "import",
+    "fs.list",
+    "fs.read",
+    "fs.write",
+    "uid.resolve",
+    "scene.read",
+    "game.run",
+    "game.stop",
+    "game.logs",
+    "game.screenshot",
+];

package/dist/core/headless/editor-connection.d.ts

@@ -0,0 +1,26 @@
+import type { EngineApiClient } from "../api-client.js";
+import type { CallOptions, ProjectConnection } from "./connection.js";
+/**
+ * Adapter that presents the EXISTING editor transport (EngineApiClient over
+ * local HTTP — untouched) through the uniform ProjectConnection surface.
+ *
+ * The canonical `call()` vocabulary is the WORKER op set; this adapter maps
+ * each worker op onto the editor method that answers the same question. Ops
+ * with no editor equivalent throw a clean, actionable error — they are never
+ * silently faked.
+ *
+ * The raw client stays reachable via `client` so callers that need the full
+ * editor surface (all ~22 EngineApiClient methods, identity binding, the
+ * async op lifecycle) can keep using it directly. The MCP flag-wiring does
+ * exactly that: when resolution picks the editor, the existing code path is
+ * used unchanged and this adapter is not even in the loop.
+ */
+export declare class EditorConnection implements ProjectConnection {
+    readonly kind: "editor";
+    readonly projectPath: string;
+    readonly client: EngineApiClient;
+    constructor(client: EngineApiClient, projectPath: string);
+    isAlive(): boolean;
+    close(): void;
+    call(op: string, params?: Record<string, unknown>, _options?: CallOptions): Promise<unknown>;
+}

package/dist/core/headless/editor-connection.js

@@ -0,0 +1,81 @@
+/**
+ * Adapter that presents the EXISTING editor transport (EngineApiClient over
+ * local HTTP — untouched) through the uniform ProjectConnection surface.
+ *
+ * The canonical `call()` vocabulary is the WORKER op set; this adapter maps
+ * each worker op onto the editor method that answers the same question. Ops
+ * with no editor equivalent throw a clean, actionable error — they are never
+ * silently faked.
+ *
+ * The raw client stays reachable via `client` so callers that need the full
+ * editor surface (all ~22 EngineApiClient methods, identity binding, the
+ * async op lifecycle) can keep using it directly. The MCP flag-wiring does
+ * exactly that: when resolution picks the editor, the existing code path is
+ * used unchanged and this adapter is not even in the loop.
+ */
+export class EditorConnection {
+    kind = "editor";
+    projectPath;
+    client;
+    constructor(client, projectPath) {
+        this.client = client;
+        this.projectPath = projectPath;
+    }
+    isAlive() {
+        // The HTTP transport is connectionless; liveness is checked per-request
+        // by the existing credential-drift logic in the client/getClient layer.
+        return true;
+    }
+    close() {
+        // Nothing to tear down — the HTTP client holds no socket.
+    }
+    async call(op, params = {}, _options = {}) {
+        switch (op) {
+            case "ping":
+            case "status":
+                return this.client.health();
+            case "import":
+                // The editor imports continuously via its filesystem scanner; there is
+                // nothing to trigger. Honest no-op with provenance.
+                return { ok: true, mode: "editor", note: "The editor imports assets continuously; no explicit import step exists on this transport." };
+            case "fs.list":
+                return this.client.getFsTree(typeof params.root === "string" ? params.root : undefined, typeof params.limit === "number" ? params.limit : undefined);
+            case "fs.read":
+                return this.client.readFile(String(params.path ?? ""), typeof params.maxBytes === "number" ? params.maxBytes : undefined);
+            case "fs.write":
+                return this.client.executeIdentityBoundOps([
+                    {
+                        op: "WriteFile",
+                        path: String(params.path ?? ""),
+                        content: String(params.content ?? ""),
+                        ...(typeof params.expectedSha256 === "string"
+                            ? { expectedSha256: params.expectedSha256 }
+                            : {}),
+                        ...(params.mustNotExist === true ? { mustNotExist: true } : {}),
+                    },
+                ]);
+            case "scene.read":
+                return this.client.getSceneState(typeof params.scenePath === "string" ? params.scenePath : undefined, {
+                    depth: typeof params.depth === "number" ? params.depth : undefined,
+                    limit: typeof params.limit === "number" ? params.limit : undefined,
+                });
+            case "game.run":
+                return this.client.play(typeof params.scene === "string" ? params.scene : undefined);
+            case "game.stop":
+                return this.client.stop();
+            case "game.logs": {
+                const opInput = { op: "GetConsoleOutput" };
+                if (typeof params.maxLines === "number")
+                    opInput.max_lines = params.maxLines;
+                if (typeof params.filter === "string")
+                    opInput.filter = params.filter;
+                return this.client.executeOps([opInput]);
+            }
+            case "game.screenshot":
+                return this.client.gameSnapshot();
+            case "uid.resolve":
+            default:
+                throw new Error(`Op "${op}" has no editor-transport mapping. Use the EngineApiClient directly (EditorConnection.client) or route to a headless worker.`);
+        }
+    }
+}

package/dist/core/headless/mcp-routing.d.ts

@@ -0,0 +1,38 @@
+import { EngineApiClient } from "../api-client.js";
+import { type EngineSelection } from "../engine.js";
+import { resolveProjectConnection } from "./resolve.js";
+/**
+ * The ONLY hook the existing MCP server calls into this module — and only
+ * when SUMMER_HEADLESS_ROUTING=1 (see src/mcp/server.ts getClient, which
+ * dynamic-imports this file so the flag-off path never even loads it).
+ *
+ * Behavior contract:
+ *   - returns null whenever the existing code path should handle the call:
+ *       * no project context on the session (no projectPath, cwd not inside
+ *         a project) — legacy single-editor discovery stays in charge
+ *       * a live EDITOR has the project open — the existing EngineApiClient
+ *         path (caching, credential-drift, identity binding) serves it
+ *         EXACTLY as with the flag off
+ *   - returns a WorkerEngineClient (cast to EngineApiClient — it implements
+ *     the full public method surface) only when no editor has the project,
+ *     connecting to a live registered worker or spawning one on demand.
+ *   - editor-resolution errors that do NOT positively mean "no editor has
+ *     this project" (ambiguity, identity change, unresponsive editor) are
+ *     RETHROWN — a worker must never write while an editor's presence is
+ *     uncertain.
+ *   - SINGLE-FLIGHT per project: concurrent tool calls share one in-flight
+ *     resolution, so a burst of first calls can never spawn more than one
+ *     worker or open more than one connection. A superseded cached
+ *     connection is always closed, never orphaned.
+ */
+interface RoutingDeps {
+    /** Full resolution (editor -> worker -> spawn). Test seam. */
+    resolve: typeof resolveProjectConnection;
+    /** Cheap "does a live editor have this project?" probe used to hand a
+     *  cached worker back to the editor path. Test seam. */
+    editorProbe: (projectPath: string) => Promise<boolean>;
+}
+export declare function getHeadlessRoutedClient(selection?: EngineSelection, deps?: Partial<RoutingDeps>): Promise<EngineApiClient | null>;
+/** Test-only: drop the cached worker client and any in-flight routes. */
+export declare function resetHeadlessRouting(): void;
+export {};

package/dist/core/headless/mcp-routing.js

@@ -0,0 +1,83 @@
+import { EngineApiClient } from "../api-client.js";
+import { findProjectRoot } from "../engine.js";
+import { isNoEditorForProjectError, resolveProjectConnection } from "./resolve.js";
+import { normalizeProjectPath } from "./registry.js";
+import { WorkerEngineClient } from "./worker-engine-client.js";
+async function defaultEditorProbe(projectPath) {
+    try {
+        await EngineApiClient.connect({ projectPath });
+        return true;
+    }
+    catch (error) {
+        if (isNoEditorForProjectError(error))
+            return false;
+        // Ambiguity / identity / unresponsive-editor: presence uncertain — the
+        // caller must NOT keep serving from a worker. Propagate.
+        throw error;
+    }
+}
+const defaultDeps = {
+    resolve: resolveProjectConnection,
+    editorProbe: defaultEditorProbe,
+};
+let cachedWorker = null;
+// Single-flight: normalized project path -> in-flight routing decision.
+const inFlightRoutes = new Map();
+async function projectPathFromSelection(selection) {
+    if (selection?.projectPath) {
+        return (await findProjectRoot(selection.projectPath)) ?? null;
+    }
+    if (selection?.cwd) {
+        return findProjectRoot(selection.cwd);
+    }
+    return null;
+}
+function dropCachedWorker() {
+    cachedWorker?.client.close();
+    cachedWorker = null;
+}
+export async function getHeadlessRoutedClient(selection, deps = {}) {
+    const { resolve, editorProbe } = { ...defaultDeps, ...deps };
+    const projectPath = await projectPathFromSelection(selection);
+    if (!projectPath)
+        return null;
+    const key = normalizeProjectPath(projectPath);
+    const inFlight = inFlightRoutes.get(key);
+    if (inFlight)
+        return inFlight;
+    const route = (async () => {
+        // Editor beats worker on EVERY call, not just at first resolution: if an
+        // editor opened the project after a worker started serving it, hand the
+        // session back to the untouched editor path (and close the worker
+        // client — never orphan it). The probe is cheap (instance registry read
+        // + one short-timeout health GET).
+        if (cachedWorker && cachedWorker.key === key && cachedWorker.client.isAlive()) {
+            if (await editorProbe(projectPath)) {
+                dropCachedWorker();
+                return null;
+            }
+            return cachedWorker.client;
+        }
+        // Cached client is for another project or dead — close before replacing.
+        dropCachedWorker();
+        const connection = await resolve(projectPath);
+        if (connection.kind === "editor") {
+            // Discard the probe connection (HTTP, nothing to tear down) and let
+            // the untouched existing path do what it does today.
+            connection.close();
+            return null;
+        }
+        const client = new WorkerEngineClient(connection);
+        cachedWorker = { key, client };
+        return client;
+    })().finally(() => {
+        inFlightRoutes.delete(key);
+    });
+    inFlightRoutes.set(key, route);
+    return route;
+}
+/** Test-only: drop the cached worker client and any in-flight routes. */
+export function resetHeadlessRouting() {
+    dropCachedWorker();
+    inFlightRoutes.clear();
+}