agent-embassy 1.7.0 → 1.7.1

package/dist/src/gateway/service.js

@@ -8,7 +8,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, gatewayPublicSnapshotLimits, gatewayRegistrationIngressPrefixes, arePublicAvailablePeerSnapshots, directionId, parseDirection, projectGatewayPublicSnapshot, } from "./types.js";
+import { GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, gatewayRegistrationIngressPrefixes, arePublicAvailablePeerSnapshots, directionId, parseDirection, projectGatewayPublicSnapshot, CONNECTOR_OBSERVATION_STALE_AFTER_MS, } 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}$/;
@@ -21,6 +21,8 @@ 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 CLAUDE_DISCOVERY_REFRESH_MS = 30_000;
+const CODEX_DOCTOR_REFRESH_MS = 30_000;
 const BOOT_REACTIVATION_TRUST_FAILURE_CODES = new Set([
     "HOME_INVALID",
     "MANAGED_CODEX_INVALID",
@@ -127,6 +129,7 @@ export class GatewayService {
     timers;
     nativePeerCwd;
     successionGeneration;
+    codexDoctor;
     mutex = new KeyedMutex();
     routeBindings = new Map();
     routeStates = new Map();
@@ -177,8 +180,17 @@ export class GatewayService {
     callbackCapacity;
     deliveryCallbackReserve;
     deliveryTokenCapacity;
+    providerDispatchInFlightMessageIds = new Set();
+    connectorFreshnessDeadlineAt = new Map();
     lifecycleTimer;
+    lifecyclePublishPending = false;
     nextDashboardRefreshAt;
+    nextClaudeDiscoveryAt;
+    claudeDiscoveryScheduled = false;
+    claudeDiscoveryInFlight;
+    codexDoctorTimer;
+    codexDoctorInFlight;
+    codexDoctorResult;
     nextProgressWatchAt;
     control;
     /** Coarse controller mutation revision exposed by `health`. */
@@ -225,6 +237,7 @@ export class GatewayService {
         this.successionGeneration =
             options.successionGeneration ??
                 createCodexRegistrationGeneration;
+        this.codexDoctor = options.codexDoctor;
         this.callbackCapacity = Math.max(64, options.config.limits.maxRoutes +
             options.config.limits.maxInFlightMessages * 8);
         // A callback flood must never crowd out write evidence. One selected route
@@ -273,6 +286,7 @@ export class GatewayService {
                         ? {}
                         : { safeErrorCode: safeCode(observation.safeErrorCode, "ADAPTER_DEGRADED") }),
                 });
+                this.recordConnectorFreshness(adapter.identity, observation.health);
                 if (observation.ownedRoute !== undefined) {
                     const route = observation.ownedRoute;
                     const prefix = gatewayRegistrationIngressPrefixes[adapter.identity.provider];
@@ -293,6 +307,14 @@ export class GatewayService {
                 }
                 assertStartActive();
             }
+            await this.refreshClaudeDiscovery({ incrementRevision: false }).catch(() => false);
+            await this.refreshCodexDoctor();
+            for (const [alias, binding] of this.routeBindings) {
+                if (binding.provider === "claude" &&
+                    this.routeStates.get(alias) === "idle") {
+                    bootReactivatedIdleAliases.push(alias);
+                }
+            }
             await this.recoverCodexSuccessionAfterRestartLocked();
             bootReactivatedIdleAliases.push(...(await this.reactivateRetainedCodexRoutesAfterRestartLocked()));
             assertStartActive();
@@ -313,8 +335,11 @@ export class GatewayService {
             this.control = control;
             this.running = true;
             this.nextDashboardRefreshAt = undefined;
+            this.nextClaudeDiscoveryAt =
+                this.now().getTime() + CLAUDE_DISCOVERY_REFRESH_MS;
             await this.refreshNextProgressWatchWakeLocked();
             this.scheduleLifecycleWakeLocked();
+            this.scheduleCodexDoctor();
             for (const alias of bootReactivatedIdleAliases) {
                 this.scheduleDispatch(alias);
             }
@@ -343,6 +368,12 @@ export class GatewayService {
         const control = this.control;
         this.control = undefined;
         let closeFailed = false;
+        if (this.codexDoctorTimer !== undefined) {
+            this.timers.clearTimeout(this.codexDoctorTimer);
+            this.codexDoctorTimer = undefined;
+        }
+        await this.codexDoctorInFlight?.catch(() => undefined);
+        await this.claudeDiscoveryInFlight?.catch(() => undefined);
         if (control !== undefined) {
             try {
                 await control.close();
@@ -359,6 +390,9 @@ export class GatewayService {
                     this.timers.clearTimeout(this.lifecycleTimer);
                     this.lifecycleTimer = undefined;
                 }
+                this.nextClaudeDiscoveryAt = undefined;
+                this.lifecyclePublishPending = false;
+                this.connectorFreshnessDeadlineAt.clear();
                 const quiesceResults = await Promise.allSettled(this.adapters.map(async (adapter) => await adapter.quiesceNativeInbound?.()));
                 if (quiesceResults.some((result) => result.status === "rejected")) {
                     closeFailed = true;
@@ -371,6 +405,13 @@ export class GatewayService {
                 for (const messageId of [...this.messageContexts.keys()]) {
                     if (retainedQueuedMessageIds.has(messageId))
                         continue;
+                    if (this.providerDispatchInFlightMessageIds.has(messageId)) {
+                        await this.advanceDeliveryLocked(messageId, {
+                            type: "dispatch_ambiguous",
+                            at: this.now().getTime(),
+                            safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
+                        });
+                    }
                     const queued = await this.store.settleQueuedMessage({
                         messageId,
                         state: "cancelled",
@@ -428,6 +469,7 @@ export class GatewayService {
                 this.activeDispatchByTarget.clear();
                 this.scheduledDispatchTargets.clear();
                 this.dispatchRunnerTargets.clear();
+                this.providerDispatchInFlightMessageIds.clear();
                 for (const timer of this.heldRedispatchTimers.values()) {
                     this.timers.clearTimeout(timer);
                 }
@@ -592,6 +634,14 @@ export class GatewayService {
             const registry = this.registryEvidenceByConnector.get(`${connector.provider}\0${connector.host}`);
             return {
                 ...connector,
+                ...(connector.provider === "codex" &&
+                    this.codexDoctorResult !== undefined
+                    ? {
+                        codexDoctor: {
+                            conditions: this.codexDoctorConditions(connector),
+                        },
+                    }
+                    : {}),
                 ...(connector.provider !== "claude" || registry === undefined
                     ? {}
                     : {
@@ -603,6 +653,70 @@ export class GatewayService {
             };
         });
     }
+    recordConnectorFreshness(identity, health) {
+        const key = `${identity.provider}\0${identity.hostId}`;
+        if (health === "healthy") {
+            this.connectorFreshnessDeadlineAt.set(key, this.now().getTime() + CONNECTOR_OBSERVATION_STALE_AFTER_MS + 1);
+        }
+        else {
+            this.connectorFreshnessDeadlineAt.delete(key);
+        }
+    }
+    codexDoctorConditions(connector) {
+        const attachment = this.codexDoctorResult?.conditions[0] ?? "unknown";
+        const stale = connector.observationAgeMs === undefined ||
+            connector.observationAgeMs > CONNECTOR_OBSERVATION_STALE_AFTER_MS;
+        if (attachment === "split_brain" || attachment === "orphaned") {
+            return stale ? [attachment, "observation_stale"] : [attachment];
+        }
+        if (stale)
+            return ["observation_stale", attachment];
+        return [attachment];
+    }
+    async refreshCodexDoctor() {
+        if (this.codexDoctor === undefined)
+            return false;
+        const next = await this.codexDoctor().catch(() => ({ conditions: ["unknown"] }));
+        const changed = JSON.stringify(next.conditions) !==
+            JSON.stringify(this.codexDoctorResult?.conditions);
+        this.codexDoctorResult = next;
+        return changed;
+    }
+    scheduleCodexDoctor() {
+        if (!this.running ||
+            this.closing ||
+            this.codexDoctor === undefined ||
+            this.codexDoctorTimer !== undefined ||
+            this.codexDoctorInFlight !== undefined) {
+            return;
+        }
+        const timer = this.timers.setTimeout(() => {
+            if (this.codexDoctorTimer !== timer)
+                return;
+            this.codexDoctorTimer = undefined;
+            const operation = this.refreshCodexDoctor()
+                .then(async (changed) => {
+                if (!changed || this.closing)
+                    return;
+                await this.mutex.run("service", async () => {
+                    this.revision += 1;
+                    await this.publish();
+                });
+            })
+                .catch(() => {
+                this.dashboardHealthy = false;
+            });
+            this.codexDoctorInFlight = operation;
+            void operation.finally(() => {
+                if (this.codexDoctorInFlight === operation) {
+                    this.codexDoctorInFlight = undefined;
+                }
+                this.scheduleCodexDoctor();
+            });
+        }, CODEX_DOCTOR_REFRESH_MS);
+        this.codexDoctorTimer = timer;
+        timer.unref?.();
+    }
     async observeSnapshot() {
         return await this.mutex.run("service", async () => {
             const changed = await this.processLifecycleLocked();
@@ -635,7 +749,11 @@ export class GatewayService {
     fingerprintSnapshot(snapshot) {
         // Closed snapshot validation bounds every array and field before this
         // serialization. Omitting generatedAt is the sole semantic exception.
-        const { generatedAt: _generatedAt, ...semanticSnapshot } = snapshot;
+        const { generatedAt: _generatedAt, connectors, ...snapshotWithoutGeneratedAt } = snapshot;
+        const semanticSnapshot = {
+            ...snapshotWithoutGeneratedAt,
+            connectors: connectors.map(({ observationAgeMs: _observationAgeMs, ...connector }) => connector),
+        };
         const encoded = JSON.stringify(semanticSnapshot);
         if (Buffer.byteLength(encoded, "utf8") >
             GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET) {
@@ -901,10 +1019,10 @@ export class GatewayService {
             this.endpointRefreshConflictPending);
     }
     enqueueCallbackWorkerOnly() {
-        if (this.callbackScheduled)
+        if (this.callbackScheduled || this.callbackWorker !== undefined)
             return;
         this.callbackScheduled = true;
-        setImmediate(() => {
+        queueMicrotask(() => {
             this.callbackScheduled = false;
             const worker = this.mutex.run("service", async () => {
                 await this.drainCallbackQueueLocked();
@@ -2610,7 +2728,7 @@ export class GatewayService {
         return JSON.stringify({
             inboundMode: snapshot.inboundMode,
             health: snapshot.health,
-            connectors: snapshot.connectors.map(({ lastSeenAt: _lastSeenAt, ...connector }) => connector),
+            connectors: snapshot.connectors.map(({ lastSeenAt: _lastSeenAt, observationAgeMs: _observationAgeMs, ...connector }) => connector),
             availablePeers: snapshot.availablePeers.map(({ lastSeenAt: _lastSeenAt, ...peer }) => peer),
             routes: snapshot.routes.map(({ lastSeenAt: _lastSeenAt, ...route }) => route),
             messages: snapshot.messages,
@@ -2619,7 +2737,116 @@ export class GatewayService {
             truncation: snapshot.truncation,
         });
     }
-    async refreshClaudeDiscovery() {
+    schedulePeriodicClaudeDiscovery() {
+        if (this.closing ||
+            this.claudeDiscoveryScheduled ||
+            this.claudeDiscoveryInFlight !== undefined) {
+            return;
+        }
+        this.claudeDiscoveryScheduled = true;
+        queueMicrotask(() => {
+            this.claudeDiscoveryScheduled = false;
+            if (this.closing || !this.running)
+                return;
+            const operation = this.refreshClaudeDiscoveryPeriodically().catch(() => {
+                this.dashboardHealthy = false;
+            });
+            this.claudeDiscoveryInFlight = operation;
+            void operation.finally(() => {
+                if (this.claudeDiscoveryInFlight === operation) {
+                    this.claudeDiscoveryInFlight = undefined;
+                }
+            });
+        });
+    }
+    async refreshClaudeDiscoveryPeriodically() {
+        const observations = (await Promise.all(this.adapters
+            .filter((adapter) => adapter.identity.provider === "claude")
+            .map(async (adapter) => {
+            try {
+                const snapshot = await adapter.discoverClaudePeers?.();
+                return snapshot === undefined ? undefined : { adapter, snapshot };
+            }
+            catch {
+                return undefined;
+            }
+        }))).filter((item) => item !== undefined);
+        if (this.closing)
+            return;
+        const preparedRebinds = [];
+        const persisted = await this.store.inspectPrivateClaudeRoutes();
+        for (const route of persisted) {
+            if (!route.enabled || route.state !== "stale")
+                continue;
+            const observation = observations.find(({ adapter, snapshot }) => snapshot.complete &&
+                adapter.identity.hostId === route.binding.hostId);
+            if (observation === undefined)
+                continue;
+            const peers = observation.snapshot.peers.filter((peer) => peer.kind === "interactive" &&
+                PUBLIC_ALIAS.test(peer.alias) &&
+                peer.alias.endsWith(`@${observation.adapter.identity.hostId}`));
+            const candidates = peers.filter((peer) => peer.routeHandle === route.binding.routeHandle);
+            const peer = candidates[0];
+            if (candidates.length !== 1 ||
+                peer === undefined ||
+                peers.filter((item) => item.alias === peer.alias).length !== 1) {
+                continue;
+            }
+            const candidate = { ...peer, adapter: observation.adapter };
+            try {
+                this.validatePersistedClaudeCandidate(candidate, route);
+                await this.assertClaudeWorkspaceDisjoint(candidate.adapter, candidate.routeHandle);
+                const selected = await candidate.adapter.selectRoute({
+                    alias: candidate.alias,
+                    routeHandle: candidate.routeHandle,
+                });
+                if (selected.routeHandle !== candidate.routeHandle) {
+                    throw new BridgeError("ROUTE_MISMATCH", "The peer identity changed during selection.");
+                }
+                preparedRebinds.push({
+                    candidate,
+                    persisted: route,
+                    selectedState: selected.state,
+                });
+            }
+            catch {
+                await candidate.adapter.releaseRoute?.(candidate.routeHandle).catch(() => undefined);
+            }
+        }
+        const consumed = new Set();
+        try {
+            await this.mutex.run("service", async () => {
+                if (this.closing || !this.running)
+                    return;
+                const changed = await this.refreshClaudeDiscovery({
+                    incrementRevision: false,
+                    observations,
+                    preparedRebinds,
+                    consumedPreparedRebinds: consumed,
+                });
+                if (changed) {
+                    this.revision += 1;
+                    await this.publish();
+                }
+                this.scheduleLifecycleWakeLocked();
+            });
+        }
+        finally {
+            const releasable = await this.mutex.run("service", async () => preparedRebinds.filter((prepared) => {
+                if (consumed.has(prepared))
+                    return false;
+                const binding = {
+                    ...prepared.candidate.adapter.identity,
+                    routeHandle: prepared.candidate.routeHandle,
+                    ownerLease: stableLease("claude", prepared.candidate.routeHandle),
+                };
+                const alias = this.bindingAliases.get(bindingKey(binding));
+                return alias === undefined || this.routeStates.get(alias) === "stale";
+            }));
+            await Promise.allSettled(releasable.map(async (prepared) => await prepared.candidate.adapter.releaseRoute?.(prepared.candidate.routeHandle)));
+        }
+    }
+    async refreshClaudeDiscovery(options = {}) {
         const publicBefore = await this.discoveryPublicFingerprint();
         this.candidates.clear();
         const rowsByAlias = new Map();
@@ -2631,14 +2858,33 @@ export class GatewayService {
                 peers: [],
                 complete: false,
             };
+            let discoverySucceeded = false;
             try {
-                discovered = (await adapter.discoverClaudePeers?.()) ?? discovered;
+                const observed = options.observations?.find((item) => item.adapter === adapter);
+                if (observed !== undefined) {
+                    discovered = observed.snapshot;
+                    discoverySucceeded = true;
+                }
+                else if (options.observations === undefined &&
+                    adapter.discoverClaudePeers !== undefined) {
+                    discovered = await adapter.discoverClaudePeers();
+                    discoverySucceeded = true;
+                }
             }
             catch {
                 // Registry observation is dashboard evidence, not Claude mailbox
                 // authority. The provider still revalidates the exact target before
                 // any write.
             }
+            if (discoverySucceeded && discovered.complete) {
+                await this.store.observeConnector({
+                    identity: adapter.identity,
+                    health: "healthy",
+                    protocol: adapter.protocol,
+                    protocolVersion: adapter.protocolVersion,
+                });
+                this.recordConnectorFreshness(adapter.identity, "healthy");
+            }
             this.captureRegistryObservation(adapter, discovered.registry ?? adapter.latestRegistryObservation?.());
             const grouped = new Map();
             const byHandle = new Map();
@@ -2749,7 +2995,21 @@ export class GatewayService {
             const candidate = matches[0];
             if (candidate === undefined)
                 continue;
-            await this.activatePersistedClaudeCandidate(candidate, route, "peer_identity_reobserved").catch(() => undefined);
+            const prepared = options.preparedRebinds?.find((item) => item.candidate.adapter === candidate.adapter &&
+                item.candidate.routeHandle === candidate.routeHandle &&
+                item.persisted.binding.ownerLease === route.binding.ownerLease);
+            const activated = prepared === undefined
+                ? options.observations === undefined &&
+                    await this.activatePersistedClaudeCandidate(candidate, route, "peer_identity_reobserved").then(() => true, () => false)
+                : await this.commitPreparedClaudeRebind(prepared, "peer_identity_reobserved").then(() => {
+                    options.consumedPreparedRebinds?.add(prepared);
+                    return true;
+                }, () => false);
+            if (activated &&
+                this.running &&
+                this.routeStates.get(candidate.alias) === "idle") {
+                this.scheduleDispatch(candidate.alias);
+            }
         }
         const rows = [];
         for (const [alias, row] of rowsByAlias) {
@@ -2819,7 +3079,7 @@ export class GatewayService {
         }
         this.availablePeers = rows.sort((left, right) => left.alias.localeCompare(right.alias));
         const changed = publicBefore !== (await this.discoveryPublicFingerprint());
-        if (changed)
+        if (changed && options.incrementRevision !== false)
             this.revision += 1;
         return changed;
     }
@@ -2873,16 +3133,7 @@ export class GatewayService {
         return this.candidates.get(selector);
     }
     async activatePersistedClaudeCandidate(candidate, persisted, reason) {
-        const expectedLease = stableLease("claude", candidate.routeHandle);
-        if (!persisted.enabled ||
-            persisted.state !== "stale" ||
-            persisted.binding.provider !== "claude" ||
-            candidate.adapter.identity.provider !== "claude" ||
-            persisted.binding.hostId !== candidate.adapter.identity.hostId ||
-            persisted.binding.routeHandle !== candidate.routeHandle ||
-            persisted.binding.ownerLease !== expectedLease) {
-            throw new BridgeError("ROUTE_REBIND_IDENTITY_MISMATCH", "The persisted Claude selection does not match the exact live session identity.");
-        }
+        this.validatePersistedClaudeCandidate(candidate, persisted);
         await this.assertClaudeWorkspaceDisjoint(candidate.adapter, candidate.routeHandle);
         try {
             const selected = await candidate.adapter.selectRoute({
@@ -2892,23 +3143,7 @@ export class GatewayService {
             if (selected.routeHandle !== candidate.routeHandle) {
                 throw new BridgeError("ROUTE_MISMATCH", "The peer identity changed during selection.");
             }
-            const binding = {
-                ...candidate.adapter.identity,
-                routeHandle: candidate.routeHandle,
-                ownerLease: expectedLease,
-            };
-            await this.store.rebindStaleRoute({
-                alias: persisted.alias,
-                newAlias: candidate.alias,
-                currentOwnerLease: persisted.binding.ownerLease,
-                newBinding: binding,
-                reason,
-                state: selected.state,
-            });
-            if (persisted.alias !== candidate.alias) {
-                this.forgetBinding(persisted.alias);
-            }
-            this.rememberBinding(candidate.alias, binding, selected.state);
+            await this.commitPreparedClaudeRebind({ candidate, persisted, selectedState: selected.state }, reason);
         }
         catch (error) {
             await candidate.adapter.releaseRoute?.(candidate.routeHandle).catch(() => {
@@ -2917,6 +3152,44 @@ export class GatewayService {
             throw error;
         }
     }
+    validatePersistedClaudeCandidate(candidate, persisted) {
+        const expectedLease = stableLease("claude", candidate.routeHandle);
+        if (!persisted.enabled ||
+            persisted.state !== "stale" ||
+            persisted.binding.provider !== "claude" ||
+            candidate.adapter.identity.provider !== "claude" ||
+            persisted.binding.hostId !== candidate.adapter.identity.hostId ||
+            persisted.binding.routeHandle !== candidate.routeHandle ||
+            persisted.binding.ownerLease !== expectedLease) {
+            throw new BridgeError("ROUTE_REBIND_IDENTITY_MISMATCH", "The persisted Claude selection does not match the exact live session identity.");
+        }
+    }
+    async commitPreparedClaudeRebind(prepared, reason) {
+        const { candidate, selectedState } = prepared;
+        const persisted = (await this.store.inspectPrivateRoute(prepared.persisted.alias)) ??
+            (await this.store.inspectPrivateRoute(candidate.alias));
+        if (persisted === undefined) {
+            throw new BridgeError("ROUTE_REBIND_IDENTITY_MISMATCH", "The persisted Claude selection changed before re-observation committed.");
+        }
+        this.validatePersistedClaudeCandidate(candidate, persisted);
+        const binding = {
+            ...candidate.adapter.identity,
+            routeHandle: candidate.routeHandle,
+            ownerLease: stableLease("claude", candidate.routeHandle),
+        };
+        await this.store.rebindStaleRoute({
+            alias: persisted.alias,
+            newAlias: candidate.alias,
+            currentOwnerLease: persisted.binding.ownerLease,
+            newBinding: binding,
+            reason,
+            state: selectedState,
+        });
+        if (persisted.alias !== candidate.alias) {
+            this.forgetBinding(persisted.alias);
+        }
+        this.rememberBinding(candidate.alias, binding, selectedState);
+    }
     async selectClaudeCandidate(candidate, persisted) {
         if (persisted !== undefined) {
             await this.activatePersistedClaudeCandidate(candidate, persisted, "peer_explicitly_reselected");
@@ -3327,6 +3600,7 @@ export class GatewayService {
             protocol: adapter.protocol,
             protocolVersion: adapter.protocolVersion,
         });
+        this.recordConnectorFreshness(adapter.identity, "healthy");
         await this.store.observeRoute({
             binding,
             state,
@@ -3632,7 +3906,15 @@ export class GatewayService {
                     unwrittenOutcome: input.unwrittenOutcome,
                     safeErrorCode: input.safeErrorCode,
                 };
-            const transition = transitionDelivery(tracker.machine, event);
+            const stateAtTermination = tracker.pendingTerminalEvent === undefined &&
+                this.providerDispatchInFlightMessageIds.has(messageId)
+                ? transitionDelivery(tracker.machine, {
+                    type: "dispatch_ambiguous",
+                    at: observedAt,
+                    safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
+                }).state
+                : tracker.machine;
+            const transition = transitionDelivery(stateAtTermination, event);
             const settlement = transition.effects.find((effect) => effect.type === "settle_delivery");
             if (settlement === undefined) {
                 throw new BridgeError("ROUTE_TERMINATION_STATE_MISMATCH", "An affected in-flight delivery could not produce an exact terminal route settlement.", true);
@@ -3664,7 +3946,15 @@ export class GatewayService {
                     unwrittenOutcome: input.unwrittenOutcome,
                     safeErrorCode: input.safeErrorCode,
                 };
-            const transition = transitionDelivery(tracker.machine, event);
+            const stateAtTermination = tracker.pendingTerminalEvent === undefined &&
+                this.providerDispatchInFlightMessageIds.has(messageId)
+                ? transitionDelivery(tracker.machine, {
+                    type: "dispatch_ambiguous",
+                    at: observedAt,
+                    safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
+                }).state
+                : tracker.machine;
+            const transition = transitionDelivery(stateAtTermination, event);
             const settlement = transition.effects.find((effect) => effect.type === "settle_delivery");
             if (settlement === undefined) {
                 throw new BridgeError("PAIR_TERMINATION_STATE_MISMATCH", "An affected in-flight delivery could not produce an exact terminal pair settlement.", true);
@@ -4029,6 +4319,17 @@ export class GatewayService {
     async processLifecycleLocked() {
         const now = this.now().getTime();
         let changed = false;
+        if (this.nextClaudeDiscoveryAt !== undefined &&
+            this.nextClaudeDiscoveryAt <= now) {
+            this.nextClaudeDiscoveryAt = now + CLAUDE_DISCOVERY_REFRESH_MS;
+            this.schedulePeriodicClaudeDiscovery();
+        }
+        for (const [key, deadlineAt] of this.connectorFreshnessDeadlineAt) {
+            if (deadlineAt > now)
+                continue;
+            this.connectorFreshnessDeadlineAt.delete(key);
+            changed = true;
+        }
         if (await this.processProgressWatchesLocked(now))
             changed = true;
         await this.drainPreDeadlineDeliveryCallbacksLocked();
@@ -4166,6 +4467,14 @@ export class GatewayService {
         if (this.nextProgressWatchAt !== undefined) {
             consider(this.nextProgressWatchAt);
         }
+        if (this.nextClaudeDiscoveryAt !== undefined) {
+            consider(this.nextClaudeDiscoveryAt);
+        }
+        for (const deadlineAt of this.connectorFreshnessDeadlineAt.values()) {
+            consider(deadlineAt);
+        }
+        if (this.lifecyclePublishPending)
+            consider(now);
         if (hasNonterminal) {
             this.nextDashboardRefreshAt ??= now + DELIVERY_DASHBOARD_REFRESH_MS;
             consider(this.nextDashboardRefreshAt);
@@ -4181,10 +4490,21 @@ export class GatewayService {
             this.lifecycleTimer = undefined;
             void this.mutex
                 .run("service", async () => {
-                const changed = await this.processLifecycleLocked();
-                if (changed) {
-                    this.revision += 1;
-                    await this.publish();
+                try {
+                    const changed = await this.processLifecycleLocked();
+                    if (changed) {
+                        this.revision += 1;
+                        this.lifecyclePublishPending = true;
+                    }
+                    if (this.lifecyclePublishPending) {
+                        await this.publish();
+                        this.lifecyclePublishPending = false;
+                    }
+                    this.scheduleLifecycleWakeLocked();
+                }
+                catch {
+                    this.dashboardHealthy = false;
+                    this.scheduleLifecycleRetryLocked();
                 }
             })
                 .catch(() => {
@@ -4194,6 +4514,23 @@ export class GatewayService {
         this.lifecycleTimer = timer;
         timer.unref?.();
     }
+    scheduleLifecycleRetryLocked() {
+        if (!this.running || this.closing || this.lifecycleTimer !== undefined) {
+            return;
+        }
+        const timer = this.timers.setTimeout(() => {
+            if (this.lifecycleTimer !== timer)
+                return;
+            this.lifecycleTimer = undefined;
+            void this.mutex.run("service", async () => {
+                this.scheduleLifecycleWakeLocked();
+            }).catch(() => {
+                this.dashboardHealthy = false;
+            });
+        }, DELIVERY_SETTLEMENT_RETRY_MS);
+        this.lifecycleTimer = timer;
+        timer.unref?.();
+    }
     async deliveryStatus(token) {
         return await this.mutex.run("service", async () => {
             if (!DELIVERY_TOKEN.test(token))
@@ -4553,7 +4890,7 @@ export class GatewayService {
                 break;
         }
     }
-    async awaitDispatchWithNativeHeldLocked(tracker, operation) {
+    async awaitDispatchWithNativeHeld(messageId, operation) {
         const outcome = operation.then((value) => ({ kind: "result", value }), (error) => ({ kind: "error", error }));
         const unwrap = (settled) => {
             if (settled.kind === "error")
@@ -4561,7 +4898,7 @@ export class GatewayService {
             return settled.value;
         };
         while (true) {
-            const current = this.deliveryTrackers.get(tracker.messageId);
+            const current = this.deliveryTrackers.get(messageId);
             if (current === undefined ||
                 current.nativeReceipt === undefined ||
                 current.nativeHeldSent ||
@@ -4586,14 +4923,15 @@ export class GatewayService {
             }
             // A terminal callback may have arrived before the provider's dispatch
             // promise resolved. Let that exact evidence win before emitting held.
-            await this.drainDeliveryCallbacksForMessageLocked(tracker.messageId);
-            const afterCallbacks = this.deliveryTrackers.get(tracker.messageId);
-            if (afterCallbacks === undefined ||
-                isTerminalDeliveryMachine(afterCallbacks.machine) ||
-                this.now().getTime() >= afterCallbacks.deadlineAt) {
-                return unwrap(await outcome);
-            }
-            await this.publishNativeHeldLocked(afterCallbacks);
+            await this.mutex.run("service", async () => {
+                await this.drainDeliveryCallbacksForMessageLocked(messageId);
+                const afterCallbacks = this.deliveryTrackers.get(messageId);
+                if (afterCallbacks !== undefined &&
+                    !isTerminalDeliveryMachine(afterCallbacks.machine) &&
+                    this.now().getTime() < afterCallbacks.deadlineAt) {
+                    await this.publishNativeHeldLocked(afterCallbacks);
+                }
+            });
         }
     }
     restoreQueuedMessageContextLocked(item, binding, canonicalConversationId) {
@@ -4634,7 +4972,7 @@ export class GatewayService {
         });
         return context;
     }
-    async dispatchOne(targetAlias) {
+    async prepareDispatchLocked(targetAlias) {
         if (!this.running ||
             this.closing ||
             this.codexSuccessionDispatchFrozen.has(targetAlias) ||
@@ -4836,14 +5174,20 @@ export class GatewayService {
             return;
         }
         context.sourceBinding ??= { ...sourceBinding };
-        let result;
-        try {
-            result = await this.awaitDispatchWithNativeHeldLocked(tracker, this.adapter(binding.provider, binding.hostId).dispatch({
+        this.scheduleLifecycleWakeLocked();
+        return {
+            targetAlias,
+            messageId: item.messageId,
+            body: item.body,
+            binding: { ...binding },
+            authorization: context.authorization,
+            steeringWhileBusy,
+            input: {
                 sourceAlias: item.sourceAlias,
                 sourceProvider: sourceBinding.provider,
                 targetAlias: item.targetAlias,
                 conversationId: context.conversationId,
-                binding,
+                binding: { ...binding },
                 authorization: context.authorization,
                 messageId: item.messageId,
                 text: item.body,
@@ -4853,21 +5197,43 @@ export class GatewayService {
                 ...(item.steer === true && item.queuedAhead !== undefined
                     ? { queuedAhead: item.queuedAhead }
                     : {}),
-                ...(progressWatchActive
-                    ? { progressWatchActive: true }
-                    : {}),
-            }));
+                ...(progressWatchActive ? { progressWatchActive: true } : {}),
+            },
+        };
+    }
+    async commitDispatchLocked(prepared, outcome) {
+        const { targetAlias, messageId, body, binding, authorization, steeringWhileBusy, } = prepared;
+        await this.drainDeliveryCallbacksForMessageLocked(messageId);
+        if (await this.processLifecycleLocked()) {
+            await this.changed();
         }
-        catch {
-            await this.drainDeliveryCallbacksForMessageLocked(item.messageId);
-            if (await this.processLifecycleLocked()) {
-                await this.changed();
-            }
-            if (!this.messageContexts.has(item.messageId)) {
-                this.scheduleDispatch(this.bindingAliases.get(bindingKey(binding)) ?? targetAlias);
-                return;
-            }
-            await this.advanceDeliveryLocked(item.messageId, {
+        const context = this.messageContexts.get(messageId);
+        const tracker = this.deliveryTrackers.get(messageId);
+        if (context === undefined || tracker === undefined) {
+            this.scheduleDispatch(this.bindingAliases.get(bindingKey(binding)) ?? targetAlias);
+            return;
+        }
+        const currentTargetAlias = this.bindingAliases.get(context.targetBindingKey) ??
+            this.bindingAliases.get(bindingKey(binding)) ??
+            targetAlias;
+        const currentSelectedBinding = authorization === "selected_route"
+            ? this.routeBindings.get(currentTargetAlias)
+            : undefined;
+        const currentSelectedRoute = authorization === "selected_route"
+            ? await this.store.inspectPrivateRoute(currentTargetAlias)
+            : undefined;
+        const authorityStillCurrent = !(context.authorization !== authorization ||
+            context.targetBindingKey !== bindingKey(binding) ||
+            (authorization === "selected_route" &&
+                (currentSelectedBinding === undefined ||
+                    bindingKey(currentSelectedBinding) !== bindingKey(binding) ||
+                    currentSelectedRoute === undefined ||
+                    !currentSelectedRoute.enabled ||
+                    currentSelectedRoute.state === "stale" ||
+                    bindingKey(currentSelectedRoute.binding) !== bindingKey(binding) ||
+                    this.routeStates.get(currentTargetAlias) === "stale")));
+        if (outcome.kind === "error") {
+            await this.advanceDeliveryLocked(messageId, {
                 type: "dispatch_ambiguous",
                 at: this.now().getTime(),
                 safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
@@ -4876,16 +5242,8 @@ export class GatewayService {
             this.scheduleDispatch(this.bindingAliases.get(bindingKey(binding)) ?? targetAlias);
             return;
         }
-        await this.drainDeliveryCallbacksForMessageLocked(item.messageId);
-        if (await this.processLifecycleLocked()) {
-            await this.changed();
-        }
-        if (!this.messageContexts.has(item.messageId)) {
-            this.scheduleDispatch(this.bindingAliases.get(bindingKey(binding)) ?? targetAlias);
-            return;
-        }
+        const result = outcome.result;
         if (result.state === "deferred") {
-            const currentTargetAlias = this.bindingAliases.get(bindingKey(binding)) ?? targetAlias;
             const now = this.now().getTime();
             const deferredSafeErrorCode = safeCode(result.safeErrorCode, "PROVIDER_DISPATCH_DEFERRED");
             const retryDelayMs = binding.provider === "claude"
@@ -4897,14 +5255,14 @@ export class GatewayService {
             const retryAt = binding.provider === "claude"
                 ? Math.min(now + retryDelayMs, tracker.deadlineAt - 1)
                 : now + retryDelayMs;
-            await this.advanceDeliveryLocked(item.messageId, {
+            await this.advanceDeliveryLocked(messageId, {
                 type: "dispatch_clean_prewrite_failed",
                 at: now,
                 retryAt,
                 safeErrorCode: deferredSafeErrorCode,
             });
             tracker.deliverySafeErrorCode = deferredSafeErrorCode;
-            const postDeferred = this.deliveryTrackers.get(item.messageId)?.machine;
+            const postDeferred = this.deliveryTrackers.get(messageId)?.machine;
             if (postDeferred === undefined ||
                 isTerminalDeliveryMachine(postDeferred)) {
                 await this.changed();
@@ -4915,19 +5273,20 @@ export class GatewayService {
             // evidence. Only the reducer's explicit queued retry phase may return
             // the body to the store queue.
             if (postDeferred.phase !== "queued") {
-                await this.advanceDeliveryLocked(item.messageId, {
+                await this.advanceDeliveryLocked(messageId, {
                     type: "await_terminal",
                     at: this.now().getTime(),
                 });
                 await this.changed();
                 return;
             }
-            const requeued = await this.store.requeueInFlightMessage(item.messageId, item.body, deferredSafeErrorCode);
-            if (this.activeDispatchByTarget.get(currentTargetAlias) === item.messageId) {
+            const requeued = await this.store.requeueInFlightMessage(messageId, body, deferredSafeErrorCode);
+            if (this.activeDispatchByTarget.get(currentTargetAlias) === messageId) {
                 this.activeDispatchByTarget.delete(currentTargetAlias);
             }
             if (requeued.status === "requeued") {
-                if (context.authorization === "selected_route") {
+                if (context.authorization === "selected_route" &&
+                    authorityStillCurrent) {
                     if (binding.provider === "codex" && !steeringWhileBusy) {
                         this.routeStates.set(currentTargetAlias, "idle");
                         await this.store.observeRoute({
@@ -4940,6 +5299,7 @@ export class GatewayService {
                     }
                     await this.setNativeSourceStatus(currentTargetAlias, "waiting");
                 }
+                await this.publishNativeHeldLocked(tracker);
             }
             else if (requeued.status === "settled") {
                 await this.applyTerminalSettlementLocked(requeued.settlement);
@@ -4947,20 +5307,30 @@ export class GatewayService {
             await this.changed();
             return;
         }
+        if (!authorityStillCurrent) {
+            await this.advanceDeliveryLocked(messageId, {
+                type: "dispatch_ambiguous",
+                at: this.now().getTime(),
+                safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
+            });
+            await this.changed();
+            this.scheduleDispatch(currentTargetAlias);
+            return;
+        }
         if (result.state === "pending" || result.state === "accepted") {
             if (result.state === "accepted" &&
-                (await this.acceptProviderDeliveryLocked(item.messageId))) {
+                (await this.acceptProviderDeliveryLocked(messageId))) {
                 await this.changed();
             }
             else if (result.state === "pending") {
-                await this.advanceDeliveryLocked(item.messageId, {
+                await this.advanceDeliveryLocked(messageId, {
                     type: "await_terminal",
                     at: this.now().getTime(),
                 });
             }
         }
         else {
-            await this.finishDelivery({ messageId: item.messageId, state: result.state, ...(result.safeErrorCode === undefined ? {} : { safeErrorCode: result.safeErrorCode }), ...(result.replyText === undefined ? {} : { replyText: result.replyText }) });
+            await this.finishDelivery({ messageId, state: result.state, ...(result.safeErrorCode === undefined ? {} : { safeErrorCode: result.safeErrorCode }), ...(result.replyText === undefined ? {} : { replyText: result.replyText }) });
         }
         this.scheduleDispatch(this.bindingAliases.get(bindingKey(binding)) ?? targetAlias);
     }
@@ -4974,27 +5344,100 @@ export class GatewayService {
             return;
         this.scheduledDispatchTargets.add(targetAlias);
         setImmediate(() => {
-            this.mutex
-                .run("service", async () => {
+            void this.runDispatch(targetAlias).catch(() => {
+                this.dashboardHealthy = false;
+            });
+        });
+    }
+    async runDispatch(targetAlias) {
+        let runnerStarted = false;
+        let initialScheduleConsumed = false;
+        let preparedMessageId;
+        let commitCompleted = false;
+        try {
+            const prepared = await this.mutex.run("service", async () => {
                 this.scheduledDispatchTargets.delete(targetAlias);
+                initialScheduleConsumed = true;
                 if (this.closing ||
                     this.codexSuccessionDispatchFrozen.has(targetAlias) ||
                     this.codexSuccessionPoisoned.has(targetAlias)) {
                     return;
                 }
                 this.dispatchRunnerTargets.add(targetAlias);
-                try {
-                    await this.dispatchOne(targetAlias);
-                }
-                finally {
+                runnerStarted = true;
+                const candidate = await this.prepareDispatchLocked(targetAlias);
+                if (candidate === undefined) {
                     this.dispatchRunnerTargets.delete(targetAlias);
                     this.scheduleLifecycleWakeLocked();
+                    runnerStarted = false;
                 }
-            })
-                .catch(() => {
-                this.dashboardHealthy = false;
+                else {
+                    preparedMessageId = candidate.messageId;
+                    this.providerDispatchInFlightMessageIds.add(candidate.messageId);
+                }
+                return candidate;
             });
-        });
+            if (prepared === undefined)
+                return;
+            let outcome;
+            try {
+                const adapter = this.adapter(prepared.binding.provider, prepared.binding.hostId);
+                outcome = {
+                    kind: "result",
+                    result: await this.awaitDispatchWithNativeHeld(prepared.messageId, adapter.dispatch(prepared.input)),
+                };
+            }
+            catch {
+                outcome = { kind: "error" };
+            }
+            await this.mutex.run("service", async () => {
+                await this.commitDispatchLocked(prepared, outcome);
+                commitCompleted = true;
+                this.providerDispatchInFlightMessageIds.delete(prepared.messageId);
+                preparedMessageId = undefined;
+                this.dispatchRunnerTargets.delete(targetAlias);
+                runnerStarted = false;
+                this.scheduleLifecycleWakeLocked();
+            });
+        }
+        finally {
+            await this.mutex.run("service", async () => {
+                if (preparedMessageId !== undefined) {
+                    let releaseUncertaintyMarker = commitCompleted;
+                    if (!commitCompleted) {
+                        const tracker = this.deliveryTrackers.get(preparedMessageId);
+                        if (tracker !== undefined &&
+                            !isTerminalDeliveryMachine(tracker.machine)) {
+                            try {
+                                await this.advanceDeliveryLocked(preparedMessageId, {
+                                    type: "dispatch_ambiguous",
+                                    at: this.now().getTime(),
+                                    safeErrorCode: "DISPATCH_OUTCOME_AMBIGUOUS",
+                                });
+                                await this.changed();
+                                releaseUncertaintyMarker = true;
+                            }
+                            catch {
+                                this.dashboardHealthy = false;
+                            }
+                        }
+                        else {
+                            releaseUncertaintyMarker = true;
+                        }
+                    }
+                    if (releaseUncertaintyMarker) {
+                        this.providerDispatchInFlightMessageIds.delete(preparedMessageId);
+                    }
+                }
+                if (runnerStarted) {
+                    this.dispatchRunnerTargets.delete(targetAlias);
+                }
+                if (!initialScheduleConsumed) {
+                    this.scheduledDispatchTargets.delete(targetAlias);
+                }
+                this.scheduleLifecycleWakeLocked();
+            });
+        }
     }
     scheduleHeldRedispatch(targetAlias) {
         if (this.closing || this.heldRedispatchTimers.has(targetAlias))
@@ -5316,12 +5759,16 @@ export class GatewayService {
             });
             await this.changed();
             await this.setNativeSourceStatus(event.targetAlias, "waiting");
-            // Native ingress gets one immediate dispatch opportunity. Only an
-            // actual queued/waiting result earns a `held` acknowledgement; an idle
-            // fast path can therefore settle with one terminal acknowledgement.
-            await this.dispatchOne(event.targetAlias);
+            // Provider I/O runs outside the service mutex. The lifecycle timer emits
+            // `held` only if this exact body remains nonterminal at its prompt
+            // boundary; a fast provider result therefore still produces one
+            // terminal acknowledgement and never freezes control-plane callbacks.
+            this.scheduleDispatch(event.targetAlias);
             const tracker = this.deliveryTrackers.get(queued.messageId);
-            if (tracker?.machine.phase === "queued") {
+            const routeState = this.routeStates.get(event.targetAlias);
+            if (tracker?.machine.phase === "queued" &&
+                routeState !== "idle" &&
+                (!steer || routeState !== "busy")) {
                 await this.publishNativeHeldLocked(tracker);
             }
         }
@@ -5462,6 +5909,7 @@ export class GatewayService {
             protocol: adapter.protocol,
             protocolVersion: adapter.protocolVersion,
         });
+        this.recordConnectorFreshness(event.current, "healthy");
         const refreshedByHandle = new Map(event.routes.map((route) => [route.routeHandle, route.state]));
         const pendingReanchors = previousRoutes.flatMap((route) => {
             const state = refreshedByHandle.get(route.binding.routeHandle);
@@ -5744,6 +6192,7 @@ export class GatewayService {
                     safeErrorCode: safeCode(event.safeErrorCode, "CONNECTOR_DEGRADED"),
                 }),
         });
+        this.recordConnectorFreshness(source, event.state === "stale" ? "degraded" : "healthy");
         if (event.state === "stale") {
             if (previousState !== "stale") {
                 this.addRuntimeAlert(staleSafeCode, "error", { provider: binding.provider, host: binding.hostId, alias });