agent-embassy 1.0.0 → 1.3.0

package/dist/src/gateway/providers.js

@@ -1,13 +1,13 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { BridgeError } from "../errors.js";
 import { CLAUDE_PEER_COMPATIBILITY, ClaudePeerAdapter, } from "./claude-peer.js";
-import { startClaudeCompatibilityScratch, } from "./claude-compatibility-scratch.js";
-import { compatibilityProbeNames, sharesCompatibilityMajor, } from "./compatibility.js";
+import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, sharesCompatibilityMajor, } from "./compatibility.js";
 import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, } from "./codex-app-server.js";
 import { LocalCodexTransportError } from "./codex-local-transport.js";
 import { ClaudeNativeHelperSupervisor, } from "./claude-helper-supervisor.js";
 import { isDashboardLocale } from "./locale.js";
+import { composeProvenanceEnvelope } from "./provenance-envelope.js";
 const LOCAL_HOST = "this-mac";
 const NATIVE_CLAUDE_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 const PUBLIC_ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
@@ -22,10 +22,42 @@ const DEFAULT_CODEX_CLEANUP_TIMEOUT_MS = 5_000;
 const DEFAULT_CODEX_CLEANUP_POLL_MS = 25;
 const DEFAULT_CODEX_RECOVERY_INITIAL_MS = 250;
 const DEFAULT_CODEX_RECOVERY_MAX_MS = 5_000;
+const MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES = 3;
 const COMPATIBILITY_PROBE_THREAD_ID = "00000000-0000-7000-8000-000000000000";
-const COMPATIBILITY_TURN_TIMEOUT_MS = 60_000;
-const CLAUDE_CERTIFICATION_TIMEOUT_MS = 10_000;
-const CLAUDE_CERTIFICATION_DISCOVERY_POLL_MS = 100;
+const CLAUDE_CLEAN_PREWRITE_RETRY_CODES = new Set([
+    "CLAUDE_PEER_TARGET_UNKNOWN",
+    "CLAUDE_PEER_TARGET_STALE",
+    "CLAUDE_PEER_TARGET_CHANGED",
+    "CLAUDE_PEER_WORKSPACE_UNATTESTED",
+]);
+function claudeCleanPrewriteResult(error) {
+    if (error instanceof BridgeError &&
+        error.code === "CLAUDE_PEER_MESSAGE_EXPIRED") {
+        return { state: "failed", safeErrorCode: "MESSAGE_EXPIRED" };
+    }
+    if (error instanceof BridgeError &&
+        CLAUDE_CLEAN_PREWRITE_RETRY_CODES.has(error.code)) {
+        return { state: "deferred", safeErrorCode: error.code };
+    }
+    const systemCode = typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+    return {
+        state: "failed",
+        safeErrorCode: error instanceof BridgeError
+            ? error.code
+            : systemCode === "ENOENT"
+                ? "CLAUDE_DISPATCH_PREWRITE_PATH_MISSING"
+                : systemCode === "EACCES" || systemCode === "EPERM"
+                    ? "CLAUDE_DISPATCH_PREWRITE_ACCESS_DENIED"
+                    : systemCode === "ETIMEDOUT"
+                        ? "CLAUDE_DISPATCH_PREWRITE_TIMEOUT"
+                        : "CLAUDE_DISPATCH_PREWRITE_FAILED",
+    };
+}
 function passedProbe(name) {
     return { name, outcome: "pass" };
 }
