agent-embassy 1.0.0 → 1.3.0

package/dist/src/gateway/store.js

@@ -8,7 +8,7 @@ import { KeyedMutex } from "../mutex.js";
 import { isCodexRegistrationGeneration } from "./codex-registration-generation.js";
 import { compatibilityCacheKey, isCompatibilityAttestation, } from "./compatibility.js";
 import { PROGRESS_WATCH_DEFAULT_CAPACITY, PROGRESS_WATCH_MAX_IDLE_MS, PROGRESS_WATCH_MIN_IDLE_MS, createProgressWatchMachine, progressWatchCapabilities, progressWatchJournalKinds, progressWatchPhases, transitionProgressWatch, } from "./progress-watch-machine.js";
-import { compatibilityStates, connectorHealthStates, deliveryStates, gatewayProviders, messageDirections, projectGatewayPublicSnapshot, routeRegistrationModes, routeStates, } from "./types.js";
+import { CODEX_ENDPOINT_REFRESH_JOURNAL_CAPACITY, CODEX_ORPHAN_REMOVAL_JOURNAL_CAPACITY, compatibilityStates, connectorHealthStates, deliveryStates, gatewayProviders, messageDirections, projectGatewayPublicSnapshot, routeRegistrationModes, routeStates, } from "./types.js";
 const STATE_MARKER = ".agent-embassy-state";
 const STATE_MARKER_CONTENT = "agent-embassy-state-v1\n";
 const STATE_FILE = "gateway-state.json";
@@ -16,6 +16,7 @@ const CONTROLLER_LOCK = ".gateway-controller.lock";
 const MAX_MARKER_FILE_BYTES = 128;
 const MAX_LOCK_FILE_BYTES = 4 * 1024;
 export const GATEWAY_MAX_STATE_FILE_BYTES = 8 * 1024 * 1024;
+const DEFAULT_RETAINED_BODY_BYTES = 1 * 1024 * 1024;
 const COMPATIBILITY_ATTESTATION_CAPACITY = 16;
 const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
 const HOST_PATTERN = /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
@@ -153,6 +154,49 @@ function isPrivateRouteBinding(value) {
         isPrivateToken(value.routeHandle) &&
         isPrivateToken(value.ownerLease));
 }
+function isCodexEndpointRefreshJournalEvent(value) {
+    return (isObject(value) &&
+        hasOnlyKeys(value, [
+            "sequence",
+            "timestamp",
+            "alias",
+            "hostId",
+            "threadId",
+            "oldEndpointGeneration",
+            "newEndpointGeneration",
+        ], ["reason"]) &&
+        isPositiveInteger(value.sequence) &&
+        isIsoTimestamp(value.timestamp) &&
+        typeof value.alias === "string" &&
+        ALIAS_PATTERN.test(value.alias) &&
+        value.alias.startsWith("codex-") &&
+        typeof value.hostId === "string" &&
+        HOST_PATTERN.test(value.hostId) &&
+        value.alias.endsWith(`@${value.hostId}`) &&
+        isPrivateToken(value.threadId) &&
+        isPrivateToken(value.oldEndpointGeneration) &&
+        isPrivateToken(value.newEndpointGeneration) &&
+        (value.reason === undefined
+            ? value.oldEndpointGeneration !== value.newEndpointGeneration
+            : value.reason === "boot_reactivation"));
+}
+function isCodexOrphanRemovalJournalEvent(value) {
+    return (isObject(value) &&
+        hasOnlyKeys(value, [
+            "sequence",
+            "timestamp",
+            "alias",
+            "hostId",
+        ]) &&
+        isPositiveInteger(value.sequence) &&
+        isIsoTimestamp(value.timestamp) &&
+        typeof value.alias === "string" &&
+        ALIAS_PATTERN.test(value.alias) &&
+        value.alias.startsWith("codex-") &&
+        typeof value.hostId === "string" &&
+        HOST_PATTERN.test(value.hostId) &&
+        value.alias.endsWith(`@${value.hostId}`));
+}
 function isRouteCounters(value) {
     if (!isObject(value) ||
         !hasOnlyKeys(value, [
@@ -348,8 +392,7 @@ function isQueuedMetadata(value) {
             "enqueuedAt",
             "deadlineAt",
             "bytes",
-            "hopCount",
-        ], ["conversationIdSuffix", "pair", "steer"])) {
+        ], ["conversationIdSuffix", "body", "pair", "transientTarget", "steer"])) {
         return false;
     }
     return (typeof value.messageId === "string" &&
@@ -368,8 +411,13 @@ function isQueuedMetadata(value) {
         isIsoTimestamp(value.enqueuedAt) &&
         isIsoTimestamp(value.deadlineAt) &&
         isPositiveInteger(value.bytes) &&
-        isNonNegativeInteger(value.hopCount) &&
+        (value.body === undefined ||
+            (typeof value.body === "string" &&
+                value.body.length > 0 &&
+                !value.body.includes("\u0000") &&
+                Buffer.byteLength(value.body, "utf8") === value.bytes)) &&
         (value.pair === undefined || value.pair === true) &&
+        (value.transientTarget === undefined || value.transientTarget === true) &&
         (value.steer === undefined || value.steer === true));
 }
 function isInFlightMetadata(value) {
@@ -389,8 +437,7 @@ function isEvent(value) {
             "targetAlias",
             "state",
             "bytes",
-            "hopCount",
-        ], ["conversationIdSuffix", "latencyMs", "safeErrorCode", "steer"])) {
+        ], ["conversationIdSuffix", "body", "latencyMs", "safeErrorCode", "steer"])) {
         return false;
     }
     return (isPositiveInteger(value.sequence) &&
@@ -409,7 +456,11 @@ function isEvent(value) {
         typeof value.state === "string" &&
         DELIVERY_STATES.has(value.state) &&
         isPositiveInteger(value.bytes) &&
-        isNonNegativeInteger(value.hopCount) &&
+        (value.body === undefined ||
+            (typeof value.body === "string" &&
+                value.body.length > 0 &&
+                !value.body.includes("\u0000") &&
+                Buffer.byteLength(value.body, "utf8") === value.bytes)) &&
         (value.latencyMs === undefined || isNonNegativeInteger(value.latencyMs)) &&
         (value.safeErrorCode === undefined || isSafeCode(value.safeErrorCode)) &&
         (value.steer === undefined || value.steer === true));
@@ -627,6 +678,115 @@ function migratePreCompatibilityAttestations(value) {
     }
     return { ...value, compatibilityAttestations: [] };
 }
