@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/dist/foundation/lifecycle/supervisor-startup.d.ts

@@ -0,0 +1,30 @@
+declare const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
+export interface SupervisorStartupAttemptIdentity {
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly resultPath: string;
+}
+export type SupervisorStartupResult = {
+    readonly schema: typeof STARTUP_SCHEMA;
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly outcome: "ready";
+    readonly pid: number;
+} | {
+    readonly schema: typeof STARTUP_SCHEMA;
+    readonly attemptId: string;
+    readonly releaseId: string;
+    readonly outcome: "failure";
+    readonly stage: string;
+    readonly code: string | null;
+    readonly message: string;
+};
+/** Create one unguessable startup result authority under the protected runtime root. */
+export declare function createSupervisorStartupAttempt(runtimeDir: string, releaseId: string): Promise<SupervisorStartupAttemptIdentity>;
+export declare function supervisorStartupResultPath(runtimeDir: string, attemptId: string): string;
+/** Atomically publish the bounded result for one detached supervisor startup attempt. */
+export declare function publishSupervisorStartupResult(path: string, result: SupervisorStartupResult): Promise<void>;
+export declare function readSupervisorStartupResult(path: string, attemptId: string, releaseId: string): Promise<SupervisorStartupResult | null>;
+export declare function supervisorStartupFailure(error: unknown, attemptId: string, releaseId: string, stage: string): SupervisorStartupResult;
+export declare function supervisorStartupReady(attemptId: string, releaseId: string): SupervisorStartupResult;
+export {};

