agent-embassy 1.4.0 → 1.5.0

package/dist/src/gateway/providers.js

@@ -1,14 +1,14 @@
-import { createHash } from "node:crypto";
 import path from "node:path";
 import { BridgeError } from "../errors.js";
 import { CLAUDE_PEER_COMPATIBILITY, ClaudePeerAdapter, } from "./claude-peer.js";
-import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, sharesCompatibilityMajor, } from "./compatibility.js";
+import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, isCompatibilityAttestation, isCompatibilityVersion, sharesCompatibilityMajor, UNKNOWN_COMPATIBILITY_VERSION, } from "./compatibility.js";
 import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, } from "./codex-app-server.js";
 import { LocalCodexTransportError } from "./codex-local-transport.js";
 import { ClaudeNativeHelperSupervisor, } from "./claude-helper-supervisor.js";
 import { isDashboardLocale } from "./locale.js";
 import { composeProvenanceEnvelope } from "./provenance-envelope.js";
 const LOCAL_HOST = "this-mac";
+const STABLE_CLAUDE_ENDPOINT_GENERATION = "claude_local_endpoint";
 const NATIVE_CLAUDE_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 const PUBLIC_ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
 const OPAQUE_ROUTE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
@@ -30,6 +30,27 @@ const CLAUDE_CLEAN_PREWRITE_RETRY_CODES = new Set([
     "CLAUDE_PEER_TARGET_CHANGED",
     "CLAUDE_PEER_WORKSPACE_UNATTESTED",
 ]);
