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

package/dist/internal/controlled-process/host-controller.js

@@ -0,0 +1,908 @@
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: Section 5.103 confines the correction to this existing host lifecycle owner.
+import { spawn } from "node:child_process";
+import { CHILD_PROCESS_ABSENCE_PROOF, CHILD_PROCESS_TERMINATION_EVIDENCE_KIND, CHILD_PROCESS_TERMINATION_KIND, CHILD_PROCESS_UNKILLABLE_REASON, } from "../../core/controlled-process.js";
+import { readFramedRecords, readRequiredFrame, writeFramedRecord, } from "./framed-transport.js";
+import { transitionControlledProcess } from "./lifecycle.js";
+import { controlledProcessRecordMatchesToken, signControlledProcessRecord, verifySignedControlledProcessRecord, } from "./record.js";
+import { assertSecureRuntimeDirectory, resolveSupervisorSocketNamespace, SignedRecordStore, supervisorSocketPath, } from "./record-store.js";
+import { controlledProcessIdentitySchema } from "./schema.js";
+import { createSupervisorPlatformAdapter } from "./supervisor-platform.js";
+import { supervisorIdentityFrameSchema, supervisorLaunchFailedFrameSchema, } from "./supervisor-schema.js";
+import { requestSupervisor } from "./supervisor-transport.js";
+import { OUTPUT_CHANNEL_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, } from "./supervisor-values.js";
+import { decodeProcessStartToken } from "./token.js";
+import { CONTROLLED_PROCESS_STATE } from "./values.js";
+const HOST_BOOTSTRAP_FD = 3;
+const HOST_IDENTITY_FD = 4;
+const OUTPUT_QUEUE_HIGH_WATER_BYTES = 64 * 1024;
+const OUTPUT_QUEUE_LOW_WATER_BYTES = 32 * 1024;
+const PRE_READY_CLEANUP_AUTHORITY = {
+    unprobed: "unprobed",
+    unavailable: "unavailable",
+    live: "live",
+    rollbackCompleted: "rollback_completed",
+    reportedFailure: "reported_failure",
+};
+const TERMINATION_OBSERVATION_SOURCE = {
+    liveResponse: "live_response",
+    liveRequestFailure: "live_request_failure",
+    supervisorClose: "supervisor_close",
+    offlineFallback: "offline_fallback",
+};
+class SupervisorReportedLaunchFailure extends Error {
+}
+export async function launchControlledProcess(input) {
+    const platform = createSupervisorPlatformAdapter();
+    const runtimeDirectory = await assertSecureRuntimeDirectory(input.runtimeDirectory, platform.uid);
+    const supervisor = spawnSupervisor(input.supervisorEntryPath);
+    const supervisorClose = observeSupervisorClose(supervisor, input.timing.probeIntervalMs);
+    void supervisorClose.promise.catch(() => undefined);
+    const control = supervisor.stdio[HOST_BOOTSTRAP_FD];
+    const identityStream = supervisor.stdio[HOST_IDENTITY_FD];
+    const identityFrames = readFramedRecords(identityStream)[Symbol.asyncIterator]();
+    let output = null;
+    let identity = null;
+    let descriptorCommitted = false;
+    let cleanupAuthority = PRE_READY_CLEANUP_AUTHORITY.unprobed;
+    try {
+        output = attachSupervisorOutput(supervisor);
+        await writeFramedRecord(control, {
+            kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.bootstrap,
+            runtimeDirectory,
+            shimEntryPath: input.shimEntryPath,
+            worker: input.worker,
+            timing: input.timing,
+        });
+        identity = await readSupervisorIdentity(identityFrames);
+        let hostAckComplete = false;
+        const readinessObservation = observeSupervisorReadiness(identityFrames, () => hostAckComplete);
+        await input.lifecycle.beforeExec(identity);
+        descriptorCommitted = true;
+        await writeFramedRecord(control, {
+            kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.hostAck,
+        });
+        hostAckComplete = true;
+        control.end();
+        const readiness = await concludeSupervisorReadiness({
+            observation: readinessObservation,
+            identity,
+            runtimeDirectory,
+            supervisorClose,
+            timing: input.timing,
+        });
+        if (readiness.kind === "failure") {
+            cleanupAuthority = readiness.cleanupAuthority;
+            throw readiness.error;
+        }
+        const readyIdentity = identity;
+        let terminationRequested = false;
+        const completion = settleControlledProcess({
+            identity: readyIdentity,
+            runtimeDirectory,
+            outputClosed: output.closed,
+            supervisorClose,
+            lifecycle: input.lifecycle,
+            terminationRequested: () => terminationRequested,
+        });
+        void completion.catch(() => undefined);
+        let requested = null;
+        return {
+            identity: readyIdentity,
+            chunks: output.queue,
+            completion,
+            requestTermination: () => {
+                requested ??= (async () => {
+                    terminationRequested = true;
+                    await requestTermination(readyIdentity, runtimeDirectory, supervisorClose);
+                    return completion;
+                })();
+                return requested;
+            },
+        };
+    }
+    catch (primaryFailure) {
+        if (primaryFailure instanceof SupervisorReportedLaunchFailure) {
+            cleanupAuthority = PRE_READY_CLEANUP_AUTHORITY.reportedFailure;
+        }
+        try {
+            await cleanupPreReadySupervisor({
+                control,
+                identity,
+                descriptorCommitted,
+                runtimeDirectory,
+                output,
+                supervisorClose,
+                lifecycle: input.lifecycle,
+                timing: input.timing,
+                cleanupAuthority,
+            });
+        }
+        catch (cleanupFailure) {
+            throw new AggregateError([primaryFailure, cleanupFailure], "Controlled process launch and pre-ready cleanup both failed.");
+        }
+        throw primaryFailure;
+    }
+}
+function observeSupervisorReadiness(frames, hostAckComplete) {
+    return frames.next().then((result) => ({
+        kind: "result",
+        result,
+        observedBeforeHostAck: !hostAckComplete(),
+    }), (error) => ({
+        kind: "failure",
+        error,
+        observedBeforeHostAck: !hostAckComplete(),
+    }));
+}
+async function concludeSupervisorReadiness(input) {
+    const observation = await input.observation;
+    if (observation.observedBeforeHostAck) {
+        return readinessFailure(new Error("Supervisor readiness arrived before host ACK completed."), PRE_READY_CLEANUP_AUTHORITY.unprobed);
+    }
+    if (observation.kind === "failure") {
+        return readinessFailure(observation.error, PRE_READY_CLEANUP_AUTHORITY.unprobed);
+    }
+    if (!observation.result.done) {
+        const failure = supervisorLaunchFailedFrameSchema.safeParse(observation.result.value);
+        if (failure.success) {
+            return readinessFailure(new Error(failure.data.reason), PRE_READY_CLEANUP_AUTHORITY.rollbackCompleted);
+        }
+        return readinessFailure(new Error("Supervisor readiness frame is invalid."), PRE_READY_CLEANUP_AUTHORITY.unprobed);
+    }
+    const probe = await raceSupervisorRequestWithClose({
+        identity: input.identity,
+        runtimeDirectory: input.runtimeDirectory,
+        requestKind: SUPERVISOR_REQUEST_KIND.probe,
+        supervisorClose: input.supervisorClose,
+        deadline: preReadyCleanupDeadline(input.timing),
+    });
+    if (probe.kind === "closed") {
+        return readinessFailure(new Error("Supervisor closed before readiness was proven."), PRE_READY_CLEANUP_AUTHORITY.unavailable);
+    }
+    if (probe.kind === "failure") {
+        return readinessFailure(probe.error, PRE_READY_CLEANUP_AUTHORITY.unavailable);
+    }
+    if (probe.kind === "deadline") {
+        return readinessFailure(probe.error, PRE_READY_CLEANUP_AUTHORITY.unavailable);
+    }
+    if (probe.response.kind !== SUPERVISOR_RESPONSE_KIND.termination) {
+        return readinessFailure(new Error("Supervisor readiness probe returned an invalid response."), PRE_READY_CLEANUP_AUTHORITY.live);
+    }
+    const { result, workerExit } = probe.response;
+    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.pending) {
+        return { kind: "ready" };
+    }
+    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent &&
+        workerExit !== null) {
+        return { kind: "ready" };
+    }
+    return readinessFailure(new Error(`Supervisor readiness probe did not prove a runnable process: ${result.kind}.`), PRE_READY_CLEANUP_AUTHORITY.live);
+}
+function readinessFailure(error, cleanupAuthority) {
+    return { kind: "failure", error, cleanupAuthority };
+}
+async function settleControlledProcess(input) {
+    const snapshot = await waitForTermination(input.identity, input.runtimeDirectory, input.supervisorClose);
+    const { result, workerExit } = snapshot;
+    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.pending) {
+        throw new Error("Controlled process completion remained pending.");
+    }
+    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.unkillable) {
+        return { ...result, workerExit };
+    }
+    await input.outputClosed;
+    if (workerExit === null &&
+        snapshot.source === TERMINATION_OBSERVATION_SOURCE.liveResponse &&
+        !input.terminationRequested()) {
+        throw new Error("Natural controlled process completion lacks worker exit evidence.");
+    }
+    await input.lifecycle.afterTermination(terminationEvidenceFromSnapshot(input.identity, result.proof, snapshot));
+    await releaseAfterLifecycleClosure({
+        identity: input.identity,
+        runtimeDirectory: input.runtimeDirectory,
+        supervisorClose: input.supervisorClose,
+        observedSupervisorExit: snapshot.supervisorExit,
+    });
+    return { ...result, workerExit };
+}
+async function cleanupPreReadySupervisor(input) {
+    if (!input.control.destroyed && !input.control.writableEnded) {
+        input.control.end();
+    }
+    if (input.output !== null) {
+        await input.output.queue[Symbol.asyncIterator]().return?.();
+    }
+    if (input.identity === null &&
+        input.cleanupAuthority === PRE_READY_CLEANUP_AUTHORITY.reportedFailure &&
+        !input.supervisorClose.didClose() &&
+        (await input.supervisorClose.observeAfterRequestSettlement()) === null) {
+        return;
+    }
+    if (input.identity === null || !input.descriptorCommitted) {
+        await cleanupAfterSupervisorClose(input);
+        return;
+    }
+    if (input.cleanupAuthority === PRE_READY_CLEANUP_AUTHORITY.rollbackCompleted ||
+        input.supervisorClose.didClose()) {
+        await cleanupAfterSupervisorClose(input);
+        return;
+    }
+    if (input.cleanupAuthority === PRE_READY_CLEANUP_AUTHORITY.unavailable) {
+        throw new Error("Pre-ready controlled process cleanup lacks live supervisor authority.");
+    }
+    const deadline = preReadyCleanupDeadline(input.timing);
+    if (input.cleanupAuthority === PRE_READY_CLEANUP_AUTHORITY.unprobed) {
+        const probe = await raceSupervisorRequestWithClose({
+            identity: input.identity,
+            runtimeDirectory: input.runtimeDirectory,
+            requestKind: SUPERVISOR_REQUEST_KIND.probe,
+            supervisorClose: input.supervisorClose,
+            deadline,
+        });
+        if (probe.kind === "closed") {
+            await cleanupAfterSupervisorClose(input);
+            return;
+        }
+        if (probe.kind === "failure") {
+            throw probe.error;
+        }
+        if (probe.kind === "deadline") {
+            throw probe.error;
+        }
+    }
+    await terminatePreReadySupervisor({
+        identity: input.identity,
+        runtimeDirectory: input.runtimeDirectory,
+        lifecycle: input.lifecycle,
+        supervisorClose: input.supervisorClose,
+        output: input.output,
+        deadline,
+    });
+}
+async function terminatePreReadySupervisor(input) {
+    let snapshot = await requestTerminationBeforeDeadline({
+        identity: input.identity,
+        runtimeDirectory: input.runtimeDirectory,
+        requestKind: SUPERVISOR_REQUEST_KIND.terminate,
+        supervisorClose: input.supervisorClose,
+        deadline: input.deadline,
+    });
+    if (snapshot === null) {
+        await cleanupAfterSupervisorClose({
+            ...input,
+            descriptorCommitted: true,
+        });
+        return;
+    }
+    while (snapshot.result.kind === CHILD_PROCESS_TERMINATION_KIND.pending) {
+        await beforeDeadline(delay(snapshot.result.retryAfterMs), input.deadline, "Pre-ready supervisor termination timed out.");
+        snapshot = await requestTerminationBeforeDeadline({
+            identity: input.identity,
+            runtimeDirectory: input.runtimeDirectory,
+            requestKind: SUPERVISOR_REQUEST_KIND.probe,
+            supervisorClose: input.supervisorClose,
+            deadline: input.deadline,
+        });
+        if (snapshot === null) {
+            await cleanupAfterSupervisorClose({
+                ...input,
+                descriptorCommitted: true,
+            });
+            return;
+        }
+    }
+    if (snapshot.result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error(`Pre-ready supervisor termination did not prove absence: ${snapshot.result.kind}.`);
+    }
+    let lifecycleFailure = null;
+    try {
+        await input.lifecycle.afterTermination(terminationEvidenceFromSnapshot(input.identity, snapshot.result.proof, snapshot));
+    }
+    catch (error) {
+        lifecycleFailure = { error };
+    }
+    try {
+        await releaseAfterLifecycleClosure({
+            identity: input.identity,
+            runtimeDirectory: input.runtimeDirectory,
+            supervisorClose: input.supervisorClose,
+            deadline: input.deadline,
+        });
+    }
+    catch (releaseFailure) {
+        if (lifecycleFailure !== null) {
+            throw new AggregateError([lifecycleFailure.error, releaseFailure], "Pre-ready lifecycle closure and supervisor release both failed.");
+        }
+        throw releaseFailure;
+    }
+    if (lifecycleFailure !== null) {
+        throw lifecycleFailure.error;
+    }
+    if (input.output !== null) {
+        await input.output.closed;
+    }
+}
+async function requestTerminationBeforeDeadline(input) {
+    const raced = await raceSupervisorRequestWithClose(input);
+    if (raced.kind === "closed") {
+        return null;
+    }
+    if (raced.kind === "failure" || raced.kind === "deadline") {
+        throw raced.error;
+    }
+    if (raced.response.kind !== SUPERVISOR_RESPONSE_KIND.termination) {
+        throw new Error("Supervisor rejected termination request.");
+    }
+    return {
+        result: raced.response.result,
+        workerExit: raced.response.workerExit,
+        source: TERMINATION_OBSERVATION_SOURCE.liveResponse,
+        supervisorExit: null,
+    };
+}
+async function raceSupervisorRequestWithClose(input) {
+    if (input.supervisorClose.didClose()) {
+        return {
+            kind: "closed",
+            exit: await input.supervisorClose.promise,
+        };
+    }
+    const controller = new AbortController();
+    const response = requestLiveSupervisor(input.identity, input.runtimeDirectory, input.requestKind, controller.signal).then((value) => ({ kind: "response", response: value }), (error) => ({ kind: "failure", error }));
+    const closed = input.supervisorClose.promise.then((exit) => ({ kind: "closed", exit }));
+    let cancelDeadline = () => { };
+    const racers = [response, closed];
+    if (input.deadline !== null) {
+        const deadline = input.deadline;
+        const deadlineFailure = new Error("Pre-ready supervisor request timed out.");
+        racers.push(new Promise((resolve) => {
+            const timeout = setTimeout(() => resolve({ kind: "deadline", error: deadlineFailure }), Math.max(0, deadline - Date.now()));
+            cancelDeadline = () => clearTimeout(timeout);
+        }));
+    }
+    const result = await Promise.race(racers);
+    cancelDeadline();
+    if (result.kind === "response" || result.kind === "failure") {
+        const exit = await input.supervisorClose.observeAfterRequestSettlement();
+        if (exit !== null) {
+            return { kind: "closed", exit };
+        }
+    }
+    if (result.kind === "closed" || result.kind === "deadline") {
+        controller.abort(result.kind === "closed"
+            ? new Error("Supervisor closed during a live request.")
+            : result.error);
+        await response;
+    }
+    return result;
+}
+function preReadyCleanupDeadline(timing) {
+    const budget = Math.min(Number.MAX_SAFE_INTEGER, timing.termGraceMs + timing.killProbeTimeoutMs + timing.probeIntervalMs);
+    return Math.min(Number.MAX_SAFE_INTEGER, Date.now() + budget);
+}
+function beforeDeadline(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);
+        });
+    });
+}
+async function cleanupAfterSupervisorClose(input) {
+    await input.supervisorClose.promise;
+    if (input.output !== null) {
+        await input.output.closed;
+    }
+    if (input.identity === null) {
+        return;
+    }
+    const result = await resolveOfflineTermination(input.identity, input.runtimeDirectory, "child_close");
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error(`Pre-ready controlled process cleanup did not prove absence: ${result.kind}.`);
+    }
+    if (input.descriptorCommitted) {
+        await input.lifecycle.afterTermination(offlineAbsenceEvidence(input.identity, result.proof));
+        await releaseOfflineControlledProcess(input.identity, input.runtimeDirectory);
+    }
+}
+async function requestTermination(identity, runtimeDirectory, supervisorClose) {
+    const raced = await raceSupervisorRequestWithClose({
+        identity,
+        runtimeDirectory,
+        requestKind: SUPERVISOR_REQUEST_KIND.terminate,
+        supervisorClose,
+        deadline: null,
+    });
+    if (raced.kind === "failure" || raced.kind === "deadline") {
+        throw raced.error;
+    }
+    if (raced.kind === "closed") {
+        await resolveOfflineTermination(identity, runtimeDirectory, "child_close");
+        return;
+    }
+    if (raced.response.kind !== SUPERVISOR_RESPONSE_KIND.termination) {
+        throw new Error("Supervisor rejected termination.");
+    }
+}
+async function waitForTermination(identity, runtimeDirectory, supervisorClose) {
+    for (;;) {
+        const snapshot = await resolveTermination(identity, runtimeDirectory, SUPERVISOR_REQUEST_KIND.probe, supervisorClose);
+        if (snapshot.result.kind !== CHILD_PROCESS_TERMINATION_KIND.pending) {
+            return snapshot;
+        }
+        await delay(snapshot.result.retryAfterMs);
+    }
+}
+async function resolveTermination(identity, runtimeDirectory, requestKind, supervisorClose) {
+    if (supervisorClose !== null) {
+        const raced = await raceSupervisorRequestWithClose({
+            identity,
+            runtimeDirectory,
+            requestKind,
+            supervisorClose,
+            deadline: null,
+        });
+        if (raced.kind === "closed") {
+            return {
+                result: await resolveOfflineTermination(identity, runtimeDirectory, "child_close"),
+                workerExit: null,
+                source: TERMINATION_OBSERVATION_SOURCE.supervisorClose,
+                supervisorExit: raced.exit,
+            };
+        }
+        if (raced.kind === "deadline") {
+            throw raced.error;
+        }
+        if (raced.kind === "failure") {
+            const classified = classifyLiveRequestFailure(raced.error);
+            if (classified !== null) {
+                return classified;
+            }
+            throw raced.error;
+        }
+        return snapshotFromResponse(raced.response);
+    }
+    const controller = new AbortController();
+    try {
+        const response = await requestLiveSupervisor(identity, runtimeDirectory, requestKind, controller.signal);
+        return snapshotFromResponse(response);
+    }
+    catch (error) {
+        const classified = classifyLiveRequestFailure(error);
+        if (classified !== null) {
+            return classified;
+        }
+        return {
+            result: await resolveOfflineTermination(identity, runtimeDirectory, "fresh_host"),
+            workerExit: null,
+            source: TERMINATION_OBSERVATION_SOURCE.offlineFallback,
+            supervisorExit: null,
+        };
+    }
+}
+function snapshotFromResponse(response) {
+    if (response.kind === SUPERVISOR_RESPONSE_KIND.termination) {
+        return {
+            result: response.result,
+            workerExit: response.workerExit,
+            source: TERMINATION_OBSERVATION_SOURCE.liveResponse,
+            supervisorExit: null,
+        };
+    }
+    return {
+        result: unkillable(CHILD_PROCESS_UNKILLABLE_REASON.protocolFailure),
+        workerExit: null,
+        source: TERMINATION_OBSERVATION_SOURCE.liveResponse,
+        supervisorExit: null,
+    };
+}
+function classifyLiveRequestFailure(error) {
+    if (!(error instanceof Error) ||
+        error.message !== "Supervisor socket authentication failed.") {
+        return null;
+    }
+    return {
+        result: unkillable(CHILD_PROCESS_UNKILLABLE_REASON.recordAuthenticationFailed),
+        workerExit: null,
+        source: TERMINATION_OBSERVATION_SOURCE.liveRequestFailure,
+        supervisorExit: null,
+    };
+}
+export async function recoverControlledProcess(input) {
+    const { result } = await resolveTermination(input.identity, input.runtimeDirectory, SUPERVISOR_REQUEST_KIND.terminate, null);
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        return result;
+    }
+    if (result.proof === CHILD_PROCESS_ABSENCE_PROOF.releasedReceipt) {
+        return result;
+    }
+    await input.lifecycle.afterTermination(offlineAbsenceEvidence(input.identity, result.proof));
+    if (result.proof === CHILD_PROCESS_ABSENCE_PROOF.supervisorProbe) {
+        await releaseRecoveredControlledProcess(input.identity, input.runtimeDirectory);
+    }
+    else if (result.proof === CHILD_PROCESS_ABSENCE_PROOF.bootChanged) {
+        await releaseOfflineControlledProcess(input.identity, input.runtimeDirectory);
+    }
+    return result;
+}
+async function releaseRecoveredControlledProcess(identity, runtimeDirectory) {
+    const controller = new AbortController();
+    const response = await requestLiveSupervisor(identity, runtimeDirectory, SUPERVISOR_REQUEST_KIND.release, controller.signal);
+    if (response.kind !== SUPERVISOR_RESPONSE_KIND.released) {
+        throw new Error("Supervisor rejected release.");
+    }
+}
+async function releaseOfflineControlledProcess(identity, runtimeDirectory) {
+    const token = decodeProcessStartToken(identity.processStartToken);
+    const platform = createSupervisorPlatformAdapter();
+    const secureRuntimeDirectory = await assertSecureRuntimeDirectory(runtimeDirectory, platform.uid);
+    const store = new SignedRecordStore(secureRuntimeDirectory, token.recordId, platform.uid);
+    const signed = await store.read();
+    if (!controlledProcessRecordMatchesToken(signed.record, token) ||
+        signed.record.pid !== identity.pid ||
+        !verifySignedControlledProcessRecord(signed, identity)) {
+        throw new Error("Offline controlled process release authentication failed.");
+    }
+    if (signed.record.state === CONTROLLED_PROCESS_STATE.released) {
+        return;
+    }
+    if (signed.record.state !== CONTROLLED_PROCESS_STATE.absent) {
+        throw new Error("Offline controlled process release requires absence.");
+    }
+    const released = {
+        ...signed.record,
+        state: transitionControlledProcess(signed.record.state, CONTROLLED_PROCESS_STATE.released),
+        absenceProof: signed.record.absenceProof,
+    };
+    await store.write(signControlledProcessRecord(released, token.capability));
+}
+async function resolveOfflineTermination(identityInput, runtimeDirectory, authority) {
+    const identity = controlledProcessIdentitySchema.safeParse(identityInput);
+    if (!identity.success) {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.invalidIdentity);
+    }
+    let token;
+    try {
+        token = decodeProcessStartToken(identity.data.processStartToken);
+    }
+    catch {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.invalidIdentity);
+    }
+    const platform = createSupervisorPlatformAdapter();
+    let secureRuntimeDirectory;
+    try {
+        secureRuntimeDirectory = await assertSecureRuntimeDirectory(runtimeDirectory, platform.uid);
+    }
+    catch {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.recordAuthenticationFailed);
+    }
+    let signed;
+    try {
+        signed = await new SignedRecordStore(secureRuntimeDirectory, token.recordId, platform.uid).read();
+    }
+    catch {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.recordAuthenticationFailed);
+    }
+    if (!controlledProcessRecordMatchesToken(signed.record, token) ||
+        signed.record.pid !== identity.data.pid) {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.recordIdentityMismatch);
+    }
+    if (!verifySignedControlledProcessRecord(signed, identity.data)) {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.recordAuthenticationFailed);
+    }
+    if (signed.record.state === CONTROLLED_PROCESS_STATE.released) {
+        return {
+            kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+            proof: CHILD_PROCESS_ABSENCE_PROOF.releasedReceipt,
+        };
+    }
+    if (signed.record.state === CONTROLLED_PROCESS_STATE.absent) {
+        if (signed.record.absenceProof === null) {
+            return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.protocolFailure);
+        }
+        if (authority === "fresh_host" &&
+            signed.record.absenceProof === CHILD_PROCESS_ABSENCE_PROOF.supervisorProbe) {
+            let currentBootId;
+            try {
+                currentBootId = await platform.bootId();
+            }
+            catch {
+                return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.bootIdentityUnavailable);
+            }
+            if (currentBootId === token.bootId) {
+                return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.supervisorUnreachable);
+            }
+            const bootChanged = {
+                ...signed.record,
+                absenceProof: CHILD_PROCESS_ABSENCE_PROOF.bootChanged,
+            };
+            await new SignedRecordStore(secureRuntimeDirectory, token.recordId, platform.uid).write(signControlledProcessRecord(bootChanged, token.capability));
+            return {
+                kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+                proof: CHILD_PROCESS_ABSENCE_PROOF.bootChanged,
+            };
+        }
+        return {
+            kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+            proof: signed.record.absenceProof,
+        };
+    }
+    let currentBootId;
+    try {
+        currentBootId = await platform.bootId();
+    }
+    catch {
+        return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.bootIdentityUnavailable);
+    }
+    if (currentBootId !== token.bootId) {
+        const absent = {
+            ...signed.record,
+            state: transitionControlledProcess(signed.record.state, CONTROLLED_PROCESS_STATE.absent),
+            absenceProof: CHILD_PROCESS_ABSENCE_PROOF.bootChanged,
+        };
+        await new SignedRecordStore(secureRuntimeDirectory, token.recordId, platform.uid).write(signControlledProcessRecord(absent, token.capability));
+        return {
+            kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+            proof: CHILD_PROCESS_ABSENCE_PROOF.bootChanged,
+        };
+    }
+    return unkillable(CHILD_PROCESS_UNKILLABLE_REASON.supervisorUnreachable);
+}
+async function releaseAfterLifecycleClosure(input) {
+    const raced = input.observedSupervisorExit === undefined ||
+        input.observedSupervisorExit === null
+        ? await raceSupervisorRequestWithClose({
+            ...input,
+            requestKind: SUPERVISOR_REQUEST_KIND.release,
+            deadline: input.deadline ?? null,
+        })
+        : {
+            kind: "closed",
+            exit: input.observedSupervisorExit,
+        };
+    if (raced.kind === "failure" || raced.kind === "deadline") {
+        throw raced.error;
+    }
+    if (raced.kind === "response") {
+        if (raced.response.kind !== SUPERVISOR_RESPONSE_KIND.released) {
+            throw new Error("Supervisor rejected release.");
+        }
+        assertSuccessfulSupervisorClose(await input.supervisorClose.promise);
+        return;
+    }
+    const result = await resolveOfflineTermination(input.identity, input.runtimeDirectory, "child_close");
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error(`Supervisor closed before release could be confirmed: ${result.kind}.`);
+    }
+    if (result.proof !== CHILD_PROCESS_ABSENCE_PROOF.releasedReceipt) {
+        await releaseOfflineControlledProcess(input.identity, input.runtimeDirectory);
+    }
+    assertSuccessfulSupervisorClose(raced.exit);
+}
+function assertSuccessfulSupervisorClose(exit) {
+    if (exit.code === 0 && exit.signal === null) {
+        return;
+    }
+    throw new Error(`Controlled process supervisor exited abnormally: ${JSON.stringify(exit)}.`);
+}
+async function requestLiveSupervisor(identity, runtimeDirectory, kind, signal) {
+    const token = decodeProcessStartToken(identity.processStartToken);
+    const platform = createSupervisorPlatformAdapter();
+    await assertSecureRuntimeDirectory(runtimeDirectory, platform.uid);
+    const socketDirectory = await resolveSupervisorSocketNamespace(token.platform, platform.uid);
+    return requestSupervisor({
+        socketPath: supervisorSocketPath({
+            socketDirectory,
+            socketLocator: token.socketLocator,
+            platform: token.platform,
+        }),
+        uid: platform.uid,
+        recordId: token.recordId,
+        capability: token.capability,
+        request: { kind },
+        signal,
+    });
+}
+function spawnSupervisor(entryPath) {
+    const child = spawn(process.execPath, [entryPath], {
+        detached: true,
+        env: {},
+        stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+    });
+    child.once("error", () => { });
+    return child;
+}
+function observeSupervisorClose(supervisor, receiptGraceMs) {
+    let closed = false;
+    let exited = false;
+    const exitObserved = new Promise((resolve) => {
+        supervisor.once("exit", () => {
+            exited = true;
+            resolve();
+        });
+    });
+    const promise = new Promise((resolve) => {
+        supervisor.once("close", (code, signal) => {
+            closed = true;
+            resolve({ code, signal });
+        });
+    });
+    return {
+        promise,
+        didClose: () => closed,
+        observeAfterRequestSettlement: async () => {
+            if (closed || exited) {
+                return promise;
+            }
+            const observed = await observeSupervisorExitWithin(exitObserved, receiptGraceMs);
+            return observed || closed ? promise : null;
+        },
+    };
+}
+function observeSupervisorExitWithin(exitObserved, graceMs) {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => resolve(false), graceMs);
+        exitObserved.then(() => {
+            clearTimeout(timeout);
+            resolve(true);
+        });
+    });
+}
+async function readSupervisorIdentity(frames) {
+    const frame = await readRequiredFrame(frames);
+    const identity = supervisorIdentityFrameSchema.safeParse(frame);
+    if (identity.success) {
+        return identity.data.identity;
+    }
+    const failure = supervisorLaunchFailedFrameSchema.safeParse(frame);
+    if (failure.success) {
+        throw new SupervisorReportedLaunchFailure(failure.data.reason);
+    }
+    throw new Error("Supervisor identity frame is invalid.");
+}
+function attachSupervisorOutput(supervisor) {
+    const stdout = requireSupervisorOutput(supervisor.stdout, "stdout");
+    const stderr = requireSupervisorOutput(supervisor.stderr, "stderr");
+    const queue = new ControlledProcessOutputQueue([stdout, stderr]);
+    let closeOutput = () => { };
+    const closed = new Promise((resolve) => {
+        closeOutput = resolve;
+    });
+    let streamsClosed = 0;
+    const attach = (stream, channel) => {
+        stream.setEncoding("utf8");
+        stream.on("data", (text) => queue.push({ channel, text }));
+        stream.once("close", () => {
+            streamsClosed += 1;
+            if (streamsClosed === 2) {
+                queue.end();
+                closeOutput();
+            }
+        });
+    };
+    attach(stdout, OUTPUT_CHANNEL_KIND.stdout);
+    attach(stderr, OUTPUT_CHANNEL_KIND.stderr);
+    return { queue, closed };
+}
+class ControlledProcessOutputQueue {
+    sources;
+    buffered = [];
+    waiters = [];
+    bufferedBytes = 0;
+    ended = false;
+    abandoned = false;
+    paused = false;
+    constructor(sources) {
+        this.sources = sources;
+    }
+    push(value) {
+        if (this.ended || this.abandoned) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            waiter({ value, done: false });
+            return;
+        }
+        const bytes = Buffer.byteLength(value.text, "utf8");
+        this.buffered.push({ value, bytes });
+        this.bufferedBytes += bytes;
+        if (!this.paused && this.bufferedBytes >= OUTPUT_QUEUE_HIGH_WATER_BYTES) {
+            this.paused = true;
+            for (const source of this.sources) {
+                source.pause();
+            }
+        }
+    }
+    end() {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+            return: () => this.abandon(),
+        };
+    }
+    next() {
+        const entry = this.buffered.shift();
+        if (entry !== undefined) {
+            this.bufferedBytes -= entry.bytes;
+            this.resumeSourcesWhenDrained();
+            return Promise.resolve({ value: entry.value, done: false });
+        }
+        if (this.ended || this.abandoned) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    abandon() {
+        if (!this.abandoned) {
+            this.abandoned = true;
+            this.buffered.splice(0);
+            this.bufferedBytes = 0;
+            for (const waiter of this.waiters.splice(0)) {
+                waiter({ value: undefined, done: true });
+            }
+            for (const source of this.sources) {
+                source.resume();
+            }
+        }
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    resumeSourcesWhenDrained() {
+        if (this.paused && this.bufferedBytes <= OUTPUT_QUEUE_LOW_WATER_BYTES) {
+            this.paused = false;
+            for (const source of this.sources) {
+                source.resume();
+            }
+        }
+    }
+}
+function requireSupervisorOutput(stream, channel) {
+    if (stream === null) {
+        throw new Error(`Supervisor ${channel} stream is unavailable.`);
+    }
+    return stream;
+}
+function unkillable(reason) {
+    return { kind: CHILD_PROCESS_TERMINATION_KIND.unkillable, reason };
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function terminationEvidenceFromSnapshot(identity, proof, snapshot) {
+    if (snapshot.source === TERMINATION_OBSERVATION_SOURCE.liveResponse &&
+        snapshot.workerExit !== null) {
+        return {
+            kind: CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.liveChildClose,
+            identity,
+            proof,
+            workerExit: snapshot.workerExit,
+        };
+    }
+    return offlineAbsenceEvidence(identity, proof);
+}
+function offlineAbsenceEvidence(identity, proof) {
+    return {
+        kind: CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.offlineAbsence,
+        identity,
+        proof,
+    };
+}