package/dist/foundation/lifecycle/supervisor-startup.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const STARTUP_SCHEMA = "a1-supervisor-startup-v1";
+const MAX_RESULT_BYTES = 8 * 1024;
+const MAX_MESSAGE_LENGTH = 1_024;
+const MAX_RETAINED_RESULTS = 16;
+const MAX_RESULT_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+const ATTEMPT_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+/** Create one unguessable startup result authority under the protected runtime root. */
+export async function createSupervisorStartupAttempt(runtimeDir, releaseId) {
+    const attemptId = randomUUID();
+    const directory = resolve(runtimeDir, "supervisor-startup");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await pruneSupervisorStartupResults(directory);
+    return { attemptId, releaseId, resultPath: supervisorStartupResultPath(runtimeDir, attemptId) };
+}
+export function supervisorStartupResultPath(runtimeDir, attemptId) {
+    if (!ATTEMPT_PATTERN.test(attemptId))
+        throw new TypeError("supervisor startup attempt identity is invalid");
+    return resolve(runtimeDir, "supervisor-startup", `${attemptId}.json`);
+}
+/** Atomically publish the bounded result for one detached supervisor startup attempt. */
+export async function publishSupervisorStartupResult(path, result) {
+    validateSupervisorStartupResult(result, result.attemptId, result.releaseId);
+    const body = `${JSON.stringify(result)}\n`;
+    if (Buffer.byteLength(body) > MAX_RESULT_BYTES)
+        throw new Error("supervisor startup result exceeds its size bound");
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, body, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+}
+export async function readSupervisorStartupResult(path, attemptId, releaseId) {
+    let metadata;
+    try {
+        metadata = await stat(path);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+    if (!metadata.isFile() || metadata.size > MAX_RESULT_BYTES)
+        throw new Error("supervisor startup result is invalid or oversized");
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return validateSupervisorStartupResult(value, attemptId, releaseId);
+}
+export function supervisorStartupFailure(error, attemptId, releaseId, stage) {
+    const source = error instanceof Error ? error : new Error(String(error));
+    return {
+        schema: STARTUP_SCHEMA,
+        attemptId,
+        releaseId,
+        outcome: "failure",
+        stage: boundedToken(stage, "unknown"),
+        code: "code" in source && typeof source.code === "string" ? boundedToken(source.code, "UNKNOWN") : null,
+        message: sanitizeMessage(source.message),
+    };
+}
+export function supervisorStartupReady(attemptId, releaseId) {
+    return { schema: STARTUP_SCHEMA, attemptId, releaseId, outcome: "ready", pid: process.pid };
+}
+async function pruneSupervisorStartupResults(directory) {
+    const now = Date.now();
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = (await Promise.all(entries.filter(entry => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
+        const path = resolve(directory, entry.name);
+        const metadata = await stat(path).catch(() => null);
+        return metadata ? { path, modified: metadata.mtimeMs } : null;
+    }))).filter((file) => file !== null);
+    files.sort((left, right) => right.modified - left.modified);
+    await Promise.all(files.flatMap((file, index) => index >= MAX_RETAINED_RESULTS - 1 || now - file.modified > MAX_RESULT_AGE_MS
+        ? [rm(file.path, { force: true })]
+        : []));
+}
+function validateSupervisorStartupResult(value, attemptId, releaseId) {
+    if (!value || typeof value !== "object")
+        throw new Error("supervisor startup result is malformed");
+    const result = value;
+    if (result.schema !== STARTUP_SCHEMA || result.attemptId !== attemptId || result.releaseId !== releaseId) {
+        throw new Error("supervisor startup result does not match the selected attempt and release");
+    }
+    if (result.outcome === "ready" && Number.isSafeInteger(result.pid) && Number(result.pid) > 0)
+        return result;
+    if (result.outcome === "failure" && typeof result.stage === "string" && result.stage.length > 0 && result.stage.length <= 128
+        && (result.code === null || typeof result.code === "string") && typeof result.message === "string" && result.message.length <= MAX_MESSAGE_LENGTH) {
+        return result;
+    }
+    throw new Error("supervisor startup result is malformed");
+}
+function sanitizeMessage(message) {
+    let value = message.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/:\/\/[^\s/@:]+:[^\s/@]+@/g, "://<redacted>@");
+    for (const [name, secret] of Object.entries(process.env)) {
+        if (!secret || secret.length < 4 || !/(?:TOKEN|SECRET|PASSWORD|COOKIE|CREDENTIAL|AUTH)/i.test(name))
+            continue;
+        value = value.split(secret).join("<redacted>");
+    }
+    return value.trim().slice(0, MAX_MESSAGE_LENGTH) || "supervisor startup failed";
+}
+function boundedToken(value, fallback) {
+    const normalized = value.replace(/[^A-Za-z0-9_.:-]/g, "-").slice(0, 128);
+    return normalized || fallback;
+}
+function isNodeError(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/foundation/process-containment/darwin-process-inspector.d.ts

@@ -0,0 +1,5 @@
+import { WindowsNativeProcessInspector, type InspectorCommandRunner } from "./windows-process-inspector.js";
+/** Verifies Darwin process identity through the bounded native guardian inspection command. */
+export declare class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
+    constructor(helperPath: string, runner?: InspectorCommandRunner);
+}

package/dist/foundation/process-containment/darwin-process-inspector.js

@@ -0,0 +1,7 @@
+import { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
+/** Verifies Darwin process identity through the bounded native guardian inspection command. */
+export class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
+    constructor(helperPath, runner) {
+        super(helperPath, runner, "darwin-proc-start:");
+    }
+}

package/dist/foundation/process-containment/index.d.ts

@@ -0,0 +1,8 @@
+export { verifyProcessGuardianArtifact } from "./artifact.js";
+export { closeVerifiedContainment } from "./contracts.js";
+export type { ContainedProcessHandle, ContainedSpawnOptions, ContainmentCloseResult, NativeProcessInspector, ProcessContainment, ProcessContainmentFactory, } from "./contracts.js";
+export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
+export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
+export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
+export type { InspectorCommandResult, InspectorCommandRunner } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/index.js

@@ -0,0 +1,6 @@
+export { verifyProcessGuardianArtifact } from "./artifact.js";
+export { closeVerifiedContainment } from "./contracts.js";
+export { DarwinNativeProcessInspector } from "./darwin-process-inspector.js";
+export { LinuxNativeProcessInspector } from "./linux-process-inspector.js";
+export { NativeGuardianContainment, resolveProcessGuardianPath } from "./native-guardian-containment.js";
+export { WindowsNativeProcessInspector } from "./windows-process-inspector.js";