+const CODEX_TRUST_FAILURE_CODES = new Set([
+    "HOME_INVALID",
+    "MANAGED_CODEX_INVALID",
+    "LOCAL_APP_SERVER_ENDPOINT_UNSAFE",
+    "APP_SERVER_VERSION_MISMATCH",
+    "ENDPOINT_GENERATION_CHANGED",
+    "CLEANUP_FAILED",
+    "FACTORY_CLOSED",
+    "INVALID_CONFIGURATION",
+    "CODEX_ROUTE_CLEANUP_FAILED",
+    "CODEX_PROVIDER_CLEANUP_FAILED",
+    "CODEX_PROVIDER_CLEANUP_AMBIGUOUS",
+    "CODEX_PROVIDER_CLEANUP_TIMEOUT",
+]);
+function isCodexTrustFailure(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        CODEX_TRUST_FAILURE_CODES.has(error.code));
+}
 function claudeCleanPrewriteResult(error) {
     if (error instanceof BridgeError &&
         error.code === "CLAUDE_PEER_MESSAGE_EXPIRED") {
@@ -105,33 +126,184 @@ function invokeCallback(operation) {
     }
 }
 function validateAttestedClaudeRuntime(runtime) {
-    if (runtime.claudeCodeVersion !==
-        CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion ||
-        [
-            runtime.claudeExecutable,
-            runtime.sessionsDir,
-            runtime.socketDir,
-        ].some((value) => !path.isAbsolute(value) ||
-            path.normalize(value) !== value ||
-            value.includes("\0"))) {
-        throw new BridgeError("CLAUDE_RUNTIME_ATTESTATION_INVALID", "The local Claude provider requires exact pinned runtime evidence.");
-    }
+    if (runtime.versionEvidenceFailure !== undefined) {
+        throw new BridgeError(runtime.versionEvidenceFailure, "The local Claude provider requires bounded, internally consistent runtime version evidence.");
+    }
+    const majorEvidence = runtime.claudeCodeVersion === UNKNOWN_COMPATIBILITY_VERSION
+        ? runtime.launcherVersionEvidence
+        : runtime.claudeCodeVersion;
+    if (majorEvidence === undefined ||
+        !sharesCompatibilityMajor(majorEvidence, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion)) {
+        throw new BridgeError(majorEvidence === undefined
+            ? "CLAUDE_VERSION_UNPARSEABLE"
+            : "CLAUDE_PEER_VERSION_UNSUPPORTED", "The local Claude provider requires a positively observed supported runtime major.");
+    }
+    validateClaudeRuntimePathEvidence(runtime);
 }
-function claudeEndpointGeneration(runtime) {
-    return `claude_${createHash("sha256")
-        .update(runtime.claudeCodeVersion)
-        .update("\0")
-        .update(runtime.claudeExecutable)
-        .update("\0")
-        .update(runtime.sessionsDir)
-        .update("\0")
-        .update(runtime.socketDir)
-        .digest("hex")
-        .slice(0, 32)}`;
+function validateClaudeRuntimePathEvidence(runtime) {
+    if ([
+        runtime.claudeExecutable,
+        runtime.sessionsDir,
+        runtime.socketDir,
+    ].some((value) => !path.isAbsolute(value) ||
+        path.normalize(value) !== value ||
+        value.includes("\0"))) {
+        throw new BridgeError("CLAUDE_RUNTIME_ATTESTATION_INVALID", "The local Claude provider requires bounded absolute runtime evidence.");
+    }
 }
 function claudeRouteState(peer) {
     return peer.status === "idle" ? "idle" : "busy";
 }
+function claudeRegistryObservation(discovery) {
+    const rejected = Object.entries(discovery.rejected)
+        .filter((entry) => Number.isSafeInteger(entry[1]) && entry[1] > 0)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([safeErrorCode, count]) => Object.freeze({ safeErrorCode, count }));
+    return Object.freeze({
+        entriesScanned: discovery.entriesScanned,
+        parseableRecords: discovery.parseableRecords,
+        rejected: Object.freeze(rejected),
+    });
+}
+function unavailableClaudeRegistryObservation() {
+    return Object.freeze({
+        entriesScanned: 0,
+        parseableRecords: 0,
+        rejected: Object.freeze([
+            Object.freeze({
+                safeErrorCode: "CLAUDE_REGISTRY_UNAVAILABLE",
+                count: 1,
+            }),
+        ]),
+    });
+}
+function isClaudeRegistryAvailabilityError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return false;
+    }
+    return (error.code === "ENOENT" ||
+        error.code === "EACCES" ||
+        error.code === "EPERM" ||
+        error.code === "UNSAFE_PEER_DIRECTORY");
+}
+/**
+ * A bounded observation-only surface for an installed provider generation
+ * whose protocol cannot be used safely. It deliberately performs no provider
+ * discovery, listener construction, route selection, or message write.
+ */
+export class IncompatibleGatewayProvider {
+    identity;
+    protocol = "not-attested";
+    protocolVersion = "unknown";
+    version;
+    probes;
+    safeErrorCode;
+    initialized = false;
+    closed = false;
+    constructor(options) {
+        const attestation = evaluateCompatibilityAttestation({
+            surface: options.identity.provider,
+            version: options.version,
+            checkedAt: "2000-01-01T00:00:00.000Z",
+            certifiedVersions: certifiedCompatibilityVersions[options.identity.provider],
+            probes: options.probes,
+        });
+        if (attestation.tier !== "incompatible" ||
+            attestation.safeErrorCode !== options.safeErrorCode) {
+            throw new BridgeError("INCOMPATIBLE_PROVIDER_EVIDENCE_INVALID", "A disabled provider requires exact bounded incompatibility evidence.");
+        }
+        exactLocalHost(options.identity.hostId);
+        this.identity = Object.freeze({ ...options.identity });
+        this.version = options.version;
+        this.probes = Object.freeze(options.probes.map((probe) => Object.freeze({ ...probe })));
+        this.safeErrorCode = options.safeErrorCode;
+    }
+    compatibilitySurface() {
+        return { surface: this.identity.provider, version: this.version };
+    }
+    async runCompatibilityProbes() {
+        return this.probes;
+    }
+    acceptCompatibilityAttestation(attestation) {
+        if (!isCompatibilityAttestation(attestation) ||
+            attestation.surface !== this.identity.provider ||
+            attestation.version !== this.version ||
+            attestation.tier !== "incompatible" ||
+            attestation.safeErrorCode !== this.safeErrorCode ||
+            attestation.probes.length !== this.probes.length ||
+            attestation.probes.some((probe, index) => probe.name !== this.probes[index]?.name ||
+                probe.outcome !== this.probes[index]?.outcome ||
+                probe.safeErrorCode !== this.probes[index]?.safeErrorCode)) {
+            throw new BridgeError("INCOMPATIBLE_PROVIDER_ATTESTATION_MISMATCH", "The compatibility attestation does not match this disabled provider surface.");
+        }
+    }
+    async initialize(_callbacks) {
+        if (this.closed || this.initialized) {
+            throw new BridgeError("INCOMPATIBLE_PROVIDER_UNAVAILABLE", "The disabled provider surface cannot be initialized again.");
+        }
+        this.initialized = true;
+        return {
+            health: "degraded",
+            compatibility: "incompatible",
+            safeErrorCode: this.safeErrorCode,
+        };
+    }
+    async discoverClaudePeers() {
+        throw this.unavailable();
+    }
+    async selectRoute(_input) {
+        throw this.unavailable();
+    }
+    async assertWorkspaceDisjoint(_routeHandle, _stateRoot) {
+        throw this.unavailable();
+    }
+    async resolveReplyAddress(_address) {
+        throw this.unavailable();
+    }
+    async advertiseNativeCodexPeer(_input) {
+        throw this.unavailable();
+    }
+    async dispatch(_input) {
+        throw this.unavailable();
+    }
+    async releaseRoute(_routeHandle) { }
+    async close() {
+        this.closed = true;
+    }
+    unavailable() {
+        return new BridgeError(this.safeErrorCode, "This provider surface is observation-only because its compatibility boundary did not pass.");
+    }
+}
+export function createIncompatibleClaudeGatewayProvider(options) {
+    validateClaudeRuntimePathEvidence(options.runtime);
+    const [launcher, version, ...unobserved] = compatibilityProbeNames.claude;
+    return new IncompatibleGatewayProvider({
+        identity: {
+            provider: "claude",
+            hostId: LOCAL_HOST,
+            endpointGeneration: STABLE_CLAUDE_ENDPOINT_GENERATION,
+        },
+        version: options.version,
+        probes: [
+            passedProbe(launcher),
+            failedProbe(version, options.safeErrorCode),
+            ...unobserved.map((name) => failedProbe(name, options.safeErrorCode)),
+        ],
+        safeErrorCode: options.safeErrorCode,
+    });
+}
+export function createIncompatibleCodexGatewayProvider(options) {
+    const [installation, ...unobserved] = compatibilityProbeNames.codex;
+    return new IncompatibleGatewayProvider({
+        identity: options.identity,
+        version: options.version,
+        probes: [
+            passedProbe(installation),
+            ...unobserved.map((name) => failedProbe(name, options.safeErrorCode)),
+        ],
+        safeErrorCode: options.safeErrorCode,
+    });
+}
 export class LocalClaudeGatewayProvider {
     identity;
     protocol = "claude-peer";
@@ -165,6 +337,7 @@ export class LocalClaudeGatewayProvider {
     /** Provider-owned terminal rejections that never enter the service queue. */
     rejectedNativeInbound = new Map();
     discoveryInFlight;
+    registryObservation;
     monitorTimer;
     /** Invocation-ordered registry mutations; the tail itself never rejects. */
     nativeCodexRegistrationTail = Promise.resolve();
@@ -175,10 +348,25 @@ export class LocalClaudeGatewayProvider {
     retiredNativeCodexListener;
     /** Fences discovery callbacks and monitor restarts across listener rotation. */
     nativeCodexSuccessionFreeze;
+    /** A completed failed probe set fences every authority-bearing operation. */
+    compatibilityBlocked = false;
+    compatibilityFailureCode;
     initialized = false;
     closed = false;
     constructor(options) {
         validateAttestedClaudeRuntime(options.runtime);
+        const compatibilityVersion = options.compatibilityVersion ??
+            (options.runtime.claudeCodeVersion === UNKNOWN_COMPATIBILITY_VERSION
+                ? options.runtime.launcherVersionEvidence
+                : options.runtime.claudeCodeVersion);
+        if (compatibilityVersion === undefined ||
+            !isCompatibilityVersion(compatibilityVersion) ||
+            (compatibilityVersion !== options.runtime.claudeCodeVersion &&
+                !(options.runtime.claudeCodeVersion ===
+                    UNKNOWN_COMPATIBILITY_VERSION &&
+                    options.runtime.launcherVersionEvidence === compatibilityVersion))) {
+            throw new BridgeError("CLAUDE_RUNTIME_ATTESTATION_INVALID", "Claude compatibility classification requires exact bounded launcher evidence.");
+        }
         if (options.locale !== undefined && !isDashboardLocale(options.locale)) {
             throw new BridgeError("DASHBOARD_LOCALE_UNSUPPORTED", "The Claude provider notice locale is unsupported.");
         }
@@ -186,12 +374,20 @@ export class LocalClaudeGatewayProvider {
         this.identity = {
             provider: "claude",
             hostId,
-            endpointGeneration: claudeEndpointGeneration(options.runtime),
+            endpointGeneration: STABLE_CLAUDE_ENDPOINT_GENERATION,
         };
-        this.runtimeVersion = options.runtime.claudeCodeVersion;
+        this.runtimeVersion = compatibilityVersion;
         this.maxPending = positiveBounded(options.maxPendingMessages, MAX_CLAUDE_PENDING, 4_096);
         this.discoveryPollMs = positiveBounded(options.discoveryPollMs, DEFAULT_CLAUDE_DISCOVERY_POLL_MS, 30_000);
         this.now = options.now ?? Date.now;
+        const protocolRuntime = {
+            claudeExecutable: options.runtime.claudeExecutable,
+            claudeCodeVersion: options.runtime.claudeCodeVersion === UNKNOWN_COMPATIBILITY_VERSION
+                ? options.runtime.launcherVersionEvidence
+                : options.runtime.claudeCodeVersion,
+            sessionsDir: options.runtime.sessionsDir,
+            socketDir: options.runtime.socketDir,
+        };
         this.peer = (options.peerFactory ??
             ((runtime, locale, deliveryNotices) => new ClaudePeerAdapter({
                 sessionsDir: runtime.sessionsDir,
@@ -199,18 +395,18 @@ export class LocalClaudeGatewayProvider {
                 attestedClaudeCodeVersion: runtime.claudeCodeVersion,
                 locale,
                 deliveryNotices,
-            })))(options.runtime, options.locale ?? "en", options.deliveryNotices ?? "merged");
+            })))(protocolRuntime, options.locale ?? "en", options.deliveryNotices ?? "merged");
         this.nativeHelpers =
             options.nativeHelpers === undefined
                 ? undefined
                 : new ClaudeNativeHelperSupervisor({
                     identity: this.identity,
-                    runtime: options.runtime,
+                    runtime: protocolRuntime,
                     locale: options.locale ?? "en",
                     deliveryNotices: options.deliveryNotices ?? "merged",
                     maxPendingMessages: this.maxPending,
                     maxHelpers: positiveBounded(options.nativeHelpers.maxHelpers, 256, 128),
-                    callbacks: () => this.callbacks,
+                    callbacks: () => this.compatibilityBlocked ? undefined : this.callbacks,
                     ...(options.nativeHelpers.factory === undefined
                         ? {}
                         : { factory: options.nativeHelpers.factory }),
@@ -223,33 +419,49 @@ export class LocalClaudeGatewayProvider {
         const [launcher, version, registry, socket, protocol] = compatibilityProbeNames.claude;
         try {
             const discovery = await this.peer.discover();
-            // Runtime discovery is deliberately per-record fail-safe: malformed,
-            // dead, unsafe, or non-routable records are omitted rather than allowed
-            // to poison the whole registry. Startup compatibility must use the same
-            // boundary. Fail only when the bounded scan itself is incomplete, or a
-            // nonempty registry contains no record with a parseable closed schema.
-            const registryUnusable = discovery.truncated ||
-                (discovery.entriesScanned > 0 && discovery.parseableRecords === 0);
+            this.registryObservation = claudeRegistryObservation(discovery);
             return [
                 passedProbe(launcher),
                 passedProbe(version),
-                registryUnusable
-                    ? failedProbe(registry, "CLAUDE_REGISTRY_SCHEMA_REJECTED")
-                    : passedProbe(registry),
+                passedProbe(registry),
                 passedProbe(socket),
                 passedProbe(protocol),
             ];
         }
-        catch {
+        catch (error) {
+            if (!isClaudeRegistryAvailabilityError(error))
+                throw error;
+            this.registryObservation = unavailableClaudeRegistryObservation();
+            // A missing or unreadable registry is provider-local incompatibility:
+            // keep the broker and the other surface alive, but fence this provider
+            // before listener construction can turn the same missing path into a
+            // broker-wide startup failure.
             return [
                 passedProbe(launcher),
                 passedProbe(version),
                 failedProbe(registry, "CLAUDE_REGISTRY_UNAVAILABLE"),
-                failedProbe(socket, "CLAUDE_SOCKET_VALIDATION_UNAVAILABLE"),
+                failedProbe(socket, "CLAUDE_REGISTRY_UNAVAILABLE"),
                 passedProbe(protocol),
             ];
         }
     }
+    latestRegistryObservation() {
+        return this.registryObservation;
+    }
+    acceptCompatibilityAttestation(attestation) {
+        if (!isCompatibilityAttestation(attestation) ||
+            attestation.surface !== "claude" ||
+            attestation.version !== this.runtimeVersion) {
+            throw new BridgeError("CLAUDE_COMPATIBILITY_ATTESTATION_MISMATCH", "The Claude compatibility attestation does not match this runtime.");
+        }
+        this.compatibilityBlocked = attestation.tier === "incompatible";
+        this.compatibilityFailureCode = attestation.safeErrorCode;
+        if (this.compatibilityBlocked) {
+            if (this.monitorTimer !== undefined)
+                clearTimeout(this.monitorTimer);
+            this.monitorTimer = undefined;
+        }
+    }
     async initialize(callbacks) {
         if (this.closed) {
             throw new BridgeError("CLAUDE_PROVIDER_CLOSED", "The local Claude provider is closed.");
@@ -258,6 +470,14 @@ export class LocalClaudeGatewayProvider {
             throw new BridgeError("CLAUDE_PROVIDER_ALREADY_INITIALIZED", "The local Claude provider can be initialized only once.");
         }
         this.callbacks = callbacks;
+        if (this.compatibilityBlocked) {
+            this.initialized = true;
+            return {
+                health: "degraded",
+                compatibility: "incompatible",
+                safeErrorCode: this.compatibilityFailureCode ?? "CLAUDE_COMPATIBILITY_CHECK_FAILED",
+            };
+        }
         if (this.nativeHelpers !== undefined) {
             this.initialized = true;
             return { health: "healthy", compatibility: "compatible" };
@@ -297,8 +517,24 @@ export class LocalClaudeGatewayProvider {
             this.initialized = true;
             return { health: "healthy", compatibility: "compatible" };
         }
-        catch {
+        catch (error) {
+            if (error instanceof BridgeError &&
+                error.code === "UNSAFE_PEER_DIRECTORY") {
+                this.compatibilityBlocked = true;
+                this.compatibilityFailureCode = "CLAUDE_REGISTRY_UNAVAILABLE";
+                this.registryObservation = unavailableClaudeRegistryObservation();
+                this.initialized = true;
+                return {
+                    health: "degraded",
+                    compatibility: "incompatible",
+                    safeErrorCode: "CLAUDE_REGISTRY_UNAVAILABLE",
+                };
+            }
             this.callbacks = undefined;
+            if (error instanceof BridgeError &&
+                error.code === "CLAUDE_PEER_CALLBACK_UNSAFE") {
+                throw error;
+            }
             throw new BridgeError("CLAUDE_CALLBACK_UNAVAILABLE", "The private Claude callback listener could not be established.");
         }
     }
@@ -769,6 +1005,12 @@ export class LocalClaudeGatewayProvider {
         active.inboundQuiesced = true;
     }
     async dispatch(input) {
+        if (this.compatibilityBlocked) {
+            return {
+                state: "failed",
+                safeErrorCode: this.compatibilityFailureCode ?? "CLAUDE_COMPATIBILITY_CHECK_FAILED",
+            };
+        }
         if (this.nativeHelpers !== undefined) {
             if (input.sourceAlias === undefined ||
                 !this.initialized ||
@@ -1050,7 +1292,7 @@ export class LocalClaudeGatewayProvider {
         }
     }
     assertReady() {
-        if (!this.initialized || this.closed) {
+        if (!this.initialized || this.closed || this.compatibilityBlocked) {
             throw new BridgeError("CLAUDE_PROVIDER_UNAVAILABLE", "The local Claude provider is not available.", true);
         }
     }
@@ -1109,7 +1351,8 @@ export class LocalClaudeGatewayProvider {
                 await this.rejectNativeInboundReceipt(listenerGeneration, message.receiptHandle, diagnosticCode);
             }
         };
-        if (this.closed ||
+        if (this.compatibilityBlocked ||
+            this.closed ||
             listenerGeneration.listener.closed ||
             !this.ownsNativeCodexListener(listenerGeneration)) {
             try {
@@ -1433,13 +1676,21 @@ export class LocalClaudeGatewayProvider {
             dispatchEpochAtStart.set(routeHandle, this.selectedDispatchEpoch.get(routeHandle) ?? 0);
         }
         const pendingAtStart = new Set(this.pendingTargetByGatewayId.values());
-        const discovery = await this.peer.discover();
+        let discovery;
+        try {
+            discovery = await this.peer.discover();
+        }
+        catch (error) {
+            this.registryObservation = unavailableClaudeRegistryObservation();
+            throw error;
+        }
+        const registry = claudeRegistryObservation(discovery);
+        this.registryObservation = registry;
         this.discovered.clear();
         const rows = [];
         for (const peer of discovery.peers) {
             if (peer.kind !== "interactive" ||
-                !NATIVE_CLAUDE_NAME.test(peer.alias) ||
-                peer.alias.startsWith("codex-")) {
+                !NATIVE_CLAUDE_NAME.test(peer.alias)) {
                 continue;
             }
             const alias = `${peer.alias}@${this.identity.hostId}`;
@@ -1480,7 +1731,7 @@ export class LocalClaudeGatewayProvider {
                 this.emitClaudeRouteObservation(routeHandle, row.state, undefined, true);
             }
         }
-        return { peers: rows, complete: !discovery.truncated };
+        return { peers: rows, complete: !discovery.truncated, registry };
     }
     emitClaudeRouteObservation(routeHandle, state, safeErrorCode, authoritative = false) {
         if (this.nativeCodexSuccessionFreeze !== undefined)
@@ -1540,33 +1791,52 @@ export class LocalClaudeGatewayProvider {
 export function createLocalClaudeGatewayProvider(options) {
     return new LocalClaudeGatewayProvider(options);
 }
-function validateCodexFactory(factory) {
+function codexVersionFailureCode(version) {
+    if (version === UNKNOWN_COMPATIBILITY_VERSION) {
+        return "CODEX_APP_SERVER_VERSION_UNPARSEABLE";
+    }
+    if (!isCompatibilityVersion(version)) {
+        throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The local Codex factory version evidence is malformed.");
+    }
+    return CODEX_APP_SERVER_WRITABLE_VERSIONS.some((certifiedVersion) => sharesCompatibilityMajor(certifiedVersion, version))
+        ? undefined
+        : "CODEX_APP_SERVER_VERSION_UNSUPPORTED";
+}
+function validateCodexFactory(factory, options = {}) {
     const schema = factory.schemaCompatibility;
     const write = factory.writeCompatibility;
+    const versionFailure = codexVersionFailureCode(factory.appServerVersion);
     const certified = CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(factory.appServerVersion);
     const schemaCandidate = schema.observedSchemaCandidate === true &&
         CODEX_APP_SERVER_WRITABLE_VERSIONS.some((version) => sharesCompatibilityMajor(version, factory.appServerVersion));
+    const unsupportedVersionInvalid = versionFailure !== undefined &&
+        (options.allowUnsupportedVersion !== true ||
+            write !== null ||
+            factory.writableReady);
+    const supportedSchemaInvalid = versionFailure === undefined &&
+        ((!certified &&
+            (!schemaCandidate || write !== null || factory.writableReady)) ||
+            schema.protocol !== "app-server-v2-stable" ||
+            schema.steering?.method !== "turn/steer" ||
+            schema.steering.requestSchema !== "expected-turn-id-text-v1" ||
+            schema.steering.deliveryBoundary !== "next-tool-call-boundary" ||
+            (write !== null &&
+                (write.appServerVersion !== schema.appServerVersion ||
+                    write.endpointGeneration !== schema.endpointGeneration ||
+                    write.protocol !== schema.protocol ||
+                    write.observedSchemaCandidate !== schema.observedSchemaCandidate ||
+                    write.steering?.method !== schema.steering.method ||
+                    write.steering.requestSchema !== schema.steering.requestSchema ||
+                    write.steering.deliveryBoundary !==
+                        schema.steering.deliveryBoundary)) ||
+            factory.writableReady !== (write !== null));
     if (factory.hostId !== LOCAL_HOST ||
         factory.protocol !== "codex-app-server" ||
         factory.protocolVersion !== factory.appServerVersion ||
-        (!certified &&
-            (!schemaCandidate || write !== null || factory.writableReady)) ||
         schema.appServerVersion !== factory.appServerVersion ||
         schema.endpointGeneration !== factory.endpointGeneration ||
-        schema.protocol !== "app-server-v2-stable" ||
-        schema.steering?.method !== "turn/steer" ||
-        schema.steering.requestSchema !== "expected-turn-id-text-v1" ||
-        schema.steering.deliveryBoundary !== "next-tool-call-boundary" ||
-        (write !== null &&
-            (write.appServerVersion !== schema.appServerVersion ||
-                write.endpointGeneration !== schema.endpointGeneration ||
-                write.protocol !== schema.protocol ||
-                write.observedSchemaCandidate !== schema.observedSchemaCandidate ||
-                write.steering?.method !== schema.steering.method ||
-                write.steering.requestSchema !== schema.steering.requestSchema ||
-                write.steering.deliveryBoundary !==
-                    schema.steering.deliveryBoundary)) ||
-        factory.writableReady !== (write !== null)) {
+        unsupportedVersionInvalid ||
+        supportedSchemaInvalid) {
         throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The local Codex provider requires exact schema and write attestations.");
     }
 }
@@ -1628,6 +1898,7 @@ export class LocalCodexGatewayProvider {
     endpointActivationRetryTimer;
     callbackDrainFrozen = false;
     compatibilityAttested;
+    compatibilityFailureCode;
     endpointUnavailable = false;
     pendingEndpointAttestation;
     pendingEndpointRefreshEvent;
@@ -1673,26 +1944,48 @@ export class LocalCodexGatewayProvider {
     }
     acceptCompatibilityAttestation(attestation) {
         const pending = this.pendingEndpointAttestation;
-        if (attestation.surface !== "codex" ||
+        const pendingMatches = pending === undefined ||
+            (attestation.checkedAt === pending.checkedAt &&
+                attestation.tier === pending.tier &&
+                attestation.safeErrorCode === pending.safeErrorCode &&
+                attestation.probes.length === pending.probes.length &&
+                attestation.probes.every((probe, index) => probe.name === pending.probes[index]?.name &&
+                    probe.outcome === pending.probes[index]?.outcome &&
+                    probe.safeErrorCode === pending.probes[index]?.safeErrorCode));
+        if (!isCompatibilityAttestation(attestation) ||
+            attestation.surface !== "codex" ||
             attestation.version !== this.factory.appServerVersion ||
-            attestation.tier !== "certified" ||
-            !CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(attestation.version) ||
+            !pendingMatches) {
+            throw new BridgeError("CODEX_COMPATIBILITY_ATTESTATION_MISMATCH", "The Codex compatibility attestation does not match this endpoint.");
+        }
+        if (attestation.tier === "incompatible") {
+            this.pendingEndpointAttestation = undefined;
+            this.pendingEndpointRefreshEvent = undefined;
+            this.clearEndpointActivationRetry();
+            this.compatibilityAttested = false;
+            this.endpointUnavailable = true;
+            this.compatibilityFailureCode =
+                attestation.safeErrorCode ?? "CODEX_COMPATIBILITY_CHECK_FAILED";
+            return;
+        }
+        const writableCertified = attestation.tier === "certified" &&
+            CODEX_APP_SERVER_WRITABLE_VERSIONS.includes(attestation.version) &&
+            this.factory.writableReady &&
+            this.factory.writeCompatibility !== null;
+        const schemaObserved = attestation.tier === "schema_attested" &&
+            !this.factory.writableReady &&
+            this.factory.writeCompatibility === null;
+        if ((!writableCertified && !schemaObserved) ||
             (this.endpointUnavailable && pending === undefined) ||
-            (pending !== undefined &&
-                (attestation.checkedAt !== pending.checkedAt ||
-                    attestation.tier !== pending.tier ||
-                    attestation.safeErrorCode !== pending.safeErrorCode ||
-                    attestation.probes.length !== pending.probes.length ||
-                    attestation.probes.some((probe, index) => probe.name !== pending.probes[index]?.name ||
-                        probe.outcome !== pending.probes[index]?.outcome ||
-                        probe.safeErrorCode !== pending.probes[index]?.safeErrorCode)))) {
+            !pendingMatches) {
             throw new BridgeError("CODEX_COMPATIBILITY_ATTESTATION_MISMATCH", "The Codex compatibility attestation does not match this endpoint.");
         }
         this.pendingEndpointAttestation = undefined;
         this.pendingEndpointRefreshEvent = undefined;
         this.clearEndpointActivationRetry();
-        this.compatibilityAttested = true;
-        this.endpointUnavailable = false;
+        this.compatibilityAttested = writableCertified;
+        this.endpointUnavailable = !writableCertified;
+        this.compatibilityFailureCode = undefined;
     }
     async runCompatibilityProbes() {
         return await this.runCompatibilityProbesFor(this.factory);
@@ -1731,19 +2024,26 @@ export class LocalCodexGatewayProvider {
             if (this.isEndpointGenerationChanged(error))
                 throw error;
             if (stage === "transport") {
-                const controlFailure = error instanceof LocalCodexTransportError &&
+                const availabilityFailure = error instanceof LocalCodexTransportError &&
                     [
+                        "MANAGED_CODEX_UNAVAILABLE",
                         "LOCAL_APP_SERVER_NOT_RUNNING",
-                        "LOCAL_APP_SERVER_ENDPOINT_UNSAFE",
+                        "SPAWN_FAILED",
+                        "SPAWN_TIMEOUT",
+                        "PROXY_STDERR_LIMIT",
                         "TRANSPORT_CONNECT_FAILED",
                     ].includes(error.code);
+                if (!availabilityFailure)
+                    throw error;
+                const installationUnavailable = error instanceof LocalCodexTransportError &&
+                    error.code === "MANAGED_CODEX_UNAVAILABLE";
                 return [
-                    controlFailure
-                        ? passedProbe(installation)
-                        : failedProbe(installation, "CODEX_INSTALLATION_INVALID"),
-                    failedProbe(control, controlFailure
-                        ? "CODEX_CONTROL_SOCKET_UNAVAILABLE"
-                        : "CODEX_COMPAT_PROBE_BLOCKED"),
+                    installationUnavailable
+                        ? failedProbe(installation, "CODEX_INSTALLATION_INVALID")
+                        : passedProbe(installation),
+                    failedProbe(control, installationUnavailable
+                        ? "CODEX_COMPAT_PROBE_BLOCKED"
+                        : "CODEX_CONTROL_SOCKET_UNAVAILABLE"),
                     failedProbe(initialize, "CODEX_COMPAT_PROBE_BLOCKED"),
                     failedProbe(threadList, "CODEX_COMPAT_PROBE_BLOCKED"),
                 ];
@@ -1759,10 +2059,10 @@ export class LocalCodexGatewayProvider {
         }
         finally {
             if (connector !== undefined) {
-                await connector.close().catch(() => undefined);
+                await connector.close();
             }
             else if (transport !== undefined) {
-                await transport.close().catch(() => undefined);
+                await transport.close();
             }
         }
     }
@@ -1772,6 +2072,13 @@ export class LocalCodexGatewayProvider {
         }
         this.callbacks = callbacks;
         this.initialized = true;
+        if (this.compatibilityFailureCode !== undefined) {
+            return {
+                health: "degraded",
+                compatibility: "incompatible",
+                safeErrorCode: this.compatibilityFailureCode,
+            };
+        }
         return this.factory.writeCompatibility === null
             ? {
                 health: "degraded",
@@ -1977,6 +2284,9 @@ export class LocalCodexGatewayProvider {
                 ...(input.progressWatchActive === true
                     ? { progressWatchActive: true }
                     : {}),
+                ...(input.steer === true && input.queuedAhead !== undefined
+                    ? { queuedAhead: input.queuedAhead }
+                    : {}),
             });
         }
         catch (error) {
@@ -2214,13 +2524,23 @@ export class LocalCodexGatewayProvider {
             return route;
         }
         catch (error) {
+            let cleanupFailure;
             if (connector !== undefined) {
-                await connector.close().catch(() => undefined);
+                await connector.close().catch((closeError) => {
+                    cleanupFailure = closeError;
+                });
             }
             else if (transport !== undefined) {
-                await transport.close().catch(() => undefined);
+                await transport.close().catch((closeError) => {
+                    cleanupFailure = closeError;
+                });
             }
-            if (this.isEndpointGenerationChanged(error))
+            if (cleanupFailure !== undefined) {
+                if (isCodexTrustFailure(cleanupFailure))
+                    throw cleanupFailure;
+                throw new BridgeError("CODEX_ROUTE_CLEANUP_FAILED", "Codex route setup could not prove exact provider-process cleanup.");
+            }
+            if (isCodexTrustFailure(error))
                 throw error;
             if (error instanceof BridgeError)
                 throw error;
@@ -2415,18 +2735,14 @@ export class LocalCodexGatewayProvider {
                 candidate = undefined;
                 return undefined;
             }
-            this.factory = candidate;
-            candidate = undefined;
-            this.retiredEndpointGeneration = undefined;
-            this.compatibilityAttested = false;
-            this.endpointUnavailable = true;
-            this.pendingEndpointAttestation = attestation;
+            const replacementFactory = candidate;
             const refreshedRoutes = [];
+            const stagedRoutes = [];
             for (const routeHandle of [...this.trackedRoutes]) {
                 if (this.closing || this.closed)
                     break;
                 try {
-                    const route = await this.createRoute(routeHandle, this.factory, false);
+                    const route = await this.createRoute(routeHandle, replacementFactory, false);
                     if (this.closing || this.closed) {
                         await this.closeRoute(route);
                         break;
@@ -2436,17 +2752,34 @@ export class LocalCodexGatewayProvider {
                         await this.closeRoute(route);
                         throw new BridgeError("CODEX_ROUTE_SETUP_REJECTED", "The exact Codex task was stale on the replacement endpoint.");
                     }
-                    this.routes.set(routeHandle, route);
-                    this.routesRequiringRecovery.delete(routeHandle);
-                    this.routeRecoveryAttempts.delete(routeHandle);
-                    refreshedRoutes.push({ routeHandle, state });
+                    stagedRoutes.push({ routeHandle, route, state });
                 }
-                catch {
+                catch (error) {
                     this.routesRequiringRecovery.add(routeHandle);
+                    if (isCodexTrustFailure(error))
+                        throw error;
                 }
             }
-            if (this.closing || this.closed)
+            if (this.closing || this.closed) {
+                await replacementFactory.close();
+                candidate = undefined;
                 return undefined;
+            }
+            this.factory = replacementFactory;
+            candidate = undefined;
+            this.retiredEndpointGeneration = undefined;
+            this.compatibilityAttested = false;
+            this.endpointUnavailable = true;
+            this.pendingEndpointAttestation = attestation;
+            for (const staged of stagedRoutes) {
+                this.routes.set(staged.routeHandle, staged.route);
+                this.routesRequiringRecovery.delete(staged.routeHandle);
+                this.routeRecoveryAttempts.delete(staged.routeHandle);
+                refreshedRoutes.push({
+                    routeHandle: staged.routeHandle,
+                    state: staged.state,
+                });
+            }
             const result = {
                 event: {
                     outcome: "compatible",
@@ -2474,7 +2807,7 @@ export class LocalCodexGatewayProvider {
         }
         catch (error) {
             if (candidate !== undefined && candidate !== previousFactory) {
-                await candidate.close().catch(() => undefined);
+                await candidate.close();
             }
             throw error;
         }
@@ -2490,7 +2823,10 @@ export class LocalCodexGatewayProvider {
             let candidate;
             try {
                 candidate = await refreshFactory();
-                validateCodexFactory(candidate);
+                const versionFailure = codexVersionFailureCode(candidate.appServerVersion);
+                validateCodexFactory(candidate, {
+                    allowUnsupportedVersion: versionFailure !== undefined,
+                });
                 if (candidate.hostId !== previous.hostId ||
                     candidate.protocol !== previousFactory.protocol) {
                     throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The replacement Codex factory moved outside its pinned boundary.");
@@ -2500,14 +2836,25 @@ export class LocalCodexGatewayProvider {
                     if (candidate !== previousFactory)
                         await candidate.close();
                     candidate = undefined;
+                    if (this.endpointUnavailable &&
+                        this.compatibilityFailureCode === undefined &&
+                        !this.factory.writableReady &&
+                        this.factory.writeCompatibility === null) {
+                        throw new BridgeError("CODEX_MONITOR_ONLY", "This Codex App Server remains monitor-only until a write-attested generation is available.");
+                    }
                     if (attempt + 1 < MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES) {
                         continue;
                     }
                     throw new BridgeError("CODEX_ENDPOINT_GENERATION_CHURN", "The Codex endpoint did not stabilize within its bounded refresh window.", true);
                 }
-                // Endpoint generations never inherit cached compatibility. Every
-                // candidate independently proves all four read-only wire probes.
-                const probes = await this.runCompatibilityProbesFor(candidate);
+                // Endpoint generations never inherit cached compatibility. A version
+                // outside the tested major is classified from OS-attested factory
+                // evidence alone; no connector or transport may touch that protocol.
+                const probes = versionFailure === undefined
+                    ? await this.runCompatibilityProbesFor(candidate)
+                    : compatibilityProbeNames.codex.map((name, index) => index === 0
+                        ? passedProbe(name)
+                        : failedProbe(name, versionFailure));
                 const attestation = evaluateCompatibilityAttestation({
                     surface: "codex",
                     version: candidate.appServerVersion,