agent-embassy 1.0.0

package/dist/src/gateway/control.js

@@ -0,0 +1,1573 @@
+/**
+ * Private, local gateway control transport.
+ *
+ * Every byte received here is untrusted even though the socket lives inside a
+ * same-UID state directory. The directory permissions are the authentication
+ * boundary; this module still validates every frame and field before calling a
+ * handler. It deliberately never logs, stores, or reflects task IDs or message
+ * text.
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, lstat, mkdtemp, realpath, rename, rmdir, unlink, } from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { isCompatibilityAttestation, isCompatibilityCertificationReport, isCompatibilityCheckReport, } from "./compatibility.js";
+import { GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, } from "./types.js";
+export const GATEWAY_CONTROL_PROTOCOL_VERSION = 1;
+export const GATEWAY_CONTROL_MAX_FRAME_BYTES = 32 * 1024;
+export const GATEWAY_CONTROL_MAX_RESPONSE_BYTES = 256 * 1024;
+export const GATEWAY_CONTROL_MAX_MESSAGE_BYTES = 16 * 1024;
+export const GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS = 3_000;
+export const GATEWAY_CONTROL_MAX_CONNECTIONS = 32;
+const MAX_SOCKET_PATH_BYTES = 100;
+const MAX_REPLY_ADDRESS_BYTES = 256;
+const MAX_REVISION = Number.MAX_SAFE_INTEGER;
+const DEFAULT_HOST_ID = "this-mac";
+const DEFAULT_BUSY_POLICY = "queue";
+const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONVERSATION_ID_PATTERN = /^conv_[A-Za-z0-9_-]{16,64}$/;
+const DELIVERY_TOKEN_PATTERN = /^dlv_[A-Za-z0-9_-]{24}$/;
+const HOST_PATTERN = /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const SAFE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+const PROTOCOL_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const PROTOCOL_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:+-]{0,63}$/;
+const MESSAGE_SUFFIX_PATTERN = /^[0-9a-f]{8}$/;
+const CONVERSATION_SUFFIX_PATTERN = /^[A-Za-z0-9_-]{8}$/;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+export const gatewayControlMethods = [
+    "health",
+    "register_codex",
+    "unregister_codex",
+    "select_claude",
+    "unselect_claude",
+    "pair",
+    "unpair",
+    "list_snapshot",
+    "observe_snapshot",
+    "compat_check",
+    "compat_certify",
+    "delivery_status",
+    "untrack",
+    "send_to_claude",
+    "send_to_codex",
+    "reply",
+    "refresh_dashboard",
+];
+const WIRE_ERROR_MESSAGES = {
+    INVALID_JSON: "The control frame is not valid JSON.",
+    FRAME_TOO_LARGE: "The control frame exceeds the size limit.",
+    INVALID_REQUEST: "The control request is invalid.",
+    UNSUPPORTED_VERSION: "The control protocol version is unsupported.",
+    UNKNOWN_METHOD: "The control method is unsupported.",
+    MULTIPLE_FRAMES: "Only one control request is allowed per connection.",
+    SERVER_BUSY: "The gateway control server is at its connection limit.",
+    REQUEST_TIMEOUT: "The control request timed out.",
+    HANDLER_FAILURE: "The gateway could not complete the control request.",
+    INVALID_HANDLER_RESPONSE: "The gateway produced an invalid control response.",
+    RESPONSE_TOO_LARGE: "The control response exceeds the size limit.",
+};
+export class GatewayControlTransportError extends Error {
+    code;
+    ambiguous;
+    recoverable;
+    constructor(code, message, ambiguous = false) {
+        super(message);
+        this.name = "GatewayControlTransportError";
+        this.code = code;
+        this.ambiguous = ambiguous;
+        this.recoverable = !ambiguous;
+    }
+}
+class ProtocolFault extends Error {
+    code;
+    constructor(code) {
+        super(WIRE_ERROR_MESSAGES[code]);
+        this.name = "ProtocolFault";
+        this.code = code;
+    }
+}
+export function createGatewayConversationId() {
+    return `conv_${randomBytes(18).toString("base64url")}`;
+}
+export function isGatewayAlias(value) {
+    return ALIAS_PATTERN.test(value);
+}
+export function isClaudeSessionSelector(value) {
+    return isGatewayAlias(value) || UUID_PATTERN.test(value);
+}
+export function isGatewayHostId(value) {
+    return HOST_PATTERN.test(value);
+}
+export function isGatewayConversationId(value) {
+    return CONVERSATION_ID_PATTERN.test(value);
+}
+export function isGatewayDeliveryToken(value) {
+    return DELIVERY_TOKEN_PATTERN.test(value);
+}
+export function isGatewayReplyAddress(value) {
+    if (value.includes("\0") ||
+        !value.startsWith("uds:") ||
+        Buffer.byteLength(value, "utf8") > MAX_REPLY_ADDRESS_BYTES) {
+        return false;
+    }
+    const socketPath = value.slice(4);
+    return (path.isAbsolute(socketPath) &&
+        path.resolve(socketPath) === socketPath &&
+        Buffer.byteLength(socketPath, "utf8") <= MAX_SOCKET_PATH_BYTES);
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(value, required, optional = []) {
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.some((key) => typeof key !== "string"))
+        return false;
+    const allowed = new Set([...required, ...optional]);
+    return (required.every((key) => Object.hasOwn(value, key)) &&
+        ownKeys.every((key) => typeof key === "string" && allowed.has(key)));
+}
+function isNonNegativeInteger(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= MAX_REVISION);
+}
+function isTrackIdleMinutes(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= 1 &&
+        value <= 24 * 60);
+}
+function isIsoTimestamp(value) {
+    if (typeof value !== "string" || !ISO_TIMESTAMP_PATTERN.test(value)) {
+        return false;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed);
+}
+function isUuid(value) {
+    return typeof value === "string" && UUID_PATTERN.test(value);
+}
+function isAlias(value) {
+    return typeof value === "string" && isGatewayAlias(value);
+}
+function isHostId(value) {
+    return typeof value === "string" && isGatewayHostId(value);
+}
+function isConversationId(value) {
+    return typeof value === "string" && isGatewayConversationId(value);
+}
+function isMessageText(value) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        !value.includes("\0") &&
+        Buffer.byteLength(value, "utf8") <= GATEWAY_CONTROL_MAX_MESSAGE_BYTES);
+}
+function normalizeReplyCaller(value) {
+    if (!isRecord(value) || typeof value.kind !== "string") {
+        throw new ProtocolFault("INVALID_REQUEST");
+    }
+    if (value.kind === "codex") {
+        if (!hasExactKeys(value, ["kind", "alias", "threadId"]) ||
+            !isAlias(value.alias) ||
+            !isUuid(value.threadId)) {
+            throw new ProtocolFault("INVALID_REQUEST");
+        }
+        return {
+            kind: "codex",
+            alias: value.alias,
+            threadId: value.threadId.toLowerCase(),
+        };
+    }
+    if (value.kind === "claude") {
+        if (!hasExactKeys(value, ["kind", "alias"], ["replyAddress"]) ||
+            !isAlias(value.alias) ||
+            (value.replyAddress !== undefined &&
+                (typeof value.replyAddress !== "string" ||
+                    !isGatewayReplyAddress(value.replyAddress)))) {
+            throw new ProtocolFault("INVALID_REQUEST");
+        }
+        return {
+            kind: "claude",
+            alias: value.alias,
+            ...(value.replyAddress === undefined
+                ? {}
+                : { replyAddress: value.replyAddress }),
+        };
+    }
+    throw new ProtocolFault("INVALID_REQUEST");
+}
+function normalizeParams(method, value) {
+    if (!isRecord(value))
+        throw new ProtocolFault("INVALID_REQUEST");
+    switch (method) {
+        case "health":
+        case "list_snapshot":
+        case "observe_snapshot":
+        case "compat_check":
+        case "refresh_dashboard":
+            if (!hasExactKeys(value, [])) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {};
+        case "compat_certify": {
+            if (!hasExactKeys(value, ["withTurn"], ["codexAlias"]) ||
+                typeof value.withTurn !== "boolean" ||
+                (value.codexAlias !== undefined &&
+                    (!isAlias(value.codexAlias) ||
+                        !value.codexAlias.startsWith("codex-")))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                withTurn: value.withTurn,
+                ...(value.codexAlias === undefined
+                    ? {}
+                    : { codexAlias: value.codexAlias }),
+            };
+        }
+        case "delivery_status": {
+            if (!hasExactKeys(value, ["token"]) ||
+                typeof value.token !== "string" ||
+                !isGatewayDeliveryToken(value.token)) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return { token: value.token };
+        }
+        case "untrack": {
+            if (!hasExactKeys(value, ["conversationId"]) ||
+                !isConversationId(value.conversationId)) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return { conversationId: value.conversationId };
+        }
+        case "register_codex": {
+            if (!hasExactKeys(value, ["alias", "threadId"], ["hostId", "busyPolicy", "succeedsAlias"]) ||
+                !isAlias(value.alias) ||
+                !value.alias.startsWith("codex-") ||
+                !isUuid(value.threadId) ||
+                (value.hostId !== undefined && !isHostId(value.hostId)) ||
+                (value.busyPolicy !== undefined &&
+                    value.busyPolicy !== "queue") ||
+                (value.succeedsAlias !== undefined &&
+                    (!isAlias(value.succeedsAlias) ||
+                        !value.succeedsAlias.startsWith("codex-")))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            const hostId = value.hostId ?? DEFAULT_HOST_ID;
+            if (!value.alias.endsWith(`@${hostId}`) ||
+                (value.succeedsAlias !== undefined &&
+                    (value.succeedsAlias === value.alias ||
+                        !value.succeedsAlias.endsWith(`@${hostId}`)))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                alias: value.alias,
+                threadId: value.threadId.toLowerCase(),
+                hostId,
+                busyPolicy: value.busyPolicy ?? DEFAULT_BUSY_POLICY,
+                ...(value.succeedsAlias === undefined
+                    ? {}
+                    : { succeedsAlias: value.succeedsAlias }),
+            };
+        }
+        case "unregister_codex": {
+            if (!hasExactKeys(value, ["alias", "threadId"]) ||
+                !isAlias(value.alias) ||
+                !value.alias.startsWith("codex-") ||
+                !isUuid(value.threadId)) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                alias: value.alias,
+                threadId: value.threadId.toLowerCase(),
+            };
+        }
+        case "select_claude":
+        case "unselect_claude": {
+            if (!hasExactKeys(value, ["alias"], ["codexThreadId"]) ||
+                typeof value.alias !== "string" ||
+                !isClaudeSessionSelector(value.alias) ||
+                (value.codexThreadId !== undefined && !isUuid(value.codexThreadId))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                alias: UUID_PATTERN.test(value.alias)
+                    ? value.alias.toLowerCase()
+                    : value.alias,
+                ...(value.codexThreadId === undefined
+                    ? {}
+                    : { codexThreadId: value.codexThreadId.toLowerCase() }),
+            };
+        }
+        case "pair":
+        case "unpair": {
+            if (!hasExactKeys(value, ["claudeAlias", "codexAlias"], ["codexThreadId"]) ||
+                typeof value.claudeAlias !== "string" ||
+                !isClaudeSessionSelector(value.claudeAlias) ||
+                !isAlias(value.codexAlias) ||
+                !value.codexAlias.startsWith("codex-") ||
+                (value.codexThreadId !== undefined && !isUuid(value.codexThreadId)) ||
+                value.claudeAlias === value.codexAlias ||
+                (isAlias(value.claudeAlias) &&
+                    value.claudeAlias.slice(value.claudeAlias.lastIndexOf("@") + 1) !==
+                        value.codexAlias.slice(value.codexAlias.lastIndexOf("@") + 1))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                claudeAlias: UUID_PATTERN.test(value.claudeAlias)
+                    ? value.claudeAlias.toLowerCase()
+                    : value.claudeAlias,
+                codexAlias: value.codexAlias,
+                ...(value.codexThreadId === undefined
+                    ? {}
+                    : { codexThreadId: value.codexThreadId.toLowerCase() }),
+            };
+        }
+        case "send_to_claude": {
+            if (!hasExactKeys(value, ["fromAlias", "threadId", "toAlias", "text"], ["expectsReply", "trackIdleMinutes"]) ||
+                !isAlias(value.fromAlias) ||
+                !isUuid(value.threadId) ||
+                (typeof value.toAlias !== "string" ||
+                    !isClaudeSessionSelector(value.toAlias)) ||
+                !isMessageText(value.text) ||
+                (value.expectsReply !== undefined &&
+                    typeof value.expectsReply !== "boolean") ||
+                (value.trackIdleMinutes !== undefined &&
+                    !isTrackIdleMinutes(value.trackIdleMinutes))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                fromAlias: value.fromAlias,
+                threadId: value.threadId.toLowerCase(),
+                toAlias: UUID_PATTERN.test(value.toAlias)
+                    ? value.toAlias.toLowerCase()
+                    : value.toAlias,
+                text: value.text,
+                expectsReply: value.expectsReply ?? false,
+                ...(value.trackIdleMinutes === undefined
+                    ? {}
+                    : { trackIdleMinutes: value.trackIdleMinutes }),
+            };
+        }
+        case "send_to_codex": {
+            if (!hasExactKeys(value, ["fromAlias", "toAlias", "text"], ["replyAddress", "expectsReply", "trackIdleMinutes"]) ||
+                !isAlias(value.fromAlias) ||
+                !isAlias(value.toAlias) ||
+                !isMessageText(value.text) ||
+                (value.replyAddress !== undefined &&
+                    (typeof value.replyAddress !== "string" ||
+                        !isGatewayReplyAddress(value.replyAddress))) ||
+                (value.expectsReply !== undefined &&
+                    typeof value.expectsReply !== "boolean") ||
+                (value.trackIdleMinutes !== undefined &&
+                    !isTrackIdleMinutes(value.trackIdleMinutes))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                fromAlias: value.fromAlias,
+                toAlias: value.toAlias,
+                text: value.text,
+                ...(value.replyAddress === undefined
+                    ? {}
+                    : { replyAddress: value.replyAddress }),
+                expectsReply: value.expectsReply ?? false,
+                ...(value.trackIdleMinutes === undefined
+                    ? {}
+                    : { trackIdleMinutes: value.trackIdleMinutes }),
+            };
+        }
+        case "reply": {
+            if (!hasExactKeys(value, ["conversationId", "text", "caller"], ["trackIdleMinutes"]) ||
+                !isConversationId(value.conversationId) ||
+                !isMessageText(value.text) ||
+                (value.trackIdleMinutes !== undefined &&
+                    !isTrackIdleMinutes(value.trackIdleMinutes))) {
+                throw new ProtocolFault("INVALID_REQUEST");
+            }
+            return {
+                conversationId: value.conversationId,
+                text: value.text,
+                caller: normalizeReplyCaller(value.caller),
+                ...(value.trackIdleMinutes === undefined
+                    ? {}
+                    : { trackIdleMinutes: value.trackIdleMinutes }),
+            };
+        }
+    }
+}
+function parseRequestObject(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ["protocolVersion", "method", "params"])) {
+        throw new ProtocolFault("INVALID_REQUEST");
+    }
+    if (value.protocolVersion !== GATEWAY_CONTROL_PROTOCOL_VERSION) {
+        throw new ProtocolFault("UNSUPPORTED_VERSION");
+    }
+    if (typeof value.method !== "string" ||
+        !gatewayControlMethods.includes(value.method)) {
+        throw new ProtocolFault("UNKNOWN_METHOD");
+    }
+    const method = value.method;
+    const params = normalizeParams(method, value.params);
+    return {
+        protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION,
+        method,
+        params,
+    };
+}
+function parseRequestFrame(frame) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(frame));
+    }
+    catch {
+        throw new ProtocolFault("INVALID_JSON");
+    }
+    return parseRequestObject(parsed);
+}
+function isDecision(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ["accepted", "code"]) ||
+        typeof value.accepted !== "boolean" ||
+        typeof value.code !== "string") {
+        return false;
+    }
+    if (value.accepted)
+        return value.code === "ok";
+    return (value.code === "not_found" ||
+        value.code === "conflict" ||
+        value.code === "route_mismatch" ||
+        value.code === "busy" ||
+        value.code === "unavailable" ||
+        value.code === "rejected");
+}
+function isHealthResult(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["status", "revision"]) &&
+        (value.status === "ok" || value.status === "degraded") &&
+        isNonNegativeInteger(value.revision));
+}
+function isSendResult(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.accepted === true) {
+        return (hasExactKeys(value, [
+            "accepted",
+            "code",
+            "conversationId",
+            "deliveryToken",
+        ]) &&
+            value.code === "ok" &&
+            isConversationId(value.conversationId) &&
+            typeof value.deliveryToken === "string" &&
+            isGatewayDeliveryToken(value.deliveryToken));
+    }
+    return isDecision(value);
+}
+function isRefreshResult(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ["accepted", "code", "revision"]) ||
+        !isNonNegativeInteger(value.revision)) {
+        return false;
+    }
+    const decision = { accepted: value.accepted, code: value.code };
+    return isDecision(decision);
+}
+function isProvider(value) {
+    return value === "codex" || value === "claude";
+}
+function isConnectorHealth(value) {
+    return (value === "offline" ||
+        value === "connecting" ||
+        value === "healthy" ||
+        value === "degraded" ||
+        value === "incompatible");
+}
+function isCompatibility(value) {
+    return (value === "unknown" ||
+        value === "compatible" ||
+        value === "incompatible" ||
+        value === "expired");
+}
+function isSafeCode(value) {
+    return typeof value === "string" && SAFE_CODE_PATTERN.test(value);
+}
+const TERMINAL_DELIVERY_STATUS_STATES = new Set([
+    "delivered",
+    "unconfirmed",
+    "expired",
+    "failed",
+    "ambiguous",
+    "cancelled",
+]);
+function isDeliveryStatusState(value) {
+    return (value === "queued" ||
+        value === "stalled" ||
+        value === "delivered" ||
+        value === "unconfirmed" ||
+        value === "expired" ||
+        value === "failed" ||
+        value === "ambiguous" ||
+        value === "cancelled");
+}
+function isDeliveryStatusResult(value) {
+    if (!isRecord(value) || typeof value.found !== "boolean")
+        return false;
+    if (!value.found)
+        return hasExactKeys(value, ["found"]);
+    if (!hasExactKeys(value, ["found", "state", "terminal", "updatedAt", "deadlineAt"], ["pendingForMs", "safeErrorCode"]) ||
+        !isDeliveryStatusState(value.state) ||
+        typeof value.terminal !== "boolean" ||
+        value.terminal !== TERMINAL_DELIVERY_STATUS_STATES.has(value.state) ||
+        !isIsoTimestamp(value.updatedAt) ||
+        !isIsoTimestamp(value.deadlineAt) ||
+        (value.pendingForMs !== undefined &&
+            !isNonNegativeInteger(value.pendingForMs)) ||
+        (value.safeErrorCode !== undefined && !isSafeCode(value.safeErrorCode))) {
+        return false;
+    }
+    return true;
+}
+function isRouteCounters(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, [
+            "accepted",
+            "delivered",
+            "unconfirmed",
+            "failed",
+            "ambiguous",
+            "expired",
+            "cancelled",
+            "abandoned",
+            "rejected",
+            "bytesAccepted",
+        ])) {
+        return false;
+    }
+    return Object.values(value).every(isNonNegativeInteger);
+}
+function isConnectorSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "provider",
+            "host",
+            "health",
+            "compatibility",
+            "protocol",
+            "protocolVersion",
+        ], ["lastSeenAt", "safeErrorCode"]) &&
+        isProvider(value.provider) &&
+        isHostId(value.host) &&
+        isConnectorHealth(value.health) &&
+        isCompatibility(value.compatibility) &&
+        typeof value.protocol === "string" &&
+        PROTOCOL_PATTERN.test(value.protocol) &&
+        typeof value.protocolVersion === "string" &&
+        PROTOCOL_VERSION_PATTERN.test(value.protocolVersion) &&
+        (value.lastSeenAt === undefined || isIsoTimestamp(value.lastSeenAt)) &&
+        (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)));
+}
+function isRouteSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "alias",
+            "provider",
+            "host",
+            "enabled",
+            "state",
+            "compatibility",
+            "busyPolicy",
+            "queueDepth",
+            "counters",
+        ], ["lastSeenAt", "oldestQueuedAt", "safeErrorCode"]) &&
+        isAlias(value.alias) &&
+        isProvider(value.provider) &&
+        isHostId(value.host) &&
+        value.alias.endsWith(`@${value.host}`) &&
+        typeof value.enabled === "boolean" &&
+        (value.state === "stale" ||
+            value.state === "idle" ||
+            value.state === "busy" ||
+            value.state === "awaiting_approval" ||
+            value.state === "offline" ||
+            value.state === "incompatible" ||
+            value.state === "disabled") &&
+        isCompatibility(value.compatibility) &&
+        value.busyPolicy === "queue" &&
+        (value.lastSeenAt === undefined || isIsoTimestamp(value.lastSeenAt)) &&
+        isNonNegativeInteger(value.queueDepth) &&
+        (value.oldestQueuedAt === undefined
+            ? value.queueDepth === 0
+            : value.queueDepth > 0 && isIsoTimestamp(value.oldestQueuedAt)) &&
+        isRouteCounters(value.counters) &&
+        (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)));
+}
+function isPairSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["claudeAlias", "codexAlias", "host", "counters"]) &&
+        isAlias(value.claudeAlias) &&
+        isAlias(value.codexAlias) &&
+        value.claudeAlias !== value.codexAlias &&
+        isHostId(value.host) &&
+        value.claudeAlias.endsWith(`@${value.host}`) &&
+        value.codexAlias.endsWith(`@${value.host}`) &&
+        isRouteCounters(value.counters));
+}
+function isAvailablePeerSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "alias",
+            "provider",
+            "host",
+            "state",
+            "compatibility",
+            "validated",
+            "selected",
+        ], ["lastSeenAt", "safeErrorCode"]) &&
+        isAlias(value.alias) &&
+        value.provider === "claude" &&
+        isHostId(value.host) &&
+        value.alias.endsWith(`@${value.host}`) &&
+        (value.state === "idle" ||
+            value.state === "busy" ||
+            value.state === "awaiting_approval" ||
+            value.state === "offline" ||
+            value.state === "incompatible") &&
+        isCompatibility(value.compatibility) &&
+        typeof value.validated === "boolean" &&
+        typeof value.selected === "boolean" &&
+        (value.lastSeenAt === undefined || isIsoTimestamp(value.lastSeenAt)) &&
+        (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)));
+}
+function isNormalizedMessageEvent(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "sequence",
+            "timestamp",
+            "messageIdSuffix",
+            "direction",
+            "sourceAlias",
+            "targetAlias",
+            "state",
+            "bytes",
+            "hopCount",
+        ], ["conversationIdSuffix", "latencyMs", "safeErrorCode", "steer"]) &&
+        isNonNegativeInteger(value.sequence) &&
+        isIsoTimestamp(value.timestamp) &&
+        typeof value.messageIdSuffix === "string" &&
+        MESSAGE_SUFFIX_PATTERN.test(value.messageIdSuffix) &&
+        (value.conversationIdSuffix === undefined ||
+            (typeof value.conversationIdSuffix === "string" &&
+                CONVERSATION_SUFFIX_PATTERN.test(value.conversationIdSuffix))) &&
+        (value.direction === "codex_to_claude" ||
+            value.direction === "claude_to_codex") &&
+        isAlias(value.sourceAlias) &&
+        isAlias(value.targetAlias) &&
+        (value.state === "queued" ||
+            value.state === "duplicate" ||
+            value.state === "dispatching" ||
+            value.state === "transport_written" ||
+            value.state === "held" ||
+            value.state === "delivered" ||
+            value.state === "unconfirmed" ||
+            value.state === "failed" ||
+            value.state === "ambiguous" ||
+            value.state === "expired" ||
+            value.state === "cancelled" ||
+            value.state === "abandoned" ||
+            value.state === "rejected") &&
+        isNonNegativeInteger(value.bytes) &&
+        isNonNegativeInteger(value.hopCount) &&
+        (value.latencyMs === undefined || isNonNegativeInteger(value.latencyMs)) &&
+        (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)) &&
+        (value.steer === undefined || value.steer === true));
+}
+function isAccounting(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, [
+            "accepted",
+            "duplicates",
+            "delivered",
+            "unconfirmed",
+            "failed",
+            "ambiguous",
+            "expired",
+            "cancelled",
+            "abandoned",
+            "rejected",
+            "bytesAccepted",
+            "queuedBytes",
+        ])) {
+        return false;
+    }
+    return Object.values(value).every(isNonNegativeInteger);
+}
+function isSafeAlert(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["code", "severity", "timestamp"], [
+            "provider",
+            "host",
+            "alias",
+        ]) &&
+        isSafeCode(value.code) &&
+        (value.severity === "info" ||
+            value.severity === "warning" ||
+            value.severity === "error") &&
+        isIsoTimestamp(value.timestamp) &&
+        (value.provider === undefined || isProvider(value.provider)) &&
+        (value.host === undefined || isHostId(value.host)) &&
+        (value.alias === undefined || isAlias(value.alias)));
+}
+function isProgressWatchSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "conversationIdSuffix",
+            "ownerAlias",
+            "workerAlias",
+            "phase",
+            "capability",
+            "lastActivityAt",
+            "nextActionAt",
+            "idleMs",
+            "nudgeCount",
+            "workerReportedComplete",
+        ]) &&
+        typeof value.conversationIdSuffix === "string" &&
+        CONVERSATION_SUFFIX_PATTERN.test(value.conversationIdSuffix) &&
+        isAlias(value.ownerAlias) &&
+        isAlias(value.workerAlias) &&
+        value.ownerAlias !== value.workerAlias &&
+        (value.phase === "quiet" || value.phase === "episode") &&
+        (value.capability === "conversation" || value.capability === "route") &&
+        isIsoTimestamp(value.lastActivityAt) &&
+        isIsoTimestamp(value.nextActionAt) &&
+        typeof value.idleMs === "number" &&
+        isTrackIdleMinutes(value.idleMs / 60_000) &&
+        (value.nudgeCount === 0 || value.nudgeCount === 1 || value.nudgeCount === 2) &&
+        typeof value.workerReportedComplete === "boolean");
+}
+function isProgressWatchEventSnapshot(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "sequence",
+            "timestamp",
+            "conversationIdSuffix",
+            "ownerAlias",
+            "workerAlias",
+            "kind",
+        ], ["nudgeNumber"]) &&
+        isNonNegativeInteger(value.sequence) &&
+        isIsoTimestamp(value.timestamp) &&
+        typeof value.conversationIdSuffix === "string" &&
+        CONVERSATION_SUFFIX_PATTERN.test(value.conversationIdSuffix) &&
+        isAlias(value.ownerAlias) &&
+        isAlias(value.workerAlias) &&
+        [
+            "opened",
+            "nudge",
+            "worker_reported_complete",
+            "capability_degraded",
+            "done",
+            "unresponsive",
+            "endpoint_retired",
+            "disabled",
+        ].includes(String(value.kind)) &&
+        (value.nudgeNumber === undefined ||
+            value.nudgeNumber === 1 ||
+            value.nudgeNumber === 2) &&
+        ((value.kind === "nudge") === (value.nudgeNumber !== undefined)));
+}
+function isGatewayActivityEvent(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "sequence",
+            "timestamp",
+            "kind",
+            "action",
+            "outcome",
+            "aliases",
+            "operatorAction",
+        ], ["safeErrorCode"]) &&
+        isNonNegativeInteger(value.sequence) &&
+        value.sequence > 0 &&
+        isIsoTimestamp(value.timestamp) &&
+        ["discovery", "selection", "registration", "pairing", "watch"].includes(String(value.kind)) &&
+        [
+            "discovery_refreshed",
+            "claude_selected",
+            "claude_unselected",
+            "codex_registered",
+            "codex_succeeded",
+            "codex_unregistered",
+            "routes_paired",
+            "routes_unpaired",
+            "watch_ended",
+        ].includes(String(value.action)) &&
+        (value.outcome === "accepted" || value.outcome === "rejected") &&
+        Array.isArray(value.aliases) &&
+        value.aliases.length <= 2 &&
+        value.aliases.every(isAlias) &&
+        new Set(value.aliases).size === value.aliases.length &&
+        value.operatorAction === true &&
+        (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)));
+}
+function isDeadlinePressure(value) {
+    const names = [
+        "under_1m",
+        "1m_to_5m",
+        "5m_to_15m",
+        "15m_to_60m",
+        "over_60m",
+    ];
+    return (isRecord(value) &&
+        hasExactKeys(value, ["configuredDeadlineMs", "terminalEvents", "expiredEvents", "buckets"], ["retainedSince"]) &&
+        isNonNegativeInteger(value.configuredDeadlineMs) &&
+        value.configuredDeadlineMs > 0 &&
+        (value.retainedSince === undefined || isIsoTimestamp(value.retainedSince)) &&
+        isNonNegativeInteger(value.terminalEvents) &&
+        isNonNegativeInteger(value.expiredEvents) &&
+        value.expiredEvents <= value.terminalEvents &&
+        Array.isArray(value.buckets) &&
+        value.buckets.length === names.length &&
+        value.buckets.every((bucket, index) => isRecord(bucket) &&
+            hasExactKeys(bucket, ["bucket", "settled", "expired"]) &&
+            bucket.bucket === names[index] &&
+            isNonNegativeInteger(bucket.settled) &&
+            isNonNegativeInteger(bucket.expired) &&
+            bucket.expired <= bucket.settled) &&
+        value.buckets.reduce((sum, bucket) => sum + Number(bucket.settled), 0) ===
+            value.terminalEvents &&
+        value.buckets.reduce((sum, bucket) => sum + Number(bucket.expired), 0) ===
+            value.expiredEvents);
+}
+function isSnapshotTruncation(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, [
+            "connectors",
+            "availablePeers",
+            "routes",
+            "pairs",
+            "messages",
+            "alerts",
+        ], [
+            "compatibilityChecks",
+            "progressWatches",
+            "progressWatchEvents",
+            "activityEvents",
+        ]) &&
+        isNonNegativeInteger(value.connectors) &&
+        isNonNegativeInteger(value.availablePeers) &&
+        isNonNegativeInteger(value.routes) &&
+        isNonNegativeInteger(value.pairs) &&
+        isNonNegativeInteger(value.messages) &&
+        isNonNegativeInteger(value.alerts) &&
+        (value.compatibilityChecks === undefined ||
+            isNonNegativeInteger(value.compatibilityChecks)) &&
+        (value.progressWatches === undefined ||
+            isNonNegativeInteger(value.progressWatches)) &&
+        (value.progressWatchEvents === undefined ||
+            isNonNegativeInteger(value.progressWatchEvents)) &&
+        (value.activityEvents === undefined ||
+            isNonNegativeInteger(value.activityEvents)));
+}
+export function isGatewaySnapshot(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, [
+            "schemaVersion",
+            "generatedAt",
+            "inboundMode",
+            "health",
+            "connectors",
+            "availablePeers",
+            "routes",
+            "pairs",
+            "messages",
+            "accounting",
+            "alerts",
+            "truncation",
+        ], [
+            "compatibilityChecks",
+            "progressWatches",
+            "progressWatchEvents",
+            "activityEvents",
+            "deadlinePressure",
+        ]) ||
+        value.schemaVersion !== 1 ||
+        !isIsoTimestamp(value.generatedAt) ||
+        (value.inboundMode !== "paired" && value.inboundMode !== "open") ||
+        !isConnectorHealth(value.health) ||
+        !Array.isArray(value.connectors) ||
+        value.connectors.length > gatewayPublicSnapshotLimits.connectors ||
+        !value.connectors.every(isConnectorSnapshot) ||
+        (value.compatibilityChecks !== undefined &&
+            (!Array.isArray(value.compatibilityChecks) ||
+                value.compatibilityChecks.length >
+                    gatewayPublicSnapshotLimits.compatibilityChecks ||
+                !value.compatibilityChecks.every(isCompatibilityAttestation))) ||
+        !Array.isArray(value.availablePeers) ||
+        value.availablePeers.length > gatewayPublicSnapshotLimits.availablePeers ||
+        !value.availablePeers.every(isAvailablePeerSnapshot) ||
+        !Array.isArray(value.routes) ||
+        value.routes.length > gatewayPublicSnapshotLimits.routes ||
+        !value.routes.every(isRouteSnapshot) ||
+        !Array.isArray(value.pairs) ||
+        value.pairs.length > gatewayPublicSnapshotLimits.pairs ||
+        !value.pairs.every(isPairSnapshot) ||
+        (value.progressWatches !== undefined &&
+            (!Array.isArray(value.progressWatches) ||
+                value.progressWatches.length >
+                    gatewayPublicSnapshotLimits.progressWatches ||
+                !value.progressWatches.every(isProgressWatchSnapshot))) ||
+        (value.progressWatchEvents !== undefined &&
+            (!Array.isArray(value.progressWatchEvents) ||
+                value.progressWatchEvents.length >
+                    gatewayPublicSnapshotLimits.progressWatchEvents ||
+                !value.progressWatchEvents.every(isProgressWatchEventSnapshot))) ||
+        (value.activityEvents !== undefined &&
+            (!Array.isArray(value.activityEvents) ||
+                value.activityEvents.length >
+                    gatewayPublicSnapshotLimits.activityEvents ||
+                !value.activityEvents.every(isGatewayActivityEvent))) ||
+        (value.deadlinePressure !== undefined &&
+            !isDeadlinePressure(value.deadlinePressure)) ||
+        !Array.isArray(value.messages) ||
+        value.messages.length > gatewayPublicSnapshotLimits.messages ||
+        !value.messages.every(isNormalizedMessageEvent) ||
+        !isAccounting(value.accounting) ||
+        !Array.isArray(value.alerts) ||
+        value.alerts.length > gatewayPublicSnapshotLimits.alerts ||
+        !value.alerts.every(isSafeAlert) ||
+        !isSnapshotTruncation(value.truncation)) {
+        return false;
+    }
+    const connectorKeys = value.connectors.map((connector) => `${connector.provider}@${connector.host}`);
+    const aliases = value.routes.map((route) => route.alias);
+    const peerAliases = value.availablePeers.map((peer) => peer.alias);
+    const pairKeys = value.pairs.map((pair) => `${pair.claudeAlias}\0${pair.codexAlias}`);
+    const routeByAlias = new Map(value.routes.map((route) => [route.alias, route]));
+    return (new Set(connectorKeys).size === connectorKeys.length &&
+        new Set(aliases).size === aliases.length &&
+        new Set(peerAliases).size === peerAliases.length &&
+        new Set(pairKeys).size === pairKeys.length &&
+        value.pairs.every((pair) => routeByAlias.get(pair.claudeAlias)?.provider === "claude" &&
+            routeByAlias.get(pair.codexAlias)?.provider === "codex") &&
+        Buffer.byteLength(JSON.stringify(value), "utf8") <=
+            GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET);
+}
+function isSnapshotObservation(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["snapshotRevision", "snapshot"]) &&
+        isNonNegativeInteger(value.snapshotRevision) &&
+        isGatewaySnapshot(value.snapshot));
+}
+function isResultForMethod(method, value) {
+    switch (method) {
+        case "health":
+            return isHealthResult(value);
+        case "register_codex":
+        case "unregister_codex":
+        case "select_claude":
+        case "unselect_claude":
+        case "pair":
+        case "unpair":
+            return isDecision(value);
+        case "list_snapshot":
+            return isGatewaySnapshot(value);
+        case "observe_snapshot":
+            return isSnapshotObservation(value);
+        case "compat_check":
+            return isCompatibilityCheckReport(value);
+        case "compat_certify":
+            return isCompatibilityCertificationReport(value);
+        case "delivery_status":
+            return isDeliveryStatusResult(value);
+        case "untrack":
+            return isDecision(value);
+        case "send_to_claude":
+        case "send_to_codex":
+        case "reply":
+            return isSendResult(value);
+        case "refresh_dashboard":
+            return isRefreshResult(value);
+    }
+}
+function errorResponse(code) {
+    return {
+        protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION,
+        ok: false,
+        error: { code, message: WIRE_ERROR_MESSAGES[code] },
+    };
+}
+async function dispatch(request, handlers) {
+    let result;
+    try {
+        switch (request.method) {
+            case "health":
+                result = await handlers.health();
+                break;
+            case "register_codex":
+                result = await handlers.registerCodex(request.params);
+                break;
+            case "unregister_codex":
+                result = await handlers.unregisterCodex(request.params);
+                break;
+            case "select_claude":
+                result = await handlers.selectClaude(request.params);
+                break;
+            case "unselect_claude":
+                result = await handlers.unselectClaude(request.params);
+                break;
+            case "pair":
+                result = await handlers.pair(request.params);
+                break;
+            case "unpair":
+                result = await handlers.unpair(request.params);
+                break;
+            case "list_snapshot":
+                result = await handlers.listSnapshot();
+                break;
+            case "observe_snapshot":
+                result = await handlers.observeSnapshot();
+                break;
+            case "compat_check":
+                result = await handlers.compatibilityCheck();
+                break;
+            case "compat_certify":
+                result = await handlers.compatibilityCertify(request.params);
+                break;
+            case "delivery_status":
+                result = await handlers.deliveryStatus(request.params);
+                break;
+            case "untrack":
+                result = await handlers.untrack(request.params);
+                break;
+            case "send_to_claude":
+                result = await handlers.sendToClaude(request.params);
+                break;
+            case "send_to_codex":
+                result = await handlers.sendToCodex(request.params);
+                break;
+            case "reply":
+                result = await handlers.reply(request.params);
+                break;
+            case "refresh_dashboard":
+                result = await handlers.refreshDashboard();
+                break;
+        }
+    }
+    catch {
+        return errorResponse("HANDLER_FAILURE");
+    }
+    if (!isResultForMethod(request.method, result)) {
+        return errorResponse("INVALID_HANDLER_RESPONSE");
+    }
+    return {
+        protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION,
+        ok: true,
+        result,
+    };
+}
+function serializeResponse(response) {
+    const encoded = Buffer.from(`${JSON.stringify(response)}\n`, "utf8");
+    if (encoded.length <= GATEWAY_CONTROL_MAX_RESPONSE_BYTES)
+        return encoded;
+    return Buffer.from(`${JSON.stringify(errorResponse("RESPONSE_TOO_LARGE"))}\n`, "utf8");
+}
+function respond(socket, response) {
+    if (socket.destroyed)
+        return;
+    let encoded;
+    try {
+        encoded = serializeResponse(response);
+    }
+    catch {
+        encoded = Buffer.from(`${JSON.stringify(errorResponse("INVALID_HANDLER_RESPONSE"))}\n`, "utf8");
+    }
+    socket.end(encoded);
+}
+function handleConnection(socket, handlers, requestTimeoutMs) {
+    let buffered = Buffer.alloc(0);
+    let completed = false;
+    const complete = (response) => {
+        if (completed)
+            return;
+        completed = true;
+        socket.pause();
+        socket.setTimeout(0);
+        respond(socket, response);
+    };
+    socket.setTimeout(requestTimeoutMs);
+    socket.once("timeout", () => complete(errorResponse("REQUEST_TIMEOUT")));
+    socket.on("error", () => {
+        completed = true;
+    });
+    socket.on("data", (chunk) => {
+        if (completed)
+            return;
+        if (buffered.length + chunk.length > GATEWAY_CONTROL_MAX_FRAME_BYTES) {
+            complete(errorResponse("FRAME_TOO_LARGE"));
+            return;
+        }
+        buffered = Buffer.concat([buffered, chunk]);
+        const newline = buffered.indexOf(0x0a);
+        if (newline < 0)
+            return;
+        const trailing = buffered.subarray(newline + 1).toString("utf8");
+        if (trailing.trim().length > 0) {
+            complete(errorResponse("MULTIPLE_FRAMES"));
+            return;
+        }
+        const frame = buffered.subarray(0, newline);
+        let request;
+        try {
+            request = parseRequestFrame(frame);
+        }
+        catch (error) {
+            const code = error instanceof ProtocolFault ? error.code : "INVALID_REQUEST";
+            complete(errorResponse(code));
+            return;
+        }
+        completed = true;
+        socket.pause();
+        socket.setTimeout(0);
+        void dispatch(request, handlers).then((response) => respond(socket, response), () => respond(socket, errorResponse("HANDLER_FAILURE")));
+    });
+    socket.once("end", () => {
+        if (!completed)
+            socket.destroy();
+    });
+}
+function controlTransportError(code, ambiguous = false) {
+    const messages = {
+        UNSUPPORTED_PLATFORM: "Unix-domain gateway control sockets are unavailable.",
+        INVALID_STATE_DIR: "The gateway state directory is invalid.",
+        INSECURE_STATE_DIR: "The gateway state directory is not private to this user.",
+        INVALID_SOCKET_PATH: "The gateway control socket path is invalid.",
+        UNSAFE_SOCKET_TARGET: "The gateway control socket target is unsafe.",
+        SOCKET_IN_USE: "The gateway control socket is already served by a live process.",
+        SOCKET_PROBE_FAILED: "The gateway control socket could not be checked safely.",
+        SOCKET_BIND_FAILED: "The gateway control socket could not be bound.",
+        SOCKET_PERMISSION_FAILED: "The gateway control socket permissions could not be secured.",
+        SOCKET_CLEANUP_CONFLICT: "The gateway control socket path changed during cleanup.",
+        CONTROL_CONNECT_FAILED: "The gateway control socket could not be reached.",
+        CONTROL_TIMEOUT: "The gateway control request timed out.",
+        CONTROL_RESPONSE_TOO_LARGE: "The gateway control response exceeds the client limit.",
+        CONTROL_INVALID_RESPONSE: "The gateway returned an invalid control response.",
+        CONTROL_CONNECTION_CLOSED: "The gateway closed before returning a control response.",
+        CONTROL_OUTCOME_AMBIGUOUS: "The gateway may have applied the control mutation before the response was lost; do not retry automatically.",
+    };
+    return new GatewayControlTransportError(code, messages[code] ?? "The gateway control transport failed.", ambiguous);
+}
+function isNonIdempotentControlMethod(method) {
+    return (method === "register_codex" ||
+        method === "unregister_codex" ||
+        method === "select_claude" ||
+        method === "unselect_claude" ||
+        method === "pair" ||
+        method === "unpair" ||
+        method === "compat_certify" ||
+        method === "send_to_claude" ||
+        method === "send_to_codex" ||
+        method === "reply");
+}
+async function optionalLstat(target) {
+    try {
+        return await lstat(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function validateSocketLocation(stateDir, socketPath) {
+    if (process.platform === "win32") {
+        throw controlTransportError("UNSUPPORTED_PLATFORM");
+    }
+    if (!path.isAbsolute(stateDir) ||
+        path.resolve(stateDir) !== stateDir ||
+        !path.isAbsolute(socketPath) ||
+        path.resolve(socketPath) !== socketPath ||
+        Buffer.byteLength(socketPath, "utf8") > MAX_SOCKET_PATH_BYTES) {
+        throw controlTransportError("INVALID_SOCKET_PATH");
+    }
+    let stateInfo;
+    try {
+        stateInfo = await lstat(stateDir);
+    }
+    catch {
+        throw controlTransportError("INVALID_STATE_DIR");
+    }
+    if (stateInfo.isSymbolicLink() || !stateInfo.isDirectory()) {
+        throw controlTransportError("INVALID_STATE_DIR");
+    }
+    const getuid = process.getuid;
+    if ((getuid !== undefined && stateInfo.uid !== getuid.call(process)) ||
+        (stateInfo.mode & 0o077) !== 0) {
+        throw controlTransportError("INSECURE_STATE_DIR");
+    }
+    let stateReal;
+    let parentReal;
+    try {
+        [stateReal, parentReal] = await Promise.all([
+            realpath(stateDir),
+            realpath(path.dirname(socketPath)),
+        ]);
+    }
+    catch {
+        throw controlTransportError("INVALID_SOCKET_PATH");
+    }
+    if (socketPath === stateDir ||
+        (parentReal !== stateReal &&
+            !parentReal.startsWith(`${stateReal}${path.sep}`))) {
+        throw controlTransportError("INVALID_SOCKET_PATH");
+    }
+}
+async function socketIsLive(socketPath) {
+    return await new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        let settled = false;
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            action();
+        };
+        socket.setTimeout(250);
+        socket.once("connect", () => finish(() => resolve(true)));
+        socket.once("timeout", () => finish(() => reject(controlTransportError("SOCKET_PROBE_FAILED"))));
+        socket.once("error", (error) => {
+            if (error.code === "ECONNREFUSED" || error.code === "ENOENT") {
+                finish(() => resolve(false));
+            }
+            else {
+                finish(() => reject(controlTransportError("SOCKET_PROBE_FAILED")));
+            }
+        });
+    });
+}
+function sameIdentity(info, identity) {
+    return info.dev === identity.dev && info.ino === identity.ino;
+}
+async function prepareSocketTarget(socketPath) {
+    let existing;
+    try {
+        existing = await optionalLstat(socketPath);
+    }
+    catch {
+        throw controlTransportError("UNSAFE_SOCKET_TARGET");
+    }
+    if (!existing)
+        return;
+    if (existing.isSymbolicLink() || !existing.isSocket()) {
+        throw controlTransportError("UNSAFE_SOCKET_TARGET");
+    }
+    const identity = { dev: existing.dev, ino: existing.ino };
+    if (await socketIsLive(socketPath)) {
+        throw controlTransportError("SOCKET_IN_USE");
+    }
+    let current;
+    try {
+        current = await lstat(socketPath);
+    }
+    catch {
+        throw controlTransportError("UNSAFE_SOCKET_TARGET");
+    }
+    if (!current.isSocket() || !sameIdentity(current, identity)) {
+        throw controlTransportError("UNSAFE_SOCKET_TARGET");
+    }
+    try {
+        await unlink(socketPath);
+    }
+    catch {
+        throw controlTransportError("UNSAFE_SOCKET_TARGET");
+    }
+}
+async function closeNativeServer(server) {
+    await new Promise((resolve) => {
+        try {
+            server.close(() => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+async function removeOwnedSocket(socketPath, identity) {
+    let current;
+    try {
+        current = await optionalLstat(socketPath);
+    }
+    catch {
+        return;
+    }
+    if (!current)
+        return;
+    if (!current.isSocket() || !sameIdentity(current, identity))
+        return;
+    try {
+        await unlink(socketPath);
+    }
+    catch {
+        // The server is already closed. A failed best-effort exact unlink must not
+        // broaden cleanup to any replacement path.
+    }
+}
+async function protectSocketReplacement(socketPath, identity) {
+    let current;
+    try {
+        current = await optionalLstat(socketPath);
+    }
+    catch {
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+    if (!current || sameIdentity(current, identity))
+        return undefined;
+    let directory;
+    try {
+        directory = await mkdtemp(path.join(path.dirname(socketPath), ".gateway-control-close-"));
+    }
+    catch {
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+    const backupPath = path.join(directory, "replacement");
+    try {
+        await rename(socketPath, backupPath);
+    }
+    catch (error) {
+        await rmdir(directory).catch(() => undefined);
+        if (error.code === "ENOENT")
+            return undefined;
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+    return { directory, backupPath };
+}
+async function restoreSocketReplacement(socketPath, replacement) {
+    if (!replacement)
+        return;
+    let current;
+    try {
+        current = await optionalLstat(socketPath);
+    }
+    catch {
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+    if (current) {
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+    try {
+        await rename(replacement.backupPath, socketPath);
+        await rmdir(replacement.directory);
+    }
+    catch {
+        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
+    }
+}
+function validServerTimeout(value) {
+    return Number.isInteger(value) && value >= 50 && value <= 30_000;
+}
+function validClientTimeout(value) {
+    return Number.isInteger(value) && value >= 50 && value <= 90_000;
+}
+export async function startGatewayControlServer(options) {
+    await validateSocketLocation(options.stateDir, options.socketPath);
+    await prepareSocketTarget(options.socketPath);
+    const requestTimeoutMs = options.requestTimeoutMs ?? GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS;
+    if (!validServerTimeout(requestTimeoutMs)) {
+        throw controlTransportError("INVALID_SOCKET_PATH");
+    }
+    const connections = new Set();
+    const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+        // Directory ownership proves same-user access, not that every caller is a
+        // trusted agent. Bound idle and in-flight peers before allocating parser or
+        // handler state so a local peer cannot grow this set without limit.
+        if (connections.size >= GATEWAY_CONTROL_MAX_CONNECTIONS) {
+            socket.once("error", () => socket.destroy());
+            socket.end(serializeResponse(errorResponse("SERVER_BUSY")), () => socket.destroy());
+            return;
+        }
+        connections.add(socket);
+        socket.once("close", () => connections.delete(socket));
+        handleConnection(socket, options.handlers, requestTimeoutMs);
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            const onError = () => reject(controlTransportError("SOCKET_BIND_FAILED"));
+            server.once("error", onError);
+            server.listen(options.socketPath, () => {
+                server.off("error", onError);
+                resolve();
+            });
+        });
+    }
+    catch (error) {
+        await closeNativeServer(server);
+        throw error;
+    }
+    let identity;
+    try {
+        const info = await lstat(options.socketPath);
+        if (!info.isSocket())
+            throw new Error("not a socket");
+        identity = { dev: info.dev, ino: info.ino };
+        await chmod(options.socketPath, 0o600);
+        const secured = await lstat(options.socketPath);
+        if (!secured.isSocket() ||
+            !sameIdentity(secured, identity) ||
+            (secured.mode & 0o777) !== 0o600) {
+            throw new Error("socket identity changed");
+        }
+    }
+    catch {
+        for (const connection of connections)
+            connection.destroy();
+        await closeNativeServer(server);
+        if (identity)
+            await removeOwnedSocket(options.socketPath, identity);
+        throw controlTransportError("SOCKET_PERMISSION_FAILED");
+    }
+    const ownedIdentity = identity;
+    let closed = false;
+    let closePromise;
+    const close = () => {
+        closePromise ??= (async () => {
+            const replacement = await protectSocketReplacement(options.socketPath, ownedIdentity);
+            for (const connection of connections)
+                connection.destroy();
+            await closeNativeServer(server);
+            await removeOwnedSocket(options.socketPath, ownedIdentity);
+            await restoreSocketReplacement(options.socketPath, replacement);
+            closed = true;
+        })();
+        return closePromise;
+    };
+    return {
+        socketPath: options.socketPath,
+        get closed() {
+            return closed;
+        },
+        close,
+    };
+}
+function validateResponseForMethod(method, value) {
+    if (!isRecord(value) || value.protocolVersion !== 1) {
+        throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    }
+    if (value.ok === false) {
+        if (!hasExactKeys(value, ["protocolVersion", "ok", "error"]) ||
+            !isRecord(value.error) ||
+            !hasExactKeys(value.error, ["code", "message"]) ||
+            typeof value.error.code !== "string" ||
+            !Object.hasOwn(WIRE_ERROR_MESSAGES, value.error.code) ||
+            value.error.message !==
+                WIRE_ERROR_MESSAGES[value.error.code]) {
+            throw controlTransportError("CONTROL_INVALID_RESPONSE");
+        }
+        return value;
+    }
+    if (value.ok !== true ||
+        !hasExactKeys(value, ["protocolVersion", "ok", "result"]) ||
+        !isResultForMethod(method, value.result)) {
+        throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    }
+    return value;
+}
+export async function sendGatewayControlRequest(options) {
+    if (!path.isAbsolute(options.socketPath) ||
+        path.resolve(options.socketPath) !== options.socketPath ||
+        Buffer.byteLength(options.socketPath, "utf8") > MAX_SOCKET_PATH_BYTES) {
+        throw controlTransportError("INVALID_SOCKET_PATH");
+    }
+    const timeoutMs = options.timeoutMs ?? GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options.maxResponseBytes ?? GATEWAY_CONTROL_MAX_RESPONSE_BYTES;
+    if (!validClientTimeout(timeoutMs) ||
+        !Number.isInteger(maxResponseBytes) ||
+        maxResponseBytes < 256 ||
+        maxResponseBytes > GATEWAY_CONTROL_MAX_RESPONSE_BYTES) {
+        throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    }
+    const normalized = parseRequestObject(options.request);
+    if (normalized.method !== options.request.method) {
+        throw new ProtocolFault("INVALID_REQUEST");
+    }
+    const requestFrame = Buffer.from(`${JSON.stringify(normalized)}\n`, "utf8");
+    if (requestFrame.length > GATEWAY_CONTROL_MAX_FRAME_BYTES) {
+        throw new ProtocolFault("FRAME_TOO_LARGE");
+    }
+    return await new Promise((resolve, reject) => {
+        const socket = net.createConnection(options.socketPath);
+        let settled = false;
+        let writeStarted = false;
+        let buffered = Buffer.alloc(0);
+        const mutation = isNonIdempotentControlMethod(normalized.method);
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(mutation && writeStarted
+                ? controlTransportError("CONTROL_OUTCOME_AMBIGUOUS", true)
+                : error);
+        };
+        const succeed = (response) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(response);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => {
+            // From this point onward the peer may receive and execute all or part of
+            // the frame. Losing the response to a mutation is therefore ambiguous,
+            // never a safe retry signal.
+            writeStarted = true;
+            socket.write(requestFrame);
+        });
+        socket.once("timeout", () => fail(controlTransportError("CONTROL_TIMEOUT")));
+        socket.once("error", () => fail(controlTransportError("CONTROL_CONNECT_FAILED")));
+        socket.on("data", (chunk) => {
+            if (settled)
+                return;
+            if (buffered.length + chunk.length > maxResponseBytes) {
+                fail(controlTransportError("CONTROL_RESPONSE_TOO_LARGE"));
+                return;
+            }
+            buffered = Buffer.concat([buffered, chunk]);
+            const newline = buffered.indexOf(0x0a);
+            if (newline < 0)
+                return;
+            if (buffered.subarray(newline + 1).toString("utf8").trim().length > 0) {
+                fail(controlTransportError("CONTROL_INVALID_RESPONSE"));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffered.subarray(0, newline)));
+            }
+            catch {
+                fail(controlTransportError("CONTROL_INVALID_RESPONSE"));
+                return;
+            }
+            try {
+                succeed(validateResponseForMethod(options.request.method, parsed));
+            }
+            catch {
+                fail(controlTransportError("CONTROL_INVALID_RESPONSE"));
+            }
+        });
+        socket.once("close", () => {
+            if (!settled) {
+                fail(controlTransportError("CONTROL_CONNECTION_CLOSED"));
+            }
+        });
+    });
+}
+//# sourceMappingURL=control.js.map