+const PRE_CODEX_ENDPOINT_REFRESH_STATE_KEYS = [
+    ...PRE_COMPATIBILITY_ATTESTATION_STATE_KEYS,
+    "compatibilityAttestations",
+];
+/** Add an empty bounded private endpoint-refresh journal to exact legacy v1. */
+function migratePreCodexEndpointRefreshJournal(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        !hasOnlyKeys(value, PRE_CODEX_ENDPOINT_REFRESH_STATE_KEYS)) {
+        return value;
+    }
+    return {
+        ...value,
+        codexEndpointRefreshSequence: 0,
+        codexEndpointRefreshEvents: [],
+    };
+}
+const PRE_CODEX_ORPHAN_REMOVAL_STATE_KEYS = [
+    ...PRE_CODEX_ENDPOINT_REFRESH_STATE_KEYS,
+    "codexEndpointRefreshSequence",
+    "codexEndpointRefreshEvents",
+];
+/** Add an empty private orphan-removal journal to exact preceding v1 state. */
+function migratePreCodexOrphanRemovalJournal(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        !hasOnlyKeys(value, PRE_CODEX_ORPHAN_REMOVAL_STATE_KEYS)) {
+        return value;
+    }
+    return {
+        ...value,
+        codexOrphanRemovalSequence: 0,
+        codexOrphanRemovalEvents: [],
+    };
+}
+/**
+ * v1.2.0 persisted hop counters on queue, in-flight, and event rows. Hop
+ * policy no longer exists; accept only the old bounded shape and discard the
+ * obsolete field before strict current-schema validation and persistence.
+ */
+function migrateLegacyHopCounts(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        !Array.isArray(value.queue) ||
+        !Array.isArray(value.inFlight) ||
+        !Array.isArray(value.events)) {
+        return value;
+    }
+    const strip = (entry) => {
+        if (!isObject(entry) || !Object.hasOwn(entry, "hopCount"))
+            return entry;
+        if (!isNonNegativeInteger(entry.hopCount) || entry.hopCount > 64) {
+            return entry;
+        }
+        const { hopCount: _legacyHopCount, ...current } = entry;
+        return current;
+    };
+    return {
+        ...value,
+        queue: value.queue.map(strip),
+        inFlight: value.inFlight.map(strip),
+        events: value.events.map(strip),
+    };
+}
+function isLegacyCompatibilityCertification(value) {
+    if (!isObject(value))
+        return false;
+    const required = ["depth", "outcome", "certifiedAt"];
+    if (!hasOnlyKeys(value, required, ["safeErrorCode"]))
+        return false;
+    if ((value.depth !== "wire" &&
+        value.depth !== "thread_ops" &&
+        value.depth !== "turn") ||
+        (value.outcome !== "pass" && value.outcome !== "fail") ||
+        !isIsoTimestamp(value.certifiedAt) ||
+        new Date(Date.parse(value.certifiedAt)).toISOString() !==
+            value.certifiedAt ||
+        (value.safeErrorCode !== undefined && !isSafeCode(value.safeErrorCode))) {
+        return false;
+    }
+    return (value.outcome === "pass") === (value.safeErrorCode === undefined);
+}
+/**
+ * v1.1-v1.2 compatibility rows could contain manual live-certification
+ * evidence. The ceremony is gone: accept only its exact old shape, discard
+ * it, and retain the automatic bounded probe evidence.
+ */
+function migrateLegacyCompatibilityCertifications(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        !Array.isArray(value.compatibilityAttestations)) {
+        return value;
+    }
+    let changed = false;
+    const compatibilityAttestations = value.compatibilityAttestations.map((entry) => {
+        if (!isObject(entry) || !Object.hasOwn(entry, "certification")) {
+            return entry;
+        }
+        if (!isLegacyCompatibilityCertification(entry.certification)) {
+            return entry;
+        }
+        const { certification: _legacyCertification, ...current } = entry;
+        if (!isCompatibilityAttestation(current))
+            return entry;
+        changed = true;
+        return current;
+    });
+    return changed ? { ...value, compatibilityAttestations } : value;
+}
 function isPersistedState(value) {
     if (!isObject(value) ||
         !hasOnlyKeys(value, [
@@ -647,6 +807,10 @@ function isPersistedState(value) {
             "progressWatches",
             "progressWatchEvents",
             "compatibilityAttestations",
+            "codexEndpointRefreshSequence",
+            "codexEndpointRefreshEvents",
+            "codexOrphanRemovalSequence",
+            "codexOrphanRemovalEvents",
             "codexSuccession",
         ]) ||
         value.schemaVersion !== 1 ||
@@ -654,6 +818,8 @@ function isPersistedState(value) {
         !isIsoTimestamp(value.updatedAt) ||
         !isNonNegativeInteger(value.eventSequence) ||
         !isNonNegativeInteger(value.watchSequence) ||
+        !isNonNegativeInteger(value.codexEndpointRefreshSequence) ||
+        !isNonNegativeInteger(value.codexOrphanRemovalSequence) ||
         !Array.isArray(value.routes) ||
         !value.routes.every(isRouteRecord) ||
         !Array.isArray(value.pairs) ||
@@ -668,6 +834,14 @@ function isPersistedState(value) {
         value.compatibilityAttestations.length >
             COMPATIBILITY_ATTESTATION_CAPACITY ||
         !value.compatibilityAttestations.every(isCompatibilityAttestation) ||
+        !Array.isArray(value.codexEndpointRefreshEvents) ||
+        value.codexEndpointRefreshEvents.length >
+            CODEX_ENDPOINT_REFRESH_JOURNAL_CAPACITY ||
+        !value.codexEndpointRefreshEvents.every(isCodexEndpointRefreshJournalEvent) ||
+        !Array.isArray(value.codexOrphanRemovalEvents) ||
+        value.codexOrphanRemovalEvents.length >
+            CODEX_ORPHAN_REMOVAL_JOURNAL_CAPACITY ||
+        !value.codexOrphanRemovalEvents.every(isCodexOrphanRemovalJournalEvent) ||
         !Array.isArray(value.connectors) ||
         !value.connectors.every(isConnectorRecord) ||
         !Array.isArray(value.queue) ||
@@ -770,6 +944,23 @@ function isPersistedState(value) {
     };
     const sequencesStrictlyIncrease = candidate.events.every((event, index) => index === 0 ||
         event.sequence > (candidate.events[index - 1]?.sequence ?? 0));
+    const endpointRefreshSequenceConsistent = candidate.codexEndpointRefreshEvents.length === 0
+        ? candidate.codexEndpointRefreshSequence === 0
+        : candidate.codexEndpointRefreshEvents.at(-1)?.sequence ===
+            candidate.codexEndpointRefreshSequence &&
+            candidate.codexEndpointRefreshEvents.every((event, index) => index === 0 ||
+                event.sequence ===
+                    (candidate.codexEndpointRefreshEvents[index - 1]?.sequence ??
+                        0) +
+                        1);
+    const orphanRemovalSequenceConsistent = candidate.codexOrphanRemovalEvents.length === 0
+        ? candidate.codexOrphanRemovalSequence === 0
+        : candidate.codexOrphanRemovalEvents.at(-1)?.sequence ===
+            candidate.codexOrphanRemovalSequence &&
+            candidate.codexOrphanRemovalEvents.every((event, index) => index === 0 ||
+                event.sequence ===
+                    (candidate.codexOrphanRemovalEvents[index - 1]?.sequence ?? 0) +
+                        1);
     return (aliases.size === candidate.routes.length &&
         new Set(pairKeys).size === pairKeys.length &&
         pairsValid &&
@@ -784,6 +975,8 @@ function isPersistedState(value) {
         candidate.accounting.queuedBytes === expectedQueuedBytes &&
         sequencesStrictlyIncrease &&
         candidate.events.every((event) => event.sequence <= candidate.eventSequence) &&
+        endpointRefreshSequenceConsistent &&
+        orphanRemovalSequenceConsistent &&
         candidate.routes.every((route) => route.alias.endsWith(`@${route.binding.hostId}`) &&
             ((route.binding.provider === "codex" &&
                 route.registrationMode === "explicit_opt_in") ||
@@ -1105,6 +1298,10 @@ export class GatewayStore {
                     progressWatches: [],
                     progressWatchEvents: [],
                     compatibilityAttestations: [],
+                    codexEndpointRefreshSequence: 0,
+                    codexEndpointRefreshEvents: [],
+                    codexOrphanRemovalSequence: 0,
+                    codexOrphanRemovalEvents: [],
                     codexSuccession: null,
                 };
                 if (this.state.pairs.length > this.config.limits.maxPairs) {
@@ -1183,7 +1380,7 @@ export class GatewayStore {
             }
         });
     }
-    async markConnectorOffline(identity, safeErrorCode = "CONNECTOR_OFFLINE", inFlightSettlements = []) {
+    async markConnectorOffline(identity, safeErrorCode = "CONNECTOR_OFFLINE", inFlightSettlements = [], options = {}) {
         return await this.mutate(async (state, now) => {
             this.assertAllowedIdentity(identity);
             if (!SAFE_CODE_PATTERN.test(safeErrorCode)) {
@@ -1211,7 +1408,7 @@ export class GatewayStore {
                 route.updatedAt = now.toISOString();
                 route.safeErrorCode = safeErrorCode;
             }
-            return this.terminateAffectedMessages(state, affectedAliases, now, safeErrorCode, settlementPlan);
+            return this.terminateAffectedMessages(state, affectedAliases, now, safeErrorCode, settlementPlan, options.preserveQueued === true);
         });
     }
     async registerRoute(input) {
@@ -1261,7 +1458,7 @@ export class GatewayStore {
                 registeredAt: now.toISOString(),
                 updatedAt: now.toISOString(),
                 lastSeenAt: now.toISOString(),
-                queueDepth: 0,
+                queueDepth: state.queue.filter((item) => item.targetAlias === input.alias).length,
                 counters: emptyCounters(),
             });
         });
@@ -1372,7 +1569,7 @@ export class GatewayStore {
                     registeredAt: now.toISOString(),
                     updatedAt: now.toISOString(),
                     lastSeenAt: now.toISOString(),
-                    queueDepth: 0,
+                    queueDepth: state.queue.filter((item) => item.targetAlias === replacement.alias).length,
                     counters: emptyCounters(),
                 });
             }
@@ -1449,7 +1646,9 @@ export class GatewayStore {
             if (!ALIAS_PATTERN.test(input.alias) ||
                 !ALIAS_PATTERN.test(newAlias) ||
                 !isPrivateRouteBinding(input.newBinding) ||
-                !newAlias.endsWith(`@${input.newBinding.hostId}`)) {
+                !newAlias.endsWith(`@${input.newBinding.hostId}`) ||
+                (input.journalReason !== undefined &&
+                    input.journalReason !== "boot_reactivation")) {
                 throw new BridgeError("INVALID_ROUTE_REBIND", "The stale-route rebind request is malformed.");
             }
             this.assertAllowedIdentity(endpointOf(input.newBinding));
@@ -1457,10 +1656,8 @@ export class GatewayStore {
             if (!route.enabled ||
                 route.state !== "stale" ||
                 route.compatibility !== "expired" ||
-                route.queueDepth !== 0 ||
-                state.queue.some((item) => item.sourceAlias === route.alias || item.targetAlias === route.alias) ||
                 state.inFlight.some((item) => item.sourceAlias === route.alias || item.targetAlias === route.alias)) {
-                throw new BridgeError("ROUTE_REBIND_NOT_SAFE", "Only an enabled, expired, empty stale route can be rebound.");
+                throw new BridgeError("ROUTE_REBIND_NOT_SAFE", "Only an enabled, expired stale route without in-flight work can be rebound.");
             }
             if (route.binding.provider !== input.newBinding.provider ||
                 route.binding.hostId !== input.newBinding.hostId) {
@@ -1476,6 +1673,10 @@ export class GatewayStore {
                     (!claudeReasonAllowed || !sameLogicalRoute))) {
                 throw new BridgeError("ROUTE_RESELECTION_REQUIRED", "A stale route may rebind only the same provider-native logical identity and ownership lease.");
             }
+            if (input.journalReason === "boot_reactivation" &&
+                route.binding.provider !== "codex") {
+                throw new BridgeError("INVALID_ROUTE_REBIND", "Only an exact retained Codex route may record boot reactivation.");
+            }
             const connector = state.connectors.find((candidate) => sameEndpoint(candidate, input.newBinding));
             if (!connector ||
                 !["healthy", "degraded"].includes(connector.health) ||
@@ -1488,7 +1689,12 @@ export class GatewayStore {
                     candidate.binding.ownerLease === input.newBinding.ownerLease))) {
                 throw new BridgeError("ROUTE_BINDING_COLLISION", "The replacement private binding already belongs to another alias.");
             }
+            if (input.journalReason === "boot_reactivation" &&
+                state.codexEndpointRefreshSequence >= Number.MAX_SAFE_INTEGER) {
+                throw new BridgeError("CODEX_ENDPOINT_REFRESH_SEQUENCE_EXHAUSTED", "The bounded Codex endpoint-refresh sequence is exhausted.");
+            }
             const previousAlias = route.alias;
+            const oldEndpointGeneration = route.binding.endpointGeneration;
             route.binding = { ...input.newBinding };
             route.alias = newAlias;
             route.state = input.state ?? "idle";
@@ -1497,9 +1703,8 @@ export class GatewayStore {
             route.lastSeenAt = now.toISOString();
             delete route.safeErrorCode;
             if (previousAlias !== newAlias) {
-                // Restart recovery has already emptied queue/in-flight state. Keep the
-                // metadata rewrite complete anyway so this mutation stays atomic if a
-                // future caller uses the same primitive after another invalidation.
+                // Retained queued mail follows only the exact re-observed logical
+                // route. In-flight work remains forbidden above.
                 for (const item of [...state.queue, ...state.inFlight]) {
                     if (item.sourceAlias === previousAlias)
                         item.sourceAlias = newAlias;
@@ -1517,6 +1722,164 @@ export class GatewayStore {
                 renameRateBucket(state, previousAlias, newAlias);
                 renamePairAlias(state, previousAlias, newAlias, now);
             }
+            if (input.journalReason === "boot_reactivation") {
+                this.appendCodexEndpointRefreshEvent(state, {
+                    timestamp: now.toISOString(),
+                    alias: route.alias,
+                    hostId: route.binding.hostId,
+                    threadId: route.binding.routeHandle,
+                    oldEndpointGeneration,
+                    newEndpointGeneration: route.binding.endpointGeneration,
+                    reason: "boot_reactivation",
+                });
+            }
+        });
+    }
+    /**
+     * Atomically re-anchor only the exact Codex tasks proved present on a newly
+     * compatible App Server generation. Omitted stale tasks stay untouched.
+     */
+    async reanchorCodexRoutes(input) {
+        return await this.mutate(async (state, now) => {
+            if (!isObject(input) ||
+                !hasOnlyKeys(input, ["oldEndpoint", "newEndpoint", "routes"]) ||
+                !isPrivateEndpointIdentity(input.oldEndpoint) ||
+                !isPrivateEndpointIdentity(input.newEndpoint) ||
+                input.oldEndpoint.provider !== "codex" ||
+                input.newEndpoint.provider !== "codex" ||
+                input.oldEndpoint.hostId !== input.newEndpoint.hostId ||
+                input.oldEndpoint.endpointGeneration ===
+                    input.newEndpoint.endpointGeneration ||
+                !Array.isArray(input.routes) ||
+                input.routes.length > this.config.limits.maxRoutes) {
+                throw new BridgeError("INVALID_CODEX_ENDPOINT_REFRESH", "Codex endpoint refresh requires two distinct exact generations on one allowlisted host and a bounded route subset.");
+            }
+            this.assertAllowedIdentity(input.oldEndpoint);
+            this.assertAllowedIdentity(input.newEndpoint);
+            const newConnector = state.connectors.find((candidate) => sameEndpoint(candidate, input.newEndpoint));
+            if (newConnector === undefined ||
+                !["healthy", "degraded"].includes(newConnector.health) ||
+                newConnector.compatibility !== "compatible") {
+                throw new BridgeError("ROUTE_ENDPOINT_NOT_OBSERVED", "The replacement Codex endpoint generation must be positively observed and compatible.");
+            }
+            const aliases = new Set();
+            const threadIds = new Set();
+            const ownerLeases = new Set();
+            const replacements = [];
+            for (const candidate of input.routes) {
+                if (!isObject(candidate) ||
+                    !hasOnlyKeys(candidate, ["alias", "threadId", "ownerLease"], ["state"]) ||
+                    typeof candidate.alias !== "string" ||
+                    !ALIAS_PATTERN.test(candidate.alias) ||
+                    !candidate.alias.startsWith("codex-") ||
+                    !candidate.alias.endsWith(`@${input.oldEndpoint.hostId}`) ||
+                    !isPrivateToken(candidate.threadId) ||
+                    !isPrivateToken(candidate.ownerLease) ||
+                    (candidate.state !== undefined &&
+                        candidate.state !== "idle" &&
+                        candidate.state !== "busy" &&
+                        candidate.state !== "awaiting_approval")) {
+                    throw new BridgeError("INVALID_CODEX_ENDPOINT_REFRESH", "A Codex endpoint refresh route proof is malformed.");
+                }
+                if (aliases.has(candidate.alias) ||
+                    threadIds.has(candidate.threadId) ||
+                    ownerLeases.has(candidate.ownerLease)) {
+                    throw new BridgeError("AMBIGUOUS_CODEX_ENDPOINT_REFRESH", "A Codex endpoint refresh cannot contain duplicate alias, task, or lease claims.");
+                }
+                aliases.add(candidate.alias);
+                threadIds.add(candidate.threadId);
+                ownerLeases.add(candidate.ownerLease);
+                const route = state.routes.find((stored) => stored.alias === candidate.alias);
+                if (route === undefined ||
+                    route.binding.provider !== "codex" ||
+                    route.registrationMode !== "explicit_opt_in" ||
+                    !route.enabled ||
+                    route.state !== "stale" ||
+                    route.compatibility !== "expired" ||
+                    !sameEndpoint(route.binding, input.oldEndpoint) ||
+                    route.binding.routeHandle !== candidate.threadId ||
+                    route.binding.ownerLease !== candidate.ownerLease ||
+                    state.inFlight.some((item) => item.sourceAlias === route.alias ||
+                        item.targetAlias === route.alias)) {
+                    throw new BridgeError("CODEX_ENDPOINT_REFRESH_NOT_SAFE", "Only an exact enabled, expired stale Codex task without in-flight work may be refreshed.");
+                }
+                const newBinding = {
+                    ...route.binding,
+                    endpointGeneration: input.newEndpoint.endpointGeneration,
+                };
+                if (state.routes.some((stored) => stored !== route &&
+                    (sameRouteTarget(stored.binding, newBinding) ||
+                        stored.binding.ownerLease === newBinding.ownerLease))) {
+                    throw new BridgeError("ROUTE_BINDING_COLLISION", "A refreshed Codex task or ownership lease is already claimed by another route.");
+                }
+                replacements.push({ route, state: candidate.state ?? "idle" });
+            }
+            if (state.codexEndpointRefreshSequence >
+                Number.MAX_SAFE_INTEGER - replacements.length) {
+                throw new BridgeError("CODEX_ENDPOINT_REFRESH_SEQUENCE_EXHAUSTED", "The bounded Codex endpoint-refresh sequence is exhausted.");
+            }
+            for (const replacement of replacements) {
+                const oldEndpointGeneration = replacement.route.binding.endpointGeneration;
+                replacement.route.binding = {
+                    ...replacement.route.binding,
+                    endpointGeneration: input.newEndpoint.endpointGeneration,
+                };
+                replacement.route.state = replacement.state;
+                replacement.route.compatibility = "compatible";
+                replacement.route.updatedAt = now.toISOString();
+                replacement.route.lastSeenAt = now.toISOString();
+                delete replacement.route.safeErrorCode;
+                this.appendCodexEndpointRefreshEvent(state, {
+                    timestamp: now.toISOString(),
+                    alias: replacement.route.alias,
+                    hostId: replacement.route.binding.hostId,
+                    threadId: replacement.route.binding.routeHandle,
+                    oldEndpointGeneration,
+                    newEndpointGeneration: input.newEndpoint.endpointGeneration,
+                });
+            }
+            return { reboundAliases: replacements.map(({ route }) => route.alias) };
+        });
+    }
+    /**
+     * Dashboard recovery primitive for one abandoned Codex registration. The
+     * alias is only authority to request evaluation; durable state must prove
+     * the task is empty, stale, expired, and on a dead or superseded generation.
+     */
+    async removeStaleCodexOrphan(input) {
+        return await this.mutate(async (state, now) => {
+            if (!isObject(input) ||
+                !hasOnlyKeys(input, ["alias"]) ||
+                typeof input.alias !== "string") {
+                throw new BridgeError("INVALID_CODEX_ORPHAN_RECOVERY", "Codex orphan recovery requires one exact Codex alias.");
+            }
+            const route = this.requireStaleCodexOrphan(state, input.alias);
+            const aliases = new Set([route.alias]);
+            const removedPairs = state.pairs
+                .filter((pair) => pair.claudeAlias === route.alias || pair.codexAlias === route.alias)
+                .map((pair) => ({
+                claudeAlias: pair.claudeAlias,
+                codexAlias: pair.codexAlias,
+            }));
+            if (state.codexOrphanRemovalSequence >= Number.MAX_SAFE_INTEGER) {
+                throw new BridgeError("CODEX_ORPHAN_REMOVAL_SEQUENCE_EXHAUSTED", "The bounded Codex orphan-removal sequence is exhausted.");
+            }
+            this.settleProgressWatchesForAliases(state, aliases, now);
+            state.routes = state.routes.filter((candidate) => candidate !== route);
+            removePairsForAliases(state, aliases);
+            state.rateBuckets = state.rateBuckets.filter((bucket) => bucket.sourceAlias !== route.alias);
+            state.dedupe = state.dedupe.filter((record) => record.sourceAlias !== route.alias &&
+                record.targetAlias !== route.alias);
+            this.appendCodexOrphanRemovalEvent(state, {
+                timestamp: now.toISOString(),
+                alias: route.alias,
+                hostId: route.binding.hostId,
+            });
+            return {
+                alias: route.alias,
+                binding: { ...route.binding },
+                removedPairs,
+            };
         });
     }
     async disableRoute(alias, ownerLease, inFlightSettlements = []) {
@@ -1651,6 +2014,64 @@ export class GatewayStore {
             };
         });
     }
+    /**
+     * Read-only preflight for service-side provider cleanup. Removal repeats the
+     * identical proof atomically so no intervening state change can authorize it.
+     */
+    async inspectStaleCodexOrphan(alias) {
+        return this.mutex.run("gateway", async () => {
+            const route = this.requireStaleCodexOrphan(this.requireState(), alias);
+            return { ...route.binding };
+        });
+    }
+    /**
+     * Capture the exact pre-mutation authority needed to reconcile a possible
+     * post-rename orphan-removal commit. This value remains controller-private.
+     */
+    async inspectStaleCodexOrphanRemovalAuthority(alias) {
+        return this.mutex.run("gateway", async () => {
+            const state = this.requireState();
+            const route = this.requireStaleCodexOrphan(state, alias);
+            return {
+                binding: { ...route.binding },
+                previousSequence: state.codexOrphanRemovalSequence,
+            };
+        });
+    }
+    /**
+     * Fail-closed reconciliation for one exact removal whose durable rename may
+     * have committed before a directory-sync error. The latest private journal
+     * row, monotonic predecessor, alias absence, and native authority absence
+     * must all corroborate the same mutation.
+     */
+    async wasStaleCodexOrphanRemovalCommitted(input) {
+        return this.mutex.run("gateway", async () => {
+            if (!isObject(input) ||
+                !hasOnlyKeys(input, ["alias", "binding", "previousSequence"]) ||
+                typeof input.alias !== "string" ||
+                !ALIAS_PATTERN.test(input.alias) ||
+                !input.alias.startsWith("codex-") ||
+                !isPrivateRouteBinding(input.binding) ||
+                input.binding.provider !== "codex" ||
+                !input.alias.endsWith(`@${input.binding.hostId}`) ||
+                !isNonNegativeInteger(input.previousSequence) ||
+                input.previousSequence >= Number.MAX_SAFE_INTEGER) {
+                throw new BridgeError("INVALID_CODEX_ORPHAN_COMMIT_PROOF", "Codex orphan-removal reconciliation requires one exact private pre-mutation authority.");
+            }
+            this.assertAllowedIdentity(endpointOf(input.binding));
+            const state = this.requireState();
+            const expectedSequence = input.previousSequence + 1;
+            const latest = state.codexOrphanRemovalEvents.at(-1);
+            const routeOrAuthorityPresent = state.routes.some((route) => route.alias === input.alias ||
+                sameRouteTarget(route.binding, input.binding) ||
+                route.binding.ownerLease === input.binding.ownerLease);
+            return (!routeOrAuthorityPresent &&
+                state.codexOrphanRemovalSequence === expectedSequence &&
+                latest?.sequence === expectedSequence &&
+                latest.alias === input.alias &&
+                latest.hostId === input.binding.hostId);
+        });
+    }
     /**
      * Controller-internal inventory used to preserve exact Codex registration
      * identities across restart. Native task handles never cross the control
@@ -2336,7 +2757,9 @@ export class GatewayStore {
                 targetAlias: input.target.alias,
                 direction: "codex_to_claude",
                 sourceRoute: source,
-                ...(input.pair === true ? { pair: true } : {}),
+                ...(input.pair === true
+                    ? { pair: true }
+                    : { transientTarget: true }),
             });
         });
     }
@@ -2363,7 +2786,7 @@ export class GatewayStore {
             const target = state.routes.find((route) => route.alias === metadata.targetAlias);
             if (target)
                 target.queueDepth = Math.max(0, target.queueDepth - 1);
-            const body = this.transientBodies.get(metadata.messageId);
+            const body = this.transientBodies.get(metadata.messageId) ?? metadata.body;
             this.transientBodies.delete(metadata.messageId);
             if (body === undefined) {
                 this.finishMetadata(state, metadata, "abandoned", now, "TRANSIENT_BODY_UNAVAILABLE");
@@ -2381,13 +2804,17 @@ export class GatewayStore {
                 targetAlias: metadata.targetAlias,
                 state: "dispatching",
                 bytes: metadata.bytes,
-                hopCount: metadata.hopCount,
+                body,
                 ...(metadata.steer === true ? { steer: true } : {}),
                 latencyMs: Math.max(0, now.getTime() - Date.parse(metadata.enqueuedAt)),
             });
             return { ...metadata, body };
         });
     }
+    /** Controller-private shutdown inventory; full IDs never cross control output. */
+    async inspectQueuedMessageIds() {
+        return this.mutex.run("gateway", async () => this.requireState().queue.map((item) => item.messageId));
+    }
     /**
      * Atomically terminalizes every message whose delivery deadline is due.
      * Returned settlements are emitted only by the mutation that removed the
@@ -2462,9 +2889,13 @@ export class GatewayStore {
             };
         });
     }
-    async requeueInFlightMessage(messageId, body) {
+    async requeueInFlightMessage(messageId, body, safeErrorCode) {
         return this.mutate(async (state, now) => {
-            if (!MESSAGE_ID_PATTERN.test(messageId) || typeof body !== "string") {
+            if (!MESSAGE_ID_PATTERN.test(messageId) ||
+                typeof body !== "string" ||
+                body.length === 0 ||
+                body.includes("\u0000") ||
+                (safeErrorCode !== undefined && !SAFE_CODE_PATTERN.test(safeErrorCode))) {
                 throw new BridgeError("INVALID_GATEWAY_MESSAGE", "Only an exact in-flight message can be returned to the queue.");
             }
             const index = state.inFlight.findIndex((item) => item.messageId === messageId);
@@ -2472,6 +2903,9 @@ export class GatewayStore {
             if (metadata === undefined || index < 0) {
                 return { status: "not_in_flight" };
             }
+            if (Buffer.byteLength(body, "utf8") !== metadata.bytes) {
+                throw new BridgeError("INVALID_GATEWAY_MESSAGE", "A requeued message body must exactly match its admitted byte count.");
+            }
             state.inFlight.splice(index, 1);
             if (Date.parse(metadata.deadlineAt) <= now.getTime()) {
                 return {
@@ -2480,6 +2914,7 @@ export class GatewayStore {
                 };
             }
             const { dispatchedAt: _dispatchedAt, ...queuedMetadata } = metadata;
+            queuedMetadata.body = body;
             state.queue.unshift(queuedMetadata);
             this.transientBodies.set(messageId, body);
             state.accounting.queuedBytes += metadata.bytes;
@@ -2497,8 +2932,9 @@ export class GatewayStore {
                 targetAlias: metadata.targetAlias,
                 state: "held",
                 bytes: metadata.bytes,
-                hopCount: metadata.hopCount,
+                body,
                 ...(metadata.steer === true ? { steer: true } : {}),
+                ...(safeErrorCode === undefined ? {} : { safeErrorCode }),
                 latencyMs: Math.max(0, now.getTime() - Date.parse(metadata.enqueuedAt)),
             });
             return { status: "requeued" };
@@ -2527,7 +2963,7 @@ export class GatewayStore {
                 targetAlias: metadata.targetAlias,
                 state: progress,
                 bytes: metadata.bytes,
-                hopCount: metadata.hopCount,
+                ...(metadata.body === undefined ? {} : { body: metadata.body }),
                 ...(metadata.steer === true ? { steer: true } : {}),
                 latencyMs: Math.max(0, now.getTime() - Date.parse(metadata.enqueuedAt)),
             });
@@ -2947,6 +3383,42 @@ export class GatewayStore {
         }
         return route;
     }
+    requireStaleCodexOrphan(state, alias) {
+        if (typeof alias !== "string" ||
+            !ALIAS_PATTERN.test(alias) ||
+            !alias.startsWith("codex-")) {
+            throw new BridgeError("INVALID_CODEX_ORPHAN_RECOVERY", "Codex orphan recovery requires one exact Codex alias.");
+        }
+        const route = state.routes.find((candidate) => candidate.alias === alias);
+        if (route === undefined) {
+            throw new BridgeError("CODEX_ORPHAN_NOT_FOUND", "No Codex registration matches the requested alias.");
+        }
+        if (route.binding.provider !== "codex" ||
+            route.registrationMode !== "explicit_opt_in" ||
+            !route.enabled ||
+            route.state !== "stale" ||
+            route.compatibility !== "expired" ||
+            route.queueDepth !== 0 ||
+            state.queue.some((item) => item.sourceAlias === route.alias || item.targetAlias === route.alias) ||
+            state.inFlight.some((item) => item.sourceAlias === route.alias || item.targetAlias === route.alias)) {
+            throw new BridgeError("CODEX_ORPHAN_RECOVERY_NOT_SAFE", "Only an enabled, expired, empty stale Codex registration can be removed as an orphan.");
+        }
+        const connector = state.connectors.find((candidate) => candidate.provider === "codex" &&
+            candidate.hostId === route.binding.hostId);
+        const generationProvedDead = connector !== undefined &&
+            (connector.endpointGeneration !== route.binding.endpointGeneration ||
+                connector.health === "offline");
+        if (!generationProvedDead) {
+            throw new BridgeError("CODEX_ORPHAN_GENERATION_LIVE", "The Codex registration cannot be removed while its endpoint generation may still be live.");
+        }
+        const succession = this.journal(state);
+        if (succession !== null &&
+            (routeMatchesSuccessionIdentity(route, succession.old) ||
+                routeMatchesSuccessionIdentity(route, succession.new))) {
+            throw new BridgeError("CODEX_ORPHAN_RECOVERY_BLOCKED", "A Codex registration owned by an active succession cannot be removed as an orphan.");
+        }
+        return route;
+    }
     requireAvailableRoute(state, alias) {
         if (!ALIAS_PATTERN.test(alias)) {
             throw new BridgeError("INVALID_GATEWAY_ALIAS", "The selected alias does not use the required lowercase ASCII grammar.");
@@ -3038,12 +3510,6 @@ export class GatewayStore {
             this.recordRejection(state, sides, bytes, now, "MESSAGE_TOO_LARGE", input.steer, input.conversationIdSuffix);
             throw new BridgeError("MESSAGE_TOO_LARGE", "The transient message exceeds the configured byte limit.");
         }
-        const hopCount = input.hopCount ?? 0;
-        if (!isNonNegativeInteger(hopCount) ||
-            hopCount > this.config.limits.maxHopCount) {
-            this.recordRejection(state, sides, bytes, now, "HOP_LIMIT_EXCEEDED", input.steer, input.conversationIdSuffix);
-            throw new BridgeError("HOP_LIMIT_EXCEEDED", "The message exceeds the configured gateway hop limit.");
-        }
         if (typeof input.dedupeKey !== "string" ||
             input.dedupeKey.length === 0 ||
             Buffer.byteLength(input.dedupeKey) > 512) {
@@ -3071,7 +3537,6 @@ export class GatewayStore {
                     ? {}
                     : { conversationIdSuffix: duplicate.conversationIdSuffix }),
                 bytes,
-                hopCount,
                 ...(input.steer === true ? { steer: true } : {}),
             });
             return {
@@ -3160,8 +3625,11 @@ export class GatewayStore {
             enqueuedAt: now.toISOString(),
             deadlineAt: deadline.toISOString(),
             bytes,
-            hopCount,
+            body: input.body,
             ...(sides.pair === true ? { pair: true } : {}),
+            ...(sides.transientTarget === true
+                ? { transientTarget: true }
+                : {}),
             ...(input.steer === true ? { steer: true } : {}),
         };
         state.queue.push(metadata);
@@ -3208,7 +3676,7 @@ export class GatewayStore {
             targetAlias: sides.targetAlias,
             state: "queued",
             bytes,
-            hopCount,
+            body: input.body,
             ...(input.steer === true ? { steer: true } : {}),
         });
         return {
@@ -3274,17 +3742,78 @@ export class GatewayStore {
             targetAlias: sides.targetAlias,
             state: "rejected",
             bytes: Math.max(1, bytes),
-            hopCount: 0,
             safeErrorCode,
             ...(steer === true ? { steer: true } : {}),
         });
     }
     appendEvent(state, event) {
+        if (event.body !== undefined) {
+            for (const retained of state.events) {
+                if (retained.body !== undefined &&
+                    retained.messageIdSuffix === event.messageIdSuffix &&
+                    retained.direction === event.direction &&
+                    retained.sourceAlias === event.sourceAlias &&
+                    retained.targetAlias === event.targetAlias &&
+                    retained.conversationIdSuffix === event.conversationIdSuffix) {
+                    delete retained.body;
+                }
+            }
+        }
         state.eventSequence += 1;
         state.events.push({ sequence: state.eventSequence, ...event });
         while (state.events.length > this.config.limits.eventCapacity) {
             state.events.shift();
         }
+        this.pruneRetainedEventBodies(state);
+    }
+    pruneRetainedEventBodies(state) {
+        const configured = this.config.limits.maxRetainedBodyBytes ??
+            DEFAULT_RETAINED_BODY_BYTES;
+        if (!Number.isSafeInteger(configured) ||
+            configured < 1 ||
+            configured > GATEWAY_MAX_STATE_FILE_BYTES) {
+            throw new BridgeError("INVALID_GATEWAY_CONFIGURATION", "The retained message-body byte limit is invalid.");
+        }
+        let retainedBytes = state.events.reduce((total, event) => total +
+            (event.body === undefined
+                ? 0
+                : Buffer.byteLength(event.body, "utf8")), 0);
+        for (const event of state.events) {
+            if (retainedBytes <= configured)
+                break;
+            if (event.body === undefined)
+                continue;
+            retainedBytes -= Buffer.byteLength(event.body, "utf8");
+            delete event.body;
+        }
+    }
+    appendCodexEndpointRefreshEvent(state, event) {
+        if (state.codexEndpointRefreshSequence >= Number.MAX_SAFE_INTEGER) {
+            throw new BridgeError("CODEX_ENDPOINT_REFRESH_SEQUENCE_EXHAUSTED", "The bounded Codex endpoint-refresh sequence is exhausted.");
+        }
+        state.codexEndpointRefreshSequence += 1;
+        state.codexEndpointRefreshEvents.push({
+            sequence: state.codexEndpointRefreshSequence,
+            ...event,
+        });
+        while (state.codexEndpointRefreshEvents.length >
+            CODEX_ENDPOINT_REFRESH_JOURNAL_CAPACITY) {
+            state.codexEndpointRefreshEvents.shift();
+        }
+    }
+    appendCodexOrphanRemovalEvent(state, event) {
+        if (state.codexOrphanRemovalSequence >= Number.MAX_SAFE_INTEGER) {
+            throw new BridgeError("CODEX_ORPHAN_REMOVAL_SEQUENCE_EXHAUSTED", "The bounded Codex orphan-removal sequence is exhausted.");
+        }
+        state.codexOrphanRemovalSequence += 1;
+        state.codexOrphanRemovalEvents.push({
+            sequence: state.codexOrphanRemovalSequence,
+            ...event,
+        });
+        while (state.codexOrphanRemovalEvents.length >
+            CODEX_ORPHAN_REMOVAL_JOURNAL_CAPACITY) {
+            state.codexOrphanRemovalEvents.shift();
+        }
     }
     /** Commit watch activity only after every message-admission check succeeds. */
     applyProgressWatchMessageActivity(state, now, activity, sides) {
@@ -3493,7 +4022,7 @@ export class GatewayStore {
             targetAlias: metadata.targetAlias,
             state: deliveryState,
             bytes: metadata.bytes,
-            hopCount: metadata.hopCount,
+            ...(metadata.body === undefined ? {} : { body: metadata.body }),
             ...(metadata.steer === true ? { steer: true } : {}),
             latencyMs: Math.max(0, now.getTime() - Date.parse(metadata.enqueuedAt)),
             ...(safeErrorCode ? { safeErrorCode } : {}),
@@ -3564,10 +4093,14 @@ export class GatewayStore {
         }
         return byMessageId;
     }
-    terminateAffectedMessages(state, aliases, now, safeErrorCode, inFlightSettlements) {
+    terminateAffectedMessages(state, aliases, now, safeErrorCode, inFlightSettlements, preserveQueued = false) {
         const settlements = [];
-        const queued = state.queue.filter((item) => routeTerminationMatches(state, aliases, item));
-        state.queue = state.queue.filter((item) => !routeTerminationMatches(state, aliases, item));
+        const queued = preserveQueued
+            ? []
+            : state.queue.filter((item) => routeTerminationMatches(state, aliases, item));
+        if (!preserveQueued) {
+            state.queue = state.queue.filter((item) => !routeTerminationMatches(state, aliases, item));
+        }
         for (const item of queued) {
             this.transientBodies.delete(item.messageId);
             state.accounting.queuedBytes -= item.bytes;
@@ -3626,6 +4159,7 @@ export class GatewayStore {
             .slice(-this.config.limits.dedupeCapacity);
         state.rateBuckets = state.rateBuckets.filter((bucket) => now.getTime() - Date.parse(bucket.windowStartedAt) <
             this.config.limits.rateWindowMs);
+        this.pruneRetainedEventBodies(state);
     }
     recoverAfterRestart(now) {
         const state = this.requireState();
@@ -3671,17 +4205,39 @@ export class GatewayStore {
             route.safeErrorCode = "REOBSERVATION_REQUIRED";
             route.queueDepth = 0;
         }
+        const retainedQueue = [];
+        let retainedQueuedBytes = 0;
+        this.transientBodies.clear();
         for (const item of state.queue) {
-            state.accounting.queuedBytes -= item.bytes;
-            this.finishMetadata(state, item, "abandoned", now, "CONTROLLER_RESTARTED");
+            if (Date.parse(item.deadlineAt) <= now.getTime()) {
+                this.finishMetadata(state, item, "expired", now, "MESSAGE_EXPIRED");
+                continue;
+            }
+            if (item.body === undefined) {
+                this.finishMetadata(state, item, "abandoned", now, "CONTROLLER_RESTARTED");
+                continue;
+            }
+            // A correlated native reply admitted through a transient Claude
+            // capability cannot regain its exact UUID/generation after restart,
+            // even when another session later claims the same public alias.
+            if (item.transientTarget === true ||
+                !state.routes.some((route) => route.alias === item.targetAlias)) {
+                this.finishMetadata(state, item, "abandoned", now, "CONTROLLER_RESTARTED");
+                continue;
+            }
+            retainedQueue.push(item);
+            retainedQueuedBytes += item.bytes;
+            this.transientBodies.set(item.messageId, item.body);
+            const target = state.routes.find((route) => route.alias === item.targetAlias);
+            if (target !== undefined)
+                target.queueDepth += 1;
         }
         for (const item of state.inFlight) {
             this.finishMetadata(state, item, "ambiguous", now, "CONTROLLER_RESTARTED");
         }
-        state.queue = [];
+        state.queue = retainedQueue;
         state.inFlight = [];
-        state.accounting.queuedBytes = 0;
-        this.transientBodies.clear();
+        state.accounting.queuedBytes = retainedQueuedBytes;
     }
     recoverCodexSuccessionAfterRestart(state, now) {
         const journal = this.journal(state);
@@ -3942,6 +4498,10 @@ export class GatewayStore {
         parsed = migratePrePairGraph(parsed);
         parsed = migratePreProgressWatches(parsed);
         parsed = migratePreCompatibilityAttestations(parsed);
+        parsed = migratePreCodexEndpointRefreshJournal(parsed);
+        parsed = migratePreCodexOrphanRemovalJournal(parsed);
+        parsed = migrateLegacyHopCounts(parsed);
+        parsed = migrateLegacyCompatibilityCertifications(parsed);
         if (!isPersistedState(parsed)) {
             throw new BridgeError("CORRUPT_GATEWAY_STATE", "The gateway controller state failed strict schema validation.");
         }