@alpacakit/agents 0.1.0-beta.19 → 0.1.0-beta.21

package/dist/internal/controlled-process/supervisor-runtime.js

@@ -0,0 +1,773 @@
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: Section 5.103 confines the supervisor correction to this existing runtime owner.
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { CHILD_PROCESS_TERMINATION_KIND } from "../../core/controlled-process.js";
+import { readString } from "../../core/json.js";
+import { closeWritableFd, readableFd, writableFd } from "./child-fd.js";
+import { readFramedRecords, readRequiredFrame, writeFramedRecord, } from "./framed-transport.js";
+import { assertSecureRuntimeDirectory, resolveSupervisorSocketNamespace, SignedRecordStore, supervisorSocketPath, } from "./record-store.js";
+import { controlledProcessRecordIdSchema, shimProcessIdSchema, supervisorCapabilitySchema, supervisorInstanceIdSchema, supervisorSocketLocatorSchema, } from "./schema.js";
+import { SupervisorCoordinator } from "./supervisor-coordinator.js";
+import { createSupervisorPlatformAdapter } from "./supervisor-platform.js";
+import { shimRunningSchema, supervisorBootstrapSchema, supervisorHostAckSchema, workerExitSchema, } from "./supervisor-schema.js";
+import { SupervisorSocketServer } from "./supervisor-transport.js";
+import { PROCESS_PROBE_KIND, SHIM_FRAME_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, } from "./supervisor-values.js";
+import { encodeProcessStartToken } from "./token.js";
+import { CONTROLLED_PROCESS_PROTOCOL_VERSION, CONTROLLED_PROCESS_STATE, } from "./values.js";
+const HOST_BOOTSTRAP_FD = 3;
+const HOST_IDENTITY_FD = 4;
+const SHIM_CONTROL_FD = 3;
+const SHIM_STATUS_FD = 4;
+const RANDOM_ID_BYTES = 16;
+const CAPABILITY_BYTES = 32;
+const ATTACHED_STDOUT = process.stdout;
+const ATTACHED_STDERR = process.stderr;
+let attachedOutputSettlement = null;
+const SUPERVISOR_RUNTIME_DEPENDENCIES = {
+    writeShimAck: async (control) => writeFramedRecord(control, { kind: SHIM_FRAME_KIND.ack }),
+    persistInitialRecord: async (coordinator) => coordinator.persistInitial(),
+    finalizeSupervisorSocket: async (server) => server.finalize(),
+};
+export async function runControlledProcessSupervisor(dependencies = SUPERVISOR_RUNTIME_DEPENDENCIES) {
+    const hostInput = readableFd(HOST_BOOTSTRAP_FD);
+    const hostOutput = {
+        stream: writableFd(HOST_IDENTITY_FD),
+        closePromise: null,
+    };
+    try {
+        const frames = readFramedRecords(hostInput)[Symbol.asyncIterator]();
+        const bootstrap = supervisorBootstrapSchema.parse(await readRequiredFrame(frames));
+        await runSupervisorSession({
+            bootstrap,
+            frames,
+            hostInput,
+            hostOutput,
+            dependencies,
+        });
+    }
+    catch (error) {
+        if (hostOutput.closePromise === null) {
+            await writeFramedRecord(hostOutput.stream, {
+                kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed,
+                reason: error instanceof Error ? error.message : "Supervisor launch failed.",
+            }).catch(() => undefined);
+            await closeHostOutput(hostOutput).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: The lifecycle sequence is kept contiguous because section 5.103 forbids a new runtime owner.
+async function runSupervisorSession(input) {
+    const platform = createSupervisorPlatformAdapter();
+    const runtimeDirectory = await assertSecureRuntimeDirectory(input.bootstrap.runtimeDirectory, platform.uid);
+    const socketDirectory = await resolveSupervisorSocketNamespace(platform.platform, platform.uid);
+    const tokenFields = await createTokenFields(platform);
+    const socketPath = supervisorSocketPath({
+        socketDirectory,
+        socketLocator: tokenFields.socketLocator,
+        platform: platform.platform,
+    });
+    const store = new SignedRecordStore(runtimeDirectory, tokenFields.recordId, platform.uid);
+    let coordinator = null;
+    let shimPid = null;
+    let shimControl = null;
+    let shimStatus = null;
+    let shimClosed = null;
+    let lifecycleMonitor = null;
+    let lifecycleMonitorInFlight = null;
+    let coordinatorTickEnabled = false;
+    let coordinatorAckMayHaveCommitted = false;
+    let initialPersistCommitted = false;
+    let initialPersistReceipt = null;
+    let identityDelivered = false;
+    let ready = false;
+    let rollbackAttempted = false;
+    let ownershipLossObserved = false;
+    let ownershipLossPromise = null;
+    const localCoordinatorOperations = [];
+    let releaseSupervisor = () => { };
+    const released = new Promise((resolve) => {
+        releaseSupervisor = resolve;
+    });
+    const trackLocalCoordinatorOperation = (operation) => {
+        localCoordinatorOperations.push(operation);
+        void operation.catch(() => undefined);
+        return operation;
+    };
+    const settleLocalCoordinatorOperations = async () => {
+        await Promise.all(localCoordinatorOperations);
+    };
+    let requestHandler = async (_request) => {
+        throw new Error("Supervisor coordinator is unavailable.");
+    };
+    const server = new SupervisorSocketServer(socketPath, platform.uid, tokenFields.recordId, tokenFields.capability, async (request) => requestHandler(request));
+    const stopLifecycleMonitor = () => {
+        if (lifecycleMonitor !== null) {
+            clearInterval(lifecycleMonitor);
+            lifecycleMonitor = null;
+        }
+    };
+    const settleLifecycleMonitor = async () => {
+        if (lifecycleMonitorInFlight !== null) {
+            await lifecycleMonitorInFlight;
+        }
+    };
+    const startOwnershipLossConvergence = () => {
+        ownershipLossObserved = true;
+        ownershipLossPromise ??= containOwnershipLossFailure((async () => {
+            const deadline = Date.now() + supervisorTerminationBudget(input.bootstrap.timing);
+            stopLifecycleMonitor();
+            input.hostInput.destroy();
+            await beforeOwnershipLossDeadline(Promise.all([
+                settleOwnershipLossHostOutput(input.hostOutput, identityDelivered
+                    ? "Supervisor socket ownership was lost."
+                    : "Supervisor socket ownership was lost before process launch."),
+                server.settleAcceptedSessions(),
+            ]).then(() => undefined), deadline, "Supervisor ownership-loss host output or session drain timed out.");
+            const persistReceipt = initialPersistReceipt;
+            const persistCommitted = persistReceipt === null
+                ? false
+                : await beforeOwnershipLossDeadline(persistReceipt, deadline, "Supervisor initial persistence receipt did not settle.");
+            if (!persistCommitted) {
+                return convergeNoRecordAfterOwnershipLoss({
+                    server,
+                    store,
+                    platform,
+                    shimPid,
+                    shimControl,
+                    shimStatus,
+                    shimClosed,
+                    hostInput: input.hostInput,
+                    hostOutput: input.hostOutput,
+                    timing: input.bootstrap.timing,
+                    deadline,
+                    settleLocalCoordinatorOperations,
+                    settleLifecycleMonitor,
+                });
+            }
+            return convergeAfterOwnershipLoss({
+                server,
+                coordinator: requireCapturedCoordinator(coordinator),
+                coordinatorAckMayHaveCommitted: () => coordinatorAckMayHaveCommitted,
+                shimControl: requireCapturedStream(shimControl, "shim control"),
+                shimStatus: requireCapturedStream(shimStatus, "shim status"),
+                shimClosed: requireCapturedPromise(shimClosed, "shim close"),
+                hostInput: input.hostInput,
+                hostOutput: input.hostOutput,
+                timing: input.bootstrap.timing,
+                deadline,
+                stopLifecycleMonitor,
+                settleLifecycleMonitor,
+                settleLocalCoordinatorOperations,
+            });
+        })());
+        return ownershipLossPromise;
+    };
+    const observeOwnership = async (rejectOperationOnLoss) => {
+        const ownership = await server.observeOwnership();
+        if (ownership.kind !== "ownership_lost") {
+            return;
+        }
+        void startOwnershipLossConvergence();
+        if (rejectOperationOnLoss) {
+            throw new Error("Supervisor socket ownership was lost.");
+        }
+    };
+    const runLifecycleMonitor = () => {
+        if (lifecycleMonitorInFlight !== null || ownershipLossObserved) {
+            return;
+        }
+        const operation = (async () => {
+            const ownership = await server.observeOwnership();
+            if (ownership.kind === "ownership_lost") {
+                void startOwnershipLossConvergence();
+                return;
+            }
+            if (coordinatorTickEnabled && coordinator !== null) {
+                await coordinator.tick();
+            }
+        })();
+        lifecycleMonitorInFlight = operation;
+        void operation
+            .catch(() => undefined)
+            .finally(() => {
+            if (lifecycleMonitorInFlight === operation) {
+                lifecycleMonitorInFlight = null;
+            }
+        });
+    };
+    makeAttachedOutputNonFatal(ATTACHED_STDOUT);
+    makeAttachedOutputNonFatal(ATTACHED_STDERR);
+    await server.listen();
+    const initialOwnership = await server.observeOwnership();
+    if (initialOwnership.kind === "ownership_lost") {
+        await startOwnershipLossConvergence();
+    }
+    lifecycleMonitor = setInterval(runLifecycleMonitor, input.bootstrap.timing.probeIntervalMs);
+    try {
+        const shim = spawnShim(input.bootstrap);
+        shimClosed = waitForShimClose(shim);
+        shimControl = shim.stdio[SHIM_CONTROL_FD];
+        shimStatus = shim.stdio[SHIM_STATUS_FD];
+        const pid = requireShimPid(shim);
+        shimPid = pid;
+        const record = {
+            protocolVersion: CONTROLLED_PROCESS_PROTOCOL_VERSION,
+            platform: tokenFields.platform,
+            bootId: tokenFields.bootId,
+            supervisorInstanceId: tokenFields.supervisorInstanceId,
+            recordId: tokenFields.recordId,
+            socketLocator: tokenFields.socketLocator,
+            pid,
+            state: CONTROLLED_PROCESS_STATE.reserved,
+            absenceProof: null,
+        };
+        coordinator = new SupervisorCoordinator({
+            record,
+            capability: tokenFields.capability,
+            store,
+            platform,
+            timing: input.bootstrap.timing,
+            now: Date.now,
+            onAbsent: endAttachedOutput,
+            onReleased: releaseSupervisor,
+        });
+        const activeCoordinator = coordinator;
+        const runCoordinatorOperation = async (operation) => {
+            await observeOwnership(true);
+            const result = await operation(activeCoordinator);
+            await observeOwnership(true);
+            return result;
+        };
+        const runLocalCoordinatorOperation = async (operation) => {
+            if (ownershipLossObserved && !initialPersistCommitted) {
+                return;
+            }
+            await observeOwnership(false);
+            if (ownershipLossObserved && !initialPersistCommitted) {
+                return;
+            }
+            await operation(activeCoordinator);
+            await observeOwnership(false);
+        };
+        requestHandler = async (request) => {
+            await observeOwnership(true);
+            const response = await handleRequest(activeCoordinator, request.kind);
+            await observeOwnership(false);
+            return response;
+        };
+        trackLocalCoordinatorOperation(attachOutput(shim, runLocalCoordinatorOperation));
+        trackLocalCoordinatorOperation(pumpShimStatus(shimStatus, runLocalCoordinatorOperation).catch(() => runLocalCoordinatorOperation(async (current) => current.recordProtocolFailure())));
+        shim.once("exit", () => {
+            trackLocalCoordinatorOperation(runLocalCoordinatorOperation(async (current) => current.recordShimExit()));
+        });
+        shim.once("close", () => {
+            trackLocalCoordinatorOperation(runLocalCoordinatorOperation(async (current) => current.recordShimClosed()));
+        });
+        await writeFramedRecord(shimControl, {
+            kind: SHIM_FRAME_KIND.bootstrap,
+            worker: input.bootstrap.worker,
+        });
+        await observeOwnership(true);
+        const persistOperation = (input.dependencies.persistInitialRecord ??
+            SUPERVISOR_RUNTIME_DEPENDENCIES.persistInitialRecord)(activeCoordinator);
+        initialPersistReceipt = persistOperation.then(() => {
+            initialPersistCommitted = true;
+            return true;
+        }, () => false);
+        await persistOperation;
+        await observeOwnership(true);
+        await writeFramedRecord(input.hostOutput.stream, {
+            kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.identity,
+            identity: {
+                pid,
+                processStartToken: encodeProcessStartToken(tokenFields),
+            },
+        });
+        identityDelivered = true;
+        const acknowledged = await readHostAck(input.frames);
+        if (!acknowledged) {
+            rollbackAttempted = true;
+            await rollbackPreReadySupervisor({
+                server,
+                finalizeSupervisorSocket: () => (input.dependencies.finalizeSupervisorSocket ??
+                    SUPERVISOR_RUNTIME_DEPENDENCIES.finalizeSupervisorSocket)(server),
+                coordinator: activeCoordinator,
+                coordinatorAckMayHaveCommitted,
+                shimControl,
+                shimStatus,
+                shimClosed,
+                probeIntervalMs: input.bootstrap.timing.probeIntervalMs,
+                timeoutMs: supervisorTerminationBudget(input.bootstrap.timing),
+                onOwnershipLoss: startOwnershipLossConvergence,
+                stopLifecycleMonitor,
+                settleLifecycleMonitor,
+            });
+            stopLifecycleMonitor();
+            await settleLifecycleMonitor();
+            await closeHostOutput(input.hostOutput);
+            input.hostInput.destroy();
+            return;
+        }
+        await runCoordinatorOperation(async (current) => current.acknowledge());
+        coordinatorAckMayHaveCommitted = true;
+        await input.dependencies.writeShimAck(shimControl);
+        await observeOwnership(false);
+        coordinatorTickEnabled = true;
+        ready = true;
+        await closeHostOutput(input.hostOutput);
+        input.hostInput.destroy();
+        await released;
+        await shimClosed;
+        await settleLocalCoordinatorOperations();
+        stopLifecycleMonitor();
+        await settleLifecycleMonitor();
+        const finalization = await (input.dependencies.finalizeSupervisorSocket ??
+            SUPERVISOR_RUNTIME_DEPENDENCIES.finalizeSupervisorSocket)(server);
+        if (finalization.kind === "ownership_lost") {
+            await startOwnershipLossConvergence();
+        }
+        shimControl.destroy();
+        shimStatus.destroy();
+    }
+    catch (primaryFailure) {
+        await observeOwnership(false).catch(() => undefined);
+        if (ownershipLossPromise !== null) {
+            await ownershipLossPromise;
+        }
+        if (ready || rollbackAttempted) {
+            stopLifecycleMonitor();
+            await settleLifecycleMonitor().catch(() => undefined);
+            throw primaryFailure;
+        }
+        try {
+            rollbackAttempted = true;
+            if (coordinator !== null &&
+                shimControl !== null &&
+                shimStatus !== null &&
+                shimClosed !== null) {
+                await waitForSecureRuntimeDirectory({
+                    runtimeDirectory,
+                    uid: platform.uid,
+                    timing: input.bootstrap.timing,
+                });
+                await rollbackPreReadySupervisor({
+                    server,
+                    finalizeSupervisorSocket: () => (input.dependencies.finalizeSupervisorSocket ??
+                        SUPERVISOR_RUNTIME_DEPENDENCIES.finalizeSupervisorSocket)(server),
+                    coordinator,
+                    coordinatorAckMayHaveCommitted,
+                    shimControl,
+                    shimStatus,
+                    shimClosed,
+                    probeIntervalMs: input.bootstrap.timing.probeIntervalMs,
+                    timeoutMs: supervisorTerminationBudget(input.bootstrap.timing),
+                    onOwnershipLoss: startOwnershipLossConvergence,
+                    stopLifecycleMonitor,
+                    settleLifecycleMonitor,
+                });
+                if (!identityDelivered) {
+                    await store.removeUnpublished();
+                }
+            }
+            else {
+                const finalization = await (input.dependencies.finalizeSupervisorSocket ??
+                    SUPERVISOR_RUNTIME_DEPENDENCIES.finalizeSupervisorSocket)(server);
+                if (finalization.kind === "ownership_lost") {
+                    await startOwnershipLossConvergence();
+                }
+            }
+            stopLifecycleMonitor();
+            await settleLifecycleMonitor();
+        }
+        catch (cleanupFailure) {
+            throw new AggregateError([primaryFailure, cleanupFailure], "Controlled process supervisor launch and rollback both failed.");
+        }
+        finally {
+            input.hostInput.destroy();
+        }
+        throw primaryFailure;
+    }
+}
+async function convergeNoRecordAfterOwnershipLoss(input) {
+    if (input.shimControl !== null &&
+        !input.shimControl.destroyed &&
+        !input.shimControl.writableEnded) {
+        input.shimControl.end();
+    }
+    if (input.shimClosed !== null) {
+        await beforeOwnershipLossDeadline(input.shimClosed, input.deadline, "Supervisor ownership-loss shim close did not settle.");
+    }
+    if (input.shimPid !== null) {
+        await waitForRuntimeGroupAbsence({
+            platform: input.platform,
+            pid: input.shimPid,
+            probeIntervalMs: input.timing.probeIntervalMs,
+            deadline: input.deadline,
+        });
+    }
+    await beforeOwnershipLossDeadline(input.settleLocalCoordinatorOperations(), input.deadline, "Supervisor ownership-loss local operations did not settle.");
+    endAttachedOutput();
+    await beforeOwnershipLossDeadline(Promise.all([
+        settleAttachedOutput(),
+        input.store.removeUnpublished(),
+        input.settleLifecycleMonitor(),
+    ]).then(() => undefined), input.deadline, "Supervisor ownership-loss unpublished cleanup did not settle.");
+    input.shimControl?.destroy();
+    input.shimStatus?.destroy();
+    return selfSigkill();
+}
+async function waitForSecureRuntimeDirectory(input) {
+    const deadline = Date.now() +
+        input.timing.termGraceMs +
+        input.timing.killProbeTimeoutMs +
+        input.timing.probeIntervalMs;
+    for (;;) {
+        try {
+            await assertSecureRuntimeDirectory(input.runtimeDirectory, input.uid);
+            return;
+        }
+        catch (error) {
+            if (Date.now() >= deadline) {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, input.timing.probeIntervalMs));
+        }
+    }
+}
+async function rollbackPreReadySupervisor(input) {
+    if (!input.shimControl.destroyed && !input.shimControl.writableEnded) {
+        input.shimControl.end();
+    }
+    let result;
+    if (input.coordinatorAckMayHaveCommitted) {
+        result = await input.coordinator.terminate();
+    }
+    else {
+        await input.coordinator.abortBeforeAck();
+        result = await input.coordinator.probe();
+    }
+    result = await waitForPreReadyConvergence(input.coordinator, result, input.probeIntervalMs, input.timeoutMs);
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error(`Pre-ready supervisor rollback did not prove absence: ${result.kind}.`);
+    }
+    await input.shimClosed;
+    input.stopLifecycleMonitor();
+    await input.settleLifecycleMonitor();
+    input.shimControl.destroy();
+    input.shimStatus.destroy();
+    const finalization = await input.finalizeSupervisorSocket();
+    if (finalization.kind === "ownership_lost") {
+        await input.onOwnershipLoss();
+    }
+}
+async function convergeAfterOwnershipLoss(input) {
+    input.stopLifecycleMonitor();
+    if (!input.coordinatorAckMayHaveCommitted() &&
+        !input.shimControl.destroyed &&
+        !input.shimControl.writableEnded) {
+        input.shimControl.end();
+    }
+    let result;
+    if (input.coordinatorAckMayHaveCommitted()) {
+        result = await beforeOwnershipLossDeadline(input.coordinator.terminate(), input.deadline, "Supervisor ownership-loss termination did not settle.");
+    }
+    else {
+        await beforeOwnershipLossDeadline(input.coordinator.abortBeforeAck(), input.deadline, "Supervisor ownership-loss rollback did not settle.");
+        result = await beforeOwnershipLossDeadline(input.coordinator.probe(), input.deadline, "Supervisor ownership-loss rollback probe did not settle.");
+    }
+    while (result.kind === CHILD_PROCESS_TERMINATION_KIND.pending) {
+        await delayBeforeOwnershipLossDeadline(Math.min(result.retryAfterMs, input.timing.probeIntervalMs), input.deadline, "Supervisor ownership-loss convergence timed out.");
+        result = await beforeOwnershipLossDeadline(input.coordinator.probe(), input.deadline, "Supervisor ownership-loss probe did not settle.");
+    }
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error(`Supervisor ownership-loss convergence did not prove absence: ${result.kind}.`);
+    }
+    await beforeOwnershipLossDeadline(input.shimClosed, input.deadline, "Supervisor ownership-loss shim close did not settle.");
+    await beforeOwnershipLossDeadline(input.settleLocalCoordinatorOperations(), input.deadline, "Supervisor ownership-loss local operations did not settle.");
+    endAttachedOutput();
+    input.shimControl.destroy();
+    input.shimStatus.destroy();
+    await beforeOwnershipLossDeadline(settleAttachedOutput(), input.deadline, "Supervisor ownership-loss attached output did not settle.");
+    await beforeOwnershipLossDeadline(input.settleLifecycleMonitor(), input.deadline, "Supervisor ownership-loss lifecycle monitor did not settle.");
+    return selfSigkill();
+}
+function settleOwnershipLossHostOutput(hostOutput, reason) {
+    return hostOutput.closePromise === null
+        ? writeLaunchFailure(hostOutput, reason)
+        : hostOutput.closePromise;
+}
+async function waitForRuntimeGroupAbsence(input) {
+    for (;;) {
+        const probe = input.platform.probeGroup(input.pid);
+        if (probe.kind === PROCESS_PROBE_KIND.absent) {
+            return;
+        }
+        if (probe.kind !== PROCESS_PROBE_KIND.alive) {
+            throw new Error(`Supervisor ownership-loss group probe failed: ${probe.kind}.`);
+        }
+        await delayBeforeOwnershipLossDeadline(input.probeIntervalMs, input.deadline, "Supervisor ownership-loss process group remained live.");
+    }
+}
+function containOwnershipLossFailure(convergence) {
+    return convergence.catch(() => new Promise(() => { }));
+}
+function beforeOwnershipLossDeadline(operation, deadline, message) {
+    return new Promise((resolve, reject) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            reject(new Error(message));
+            return;
+        }
+        const timeout = setTimeout(() => reject(new Error(message)), remaining);
+        operation.then((result) => {
+            clearTimeout(timeout);
+            resolve(result);
+        }, (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+function delayBeforeOwnershipLossDeadline(delayMs, deadline, message) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        return Promise.reject(new Error(message));
+    }
+    return new Promise((resolve) => setTimeout(resolve, Math.min(delayMs, remaining)));
+}
+async function waitForPreReadyConvergence(coordinator, initial, probeIntervalMs, timeoutMs) {
+    let result = initial;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent) {
+            return result;
+        }
+        if (Date.now() >= deadline) {
+            return result;
+        }
+        await new Promise((resolve) => setTimeout(resolve, probeIntervalMs));
+        result = await coordinator.probe();
+    }
+}
+function supervisorTerminationBudget(timing) {
+    return (timing.termGraceMs + timing.killProbeTimeoutMs + timing.probeIntervalMs);
+}
+async function createTokenFields(platform) {
+    return {
+        protocolVersion: CONTROLLED_PROCESS_PROTOCOL_VERSION,
+        platform: platform.platform,
+        bootId: await platform.bootId(),
+        supervisorInstanceId: supervisorInstanceIdSchema.parse(randomHex(RANDOM_ID_BYTES)),
+        recordId: controlledProcessRecordIdSchema.parse(randomHex(RANDOM_ID_BYTES)),
+        socketLocator: supervisorSocketLocatorSchema.parse(randomHex(RANDOM_ID_BYTES)),
+        capability: supervisorCapabilitySchema.parse(randomHex(CAPABILITY_BYTES)),
+    };
+}
+function spawnShim(bootstrap) {
+    const shim = spawn(process.execPath, [bootstrap.shimEntryPath], {
+        detached: true,
+        env: {},
+        stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+    });
+    shim.once("error", () => { });
+    return shim;
+}
+function waitForShimClose(shim) {
+    return new Promise((resolve) => {
+        shim.once("close", () => resolve());
+    });
+}
+function requireShimPid(shim) {
+    if (shim.pid === undefined) {
+        throw new Error("Detached shim did not expose a pid.");
+    }
+    return shimProcessIdSchema.parse(shim.pid);
+}
+async function readHostAck(frames) {
+    try {
+        supervisorHostAckSchema.parse(await readRequiredFrame(frames));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function attachOutput(shim, runCoordinatorOperation) {
+    const stdout = requireStream(shim.stdout, "stdout");
+    const stderr = requireStream(shim.stderr, "stderr");
+    return Promise.all([
+        pumpOutput(stdout, ATTACHED_STDOUT),
+        pumpOutput(stderr, ATTACHED_STDERR),
+    ]).then(async () => runCoordinatorOperation(async (coordinator) => coordinator.recordOutputClosed()), async () => runCoordinatorOperation(async (coordinator) => coordinator.recordProtocolFailure()));
+}
+async function pumpShimStatus(status, runCoordinatorOperation) {
+    for await (const frame of readFramedRecords(status)) {
+        const kind = readString(frame, "kind");
+        if (kind === SHIM_FRAME_KIND.running) {
+            shimRunningSchema.parse(frame);
+            await runCoordinatorOperation(async (coordinator) => coordinator.running());
+        }
+        else if (kind === SHIM_FRAME_KIND.workerExit) {
+            const workerExit = workerExitSchema.parse(frame);
+            await runCoordinatorOperation(async (coordinator) => coordinator.recordWorkerExit({
+                code: workerExit.code,
+                signal: workerExit.signal,
+            }));
+        }
+        else {
+            throw new Error("Shim status frame is invalid.");
+        }
+    }
+}
+async function handleRequest(coordinator, kind) {
+    if (kind === SUPERVISOR_REQUEST_KIND.probe) {
+        const result = await coordinator.probe();
+        return {
+            kind: SUPERVISOR_RESPONSE_KIND.termination,
+            result,
+            workerExit: coordinator.workerExitEvidence(),
+        };
+    }
+    if (kind === SUPERVISOR_REQUEST_KIND.terminate) {
+        const result = await coordinator.terminate();
+        return {
+            kind: SUPERVISOR_RESPONSE_KIND.termination,
+            result,
+            workerExit: coordinator.workerExitEvidence(),
+        };
+    }
+    if (kind === SUPERVISOR_REQUEST_KIND.release) {
+        return (await coordinator.release())
+            ? { kind: SUPERVISOR_RESPONSE_KIND.released }
+            : { kind: SUPERVISOR_RESPONSE_KIND.releaseBeforeAbsent };
+    }
+    return unreachableRequest(kind);
+}
+function unreachableRequest(kind) {
+    throw new Error(`Unreachable supervisor request: ${String(kind)}`);
+}
+function requireStream(stream, name) {
+    if (stream === null) {
+        throw new Error(`Shim ${name} stream is unavailable.`);
+    }
+    return stream;
+}
+async function pumpOutput(readable, writable) {
+    let sinkLive = isWritableSinkLive(writable);
+    for await (const chunk of readable) {
+        if (sinkLive) {
+            try {
+                if (!writable.write(chunk)) {
+                    sinkLive = await waitForOutputDrain(writable);
+                }
+            }
+            catch {
+                sinkLive = false;
+            }
+        }
+    }
+}
+function waitForOutputDrain(writable) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const cleanup = () => {
+            writable.off("drain", drained);
+            writable.off("error", dead);
+            writable.off("close", dead);
+        };
+        const settle = (live) => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+                resolve(live);
+            }
+        };
+        const drained = () => settle(true);
+        const dead = () => settle(false);
+        writable.once("drain", drained);
+        writable.once("error", dead);
+        writable.once("close", dead);
+        if (!isWritableSinkLive(writable)) {
+            dead();
+        }
+    });
+}
+function isWritableSinkLive(writable) {
+    return !writable.destroyed && !writable.closed && !writable.writableEnded;
+}
+function makeAttachedOutputNonFatal(writable) {
+    writable.on("error", () => { });
+}
+function endAttachedOutput() {
+    if (attachedOutputSettlement !== null) {
+        return;
+    }
+    attachedOutputSettlement = Promise.all([
+        waitForWritableFinish(ATTACHED_STDOUT),
+        waitForWritableFinish(ATTACHED_STDERR),
+    ]).then(() => undefined);
+    ATTACHED_STDOUT.end();
+    ATTACHED_STDERR.end();
+}
+async function settleAttachedOutput() {
+    endAttachedOutput();
+    await attachedOutputSettlement;
+}
+function waitForWritableFinish(writable) {
+    if (writable.writableFinished) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            writable.off("finish", resolveFinish);
+            writable.off("error", rejectError);
+        };
+        const resolveFinish = () => {
+            cleanup();
+            resolve();
+        };
+        const rejectError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        writable.once("finish", resolveFinish);
+        writable.once("error", rejectError);
+    });
+}
+function requireCapturedStream(stream, name) {
+    if (stream === null) {
+        throw new Error(`Supervisor ${name} was not captured.`);
+    }
+    return stream;
+}
+function requireCapturedPromise(promise, name) {
+    if (promise === null) {
+        throw new Error(`Supervisor ${name} was not captured.`);
+    }
+    return promise;
+}
+function requireCapturedCoordinator(coordinator) {
+    if (coordinator === null) {
+        throw new Error("Supervisor coordinator was not captured.");
+    }
+    return coordinator;
+}
+async function writeLaunchFailure(hostOutput, reason) {
+    await writeFramedRecord(hostOutput.stream, {
+        kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed,
+        reason,
+    });
+    await closeHostOutput(hostOutput);
+}
+function closeHostOutput(hostOutput) {
+    hostOutput.closePromise ??= closeWritableFd(hostOutput.stream, HOST_IDENTITY_FD);
+    return hostOutput.closePromise;
+}
+async function selfSigkill() {
+    process.kill(process.pid, "SIGKILL");
+    return new Promise(() => { });
+}
+function randomHex(bytes) {
+    return randomBytes(bytes).toString("hex");
+}