agent-embassy 1.9.5 → 3.0.0

package/dist/src/gateway/control.js

@@ -4,10 +4,10 @@ import { chmod, lstat, mkdtemp, realpath, rename, rmdir, unlink } from "node:fs/
 import net from "node:net";
 import path from "node:path";
 import { TextDecoder } from "node:util";
-import { CONNECTOR_OBSERVATION_STALE_AFTER_MS, GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayProviders, gatewayPublicSnapshotLimits, isGatewayProvider, isMessageDirection, isPublicRegistryObservationSnapshot, } from "./types.js";
+import { CONNECTOR_OBSERVATION_STALE_AFTER_MS, GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, isGatewayProvider, isMessageDirection, isPublicRegistryObservationSnapshot, } from "./types.js";
 import { decodePeerParams, decodePeerResult } from "./peer-protocol.js";
 import { isPeerMailboxAwaitResult } from "./peer-mailbox.js";
-export const GATEWAY_CONTROL_PROTOCOL_VERSION = 1;
+export const GATEWAY_CONTROL_PROTOCOL_VERSION = 3;
 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;
@@ -16,7 +16,6 @@ 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 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}$/;
@@ -31,21 +30,15 @@ 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", "remove_codex_registration",
-    "select_claude", "unselect_claude", "pair", "unpair", "list_snapshot",
-    "observe_snapshot", "delivery_status", "untrack", "send_to_claude",
-    "send_to_codex", "reply", "refresh_dashboard", "peer_catalog", "peer_handoff",
+    "health", "register_codex", "unregister_codex", "list_snapshot",
+    "observe_snapshot", "delivery_status", "send",
+    "refresh_discovery", "peer_catalog", "peer_handoff",
     "register_peer", "unregister_peer", "await_peer", "peer_receipt",
 ];
-export function pairParamAliases(params) {
-    return "aliases" in params ? params.aliases : [params.claudeAlias, params.codexAlias];
-}
-export function pairParamThreadAttestation(params) {
-    if ("aliases" in params)
-        return params.threadAttestation;
-    return params.codexThreadId === undefined
-        ? undefined : { alias: params.codexAlias, threadId: params.codexThreadId };
-}
+/** Bounds on an ephemeral peer registration's lifetime, in milliseconds. */
+export const GATEWAY_EPHEMERAL_PEER_TTL_DEFAULT_MS = 300_000;
+export const GATEWAY_EPHEMERAL_PEER_TTL_MIN_MS = 1_000;
+export const GATEWAY_EPHEMERAL_PEER_TTL_MAX_MS = 3_600_000;
 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.",
@@ -66,9 +59,13 @@ const TRANSPORT_MESSAGES = {
     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_CONNECT_DENIED: "The gateway control socket connection was denied by local policy.",
+    CONTROL_SOCKET_MISSING: "The gateway control socket does not exist at the configured path.",
+    CONTROL_LISTENER_UNAVAILABLE: "Nothing is listening on the gateway control socket.",
     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. Restart the broker, then retry.",
+    CONTROL_VERSION_MISMATCH: "The gateway control protocol version does not match this client.",
     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.",
 };
