@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/foundation/supervision/server.js

@@ -0,0 +1,573 @@
+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 { 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 = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
+    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())
+            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() {
+        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 });
+        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();
+            });
+        });
+        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();
+        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")
+                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 code = /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 });
+    }
+    #createLaunchInstance(command, socket, clientId) {
+        assertNativeProcessIdentity(command.guardianIdentity);
+        const existing = this.store.loadLaunchInstance(command.instanceId);
+        if (this.#superseded && !existing) {
+            throw new Error(PRODUCT_TEXT.diagnostic(`release ${this.release.releaseId} is no longer the release new sessions start on`));
+        }
+        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;
+        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,
+            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();
+    });
+}

package/dist/foundation/terminal-cleanup/fatal-exit.d.ts

@@ -0,0 +1,12 @@
+export interface FatalExitOptions {
+    readonly directory: string;
+    readonly releaseId?: string;
+    readonly restore?: () => void;
+    readonly dispose?: () => Promise<unknown> | void;
+    readonly timeoutMs?: number;
+}
+export declare function writeFatalDiagnostic(directory: string, origin: string, error: unknown, releaseId?: string): Promise<string | null>;
+export declare function installFatalExit(options: FatalExitOptions): {
+    fail(error: unknown): void;
+    remove(): void;
+};

package/dist/foundation/terminal-cleanup/fatal-exit.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { writeSync } from "node:fs";
+import { join } from "node:path";
+import { boundedCleanup, restoreProcessTerminal } from "./terminal-reset.js";
+export async function writeFatalDiagnostic(directory, origin, error, releaseId) {
+    try {
+        // Security: only known classifications and code locations are retained. Error messages,
+        // function names, arbitrary paths, and request objects are never persisted.
+        const cleanupFailed = error instanceof AggregateError && error.cause instanceof Error;
+        const primary = cleanupFailed ? error.cause : error;
+        const classification = primary instanceof TypeError ? "TypeError" : primary instanceof RangeError ? "RangeError" : "Error";
+        const stack = primary instanceof Error && typeof primary.stack === "string" ? primary.stack.slice(0, 32768) : "";
+        const locations = stack.split("\n").slice(1).flatMap(line => {
+            const match = /\/(?:dist|src)\/([a-zA-Z0-9_./-]+\.[cm]?[jt]s):(\d+):(\d+)\)?$/.exec(line.replaceAll("\\", "/"));
+            return match ? [{ file: match[1].slice(0, 160), line: Number(match[2]), column: Number(match[3]) }] : [];
+        }).slice(0, 16);
+        const record = {
+            timestamp: new Date().toISOString(),
+            origin: ["uncaughtException", "unhandledRejection", "entry"].includes(origin) ? origin : "entry",
+            classification, cleanupFailed, locations, node: process.version, platform: process.platform,
+            releaseId: releaseId && /^[a-zA-Z0-9._-]{1,128}$/.test(releaseId) ? releaseId : "unknown",
+        };
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const name = `fatal-${Date.now()}-${randomUUID()}.json`;
+        const path = join(directory, name);
+        const text = JSON.stringify(record, null, 2);
+        if (Buffer.byteLength(text) > 16 * 1024)
+            return null;
+        await writeFile(path, text, { flag: "wx", mode: 0o600 });
+        const names = (await readdir(directory)).filter(file => /^fatal-\d+-[a-f0-9-]+\.json$/.test(file)).sort().reverse();
+        await Promise.all(names.slice(10).map(file => unlink(join(directory, file)).catch(() => undefined)));
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function installFatalExit(options) {
+    let failing = false;
+    const restore = () => { try {
+        (options.restore ?? restoreProcessTerminal)();
+    }
+    catch { } };
+    const terminate = (origin, error) => {
+        if (failing)
+            return;
+        failing = true;
+        process.exitCode = 1;
+        // Security: stop accepting input immediately; fatal errors never resume normal work.
+        try {
+            process.stdin.pause();
+            process.stdin.removeAllListeners("data");
+        }
+        catch { }
+        restore();
+        let record = null;
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            restore();
+            try {
+                const location = record?.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 512);
+                writeSync(2, `A1 stopped after an unexpected error.${location ? ` Diagnostic: ${location}` : " Diagnostic storage unavailable."}\n`);
+            }
+            catch { }
+            process.exit(1);
+        };
+        const cleanupTimeoutMs = options.timeoutMs ?? 1000;
+        // Rationale: a short cleanup budget must not terminate the process while its bounded diagnostic write is still in flight.
+        const deadline = setTimeout(finish, Math.max(1000, cleanupTimeoutMs));
+        void Promise.all([
+            writeFatalDiagnostic(options.directory, origin, error, options.releaseId).then(path => { record = path; }),
+            boundedCleanup(() => options.dispose?.(), cleanupTimeoutMs).catch(() => undefined),
+        ]).then(() => { clearTimeout(deadline); finish(); }, finish);
+    };
+    const exception = (error) => terminate("uncaughtException", error);
+    const rejection = (error) => terminate("unhandledRejection", error);
+    process.on("uncaughtException", exception);
+    process.on("unhandledRejection", rejection);
+    return {
+        fail: error => terminate("entry", error),
+        remove() { process.off("uncaughtException", exception); process.off("unhandledRejection", rejection); },
+    };
+}

package/dist/foundation/terminal-cleanup/index.d.ts

@@ -0,0 +1,3 @@
+export { EMERGENCY_TERMINAL_RESET, boundedCleanup, restoreAfterOwnedExit, restoreProcessTerminal } from "./terminal-reset.js";
+export { installFatalExit, writeFatalDiagnostic } from "./fatal-exit.js";
+export type { FatalExitOptions } from "./fatal-exit.js";