@@ -73,7 +105,8 @@ function invokeCallback(operation) {
     }
 }
 function validateAttestedClaudeRuntime(runtime) {
-    if (!sharesCompatibilityMajor(runtime.claudeCodeVersion, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion) ||
+    if (runtime.claudeCodeVersion !==
+        CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion ||
         [
             runtime.claudeExecutable,
             runtime.sessionsDir,
@@ -110,7 +143,6 @@ export class LocalClaudeGatewayProvider {
     now;
     selectedStateRoots = new Map();
     nativeHelpers;
-    compatibilityScratchFactory;
     discovered = new Map();
     selected = new Map();
     /** Exact live same-UID sessions observed through native inbound frames. */
@@ -143,7 +175,6 @@ export class LocalClaudeGatewayProvider {
     retiredNativeCodexListener;
     /** Fences discovery callbacks and monitor restarts across listener rotation. */
     nativeCodexSuccessionFreeze;
-    compatibilityCertificationInFlight = false;
     initialized = false;
     closed = false;
     constructor(options) {
@@ -169,9 +200,6 @@ export class LocalClaudeGatewayProvider {
                 locale,
                 deliveryNotices,
             })))(options.runtime, options.locale ?? "en", options.deliveryNotices ?? "merged");
-        this.compatibilityScratchFactory =
-            options.compatibilityScratchFactory ??
-                (() => startClaudeCompatibilityScratch(options.runtime));
         this.nativeHelpers =
             options.nativeHelpers === undefined
                 ? undefined
@@ -222,90 +250,6 @@ export class LocalClaudeGatewayProvider {
             ];
         }
     }
-    async runCompatibilityCertification(input) {
-        void input.routeHandle;
-        void input.withTurn;
-        const depth = "wire";
-        let scratch;
-        let listener;
-        if (this.compatibilityCertificationInFlight) {
-            return {
-                depth,
-                outcome: "fail",
-                certifiedAt: new Date(this.now()).toISOString(),
-                safeErrorCode: "CLAUDE_CERTIFICATION_BUSY",
-            };
-        }
-        this.compatibilityCertificationInFlight = true;
-        try {
-            this.assertReady();
-            scratch = await this.compatibilityScratchFactory();
-            const deadlineAt = this.now() + CLAUDE_CERTIFICATION_TIMEOUT_MS;
-            let targetId;
-            while (this.now() < deadlineAt) {
-                scratch.assertRunning();
-                const discovery = await this.peer.discover();
-                if (discovery.truncated) {
-                    throw new BridgeError("CLAUDE_CERTIFICATION_DISCOVERY_INCOMPLETE", "The scratch session could not be proven from a complete registry scan.", true);
-                }
-                const matches = discovery.peers.filter((peer) => peer.alias === scratch?.name && peer.targetId === scratch?.sessionId);
-                if (matches.length > 1) {
-                    throw new BridgeError("CLAUDE_CERTIFICATION_TARGET_COLLISION", "The scratch session identity was not unique.");
-                }
-                if (matches.length === 1) {
-                    targetId = matches[0]?.targetId;
-                    break;
-                }
-                await new Promise((resolve) => {
-                    const timer = setTimeout(resolve, CLAUDE_CERTIFICATION_DISCOVERY_POLL_MS);
-                    timer.unref();
-                });
-            }
-            if (targetId === undefined) {
-                throw new BridgeError("CLAUDE_CERTIFICATION_TARGET_UNAVAILABLE", "The bounded scratch session did not publish a discoverable peer record.", true);
-            }
-            await this.peer.assertTargetWorkspaceDisjoint(targetId, input.controllerStateRoot);
-            listener = await this.peer.listen({
-                onMessage: () => undefined,
-                onReceipt: () => undefined,
-            });
-            const sent = await this.peer.send(targetId, "[embassy compat-certify] ignore", {
-                listener,
-                receiptDeadlineAt: deadlineAt,
-            });
-            if (sent.transportStatus !== "transport_written" ||
-                sent.receiptStatus !== "pending") {
-                throw new BridgeError("CLAUDE_CERTIFICATION_WRITE_UNCONFIRMED", "The scratch diagnostic frame was not accepted for receipt tracking.", true);
-            }
-            // A direct `crossSessionInbound: accept` write emits no native
-            // peer_message_status frame. That status family describes the optional
-            // approval lifecycle, not universal delivery acknowledgement. For this
-            // wire-depth certification, the strongest portable evidence is the
-            // confirmed write to the exact, uniquely discovered scratch session.
-            return {
-                depth,
-                outcome: "pass",
-                certifiedAt: new Date(this.now()).toISOString(),
-            };
-        }
-        catch (error) {
-            const observedCode = error instanceof BridgeError && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code)
-                ? error.code
-                : "CLAUDE_CERTIFICATION_FAILED";
-            return {
-                depth,
-                outcome: "fail",
-                certifiedAt: new Date(this.now()).toISOString(),
-                safeErrorCode: observedCode,
-            };
-        }
-        finally {
-            await listener?.close().catch(() => undefined);
-            await scratch?.close().catch(() => undefined);
-            await this.peer.discover().catch(() => undefined);
-            this.compatibilityCertificationInFlight = false;
-        }
-    }
     async initialize(callbacks) {
         if (this.closed) {
             throw new BridgeError("CLAUDE_PROVIDER_CLOSED", "The local Claude provider is closed.");
@@ -881,22 +825,22 @@ export class LocalClaudeGatewayProvider {
             return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
         }
         if (input.authorization === "native_reply") {
-            try {
-                await this.refreshClaudeDiscovery();
-            }
-            catch {
-                return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
-            }
             const observedRoute = this.nativeInbound.get(input.binding.routeHandle);
-            const current = this.discovered.get(input.binding.routeHandle);
             if (observedRoute === undefined ||
-                observedRoute.listenerGeneration !== activeListener.generation ||
-                current?.alias !== observedRoute.alias) {
+                observedRoute.listenerGeneration !== activeListener.generation) {
                 this.nativeInbound.delete(input.binding.routeHandle);
                 return { state: "failed", safeErrorCode: "CLAUDE_NATIVE_REPLY_STALE" };
             }
         }
-        else if (this.selected.get(input.binding.routeHandle) === undefined) {
+        else {
+            const selectedAlias = this.selected.get(input.binding.routeHandle);
+            const stateRoot = this.selectedStateRoots.get(input.binding.routeHandle);
+            if (selectedAlias === undefined ||
+                stateRoot === undefined) {
+                return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
+            }
+        }
+        if (activeListener.registration?.alias !== input.sourceAlias) {
             return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
         }
         if (this.activeNativeCodexListener !== activeListener ||
@@ -912,15 +856,44 @@ export class LocalClaudeGatewayProvider {
             this.providerIdByGatewayId.has(input.messageId)) {
             return { state: "failed", safeErrorCode: "CLAUDE_RECEIPT_CAPACITY" };
         }
-        this.providerIdByGatewayId.set(input.messageId, "");
-        this.pendingTargetByGatewayId.set(input.messageId, input.binding.routeHandle);
+        let content;
+        try {
+            content = composeProvenanceEnvelope({
+                direction: "claude",
+                sourceAlias: input.sourceAlias,
+                targetAlias: input.targetAlias,
+                conversationId: input.conversationId,
+                body: input.text,
+            });
+        }
+        catch (error) {
+            if (error instanceof BridgeError &&
+                (error.code === "PROVENANCE_ENVELOPE_INVALID" ||
+                    error.code === "PROVENANCE_ENVELOPE_TOO_LARGE")) {
+                return { state: "failed", safeErrorCode: error.code };
+            }
+            throw error;
+        }
         if (input.authorization === "selected_route") {
+            const stateRoot = this.selectedStateRoots.get(input.binding.routeHandle);
+            if (stateRoot === undefined) {
+                return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
+            }
             this.selectedDispatchEpoch.set(input.binding.routeHandle, (this.selectedDispatchEpoch.get(input.binding.routeHandle) ?? 0) + 1);
-            // Once a selected-route dispatch begins, keep the route conservatively
-            // busy until a later registry refresh observes authoritative state.
+            // The exact workspace attestation is refreshed before every send. A
+            // clean prewrite failure remains retryable within the message deadline;
+            // retry timing does not depend on the model turn's observed state.
             this.selectedObservationDirty.add(input.binding.routeHandle);
             this.emitClaudeRouteObservation(input.binding.routeHandle, "busy");
+            try {
+                await this.peer.assertTargetWorkspaceDisjoint(input.binding.routeHandle, stateRoot);
+            }
+            catch (error) {
+                return claudeCleanPrewriteResult(error);
+            }
         }
+        this.providerIdByGatewayId.set(input.messageId, "");
+        this.pendingTargetByGatewayId.set(input.messageId, input.binding.routeHandle);
         let providerId;
         let trackingFailed = false;
         let terminalDuringSend = false;
@@ -962,7 +935,7 @@ export class LocalClaudeGatewayProvider {
             // listener's bounded timeout is authoritative and may settle it later.
         };
         try {
-            const result = await this.peer.send(input.binding.routeHandle, input.text, {
+            const result = await this.peer.send(input.binding.routeHandle, content, {
                 listener: activeListener.listener,
                 receiptDeadlineAt: deadline,
                 onTransportStatus,
@@ -1017,11 +990,7 @@ export class LocalClaudeGatewayProvider {
             }
             this.providerIdByGatewayId.delete(input.messageId);
             this.pendingTargetByGatewayId.delete(input.messageId);
-            if (error instanceof BridgeError &&
-                error.code === "CLAUDE_PEER_MESSAGE_EXPIRED") {
-                return { state: "failed", safeErrorCode: "MESSAGE_EXPIRED" };
-            }
-            return { state: "failed", safeErrorCode: "CLAUDE_DISPATCH_REJECTED" };
+            return claudeCleanPrewriteResult(error);
         }
     }
     async releaseRoute(routeHandle) {
@@ -1483,29 +1452,16 @@ export class LocalClaudeGatewayProvider {
             this.discovered.set(peer.targetId, row);
             rows.push(row);
         }
-        for (const [routeHandle, route] of this.nativeInbound) {
-            const current = this.discovered.get(routeHandle);
-            if (current !== undefined) {
-                // The stable session UUID owns native reply authority. A rename only
-                // updates its current public coordinate.
-                this.nativeInbound.set(routeHandle, {
-                    alias: current.alias,
-                    listenerGeneration: route.listenerGeneration,
-                });
-            }
-            else if (!discovery.truncated) {
-                this.nativeInbound.delete(routeHandle);
-            }
-        }
         for (const [routeHandle, selectedAlias] of this.selected) {
             const row = this.discovered.get(routeHandle);
             if (row === undefined) {
                 this.emitClaudeRouteObservation(routeHandle, "busy", "CLAUDE_PEER_NOT_OBSERVED", true);
             }
             else {
-                if (row.alias !== selectedAlias) {
+                if (!discovery.truncated && row.alias !== selectedAlias) {
                     // A Claude rename changes only the live name index. The native
-                    // session UUID remains the selected logical route.
+                    // session UUID remains the selected logical route. An incomplete
+                    // scan is display evidence only and cannot rename dispatch authority.
                     this.selected.set(routeHandle, row.alias);
                 }
                 if (row.state === "idle" &&
@@ -1585,13 +1541,13 @@ function validateCodexFactory(factory) {
     const schema = factory.schemaCompatibility;
     const write = factory.writeCompatibility;
     const certified = CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(factory.appServerVersion);
-    const observedCandidate = factory.compatibilityPolicy === "observed" &&
-        schema.observedSchemaCandidate === true &&
+    const schemaCandidate = schema.observedSchemaCandidate === true &&
         CODEX_APP_SERVER_WRITABLE_VERSIONS.some((version) => sharesCompatibilityMajor(version, factory.appServerVersion));
     if (factory.hostId !== LOCAL_HOST ||
         factory.protocol !== "codex-app-server" ||
         factory.protocolVersion !== factory.appServerVersion ||
-        (!certified && !observedCandidate) ||
+        (!certified &&
+            (!schemaCandidate || write !== null || factory.writableReady)) ||
         schema.appServerVersion !== factory.appServerVersion ||
         schema.endpointGeneration !== factory.endpointGeneration ||
         schema.protocol !== "app-server-v2-stable" ||
@@ -1638,10 +1594,8 @@ function codexRouteSafeCode(observation) {
     return undefined;
 }
 export class LocalCodexGatewayProvider {
-    identity;
-    protocol;
-    protocolVersion;
     factory;
+    refreshFactory;
     maxCallbacks;
     maxRoutes;
     maxReplyBytes;
@@ -1651,32 +1605,37 @@ export class LocalCodexGatewayProvider {
     recoveryMaxMs;
     now;
     routes = new Map();
+    /** Exact public alias authority retained across internal route recovery. */
+    routeAliases = new Map();
     routeCreations = new Map();
     routeReleases = new Map();
     routeRecoveryAttempts = new Map();
     routeRecoveryTimers = new Map();
     routeRecoveries = new Map();
     routesRequiringRecovery = new Set();
+    trackedRoutes = new Set();
+    retiredEndpointGeneration;
     expectsReply = new Map();
-    compatibilityCertifyingRoutes = new Set();
-    compatibilityTurns = new Map();
     callbackQueue = [];
     callbackScheduled = false;
     callbacks;
+    endpointRefresh;
+    endpointRefreshDelivery;
+    endpointActivationRetry;
+    endpointActivationRetryTimer;
+    callbackDrainFrozen = false;
     compatibilityAttested;
+    endpointUnavailable = false;
+    pendingEndpointAttestation;
+    pendingEndpointRefreshEvent;
     initialized = false;
     closing = false;
     closed = false;
     constructor(options) {
         validateCodexFactory(options.factory);
         this.factory = options.factory;
-        this.identity = {
-            provider: "codex",
-            hostId: exactLocalHost(options.factory.hostId),
-            endpointGeneration: options.factory.endpointGeneration,
-        };
-        this.protocol = options.factory.protocol;
-        this.protocolVersion = options.factory.protocolVersion;
+        this.refreshFactory = options.refreshFactory;
+        exactLocalHost(options.factory.hostId);
         this.compatibilityAttested = CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(options.factory.appServerVersion);
         this.maxCallbacks = positiveBounded(options.maxCallbackEvents, MAX_CODEX_CALLBACKS, 4_096);
         this.maxRoutes = positiveBounded(options.maxRoutes, MAX_CODEX_ROUTES, 256);
@@ -1693,30 +1652,61 @@ export class LocalCodexGatewayProvider {
         }
         this.now = options.now ?? (() => new Date());
     }
+    get identity() {
+        return {
+            provider: "codex",
+            hostId: exactLocalHost(this.factory.hostId),
+            endpointGeneration: this.factory.endpointGeneration,
+        };
+    }
+    get protocol() {
+        return this.factory.protocol;
+    }
+    get protocolVersion() {
+        return this.factory.protocolVersion;
+    }
     compatibilitySurface() {
         return { surface: "codex", version: this.factory.appServerVersion };
     }
     acceptCompatibilityAttestation(attestation) {
+        const pending = this.pendingEndpointAttestation;
         if (attestation.surface !== "codex" ||
             attestation.version !== this.factory.appServerVersion ||
-            attestation.tier === "incompatible") {
+            attestation.tier !== "certified" ||
+            !CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(attestation.version) ||
+            (this.endpointUnavailable && pending === undefined) ||
+            (pending !== undefined &&
+                (attestation.checkedAt !== pending.checkedAt ||
+                    attestation.tier !== pending.tier ||
+                    attestation.safeErrorCode !== pending.safeErrorCode ||
+                    attestation.probes.length !== pending.probes.length ||
+                    attestation.probes.some((probe, index) => probe.name !== pending.probes[index]?.name ||
+                        probe.outcome !== pending.probes[index]?.outcome ||
+                        probe.safeErrorCode !== pending.probes[index]?.safeErrorCode)))) {
             throw new BridgeError("CODEX_COMPATIBILITY_ATTESTATION_MISMATCH", "The Codex compatibility attestation does not match this endpoint.");
         }
+        this.pendingEndpointAttestation = undefined;
+        this.pendingEndpointRefreshEvent = undefined;
+        this.clearEndpointActivationRetry();
         this.compatibilityAttested = true;
+        this.endpointUnavailable = false;
     }
     async runCompatibilityProbes() {
+        return await this.runCompatibilityProbesFor(this.factory);
+    }
+    async runCompatibilityProbesFor(factory) {
         const [installation, control, initialize, threadList] = compatibilityProbeNames.codex;
         let transport;
         let connector;
         let stage = "transport";
         try {
-            transport = await this.factory.connectTransport();
+            transport = await factory.connectTransport();
             stage = "initialize";
             connector = await CodexAppServerConnector.connect({
-                compatibility: this.factory.schemaCompatibility,
+                compatibility: factory.schemaCompatibility,
                 writesEnabled: false,
                 route: {
-                    endpointGeneration: this.identity.endpointGeneration,
+                    endpointGeneration: factory.endpointGeneration,
                     threadId: COMPATIBILITY_PROBE_THREAD_ID,
                 },
                 transport,
@@ -1727,7 +1717,6 @@ export class LocalCodexGatewayProvider {
             });
             stage = "thread_list";
             await connector.observeLoadedThread(connector.guard());
-            this.compatibilityAttested = true;
             return [
                 passedProbe(installation),
                 passedProbe(control),
@@ -1736,6 +1725,8 @@ export class LocalCodexGatewayProvider {
             ];
         }
         catch (error) {
+            if (this.isEndpointGenerationChanged(error))
+                throw error;
             if (stage === "transport") {
                 const controlFailure = error instanceof LocalCodexTransportError &&
                     [
@@ -1772,107 +1763,6 @@ export class LocalCodexGatewayProvider {
             }
         }
     }
-    async runCompatibilityCertification(input) {
-        void input.controllerStateRoot;
-        const certifiedAt = this.now().toISOString();
-        const depth = input.withTurn ? "turn" : "thread_ops";
-        const routeHandle = input.routeHandle;
-        if (routeHandle === undefined || this.compatibilityCertifyingRoutes.has(routeHandle)) {
-            return {
-                depth,
-                outcome: "fail",
-                certifiedAt,
-                safeErrorCode: "CODEX_CERTIFICATION_ROUTE_REQUIRED",
-            };
-        }
-        this.assertReady();
-        const route = this.routes.get(routeHandle);
-        if (route === undefined || !this.observeRouteSuccessionBarrier(routeHandle).clean) {
-            return {
-                depth,
-                outcome: "fail",
-                certifiedAt,
-                safeErrorCode: "CODEX_CERTIFICATION_ROUTE_BUSY",
-            };
-        }
-        this.compatibilityCertifyingRoutes.add(routeHandle);
-        try {
-            const loaded = await route.connector.observeLoadedThread(route.connector.guard());
-            if (!loaded.selectedThreadLoaded) {
-                return {
-                    depth,
-                    outcome: "fail",
-                    certifiedAt: this.now().toISOString(),
-                    safeErrorCode: "CODEX_CERTIFICATION_THREAD_UNAVAILABLE",
-                };
-            }
-            await route.connector.certifyThreadOperations(route.connector.guard());
-            if (!input.withTurn) {
-                return {
-                    depth,
-                    outcome: "pass",
-                    certifiedAt: this.now().toISOString(),
-                };
-            }
-            const messageId = `compat_${randomBytes(12).toString("hex")}`;
-            const result = new Promise((resolve) => {
-                const timer = setTimeout(() => {
-                    this.compatibilityTurns.delete(messageId);
-                    resolve({
-                        messageId,
-                        outcome: "expired",
-                        replyCode: "REPLY_UNAVAILABLE",
-                        text: null,
-                    });
-                }, COMPATIBILITY_TURN_TIMEOUT_MS);
-                timer.unref();
-                this.compatibilityTurns.set(messageId, { resolve, timer });
-            });
-            try {
-                const disposition = await route.connector.submitMessage(route.connector.guard(), {
-                    deadlineAt: new Date(this.now().getTime() + COMPATIBILITY_TURN_TIMEOUT_MS).toISOString(),
-                    messageId,
-                    text: "reply OK",
-                });
-                if (disposition.disposition !== "started") {
-                    throw new BridgeError("CODEX_CERTIFICATION_TURN_NOT_STARTED", "The bounded certification turn did not start on the exact idle route.");
-                }
-                const settled = await result;
-                if (settled.outcome !== "completed" ||
-                    settled.text?.trim() !== "OK") {
-                    return {
-                        depth,
-                        outcome: "fail",
-                        certifiedAt: this.now().toISOString(),
-                        safeErrorCode: "CODEX_CERTIFICATION_TURN_FAILED",
-                    };
-                }
-                return {
-                    depth,
-                    outcome: "pass",
-                    certifiedAt: this.now().toISOString(),
-                };
-            }
-            finally {
-                const pending = this.compatibilityTurns.get(messageId);
-                if (pending !== undefined) {
-                    clearTimeout(pending.timer);
-                    this.compatibilityTurns.delete(messageId);
-                }
-            }
-        }
-        catch {
-            return {
-                depth,
-                outcome: "fail",
-                certifiedAt: this.now().toISOString(),
-                safeErrorCode: "CODEX_CERTIFICATION_FAILED",
-            };
-        }
-        finally {
-            this.compatibilityCertifyingRoutes.delete(routeHandle);
-        }
-    }
     async initialize(callbacks) {
         if (this.closed || this.initialized) {
             throw new BridgeError("CODEX_PROVIDER_INITIALIZATION_REJECTED", "The local Codex provider cannot be initialized in this state.");
@@ -1888,7 +1778,9 @@ export class LocalCodexGatewayProvider {
             : { health: "healthy", compatibility: "compatible" };
     }
     async selectRoute(input) {
-        this.assertReady();
+        if (!this.initialized || this.closing || this.closed) {
+            throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The local Codex provider is unavailable.", true);
+        }
         if (!PUBLIC_ALIAS.test(input.alias) ||
             !input.alias.endsWith(`@${this.identity.hostId}`)) {
             throw new BridgeError("CODEX_ALIAS_MISMATCH", "The Codex alias is outside the exact local provider boundary.");
@@ -1896,25 +1788,116 @@ export class LocalCodexGatewayProvider {
         if (!OPAQUE_ROUTE.test(input.routeHandle)) {
             throw new BridgeError("CODEX_ROUTE_INVALID", "The Codex task identifier is outside the exact provider boundary.");
         }
+        const retainedAlias = this.routeAliases.get(input.routeHandle);
+        if (retainedAlias !== undefined && retainedAlias !== input.alias) {
+            throw new BridgeError("CODEX_ALIAS_MISMATCH", "The Codex route is already bound to another exact public alias.");
+        }
         this.cancelRouteRecovery(input.routeHandle);
-        const route = await this.ensureRoute(input.routeHandle);
+        let refreshResult;
+        let selectorRefreshReserved = false;
+        let route;
+        const stageRefreshedRoute = async (result) => {
+            if (result === undefined ||
+                result.event.outcome !== "compatible") {
+                throw new BridgeError("CODEX_ROUTE_SETUP_REJECTED", "The exact Codex endpoint replacement was not compatibility-attested.");
+            }
+            refreshResult = result;
+            selectorRefreshReserved = this.reserveSelectorRefresh(result);
+            if (!selectorRefreshReserved) {
+                throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The Codex endpoint replacement is awaiting controller activation.", true);
+            }
+            try {
+                return await this.ensureRoute(input.routeHandle, false, true);
+            }
+            catch (selectionError) {
+                this.emitSelectorRefreshFallback(result, input.routeHandle);
+                throw selectionError;
+            }
+        };
+        if (this.endpointRefresh !== undefined) {
+            route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
+        }
+        else if (this.endpointUnavailable &&
+            this.pendingEndpointAttestation === undefined) {
+            route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
+        }
+        else {
+            this.assertReady();
+            try {
+                route = await this.ensureRoute(input.routeHandle);
+            }
+            catch (error) {
+                const refreshPending = error instanceof BridgeError &&
+                    error.code === "CODEX_ENDPOINT_REFRESH_PENDING";
+                if (!this.isEndpointGenerationChanged(error) && !refreshPending) {
+                    throw error;
+                }
+                if (this.isEndpointGenerationChanged(error)) {
+                    this.endpointUnavailable = true;
+                    route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
+                }
+                else if (this.endpointRefresh !== undefined) {
+                    route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
+                }
+                else {
+                    throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The Codex endpoint replacement is awaiting controller activation.", true);
+                }
+            }
+            if (refreshResult === undefined &&
+                (route.endpointGeneration !== this.factory.endpointGeneration ||
+                    this.endpointUnavailable ||
+                    this.endpointRefresh !== undefined)) {
+                if (this.endpointRefresh === undefined) {
+                    throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The Codex endpoint replacement is awaiting controller activation.", true);
+                }
+                route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
+            }
+        }
         const observation = route.connector.observation();
         const state = codexRouteState(observation);
         if (state === "stale") {
-            await this.releaseRoute(input.routeHandle);
+            if (refreshResult !== undefined && selectorRefreshReserved) {
+                // Publish the transition before any asynchronous connector cleanup so
+                // the controller can accept or durably reject the exact replacement
+                // generation. A route which closed after refresh staging is not valid
+                // re-anchoring evidence and must be removed from both the callback and
+                // its retained retry authority.
+                this.emitSelectorRefreshFallback(refreshResult, input.routeHandle);
+            }
+            this.routesRequiringRecovery.add(input.routeHandle);
+            await this.releaseRouteInternal(input.routeHandle);
+            if (this.trackedRoutes.has(input.routeHandle)) {
+                this.scheduleRouteRecovery(input.routeHandle);
+            }
             throw new BridgeError("CODEX_ROUTE_SETUP_REJECTED", "The exact Codex task connection closed during route selection.");
         }
-        this.queueRouteObservation(route, observation);
+        this.trackedRoutes.add(input.routeHandle);
+        this.routeAliases.set(input.routeHandle, input.alias);
+        if (refreshResult === undefined) {
+            this.queueRouteObservation(route, observation);
+        }
+        const endpointRefresh = refreshResult === undefined || !selectorRefreshReserved
+            ? undefined
+            : refreshResult.event;
+        if (endpointRefresh !== undefined) {
+            this.armEndpointActivationRetry(endpointRefresh);
+        }
         return {
             routeHandle: input.routeHandle,
             state,
+            ...(endpointRefresh === undefined ? {} : { endpointRefresh }),
         };
     }
     observeRouteSuccessionBarrier(routeHandle) {
-        this.assertReady();
+        if (!this.initialized || this.closing || this.closed) {
+            throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The local Codex provider is unavailable.", true);
+        }
         const route = this.routes.get(routeHandle);
         const observation = route?.connector.observation();
-        const routeCreationInFlight = this.routeCreations.has(routeHandle);
+        const routeCreationInFlight = this.routeCreations.has(routeHandle) ||
+            this.routeRecoveries.has(routeHandle) ||
+            (this.endpointRefresh !== undefined && this.trackedRoutes.has(routeHandle)) ||
+            this.pendingEndpointActivationClaims(routeHandle);
         const routeReleaseInFlight = this.routeReleases.has(routeHandle);
         const pendingReplyCorrelations = this.expectsReply.size;
         const pendingCallbacks = Math.max(this.callbackQueue.length, this.callbackScheduled ? 1 : 0);
@@ -1951,6 +1934,8 @@ export class LocalCodexGatewayProvider {
         if (!this.initialized ||
             this.closing ||
             this.closed ||
+            this.endpointUnavailable ||
+            this.endpointRefresh !== undefined ||
             !this.compatibilityAttested ||
             input.authorization !== "selected_route" ||
             !sameEndpoint(input.binding, this.identity)) {
@@ -1958,12 +1943,12 @@ export class LocalCodexGatewayProvider {
         }
         const route = this.routes.get(input.binding.routeHandle);
         if (route === undefined ||
-            this.routeReleases.has(input.binding.routeHandle)) {
+            this.routeAliases.get(input.binding.routeHandle) !== input.targetAlias ||
+            this.routeReleases.has(input.binding.routeHandle) ||
+            route.endpointGeneration !== input.binding.endpointGeneration ||
+            route.endpointGeneration !== this.factory.endpointGeneration) {
             return { state: "failed", safeErrorCode: "CODEX_ROUTE_UNAVAILABLE" };
         }
-        if (this.compatibilityCertifyingRoutes.has(input.binding.routeHandle)) {
-            return { state: "deferred", safeErrorCode: "CODEX_ROUTE_HELD" };
-        }
         if (!this.factory.writableReady ||
             this.factory.writeCompatibility === null) {
             return { state: "failed", safeErrorCode: "CODEX_WRITES_DISABLED" };
@@ -1978,13 +1963,31 @@ export class LocalCodexGatewayProvider {
         if (this.expectsReply.has(input.messageId)) {
             return { state: "failed", safeErrorCode: "CODEX_MESSAGE_DUPLICATE" };
         }
+        let content;
+        try {
+            content = composeProvenanceEnvelope({
+                direction: "codex",
+                sourceAlias: input.sourceAlias,
+                targetAlias: input.targetAlias,
+                conversationId: input.conversationId,
+                body: input.text,
+            });
+        }
+        catch (error) {
+            const safeErrorCode = error instanceof BridgeError &&
+                (error.code === "PROVENANCE_ENVELOPE_INVALID" ||
+                    error.code === "PROVENANCE_ENVELOPE_TOO_LARGE")
+                ? error.code
+                : "PROVENANCE_ENVELOPE_INVALID";
+            return { state: "failed", safeErrorCode };
+        }
         this.expectsReply.set(input.messageId, input.expectsReply);
         try {
             const disposition = await route.connector.submitMessage(guard, {
                 deadlineAt: input.deadlineAt,
                 messageId: input.messageId,
                 ...(input.steer === true ? { steer: true } : {}),
-                text: input.text,
+                text: content,
             });
             if (disposition.disposition === "deferred") {
                 this.expectsReply.delete(input.messageId);
@@ -2019,11 +2022,22 @@ export class LocalCodexGatewayProvider {
         }
     }
     async releaseRoute(routeHandle) {
+        if (this.pendingEndpointActivationClaims(routeHandle)) {
+            throw new BridgeError("CODEX_ENDPOINT_ACTIVATION_PENDING", "The exact Codex route still belongs to an unaccepted endpoint transition.", true);
+        }
+        this.trackedRoutes.delete(routeHandle);
         this.cancelRouteRecovery(routeHandle);
         const recovery = this.routeRecoveries.get(routeHandle);
         if (recovery !== undefined)
             await recovery;
+        const endpointRefresh = this.endpointRefresh;
+        if (endpointRefresh !== undefined)
+            await endpointRefresh;
+        if (this.pendingEndpointActivationClaims(routeHandle)) {
+            throw new BridgeError("CODEX_ENDPOINT_ACTIVATION_PENDING", "The exact Codex route acquired endpoint-transition authority during release.", true);
+        }
         await this.releaseRouteInternal(routeHandle);
+        this.routeAliases.delete(routeHandle);
     }
     async releaseRouteInternal(routeHandle) {
         const pending = this.routeReleases.get(routeHandle);
@@ -2053,6 +2067,12 @@ export class LocalCodexGatewayProvider {
             clearTimeout(timer);
         this.routeRecoveryTimers.clear();
         this.routesRequiringRecovery.clear();
+        this.clearEndpointActivationRetry();
+        this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointAttestation = undefined;
+        const refreshResult = this.endpointRefresh === undefined
+            ? []
+            : await Promise.allSettled([this.endpointRefresh]);
         const entries = [...this.routes.entries()];
         const routeResults = await Promise.allSettled(entries.map(async ([routeHandle]) => this.releaseRoute(routeHandle)));
         await Promise.allSettled([
@@ -2060,7 +2080,8 @@ export class LocalCodexGatewayProvider {
             ...this.routeCreations.values(),
         ]);
         this.drainCallbackQueue();
-        if (routeResults.some((result) => result.status === "rejected")) {
+        if (refreshResult.some((result) => result.status === "rejected") ||
+            routeResults.some((result) => result.status === "rejected")) {
             this.closing = false;
             throw new BridgeError("CODEX_PROVIDER_CLEANUP_FAILED", "An exact owned Codex turn did not confirm termination.");
         }
@@ -2074,17 +2095,10 @@ export class LocalCodexGatewayProvider {
         this.closed = true;
         this.closing = false;
         this.callbackQueue.length = 0;
-        for (const [messageId, pending] of this.compatibilityTurns) {
-            clearTimeout(pending.timer);
-            pending.resolve({
-                messageId,
-                outcome: "abandoned",
-                replyCode: "REPLY_UNAVAILABLE",
-                text: null,
-            });
-        }
-        this.compatibilityTurns.clear();
-        this.compatibilityCertifyingRoutes.clear();
+        this.pendingEndpointAttestation = undefined;
+        this.pendingEndpointRefreshEvent = undefined;
+        this.trackedRoutes.clear();
+        this.routeAliases.clear();
         this.expectsReply.clear();
         this.callbacks = undefined;
     }
@@ -2092,16 +2106,25 @@ export class LocalCodexGatewayProvider {
         if (!this.initialized ||
             this.closing ||
             this.closed ||
+            this.endpointUnavailable ||
+            this.endpointRefresh !== undefined ||
             !this.compatibilityAttested) {
             throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The local Codex provider is unavailable.", true);
         }
     }
-    async ensureRoute(threadId) {
-        this.assertReady();
+    async ensureRoute(threadId, queueInitialObservation = true, allowPendingEndpointAttestation = false) {
+        if (allowPendingEndpointAttestation) {
+            if (!this.initialized || this.closing || this.closed) {
+                throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The local Codex provider is unavailable.", true);
+            }
+        }
+        else {
+            this.assertReady();
+        }
         const pendingRelease = this.routeReleases.get(threadId);
         if (pendingRelease !== undefined) {
             await pendingRelease;
-            return await this.ensureRoute(threadId);
+            return await this.ensureRoute(threadId, queueInitialObservation, allowPendingEndpointAttestation);
         }
         const existing = this.routes.get(threadId);
         if (existing !== undefined) {
@@ -2113,7 +2136,7 @@ export class LocalCodexGatewayProvider {
             // a fresh one. The identity-checked release lets automatic recovery and
             // an explicit selector join the same cleanup safely.
             await this.releaseRouteInternal(threadId);
-            return await this.ensureRoute(threadId);
+            return await this.ensureRoute(threadId, queueInitialObservation, allowPendingEndpointAttestation);
         }
         const pending = this.routeCreations.get(threadId);
         if (pending !== undefined)
@@ -2121,42 +2144,51 @@ export class LocalCodexGatewayProvider {
         if (this.routes.size + this.routeCreations.size >= this.maxRoutes) {
             throw new BridgeError("CODEX_ROUTE_CAPACITY", "The bounded local Codex route table is full.", true);
         }
-        const creation = this.createRoute(threadId);
-        this.routeCreations.set(threadId, creation);
-        try {
-            const route = await creation;
+        const admittedFactory = this.factory;
+        const creation = (async () => {
+            const route = await this.createRoute(threadId, admittedFactory, queueInitialObservation);
             if (this.closing || this.closed) {
                 await this.closeRoute(route);
                 throw new BridgeError("CODEX_PROVIDER_UNAVAILABLE", "The local Codex provider closed during route creation.");
             }
+            if (!allowPendingEndpointAttestation &&
+                (this.endpointUnavailable ||
+                    this.endpointRefresh !== undefined ||
+                    admittedFactory !== this.factory ||
+                    route.endpointGeneration !== this.factory.endpointGeneration)) {
+                await this.closeRoute(route);
+                throw new BridgeError("CODEX_ENDPOINT_REFRESH_PENDING", "The Codex endpoint moved during exact route creation.", true);
+            }
             this.routes.set(threadId, route);
             return route;
+        })();
+        this.routeCreations.set(threadId, creation);
+        try {
+            return await creation;
         }
         finally {
             this.routeCreations.delete(threadId);
         }
     }
-    async createRoute(threadId) {
+    async createRoute(threadId, factory, queueInitialObservation) {
         let transport;
         let connector;
         const generation = Symbol(threadId);
         try {
-            transport = await this.factory.connectTransport();
-            const writesEnabled = this.factory.writableReady &&
-                this.factory.writeCompatibility !== null;
+            transport = await factory.connectTransport();
+            const writesEnabled = factory.writableReady && factory.writeCompatibility !== null;
             connector = await CodexAppServerConnector.connect({
-                compatibility: this.factory.writeCompatibility ??
-                    this.factory.schemaCompatibility,
+                compatibility: factory.writeCompatibility ?? factory.schemaCompatibility,
                 writesEnabled,
                 route: {
-                    endpointGeneration: this.identity.endpointGeneration,
+                    endpointGeneration: factory.endpointGeneration,
                     threadId,
                 },
                 transport,
                 maxReplyBytes: this.maxReplyBytes,
                 now: this.now,
                 onEvent: (event) => this.onConnectorEvent(threadId, generation, event),
-                onTurnResult: (result) => this.onTurnResult(result),
+                onTurnResult: (result) => this.onTurnResult(factory.endpointGeneration, result),
             });
             const loaded = await connector.observeLoadedThread(connector.guard());
             if (!loaded.selectedThreadLoaded) {
@@ -2165,11 +2197,14 @@ export class LocalCodexGatewayProvider {
             await connector.resumeThread(connector.guard());
             const route = {
                 connector,
+                endpointGeneration: factory.endpointGeneration,
                 generation,
                 threadId,
                 transport,
             };
-            this.queueRouteObservation(route, connector.observation());
+            if (queueInitialObservation) {
+                this.queueRouteObservation(route, connector.observation());
+            }
             return route;
         }
         catch (error) {
@@ -2179,6 +2214,8 @@ export class LocalCodexGatewayProvider {
             else if (transport !== undefined) {
                 await transport.close().catch(() => undefined);
             }
+            if (this.isEndpointGenerationChanged(error))
+                throw error;
             if (error instanceof BridgeError)
                 throw error;
             if (error instanceof CodexConnectorError) {
@@ -2236,6 +2273,19 @@ export class LocalCodexGatewayProvider {
             return;
         }
         try {
+            if (this.endpointUnavailable) {
+                if (this.pendingEndpointAttestation !== undefined) {
+                    throw new BridgeError("CODEX_ENDPOINT_REFRESH_PENDING", "The replacement Codex endpoint is awaiting controller activation.", true);
+                }
+                const refreshed = await this.refreshEndpoint("callback");
+                if (refreshed?.event.outcome === "compatible" &&
+                    refreshed.event.routes.some((route) => route.routeHandle === threadId)) {
+                    this.routesRequiringRecovery.delete(threadId);
+                    this.routeRecoveryAttempts.delete(threadId);
+                    return;
+                }
+                throw new BridgeError("CODEX_ENDPOINT_REFRESH_PENDING", "The replacement Codex endpoint is not ready.", true);
+            }
             const current = this.routes.get(threadId);
             if (current !== undefined &&
                 codexRouteState(current.connector.observation()) === "stale") {
@@ -2255,7 +2305,17 @@ export class LocalCodexGatewayProvider {
             this.routeRecoveryAttempts.delete(threadId);
             this.queueRouteObservation(replacement, replacement.connector.observation());
         }
-        catch {
+        catch (error) {
+            if (this.isEndpointGenerationChanged(error)) {
+                this.endpointUnavailable = true;
+                const refreshed = await this.refreshEndpoint("callback").catch(() => undefined);
+                if (refreshed?.event.outcome === "compatible" &&
+                    refreshed.event.routes.some((route) => route.routeHandle === threadId)) {
+                    this.routesRequiringRecovery.delete(threadId);
+                    this.routeRecoveryAttempts.delete(threadId);
+                    return;
+                }
+            }
             this.routeRecoveryAttempts.set(threadId, (this.routeRecoveryAttempts.get(threadId) ?? 0) + 1);
         }
     }
@@ -2267,14 +2327,321 @@ export class LocalCodexGatewayProvider {
             clearTimeout(timer);
         this.routeRecoveryTimers.delete(threadId);
     }
-    onTurnResult(result) {
-        const certification = this.compatibilityTurns.get(result.messageId);
-        if (certification !== undefined) {
-            clearTimeout(certification.timer);
-            this.compatibilityTurns.delete(result.messageId);
-            certification.resolve(result);
+    isEndpointGenerationChanged(error) {
+        return (error instanceof LocalCodexTransportError &&
+            error.code === "ENDPOINT_GENERATION_CHANGED");
+    }
+    pendingEndpointActivationClaims(routeHandle) {
+        const event = this.pendingEndpointRefreshEvent;
+        return (event !== undefined &&
+            event.current.endpointGeneration === this.factory.endpointGeneration &&
+            event.routes.some((route) => route.routeHandle === routeHandle));
+    }
+    async refreshEndpoint(delivery) {
+        if (this.refreshFactory === undefined || this.closing || this.closed) {
+            return undefined;
+        }
+        const existing = this.endpointRefresh;
+        if (existing !== undefined) {
+            // A selector already running inside the controller lock takes ownership
+            // of the transition result. This avoids waiting on a callback that needs
+            // that same lock while still ensuring exactly one activation path.
+            if (delivery === "selector")
+                this.endpointRefreshDelivery = "selector";
+            return await existing;
+        }
+        this.endpointRefreshDelivery = delivery;
+        const refresh = this.performEndpointRefresh();
+        this.endpointRefresh = refresh;
+        try {
+            return await refresh;
+        }
+        finally {
+            if (this.endpointRefresh === refresh) {
+                this.endpointRefresh = undefined;
+                this.endpointRefreshDelivery = undefined;
+            }
+        }
+    }
+    async performEndpointRefresh() {
+        const refreshFactory = this.refreshFactory;
+        if (refreshFactory === undefined)
+            return undefined;
+        const previousFactory = this.factory;
+        const previous = this.identity;
+        let candidate;
+        try {
+            const resolved = await this.resolveEndpointRefreshCandidate(refreshFactory, previousFactory, previous);
+            candidate = resolved.factory;
+            const { attestation, identity: candidateIdentity } = resolved;
+            await this.retireEndpointGeneration(previousFactory, previous.endpointGeneration);
+            if (attestation.tier === "incompatible") {
+                await candidate.close();
+                candidate = undefined;
+                this.compatibilityAttested = false;
+                this.pendingEndpointAttestation = undefined;
+                this.pendingEndpointRefreshEvent = undefined;
+                for (const routeHandle of this.trackedRoutes) {
+                    this.routesRequiringRecovery.add(routeHandle);
+                }
+                if (this.closing || this.closed)
+                    return undefined;
+                const result = {
+                    event: {
+                        outcome: "incompatible",
+                        previous,
+                        candidate: candidateIdentity,
+                        attestation,
+                    },
+                    delivery: "callback",
+                    selectorClaimed: true,
+                };
+                this.emitEndpointRefresh(result.event);
+                for (const routeHandle of this.routesRequiringRecovery) {
+                    if (this.trackedRoutes.has(routeHandle)) {
+                        this.scheduleRouteRecovery(routeHandle);
+                    }
+                }
+                return result;
+            }
+            if (this.closing || this.closed) {
+                await candidate.close();
+                candidate = undefined;
+                return undefined;
+            }
+            this.factory = candidate;
+            candidate = undefined;
+            this.retiredEndpointGeneration = undefined;
+            this.compatibilityAttested = false;
+            this.endpointUnavailable = true;
+            this.pendingEndpointAttestation = attestation;
+            const refreshedRoutes = [];
+            for (const routeHandle of [...this.trackedRoutes]) {
+                if (this.closing || this.closed)
+                    break;
+                try {
+                    const route = await this.createRoute(routeHandle, this.factory, false);
+                    if (this.closing || this.closed) {
+                        await this.closeRoute(route);
+                        break;
+                    }
+                    const state = codexRouteState(route.connector.observation());
+                    if (state === "stale") {
+                        await this.closeRoute(route);
+                        throw new BridgeError("CODEX_ROUTE_SETUP_REJECTED", "The exact Codex task was stale on the replacement endpoint.");
+                    }
+                    this.routes.set(routeHandle, route);
+                    this.routesRequiringRecovery.delete(routeHandle);
+                    this.routeRecoveryAttempts.delete(routeHandle);
+                    refreshedRoutes.push({ routeHandle, state });
+                }
+                catch {
+                    this.routesRequiringRecovery.add(routeHandle);
+                }
+            }
+            if (this.closing || this.closed)
+                return undefined;
+            const result = {
+                event: {
+                    outcome: "compatible",
+                    previous,
+                    current: this.identity,
+                    attestation,
+                    routes: refreshedRoutes,
+                },
+                delivery: this.endpointRefreshDelivery ?? "callback",
+                selectorClaimed: false,
+            };
+            if (result.event.outcome === "compatible") {
+                this.pendingEndpointRefreshEvent = result.event;
+            }
+            if (result.delivery === "callback") {
+                result.selectorClaimed = true;
+                this.publishEndpointRefresh(result.event);
+            }
+            for (const routeHandle of this.routesRequiringRecovery) {
+                if (this.trackedRoutes.has(routeHandle)) {
+                    this.scheduleRouteRecovery(routeHandle);
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            if (candidate !== undefined && candidate !== previousFactory) {
+                await candidate.close().catch(() => undefined);
+            }
+            throw error;
+        }
+        finally {
+            if (this.callbackDrainFrozen) {
+                this.callbackDrainFrozen = false;
+                this.drainCallbackQueue();
+            }
+        }
+    }
+    async resolveEndpointRefreshCandidate(refreshFactory, previousFactory, previous) {
+        for (let attempt = 0; attempt < MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES; attempt += 1) {
+            let candidate;
+            try {
+                candidate = await refreshFactory();
+                validateCodexFactory(candidate);
+                if (candidate.hostId !== previous.hostId ||
+                    candidate.protocol !== previousFactory.protocol) {
+                    throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The replacement Codex factory moved outside its pinned boundary.");
+                }
+                if (candidate === previousFactory ||
+                    candidate.endpointGeneration === previous.endpointGeneration) {
+                    if (candidate !== previousFactory)
+                        await candidate.close();
+                    candidate = undefined;
+                    if (attempt + 1 < MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES) {
+                        continue;
+                    }
+                    throw new BridgeError("CODEX_ENDPOINT_GENERATION_CHURN", "The Codex endpoint did not stabilize within its bounded refresh window.", true);
+                }
+                // Endpoint generations never inherit cached compatibility. Every
+                // candidate independently proves all four read-only wire probes.
+                const probes = await this.runCompatibilityProbesFor(candidate);
+                const attestation = evaluateCompatibilityAttestation({
+                    surface: "codex",
+                    version: candidate.appServerVersion,
+                    checkedAt: this.now().toISOString(),
+                    certifiedVersions: certifiedCompatibilityVersions.codex,
+                    probes,
+                });
+                return {
+                    factory: candidate,
+                    identity: {
+                        provider: "codex",
+                        hostId: previous.hostId,
+                        endpointGeneration: candidate.endpointGeneration,
+                    },
+                    attestation,
+                };
+            }
+            catch (error) {
+                if (candidate !== undefined && candidate !== previousFactory) {
+                    await candidate.close();
+                }
+                if (this.isEndpointGenerationChanged(error)) {
+                    if (attempt + 1 < MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES) {
+                        continue;
+                    }
+                    throw new BridgeError("CODEX_ENDPOINT_GENERATION_CHURN", "The Codex endpoint did not stabilize within its bounded refresh window.", true);
+                }
+                throw error;
+            }
+        }
+        throw new BridgeError("CODEX_ENDPOINT_GENERATION_CHURN", "The Codex endpoint did not stabilize within its bounded refresh window.", true);
+    }
+    async retireEndpointGeneration(factory, endpointGeneration) {
+        this.callbackDrainFrozen = true;
+        this.drainCallbackQueue(true);
+        // Fence every operation admitted on the previous immutable factory.
+        // Ordinary route creation is blocked by endpointRefresh; joining these
+        // exact promises ensures none can be inserted after the close sweep.
+        await Promise.allSettled([...this.routeCreations.values()]);
+        await Promise.allSettled([...this.routeReleases.values()]);
+        this.drainCallbackQueue(true);
+        for (const [routeHandle, route] of [...this.routes]) {
+            if (route.endpointGeneration !== endpointGeneration)
+                continue;
+            await this.closeRoute(route);
+            if (this.routes.get(routeHandle) === route) {
+                this.routes.delete(routeHandle);
+            }
+        }
+        this.drainCallbackQueue(true);
+        await factory.close();
+        this.drainCallbackQueue(true);
+        this.retiredEndpointGeneration = endpointGeneration;
+    }
+    reserveSelectorRefresh(result) {
+        if (result.delivery !== "selector" || result.selectorClaimed) {
+            return false;
+        }
+        result.selectorClaimed = true;
+        return true;
+    }
+    emitSelectorRefreshFallback(result, staleRouteHandle) {
+        if (result.delivery !== "selector" || !result.selectorClaimed)
             return;
+        let event = result.event;
+        if (staleRouteHandle !== undefined &&
+            event.outcome === "compatible" &&
+            event.routes.some((route) => route.routeHandle === staleRouteHandle)) {
+            event = {
+                ...event,
+                routes: event.routes.filter((route) => route.routeHandle !== staleRouteHandle),
+            };
+            result.event = event;
+            this.pendingEndpointRefreshEvent = event;
         }
+        this.publishEndpointRefresh(event);
+    }
+    publishEndpointRefresh(event) {
+        this.emitEndpointRefresh(event);
+        if (event.outcome === "compatible") {
+            this.armEndpointActivationRetry(event);
+        }
+    }
+    armEndpointActivationRetry(event) {
+        this.clearEndpointActivationRetry();
+        this.endpointActivationRetry = { event, attempt: 0 };
+        this.scheduleEndpointActivationRetry();
+    }
+    scheduleEndpointActivationRetry() {
+        const pending = this.endpointActivationRetry;
+        if (pending === undefined ||
+            this.closing ||
+            this.closed ||
+            pending.attempt >= 3 ||
+            (pending.event.outcome === "compatible" &&
+                this.pendingEndpointAttestation === undefined)) {
+            this.clearEndpointActivationRetry();
+            return;
+        }
+        const delay = Math.max(DEFAULT_CODEX_RECOVERY_INITIAL_MS, Math.min(this.recoveryMaxMs, this.recoveryInitialMs * 2 ** pending.attempt));
+        const timer = setTimeout(() => {
+            if (this.endpointActivationRetryTimer !== timer)
+                return;
+            this.endpointActivationRetryTimer = undefined;
+            const current = this.endpointActivationRetry;
+            if (current === undefined || current.event !== pending.event)
+                return;
+            if (current.event.outcome === "compatible" &&
+                this.pendingEndpointAttestation === undefined) {
+                this.clearEndpointActivationRetry();
+                return;
+            }
+            this.emitEndpointRefresh(current.event);
+            if (this.endpointActivationRetry === undefined ||
+                this.endpointActivationRetry.event !== current.event) {
+                return;
+            }
+            this.endpointActivationRetry = {
+                event: current.event,
+                attempt: current.attempt + 1,
+            };
+            this.scheduleEndpointActivationRetry();
+        }, delay);
+        timer.unref();
+        this.endpointActivationRetryTimer = timer;
+    }
+    clearEndpointActivationRetry() {
+        if (this.endpointActivationRetryTimer !== undefined) {
+            clearTimeout(this.endpointActivationRetryTimer);
+        }
+        this.endpointActivationRetryTimer = undefined;
+        this.endpointActivationRetry = undefined;
+    }
+    emitEndpointRefresh(event) {
+        const callbacks = this.callbacks;
+        if (callbacks?.onEndpointRefresh === undefined)
+            return;
+        invokeCallback(() => callbacks.onEndpointRefresh?.(event));
+    }
+    onTurnResult(endpointGeneration, result) {
         const wantsReply = this.expectsReply.get(result.messageId) === true;
         this.expectsReply.delete(result.messageId);
         let replyText;
@@ -2306,6 +2673,7 @@ export class LocalCodexGatewayProvider {
                         : "CODEX_DELIVERY_AMBIGUOUS";
         this.enqueueCodexCallback({
             type: "delivery",
+            endpointGeneration,
             value: {
                 messageId: result.messageId,
                 state,
@@ -2317,6 +2685,7 @@ export class LocalCodexGatewayProvider {
     queueRouteObservation(route, observation) {
         this.enqueueCodexCallback({
             type: "route",
+            endpointGeneration: route.endpointGeneration,
             generation: route.generation,
             routeHandle: route.threadId,
             state: codexRouteState(observation),
@@ -2340,6 +2709,8 @@ export class LocalCodexGatewayProvider {
             }
         }
         this.callbackQueue.push(event);
+        if (this.callbackDrainFrozen)
+            return;
         if (this.callbackScheduled)
             return;
         this.callbackScheduled = true;
@@ -2353,6 +2724,10 @@ export class LocalCodexGatewayProvider {
         const callbacks = this.callbacks;
         if (event === undefined || callbacks === undefined)
             return;
+        if (event.endpointGeneration !== this.factory.endpointGeneration ||
+            this.retiredEndpointGeneration === event.endpointGeneration) {
+            return;
+        }
         if (event.type === "delivery") {
             invokeCallback(() => callbacks.onDelivery(event.value));
         }
@@ -2361,7 +2736,11 @@ export class LocalCodexGatewayProvider {
                 return;
             }
             invokeCallback(() => callbacks.onRouteState({
-                endpoint: callbackEndpoint(this.identity, event.routeHandle),
+                endpoint: callbackEndpoint({
+                    provider: "codex",
+                    hostId: this.identity.hostId,
+                    endpointGeneration: event.endpointGeneration,
+                }, event.routeHandle),
                 state: event.state,
                 ...(event.safeErrorCode === undefined
                     ? {}
@@ -2369,7 +2748,9 @@ export class LocalCodexGatewayProvider {
             }));
         }
     }
-    drainCallbackQueue() {
+    drainCallbackQueue(force = false) {
+        if (this.callbackDrainFrozen && !force)
+            return;
         while (this.callbackQueue.length > 0)
             this.drainOneCallback();
     }