@hheei/pi-subagents 0.1.2 → 0.2.2

package/dist/runner.js

@@ -1,930 +0,0 @@
-import { timingSafeEqual } from "node:crypto";
-import { chmod, lstat, unlink } from "node:fs/promises";
-import { createConnection, createServer } from "node:net";
-import { abortError, errorMessage, toError, writeDiagnostic } from "./diagnostics.js";
-import { isRecord, PROTOCOL_VERSION } from "./domain.js";
-import { attachJsonLineReader, writeJsonLine } from "./json-lines.js";
-import { CANCEL_PAUSE_EVENT, CHILD_LIFECYCLE_EVENT, DEFAULT_MAX_BUFFERED_EVENTS, DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_PENDING_REQUESTS, eventFrame, failureResponse, isChildLifecyclePayload, isContactReportPayload, isHelloFrame, isPauseReportPayload, isRequestFrame, PAUSE_EVENT, RUNNER_EVENTS_DROPPED_EVENT, RUNNER_EXIT_EVENT, successResponse, WRITER_EXIT_EVENT, } from "./protocol.js";
-import { PiRpcAdapter, PiRpcTimeoutError } from "./rpc-adapter.js";
-import { isIdlePiState, shouldForwardPiEvent } from "./rpc-events.js";
-/** Bounded memory of finished request IDs, used to answer duplicate requests. */
-const MAX_RETIRED_REQUEST_IDS = 256;
-/** Unauthenticated connections accepted at once before new ones are refused. */
-const MAX_PENDING_HANDSHAKES = 16;
-/**
- * Starts the reconnectable runner endpoint for one Pi RPC child.
- *
- * The runner owns the child stdio, accepts exactly one authenticated controller
- * at a time, and stays alive across controller disconnects: only an explicit
- * `shutdown` request, the end of the Pi child, or process termination stops it.
- */
-export async function startRunner(options) {
-    const runner = new Runner(options);
-    const readiness = await runner.start();
-    return {
-        endpoint: runner.endpoint,
-        identity: options.identity,
-        readiness,
-        closed: () => runner.closed(),
-        shutdown: (reason) => runner.shutdown(reason),
-    };
-}
-class Runner {
-    endpoint;
-    identity;
-    #process;
-    #adapter;
-    #spawnWriter;
-    #diagnose;
-    #maxFrameBytes;
-    #maxPendingRequests;
-    #maxBufferedEvents;
-    #maxControllerBufferBytes;
-    #requestTimeoutMs;
-    #readyTimeoutMs;
-    #handshakeTimeoutMs;
-    #shutdownGraceMs;
-    #killGraceMs;
-    #pendingHandshakes = new Map();
-    #authenticating = new Set();
-    #bufferedEvents = [];
-    #detachEvents;
-    #reporters = new Map();
-    #pendingReports = [];
-    #controller;
-    #server;
-    #boundEndpoint = false;
-    #droppedEvents = 0;
-    #readyState = undefined;
-    #shutdownRequested = false;
-    #writerClosing = false;
-    #writerExit;
-    #exit;
-    #closing;
-    #authorizeRecovery;
-    #bridgeBound = true;
-    #boundSessionId;
-    #bridge;
-    #pauseGeneration = 0;
-    #pauseWaiters = [];
-    #resolveClosed;
-    constructor(options) {
-        this.endpoint = options.identity.endpoint;
-        this.identity = options.identity;
-        this.#process = options.process;
-        this.#spawnWriter = options.spawnWriter;
-        this.#diagnose = options.onDiagnostic ?? ((line) => writeDiagnostic("runner", line));
-        this.#maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
-        this.#maxPendingRequests = options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS;
-        this.#maxBufferedEvents = options.maxBufferedEvents ?? DEFAULT_MAX_BUFFERED_EVENTS;
-        this.#maxControllerBufferBytes = options.maxControllerBufferBytes ?? 4 * this.#maxFrameBytes;
-        this.#requestTimeoutMs = options.requestTimeoutMs ?? 120_000;
-        this.#readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
-        this.#handshakeTimeoutMs = options.handshakeTimeoutMs ?? 10_000;
-        this.#shutdownGraceMs = options.shutdownGraceMs ?? 2_000;
-        this.#killGraceMs = options.killGraceMs ?? 1_000;
-        this.#authorizeRecovery = options.authorizeRecovery;
-        this.#boundSessionId = options.sessionId;
-        this.#bindWriter(options.process);
-    }
-    #bindWriter(child) {
-        this.#process = child;
-        this.#writerExit = undefined;
-        this.#adapter = new PiRpcAdapter({
-            process: child,
-            maxFrameBytes: this.#maxFrameBytes,
-            maxPendingRequests: this.#maxPendingRequests,
-            requestTimeoutMs: this.#requestTimeoutMs,
-            onListenerError: (error) => this.#diagnose(`event listener failed: ${errorMessage(error)}`),
-        });
-        this.#detachEvents = this.#adapter.onEvent((event) => {
-            if (shouldForwardPiEvent(event))
-                this.#broadcast(event);
-        });
-        child.once("exit", (code, signal) => this.#onChildExit(code, signal));
-    }
-    /** Confirms a real Pi RPC round trip, then publishes the endpoint. */
-    async start() {
-        const adapter = this.#adapter;
-        if (adapter === undefined)
-            throw new Error("Pi RPC writer is not bound");
-        try {
-            this.#readyState = await adapter.ready(AbortSignal.timeout(this.#readyTimeoutMs));
-        }
-        catch (error) {
-            this.#teardownWriter(toError(error));
-            throw new Error(`Pi RPC did not become ready: ${errorMessage(error)}`);
-        }
-        try {
-            await this.#listen();
-        }
-        catch (error) {
-            await this.shutdown(toError(error));
-            throw toError(error);
-        }
-        return this.#readyState;
-    }
-    closed() {
-        if (this.#exit !== undefined)
-            return Promise.resolve(this.#exit);
-        return new Promise((resolve) => {
-            this.#resolveClosed = resolve;
-        });
-    }
-    shutdown(reason = new Error("Runner shutdown requested")) {
-        if (this.#closing !== undefined)
-            return this.#closing;
-        this.#closing = this.#runShutdown(reason);
-        return this.#closing;
-    }
-    async #runShutdown(reason) {
-        this.#shutdownRequested = true;
-        this.#diagnose(`shutting down: ${reason.message}`);
-        try {
-            return await this.#cleanup(reason);
-        }
-        catch (error) {
-            this.#diagnose(`shutdown cleanup failed: ${errorMessage(error)}`);
-            const exit = this.#exit ?? {
-                code: this.#process?.exitCode ?? this.#writerExit?.code ?? null,
-                signal: this.#process?.signalCode ?? this.#writerExit?.signal ?? null,
-                reason,
-                requested: true,
-            };
-            this.#finish(exit);
-            return exit;
-        }
-    }
-    async #cleanup(reason) {
-        const controller = this.#controller;
-        this.#controller = undefined;
-        if (controller !== undefined) {
-            // Let the final events (child exit, gap notice) reach a live controller.
-            await drainSocket(controller.socket, 250);
-            this.#destroyController(controller, reason);
-        }
-        for (const [socket, handshake] of this.#pendingHandshakes) {
-            clearTimeout(handshake.timer);
-            handshake.detach();
-            socket.destroy();
-        }
-        this.#pendingHandshakes.clear();
-        for (const reporter of this.#reporters.values())
-            this.#dropReporter(reporter);
-        this.#reporters.clear();
-        if (this.#bridge !== undefined)
-            this.#dropBridge(this.#bridge);
-        this.#failPauseWaiters(new Error("Runner is shutting down"));
-        await this.#closeServer();
-        await this.#releaseChild();
-        this.#teardownWriter(reason);
-        const exit = this.#exit ?? {
-            code: this.#process?.exitCode ?? this.#writerExit?.code ?? null,
-            signal: this.#process?.signalCode ?? this.#writerExit?.signal ?? null,
-            reason,
-            requested: true,
-        };
-        this.#finish(exit);
-        return exit;
-    }
-    async #listen() {
-        await this.#clearStaleEndpoint();
-        const server = createServer({ allowHalfOpen: false });
-        this.#server = server;
-        server.on("connection", (socket) => this.#accept(socket));
-        server.on("error", (error) => this.#diagnose(`socket server error: ${errorMessage(error)}`));
-        const listening = new Promise((resolve, reject) => {
-            server.once("error", reject);
-            server.listen(this.endpoint, () => {
-                server.off("error", reject);
-                resolve();
-            });
-        });
-        try {
-            await listening;
-        }
-        catch (error) {
-            this.#server = undefined;
-            server.close();
-            throw toError(error);
-        }
-        this.#boundEndpoint = true;
-        await this.#restrictEndpoint();
-    }
-    /**
-     * Refuses to steal an endpoint owned by a live runner. A socket that exists
-     * but cannot be connected to is a leftover from a dead runner and is removed.
-     */
-    async #clearStaleEndpoint() {
-        try {
-            const stats = await lstat(this.endpoint);
-            if (!stats.isSocket()) {
-                throw new Error(`runner endpoint path exists and is not a Unix socket: ${this.endpoint}`);
-            }
-        }
-        catch (error) {
-            if (isErrno(error, "ENOENT"))
-                return;
-            throw toError(error);
-        }
-        if (await isEndpointLive(this.endpoint)) {
-            throw new Error(`a live runner already owns endpoint ${this.endpoint}`);
-        }
-        await unlink(this.endpoint);
-        this.#diagnose(`removed stale endpoint ${this.endpoint}`);
-    }
-    async #restrictEndpoint() {
-        try {
-            await chmod(this.endpoint, 0o600);
-        }
-        catch (error) {
-            this.#diagnose(`could not restrict endpoint permissions: ${errorMessage(error)}`);
-        }
-    }
-    async #closeServer() {
-        const server = this.#server;
-        this.#server = undefined;
-        if (server !== undefined) {
-            await new Promise((resolve) => {
-                server.close(() => resolve());
-            });
-        }
-        // Only remove a socket this runner created; another live runner may own it.
-        if (!this.#boundEndpoint)
-            return;
-        this.#boundEndpoint = false;
-        try {
-            await unlink(this.endpoint);
-        }
-        catch (error) {
-            if (!isErrno(error, "ENOENT"))
-                this.#diagnose(`could not remove endpoint: ${errorMessage(error)}`);
-        }
-    }
-    #accept(socket) {
-        if (this.#pendingHandshakes.size >= MAX_PENDING_HANDSHAKES) {
-            this.#diagnose("refused connection: too many unauthenticated connections");
-            socket.destroy();
-            return;
-        }
-        socket.setNoDelay(true);
-        const detach = attachJsonLineReader(socket, {
-            maxFrameBytes: this.#maxFrameBytes,
-            onError: (error) => {
-                this.#diagnose(`controller stream error: ${error.message}`);
-                this.#dropSocket(socket);
-            },
-            onValue: (value) => {
-                const reporter = this.#reporters.get(socket) ?? this.#bridgeFor(socket);
-                if (reporter !== undefined) {
-                    this.#handleReporterRequest(reporter, value);
-                    return;
-                }
-                const controller = this.#controller;
-                if (controller !== undefined && controller.socket === socket) {
-                    this.#handleRequest(controller, value);
-                    return;
-                }
-                if (this.#authenticating.has(socket)) {
-                    this.#diagnose("rejected connection: overlapping handshake frames");
-                    this.#dropSocket(socket);
-                    return;
-                }
-                void this.#authenticate(socket, value);
-            },
-        });
-        const timer = setTimeout(() => {
-            this.#diagnose("refused connection: handshake deadline exceeded");
-            this.#dropSocket(socket);
-        }, this.#handshakeTimeoutMs);
-        this.#pendingHandshakes.set(socket, { detach, timer });
-        socket.once("close", () => {
-            const handshake = this.#pendingHandshakes.get(socket);
-            if (handshake !== undefined) {
-                clearTimeout(handshake.timer);
-                this.#pendingHandshakes.delete(socket);
-                handshake.detach();
-                return;
-            }
-            const reporter = this.#reporters.get(socket);
-            if (reporter !== undefined) {
-                this.#reporters.delete(socket);
-                reporter.detach();
-                return;
-            }
-            if (this.#bridge?.socket === socket) {
-                this.#bridge.detach();
-                this.#bridge = undefined;
-                this.#diagnose("child bridge disconnected; runner keeps running");
-                return;
-            }
-            const controller = this.#controller;
-            if (controller === undefined || controller.socket !== socket)
-                return;
-            this.#controller = undefined;
-            controller.detach();
-            this.#diagnose("controller disconnected; runner keeps running");
-        });
-    }
-    /** Only a connection that proves identity and token may control the runner. */
-    async #authenticate(socket, value) {
-        const handshake = this.#pendingHandshakes.get(socket);
-        if (handshake === undefined) {
-            socket.destroy();
-            return;
-        }
-        if (!isHelloFrame(value) || !this.#matchesStaticIdentity(value)) {
-            this.#diagnose("rejected connection: handshake did not authenticate");
-            this.#dropSocket(socket);
-            return;
-        }
-        this.#authenticating.add(socket);
-        try {
-            const authenticated = value.role === "recovery"
-                ? value.claimId !== undefined &&
-                    this.#authorizeRecovery !== undefined &&
-                    (await this.#authorizeRecovery(value.claimId, value.token))
-                : tokensMatch(value.token, this.identity.token);
-            if (!authenticated || socket.destroyed || !this.#pendingHandshakes.has(socket)) {
-                this.#diagnose("rejected connection: handshake did not authenticate");
-                this.#dropSocket(socket);
-                return;
-            }
-            clearTimeout(handshake.timer);
-            this.#pendingHandshakes.delete(socket);
-            if (value.role === "reporter") {
-                const reporter = { socket, detach: handshake.detach };
-                this.#reporters.set(socket, reporter);
-                void writeJsonLine(socket, { version: PROTOCOL_VERSION, type: "hello_ack" }, this.#maxFrameBytes).catch((error) => {
-                    this.#diagnose(`reporter handshake write failed: ${errorMessage(error)}`);
-                    this.#dropReporter(reporter);
-                });
-                return;
-            }
-            if (value.role === "bridge") {
-                const previous = this.#bridge;
-                if (previous !== undefined)
-                    this.#dropBridge(previous);
-                const bridge = { socket, detach: handshake.detach };
-                this.#bridge = bridge;
-                void writeJsonLine(socket, { version: PROTOCOL_VERSION, type: "hello_ack" }, this.#maxFrameBytes).catch((error) => {
-                    this.#diagnose(`bridge handshake write failed: ${errorMessage(error)}`);
-                    this.#dropBridge(bridge);
-                });
-                return;
-            }
-            const previous = this.#controller;
-            if (previous !== undefined) {
-                this.#diagnose("revoking previous controller");
-                this.#controller = undefined;
-                this.#destroyController(previous, new Error("Controller replaced by a new authenticated connection"));
-            }
-            const link = {
-                socket,
-                detach: handshake.detach,
-                requests: new Map(),
-                retired: new Set(),
-            };
-            this.#controller = link;
-            void writeJsonLine(socket, { version: PROTOCOL_VERSION, type: "hello_ack" }, this.#maxFrameBytes)
-                .then(() => {
-                this.#flushPendingReports(link);
-                this.#flushBufferedEvents(link);
-            })
-                .catch((error) => {
-                this.#diagnose(`controller handshake write failed: ${errorMessage(error)}`);
-                this.#dropController(link, toError(error));
-            });
-        }
-        catch (error) {
-            this.#diagnose(`recovery authorization failed: ${errorMessage(error)}`);
-            this.#dropSocket(socket);
-        }
-        finally {
-            this.#authenticating.delete(socket);
-        }
-    }
-    #matchesStaticIdentity(frame) {
-        const identity = this.identity;
-        return (frame.parentSessionId === identity.parentSessionId &&
-            frame.subagentId === identity.subagentId &&
-            frame.runtimeIdentity === identity.runtimeIdentity &&
-            frame.endpoint === identity.endpoint);
-    }
-    #handleReporterRequest(link, value) {
-        if (!isRequestFrame(value)) {
-            void this.#respondReporter(link, failureResponse("report", "invalid_report", "Reporter sent an invalid report"));
-            return;
-        }
-        if (value.operation === "report_lifecycle" && isChildLifecyclePayload(value.payload)) {
-            if (!this.#matchesReporterIdentity(value.payload)) {
-                void this.#respondReporter(link, failureResponse(value.id, "invalid_report", "Reporter sent an invalid report"));
-                return;
-            }
-            if (value.payload.kind === "left_session")
-                this.#bridgeBound = false;
-            this.#broadcast({ ...value.payload, type: CHILD_LIFECYCLE_EVENT });
-            void this.#respondReporter(link, successResponse(value.id));
-            return;
-        }
-        if (value.operation === "report_paused" && isPauseReportPayload(value.payload)) {
-            if (!this.#matchesReporterIdentity(value.payload)) {
-                void this.#respondReporter(link, failureResponse(value.id, "invalid_report", "Reporter sent an invalid report"));
-                return;
-            }
-            this.#acceptPauseAck(value.payload.generation);
-            void this.#respondReporter(link, successResponse(value.id));
-            return;
-        }
-        if (value.operation !== "contact_parent" ||
-            !isContactReportPayload(value.payload) ||
-            !this.#matchesReporterIdentity(value.payload)) {
-            void this.#respondReporter(link, failureResponse(value.id, "invalid_report", "Reporter sent an invalid report"));
-            return;
-        }
-        if (!this.#bridgeBound) {
-            void this.#respondReporter(link, failureResponse(value.id, "bridge_unbound", "Child bridge is no longer bound to this session"));
-            return;
-        }
-        if (value.payload.sessionId !== undefined &&
-            this.#boundSessionId !== undefined &&
-            value.payload.sessionId !== this.#boundSessionId) {
-            void this.#respondReporter(link, failureResponse(value.id, "bridge_unbound", "Report session is not the bound child session"));
-            return;
-        }
-        const accepted = this.#deliverOrQueueReport(value.payload);
-        void this.#respondReporter(link, accepted
-            ? successResponse(value.id)
-            : failureResponse(value.id, "report_queue_full", "Parent report queue is full"));
-    }
-    #matchesReporterIdentity(payload) {
-        return (payload.parentSessionId === this.identity.parentSessionId &&
-            payload.childId === this.identity.subagentId &&
-            payload.runtimeIdentity === this.identity.runtimeIdentity);
-    }
-    async #respondReporter(link, frame) {
-        try {
-            await writeJsonLine(link.socket, frame, this.#maxFrameBytes);
-        }
-        catch (error) {
-            this.#diagnose(`reporter response write failed: ${errorMessage(error)}`);
-            if (this.#bridge === link)
-                this.#dropBridge(link);
-            else
-                this.#dropReporter(link);
-            return;
-        }
-        if (this.#bridge !== link)
-            this.#dropReporter(link);
-    }
-    #dropReporter(link) {
-        if (this.#reporters.get(link.socket) === link)
-            this.#reporters.delete(link.socket);
-        link.detach();
-        if (!link.socket.destroyed)
-            link.socket.destroy();
-    }
-    #bridgeFor(socket) {
-        return this.#bridge?.socket === socket ? this.#bridge : undefined;
-    }
-    #dropBridge(link) {
-        if (this.#bridge === link)
-            this.#bridge = undefined;
-        link.detach();
-        if (!link.socket.destroyed)
-            link.socket.destroy();
-    }
-    #deliverOrQueueReport(report) {
-        if (this.#pendingReports.length >= this.#maxBufferedEvents)
-            return false;
-        const link = this.#controller;
-        if (link !== undefined && link.socket.writableLength <= this.#maxControllerBufferBytes) {
-            void writeJsonLine(link.socket, eventFrame({ type: "subagent_report", report }), this.#maxFrameBytes).catch((error) => {
-                this.#diagnose(`parent report delivery failed: ${errorMessage(error)}`);
-                this.#dropController(link, toError(error));
-                if (this.#pendingReports.length < this.#maxBufferedEvents)
-                    this.#pendingReports.push(report);
-            });
-            return true;
-        }
-        if (this.#pendingReports.length >= this.#maxBufferedEvents)
-            return false;
-        this.#pendingReports.push(report);
-        return true;
-    }
-    #flushPendingReports(link) {
-        if (this.#controller !== link)
-            return;
-        const reports = this.#pendingReports.splice(0, this.#pendingReports.length);
-        for (const report of reports) {
-            void writeJsonLine(link.socket, eventFrame({ type: "subagent_report", report }), this.#maxFrameBytes).catch((error) => {
-                this.#pendingReports.unshift(report);
-                this.#diagnose(`parent report catch-up failed: ${errorMessage(error)}`);
-                this.#dropController(link, toError(error));
-            });
-        }
-    }
-    #handleRequest(link, value) {
-        if (!isRequestFrame(value)) {
-            this.#diagnose("controller sent a malformed frame");
-            this.#dropController(link, new Error("Controller sent a malformed frame"));
-            return;
-        }
-        const { id, operation } = value;
-        if (link.retired.has(id) || link.requests.has(id)) {
-            rememberRequestId(link.retired, id);
-            void this.#respond(link, failureResponse(id, "duplicate_request_id", `Request ${id} is already known`));
-            return;
-        }
-        if (link.requests.size >= this.#maxPendingRequests) {
-            void this.#respond(link, failureResponse(id, "too_many_pending_requests", "Runner pending request limit exceeded"));
-            return;
-        }
-        if (operation === "shutdown") {
-            rememberRequestId(link.retired, id);
-            void this.#respond(link, successResponse(id)).then(() => this.shutdown(new Error("Controller requested shutdown")));
-            return;
-        }
-        if (operation === "close_writer") {
-            rememberRequestId(link.retired, id);
-            void this.#closeWriter()
-                .then(() => this.#respond(link, successResponse(id, { closed: true })))
-                .catch((error) => this.#respond(link, failureResponse(id, errorCode(error), errorMessage(error))));
-            return;
-        }
-        if (operation === "start_rpc") {
-            rememberRequestId(link.retired, id);
-            void this.#startRpc()
-                .then((data) => this.#respond(link, successResponse(id, data)))
-                .catch((error) => this.#respond(link, failureResponse(id, errorCode(error), errorMessage(error))));
-            return;
-        }
-        if (operation === "pause") {
-            const abort = new AbortController();
-            link.requests.set(id, abort);
-            void this.#runPause(abort.signal)
-                .then((data) => this.#respond(link, successResponse(id, data)))
-                .catch((error) => this.#respond(link, failureResponse(id, errorCode(error), errorMessage(error))))
-                .finally(() => {
-                link.requests.delete(id);
-                rememberRequestId(link.retired, id);
-            });
-            return;
-        }
-        if (operation === "cancel_pause") {
-            rememberRequestId(link.retired, id);
-            this.#cancelPause("Controller cancelled pause");
-            void this.#respond(link, successResponse(id, { cancelled: true }));
-            return;
-        }
-        if (operation === "contact_parent" ||
-            operation === "report_lifecycle" ||
-            operation === "report_paused") {
-            rememberRequestId(link.retired, id);
-            void this.#respond(link, failureResponse(id, "reporter_required", `${operation} requires a reporter connection`));
-            return;
-        }
-        const abort = new AbortController();
-        link.requests.set(id, abort);
-        void this.#forward(link, id, operation, value.payload, abort);
-    }
-    async #forward(link, id, operation, payload, abort) {
-        try {
-            const adapter = this.#adapter;
-            if (adapter === undefined) {
-                throw new Error("RPC writer is not bound");
-            }
-            const data = await adapter.request(operation, payload, {
-                signal: abort.signal,
-                timeoutMs: this.#requestTimeoutMs,
-            });
-            await this.#respond(link, successResponse(id, data));
-        }
-        catch (error) {
-            await this.#respond(link, failureResponse(id, errorCode(error), errorMessage(error)));
-        }
-        finally {
-            link.requests.delete(id);
-            rememberRequestId(link.retired, id);
-        }
-    }
-    /** Answers only the controller that asked; a revoked controller gets nothing. */
-    #respond(link, frame) {
-        if (this.#controller !== link || link.socket.destroyed)
-            return Promise.resolve();
-        return writeJsonLine(link.socket, frame, this.#maxFrameBytes).catch((error) => {
-            this.#diagnose(`controller response write failed: ${errorMessage(error)}`);
-            this.#dropController(link, toError(error));
-        });
-    }
-    #broadcast(event) {
-        if (this.#exit !== undefined)
-            return;
-        const link = this.#controller;
-        if (link !== undefined) {
-            if (link.socket.writableLength > this.#maxControllerBufferBytes) {
-                this.#diagnose(`controller is not reading events (${link.socket.writableLength} bytes queued)`);
-                this.#dropController(link, new Error("Controller is not reading runner events"));
-            }
-            else {
-                void writeJsonLine(link.socket, eventFrame(event), this.#maxFrameBytes).catch((error) => {
-                    this.#diagnose(`controller event write failed: ${errorMessage(error)}`);
-                    this.#dropController(link, toError(error));
-                    this.#bufferEvent(event);
-                });
-                return;
-            }
-        }
-        this.#bufferEvent(event);
-    }
-    #bufferEvent(event) {
-        if (this.#bufferedEvents.length >= this.#maxBufferedEvents) {
-            this.#bufferedEvents.shift();
-            this.#droppedEvents += 1;
-        }
-        this.#bufferedEvents.push(event);
-    }
-    /** Hands a reconnected controller the events it missed, or a gap notice. */
-    #flushBufferedEvents(link) {
-        if (this.#controller !== link)
-            return;
-        const pending = [...this.#bufferedEvents];
-        this.#bufferedEvents.length = 0;
-        const dropped = this.#droppedEvents;
-        this.#droppedEvents = 0;
-        if (dropped > 0) {
-            pending.unshift({ type: RUNNER_EVENTS_DROPPED_EVENT, count: dropped });
-        }
-        for (const event of pending) {
-            void writeJsonLine(link.socket, eventFrame(event), this.#maxFrameBytes).catch((error) => {
-                this.#bufferEvent(event);
-                this.#diagnose(`controller catch-up write failed: ${errorMessage(error)}`);
-                this.#dropController(link, toError(error));
-            });
-        }
-    }
-    #onChildExit(code, signal) {
-        this.#diagnose(`Pi child exited (code=${String(code)}, signal=${String(signal)})`);
-        this.#failPauseWaiters(new Error("Pi child exited"));
-        this.#writerExit = { code, signal };
-        if (this.#writerClosing && !this.#shutdownRequested) {
-            this.#broadcast({ type: WRITER_EXIT_EVENT, code, signal });
-            this.#teardownWriter(new Error(`Pi RPC writer exited (code=${String(code)}, signal=${String(signal)})`));
-            this.#process = undefined;
-            return;
-        }
-        this.#broadcast({ type: RUNNER_EXIT_EVENT, code, signal });
-        this.#exit = {
-            code,
-            signal,
-            reason: new Error(`Pi child exited (code=${String(code)}, signal=${String(signal)})`),
-            requested: this.#shutdownRequested,
-        };
-        void this.shutdown(this.#exit.reason);
-    }
-    #notifyBridge(event) {
-        const bridge = this.#bridge;
-        if (bridge === undefined)
-            return;
-        void writeJsonLine(bridge.socket, eventFrame(event), this.#maxFrameBytes).catch((error) => {
-            this.#diagnose(`bridge event write failed: ${errorMessage(error)}`);
-            this.#dropBridge(bridge);
-        });
-    }
-    async #runPause(signal) {
-        if (signal.aborted)
-            throw abortError();
-        const adapter = this.#adapter;
-        if (adapter !== undefined) {
-            try {
-                const state = await adapter.request("get_state", undefined, {
-                    signal,
-                    timeoutMs: this.#requestTimeoutMs,
-                });
-                if (isIdlePiState(state)) {
-                    return { paused: true, idle: true, generation: this.#pauseGeneration };
-                }
-            }
-            catch (error) {
-                if (signal.aborted || (error instanceof Error && error.name === "AbortError")) {
-                    throw toError(error);
-                }
-            }
-        }
-        return this.#waitForPauseAck(signal);
-    }
-    #waitForPauseAck(signal) {
-        if (signal.aborted)
-            return Promise.reject(abortError());
-        this.#pauseGeneration += 1;
-        const generation = this.#pauseGeneration;
-        this.#notifyBridge({ type: PAUSE_EVENT, generation });
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.#cancelPause("Pause handshake timed out");
-            }, this.#requestTimeoutMs);
-            const onAbort = () => {
-                this.#cancelPause("Pause was cancelled");
-            };
-            this.#pauseWaiters.push({ generation, resolve, reject, timer, onAbort, signal });
-            if (signal.aborted) {
-                onAbort();
-                return;
-            }
-            signal.addEventListener("abort", onAbort, { once: true });
-        });
-    }
-    #acceptPauseAck(generation) {
-        const waiters = this.#pauseWaiters.filter((waiter) => waiter.generation === generation);
-        if (waiters.length === 0)
-            return;
-        this.#pauseWaiters.splice(0, this.#pauseWaiters.length, ...this.#pauseWaiters.filter((waiter) => waiter.generation !== generation));
-        for (const waiter of waiters) {
-            clearTimeout(waiter.timer);
-            waiter.signal?.removeEventListener("abort", waiter.onAbort);
-            waiter.resolve({ paused: true, idle: false, generation });
-        }
-    }
-    #cancelPause(reason) {
-        this.#pauseGeneration += 1;
-        this.#notifyBridge({ type: CANCEL_PAUSE_EVENT, generation: this.#pauseGeneration });
-        this.#failPauseWaiters(new Error(reason));
-    }
-    #failPauseWaiters(error) {
-        const waiters = this.#pauseWaiters.splice(0, this.#pauseWaiters.length);
-        for (const waiter of waiters) {
-            clearTimeout(waiter.timer);
-            waiter.signal?.removeEventListener("abort", waiter.onAbort);
-            waiter.reject(error);
-        }
-    }
-    async #closeWriter() {
-        if (this.#process === undefined || this.#writerExit !== undefined)
-            return;
-        this.#writerClosing = true;
-        try {
-            await this.#releaseChild();
-            if (!(await this.#waitForExit(this.#shutdownGraceMs + this.#killGraceMs))) {
-                throw new Error("RPC writer did not exit after close_writer");
-            }
-        }
-        finally {
-            this.#writerClosing = false;
-        }
-    }
-    async #startRpc() {
-        if (this.#process !== undefined && this.#writerExit === undefined) {
-            throw new Error("RPC writer is still bound");
-        }
-        if (this.#spawnWriter === undefined) {
-            throw new Error("RPC writer respawn is not configured");
-        }
-        this.#teardownWriter(new Error("Replacing RPC writer"));
-        this.#bindWriter(this.#spawnWriter());
-        this.#bridgeBound = true;
-        const adapter = this.#adapter;
-        if (adapter === undefined)
-            throw new Error("RPC writer is not bound");
-        this.#readyState = await adapter.ready(AbortSignal.timeout(this.#readyTimeoutMs));
-        return this.#readyState;
-    }
-    #teardownWriter(reason) {
-        this.#detachEvents?.();
-        this.#detachEvents = undefined;
-        this.#adapter?.close(reason);
-        this.#adapter = undefined;
-    }
-    #dropSocket(socket) {
-        const handshake = this.#pendingHandshakes.get(socket);
-        if (handshake !== undefined) {
-            clearTimeout(handshake.timer);
-            this.#pendingHandshakes.delete(socket);
-            handshake.detach();
-        }
-        socket.destroy();
-    }
-    #dropController(link, error) {
-        if (this.#controller === link)
-            this.#controller = undefined;
-        this.#destroyController(link, error);
-    }
-    /** Fails every in-flight request of a controller that lost its authority. */
-    #destroyController(link, error) {
-        link.detach();
-        const requests = [...link.requests.values()];
-        link.requests.clear();
-        for (const request of requests)
-            request.abort();
-        if (!link.socket.destroyed)
-            link.socket.destroy();
-        this.#diagnose(`controller released: ${error.message}`);
-    }
-    /** Aborts the current turn, then ends the Pi child within fixed deadlines. */
-    async #releaseChild() {
-        const child = this.#process;
-        if (child === undefined)
-            return;
-        if (this.#writerExit === undefined && child.exitCode === null && child.signalCode === null) {
-            try {
-                await this.#adapter?.request("abort", undefined, { timeoutMs: 1_000 });
-            }
-            catch (error) {
-                this.#diagnose(`abort before shutdown failed: ${errorMessage(error)}`);
-            }
-        }
-        if (await this.#waitForExit(0))
-            return;
-        child.kill("SIGTERM");
-        if (await this.#waitForExit(this.#shutdownGraceMs))
-            return;
-        this.#diagnose("Pi child ignored SIGTERM; sending SIGKILL");
-        child.kill("SIGKILL");
-        if (await this.#waitForExit(this.#killGraceMs))
-            return;
-        this.#diagnose("Pi child did not exit after SIGKILL");
-    }
-    #waitForExit(timeoutMs) {
-        if (this.#writerExit !== undefined || this.#process === undefined)
-            return Promise.resolve(true);
-        if (this.#process.exitCode !== null || this.#process.signalCode !== null) {
-            return Promise.resolve(true);
-        }
-        const child = this.#process;
-        return new Promise((resolve) => {
-            const timer = setTimeout(() => {
-                child.off("exit", onExit);
-                resolve(false);
-            }, timeoutMs);
-            const onExit = () => {
-                clearTimeout(timer);
-                resolve(true);
-            };
-            child.once("exit", onExit);
-        });
-    }
-    #finish(exit) {
-        if (this.#exit === undefined)
-            this.#exit = exit;
-        const resolve = this.#resolveClosed;
-        this.#resolveClosed = undefined;
-        resolve?.(exit);
-    }
-}
-/** Bounded FIFO memory of finished request IDs for one controller. */
-function rememberRequestId(retired, id) {
-    retired.add(id);
-    if (retired.size <= MAX_RETIRED_REQUEST_IDS)
-        return;
-    const oldest = retired.values().next();
-    if (!oldest.done)
-        retired.delete(oldest.value);
-}
-function errorCode(error) {
-    if (error instanceof Error && error.name === "AbortError")
-        return "aborted";
-    if (error instanceof PiRpcTimeoutError)
-        return "timeout";
-    return "runner_error";
-}
-function tokensMatch(candidate, expected) {
-    const left = Buffer.from(candidate, "utf8");
-    const right = Buffer.from(expected, "utf8");
-    return left.length === right.length && timingSafeEqual(left, right);
-}
-function isErrno(error, code) {
-    return isRecord(error) && error.code === code;
-}
-/** Waits, within a fixed deadline, for queued socket writes to flush. */
-function drainSocket(socket, timeoutMs) {
-    if (socket.destroyed || socket.writableLength === 0)
-        return Promise.resolve();
-    return new Promise((resolve) => {
-        const timer = setTimeout(() => {
-            socket.off("drain", onDrain);
-            resolve();
-        }, timeoutMs);
-        const onDrain = () => {
-            clearTimeout(timer);
-            resolve();
-        };
-        socket.once("drain", onDrain);
-    });
-}
-/** True when a runner answers on this endpoint; connect failures mean stale. */
-function isEndpointLive(endpoint) {
-    const socket = createConnection(endpoint);
-    return new Promise((resolve) => {
-        let settled = false;
-        const finish = (live) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            socket.destroy();
-            resolve(live);
-        };
-        const timer = setTimeout(() => finish(true), 1_000);
-        socket.once("connect", () => finish(true));
-        socket.once("error", () => finish(false));
-    });
-}