@@ -135,12 +132,6 @@ function isNonNegativeInteger(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;
@@ -165,7 +156,6 @@ function isMessageText(value) {
 }
 const exact = hasExactKeys;
 const nonNegative = isNonNegativeInteger;
-const trackMinutes = isTrackIdleMinutes;
 const iso = isIsoTimestamp;
 const uuid = isUuid;
 const alias = isAlias;
@@ -206,9 +196,20 @@ function decodePeerHandoff(value) {
     }
 }
 function decodeRegisterPeer(value) {
-    if (!shape(value, { alias: peerAlias }, { token: peerToken }))
+    // `ephemeral` belongs only to a first registration: re-presenting a token
+    // proves an existing route, and an existing route's lifetime is already
+    // fixed. `ttlMs` without `ephemeral` would name a lifetime nothing honours.
+    if (!shape(value, { alias: peerAlias }, { token: peerToken, ephemeral: oneOf(true),
+        ttlMs: (item) => Number.isSafeInteger(item) &&
+            Number(item) >= GATEWAY_EPHEMERAL_PEER_TTL_MIN_MS &&
+            Number(item) <= GATEWAY_EPHEMERAL_PEER_TTL_MAX_MS }) ||
+        (value.ephemeral !== undefined && value.token !== undefined) ||
+        (value.ttlMs !== undefined && value.ephemeral === undefined))
         invalid();
-    return { alias: value.alias, ...(value.token === undefined ? {} : { token: value.token }) };
+    return { alias: value.alias,
+        ...(value.token === undefined ? {} : { token: value.token }),
+        ...(value.ephemeral === undefined ? {} : { ephemeral: true }),
+        ...(value.ttlMs === undefined ? {} : { ttlMs: value.ttlMs }) };
 }
 function decodePeerPrincipal(value) {
     if (!shape(value, { alias: peerAlias, token: peerToken }))
@@ -240,142 +241,52 @@ const isPeerHandoffResult = (value) => {
     }
 };
 function decodeRegister(value) {
-    if (!isRecord(value) || !exact(value, ["alias", "threadId"], ["hostId", "busyPolicy", "succeedsAlias"]) ||
+    if (!isRecord(value) || !exact(value, ["alias", "threadId", "hostId", "busyPolicy"], ["succeedsAlias"]) ||
         !alias(value.alias) || !value.alias.startsWith("codex-") || !uuid(value.threadId) ||
-        (value.hostId !== undefined && !host(value.hostId)) ||
-        (value.busyPolicy !== undefined && value.busyPolicy !== "queue") ||
+        !host(value.hostId) || value.busyPolicy !== "queue" ||
         (value.succeedsAlias !== undefined && (!alias(value.succeedsAlias) || !value.succeedsAlias.startsWith("codex-"))))
         invalid();
-    const hostId = value.hostId ?? DEFAULT_HOST_ID;
-    if (!value.alias.endsWith(`@${hostId}`) ||
+    if (!value.alias.endsWith(`@${value.hostId}`) ||
         (value.succeedsAlias !== undefined &&
-            (value.succeedsAlias === value.alias || !value.succeedsAlias.endsWith(`@${hostId}`))))
+            (value.succeedsAlias === value.alias || !value.succeedsAlias.endsWith(`@${value.hostId}`))))
         invalid();
-    return { alias: value.alias, threadId: value.threadId.toLowerCase(), hostId,
-        busyPolicy: "queue", ...(value.succeedsAlias === undefined ? {} : { succeedsAlias: value.succeedsAlias }) };
+    return { alias: value.alias, threadId: value.threadId.toLowerCase(), hostId: value.hostId,
+        busyPolicy: value.busyPolicy, ...(value.succeedsAlias === undefined ? {} : { succeedsAlias: value.succeedsAlias }) };
 }
 function decodeUnregister(value) {
     if (!shape(value, { alias, threadId: uuid }) || !value.alias.startsWith("codex-"))
         invalid();
     return { alias: value.alias, threadId: value.threadId.toLowerCase() };
 }
