agent-embassy 1.0.0 → 1.2.0

package/dist/src/gateway/providers.js

@@ -3,11 +3,12 @@ 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 +23,45 @@ 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" };
 }
@@ -835,7 +871,9 @@ export class LocalClaudeGatewayProvider {
             const selectedAlias = this.selected.get(input.binding.routeHandle);
             const stateRoot = this.selectedStateRoots.get(input.binding.routeHandle);
             if (input.authorization === "selected_route" &&
-                (selectedAlias === undefined || stateRoot === undefined)) {
+                (selectedAlias === undefined ||
+                    selectedAlias !== input.targetAlias ||
+                    stateRoot === undefined)) {
                 return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
             }
             if (input.authorization === "selected_route") {
@@ -895,8 +933,20 @@ export class LocalClaudeGatewayProvider {
                 this.nativeInbound.delete(input.binding.routeHandle);
                 return { state: "failed", safeErrorCode: "CLAUDE_NATIVE_REPLY_STALE" };
             }
+            if (observedRoute.alias !== input.targetAlias) {
+                return { state: "failed", safeErrorCode: "CLAUDE_ROUTE_UNAVAILABLE" };
+            }
         }
-        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 ||
+                selectedAlias !== input.targetAlias ||
+                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 +962,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 failure keeps the route busy until a later authoritative idle
+            // observation wakes the one bounded retry.
             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 +1041,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 +1096,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) {
@@ -1585,13 +1660,12 @@ 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) ||
         schema.appServerVersion !== factory.appServerVersion ||
         schema.endpointGeneration !== factory.endpointGeneration ||
         schema.protocol !== "app-server-v2-stable" ||
@@ -1638,10 +1712,9 @@ function codexRouteSafeCode(observation) {
     return undefined;
 }
 export class LocalCodexGatewayProvider {
-    identity;
-    protocol;
-    protocolVersion;
     factory;
+    refreshFactory;
+    compatibilityPolicy;
     maxCallbacks;
     maxRoutes;
     maxReplyBytes;
@@ -1651,32 +1724,41 @@ 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;
+        this.compatibilityPolicy =
+            options.compatibilityPolicy ?? options.factory.compatibilityPolicy;
+        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 +1775,60 @@ 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 === "incompatible" ||
+            (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 +1839,6 @@ export class LocalCodexGatewayProvider {
             });
             stage = "thread_list";
             await connector.observeLoadedThread(connector.guard());
-            this.compatibilityAttested = true;
             return [
                 passedProbe(installation),
                 passedProbe(control),
@@ -1736,6 +1847,8 @@ export class LocalCodexGatewayProvider {
             ];
         }
         catch (error) {
+            if (this.isEndpointGenerationChanged(error))
+                throw error;
             if (stage === "transport") {
                 const controlFailure = error instanceof LocalCodexTransportError &&
                     [
@@ -1888,7 +2001,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 +2011,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 +2157,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,7 +2166,10 @@ 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)) {
@@ -1978,13 +2189,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 +2248,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 +2293,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 +2306,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.");
         }
@@ -2085,6 +2332,10 @@ export class LocalCodexGatewayProvider {
         }
         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 +2343,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 +2373,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 +2381,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 +2434,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 +2451,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 +2510,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 +2542,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,7 +2564,323 @@ export class LocalCodexGatewayProvider {
             clearTimeout(timer);
         this.routeRecoveryTimers.delete(threadId);
     }
-    onTurnResult(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 ||
+                    candidate.compatibilityPolicy !== this.compatibilityPolicy) {
+                    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(),
+                    policy: this.compatibilityPolicy,
+                    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 certification = this.compatibilityTurns.get(result.messageId);
         if (certification !== undefined) {
             clearTimeout(certification.timer);
@@ -2306,6 +2919,7 @@ export class LocalCodexGatewayProvider {
                         : "CODEX_DELIVERY_AMBIGUOUS";
         this.enqueueCodexCallback({
             type: "delivery",
+            endpointGeneration,
             value: {
                 messageId: result.messageId,
                 state,
@@ -2317,6 +2931,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 +2955,8 @@ export class LocalCodexGatewayProvider {
             }
         }
         this.callbackQueue.push(event);
+        if (this.callbackDrainFrozen)
+            return;
         if (this.callbackScheduled)
             return;
         this.callbackScheduled = true;
@@ -2353,6 +2970,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 +2982,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 +2994,9 @@ export class LocalCodexGatewayProvider {
             }));
         }
     }
-    drainCallbackQueue() {
+    drainCallbackQueue(force = false) {
+        if (this.callbackDrainFrozen && !force)
+            return;
         while (this.callbackQueue.length > 0)
             this.drainOneCallback();
     }