agent-embassy 1.4.1 → 1.6.0

package/dist/src/gateway/providers.js

@@ -1,14 +1,15 @@
-import { createHash } from "node:crypto";
 import path from "node:path";
+import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rmdir, } from "node:fs/promises";
 import { BridgeError } from "../errors.js";
 import { CLAUDE_PEER_COMPATIBILITY, ClaudePeerAdapter, } from "./claude-peer.js";
-import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, sharesCompatibilityMajor, } from "./compatibility.js";
-import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, } from "./codex-app-server.js";
+import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, isCompatibilityAttestation, isCompatibilityVersion, sharesCompatibilityMajor, UNKNOWN_COMPATIBILITY_VERSION, } from "./compatibility.js";
+import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, codexWriteProbeFailure, } 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}$/;
@@ -24,12 +25,39 @@ const DEFAULT_CODEX_RECOVERY_INITIAL_MS = 250;
 const DEFAULT_CODEX_RECOVERY_MAX_MS = 5_000;
 const MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES = 3;
 const COMPATIBILITY_PROBE_THREAD_ID = "00000000-0000-7000-8000-000000000000";
+const CODEX_WRITE_PROBE_DIRECTORY_PREFIX = ".codex-write-probe-";
+const CODEX_WRITE_PROBE_ROOT = "write-probes";
+const MAX_CODEX_WRITE_PROBE_ATTEMPTS = 16;
+const CODEX_WRITE_PROBE_TRANSIENT_ERRNOS = new Set([
+    "EAGAIN", "EIO", "EMFILE", "ENFILE",
+]);
 const CLAUDE_CLEAN_PREWRITE_RETRY_CODES = new Set([
     "CLAUDE_PEER_TARGET_UNKNOWN",
     "CLAUDE_PEER_TARGET_STALE",
     "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") {
@@ -64,6 +92,99 @@ function passedProbe(name) {
 function failedProbe(name, safeErrorCode) {
     return { name, outcome: "fail", safeErrorCode };
 }
+function systemErrorCode(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+function transientCodexWriteProbeError(error) {
+    return CODEX_WRITE_PROBE_TRANSIENT_ERRNOS.has(systemErrorCode(error) ?? "");
+}
+function safeCodexWriteProbeFilesystemFailure(error) {
+    return (transientCodexWriteProbeError(error) ||
+        systemErrorCode(error) === "ENOTEMPTY" ||
+        (error instanceof BridgeError &&
+            error.code === "CODEX_WRITE_PROBE_THREAD_SETUP_FAILED"));
+}
+async function attestCodexWriteProbeDirectory(directory) {
+    try {
+        const resolved = path.resolve(directory);
+        const [metadata, canonical, entries] = await Promise.all([
+            lstat(resolved, { bigint: true }),
+            realpath(resolved),
+            readdir(resolved),
+        ]);
+        const uid = process.getuid?.();
+        if (uid === undefined ||
+            !metadata.isDirectory() ||
+            canonical !== resolved ||
+            metadata.uid !== BigInt(uid) ||
+            (metadata.mode & 511n) !== 448n) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory crossed its ownership, mode, or canonical-path boundary.");
+        }
+        if (entries.length !== 0) {
+            throw new BridgeError("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", "The disposable Codex probe directory was not empty.");
+        }
+        return {
+            dev: metadata.dev,
+            ino: metadata.ino,
+            mode: metadata.mode & 511n,
+            mtimeNs: metadata.mtimeNs,
+            uid: metadata.uid,
+        };
+    }
+    catch (error) {
+        if (error instanceof BridgeError)
+            throw error;
+        if (transientCodexWriteProbeError(error)) {
+            throw new BridgeError("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", "A transient filesystem error prevented disposable probe attestation.");
+        }
+        throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be attested safely.");
+    }
+}
+async function attestCodexWriteProbeRoot(root) {
+    try {
+        const resolved = path.resolve(root);
+        const [metadata, canonical] = await Promise.all([
+            lstat(resolved, { bigint: true }),
+            realpath(resolved),
+        ]);
+        const uid = process.getuid?.();
+        if (uid === undefined ||
+            !metadata.isDirectory() ||
+            canonical !== resolved ||
+            metadata.uid !== BigInt(uid) ||
+            (metadata.mode & 511n) !== 448n) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root changed outside its exact owned-directory boundary.");
+        }
+        return {
+            dev: metadata.dev,
+            ino: metadata.ino,
+            mode: metadata.mode & 511n,
+            uid: metadata.uid,
+        };
+    }
+    catch (error) {
+        if (error instanceof BridgeError)
+            throw error;
+        if (transientCodexWriteProbeError(error)) {
+            return null;
+        }
+        throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root could not be attested.");
+    }
+}
+function sameCodexWriteProbeDirectory(before, after) {
+    return sameCodexWriteProbeRoot(before, after) && before.mtimeNs === after.mtimeNs;
+}
+function sameCodexWriteProbeRoot(before, after) {
+    return (before.dev === after.dev &&
+        before.ino === after.ino &&
+        before.mode === after.mode &&
+        before.uid === after.uid);
+}
 function exactLocalHost(hostId) {
     if ((hostId ?? LOCAL_HOST) !== LOCAL_HOST) {
         throw new BridgeError("GATEWAY_REMOTE_PROVIDER_DISABLED", "This provider is restricted to the exact local host boundary.");
@@ -105,33 +226,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 +437,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 +448,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 +474,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 +495,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 +519,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 +570,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 +617,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 +1105,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 +1392,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 +1451,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 +1776,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 +1831,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 +1891,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.");
     }
 }
@@ -1627,10 +1997,15 @@ export class LocalCodexGatewayProvider {
     endpointActivationRetry;
     endpointActivationRetryTimer;
     callbackDrainFrozen = false;
+    writeProbeObservationsByGeneration = new Map();
+    writeProbeResults = new Map();
+    writeProbeOverflow;
     compatibilityAttested;
+    compatibilityFailureCode;
     endpointUnavailable = false;
     pendingEndpointAttestation;
     pendingEndpointRefreshEvent;
+    pendingEndpointRefreshSelectorClaimed = false;
     initialized = false;
     closing = false;
     closed = false;
@@ -1673,31 +2048,82 @@ 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.pendingEndpointRefreshSelectorClaimed = false;
+            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.pendingEndpointRefreshSelectorClaimed = false;
         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);
+    releaseEndpointRefreshSelectorClaim(endpointGeneration) {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event?.current.endpointGeneration === endpointGeneration &&
+            this.pendingEndpointAttestation !== undefined) {
+            this.pendingEndpointRefreshSelectorClaimed = false;
+        }
+    }
+    rearmEndpointRefreshActivation(endpointGeneration) {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event?.current.endpointGeneration === endpointGeneration &&
+            this.pendingEndpointAttestation !== undefined &&
+            !this.closing &&
+            !this.closed) {
+            this.publishEndpointRefresh(event);
+        }
     }