-function decodeRemoval(value) {
-    if (!shape(value, { alias }) || !value.alias.startsWith("codex-"))
-        invalid();
-    return { alias: value.alias };
-}
-function decodeSelection(value) {
-    if (!isRecord(value) || !exact(value, ["alias"], ["codexThreadId"]) ||
-        typeof value.alias !== "string" || !isClaudeSessionSelector(value.alias) ||
-        (value.codexThreadId !== undefined && !uuid(value.codexThreadId)))
-        invalid();
-    return { alias: UUID_PATTERN.test(value.alias) ? value.alias.toLowerCase() : value.alias,
-        ...(value.codexThreadId === undefined ? {} : { codexThreadId: value.codexThreadId.toLowerCase() }) };
-}
-function decodePair(value) {
-    if (!isRecord(value))
-        invalid();
-    if (Object.hasOwn(value, "aliases")) {
-        if (!exact(value, ["aliases"], ["threadAttestation"]) || !Array.isArray(value.aliases) ||
-            value.aliases.length !== 2 || !alias(value.aliases[0]) || !alias(value.aliases[1]) ||
-            value.aliases[0] === value.aliases[1])
-            invalid();
-        let threadAttestation;
-        if (value.threadAttestation !== undefined) {
-            if (!shape(value.threadAttestation, { alias, threadId: uuid }) ||
-                !value.aliases.includes(value.threadAttestation.alias))
-                invalid();
-            threadAttestation = { alias: value.threadAttestation.alias,
-                threadId: value.threadAttestation.threadId.toLowerCase() };
-        }
-        return { aliases: [value.aliases[0], value.aliases[1]],
-            ...(threadAttestation === undefined ? {} : { threadAttestation }) };
-    }
-    if (!exact(value, ["claudeAlias", "codexAlias"], ["codexThreadId"]) ||
-        typeof value.claudeAlias !== "string" || !isClaudeSessionSelector(value.claudeAlias) ||
-        !alias(value.codexAlias) || !value.codexAlias.startsWith("codex-") ||
-        (value.codexThreadId !== undefined && !uuid(value.codexThreadId)) ||
-        value.claudeAlias === value.codexAlias ||
-        (alias(value.claudeAlias) && value.claudeAlias.slice(value.claudeAlias.lastIndexOf("@") + 1) !==
-            value.codexAlias.slice(value.codexAlias.lastIndexOf("@") + 1)))
-        invalid();
-    return { claudeAlias: UUID_PATTERN.test(value.claudeAlias) ? value.claudeAlias.toLowerCase() : value.claudeAlias,
-        codexAlias: value.codexAlias,
-        ...(value.codexThreadId === undefined ? {} : { codexThreadId: value.codexThreadId.toLowerCase() }) };
-}
-function commonSend(value, required, optional) {
-    if (!isRecord(value) || !exact(value, required, optional) || !alias(value.fromAlias) ||
-        !alias(value.toAlias) || !messageText(value.text) ||
-        (value.expectsReply !== undefined && typeof value.expectsReply !== "boolean") ||
-        (value.trackIdleMinutes !== undefined && !trackMinutes(value.trackIdleMinutes)))
-        invalid();
-    return value;
-}
-function decodeSendClaude(value) {
-    if (!isRecord(value) || !exact(value, ["fromAlias", "toAlias", "text"], ["threadId", "peerToken", "expectsReply", "trackIdleMinutes"]) ||
-        !alias(value.fromAlias) || (value.threadId === undefined) === (value.peerToken === undefined) ||
+function decodeSend(value) {
+    if (!isRecord(value) || !exact(value, ["fromAlias", "text"], ["toAlias", "conversationId", "threadId", "replyAddress", "peerToken", "expectsReply"]) ||
+        !alias(value.fromAlias) || !messageText(value.text) ||
+        [value.toAlias, value.conversationId].filter((item) => item !== undefined).length !== 1 ||
+        (value.toAlias !== undefined && (typeof value.toAlias !== "string" || !isClaudeSessionSelector(value.toAlias))) ||
+        (value.conversationId !== undefined && (typeof value.conversationId !== "string" || !isGatewayConversationId(value.conversationId))) ||
+        [value.threadId, value.replyAddress, value.peerToken].filter((item) => item !== undefined).length !== 1 ||
         (value.threadId !== undefined && !uuid(value.threadId)) ||
-        (value.peerToken !== undefined && !peerToken(value.peerToken)) || typeof value.toAlias !== "string" ||
-        !isClaudeSessionSelector(value.toAlias) || !messageText(value.text) ||
-        (value.expectsReply !== undefined && typeof value.expectsReply !== "boolean") ||
-        (value.trackIdleMinutes !== undefined && !trackMinutes(value.trackIdleMinutes)))
-        invalid();
-    return { fromAlias: value.fromAlias,
-        toAlias: UUID_PATTERN.test(value.toAlias) ? value.toAlias.toLowerCase() : value.toAlias,
-        text: value.text, expectsReply: value.expectsReply ?? false,
-        ...(typeof value.threadId === "string" ? { threadId: value.threadId.toLowerCase() } : { peerToken: value.peerToken }),
-        ...(value.trackIdleMinutes === undefined ? {} : { trackIdleMinutes: value.trackIdleMinutes }) };
-}
-function decodeSendCodex(value) {
-    const row = commonSend(value, ["fromAlias", "toAlias", "text"], ["replyAddress", "peerToken", "expectsReply", "trackIdleMinutes"]);
-    if ((row.replyAddress === undefined) === (row.peerToken === undefined) ||
-        (row.replyAddress !== undefined && (typeof row.replyAddress !== "string" || !isGatewayReplyAddress(row.replyAddress))) ||
-        (row.peerToken !== undefined && !peerToken(row.peerToken)))
-        invalid();
-    const replyAddress = row.replyAddress !== undefined;
-    return { fromAlias: row.fromAlias, toAlias: row.toAlias, text: row.text,
-        ...(replyAddress ? { replyAddress: row.replyAddress } : { peerToken: row.peerToken }),
-        expectsReply: row.expectsReply === true,
-        ...(row.trackIdleMinutes === undefined ? {} : { trackIdleMinutes: row.trackIdleMinutes }) };
-}
-function normalizeReplyCaller(value) {
-    if (!isRecord(value))
-        invalid();
-    if (value.kind === "codex" && shape(value, { kind: oneOf("codex"), alias, threadId: uuid }))
-        return { kind: "codex", alias: value.alias,
-            threadId: value.threadId.toLowerCase() };
-    if (value.kind === "claude" && isRecord(value) && exact(value, ["kind", "alias"], ["replyAddress"]) &&
-        alias(value.alias) && (value.replyAddress === undefined ||
-        (typeof value.replyAddress === "string" && isGatewayReplyAddress(value.replyAddress))))
-        return { kind: "claude", alias: value.alias,
-            ...(value.replyAddress === undefined ? {} : { replyAddress: value.replyAddress }) };
-    if (value.kind === "peer" && shape(value, { kind: oneOf("peer"), alias: peerAlias, token: peerToken }))
-        return { kind: "peer", alias: value.alias, token: value.token };
-    return invalid();
-}
-function decodeReply(value) {
-    if (!isRecord(value) || !exact(value, ["conversationId", "text", "caller"], ["trackIdleMinutes"]) ||
-        typeof value.conversationId !== "string" || !isGatewayConversationId(value.conversationId) ||
-        !messageText(value.text) ||
-        (value.trackIdleMinutes !== undefined && !trackMinutes(value.trackIdleMinutes)))
+        (value.replyAddress !== undefined && (typeof value.replyAddress !== "string" || !isGatewayReplyAddress(value.replyAddress))) ||
+        (value.peerToken !== undefined && !peerToken(value.peerToken)) ||
+        (value.expectsReply !== undefined &&
+            (typeof value.expectsReply !== "boolean" || value.conversationId !== undefined)))
         invalid();
-    return { conversationId: value.conversationId, text: value.text, caller: normalizeReplyCaller(value.caller),
-        ...(value.trackIdleMinutes === undefined ? {} : { trackIdleMinutes: value.trackIdleMinutes }) };
+    const authority = value.threadId !== undefined ? { threadId: value.threadId.toLowerCase() }
+        : value.replyAddress !== undefined ? { replyAddress: value.replyAddress }
+            : { peerToken: value.peerToken };
+    const target = value.conversationId !== undefined
+        ? { conversationId: value.conversationId }
+        : { toAlias: UUID_PATTERN.test(value.toAlias) ? value.toAlias.toLowerCase() : value.toAlias,
+            expectsReply: value.expectsReply === true };
+    return { fromAlias: value.fromAlias, text: value.text, ...target, ...authority };
 }
 function decodeDeliveryStatus(value) {
     if (!shape(value, { token: (item) => typeof item === "string" && DELIVERY_TOKEN_PATTERN.test(item) }))
         invalid();
     return { token: value.token };
 }
-function decodeUntrack(value) {
-    if (!shape(value, { conversationId: (item) => typeof item === "string" && CONVERSATION_ID_PATTERN.test(item) }))
-        invalid();
-    return { conversationId: value.conversationId };
-}
 function isDecision(value) {
-    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "watch_owner_conflict", "route_mismatch", "busy", "unavailable", "rejected") }, { ownerHost: host }) && (value.accepted === true
-        ? value.code === "ok" && value.ownerHost === undefined
-        : value.code !== "ok" && (value.ownerHost === undefined || value.code === "conflict"));
+    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected") }) && (value.accepted === true ? value.code === "ok" : value.code !== "ok");
 }
 function isRegisterPeerResult(value) {
     return isDecision(value) || shape(value, { accepted: oneOf(true), code: oneOf("ok"), token: peerToken });
@@ -384,14 +295,15 @@ function isHealthResult(value) {
     return shape(value, { status: oneOf("ok", "degraded"), revision: nonNegative });
 }
 function isSendResult(value) {
-    if (!isRecord(value) || value.accepted !== true)
-        return isDecision(value);
+    if (!isRecord(value) || value.accepted !== true) {
+        return shape(value, { accepted: oneOf(false), code: oneOf("not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected") }, { reason: safeCode });
+    }
     return shape(value, { accepted: oneOf(true), code: oneOf("ok"),
         conversationId: (item) => typeof item === "string" && CONVERSATION_ID_PATTERN.test(item),
         deliveryToken: (item) => typeof item === "string" && DELIVERY_TOKEN_PATTERN.test(item) });
 }
 function isRefreshResult(value) {
-    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "watch_owner_conflict", "route_mismatch", "busy", "unavailable", "rejected"), revision: nonNegative }) && isDecision({ accepted: value.accepted, code: value.code });
+    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected"), revision: nonNegative }) && isDecision({ accepted: value.accepted, code: value.code });
 }
 const TERMINAL = new Set(["delivered", "unconfirmed", "expired", "failed", "ambiguous", "cancelled"]);
 function isDeliveryStatusResult(value) {
@@ -411,13 +323,9 @@ function isConnectorSnapshot(value) {
     if (!shape(value, { provider: isGatewayProvider, host, health: isConnectorHealth,
         protocol: (item) => typeof item === "string" && PROTOCOL_PATTERN.test(item),
         protocolVersion: (item) => typeof item === "string" && PROTOCOL_VERSION_PATTERN.test(item) }, { lastSeenAt: iso, observationAgeMs: nonNegative, safeErrorCode: safeCode,
-        registry: isPublicRegistryObservationSnapshot, codexDoctor: (item) => shape(item, {
-            conditions: (rows) => Array.isArray(rows) && rows.length > 0 && rows.length <= 2 &&
-                rows.every(oneOf("split_brain", "orphaned", "attached", "observation_stale", "managed_layout_missing", "unknown")),
-        }) }))
+        registry: isPublicRegistryObservationSnapshot }))
         return false;
