@timurproko/a1 0.2.7-dev.1249 → 0.2.7-dev.1252

package/dist/foundation/supervision/server.d.ts

@@ -1,46 +0,0 @@
-import { rename, rm, writeFile } from "node:fs/promises";
-import { type SupervisorSnapshot } from "../lifecycle/index.js";
-import { type MaterializedRelease } from "../release/index.js";
-import { ControlStore } from "../storage/index.js";
-import { type ProductPaths } from "./paths.js";
-interface EndpointMetadataCommitOperations {
-    readonly platform?: NodeJS.Platform;
-    readonly write?: typeof writeFile;
-    readonly replace?: typeof rename;
-    readonly remove?: typeof rm;
-    readonly wait?: (delayMs: number) => Promise<void>;
-}
-/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
-export declare function commitEndpointMetadata(path: string, source: string, operations?: EndpointMetadataCommitOperations): Promise<void>;
-/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
-export declare class SupervisorServer {
-    #private;
-    readonly id: `${string}-${string}-${string}-${string}-${string}`;
-    readonly bootNonce: string;
-    readonly pidStartIdentity: string;
-    readonly startedAt: string;
-    readonly paths: ProductPaths;
-    readonly store: ControlStore;
-    readonly release: MaterializedRelease;
-    readonly terminateProcess: (code: number) => void;
-    readonly reconciliationDeadlineMs: number;
-    readonly shutdownDeadlineMs: number;
-    readonly readActiveReleaseId: (() => Promise<string | null>) | null;
-    readonly supersededPollMs: number;
-    constructor(store: ControlStore, paths: ProductPaths | undefined, release: MaterializedRelease, bootNonce?: string, terminateProcess?: (code: number) => void, reconciliationDeadlineMs?: number, shutdownDeadlineMs?: number, 
-    /**
-     * Which release new sessions start on. A cohort that is no longer that release keeps
-     * serving the instances it already has, takes no new ones, and exits when its last one
-     * leaves. Absent, this supervisor never considers itself superseded.
-     */
-    readActiveReleaseId?: (() => Promise<string | null>) | null, supersededPollMs?: number);
-    snapshot(): SupervisorSnapshot;
-    listen(): Promise<void>;
-    /** Whether new sessions start on some other release. */
-    get superseded(): boolean;
-    /** Leaves, taking this cohort's own endpoint artifacts with it. */
-    retire(): Promise<void>;
-    close(stopAgents?: boolean): Promise<void>;
-    closeForReleaseReplacement(stopAgents: boolean): Promise<void>;
-}
-export {};

package/dist/foundation/supervision/server.js

