summer-engine 2.8.2 → 3.0.0

package/dist/core/headless/spawn.js

@@ -0,0 +1,205 @@
+import { spawn as nodeSpawn } from "child_process";
+import { closeSync, existsSync, fstatSync, openSync, readSync } from "fs";
+import { mkdir } from "fs/promises";
+import { platform, tmpdir } from "os";
+import { join, resolve } from "path";
+import { findEngineBinary as findInstalledEngineBinary } from "../engine-install.js";
+import { sleep } from "../util/sleep.js";
+import { envMs, HeadlessTimeoutError, scrubSecrets } from "./connection.js";
+import { findWorkerEntry, normalizeProjectPath, } from "./registry.js";
+/**
+ * On-demand worker spawning: <engine binary> --summer-worker --path <project>
+ * then poll the process registry until the worker registers itself.
+ *
+ * Process model (zombie hygiene):
+ *   - The worker is spawned DETACHED (own process group) and unref()ed, so it
+ *     deliberately outlives this CLI process — an MCP session ending must not
+ *     kill a worker another session may be using. It stays discoverable via
+ *     the registry; dead entries are pruned by pid liveness on every read.
+ *   - While this process is alive, node's child_process reaps the child on
+ *     exit (no zombie), and the exit is used to fail fast (see below).
+ *   - stderr goes to a per-spawn log FILE (never a pipe): a pipe would EPIPE
+ *     the worker if the CLI exits first. On exit-before-ready the log tail is
+ *     read back and surfaced in the error.
+ *   - argv array only — no shell, no interpolation.
+ *
+ * Engine-binary discovery: SUMMER_ENGINE_BIN (this layer's documented
+ * override — set-but-missing means "no binary", never a silent fallback),
+ * then the canonical resolver in src/core/engine-install.ts (its own
+ * SUMMER_ENGINE_BINARY override + the platform install locations shared with
+ * `summer install` / `summer run` / `summer doctor`). No install-path list
+ * is duplicated here.
+ *
+ * Single-flight: concurrent spawn requests for the SAME project share one
+ * spawn (module-level in-flight promise map keyed by canonical project
+ * path). The first caller's options win for the shared attempt.
+ */
+const STDERR_TAIL_BYTES = 4096;
+export function findEngineBinary(env = process.env) {
+    const override = env.SUMMER_ENGINE_BIN?.trim();
+    if (override)
+        return existsSync(override) ? override : null;
+    return findInstalledEngineBinary(platform(), env);
+}
+/** Read ONLY the last STDERR_TAIL_BYTES of a file (open + seek — never the
+ *  whole file, which could be huge for a long-lived chatty worker). */
+function readFileTail(path) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, STDERR_TAIL_BYTES);
+            if (length === 0)
+                return "";
+            const buffer = Buffer.alloc(length);
+            readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString("utf-8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return "";
+    }
+}
+function defaultLaunch(binary, args) {
+    // stderr -> file (see module doc). Directory creation (mode 0700) is done
+    // in spawnWorker before the launcher runs; the log itself is 0600 — worker
+    // stderr can quote project content and must not be world-readable.
+    const logPath = join(workerLogDir(), `worker-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.log`);
+    const fd = openSync(logPath, "a", 0o600);
+    let exit = null;
+    let launchError = "";
+    // The child inherits process.env wholesale, which already carries
+    // SUMMER_CACHE_DIR when set — so the spawned worker writes its registry
+    // entry to the same overridden cache dir this CLI polls. (An earlier
+    // explicit re-assignment of the same value was a no-op.)
+    const child = nodeSpawn(binary, args, {
+        detached: true,
+        // detached on Windows opens a new console window for the child unless
+        // hidden; a no-op elsewhere.
+        windowsHide: true,
+        stdio: ["ignore", "ignore", fd],
+        env: process.env,
+    });
+    closeSync(fd);
+    child.once("exit", (code, signal) => {
+        exit = { code, signal };
+    });
+    // A spawn failure (ENOENT, EACCES) arrives as an 'error' event, not an
+    // exit — without a listener it would crash the process. Treat it as an
+    // immediate exit whose "stderr" is the launch error.
+    child.once("error", (error) => {
+        launchError = error.message;
+        exit = exit ?? { code: null, signal: null };
+    });
+    child.unref();
+    return {
+        exit: () => exit,
+        stderrTail: () => (launchError ? launchError : readFileTail(logPath)),
+        kill: () => {
+            if (exit)
+                return;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                return; // already gone
+            }
+            const escalate = setTimeout(() => {
+                if (!exit) {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                }
+            }, 5_000);
+            // Never keep the CLI alive just to escalate a kill.
+            escalate.unref();
+        },
+    };
+}
+function workerLogDir() {
+    return join(tmpdir(), "summer-engine", "worker-logs");
+}
+// Single-flight: canonical project path -> in-flight spawn attempt.
+const inFlightSpawns = new Map();
+/**
+ * Spawn a headless worker for `projectPath` and wait for its registry entry.
+ * Resolves with the live entry; rejects on missing binary, early exit
+ * (surfacing the exit code and a stderr tail), or registration timeout.
+ * Concurrent calls for the same project share ONE spawn.
+ */
+export function spawnWorker(projectPath, options = {}) {
+    const target = resolve(projectPath);
+    const flightKey = normalizeProjectPath(projectPath);
+    const existing = inFlightSpawns.get(flightKey);
+    if (existing)
+        return existing;
+    const attempt = spawnWorkerOnce(target, options).finally(() => {
+        inFlightSpawns.delete(flightKey);
+    });
+    inFlightSpawns.set(flightKey, attempt);
+    return attempt;
+}
+async function spawnWorkerOnce(target, options) {
+    const binary = options.binary ?? findEngineBinary();
+    if (!binary) {
+        throw new Error("Summer Engine binary not found (checked the standard install locations and SUMMER_ENGINE_BIN). " +
+            "Install it first: npx summer-engine install");
+    }
+    // Baseline snapshot (stale-entry defense): a registry entry that already
+    // exists for this project — even one whose pid probe still answers — must
+    // NEVER satisfy the post-spawn poll. Only an entry that differs from the
+    // baseline (new pid/port/token or a newer started_ts) counts as the worker
+    // we just launched. This closes the "connect failed to a stale live-pid
+    // entry, spawn, then immediately re-adopt the same stale entry" loop.
+    const baseline = await findWorkerEntry(target, options.registry);
+    const launch = options.launch ?? defaultLaunch;
+    if (launch === defaultLaunch) {
+        await mkdir(workerLogDir(), { recursive: true, mode: 0o700 });
+    }
+    const handle = launch(binary, ["--summer-worker", "--path", target]);
+    const timeoutMs = options.timeoutMs ?? envMs("SUMMER_WORKER_SPAWN_TIMEOUT_MS", 120_000);
+    const pollIntervalMs = options.pollIntervalMs ?? 500;
+    const startedAt = Date.now();
+    const isFreshEntry = (entry) => {
+        if (!baseline)
+            return true;
+        return (entry.pid !== baseline.pid ||
+            entry.port !== baseline.port ||
+            entry.token !== baseline.token ||
+            (entry.startedTs ?? 0) > (baseline.startedTs ?? 0));
+    };
+    while (Date.now() - startedAt < timeoutMs) {
+        const entry = await findWorkerEntry(target, options.registry);
+        if (entry && isFreshEntry(entry))
+            return entry;
+        // Registry checked first, exit second: a worker that registers and then
+        // exits still surfaces its (now dead) entry to the pruning reader, while
+        // a crash-before-register fails fast here instead of burning the budget.
+        const exit = handle.exit();
+        if (exit) {
+            // Scrub any token material out of the surfaced tail (defense in depth;
+            // the tail is worker stderr and could quote its own environment).
+            const tail = scrubSecrets(handle.stderrTail(), [baseline?.token]).trim();
+            throw new Error(`Headless worker for ${target} exited before registering ` +
+                `(code ${exit.code ?? "null"}${exit.signal ? `, signal ${exit.signal}` : ""}).` +
+                (tail ? `\nWorker stderr (tail):\n${tail}` : ""));
+        }
+        options.onProgress?.({
+            phase: "waiting_for_worker_registration",
+            elapsedMs: Date.now() - startedAt,
+        });
+        await sleep(pollIntervalMs);
+    }
+    // Abandoning the attempt: never leak the just-spawned child. Kill it so a
+    // worker nobody adopted (and whose registry entry never appeared) does not
+    // run forever.
+    handle.kill?.();
+    throw new HeadlessTimeoutError("spawn", `Spawned a headless worker for ${target}, but it did not register within ${Math.round(timeoutMs / 1000)}s (the spawned process has been terminated). First imports of large projects can be ` +
+        "slow — raise SUMMER_WORKER_SPAWN_TIMEOUT_MS and retry, or open the project in the Summer editor instead.");
+}

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