-    return (value.codexDoctor === undefined || value.provider === "codex") &&
-        (value.registry === undefined || value.provider === "claude");
+    return value.registry === undefined || value.provider === "claude";
 }
 function isRouteSnapshot(value) {
     if (!shape(value, { alias, provider: isGatewayProvider, host, enabled: (item) => typeof item === "boolean",
@@ -428,24 +336,10 @@ function isRouteSnapshot(value) {
     return row.alias.endsWith(`@${row.host}`) &&
         (row.oldestQueuedAt === undefined ? row.queueDepth === 0 : row.queueDepth > 0);
 }
-function compareConsentEndpoints(left, right) {
-    return gatewayProviders.indexOf(left.provider) -
-        gatewayProviders.indexOf(right.provider) || left.alias.localeCompare(right.alias);
-}
-function isConsentEdgeSnapshot(value) {
-    const endpoint = (item) => shape(item, { alias, provider: isGatewayProvider });
-    if (!shape(value, { endpoints: (rows) => Array.isArray(rows) && rows.length === 2 && rows.every(endpoint),
-        host, counters: isRouteCounters }, { mutable: (item) => typeof item === "boolean" }))
-        return false;
-    const [left, right] = value.endpoints;
-    const hosts = [left.alias.slice(left.alias.lastIndexOf("@") + 1), right.alias.slice(right.alias.lastIndexOf("@") + 1)];
-    return left.alias !== right.alias && compareConsentEndpoints(left, right) < 0 &&
-        (left.provider !== right.provider || hosts[0] !== hosts[1]) && value.host === [...hosts].sort()[0];
-}
 function isAvailablePeerSnapshot(value) {
     return shape(value, { alias, provider: oneOf("claude"), host,
         state: oneOf("idle", "busy", "awaiting_approval", "offline"),
-        validated: (item) => typeof item === "boolean", selected: (item) => typeof item === "boolean" }, { lastSeenAt: iso, safeErrorCode: safeCode }) &&
+        validated: (item) => typeof item === "boolean", routed: (item) => typeof item === "boolean" }, { lastSeenAt: iso, safeErrorCode: safeCode }) &&
         value.alias.endsWith(`@${String(value.host)}`);
 }
 function isNormalizedMessageEvent(value) {
@@ -467,40 +361,17 @@ function isAccounting(value) {
 function isSafeAlert(value) {
     return shape(value, { code: safeCode, severity: oneOf("info", "warning", "error"), timestamp: iso }, { provider: isGatewayProvider, host, alias });
 }
-function isProgressWatchSnapshot(value) {
-    return shape(value, {
-        conversationIdSuffix: (item) => typeof item === "string" && CONVERSATION_SUFFIX_PATTERN.test(item),
-        ownerAlias: alias, workerAlias: alias, lastActivityAt: iso, nextActionAt: iso,
-        nudgeCount: oneOf(0, 1, 2),
-    }) && value.ownerAlias !== value.workerAlias;
-}
-function isProgressWatchEventSnapshot(value) {
-    if (!shape(value, { sequence: nonNegative, timestamp: iso,
-        conversationIdSuffix: (item) => typeof item === "string" && CONVERSATION_SUFFIX_PATTERN.test(item),
-        ownerAlias: alias, workerAlias: alias, kind: oneOf("opened", "replaced", "settled"),
-        actor: oneOf("owner", "worker", "operator", "gateway", "unknown") }, { reason: oneOf("done", "untracked", "idle_timeout", "tracking_disabled", "endpoint_retired", "pair_removed") }))
-        return false;
-    if (value.kind === "opened")
-        return value.actor === "owner" && value.reason === undefined;
-    if (value.kind === "replaced")
-        return (value.actor === "owner" || value.actor === "unknown") && value.reason === undefined;
-    return (value.reason === "done" && (value.actor === "owner" || value.actor === "worker")) ||
-        (value.reason === "untracked" && value.actor === "operator") ||
-        ((value.reason === "idle_timeout" || value.reason === "tracking_disabled") && value.actor === "gateway") ||
-        (value.reason === "endpoint_retired" && (value.actor === "gateway" || value.actor === "operator")) ||
-        (value.reason === "pair_removed" && value.actor === "operator");
-}
 function isGatewayActivityEvent(value) {
     if (!shape(value, { sequence: positive, timestamp: iso,
-        kind: oneOf("discovery", "selection", "registration", "pairing", "watch"),
-        action: oneOf("discovery_refreshed", "claude_selected", "claude_unselected", "codex_registered", "codex_succeeded", "codex_unregistered", "routes_paired", "routes_unpaired", "watch_ended"),
+        kind: oneOf("discovery", "registration"),
+        action: oneOf("discovery_refreshed", "codex_registered", "codex_succeeded", "codex_unregistered", "claude_route_installed", "claude_route_retired"),
         outcome: oneOf("accepted", "rejected"), aliases: (rows) => arrayOf(rows, 2, alias),
         operatorAction: oneOf(true) }, { safeErrorCode: safeCode }))
         return false;
     const allowed = {
-        discovery: ["discovery_refreshed"], selection: ["claude_selected", "claude_unselected"],
-        registration: ["codex_registered", "codex_succeeded", "codex_unregistered"],
-        pairing: ["routes_paired", "routes_unpaired"], watch: ["watch_ended"],
+        discovery: ["discovery_refreshed"],
+        registration: ["codex_registered", "codex_succeeded", "codex_unregistered",
+            "claude_route_installed", "claude_route_retired"],
     };
     return new Set(value.aliases).size === value.aliases.length &&
         (allowed[value.kind]?.includes(value.action) ?? false);
@@ -518,23 +389,20 @@ function isDeadlinePressure(value) {
         rows.reduce((sum, row) => sum + Number(row.expired), 0) === value.expiredEvents;
 }
 function isSnapshotTruncation(value) {
-    const required = ["connectors", "availablePeers", "routes", "consentEdges", "messages", "alerts"];
-    const optional = ["progressWatches", "progressWatchEvents", "activityEvents"];
+    const required = ["connectors", "availablePeers", "routes", "messages", "alerts"];
+    const optional = ["activityEvents"];
     return isRecord(value) && exact(value, required, optional) &&
         [...required, ...optional].every((key) => value[key] === undefined || nonNegative(value[key]));
 }
 export function isGatewaySnapshot(value) {
-    if (!shape(value, { schemaVersion: oneOf(2), generatedAt: iso, inboundMode: oneOf("paired", "open"),
+    if (!shape(value, { schemaVersion: oneOf(2), generatedAt: iso,
         health: isConnectorHealth,
         connectors: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.connectors, isConnectorSnapshot),
         availablePeers: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.availablePeers, isAvailablePeerSnapshot),
         routes: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.routes, isRouteSnapshot),
-        consentEdges: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.consentEdges, isConsentEdgeSnapshot),
         messages: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.messages, isNormalizedMessageEvent),
         accounting: isAccounting, alerts: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.alerts, isSafeAlert),
-        truncation: isSnapshotTruncation }, { progressWatches: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.progressWatches, isProgressWatchSnapshot),
-        progressWatchEvents: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.progressWatchEvents, isProgressWatchEventSnapshot),
-        activityEvents: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.activityEvents, isGatewayActivityEvent),
+        truncation: isSnapshotTruncation }, { activityEvents: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.activityEvents, isGatewayActivityEvent),
         deadlinePressure: isDeadlinePressure }))
         return false;
     const snapshot = value;
