agent-embassy 1.4.1 → 1.6.0

package/dist/src/gateway/service.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { BridgeError } from "../errors.js";
 import { KeyedMutex } from "../mutex.js";
-import { certifiedCompatibilityVersions, compatibilitySurfaces, evaluateCompatibilityAttestation, isCompatibilityAttestation, } from "./compatibility.js";
+import { certifiedCompatibilityVersions, compatibilitySurfaceDefinitions, evaluateCompatibilityAttestation, isCompatibilityAttestation, } from "./compatibility.js";
 import { createGatewayConversationId, isGatewaySnapshot, startGatewayControlServer, } from "./control.js";
 import { publishGatewayDashboard } from "./dashboard.js";
 import { createDeliveryMachine, isTerminalDeliveryMachine, projectDelivery, projectDeliveryWakeups, transitionDelivery, } from "./delivery-machine.js";
@@ -9,7 +9,7 @@ import { createCodexRegistrationSuccession, transitionCodexRegistrationSuccessio
 import { createCodexRegistrationGeneration, isCodexRegistrationGeneration, } from "./codex-registration-generation.js";
 import { PROGRESS_WATCH_DEFAULT_IDLE_MS } from "./progress-watch-machine.js";
 import { GatewayStore, } from "./store.js";
-import { GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, arePublicAvailablePeerSnapshots, projectGatewayPublicSnapshot, } from "./types.js";
+import { GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, arePublicAvailablePeerSnapshots, projectPublicCompatibilityCheck, projectGatewayPublicSnapshot, } from "./types.js";
 const PUBLIC_ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
 const CLAUDE_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const SAFE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
@@ -22,10 +22,37 @@ const NATIVE_HELD_THRESHOLD_MS = 1_000;
 const RUNTIME_ACTIVITY_CAPACITY = 256;
 const DELIVERY_SETTLEMENT_RETRY_MS = 250;
 const DELIVERY_DASHBOARD_REFRESH_MS = 15_000;
+const BOOT_REACTIVATION_TRUST_FAILURE_CODES = new Set([
+    "HOME_INVALID",
+    "MANAGED_CODEX_INVALID",
+    "LOCAL_APP_SERVER_ENDPOINT_UNSAFE",
+    "APP_SERVER_VERSION_MISMATCH",
+    "ENDPOINT_GENERATION_CHANGED",
+    "CODEX_ENDPOINT_GENERATION_CHURN",
+    "CODEX_FACTORY_ATTESTATION_INVALID",
+    "CLEANUP_FAILED",
+    "FACTORY_CLOSED",
+    "INVALID_CONFIGURATION",
+    "CLAUDE_PEER_CALLBACK_UNSAFE",
+    "CODEX_ROUTE_CLEANUP_FAILED",
+    "CODEX_PROVIDER_CLEANUP_FAILED",
+    "CODEX_PROVIDER_CLEANUP_AMBIGUOUS",
+    "CODEX_PROVIDER_CLEANUP_TIMEOUT",
+]);
+function boundedErrorCode(error) {
+    if (typeof error !== "object" ||
+        error === null ||
+        !("code" in error) ||
+        typeof error.code !== "string" ||
+        !SAFE_CODE.test(error.code)) {
+        return undefined;
+    }
+    return error.code;
+}
 function progressWatchActivity(text, conversationId, actorAlias, explicitIdleMinutes) {
     const prefixedOpen = text.startsWith("TRACK:");
     const completionSignal = text.startsWith("DONE:");
-    if (completionSignal && (prefixedOpen || explicitIdleMinutes !== undefined)) {
+    if (completionSignal && explicitIdleMinutes !== undefined) {
         throw new BridgeError("PROGRESS_WATCH_SIGNAL_CONFLICT", "A single message cannot both open and complete a progress watch.");
     }
     const openIdleMs = explicitIdleMinutes === undefined
@@ -122,6 +149,8 @@ export class GatewayService {
     config;
     store;
     adapters;
+    compatibilityObservers;
+    compatibilitySurfaceDefinitions;
     publishDashboard;
     now;
     timers;
@@ -133,6 +162,8 @@ export class GatewayService {
     bindingAliases = new Map();
     candidates = new Map();
     availablePeers = [];
+    registryEvidenceByConnector = new Map();
+    registryAdaptersWithParseableRecords = new Set();
     conversations = new Map();
     messageContexts = new Map();
     providerTurnContinuations = new Map();
@@ -145,6 +176,8 @@ export class GatewayService {
     deliveryTokens = new Map();
     runtimeAlerts = [];
     activityEvents = [];
+    /** Startup probe failures that must preflight cross-provider mutations. */
+    incompatibleProviderSurfaces = new Map();
     activeCodexIncompatibility;
     activitySequence = 0;
     detachedReceiptWrites = new Set();
@@ -214,6 +247,9 @@ export class GatewayService {
     constructor(options) {
         this.config = options.config;
         this.adapters = [...(options.adapters ?? [])];
+        this.compatibilityObservers = [...(options.compatibilityObservers ?? [])];
+        this.compatibilitySurfaceDefinitions =
+            options.compatibilitySurfaceDefinitions ?? compatibilitySurfaceDefinitions;
         this.publishDashboard = options.publishDashboard ?? publishGatewayDashboard;
         this.now = options.now ?? (() => new Date());
         this.store =
@@ -260,6 +296,12 @@ export class GatewayService {
                     throw new BridgeError("GATEWAY_ADAPTER_NOT_ALLOWED", "A provider adapter is duplicated or outside the host allowlist.");
                 }
                 seen.add(key);
+            }
+            if (this.adapters.length > 0) {
+                await this.runAutomaticCompatibilityProbesLocked();
+                assertStartActive();
+            }
+            for (const adapter of this.adapters) {
                 const observation = await adapter.initialize(this.callbacksFor(adapter));
                 assertStartActive();
                 await this.store.observeConnector({
@@ -274,15 +316,6 @@ export class GatewayService {
                 });
                 assertStartActive();
             }
-            if (this.adapters.length > 0 &&
-                this.adapters.every((adapter) => adapter.compatibilitySurface !== undefined &&
-                    adapter.runCompatibilityProbes !== undefined)) {
-                const attestations = await this.runAutomaticCompatibilityProbesLocked();
-                const incompatible = attestations.find((surface) => surface.tier === "incompatible");
-                if (incompatible !== undefined) {
-                    throw new BridgeError(incompatible.safeErrorCode ?? "COMPATIBILITY_CHECK_FAILED", "A local provider failed bounded compatibility attestation.");
-                }
-            }
             await this.recoverCodexSuccessionAfterRestartLocked();
             bootReactivatedIdleAliases =
                 await this.reactivateRetainedCodexRoutesAfterRestartLocked();
@@ -338,7 +371,7 @@ export class GatewayService {
             try {
                 await control.close();
             }
-            catch {
+            catch (error) {
                 closeFailed = true;
             }
         }
@@ -404,7 +437,7 @@ export class GatewayService {
                 await this.drainDetachedReceiptWritesLocked();
                 await this.publish();
             }
-            catch {
+            catch (error) {
                 closeFailed = true;
             }
             const adapterResults = await Promise.allSettled(this.adapters.map(async (adapter) => adapter.close()));
@@ -427,6 +460,9 @@ export class GatewayService {
                 this.deliveryTrackers.clear();
                 this.deliveryTokens.clear();
                 this.runtimeAlerts.length = 0;
+                this.incompatibleProviderSurfaces.clear();
+                this.registryEvidenceByConnector.clear();
+                this.registryAdaptersWithParseableRecords.clear();
                 this.detachedReceiptWrites.clear();
                 this.nativeIngressByConversation.clear();
                 this.callbackQueue.length = 0;
@@ -511,10 +547,7 @@ export class GatewayService {
             observeSnapshot: async () => await this.observeSnapshot(),
             deliveryStatus: async (params) => await this.deliveryStatus(params.token),
             untrack: async (params) => await this.exclusiveDecision(async () => {
-                const settled = await this.store.settleProgressWatch({
-                    conversationId: params.conversationId,
-                    outcome: "done",
-                });
+                const settled = await this.store.endProgressWatch(params.conversationId);
                 if (!settled) {
                     throw new BridgeError("PROGRESS_WATCH_NOT_FOUND", "No active progress watch matches that conversation token.");
                 }
@@ -540,25 +573,58 @@ export class GatewayService {
         return (await this.observeSnapshot()).snapshot;
     }
     async runAutomaticCompatibilityProbesLocked() {
-        const bySurface = new Map(this.adapters.map((adapter) => {
-            if (adapter.compatibilitySurface === undefined ||
-                adapter.runCompatibilityProbes === undefined) {
-                throw new BridgeError("COMPAT_PROVIDER_UNAVAILABLE", "Every local provider must expose the bounded compatibility probe contract.");
-            }
-            const observation = adapter.compatibilitySurface();
-            return [observation.surface, { adapter, observation }];
+        const entries = [
+            ...this.adapters.map((adapter) => {
+                if (adapter.compatibilitySurface === undefined ||
+                    adapter.runCompatibilityProbes === undefined) {
+                    throw new BridgeError("COMPAT_PROVIDER_UNAVAILABLE", "Every local provider must expose the bounded compatibility probe contract.");
+                }
+                return {
+                    observer: adapter,
+                    adapter,
+                };
+            }),
+            ...this.compatibilityObservers.map((observer) => ({ observer })),
+        ];
+        const observedEntries = entries.map((entry) => ({
+            ...entry,
+            observation: entry.observer.compatibilitySurface(),
         }));
-        if (bySurface.size !== compatibilitySurfaces.length ||
-            compatibilitySurfaces.some((surface) => !bySurface.has(surface))) {
-            throw new BridgeError("COMPAT_PROVIDER_UNAVAILABLE", "The bounded compatibility probe requires one Claude and one Codex surface.");
-        }
+        const bySurface = new Map(observedEntries.map((entry) => [entry.observation.surface, entry]));
+        if (bySurface.size !== entries.length) {
+            throw new BridgeError("COMPAT_PROVIDER_UNAVAILABLE", "Each compatibility observer must expose one distinct surface.");
+        }
+        const declared = new Set(this.compatibilitySurfaceDefinitions.map(({ surface }) => surface));
+        if ([...bySurface.keys()].some((surface) => !declared.has(surface))) {
+            throw new BridgeError("COMPAT_SURFACE_UNDECLARED", "Every compatibility observer must use a declared surface.");
+        }
+        const forbiddenCodexThreadIds = (await this.store.inspectPrivateCodexRoutes()).map((route) => route.binding.routeHandle);
+        const probeContext = {
+            stateRoot: this.store.rootDir,
+            forbiddenCodexThreadIds,
+        };
         const attestations = [];
-        for (const surface of compatibilitySurfaces) {
+        for (const definition of this.compatibilitySurfaceDefinitions) {
+            const { surface } = definition;
             const entry = bySurface.get(surface);
             if (entry === undefined) {
+                if (!definition.required)
+                    continue;
                 throw new BridgeError("COMPAT_PROVIDER_UNAVAILABLE", "A required compatibility surface is unavailable.");
             }
-            const probes = await entry.adapter.runCompatibilityProbes();
+            const probes = entry.adapter === undefined
+                ? await entry.observer.runCompatibilityProbes()
+                : await entry.adapter.runCompatibilityProbes(probeContext);
+            if (entry.adapter !== undefined) {
+                const writeProbe = entry.adapter.latestWriteCompatibilityProbeObservation?.(entry.adapter.identity.endpointGeneration);
+                if (writeProbe?.outcome === "fail") {
+                    this.addRuntimeAlert(writeProbe.safeErrorCode, writeProbe.safeErrorCode === "CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED" ||
+                        writeProbe.safeErrorCode === "CODEX_WRITE_PROBE_CLEANUP_UNCONFIRMED"
+                        ? "error"
+                        : "warning", { provider: "codex", host: entry.adapter.identity.hostId });
+                }
+                this.captureRegistryObservation(entry.adapter, entry.adapter.latestRegistryObservation?.());
+            }
             const attestation = evaluateCompatibilityAttestation({
                 surface,
                 version: entry.observation.version,
@@ -567,13 +633,84 @@ export class GatewayService {
                 probes,
             });
             await this.store.recordCompatibilityAttestation(attestation);
-            if (attestation.tier !== "incompatible") {
-                entry.adapter.acceptCompatibilityAttestation?.(attestation);
+            entry.observer.acceptCompatibilityAttestation?.(attestation);
+            if (attestation.tier === "incompatible" && entry.adapter !== undefined) {
+                const code = attestation.safeErrorCode ?? "COMPATIBILITY_CHECK_FAILED";
+                this.incompatibleProviderSurfaces.set(this.providerSurfaceKey(entry.adapter.identity.provider, entry.adapter.identity.hostId), code);
+                if (surface === "codex") {
+                    this.activeCodexIncompatibility = structuredClone(attestation);
+                }
+            }
+            else if (surface === "codex" &&
+                attestation.tier === "schema_attested" &&
+                entry.adapter !== undefined) {
+                // A live but untested App Server schema is useful for observation only.
+                // Fence retained boot reactivation before it can trigger endpoint
+                // refresh churn; an explicit registration may still re-probe a later,
+                // certified generation through the provider's bounded refresh path.
+                this.incompatibleProviderSurfaces.set(this.providerSurfaceKey("codex", entry.adapter.identity.hostId), "CODEX_MONITOR_ONLY");
             }
             attestations.push(attestation);
         }
         return attestations;
     }
+    captureRegistryObservation(adapter, observation) {
+        if (adapter.identity.provider !== "claude" ||
+            observation === undefined ||
+            !Number.isSafeInteger(observation.entriesScanned) ||
+            observation.entriesScanned < 0 ||
+            !Number.isSafeInteger(observation.parseableRecords) ||
+            observation.parseableRecords < 0 ||
+            observation.parseableRecords > observation.entriesScanned ||
+            !Array.isArray(observation.rejected)) {
+            return;
+        }
+        const counts = new Map();
+        for (const row of observation.rejected) {
+            if (!row ||
+                typeof row !== "object" ||
+                typeof row.safeErrorCode !== "string" ||
+                !SAFE_CODE.test(row.safeErrorCode) ||
+                !Number.isSafeInteger(row.count) ||
+                row.count <= 0) {
+                continue;
+            }
+            const next = (counts.get(row.safeErrorCode) ?? 0) + row.count;
+            counts.set(row.safeErrorCode, Math.min(Number.MAX_SAFE_INTEGER, next));
+        }
+        const ordered = [...counts]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([safeErrorCode, count]) => ({ safeErrorCode, count }));
+        const rejected = ordered.slice(0, gatewayPublicSnapshotLimits.registryRejectionCodes);
+        if (observation.parseableRecords > 0) {
+            this.registryAdaptersWithParseableRecords.add(adapter);
+        }
+        const hasObservedParseableRecord = this.registryAdaptersWithParseableRecords.has(adapter);
+        const row = {
+            entriesScanned: observation.entriesScanned,
+            parseableRecords: observation.parseableRecords,
+            parseableRecordSeenSinceBoot: hasObservedParseableRecord,
+            rejected,
+            rejectedCodesOmitted: Math.max(0, ordered.length - rejected.length),
+        };
+        this.registryEvidenceByConnector.set(`${adapter.identity.provider}\0${adapter.identity.hostId}`, row);
+    }
+    connectorsWithRegistry(connectors) {
+        return connectors.map((connector) => {
+            const registry = this.registryEvidenceByConnector.get(`${connector.provider}\0${connector.host}`);
+            return {
+                ...connector,
+                ...(connector.provider !== "claude" || registry === undefined
+                    ? {}
+                    : {
+                        registry: {
+                            ...registry,
+                            rejected: registry.rejected.map((row) => ({ ...row })),
+                        },
+                    }),
+            };
+        });
+    }
     async observeSnapshot() {
         return await this.mutex.run("service", async () => {
             const changed = await this.processLifecycleLocked();
@@ -921,17 +1058,31 @@ export class GatewayService {
             await this.publish();
         }
         this.pruneTransient();
+        const deferredRouteObservations = [];
         while (this.hasPendingCallbackWork()) {
             // Preserve the complete ordinary queue order. In particular, every
             // delivery observation already retained before endpoint replacement is
             // reduced before the lifecycle transition can settle its generation.
             const ordinaryBatch = this.callbackQueue.splice(0, this.callbackQueue.length);
+            const pendingRefresh = this.endpointRefreshCallback?.value;
             for (const event of ordinaryBatch) {
                 try {
                     if (event.type === "delivery") {
                         await this.onDelivery(event.source, event.value, event.receivedAt);
                     }
                     else if (event.type === "route") {
+                        if (pendingRefresh?.outcome === "compatible" &&
+                            event.source.provider === "codex" &&
+                            event.source.hostId === pendingRefresh.current.hostId &&
+                            event.source.endpointGeneration ===
+                                pendingRefresh.current.endpointGeneration &&
+                            pendingRefresh.routes.some((route) => route.routeHandle === event.value.routeHandle)) {
+                            // The provider can observe G2 after staging it but before this
+                            // worker installs G2's durable binding. Preserve that fresher
+                            // state until the exact transition evidence has been reduced.
+                            deferredRouteObservations.push(event);
+                            continue;
+                        }
                         await this.onRouteState(event.source, event.value);
                     }
                     else if (event.type === "claude_reply") {
@@ -994,6 +1145,14 @@ export class GatewayService {
                 this.endpointRefreshCallback = requestedRetry;
             }
         }
+        for (const event of deferredRouteObservations) {
+            try {
+                await this.onRouteState(event.source, event.value);
+            }
+            catch {
+                this.dashboardHealthy = false;
+            }
+        }
     }
     /**
      * A selector can synchronously admit callbacks while its promise is still
@@ -1149,6 +1308,23 @@ export class GatewayService {
             throw new BridgeError("PROVIDER_UNAVAILABLE", "The selected provider is unavailable.", true);
         return adapter;
     }
+    providerSurfaceKey(provider, host) {
+        return `${provider}@${host}`;
+    }
+    incompatibleProviderCode(provider, host) {
+        return this.incompatibleProviderSurfaces.get(this.providerSurfaceKey(provider, host));
+    }
+    /** Reject before either half of a cross-provider mutation can acquire state. */
+    assertCrossProviderMutationCompatible(host, options = { allowCodexRefresh: false }) {
+        const claudeCode = this.incompatibleProviderCode("claude", host);
+        if (claudeCode !== undefined) {
+            throw new BridgeError(claudeCode, "The Claude provider is observation-only until Embassy restarts with a compatible runtime.");
+        }
+        const codexCode = this.incompatibleProviderCode("codex", host);
+        if (codexCode !== undefined && !options.allowCodexRefresh) {
+            throw new BridgeError(codexCode, "The Codex provider is observation-only until a compatible endpoint is re-observed.");
+        }
+    }
     async assertClaudeWorkspaceDisjoint(adapter, routeHandle) {
         if (adapter.identity.provider !== "claude") {
             throw new BridgeError("CLAUDE_PROVIDER_MISMATCH", "The selected workspace guard does not belong to Claude.");
@@ -1219,6 +1395,13 @@ export class GatewayService {
                 this.addRuntimeAlert("CODEX_BOOT_REACTIVATION_SKIPPED", "warning", { provider: "codex", host: route.binding.hostId, alias: route.alias });
                 continue;
             }
+            if (this.incompatibleProviderCode("codex", route.binding.hostId) !==
+                undefined ||
+                this.incompatibleProviderCode("claude", route.binding.hostId) !==
+                    undefined) {
+                this.addRuntimeAlert("CODEX_BOOT_REACTIVATION_SKIPPED", "warning", { provider: "codex", host: route.binding.hostId, alias: route.alias });
+                continue;
+            }
             let routeSelected = false;
             let advertiseAttempted = false;
             let storeReactivated = false;
@@ -1308,7 +1491,7 @@ export class GatewayService {
                 if (selected.state === "idle")
                     idleAliases.push(route.alias);
             }
-            catch {
+            catch (error) {
                 let cleanupFailed = false;
                 if (advertiseAttempted) {
                     await claudeAdapter
@@ -1327,6 +1510,11 @@ export class GatewayService {
                 if (cleanupFailed || storeReactivated || deferredEndpointRefresh) {
                     throw new BridgeError("CODEX_BOOT_REACTIVATION_CLEANUP_FAILED", "A Codex boot reactivation crossed its durable boundary without exact live authority.");
                 }
+                const failureCode = boundedErrorCode(error);
+                if (failureCode !== undefined &&
+                    BOOT_REACTIVATION_TRUST_FAILURE_CODES.has(failureCode)) {
+                    throw error;
+                }
                 this.addRuntimeAlert("CODEX_BOOT_REACTIVATION_SKIPPED", "warning", { provider: "codex", host: route.binding.hostId, alias: route.alias });
             }
         }
@@ -2119,6 +2307,9 @@ export class GatewayService {
         if (!params.alias.startsWith("codex-")) {
             throw new BridgeError("INVALID_CODEX_PEER_ALIAS", "A registered Codex alias must start with codex-.");
         }
+        this.assertCrossProviderMutationCompatible(params.hostId, {
+            allowCodexRefresh: params.succeedsAlias === undefined,
+        });
         if (this.codexSuccessionPoisoned.has(params.alias) ||
             this.codexOrphanCleanupPending.has(params.alias) ||
             (params.succeedsAlias !== undefined &&
@@ -2338,7 +2529,7 @@ export class GatewayService {
             unwrittenOutcome: "cancelled",
             safeErrorCode: "ROUTE_UNREGISTERED",
         });
-        const settlements = await this.store.unregisterRoute(params.alias, lease, inFlightSettlements);
+        const settlements = await this.store.unregisterRoute(params.alias, lease, inFlightSettlements, "operator");
         for (const settlement of settlements) {
             await this.applyTerminalSettlementLocked(settlement);
         }
@@ -2573,6 +2764,7 @@ export class GatewayService {
         const base = await this.store.publicSnapshot();
         const snapshot = projectGatewayPublicSnapshot({
             ...base,
+            connectors: this.connectorsWithRegistry(base.connectors),
             availablePeers: this.availablePeers.map((peer) => ({ ...peer })),
         });
         return JSON.stringify({
@@ -2607,6 +2799,7 @@ export class GatewayService {
                 // authority. The provider still revalidates the exact target before
                 // any write.
             }
+            this.captureRegistryObservation(adapter, discovered.registry ?? adapter.latestRegistryObservation?.());
             const grouped = new Map();
             const byHandle = new Map();
             for (const peer of discovered.peers) {
@@ -3094,6 +3287,32 @@ export class GatewayService {
         await this.selectAndPairClaude(params.alias, await this.inferCodexAlias(params.codexThreadId));
     }
     async selectAndPairClaude(selector, codexAlias) {
+        const codexBinding = this.routeBindings.get(codexAlias);
+        const retainedCodexRoute = codexBinding?.provider === "codex"
+            ? undefined
+            : await this.store.inspectPrivateRoute(codexAlias);
+        const codexHost = codexBinding?.provider === "codex"
+            ? codexBinding.hostId
+            : retainedCodexRoute?.binding.provider === "codex"
+                ? retainedCodexRoute.binding.hostId
+                : undefined;
+        if (codexHost !== undefined) {
+            this.assertCrossProviderMutationCompatible(codexHost);
+        }
+        const codexAdapter = codexBinding?.provider === "codex"
+            ? this.adapters.find((adapter) => adapter.identity.provider === "codex" &&
+                adapter.identity.hostId === codexBinding.hostId)
+            : undefined;
+        const codexState = this.routeStates.get(codexAlias);
+        if (codexBinding?.provider !== "codex" ||
+            codexAdapter === undefined ||
+            codexAdapter.identity.endpointGeneration !==
+                codexBinding.endpointGeneration ||
+            (codexState !== "idle" &&
+                codexState !== "busy" &&
+                codexState !== "awaiting_approval")) {
+            throw new BridgeError("CODEX_ROUTE_UNAVAILABLE", "Claude selection requires an exact positively observed live Codex route.");
+        }
         const discoveryChanged = await this.refreshClaudeDiscovery();
         const candidate = this.claudeCandidate(selector);
         if (candidate === undefined)
@@ -3201,6 +3420,16 @@ export class GatewayService {
         this.routeStates.set(alias, state);
         this.bindingAliases.set(bindingKey(binding), alias);
     }
+    reanchorQueuedMessageContexts(alias, previous, current) {
+        const previousKey = bindingKey(previous);
+        const currentKey = bindingKey(current);
+        for (const context of this.messageContexts.values()) {
+            if (context.targetAlias === alias &&
+                context.targetBindingKey === previousKey) {
+                context.targetBindingKey = currentKey;
+            }
+        }
+    }
     forgetBinding(alias) {
         const heldTimer = this.heldRedispatchTimers.get(alias);
         if (heldTimer !== undefined) {
@@ -3924,14 +4153,7 @@ export class GatewayService {
             return false;
         }
         const actions = await this.store.advanceDueProgressWatches();
-        let changed = actions.length > 0;
         for (const action of actions) {
-            if (action.type === "settled") {
-                this.addRuntimeAlert(action.outcome === "unresponsive"
-                    ? "PROGRESS_WATCH_UNRESPONSIVE"
-                    : "PROGRESS_WATCH_ENDPOINT_RETIRED", action.outcome === "unresponsive" ? "error" : "warning", { alias: action.ownerAlias });
-                continue;
-            }
             const text = `[Embassy automated liveness check — ${action.conversationId} / ` +
                 `Embassy 自动活跃检查 — ${action.conversationId}]\n` +
                 "Reply with the result or a status. / 请回复结果或状态。";
@@ -3945,20 +4167,13 @@ export class GatewayService {
                         nudgeNumber: action.nudgeNumber,
                     },
                 });
-                this.addRuntimeAlert("PROGRESS_WATCH_NUDGE", "warning", {
-                    alias: action.ownerAlias,
-                });
             }
             catch {
-                await this.store.deferProgressWatchNudge(action.conversationId);
-                this.addRuntimeAlert("PROGRESS_WATCH_NUDGE_DEFERRED", "warning", {
-                    alias: action.ownerAlias,
-                });
-                changed = true;
+                await this.store.deferProgressWatchNudge(action.conversationId, action.nudgeNumber);
             }
         }
         await this.refreshNextProgressWatchWakeLocked();
-        return changed;
+        return actions.length > 0;
     }
     async processLifecycleLocked() {
         const now = this.now().getTime();
@@ -4253,6 +4468,9 @@ export class GatewayService {
         const conversationId = options.existingConversationId ?? createGatewayConversationId();
         const conversation = this.conversations.get(conversationId) ?? {
             id: conversationId,
+            ...(options.existingConversationId === undefined
+                ? {}
+                : { dedupeScope: createGatewayConversationId() }),
             sourceAlias,
             targetAlias,
             expectsReply,
@@ -4269,7 +4487,7 @@ export class GatewayService {
             sourceAlias,
             targetAlias,
             body: text,
-            dedupeKey: `${conversationId}:${sequence}`,
+            dedupeKey: `${conversation.dedupeScope ?? conversationId}:${sequence}`,
             conversationIdSuffix: conversationId.slice(-8),
             deadlineAt,
             ...(options.steer === true ? { steer: true } : {}),
@@ -4348,7 +4566,7 @@ export class GatewayService {
                 binding: capability.binding,
             },
             body: text,
-            dedupeKey: `${conversation.id}:${sequence}`,
+            dedupeKey: `${conversation.dedupeScope ?? conversation.id}:${sequence}`,
             conversationIdSuffix: conversation.id.slice(-8),
             deadlineAt,
             ...(conversation.pair === true ? { pair: true } : {}),
@@ -4410,7 +4628,7 @@ export class GatewayService {
             },
             targetAlias: conversation.sourceAlias,
             body: text,
-            dedupeKey: `${conversation.id}:${sequence}`,
+            dedupeKey: `${conversation.dedupeScope ?? conversation.id}:${sequence}`,
             conversationIdSuffix: conversation.id.slice(-8),
             deadlineAt,
             authorizedPairTeardownReply: true,
@@ -4525,14 +4743,17 @@ export class GatewayService {
             await this.publishNativeHeldLocked(afterCallbacks);
         }
     }
-    restoreQueuedMessageContextLocked(item, binding) {
+    restoreQueuedMessageContextLocked(item, binding, canonicalConversationId) {
         this.pruneTransient();
-        const generatedConversationId = createGatewayConversationId();
-        const conversationId = item.conversationIdSuffix === undefined
-            ? generatedConversationId
-            : `${generatedConversationId.slice(0, -8)}${item.conversationIdSuffix}`;
-        const conversation = {
+        const conversationId = canonicalConversationId ??
+            (item.conversationIdSuffix === undefined
+                ? createGatewayConversationId()
+                : `${createGatewayConversationId().slice(0, -8)}${item.conversationIdSuffix}`);
+        const conversation = this.conversations.get(conversationId) ?? {
             id: conversationId,
+            ...(canonicalConversationId === undefined
+                ? {}
+                : { dedupeScope: createGatewayConversationId() }),
             sourceAlias: item.sourceAlias,
             targetAlias: item.targetAlias,
             expectsReply: false,
@@ -4548,7 +4769,6 @@ export class GatewayService {
             authorization: "selected_route",
             targetAlias: item.targetAlias,
             deadlineAt: item.deadlineAt,
-            recovered: true,
         };
         this.conversations.set(conversationId, conversation);
         this.messageContexts.set(item.messageId, context);
@@ -4589,6 +4809,7 @@ export class GatewayService {
             return;
         const selectedBinding = this.routeBindings.get(targetAlias);
         let context = this.messageContexts.get(item.messageId);
+        let progressWatchActive;
         if (context === undefined && selectedBinding === undefined) {
             const result = await this.store.requeueInFlightMessage(item.messageId, item.body);
             if (result.status === "settled") {
@@ -4598,7 +4819,15 @@ export class GatewayService {
             return;
         }
         if (context === undefined && selectedBinding !== undefined) {
-            context = this.restoreQueuedMessageContextLocked(item, selectedBinding);
+            const resolution = item.pair === true && item.conversationIdSuffix !== undefined
+                ? await this.store.resolveProgressWatchDispatch({
+                    recoveredConversationIdSuffix: item.conversationIdSuffix,
+                    sourceAlias: item.sourceAlias,
+                    targetAlias: item.targetAlias,
+                })
+                : undefined;
+            context = this.restoreQueuedMessageContextLocked(item, selectedBinding, resolution?.conversationId);
+            progressWatchActive = resolution?.markerActive === true;
         }
         if (context === undefined) {
             const result = await this.store.settleMessage({
@@ -4634,22 +4863,11 @@ export class GatewayService {
                     inspection?.state === "stale" ||
                     inspection?.safeErrorCode === "CODEX_ROUTE_STALE");
             if (codexRouteStale) {
-                if (context.recovered === true) {
-                    const result = await this.store.requeueInFlightMessage(item.messageId, item.body);
-                    if (result.status === "settled") {
-                        await this.applyTerminalSettlementLocked(result.settlement);
-                    }
-                    await this.changed();
-                    return;
+                const result = await this.store.requeueInFlightMessage(item.messageId, item.body);
+                if (result.status === "settled") {
+                    await this.applyTerminalSettlementLocked(result.settlement);
                 }
-                await this.advanceDeliveryLocked(item.messageId, {
-                    type: "route_terminated",
-                    at: this.now().getTime(),
-                    unwrittenOutcome: "failed",
-                    safeErrorCode: "CODEX_ROUTE_STALE",
-                });
                 await this.changed();
-                this.scheduleDispatch(targetAlias);
                 return;
             }
             const storedDispatchable = binding.provider === "claude" ||
@@ -4741,23 +4959,16 @@ export class GatewayService {
             this.scheduleLifecycleWakeLocked();
             return;
         }
-        let progressWatches = await this.store.inspectProgressWatches();
-        if (context.recovered === true &&
-            item.pair === true &&
-            !item.body.startsWith("DONE:") &&
-            progressWatches.some((watch) => watch.capability === "route" &&
-                watch.ownerAlias === item.sourceAlias &&
-                watch.workerAlias === item.targetAlias)) {
-            await this.store.bindProgressWatchConversation({
-                conversationId: context.conversationId,
-                ownerAlias: item.sourceAlias,
-                workerAlias: item.targetAlias,
-            });
-            progressWatches = await this.store.inspectProgressWatches();
+        if (progressWatchActive === undefined) {
+            progressWatchActive =
+                item.pair === true
+                    ? (await this.store.resolveProgressWatchDispatch({
+                        conversationId: context.conversationId,
+                        sourceAlias: item.sourceAlias,
+                        targetAlias: item.targetAlias,
+                    })).markerActive
+                    : false;
         }
-        const progressWatchActive = progressWatches.some((watch) => watch.capability === "conversation" &&
-            watch.workerAlias === item.targetAlias &&
-            watch.conversationId === context.conversationId);
         let result;
         try {
             result = await this.awaitDispatchWithNativeHeldLocked(tracker, this.adapter(binding.provider, binding.hostId).dispatch({
@@ -4771,6 +4982,9 @@ export class GatewayService {
                 expectsReply: context.expectsReply,
                 deadlineAt: item.deadlineAt,
                 ...(item.steer === true ? { steer: true } : {}),
+                ...(item.steer === true && item.queuedAhead !== undefined
+                    ? { queuedAhead: item.queuedAhead }
+                    : {}),
                 ...(progressWatchActive
                     ? { progressWatchActive: true }
                     : {}),
@@ -5304,6 +5518,9 @@ export class GatewayService {
             return activationDeferred;
         }
         finally {
+            if (!succeeded && event.outcome === "compatible") {
+                adapter.releaseEndpointRefreshSelectorClaim?.(event.current.endpointGeneration);
+            }
             if (ownsActiveTransition &&
                 this.activeEndpointRefreshCallbackKey === transitionKey) {
                 this.activeEndpointRefreshCallback = undefined;
@@ -5404,11 +5621,37 @@ export class GatewayService {
         if (event.outcome === "incompatible") {
             await this.requireEndpointRefreshUnconflicted();
             this.activeCodexIncompatibility = structuredClone(event.attestation);
+            this.incompatibleProviderSurfaces.set(this.providerSurfaceKey("codex", event.previous.hostId), event.attestation.safeErrorCode ?? "CODEX_ENDPOINT_INCOMPATIBLE");
             this.addRuntimeAlert(event.attestation.safeErrorCode ?? "CODEX_ENDPOINT_INCOMPATIBLE", "error", { provider: "codex", host: event.previous.hostId });
             this.handledIncompatibleEndpointRefreshes.set(event.previous.hostId, transitionKey);
             await this.changed();
             return false;
         }
+        if (event.attestation.tier === "schema_attested") {
+            // A passing untested-version schema is useful observation, but it is not
+            // durable route or write authority. Settle the provider's pending probe
+            // so a later generation can be examined, while leaving every G1 route
+            // stale and refusing selector/registration activation.
+            await this.requireEndpointRefreshUnconflicted();
+            await this.store.observeConnector({
+                identity: event.current,
+                health: "degraded",
+                compatibility: "unknown",
+                protocol: adapter.protocol,
+                protocolVersion: adapter.protocolVersion,
+                safeErrorCode: "CODEX_MONITOR_ONLY",
+            });
+            adapter.acceptCompatibilityAttestation(event.attestation);
+            this.activeCodexIncompatibility = undefined;
+            this.incompatibleProviderSurfaces.set(this.providerSurfaceKey("codex", event.current.hostId), "CODEX_MONITOR_ONLY");
+            this.handledIncompatibleEndpointRefreshes.delete(event.current.hostId);
+            await this.changed();
+            if (options.deferActivation === true ||
+                options.requiredRoute !== undefined) {
+                throw new BridgeError("CODEX_MONITOR_ONLY", "This Codex App Server passed read-only schema probes but cannot authorize a task route or message write.");
+            }
+            return false;
+        }
         await this.store.observeConnector({
             identity: event.current,
             health: "healthy",
@@ -5430,6 +5673,18 @@ export class GatewayService {
                     },
                 ];
         });
+        const reanchorPendingMessageContexts = () => {
+            for (const route of pendingReanchors) {
+                const previous = previousRoutes.find((candidate) => candidate.alias === route.alias)?.binding;
+                if (previous === undefined)
+                    continue;
+                this.reanchorQueuedMessageContexts(route.alias, previous, {
+                    ...event.current,
+                    routeHandle: route.threadId,
+                    ownerLease: route.ownerLease,
+                });
+            }
+        };
         if (pendingReanchors.length > 0) {
             try {
                 await this.store.reanchorCodexRoutes({
@@ -5437,6 +5692,7 @@ export class GatewayService {
                     newEndpoint: event.current,
                     routes: pendingReanchors,
                 });
+                reanchorPendingMessageContexts();
                 this.durablyAppliedEndpointRefreshes.set(event.current.hostId, transitionKey);
             }
             catch (error) {
@@ -5458,6 +5714,7 @@ export class GatewayService {
                     return matches.length === 1;
                 });
                 if (committedExactly) {
+                    reanchorPendingMessageContexts();
                     this.durablyAppliedEndpointRefreshes.set(event.current.hostId, transitionKey);
                     try {
                         await this.store.markConnectorOffline(event.current, "CODEX_ENDPOINT_ACTIVATION_FAILED", [], { preserveQueued: true });
@@ -5639,11 +5896,7 @@ export class GatewayService {
             // Provider writes remain closed until every durable and native transition
             // above is complete. This acknowledgement is deliberately the final
             // fallible activation step.
-            const accept = adapter.acceptCompatibilityAttestation;
-            if (accept === undefined) {
-                throw new BridgeError("CODEX_ENDPOINT_REFRESH_ACTIVATION_UNAVAILABLE", "The Codex provider cannot acknowledge the validated endpoint transition.");
-            }
-            accept.call(adapter, event.attestation);
+            adapter.acceptCompatibilityAttestation(event.attestation);
         }
         catch (error) {
             try {
@@ -5665,6 +5918,7 @@ export class GatewayService {
         }
         this.handledIncompatibleEndpointRefreshes.delete(event.current.hostId);
         this.activeCodexIncompatibility = undefined;
+        this.incompatibleProviderSurfaces.delete(this.providerSurfaceKey("codex", event.current.hostId));
         return false;
     }
     async onRouteState(source, event) {
@@ -5726,6 +5980,9 @@ export class GatewayService {
                 : event.state === "awaiting_approval"
                     ? "waiting"
                     : "busy");
+            if (previousState === "stale" && event.state !== "stale") {
+                adapter.rearmEndpointRefreshActivation?.(binding.endpointGeneration);
+            }
         }
         if (event.state === "idle" || event.state === "stale") {
             const heldTimer = this.heldRedispatchTimers.get(alias);
@@ -5841,14 +6098,14 @@ export class GatewayService {
     async publicSnapshotLocked() {
         const base = await this.store.publicSnapshot();
         const compatibilityChecks = [];
-        for (const surface of compatibilitySurfaces) {
+        for (const { surface } of this.compatibilitySurfaceDefinitions) {
             if (surface === "codex" && this.activeCodexIncompatibility !== undefined) {
                 compatibilityChecks.push(structuredClone(this.activeCodexIncompatibility));
                 continue;
             }
             const currentVersions = [
-                ...new Set(this.adapters.flatMap((adapter) => {
-                    const observation = adapter.compatibilitySurface?.();
+                ...new Set([...this.adapters, ...this.compatibilityObservers].flatMap((observer) => {
+                    const observation = observer.compatibilitySurface?.();
                     return observation?.surface === surface ? [observation.version] : [];
                 })),
             ].sort((left, right) => left.localeCompare(right));
@@ -5891,7 +6148,12 @@ export class GatewayService {
         });
         return projectGatewayPublicSnapshot({
             ...base,
-            ...(compatibilityChecks.length === 0 ? {} : { compatibilityChecks }),
+            connectors: this.connectorsWithRegistry(base.connectors),
+            ...(compatibilityChecks.length === 0
+                ? {}
+                : {
+                    compatibilityChecks: compatibilityChecks.map(projectPublicCompatibilityCheck),
+                }),
             availablePeers: peers,
             activityEvents: this.activityEvents.map((event) => ({
                 ...event,