@@ -0,0 +1,96 @@
+import { type CallOptions, type ProjectConnection } from "./connection.js";
+/**
+ * TCP client for a headless Summer worker — protocol v1.1.
+ *
+ * Wire protocol (pinned v1.1; the worker implements the same):
+ *   - connect to 127.0.0.1:<port>
+ *   - WORKER sends first (within 3s):
+ *       {"hello":{"pid":<int>,"nonce":"<32 hex>","proof":"<hex sha256(nonce + ':' + token)>"}}
+ *   - client verifies `proof` against the REGISTRY token (proves the worker
+ *     holds the token without it crossing the wire) AND `hello.pid` against
+ *     the REGISTRY pid (pid-reuse / port-squat detection), then answers:
+ *       {"auth":"<hex sha256('client:' + nonce + ':' + token)>"}
+ *     The raw token NEVER crosses the wire in either direction.
+ *   - then requests:        {"id": "...", "op": "...", "params": {...}}
+ *   - responses:            {"id": "...", "ok": true, "result": ...}
+ *                        or {"id": "...", "ok": false, "error": "..."}
+ *   - interim progress:     {"id": "...", "event": "progress", "progress": ...}
+ * All lines are newline-delimited JSON, one document per \n. Framing is done
+ * on BYTES (split on 0x0a before utf-8 decoding) so a multibyte codepoint
+ * split across TCP chunks is never corrupted. An un-terminated frame is
+ * capped at 8MiB — beyond that the connection is destroyed with a clear
+ * error.
+ *
+ * Timeouts (env-overridable; every timeout is a HeadlessTimeoutError naming
+ * its stage):
+ *   - connect: SUMMER_WORKER_CONNECT_TIMEOUT_MS (default 5s)   stage "connect"
+ *   - hello:   SUMMER_WORKER_HELLO_TIMEOUT_MS (default 3s)     stage "auth"
+ *   - per-op INACTIVITY: SUMMER_WORKER_OP_TIMEOUT_MS (30s) or
+ *     SUMMER_WORKER_LONG_OP_TIMEOUT_MS (300s) for LONG_RUNNING_OPS. Progress
+ *     lines RESTART the timer; the timer only STARTS once the request has
+ *     flushed to the socket (write backpressure never eats the budget).
+ *
+ * Quarantine: when a MUTATING op (MUTATING_OPS) times out, the mutation's
+ * outcome is UNKNOWN — the connection is destroyed and reports drift via
+ * credentialsChanged()/isAlive() so caches evict it. The surfaced error says
+ * so explicitly; callers must inspect the target before retrying. Read-only
+ * timeouts leave the connection usable.
+ *
+ * Security: no token material ever appears in an error, log line, or thrown
+ * value. Auth-phase failures surface FIXED messages (never worker-supplied
+ * text); op errors from the worker are scrubbed of the token as defense in
+ * depth.
+ *
+ * Failure model: a dropped socket fails ALL pending calls with a clean error
+ * and marks the connection permanently dead. No transparent reconnect — the
+ * worker may have died mid-mutation and this client sends no idempotency
+ * keys, so a blind retry could double-apply (same reasoning as withEngine's
+ * narrow retry policy). Callers evict and re-resolve.
+ */
+export declare const MAX_FRAME_BYTES: number;
+export interface WorkerConnectOptions {
+    host?: string;
+    port: number;
+    token: string;
+    /** Registry pid for this worker — verified against hello.pid. */
+    pid: number;
+    projectPath: string;
+    /** TCP connect budget. Default: SUMMER_WORKER_CONNECT_TIMEOUT_MS or 5s. */
+    connectTimeoutMs?: number;
+    /** Budget for the worker's hello line.
+     *  Default: SUMMER_WORKER_HELLO_TIMEOUT_MS or 3s. */
+    helloTimeoutMs?: number;
+    /** Verify the channel with a `ping` op after the handshake. Default true. */
+    verifyWithPing?: boolean;
+    /** Un-terminated frame cap in bytes (test seam). Default MAX_FRAME_BYTES. */
+    maxFrameBytes?: number;
+}
+/** v1.1: what the WORKER must present in hello.proof. */
+export declare function helloProof(nonce: string, token: string): string;
+/** v1.1: what the CLIENT answers with in the auth line. */
+export declare function clientAuthProof(nonce: string, token: string): string;
+export declare function defaultOpTimeoutMs(op: string): number;
+export declare class WorkerConnection implements ProjectConnection {
+    readonly kind: "worker";
+    readonly projectPath: string;
+    private socket;
+    private buffer;
+    private nextId;
+    private pending;
+    private alive;
+    private closeReason;
+    private readonly token;
+    private readonly maxFrameBytes;
+    private constructor();
+    static connect(options: WorkerConnectOptions): Promise<WorkerConnection>;
+    isAlive(): boolean;
+    call(op: string, params?: Record<string, unknown>, options?: CallOptions): Promise<unknown>;
+    close(): void;
+    private scrub;
+    private onData;
+    /** Byte-exact framing: split on 0x0a BEFORE utf-8 decoding, so a multibyte
+     *  codepoint split across TCP chunks is reassembled correctly. */
+    private drainFrames;
+    private dispatch;
+    private failAll;
+}

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