-    async runCompatibilityProbesFor(factory) {
+    latestWriteCompatibilityProbeObservation(endpointGeneration) {
+        return (this.writeProbeObservationsByGeneration.get(endpointGeneration) ??
+            (this.writeProbeOverflow?.endpointGeneration === endpointGeneration
+                ? this.writeProbeOverflow.observation
+                : undefined));
+    }
+    async runCompatibilityProbes(context) {
+        return await this.runCompatibilityProbesFor(this.factory, context === undefined
+            ? undefined
+            : {
+                stateRoot: path.resolve(context.stateRoot),
+                forbiddenCodexThreadIds: [...context.forbiddenCodexThreadIds],
+            });
+    }
+    async runCompatibilityProbesFor(factory, context) {
         const [installation, control, initialize, threadList] = compatibilityProbeNames.codex;
         let transport;
         let connector;
@@ -1707,6 +2133,9 @@ export class LocalCodexGatewayProvider {
             stage = "initialize";
             connector = await CodexAppServerConnector.connect({
                 compatibility: factory.schemaCompatibility,
+                ...(context === undefined
+                    ? {}
+                    : { writeCompatibilityProbe: true }),
                 writesEnabled: false,
                 route: {
                     endpointGeneration: factory.endpointGeneration,
@@ -1720,30 +2149,46 @@ export class LocalCodexGatewayProvider {
             });
             stage = "thread_list";
             await connector.observeLoadedThread(connector.guard());
-            return [
+            const requiredProbes = [
                 passedProbe(installation),
                 passedProbe(control),
                 passedProbe(initialize),
                 passedProbe(threadList),
             ];
+            if (context === undefined)
+                return requiredProbes;
+            const result = await this.runCodexWriteProbe(factory, connector, context);
+            return result.outcome === "pass"
+                ? [...requiredProbes, passedProbe("write_attestation")]
+                : requiredProbes;
         }
         catch (error) {
-            if (this.isEndpointGenerationChanged(error))
+            if (this.isEndpointGenerationChanged(error) ||
+                (error instanceof BridgeError &&
+                    error.code === "CODEX_FACTORY_ATTESTATION_INVALID")) {
                 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,19 +2204,168 @@ 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();
             }
         }
     }
+    async runCodexWriteProbe(factory, connector, context) {
+        const key = `${factory.appServerVersion}\0${factory.endpointGeneration}`;
+        const cached = this.writeProbeResults.get(key);
+        if (cached !== undefined)
+            return await cached;
+        if (this.writeProbeOverflow?.key === key) {
+            return this.writeProbeOverflow.observation;
+        }
+        if (this.writeProbeResults.size >= MAX_CODEX_WRITE_PROBE_ATTEMPTS) {
+            const observation = Object.freeze(codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED"));
+            this.writeProbeOverflow = Object.freeze({
+                endpointGeneration: factory.endpointGeneration,
+                key,
+                observation,
+            });
+            if (this.callbacks !== undefined) {
+                invokeCallback(() => this.callbacks?.onProtocolNotice?.({
+                    code: observation.safeErrorCode,
+                }));
+            }
+            return observation;
+        }
+        const pending = this.executeCodexWriteProbe(connector, context).then((result) => {
+            const observation = Object.freeze({ ...result });
+            this.writeProbeObservationsByGeneration.set(factory.endpointGeneration, observation);
+            if (observation.outcome === "fail" && this.callbacks !== undefined) {
+                invokeCallback(() => this.callbacks?.onProtocolNotice?.({
+                    code: observation.safeErrorCode,
+                }));
+            }
+            return observation;
+        });
+        this.writeProbeResults.set(key, pending);
+        return await pending;
+    }
+    async executeCodexWriteProbe(connector, context) {
+        const stateRoot = path.resolve(context.stateRoot);
+        const rootBefore = await attestCodexWriteProbeRoot(stateRoot);
+        if (rootBefore === null) {
+            return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        }
+        const probeRoot = path.join(stateRoot, CODEX_WRITE_PROBE_ROOT);
+        let probeRootBefore;
+        try {
+            let created = false;
+            try {
+                await mkdir(probeRoot, { mode: 0o700 });
+                created = true;
+            }
+            catch (error) {
+                if (systemErrorCode(error) !== "EEXIST")
+                    throw error;
+            }
+            if (created)
+                await chmod(probeRoot, 0o700);
+            const evidence = await attestCodexWriteProbeRoot(probeRoot);
+            if (evidence === null) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            probeRootBefore = evidence;
+        }
+        catch (error) {
+            if (error instanceof BridgeError &&
+                error.code === "CODEX_FACTORY_ATTESTATION_INVALID") {
+                throw error;
+            }
+            if (transientCodexWriteProbeError(error)) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The controller-owned Codex probe root could not be established safely.");
+        }
+        let cwd;
+        let before;
+        let result = codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        try {
+            cwd = await mkdtemp(path.join(probeRoot, CODEX_WRITE_PROBE_DIRECTORY_PREFIX));
+            if (path.dirname(cwd) !== probeRoot) {
+                throw new Error("probe directory escaped its dedicated root");
+            }
+            await chmod(cwd, 0o700);
+            before = await attestCodexWriteProbeDirectory(cwd);
+            result = await connector.runWriteCompatibilityProbe({
+                cwd,
+                forbiddenThreadIds: [
+                    ...new Set([
+                        COMPATIBILITY_PROBE_THREAD_ID,
+                        ...context.forbiddenCodexThreadIds,
+                        ...this.trackedRoutes,
+                    ]),
+                ],
+            });
+        }
+        catch (error) {
+            if (!safeCodexWriteProbeFilesystemFailure(error)) {
+                if (error instanceof BridgeError)
+                    throw error;
+                throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be established safely.");
+            }
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        }
+        let unchanged = false;
+        let removed = false;
+        if (cwd !== undefined && before !== undefined) {
+            try {
+                const after = await attestCodexWriteProbeDirectory(cwd);
+                unchanged = sameCodexWriteProbeDirectory(before, after);
+                await rmdir(cwd);
+                try {
+                    await lstat(cwd);
+                }
+                catch (error) {
+                    removed = systemErrorCode(error) === "ENOENT";
+                }
+            }
+            catch (error) {
+                if (!safeCodexWriteProbeFilesystemFailure(error)) {
+                    if (error instanceof BridgeError)
+                        throw error;
+                    throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be re-attested safely.");
+                }
+                // Never remove a path after its exact ownership evidence changed.
+            }
+        }
+        if (cwd !== undefined && !removed) {
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_CLEANUP_UNCONFIRMED", result);
+        }
+        else if (cwd !== undefined && !unchanged) {
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED", result);
+        }
+        const [probeRootAfter, rootAfter] = await Promise.all([
+            attestCodexWriteProbeRoot(probeRoot),
+            attestCodexWriteProbeRoot(stateRoot),
+        ]);
+        if (probeRootAfter === null || rootAfter === null) {
+            return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", result);
+        }
+        if (!sameCodexWriteProbeRoot(probeRootBefore, probeRootAfter) ||
+            !sameCodexWriteProbeRoot(rootBefore, rootAfter)) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root changed while the disposable probe ran.");
+        }
+        return result;
+    }
     async initialize(callbacks) {
         if (this.closed || this.initialized) {
             throw new BridgeError("CODEX_PROVIDER_INITIALIZATION_REJECTED", "The local Codex provider cannot be initialized in this state.");
         }
         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",
@@ -1817,9 +2411,13 @@ export class LocalCodexGatewayProvider {
                 throw selectionError;
             }
         };
+        const retainedEndpointRefresh = this.retainedEndpointRefreshResult();
         if (this.endpointRefresh !== undefined) {
             route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
         }
+        else if (retainedEndpointRefresh !== undefined) {
+            route = await stageRefreshedRoute(retainedEndpointRefresh);
+        }
         else if (this.endpointUnavailable &&
             this.pendingEndpointAttestation === undefined) {
             route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
@@ -1977,6 +2575,9 @@ export class LocalCodexGatewayProvider {
                 ...(input.progressWatchActive === true
                     ? { progressWatchActive: true }
                     : {}),
+                ...(input.steer === true && input.queuedAhead !== undefined
+                    ? { queuedAhead: input.queuedAhead }
+                    : {}),
             });
         }
         catch (error) {
@@ -2075,6 +2676,7 @@ export class LocalCodexGatewayProvider {
         this.routesRequiringRecovery.clear();
         this.clearEndpointActivationRetry();
         this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointRefreshSelectorClaimed = false;
         this.pendingEndpointAttestation = undefined;
         const refreshResult = this.endpointRefresh === undefined
             ? []
@@ -2103,6 +2705,7 @@ export class LocalCodexGatewayProvider {
         this.callbackQueue.length = 0;
         this.pendingEndpointAttestation = undefined;
         this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointRefreshSelectorClaimed = false;
         this.trackedRoutes.clear();
         this.routeAliases.clear();
         this.expectsReply.clear();
@@ -2214,13 +2817,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 (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 (this.isEndpointGenerationChanged(error))
+            if (isCodexTrustFailure(error))
                 throw error;
             if (error instanceof BridgeError)
                 throw error;
@@ -2343,6 +2956,21 @@ export class LocalCodexGatewayProvider {
             event.current.endpointGeneration === this.factory.endpointGeneration &&
             event.routes.some((route) => route.routeHandle === routeHandle));
     }
+    retainedEndpointRefreshResult() {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event === undefined ||
+            this.pendingEndpointRefreshSelectorClaimed ||
+            this.pendingEndpointAttestation === undefined ||
+            event.current.endpointGeneration !== this.factory.endpointGeneration) {
+            return undefined;
+        }
+        return {
+            event,
+            delivery: "selector",
+            selectorClaimed: false,
+            published: true,
+        };
+    }
     async refreshEndpoint(delivery) {
         if (this.refreshFactory === undefined || this.closing || this.closed) {
             return undefined;
@@ -2387,6 +3015,7 @@ export class LocalCodexGatewayProvider {
                 this.compatibilityAttested = false;
                 this.pendingEndpointAttestation = undefined;
                 this.pendingEndpointRefreshEvent = undefined;
+                this.pendingEndpointRefreshSelectorClaimed = false;
                 for (const routeHandle of this.trackedRoutes) {
                     this.routesRequiringRecovery.add(routeHandle);
                 }
@@ -2401,7 +3030,9 @@ export class LocalCodexGatewayProvider {
                     },
                     delivery: "callback",
                     selectorClaimed: true,
+                    published: false,
                 };
+                result.published = true;
                 this.emitEndpointRefresh(result.event);
                 for (const routeHandle of this.routesRequiringRecovery) {
                     if (this.trackedRoutes.has(routeHandle)) {
@@ -2415,18 +3046,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 +3063,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",
@@ -2457,12 +3101,15 @@ export class LocalCodexGatewayProvider {
                 },
                 delivery: this.endpointRefreshDelivery ?? "callback",
                 selectorClaimed: false,
+                published: false,
             };
             if (result.event.outcome === "compatible") {
                 this.pendingEndpointRefreshEvent = result.event;
+                this.pendingEndpointRefreshSelectorClaimed = false;
             }
             if (result.delivery === "callback") {
                 result.selectorClaimed = true;
+                result.published = true;
                 this.publishEndpointRefresh(result.event);
             }
             for (const routeHandle of this.routesRequiringRecovery) {
@@ -2474,7 +3121,7 @@ export class LocalCodexGatewayProvider {
         }
         catch (error) {
             if (candidate !== undefined && candidate !== previousFactory) {
-                await candidate.close().catch(() => undefined);
+                await candidate.close();
             }
             throw error;
         }
@@ -2490,7 +3137,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 +3150,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,
@@ -2567,11 +3228,16 @@ export class LocalCodexGatewayProvider {
             return false;
         }
         result.selectorClaimed = true;
+        if (this.pendingEndpointRefreshEvent === result.event) {
+            this.pendingEndpointRefreshSelectorClaimed = true;
+        }
         return true;
     }
     emitSelectorRefreshFallback(result, staleRouteHandle) {
         if (result.delivery !== "selector" || !result.selectorClaimed)
             return;
+        if (result.published)
+            return;
         let event = result.event;
         if (staleRouteHandle !== undefined &&
             event.outcome === "compatible" &&
@@ -2583,6 +3249,7 @@ export class LocalCodexGatewayProvider {
             result.event = event;
             this.pendingEndpointRefreshEvent = event;
         }
+        result.published = true;
         this.publishEndpointRefresh(event);
     }
     publishEndpointRefresh(event) {