@@ -543,16 +411,13 @@ export function isGatewaySnapshot(value) {
     const connectorKeys = snapshot.connectors.map((row) => `${row.provider}@${row.host}`);
     const aliases = snapshot.routes.map((row) => row.alias);
     const peers = snapshot.availablePeers.map((row) => row.alias);
-    const edgeKeys = snapshot.consentEdges.map((row) => `${row.endpoints[0].alias}\0${row.endpoints[1].alias}`);
-    const routeByAlias = new Map(snapshot.routes.map((row) => [row.alias, row]));
     const honest = snapshot.connectors.every((row) => {
         const seen = row.lastSeenAt === undefined ? undefined : Date.parse(row.lastSeenAt);
         const age = seen === undefined ? undefined : Math.min(MAX_REVISION, Math.max(0, generated - seen));
         return (row.observationAgeMs === undefined || row.observationAgeMs === age) &&
             (row.health !== "healthy" || (age !== undefined && age <= CONNECTOR_OBSERVATION_STALE_AFTER_MS));
     });
-    return honest && unique(connectorKeys) && unique(aliases) && unique(peers) && unique(edgeKeys) &&
-        snapshot.consentEdges.every((edge) => edge.endpoints.every((endpoint) => routeByAlias.get(endpoint.alias)?.provider === endpoint.provider)) &&
+    return honest && unique(connectorKeys) && unique(aliases) && unique(peers) &&
         Buffer.byteLength(JSON.stringify(snapshot), "utf8") <= GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET;
 }
 function isSnapshotObservation(value) {
@@ -560,13 +425,11 @@ function isSnapshotObservation(value) {
 }
 const descriptors = {
     health: { handler: "health", decode: emptyParams, result: isHealthResult, mutation: false }, register_codex: { handler: "registerCodex", decode: decodeRegister, result: isDecision, mutation: true },
-    unregister_codex: { handler: "unregisterCodex", decode: decodeUnregister, result: isDecision, mutation: true }, remove_codex_registration: { handler: "removeCodexRegistration", decode: decodeRemoval, result: isDecision, mutation: true },
-    select_claude: { handler: "selectClaude", decode: decodeSelection, result: isDecision, mutation: true }, unselect_claude: { handler: "unselectClaude", decode: decodeSelection, result: isDecision, mutation: true },
-    pair: { handler: "pair", decode: decodePair, result: isDecision, mutation: true }, unpair: { handler: "unpair", decode: decodePair, result: isDecision, mutation: true },
+    unregister_codex: { handler: "unregisterCodex", decode: decodeUnregister, result: isDecision, mutation: true },
     list_snapshot: { handler: "listSnapshot", decode: emptyParams, result: isGatewaySnapshot, mutation: false }, observe_snapshot: { handler: "observeSnapshot", decode: emptyParams, result: isSnapshotObservation, mutation: false },
-    delivery_status: { handler: "deliveryStatus", decode: decodeDeliveryStatus, result: isDeliveryStatusResult, mutation: false }, untrack: { handler: "untrack", decode: decodeUntrack, result: isDecision, mutation: false },
-    send_to_claude: { handler: "sendToClaude", decode: decodeSendClaude, result: isSendResult, mutation: true }, send_to_codex: { handler: "sendToCodex", decode: decodeSendCodex, result: isSendResult, mutation: true },
-    reply: { handler: "reply", decode: decodeReply, result: isSendResult, mutation: true }, refresh_dashboard: { handler: "refreshDashboard", decode: emptyParams, result: isRefreshResult, mutation: false },
+    delivery_status: { handler: "deliveryStatus", decode: decodeDeliveryStatus, result: isDeliveryStatusResult, mutation: false },
+    send: { handler: "send", decode: decodeSend, result: isSendResult, mutation: true },
+    refresh_discovery: { handler: "refreshDiscovery", decode: emptyParams, result: isRefreshResult, mutation: false },
     peer_catalog: { handler: "peerCatalog", decode: decodePeerCatalog, result: isPeerCatalog, mutation: false },
     peer_handoff: { handler: "peerHandoff", decode: decodePeerHandoff, result: isPeerHandoffResult, mutation: true },
     register_peer: { handler: "registerPeer", decode: decodeRegisterPeer, result: isRegisterPeerResult, mutation: true },
@@ -577,12 +440,12 @@ const descriptors = {
 function parseRequestObject(value) {
     if (!isRecord(value) || !exact(value, ["protocolVersion", "method", "params"]))
         invalid();
-    if (value.protocolVersion !== 1)
+    if (value.protocolVersion !== GATEWAY_CONTROL_PROTOCOL_VERSION)
         throw new ProtocolFault("UNSUPPORTED_VERSION");
     if (typeof value.method !== "string" || !Object.hasOwn(descriptors, value.method))
         throw new ProtocolFault("UNKNOWN_METHOD");
     const method = value.method;
-    return { protocolVersion: 1, method, params: descriptors[method].decode(value.params) };
+    return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, method, params: descriptors[method].decode(value.params) };
 }
 function decodeJson(frame, invalidCode) {
     try {
@@ -593,14 +456,14 @@ function decodeJson(frame, invalidCode) {
     }
 }
 function errorResponse(code) {
-    return { protocolVersion: 1, ok: false, error: { code, message: WIRE_ERROR_MESSAGES[code] } };
+    return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, ok: false, error: { code, message: WIRE_ERROR_MESSAGES[code] } };
 }
 async function dispatch(request, handlers) {
     const descriptor = descriptors[request.method];
     const handler = handlers[descriptor.handler];
     try {
         const result = await (Object.keys(request.params).length === 0 ? handler() : handler(request.params));
-        return { protocolVersion: 1, ok: true, result };
+        return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, ok: true, result };
     }
     catch {
         return errorResponse("HANDLER_FAILURE");
@@ -617,9 +480,11 @@ function serializeResponse(response) {
 }
 class FrameFault extends Error {
     kind;
-    constructor(kind) {
+    systemCode;
+    constructor(kind, systemCode) {
         super(kind);
         this.kind = kind;
+        this.systemCode = systemCode;
     }
 }
 function readOneFrame(socket, maximum) {
@@ -652,7 +517,7 @@ function readOneFrame(socket, maximum) {
         socket.on("data", onData);
         socket.once("end", onEnd);
         socket.once("timeout", onTimeout);
-        socket.once("error", () => finish(new FrameFault("error")));
+        socket.once("error", (error) => finish(new FrameFault("error", error.code)));
     });
 }
 function respond(socket, response) {
@@ -961,16 +826,18 @@ export async function startGatewayControlServer(options) {
     };
 }
 function decodeResponse(method, params, value) {
-    if (!isRecord(value) || value.protocolVersion !== 1)
+    if (!isRecord(value) || !Number.isSafeInteger(value.protocolVersion))
         throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    if (value.protocolVersion !== GATEWAY_CONTROL_PROTOCOL_VERSION)
+        throw controlTransportError("CONTROL_VERSION_MISMATCH");
     if (value.ok === false) {
-        if (!shape(value, { protocolVersion: oneOf(1), ok: oneOf(false), error: (item) => shape(item, { code: (code) => typeof code === "string" && Object.hasOwn(WIRE_ERROR_MESSAGES, code),
+        if (!shape(value, { protocolVersion: oneOf(GATEWAY_CONTROL_PROTOCOL_VERSION), ok: oneOf(false), error: (item) => shape(item, { code: (code) => typeof code === "string" && Object.hasOwn(WIRE_ERROR_MESSAGES, code),
                 message: (message) => typeof message === "string" }) }) ||
             !isRecord(value.error) || value.error.message !== WIRE_ERROR_MESSAGES[value.error.code])
             throw controlTransportError("CONTROL_INVALID_RESPONSE");
         return value;
     }
-    if (!shape(value, { protocolVersion: oneOf(1), ok: oneOf(true), result: descriptors[method].result }))
+    if (!shape(value, { protocolVersion: oneOf(GATEWAY_CONTROL_PROTOCOL_VERSION), ok: oneOf(true), result: descriptors[method].result }))
         throw controlTransportError("CONTROL_INVALID_RESPONSE");
     if (method === "register_peer" && isRecord(value.result) && value.result.accepted === true &&
         Object.hasOwn(params, "token") === Object.hasOwn(value.result, "token"))
@@ -1015,14 +882,20 @@ export async function sendGatewayControlRequest(options) {
                     resolve(response);
                 }
             }
-            catch {
-                fail(controlTransportError("CONTROL_INVALID_RESPONSE"));
+            catch (error) {
+                fail(error instanceof GatewayControlTransportError
+                    ? error : controlTransportError("CONTROL_INVALID_RESPONSE"));
             }
         }, (error) => {
             const kind = error instanceof FrameFault ? error.kind : "error";
+            const systemCode = !writeStarted && error instanceof FrameFault ? error.systemCode : undefined;
             const code = kind === "timeout" ? "CONTROL_TIMEOUT" :
                 kind === "too_large" ? "CONTROL_RESPONSE_TOO_LARGE" :
-                    kind === "closed" ? "CONTROL_CONNECTION_CLOSED" : "CONTROL_CONNECT_FAILED";
+                    kind === "closed" ? "CONTROL_CONNECTION_CLOSED" :
+                        systemCode === "EPERM" || systemCode === "EACCES"
+                            ? "CONTROL_CONNECT_DENIED" : systemCode === "ENOENT"
+                            ? "CONTROL_SOCKET_MISSING" : systemCode === "ECONNREFUSED"
+                            ? "CONTROL_LISTENER_UNAVAILABLE" : "CONTROL_CONNECT_FAILED";
             fail(controlTransportError(code));
         });
     });