@@ -0,0 +1,353 @@
+import { createHash } from "node:crypto";
+import { asRecord } from "../util/json.js";
+import { createConnection } from "node:net";
+import { envMs, HeadlessTimeoutError, LONG_RUNNING_OPS, MUTATING_OPS, scrubSecrets, WorkerOpError, } from "./connection.js";
+/**
+ * TCP client for a headless Summer worker — protocol v1.1.
+ *
+ * Wire protocol (pinned v1.1; the worker implements the same):
+ *   - connect to 127.0.0.1:<port>
+ *   - WORKER sends first (within 3s):
+ *       {"hello":{"pid":<int>,"nonce":"<32 hex>","proof":"<hex sha256(nonce + ':' + token)>"}}
+ *   - client verifies `proof` against the REGISTRY token (proves the worker
+ *     holds the token without it crossing the wire) AND `hello.pid` against
+ *     the REGISTRY pid (pid-reuse / port-squat detection), then answers:
+ *       {"auth":"<hex sha256('client:' + nonce + ':' + token)>"}
+ *     The raw token NEVER crosses the wire in either direction.
+ *   - then requests:        {"id": "...", "op": "...", "params": {...}}
+ *   - responses:            {"id": "...", "ok": true, "result": ...}
+ *                        or {"id": "...", "ok": false, "error": "..."}
+ *   - interim progress:     {"id": "...", "event": "progress", "progress": ...}
+ * All lines are newline-delimited JSON, one document per \n. Framing is done
+ * on BYTES (split on 0x0a before utf-8 decoding) so a multibyte codepoint
+ * split across TCP chunks is never corrupted. An un-terminated frame is
+ * capped at 8MiB — beyond that the connection is destroyed with a clear
+ * error.
+ *
+ * Timeouts (env-overridable; every timeout is a HeadlessTimeoutError naming
+ * its stage):
+ *   - connect: SUMMER_WORKER_CONNECT_TIMEOUT_MS (default 5s)   stage "connect"
+ *   - hello:   SUMMER_WORKER_HELLO_TIMEOUT_MS (default 3s)     stage "auth"
+ *   - per-op INACTIVITY: SUMMER_WORKER_OP_TIMEOUT_MS (30s) or
+ *     SUMMER_WORKER_LONG_OP_TIMEOUT_MS (300s) for LONG_RUNNING_OPS. Progress
+ *     lines RESTART the timer; the timer only STARTS once the request has
+ *     flushed to the socket (write backpressure never eats the budget).
+ *
+ * Quarantine: when a MUTATING op (MUTATING_OPS) times out, the mutation's
+ * outcome is UNKNOWN — the connection is destroyed and reports drift via
+ * credentialsChanged()/isAlive() so caches evict it. The surfaced error says
+ * so explicitly; callers must inspect the target before retrying. Read-only
+ * timeouts leave the connection usable.
+ *
+ * Security: no token material ever appears in an error, log line, or thrown
+ * value. Auth-phase failures surface FIXED messages (never worker-supplied
+ * text); op errors from the worker are scrubbed of the token as defense in
+ * depth.
+ *
+ * Failure model: a dropped socket fails ALL pending calls with a clean error
+ * and marks the connection permanently dead. No transparent reconnect — the
+ * worker may have died mid-mutation and this client sends no idempotency
+ * keys, so a blind retry could double-apply (same reasoning as withEngine's
+ * narrow retry policy). Callers evict and re-resolve.
+ */
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_HELLO_BYTES = 64 * 1024;
+const NEWLINE = 0x0a;
+function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf-8").digest("hex");
+}
+/** v1.1: what the WORKER must present in hello.proof. */
+export function helloProof(nonce, token) {
+    return sha256Hex(`${nonce}:${token}`);
+}
+/** v1.1: what the CLIENT answers with in the auth line. */
+export function clientAuthProof(nonce, token) {
+    return sha256Hex(`client:${nonce}:${token}`);
+}
+export function defaultOpTimeoutMs(op) {
+    return LONG_RUNNING_OPS.has(op)
+        ? envMs("SUMMER_WORKER_LONG_OP_TIMEOUT_MS", 300_000)
+        : envMs("SUMMER_WORKER_OP_TIMEOUT_MS", 30_000);
+}
+/** Read the first \n-terminated line off a raw socket (byte-exact; the
+ *  remainder after the newline is returned untouched for the connection's
+ *  frame buffer). Fixed error messages only — this runs pre-auth. */
+function readFirstLine(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = Buffer.alloc(0);
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            socket.destroy();
+            reject(error);
+        };
+        const onData = (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            const newline = buffer.indexOf(NEWLINE);
+            if (newline >= 0) {
+                const line = buffer.subarray(0, newline).toString("utf-8");
+                const rest = Buffer.from(buffer.subarray(newline + 1));
+                settled = true;
+                cleanup();
+                resolve({ line, rest });
+                return;
+            }
+            if (buffer.length > MAX_HELLO_BYTES) {
+                fail(new HeadlessTimeoutError("auth", "Headless worker handshake failed: oversized hello frame."));
+            }
+        };
+        const onClose = () => fail(new HeadlessTimeoutError("auth", "Headless worker handshake failed: connection closed before hello."));
+        const timer = setTimeout(() => fail(new HeadlessTimeoutError("auth", `Headless worker handshake failed: no hello within ${timeoutMs}ms.`)), timeoutMs);
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.off("data", onData);
+            socket.off("close", onClose);
+            socket.off("error", onClose);
+        };
+        socket.on("data", onData);
+        socket.once("close", onClose);
+        socket.once("error", onClose);
+    });
+}
+export class WorkerConnection {
+    kind = "worker";
+    projectPath;
+    socket;
+    buffer;
+    // ID CONTRACT (pinned): request ids are POSITIVE JSON INTEGERS, monotonic
+    // per connection. String ids are coerced to -1 by the worker's engine-side
+    // String->int conversion and every op would time out.
+    nextId = 1;
+    pending = new Map();
+    alive = true;
+    closeReason = null;
+    token;
+    maxFrameBytes;
+    constructor(socket, projectPath, token, initialBuffer, maxFrameBytes) {
+        this.socket = socket;
+        this.projectPath = projectPath;
+        this.token = token;
+        this.buffer = initialBuffer;
+        this.maxFrameBytes = maxFrameBytes;
+        socket.on("data", (chunk) => this.onData(chunk));
+        socket.on("error", (error) => 
+        // error.message comes from the OS (ECONNRESET etc.); scrubbed anyway.
+        this.failAll(`Headless worker connection error: ${this.scrub(error.message)}`));
+        socket.on("close", () => this.failAll("Headless worker connection closed."));
+        // Process any bytes that arrived in the same chunk as the hello frame.
+        if (this.buffer.length > 0)
+            this.drainFrames();
+    }
+    static async connect(options) {
+        const host = options.host ?? "127.0.0.1";
+        const connectTimeoutMs = options.connectTimeoutMs ?? envMs("SUMMER_WORKER_CONNECT_TIMEOUT_MS", 5_000);
+        const helloTimeoutMs = options.helloTimeoutMs ?? envMs("SUMMER_WORKER_HELLO_TIMEOUT_MS", 3_000);
+        const socket = await new Promise((resolvePromise, rejectPromise) => {
+            const sock = createConnection({ host, port: options.port });
+            const timer = setTimeout(() => {
+                sock.destroy();
+                rejectPromise(new HeadlessTimeoutError("connect", `Timed out after ${connectTimeoutMs}ms connecting to headless worker at ${host}:${options.port}.`));
+            }, connectTimeoutMs);
+            sock.once("connect", () => {
+                clearTimeout(timer);
+                resolvePromise(sock);
+            });
+            sock.once("error", (error) => {
+                clearTimeout(timer);
+                rejectPromise(new HeadlessTimeoutError("connect", `Could not connect to headless worker at ${host}:${options.port}: ${scrubSecrets(error.message, [options.token])}`));
+            });
+        });
+        socket.setNoDelay(true);
+        // --- v1.1 mutual auth. FIXED messages only in this phase: nothing
+        // worker-supplied and no token material may reach an error string.
+        const authFail = (reason) => {
+            socket.destroy();
+            throw new HeadlessTimeoutError("auth", `Headless worker handshake failed at ${host}:${options.port}: ${reason} ` +
+                "(stale registry entry, pid reuse, or another process squatting the port).");
+        };
+        const { line, rest } = await readFirstLine(socket, helloTimeoutMs);
+        let hello = null;
+        try {
+            hello = asRecord(asRecord(JSON.parse(line))?.hello);
+        }
+        catch {
+            hello = null;
+        }
+        const nonce = typeof hello?.nonce === "string" ? hello.nonce : null;
+        const proof = typeof hello?.proof === "string" ? hello.proof : null;
+        const pid = typeof hello?.pid === "number" ? hello.pid : null;
+        if (!hello || nonce === null || proof === null || pid === null) {
+            authFail("malformed hello");
+        }
+        if (!/^[0-9a-f]{32}$/.test(nonce)) {
+            authFail("malformed hello nonce");
+        }
+        if (proof.toLowerCase() !== helloProof(nonce, options.token)) {
+            authFail("worker proof mismatch");
+        }
+        if (pid !== options.pid) {
+            authFail("worker pid mismatch");
+        }
+        socket.write(JSON.stringify({ auth: clientAuthProof(nonce, options.token) }) + "\n");
+        const connection = new WorkerConnection(socket, options.projectPath, options.token, rest, options.maxFrameBytes ?? MAX_FRAME_BYTES);
+        if (options.verifyWithPing !== false) {
+            try {
+                await connection.call("ping", {}, { timeoutMs: helloTimeoutMs });
+            }
+            catch {
+                connection.close();
+                // Fixed message — the ping failure detail could be worker-supplied.
+                throw new HeadlessTimeoutError("auth", `Headless worker at ${host}:${options.port} completed the handshake but did not answer ping ` +
+                    "(worker rejected the client auth or died during startup).");
+            }
+        }
+        return connection;
+    }
+    isAlive() {
+        return this.alive;
+    }
+    call(op, params = {}, options = {}) {
+        if (!this.alive) {
+            return Promise.reject(new Error(this.closeReason ??
+                "Headless worker connection is closed. Re-resolve the project connection and retry if safe."));
+        }
+        const id = this.nextId++;
+        const timeoutMs = options.timeoutMs ?? defaultOpTimeoutMs(op);
+        return new Promise((resolvePromise, rejectPromise) => {
+            const onTimeout = () => {
+                this.pending.delete(id);
+                if (MUTATING_OPS.has(op)) {
+                    // The mutation may or may not have applied — quarantine the whole
+                    // connection so nothing (including caller-side retries) can
+                    // silently reuse it and double-apply.
+                    rejectPromise(new HeadlessTimeoutError("op", `Mutating worker op "${op}" produced no response or progress for ${timeoutMs}ms ` +
+                        `(request ${id}). The mutation's outcome is UNKNOWN. This connection has been ` +
+                        "quarantined (closed) to block blind retries; re-resolve and INSPECT the target " +
+                        "before retrying."));
+                    this.failAll("Headless worker connection quarantined: a mutating op timed out with unknown outcome.");
+                    this.socket.destroy();
+                    return;
+                }
+                rejectPromise(new HeadlessTimeoutError("op", `Worker op "${op}" produced no response or progress for ${timeoutMs}ms ` +
+                    `(request ${id}). Its final state is unknown; inspect the target before retrying.`));
+            };
+            const entry = {
+                op,
+                resolve: resolvePromise,
+                reject: rejectPromise,
+                onProgress: options.onProgress,
+                timer: null,
+                restartTimer: () => {
+                    if (entry.timer)
+                        clearTimeout(entry.timer);
+                    entry.timer = setTimeout(onTimeout, timeoutMs);
+                },
+            };
+            this.pending.set(id, entry);
+            // The inactivity timer starts only once the request has actually
+            // FLUSHED to the socket — write backpressure must not eat the budget.
+            this.socket.write(JSON.stringify({ id, op, params }) + "\n", (error) => {
+                if (!this.pending.has(id))
+                    return; // already settled (drop/response)
+                if (error) {
+                    this.pending.delete(id);
+                    rejectPromise(new Error(`Headless worker request could not be sent: ${this.scrub(error.message)}. ` +
+                        "Nothing was submitted."));
+                    return;
+                }
+                entry.restartTimer();
+            });
+        });
+    }
+    close() {
+        this.failAll("Headless worker connection closed by client.");
+        this.socket.destroy();
+    }
+    scrub(text) {
+        return scrubSecrets(text, [this.token]);
+    }
+    onData(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this.drainFrames();
+    }
+    /** Byte-exact framing: split on 0x0a BEFORE utf-8 decoding, so a multibyte
+     *  codepoint split across TCP chunks is reassembled correctly. */
+    drainFrames() {
+        let newline;
+        while ((newline = this.buffer.indexOf(NEWLINE)) >= 0) {
+            const line = this.buffer.subarray(0, newline).toString("utf-8").trim();
+            this.buffer = Buffer.from(this.buffer.subarray(newline + 1));
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = asRecord(JSON.parse(line));
+            }
+            catch {
+                // A malformed line must not kill unrelated in-flight requests.
+                continue;
+            }
+            if (!message)
+                continue;
+            this.dispatch(message);
+        }
+        if (this.buffer.length > this.maxFrameBytes) {
+            this.failAll(`Headless worker sent an un-terminated frame larger than ${this.maxFrameBytes} bytes; ` +
+                "closing the connection.");
+            this.socket.destroy();
+        }
+    }
+    dispatch(message) {
+        const id = typeof message.id === "number" && Number.isInteger(message.id)
+            ? message.id
+            : null;
+        if (!id)
+            return;
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        if (message.event === "progress") {
+            // Liveness: progress restarts the inactivity timer, so a long op that
+            // keeps reporting never times out spuriously.
+            pending.restartTimer();
+            try {
+                pending.onProgress?.(message.progress);
+            }
+            catch {
+                // A progress observer must never break the request itself.
+            }
+            return;
+        }
+        this.pending.delete(id);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        if (message.ok === true) {
+            pending.resolve(message.result);
+        }
+        else {
+            const error = typeof message.error === "string" && message.error.length > 0
+                ? this.scrub(message.error)
+                : "Headless worker reported an unspecified error.";
+            // WorkerOpError carries a `.code` (sha256_mismatch / already_exists /
+            // needs_display / ...) when the worker sent a structured classifier,
+            // so guard failures are distinguishable from transport throws.
+            pending.reject(new WorkerOpError(error));
+        }
+    }
+    failAll(reason) {
+        if (!this.alive)
+            return;
+        this.alive = false;
+        this.closeReason = this.scrub(reason);
+        const failures = [...this.pending.values()];
+        this.pending.clear();
+        for (const pending of failures) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new Error(`${this.closeReason} The in-flight operation's final state is unknown; do not retry blindly.`));
+        }
+    }
+}