package/dist/foundation/process-containment/linux-process-inspector.d.ts

@@ -0,0 +1,7 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
+export declare class LinuxNativeProcessInspector implements NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/foundation/process-containment/linux-process-inspector.js

@@ -0,0 +1,27 @@
+import { readFile } from "node:fs/promises";
+/** Verifies Linux process identity from the PID and kernel start-time field in procfs. */
+export class LinuxNativeProcessInspector {
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        let stat;
+        try {
+            stat = await readFile(`/proc/${pid}/stat`, "utf8");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        const commandEnd = stat.lastIndexOf(")");
+        const fields = commandEnd >= 0 ? stat.slice(commandEnd + 1).trim().split(/\s+/) : [];
+        const startTicks = fields[19];
+        if (!startTicks || !/^\d+$/.test(startTicks))
+            throw new Error("process stat has no valid start-time field");
+        return { pid, startIdentity: `linux-proc-start:${startTicks}` };
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}

package/dist/foundation/process-containment/native-guardian-containment.d.ts

@@ -0,0 +1,17 @@
+import type { NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+import type { ContainedProcessHandle, ContainedSpawnOptions, ProcessContainment } from "./contracts.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
+export declare class NativeGuardianContainment implements ProcessContainment {
+    #private;
+    readonly instanceId: string;
+    readonly helperPath: string;
+    readonly statusPath: string;
+    constructor(instanceId: string, helperPath: string, statusPath: string);
+    get identity(): ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export declare function resolveProcessGuardianPath(releaseRoot: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, architecture?: string): string;

package/dist/foundation/process-containment/native-guardian-containment.js

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
+export class NativeGuardianContainment {
+    #identity;
+    #helper = null;
+    #rootIdentity = null;
+    #outcome = null;
+    instanceId;
+    helperPath;
+    statusPath;
+    constructor(instanceId, helperPath, statusPath) {
+        this.instanceId = instanceId;
+        this.helperPath = helperPath;
+        this.statusPath = statusPath;
+        this.#identity = { provider: "native-guardian-pending", token: instanceId };
+    }
+    get identity() {
+        return this.#identity;
+    }
+    async spawn(executable, arguments_, options) {
+        if (this.#helper)
+            throw new Error("process containment already has a root runtime");
+        await mkdir(dirname(this.statusPath), { recursive: true, mode: 0o700 });
+        await rm(this.statusPath, { force: true });
+        const helper = spawn(this.helperPath, [
+            "--parent-pid", String(process.pid),
+            "--instance", this.instanceId,
+            "--status-file", this.statusPath,
+            "--", executable, ...arguments_,
+        ], {
+            cwd: options.cwd,
+            env: { ...options.environment, ...(options.terminalType ? { TERM: options.terminalType } : {}) },
+            shell: false,
+            stdio: "inherit",
+            windowsHide: false,
+        });
+        this.#helper = helper;
+        this.#outcome = helperOutcome(helper);
+        const status = await waitForReadyStatus(this.statusPath, this.#outcome, 5_000);
+        this.#rootIdentity = { pid: status.pid, startIdentity: status.startIdentity };
+        this.#identity = { provider: status.containmentProvider, token: status.containmentToken };
+        return { identity: this.#rootIdentity, outcome: this.#outcome };
+    }
+    async contains(identity) {
+        return this.#rootIdentity !== null
+            && identity.pid === this.#rootIdentity.pid
+            && identity.startIdentity === this.#rootIdentity.startIdentity;
+    }
+    async stop(force) {
+        const root = this.#rootIdentity;
+        if (!root)
+            return;
+        try {
+            process.kill(root.pid, force ? "SIGKILL" : "SIGTERM");
+        }
+        catch { }
+    }
+    async waitForEmpty(timeoutMs) {
+        if (!this.#helper || this.#helper.exitCode !== null || this.#helper.signalCode !== null)
+            return true;
+        return await new Promise(resolvePromise => {
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            const finish = (empty) => {
+                clearTimeout(timer);
+                this.#helper?.off("close", onClose);
+                resolvePromise(empty);
+            };
+            const onClose = () => finish(true);
+            this.#helper?.once("close", onClose);
+        });
+    }
+    async close() {
+        const helper = this.#helper;
+        if (helper && helper.exitCode === null && helper.signalCode === null)
+            helper.kill("SIGKILL");
+        await this.waitForEmpty(1_500);
+        await rm(this.statusPath, { force: true });
+    }
+}
+export function resolveProcessGuardianPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
+    const override = environment[PRODUCT_IDENTITY.environment.processGuardianPath]?.trim();
+    if (override)
+        return resolve(override);
+    const executable = platform === "win32"
+        ? `${PRODUCT_IDENTITY.artifacts.processGuardianExecutable}.exe`
+        : PRODUCT_IDENTITY.artifacts.processGuardianExecutable;
+    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
+}
+function helperOutcome(helper) {
+    return new Promise(resolvePromise => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(outcome);
+        };
+        helper.once("error", error => settle({ kind: "guardian-error", message: error.message, code: errorCode(error) }));
+        helper.once("close", (code, signal) => {
+            if (signal)
+                settle({ kind: "signaled", signal });
+            else
+                settle({ kind: "exited", exitCode: code ?? 1 });
+        });
+    });
+}
+async function waitForReadyStatus(path, outcome, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let terminalOutcome = null;
+    void outcome.then(value => { terminalOutcome = value; });
+    while (Date.now() < deadline) {
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (isReadyStatus(value))
+                return value;
+            throw new Error("process guardian published invalid ready status");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        if (terminalOutcome)
+            throw new Error(`process guardian exited before readiness: ${JSON.stringify(terminalOutcome)}`);
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+    }
+    throw new Error(`process guardian did not publish readiness within ${timeoutMs}ms`);
+}
+function isReadyStatus(value) {
+    return Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && typeof value.startIdentity === "string" && value.startIdentity.length > 0
+        && typeof value.containmentProvider === "string" && value.containmentProvider.length > 0
+        && typeof value.containmentToken === "string" && value.containmentToken.length > 0;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string" ? error.code : null;
+}

package/dist/foundation/process-containment/windows-process-inspector.d.ts

@@ -0,0 +1,19 @@
+import type { NativeProcessIdentity } from "../lifecycle/index.js";
+import type { NativeProcessInspector } from "./contracts.js";
+export interface InspectorCommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface InspectorCommandRunner {
+    run(executable: string, arguments_: readonly string[]): Promise<InspectorCommandResult>;
+}
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
+export declare class WindowsNativeProcessInspector implements NativeProcessInspector {
+    readonly helperPath: string;
+    private readonly runner;
+    private readonly identityPrefix;
+    constructor(helperPath: string, runner?: InspectorCommandRunner, identityPrefix?: string);
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}

package/dist/foundation/process-containment/windows-process-inspector.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+/** Verifies Windows process identity through the bounded process-guardian inspection command. */
+export class WindowsNativeProcessInspector {
+    helperPath;
+    runner;
+    identityPrefix;
+    constructor(helperPath, runner = defaultRunner, identityPrefix = "windows-filetime:") {
+        this.helperPath = helperPath;
+        this.runner = runner;
+        this.identityPrefix = identityPrefix;
+        if (!helperPath || helperPath.includes("\0"))
+            throw new TypeError("process guardian helper path is invalid");
+    }
+    async observe(pid) {
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            throw new TypeError("inspected PID must be a positive safe integer");
+        const result = await this.runner.run(this.helperPath, ["--inspect-pid", String(pid)]);
+        if (result.exitCode === 3)
+            return null;
+        if (result.exitCode !== 0) {
+            const detail = result.stderr.trim() || `helper exited ${result.exitCode}`;
+            throw Object.assign(new Error(`cannot inspect native process identity: ${detail}`), { code: "PROCESS_INSPECTION_FAILED" });
+        }
+        let value;
+        try {
+            value = JSON.parse(result.stdout);
+        }
+        catch {
+            throw Object.assign(new Error("process guardian returned malformed identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        if (!isIdentity(value) || value.pid !== pid || !value.startIdentity.startsWith(this.identityPrefix)) {
+            throw Object.assign(new Error("process guardian returned mismatched identity data"), { code: "PROCESS_INSPECTION_INVALID" });
+        }
+        return value;
+    }
+    async matches(identity) {
+        const observed = await this.observe(identity.pid);
+        return observed !== null && observed.startIdentity === identity.startIdentity;
+    }
+}
+const defaultRunner = {
+    async run(executable, arguments_) {
+        return await new Promise(resolvePromise => {
+            execFile(executable, [...arguments_], { windowsHide: true, timeout: 2_000, maxBuffer: 8 * 1_024 }, (error, stdout, stderr) => {
+                const exitCode = error && "code" in error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+                resolvePromise({ exitCode, stdout, stderr });
+            });
+        });
+    },
+};
+function isIdentity(value) {
+    return typeof value === "object" && value !== null
+        && "pid" in value && Number.isSafeInteger(value.pid) && Number(value.pid) > 0
+        && "startIdentity" in value && typeof value.startIdentity === "string"
+        && value.startIdentity.length > 0 && value.startIdentity.length <= 512 && !value.startIdentity.includes("\0");
+}

package/dist/foundation/protocol/client.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from "node:events";
+import type { CommandResult, LaunchInstanceStopIntent, SupervisorCommand, SupervisorSnapshot } from "../lifecycle/index.js";
+interface ClientEvents {
+    snapshot: [SupervisorSnapshot];
+    stopIntent: [LaunchInstanceStopIntent];
+    disconnect: [];
+}
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
+export declare class SupervisorClient extends EventEmitter<ClientEvents> {
+    #private;
+    readonly clientId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly releaseId?: string;
+    constructor(releaseId?: string);
+    connect(endpoint: string, timeoutMs?: number): Promise<SupervisorSnapshot>;
+    command(command: SupervisorCommand): Promise<CommandResult>;
+    close(): void;
+}
+export {};

package/dist/foundation/protocol/client.js

@@ -0,0 +1,130 @@
+import { EventEmitter } from "node:events";
+import { connect } from "node:net";
+import { randomUUID } from "node:crypto";
+import { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, encodeFrame, LineFrameDecoder, localControlHello, negotiateControlFeatures } from "./messages.js";
+/** Maintains one negotiated supervisor connection and rejects all pending commands on disconnect. */
+export class SupervisorClient extends EventEmitter {
+    clientId = randomUUID();
+    releaseId;
+    constructor(releaseId) {
+        super();
+        if (releaseId !== undefined)
+            this.releaseId = releaseId;
+    }
+    #socket = null;
+    #pending = new Map();
+    async connect(endpoint, timeoutMs = 5_000) {
+        if (this.#socket)
+            throw new Error("client is already connected");
+        const deadline = Date.now() + timeoutMs;
+        let lastError = null;
+        while (Date.now() < deadline) {
+            try {
+                return await this.#connectOnce(endpoint, Math.max(1, deadline - Date.now()));
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (!isTransientEndpointError(lastError))
+                    throw lastError;
+                await new Promise(resolve => setTimeout(resolve, Math.min(40, Math.max(1, deadline - Date.now()))));
+            }
+        }
+        throw new Error(`supervisor endpoint ${endpoint} remained unavailable for ${timeoutMs}ms`, { cause: lastError ?? undefined });
+    }
+    #connectOnce(endpoint, timeoutMs) {
+        const socket = connect(endpoint);
+        this.#socket = socket;
+        socket.setNoDelay(true);
+        const decoder = new LineFrameDecoder();
+        return new Promise((resolve, reject) => {
+            let welcomed = false;
+            const timeout = setTimeout(() => {
+                const error = transientError(`supervisor connection timed out after ${timeoutMs}ms`, "ETIMEDOUT");
+                fail(error);
+                socket.destroy();
+            }, timeoutMs);
+            const fail = (error) => {
+                clearTimeout(timeout);
+                if (!welcomed)
+                    reject(error);
+            };
+            socket.once("error", fail);
+            socket.on("close", () => {
+                if (this.#socket === socket)
+                    this.#socket = null;
+                if (!welcomed) {
+                    fail(transientError("supervisor disconnected before completing its handshake", "ECONNRESET"));
+                    return;
+                }
+                for (const pending of this.#pending.values())
+                    pending.reject(new Error("supervisor disconnected"));
+                this.#pending.clear();
+                this.emit("disconnect");
+            });
+            socket.on("data", chunk => {
+                try {
+                    for (const value of decoder.push(chunk)) {
+                        const message = value;
+                        if (message.type === "server-hello" && message.snapshot) {
+                            const hello = message;
+                            if (hello.envelope !== CONTROL_ENVELOPE || hello.envelopeRevision !== CONTROL_ENVELOPE_REVISION || !Array.isArray(hello.requiredFeatures) || !Array.isArray(hello.optionalFeatures) || typeof hello.contractDigest !== "string") {
+                                fail(new Error("supervisor returned an invalid control handshake"));
+                                socket.destroy();
+                                continue;
+                            }
+                            const negotiation = negotiateControlFeatures(localControlHello(this.releaseId), hello);
+                            if (!negotiation.ok) {
+                                fail(new Error(negotiation.diagnostic));
+                                socket.destroy();
+                                continue;
+                            }
+                            welcomed = true;
+                            clearTimeout(timeout);
+                            resolve(message.snapshot);
+                        }
+                        else if (message.type === "snapshot" && message.snapshot) {
+                            this.emit("snapshot", message.snapshot);
+                        }
+                        else if (message.type === "command-result" && message.result) {
+                            const pending = this.#pending.get(message.result.requestId);
+                            if (pending) {
+                                this.#pending.delete(message.result.requestId);
+                                pending.resolve(message.result);
+                            }
+                        }
+                        else if (message.type === "stop-launch-instance" && message.instanceId && message.requestId && message.reason) {
+                            this.emit("stopIntent", message);
+                        }
+                        else if (message.type === "protocol-error") {
+                            fail(new Error(message.message ?? "protocol error"));
+                        }
+                    }
+                }
+                catch (error) {
+                    fail(error instanceof Error ? error : new Error(String(error)));
+                    socket.destroy();
+                }
+            });
+            socket.once("connect", () => socket.write(encodeFrame({ type: "client-hello", clientId: this.clientId, ...localControlHello(this.releaseId) })));
+        });
+    }
+    command(command) {
+        if (!this.#socket)
+            return Promise.reject(new Error("supervisor is not connected"));
+        return new Promise((resolve, reject) => {
+            this.#pending.set(command.requestId, { resolve, reject });
+            this.#socket?.write(encodeFrame({ type: "command", command }));
+        });
+    }
+    close() {
+        this.#socket?.end();
+        this.#socket = null;
+    }
+}
+function isTransientEndpointError(error) {
+    const code = "code" in error ? String(error.code) : "";
+    return ["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT"].includes(code);
+}
+function transientError(message, code) {
+    return Object.assign(new Error(message), { code });
+}

package/dist/foundation/protocol/index.d.ts

@@ -0,0 +1,3 @@
+export { SupervisorClient } from "./client.js";
+export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";
+export type { ClientMessage, ControlFeature, ControlHello, ControlNegotiation, ServerMessage } from "./messages.js";

package/dist/foundation/protocol/index.js

@@ -0,0 +1,2 @@
+export { SupervisorClient } from "./client.js";
+export { CONTROL_ENVELOPE, CONTROL_ENVELOPE_REVISION, GENERATED_CONTRACT_DIGEST, LineFrameDecoder, MAX_CONTROL_FRAME_BYTES, OPTIONAL_CONTROL_FEATURES, REQUIRED_CONTROL_FEATURES, encodeFrame, isCommandMessage, isControlHello, localControlHello, negotiateControlFeatures, } from "./messages.js";