@@ -1,611 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { createConnection, createServer } from "node:net";
-import { platform } from "node:os";
-import { dirname } from "node:path";
-import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
-import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
-import { listRecordedEndpoints, readEndpointMetadata, supervisorProcessState, currentSupervisorStartIdentity, withEndpointLock, processIsAlive } from "../release/index.js";
-import { ControlStore } from "../storage/index.js";
-import { resolveProductPaths } from "./paths.js";
-import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-const WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160];
-/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
-export async function commitEndpointMetadata(path, source, operations = {}) {
-    const temporary = `${path}.${process.pid}.tmp`;
-    const write = operations.write ?? writeFile;
-    const replace = operations.replace ?? rename;
-    const remove = operations.remove ?? rm;
-    const wait = operations.wait ?? (delayMs => new Promise(resolvePromise => setTimeout(resolvePromise, delayMs)));
-    let committed = false;
-    try {
-        await write(temporary, source, { mode: 0o600 });
-        for (let attempt = 0;; attempt += 1) {
-            try {
-                await replace(temporary, path);
-                committed = true;
-                return;
-            }
-            catch (error) {
-                const delayMs = WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS[attempt];
-                if ((operations.platform ?? platform()) !== "win32" || delayMs === undefined || !isWindowsSharingViolation(error))
-                    throw error;
-                await wait(delayMs);
-            }
-        }
-    }
-    finally {
-        if (!committed)
-            await remove(temporary, { force: true }).catch(() => undefined);
-    }
-}
-/** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
-export class SupervisorServer {
-    id = randomUUID();
-    bootNonce;
-    pidStartIdentity = currentSupervisorStartIdentity();
-    startedAt = new Date().toISOString();
-    paths;
-    #server = null;
-    #ownsEndpoint = false;
-    #instances = new Map();
-    #instanceOwners = new Map();
-    #clientIds = new Map();
-    #clientInstances = new Map();
-    #uncertainInstances = new Set();
-    #reconciliations = new Map();
-    #revision = 0;
-    #clients = new Set();
-    #results = new Map();
-    #metadataWrites = Promise.resolve();
-    #closing = false;
-    #superseded = false;
-    #supersededPoll = null;
-    store;
-    release;
-    terminateProcess;
-    reconciliationDeadlineMs;
-    shutdownDeadlineMs;
-    readActiveReleaseId;
-    supersededPollMs;
-    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500, 
-    /**
-     * Which release new sessions start on. A cohort that is no longer that release keeps
-     * serving the instances it already has, takes no new ones, and exits when its last one
-     * leaves. Absent, this supervisor never considers itself superseded.
-     */
-    readActiveReleaseId = null, supersededPollMs = 1_000) {
-        this.store = store;
-        this.release = release;
-        this.terminateProcess = terminateProcess;
-        this.reconciliationDeadlineMs = reconciliationDeadlineMs;
-        this.shutdownDeadlineMs = shutdownDeadlineMs;
-        this.readActiveReleaseId = readActiveReleaseId;
-        this.supersededPollMs = supersededPollMs;
-        this.bootNonce = bootNonce;
-        this.paths = paths;
-        for (const instance of store.loadActiveLaunchInstances(bootNonce))
-            this.#instances.set(instance.id, instance);
-    }
-    snapshot() {
-        return {
-            revision: this.#revision,
-            activeInstances: [...this.#instances.values()].flatMap(instance => {
-                if (instance.state !== "requested" && instance.state !== "active" && instance.state !== "stopping")
-                    return [];
-                return [{ id: instance.id, profileId: instance.profileId, state: instance.state }];
-            }),
-        };
-    }
-    async listen() {
-        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
-            if (this.#server)
-                throw new Error("supervisor is already listening");
-            await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
-            await mkdir(this.paths.endpointsDir, { recursive: true, mode: 0o700 });
-            const recorded = await readEndpointMetadata(this.paths.endpointMetadataPath);
-            if (recorded && await supervisorProcessState(recorded) !== "gone") {
-                throw Object.assign(new Error("another supervisor still owns this endpoint"), { code: "EADDRINUSE" });
-            }
-            if (platform() !== "win32") {
-                if (this.paths.endpointDirectory)
-                    await ensureManagedEndpointDirectory(dirname(this.paths.endpoint));
-                const existing = await lstat(this.paths.endpoint).catch(error => {
-                    if (error.code === "ENOENT")
-                        return null;
-                    throw error;
-                });
-                if (existing) {
-                    if (await endpointIsLive(this.paths.endpoint)) {
-                        throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`)), { code: "EADDRINUSE" });
-                    }
-                    await rm(this.paths.endpoint, { force: true });
-                }
-            }
-            const server = createServer(socket => this.#attach(socket));
-            this.#server = server;
-            await new Promise((resolve, reject) => {
-                server.once("error", reject);
-                server.listen(this.paths.endpoint, () => {
-                    this.#ownsEndpoint = true;
-                    server.off("error", reject);
-                    resolve();
-                });
-            });
-            // Concurrency: only the bound winner may reconcile shared control data. Other cohort boots
-            // remain protected even when temporarily unresponsive; their instances never become ours.
-            await withEndpointLock(this.paths.databasePath, async () => {
-                // Concurrency: all cohorts sharing SQLite serialize boot reconciliation plus publication, so a new
-                // cohort cannot insert instances between another cohort's inventory and stale-row update.
-                const protectedBoots = [];
-                for (const other of await listRecordedEndpoints(this.paths)) {
-                    if (other.paths.endpointMetadataPath !== this.paths.endpointMetadataPath
-                        && await supervisorProcessState(other.metadata) !== "gone")
-                        protectedBoots.push(other.metadata.bootNonce);
-                }
-                this.store.reconcilePriorBootLaunchInstances(this.bootNonce, new Date().toISOString(), protectedBoots);
-                await this.#writeEndpointMetadata();
-            });
-            if (this.readActiveReleaseId) {
-                const poll = setInterval(() => void this.#refreshCohortRole(), this.supersededPollMs);
-                poll.unref();
-                this.#supersededPoll = poll;
-            }
-        });
-    }
-    // Invariant: superseding a cohort never interrupts its held instances; it retires only when empty.
-    async #refreshCohortRole() {
-        if (this.#closing || !this.readActiveReleaseId)
-            return;
-        const active = await this.readActiveReleaseId().catch(() => null);
-        if (active === null)
-            return;
-        this.#superseded = active !== this.release.releaseId;
-        if (this.#superseded && this.#instances.size === 0)
-            await this.retire();
-    }
-    /** Whether new sessions start on some other release. */
-    get superseded() {
-        return this.#superseded;
-    }
-    /** Leaves, taking this cohort's own endpoint artifacts with it. */
-    async retire() {
-        if (this.#closing)
-            return;
-        await this.close(false);
-    }
-    async close(stopAgents = false) {
-        if (this.#closing)
-            return;
-        if (stopAgents && this.#ownsEndpoint && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
-            throw new Error("active launch instances did not release ownership within the shutdown deadline");
-        }
-        this.#closing = true;
-        if (this.#supersededPoll)
-            clearInterval(this.#supersededPoll);
-        this.#supersededPoll = null;
-        for (const client of this.#clients)
-            client.destroy();
-        // Concurrency: disconnect reconciliation can still commit a terminal outcome after its
-        // bounded process wait. Settle it before retiring the endpoint and closing shared storage.
-        await Promise.allSettled(this.#reconciliations.values());
-        await withEndpointLock(this.paths.endpointMetadataPath, async () => {
-            try {
-                await this.#metadataWrites.catch(() => undefined);
-                if (this.#ownsEndpoint) {
-                    // Concurrency: remove only our publication, before releasing the listening endpoint.
-                    // A contender that failed to bind must never erase the successful owner's discovery file.
-                    const metadata = await readFile(this.paths.endpointMetadataPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
-                    if (metadata?.supervisorId === this.id && metadata.bootNonce === this.bootNonce) {
-                        await rm(this.paths.endpointMetadataPath, { force: true });
-                    }
-                    // Platform: Node unlinks its Unix socket when the server closes; unlinking it early would
-                    // let a replacement bind before the old server finishes releasing that path.
-                }
-            }
-            finally {
-                // Platform: a metadata sharing error must not leave a bound but undiscoverable listener.
-                if (this.#server)
-                    await new Promise(resolve => this.#server?.close(() => resolve()));
-                this.#server = null;
-                this.#ownsEndpoint = false;
-                this.store.close();
-            }
-        });
-    }
-    async closeForReleaseReplacement(stopAgents) {
-        await this.close(stopAgents);
-        this.terminateProcess(0);
-    }
-    #attach(socket) {
-        socket.setNoDelay(true);
-        const decoder = new LineFrameDecoder();
-        let welcomed = false;
-        socket.on("data", chunk => {
-            try {
-                for (const value of decoder.push(chunk)) {
-                    if (!welcomed) {
-                        if (isMessageType(value, "identity-probe")) {
-                            this.#send(socket, { type: "identity", supervisorId: this.id, bootNonce: this.bootNonce, pidStartIdentity: this.pidStartIdentity, releaseId: this.release.releaseId });
-                            continue;
-                        }
-                        if (isMessageType(value, "release-idle-ownership")) {
-                            const request = value;
-                            const identityMatches = request.bootNonce === this.bootNonce && typeof request.candidateReleaseId === "string";
-                            const released = identityMatches && this.#instances.size === 0;
-                            this.#send(socket, {
-                                type: "release-ownership-result",
-                                released,
-                                reason: released ? "idle cohort released ownership"
-                                    : identityMatches ? "launch instances are still active" : "boot nonce or candidate release mismatch",
-                                liveInstanceIds: this.#liveInstanceIds(),
-                            });
-                            if (released)
-                                setTimeout(() => void this.closeForReleaseReplacement(false), 25);
-                            continue;
-                        }
-                        if (isMessageType(value, "release-update-ownership")) {
-                            const request = value;
-                            void this.#handleUpdateRelease(socket, request);
-                            continue;
-                        }
-                        if (!isControlHello(value)) {
-                            this.#send(socket, { type: "protocol-error", code: "invalid-control-handshake", message: `the first message must be a valid ${PRODUCT_TEXT.displayName} control feature handshake`, diagnostics: { received: value } });
-                            socket.destroy();
-                            return;
-                        }
-                        const serverHello = localControlHello();
-                        const negotiation = negotiateControlFeatures(value, serverHello);
-                        if (!negotiation.ok) {
-                            this.#send(socket, { type: "protocol-error", code: "incompatible-control-features", message: negotiation.diagnostic, diagnostics: negotiation });
-                            socket.destroy();
-                            return;
-                        }
-                        welcomed = true;
-                        this.#clients.add(socket);
-                        this.#clientIds.set(socket, value.clientId);
-                        this.#clientInstances.set(socket, new Set());
-                        this.#send(socket, { type: "server-hello", ...serverHello, releaseId: this.release.releaseId, supervisorId: this.id, bootNonce: this.bootNonce, pidStartIdentity: this.pidStartIdentity, negotiatedFeatures: negotiation.negotiatedFeatures, snapshot: this.snapshot() });
-                    }
-                    else if (isCommandMessage(value)) {
-                        void this.#execute(value.command, socket);
-                    }
-                }
-            }
-            catch (error) {
-                this.#send(socket, { type: "protocol-error", code: "framing-error", message: error instanceof Error ? error.message : String(error) });
-                socket.destroy();
-            }
-        });
-        socket.on("close", () => this.#onSocketClosed(socket));
-        socket.on("error", () => this.#onSocketClosed(socket));
-    }
-    async #execute(command, socket) {
-        const clientId = this.#clientIds.get(socket);
-        if (!clientId) {
-            this.#send(socket, { type: "protocol-error", code: "unauthenticated-command", message: "launch-instance commands require an authenticated client" });
-            return;
-        }
-        const resultKey = `${clientId}:${command.requestId}`;
-        const recorded = this.#results.get(resultKey);
-        if (recorded) {
-            this.#send(socket, { type: "command-result", result: recorded });
-            return;
-        }
-        let result;
-        try {
-            if (command.type === "create-launch-instance")
-                await this.#createLaunchInstance(command, socket, clientId);
-            if (command.type === "activate-launch-instance")
-                this.#activateLaunchInstance(command, socket, clientId);
-            if (command.type === "begin-launch-instance-stop")
-                this.#beginLaunchInstanceStop(command, socket, clientId);
-            if (command.type === "complete-launch-instance")
-                this.#completeLaunchInstance(command, socket, clientId);
-            if (command.type === "reconcile-launch-instance") {
-                this.#ownedInstance(command.instanceId, socket, clientId);
-                await this.#reconcileLaunchInstance(command.instanceId);
-            }
-            if (command.type === "resynchronize")
-                this.#send(socket, { type: "snapshot", snapshot: this.snapshot() });
-            await this.#metadataWrites;
-            result = { requestId: command.requestId, ok: true, revision: this.#revision };
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const explicitCode = error instanceof Error && "code" in error ? error.code : undefined;
-            const code = explicitCode === "release-superseded"
-                ? "release-superseded"
-                : /not found/i.test(message) ? "not-found"
-                    : /owner|ownership|authenticated/i.test(message) ? "ownership-error" : "driver-error";
-            result = { requestId: command.requestId, ok: false, revision: this.#revision, error: { code, message } };
-        }
-        this.#results.set(resultKey, result);
-        this.#send(socket, { type: "command-result", result });
-    }
-    async #createLaunchInstance(command, socket, clientId) {
-        assertNativeProcessIdentity(command.guardianIdentity);
-        const existing = this.store.loadLaunchInstance(command.instanceId);
-        if (!existing && this.readActiveReleaseId) {
-            const active = await this.readActiveReleaseId().catch(() => null);
-            if (active !== null)
-                this.#superseded = active !== this.release.releaseId;
-        }
-        if (this.#superseded && !existing) {
-            throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`release ${this.release.releaseId} is no longer active for new sessions`)), {
-                code: "release-superseded",
-            });
-        }
-        if (existing) {
-            if (existing.ownerClientId !== clientId
-                || existing.profileId !== command.profileId
-                || existing.shutdownPolicy !== command.shutdownPolicy
-                || !sameProcessIdentity(existing.guardianIdentity, command.guardianIdentity)) {
-                throw new Error("launch instance already exists with different authenticated ownership");
-            }
-            if (existing.state === "completed" || existing.state === "interrupted")
-                throw new Error("launch instance already has a terminal outcome");
-            this.#instances.set(existing.id, existing);
-            this.#bindOwner(existing.id, socket);
-            return;
-        }
-        const instance = {
-            id: command.instanceId,
-            ownerClientId: clientId,
-            profileId: command.profileId,
-            state: "requested",
-            shutdownPolicy: command.shutdownPolicy,
-            guardianIdentity: command.guardianIdentity,
-            rootIdentity: null,
-            containmentIdentity: null,
-            createdAt: new Date().toISOString(),
-            activatedAt: null,
-            stoppingAt: null,
-            completedAt: null,
-            outcome: null,
-        };
-        this.store.createLaunchInstance(instance);
-        this.#instances.set(instance.id, instance);
-        this.#bindOwner(instance.id, socket);
-        this.#mutated();
-    }
-    #activateLaunchInstance(command, socket, clientId) {
-        assertNativeProcessIdentity(command.rootIdentity);
-        assertProcessContainmentIdentity(command.containmentIdentity);
-        const instance = this.#ownedInstance(command.instanceId, socket, clientId);
-        if (instance.state === "active"
-            && sameProcessIdentity(instance.rootIdentity, command.rootIdentity)
-            && sameContainmentIdentity(instance.containmentIdentity, command.containmentIdentity))
-            return;
-        if (instance.state !== "requested")
-            throw new Error("launch instance is not requested");
-        const activatedAt = new Date().toISOString();
-        if (!this.store.activateLaunchInstance(instance.id, clientId, command.rootIdentity, command.containmentIdentity, activatedAt)) {
-            throw new Error("launch instance activation ownership mismatch");
-        }
-        this.#instances.set(instance.id, { ...instance, state: "active", rootIdentity: command.rootIdentity, containmentIdentity: command.containmentIdentity, activatedAt });
-        this.#mutated();
-    }
-    #beginLaunchInstanceStop(command, socket, clientId) {
-        const instance = this.#ownedInstance(command.instanceId, socket, clientId);
-        if (instance.state === "stopping")
-            return;
-        if (instance.state !== "active")
-            throw new Error("active launch instance not found");
-        const stoppingAt = new Date().toISOString();
-        if (!this.store.beginLaunchInstanceStop(instance.id, clientId, stoppingAt))
-            throw new Error("launch instance stop ownership mismatch");
-        this.#instances.set(instance.id, { ...instance, state: "stopping", stoppingAt });
-        this.#mutated();
-    }
-    #completeLaunchInstance(command, socket, clientId) {
-        assertLaunchInstanceOutcome(command.outcome);
-        const stored = this.store.loadLaunchInstance(command.instanceId);
-        if (!stored)
-            throw new Error("launch instance not found");
-        if (stored.ownerClientId !== clientId || this.#instanceOwners.get(stored.id) !== socket)
-            throw new Error("launch instance ownership mismatch");
-        if (stored.state === "completed" || stored.state === "interrupted") {
-            if (stored.state === command.terminalState && JSON.stringify(stored.outcome) === JSON.stringify(command.outcome))
-                return;
-            throw new Error("launch instance already has a different terminal outcome");
-        }
-        const completedAt = new Date().toISOString();
-        if (!this.store.completeLaunchInstance(stored.id, clientId, command.terminalState, command.outcome, completedAt)) {
-            throw new Error("launch instance completion ownership mismatch");
-        }
-        this.#instances.delete(stored.id);
-        this.#uncertainInstances.delete(stored.id);
-        this.#unbindOwner(stored.id, socket);
-        this.#mutated();
-        // Invariant: the last session on a superseded cohort has left; there is nothing here to keep.
-        if (this.#superseded && this.#instances.size === 0)
-            void this.retire();
-    }
-    #ownedInstance(instanceId, socket, clientId) {
-        const instance = this.#instances.get(instanceId) ?? this.store.loadLaunchInstance(instanceId);
-        if (!instance || instance.state === "completed" || instance.state === "interrupted")
-            throw new Error("active launch instance not found");
-        if (instance.ownerClientId !== clientId || this.#instanceOwners.get(instanceId) !== socket)
-            throw new Error("launch instance ownership mismatch");
-        return instance;
-    }
-    #bindOwner(instanceId, socket) {
-        const current = this.#instanceOwners.get(instanceId);
-        if (current && current !== socket)
-            throw new Error("launch instance already belongs to another authenticated connection");
-        this.#instanceOwners.set(instanceId, socket);
-        this.#clientInstances.get(socket)?.add(instanceId);
-    }
-    #unbindOwner(instanceId, socket) {
-        this.#instanceOwners.delete(instanceId);
-        this.#clientInstances.get(socket)?.delete(instanceId);
-    }
-    #onSocketClosed(socket) {
-        if (!this.#clients.delete(socket) && !this.#clientIds.has(socket))
-            return;
-        const instanceIds = [...(this.#clientInstances.get(socket) ?? [])];
-        this.#clientInstances.delete(socket);
-        this.#clientIds.delete(socket);
-        for (const instanceId of instanceIds) {
-            if (this.#instanceOwners.get(instanceId) === socket)
-                this.#instanceOwners.delete(instanceId);
-            if (!this.#closing)
-                void this.#reconcileLaunchInstance(instanceId);
-        }
-    }
-    #reconcileLaunchInstance(instanceId) {
-        const existing = this.#reconciliations.get(instanceId);
-        if (existing)
-            return existing;
-        if (this.#closing)
-            return Promise.resolve();
-        const reconciliation = this.#performReconciliation(instanceId).finally(() => this.#reconciliations.delete(instanceId));
-        this.#reconciliations.set(instanceId, reconciliation);
-        return reconciliation;
-    }
-    async #performReconciliation(instanceId) {
-        const instance = this.#instances.get(instanceId);
-        if (!instance)
-            return;
-        const deadline = Date.now() + this.reconciliationDeadlineMs;
-        while (instance.rootIdentity && processIsAlive(instance.rootIdentity.pid) && Date.now() < deadline) {
-            await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
-        }
-        if (instance.state === "requested" || (instance.rootIdentity && !processIsAlive(instance.rootIdentity.pid))) {
-            const outcome = { kind: "interrupted", reason: "owner-disconnect", message: "launch instance owner disconnected before reporting a terminal outcome" };
-            if (this.store.completeLaunchInstance(instance.id, instance.ownerClientId, "interrupted", outcome, new Date().toISOString())) {
-                this.#instances.delete(instance.id);
-                this.#uncertainInstances.delete(instance.id);
-                this.#mutated();
-            }
-            return;
-        }
-        this.#uncertainInstances.add(instance.id);
-        await this.#writeEndpointMetadata();
-    }
-    async #handleUpdateRelease(socket, request) {
-        const identityMatches = request.bootNonce === this.bootNonce && typeof request.targetVersion === "string";
-        if (!identityMatches) {
-            this.#send(socket, {
-                type: "release-update-result",
-                accepted: false,
-                reason: "boot nonce or target version mismatch",
-                liveInstanceIds: this.#liveInstanceIds(),
-            });
-            return;
-        }
-        const released = await this.#drainInstances("update", this.shutdownDeadlineMs);
-        this.#send(socket, {
-            type: "release-update-result",
-            accepted: released,
-            reason: released
-                ? `verified ${PRODUCT_TEXT.displayName} owner drained all launch instances for immediate update shutdown`
-                : "one or more launch instances did not release verified ownership within the update deadline",
-            liveInstanceIds: this.#liveInstanceIds(),
-        });
-        if (released)
-            setTimeout(() => void this.closeForReleaseReplacement(false), 25);
-    }
-    async #drainInstances(reason, timeoutMs) {
-        if (this.#instances.size === 0)
-            return true;
-        this.#requestStopAll(reason);
-        const deadline = Date.now() + timeoutMs;
-        while (Date.now() < deadline) {
-            if (this.#instances.size === 0) {
-                // Concurrency: allow the terminal command result to flush before closing owner sockets.
-                await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
-                return this.#instances.size === 0;
-            }
-            await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
-        }
-        return this.#instances.size === 0;
-    }
-    #requestStopAll(reason) {
-        for (const [instanceId, socket] of this.#instanceOwners) {
-            this.#send(socket, { type: "stop-launch-instance", requestId: randomUUID(), instanceId, reason });
-        }
-    }
-    #mutated() {
-        this.#revision += 1;
-        void this.#writeEndpointMetadata();
-    }
-    #liveInstanceIds() {
-        return [...this.#instances.keys()];
-    }
-    #writeEndpointMetadata() {
-        if (this.#closing)
-            return Promise.resolve();
-        const liveInstanceIds = this.#liveInstanceIds();
-        const metadata = {
-            schema: PRODUCT_IDENTITY.protocol.supervisorSchema,
-            ...localControlHello(this.release.releaseId),
-            supervisorId: this.id,
-            pid: process.pid,
-            pidStartIdentity: this.pidStartIdentity,
-            nativeStartIdentity: this.pidStartIdentity,
-            bootNonce: this.bootNonce,
-            endpoint: this.paths.endpoint,
-            databasePath: this.paths.databasePath,
-            startedAt: this.startedAt,
-            releaseId: this.release.releaseId,
-            releaseRoot: this.release.releaseRoot,
-            contentDigest: this.release.contentDigest,
-            ownership: {
-                state: this.#uncertainInstances.size > 0 ? "blocked" : liveInstanceIds.length > 0 ? "busy" : "idle",
-                liveInstanceIds,
-                nonResumableInstanceIds: liveInstanceIds,
-                uncertainInstanceIds: [...this.#uncertainInstances],
-            },
-        };
-        const commit = () => commitEndpointMetadata(this.paths.endpointMetadataPath, JSON.stringify(metadata, null, 2));
-        // Platform: one exhausted filesystem replacement must fail its command, but it must not
-        // poison every later ownership revision after the sharing condition has cleared.
-        this.#metadataWrites = this.#metadataWrites.then(commit, commit);
-        return this.#metadataWrites;
-    }
-    #send(socket, message) {
-        if (socket.destroyed)
-            return;
-        const frame = encodeFrame(message);
-        const bytes = Buffer.byteLength(frame, "utf8");
-        if (bytes > MAX_CONTROL_FRAME_BYTES || socket.writableLength + bytes > MAX_CONTROL_FRAME_BYTES * 2) {
-            socket.destroy(new Error("slow client exceeded the bounded control/output queue"));
-            return;
-        }
-        socket.write(frame);
-    }
-}
-function sameProcessIdentity(left, right) {
-    return left !== null && left.pid === right.pid && left.startIdentity === right.startIdentity;
-}
-function sameContainmentIdentity(left, right) {
-    return left !== null && left.provider === right.provider && left.token === right.token;
-}
-function isMessageType(value, type) {
-    return typeof value === "object" && value !== null && "type" in value && value.type === type;
-}
-function isWindowsSharingViolation(error) {
-    return error instanceof Error && "code" in error
-        && (error.code === "EPERM" || error.code === "EACCES" || error.code === "EBUSY");
-}
-async function ensureManagedEndpointDirectory(path) {
-    await mkdir(path, { recursive: true, mode: 0o700 });
-    const metadata = await lstat(path);
-    if (!metadata.isDirectory() || metadata.isSymbolicLink())
-        throw new Error(`managed endpoint path is not a directory: ${path}`);
-    const currentUser = process.getuid?.();
-    if (currentUser !== undefined && metadata.uid !== currentUser)
-        throw new Error(`managed endpoint directory has another owner: ${path}`);
-    await chmod(path, 0o700);
-}
-async function endpointIsLive(endpoint) {
-    return await new Promise(resolve => {
-        const socket = createConnection(endpoint);
-        const done = (live) => { socket.destroy(); resolve(live); };
-        socket.once("connect", () => done(true));
-        socket.once("error", () => done(false));
-        setTimeout(() => done(false), 250).unref();
-    });
-}