@bitkyc08/opencodex 2.91.0 → 2.92.0

package/src/client/link-relay.ts

@@ -1,4 +1,5 @@
-import { fetchBoundLinkRelay, LinkRelayAuthenticationError } from "./link-relay-transport";
+import { randomUUID } from "node:crypto";
+import { fetchBoundLinkRelay, LinkRelayAuthenticationError, LinkRelayAuthTimeoutError } from "./link-relay-transport";
 import { homeUnreachableBody } from "./home-unreachable";
 import {
   boundedRelayResponseStream,
@@ -6,6 +7,7 @@ import {
   headersWithinLimit,
   validateHubRelayRequestHeaders,
 } from "./hub-relay";
+import type { LinkDiagnosticRecord, LinkDiagnosticSink } from "../link/diagnostics";
 import { linkRouteAllowed } from "../link/routes";
 import { isLinkPort } from "../link/ports";
 import { resolveInboundBodyLimitBytes } from "../server/request-decompress";
@@ -26,14 +28,23 @@ export interface LinkRelayClock {
   clearTimeout: typeof clearTimeout;
 }
 
+/** A fresh admission verdict plus optional diagnostic evidence; metadata never grants admission. */
+export interface LinkAdmissionResult {
+  kind: "match" | "mismatch" | "lookup_error" | "deadline" | "stale" | "identity_unknown" | "identity_mismatch" | "unavailable";
+  elapsedMs?: number;
+  generation?: number;
+  state?: string;
+  checkId?: string;
+}
+
 /**
  * The Child's tunnel as the relay sees it (the client link supervisor implements it). A request
  * waits on it only while the tunnel is being (re)established. Every relayed fetch waits for a
  * fresh bounded asynchronous ownership proof, including after a reconnect or refused retry.
  */
 export interface LinkTunnelGate {
-  /** True only while a keyed probe has established this live tunnel. */
-  connected(): boolean | Promise<boolean>;
+  /** Admission and its evidence are returned together; only match permits a fetch. */
+  connected(context?: { requestId?: string }): LinkAdmissionResult | Promise<LinkAdmissionResult>;
   /** True while the tunnel is connecting or reconnecting. */
   pending(): boolean;
   /**
@@ -51,12 +62,13 @@ export interface LinkTunnelGate {
  * supervisor, and a relay with no gate at all still refuses every request.
  */
 export const HOME_INITIATED_LINK_TUNNEL: LinkTunnelGate = {
-  connected: () => true,
+  connected: () => ({ kind: "match" }),
   pending: () => false,
   waitForConnected: async () => false,
 };
 
 export interface LinkRelayDeps {
+  diagnostic?: LinkDiagnosticSink;
   /** Trusted complete-send test seam. Production always uses the connection-bound transport. */
   fetchImpl?: typeof fetch;
   clock?: LinkRelayClock;
@@ -136,6 +148,7 @@ function relayAuthenticationFailed(error: string): Response {
   });
 }
 
+/** Preserve path/query on a fixed IPv4 loopback origin; throw when the tunnel port is invalid. */
 export function linkRelayDestination(url: URL, target: Pick<LinkRelayTarget, "tunnelPort">): string {
   if (!isLinkPort(target.tunnelPort)) {
     throw new RangeError("invalid link tunnel port");
@@ -180,6 +193,7 @@ function linkRequestHeaders(
   return headers;
 }
 
+/** Drop hop-by-hop and stale length/encoding headers before exposing the decoded response. */
 export function sanitizeLinkResponseHeaders(source: Headers): Headers {
   const connectionNamed = new Set((source.get("connection") ?? "")
     .split(",").map(value => value.trim().toLowerCase()).filter(Boolean));
@@ -328,6 +342,11 @@ function idleBoundedStream(
   });
 }
 
+/**
+ * Admit an allowlisted route and stream it through the authenticated tunnel with bounded bodies.
+ * Owner/auth preflight deadlines share one recovery attempt before data dispatch; an ambiguous
+ * post-dispatch failure never earns that recovery. Diagnostic failures cannot change admission.
+ */
 export async function relayLinkDataRequest(
   req: Request,
   target: LinkRelayTarget,
@@ -352,6 +371,16 @@ export async function relayLinkDataRequest(
     return jsonError(431, "link relay request headers too large");
   }
 
+  const requestId = randomUUID();
+  let admission: LinkAdmissionResult = { kind: "unavailable" };
+  let recoveryAttempts = 0;
+  const diagnostic = (event: LinkDiagnosticRecord["event"], outcome: LinkDiagnosticRecord["outcome"], elapsedMs?: number) => {
+    try { deps.diagnostic?.({ event, outcome, requestId,
+      checkId: admission.checkId, generation: admission.generation,
+      state: admission.state, elapsedMs: admission.elapsedMs,
+      ...(elapsedMs !== undefined ? { elapsedMs } : {}), attempt: recoveryAttempts }); }
+    catch { /* diagnostics never alter admission */ }
+  };
   const relayAbort = new AbortController();
   const clock = deps.clock ?? defaultClock;
   let headerTimer: ReturnType<typeof setTimeout> | undefined = clock.setTimeout(() => {
@@ -390,20 +419,45 @@ export async function relayLinkDataRequest(
     const remaining = holdUntil - now;
     return remaining > 0 && await gate.waitForConnected(remaining, relayAbort.signal);
   };
-  const tunnelUnavailable = async (): Promise<Response> => {
+  const tunnelUnavailable = async (
+    reason: LinkDiagnosticRecord["outcome"] = admission.kind === "match" ? "unavailable" : admission.kind,
+    message = "link tunnel unavailable",
+    elapsedMs?: number,
+  ): Promise<Response> => {
+    diagnostic("relay_failure", relayAbort.signal.aborted
+      ? req.signal.aborted ? "client_abort" : "header_timeout" : reason, elapsedMs);
     cleanup();
     try { await body?.cancel(); } catch { /* best effort */ }
-    return homeUnreachable("link tunnel unavailable");
+    const response = reason === "auth_failed" ? relayAuthenticationFailed(message) : homeUnreachable(message);
+    response.headers.set("x-opencodex-link-request-id", requestId);
+    return response;
+  };
+  const retryPreflight = (reason: "deadline" | "auth_timeout", elapsedMs?: number): boolean => {
+    if (recoveryAttempts >= 1 || relayAbort.signal.aborted || bodyOverflow || bodyCancelled || body?.locked) return false;
+    recoveryAttempts += 1;
+    diagnostic("relay_retry", reason, elapsedMs);
+    return true;
+  };
+  const checkConnected = async (): Promise<boolean> => {
+    admission = tunnel ? await tunnel.connected({ requestId }) : { kind: "unavailable" };
+    return admission.kind === "match";
   };
   const readyForFetch = async (): Promise<boolean> => {
-    if (!tunnel) return false;
-    if (await tunnel.connected()) return true;
-    return tunnel.pending() && await holdForTunnel(tunnel) && await tunnel.connected();
+    if (!tunnel || relayAbort.signal.aborted) return false;
+    if (await checkConnected()) return !relayAbort.signal.aborted;
+    // No fetch or body read has occurred. A deadline proves neither a foreign owner nor a
+    // broken SSH process: give this request one fresh proof, without caching or restarting it.
+    if (admission.kind === "deadline" && retryPreflight("deadline")) {
+      if (await checkConnected()) return !relayAbort.signal.aborted;
+    }
+    return !relayAbort.signal.aborted && tunnel.pending() && await holdForTunnel(tunnel)
+      && await checkConnected() && !relayAbort.signal.aborted;
   };
 
   let upstream: Response | undefined;
   while (!upstream) {
     if (!await readyForFetch()) return await tunnelUnavailable();
+    const fetchStartedAt = performance.now();
     try {
       const init: RequestInit & { duplex?: "half" } = {
         method: req.method,
@@ -415,24 +469,28 @@ export async function relayLinkDataRequest(
       upstream = await (deps.fetchImpl ? deps.fetchImpl(destination, init) : fetchBoundLinkRelay(target, destination, init));
     } catch (error) {
       if (error instanceof LinkRelayAuthenticationError) {
-        cleanup();
-        try { await body?.cancel(); } catch { /* an upload might already be drained */ }
-        return relayAuthenticationFailed(error.message);
+        return await tunnelUnavailable("auth_failed", error.message);
       }
       if (bodyOverflow) {
         cleanup();
         return jsonError(413, "link relay request body too large");
       }
+      if (error instanceof LinkRelayAuthTimeoutError) {
+        // The transport certifies that only its credential-free challenge was sent. A new
+        // iteration obtains a fresh ownership proof and a new authenticated physical socket.
+        const elapsedMs = performance.now() - fetchStartedAt;
+        if (retryPreflight("auth_timeout", elapsedMs)) continue;
+        return await tunnelUnavailable("auth_timeout", "link tunnel unavailable", elapsedMs);
+      }
       // A refused connection sent nothing, and an untouched body can go again once the tunnel
       // is back inside the same hold window. Anything else is never replayed.
       const resendable = connectionRefused(error) && (body === null || (!body.locked && !bodyCancelled));
-      if (!tunnel || !resendable || !tunnel.pending() || !await holdForTunnel(tunnel)) return await tunnelUnavailable();
+      if (!tunnel || !resendable || !tunnel.pending() || !await holdForTunnel(tunnel)) return await tunnelUnavailable("transport_error");
     }
   }
   if (relayAbort.signal.aborted) {
-    cleanup();
     try { await upstream.body?.cancel(); } catch { /* best effort */ }
-    return homeUnreachable("link tunnel unavailable");
+    return await tunnelUnavailable();
   }
 
   const sse = isSse(upstream.headers);
@@ -449,6 +507,7 @@ export async function relayLinkDataRequest(
     try { await upstream.body?.cancel(); } catch { /* best effort */ }
     return jsonError(502, "link relay response body too large");
   }
+  if (recoveryAttempts > 0 && upstream.ok) diagnostic("relay_recovered", "recovered");
   if (req.method === "HEAD" || !upstream.body) {
     cleanup();
     try { await upstream.body?.cancel(); } catch { /* best effort */ }

package/src/client/link-tunnel.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { readFile as readFileAsync } from "node:fs/promises";
@@ -13,17 +14,18 @@ import {
   CLIENT_TUNNEL_RETRY_POLICY,
   classifySshStderr,
   dueForSpawn,
-  failedTunnel,
+  failedSpawnTunnel,
   IDLE,
   reduceTunnel,
   type StderrClass,
   type TunnelState,
 } from "../link/tunnel-state";
 import { isLinkPort } from "../link/ports";
-import { ownsIpv4LoopbackListener } from "../server/port-reclaim";
+import { inspectIpv4LoopbackListener, type LoopbackOwnerLookupResult } from "../server/port-reclaim";
+import type { LinkDiagnosticSink } from "../link/diagnostics";
 import { isLinkConnection, readClientConnectionState } from "./state";
 import { clientLinkStatePath, readClientLinkState, type ClientLinkState } from "./link-state";
-import type { LinkTunnelGate } from "./link-relay";
+import type { LinkTunnelGate, LinkAdmissionResult } from "./link-relay";
 
 /**
  * The client-owned `ssh -N -L 127.0.0.1:<tunnelPort>:127.0.0.1:<peerListenerPort> <alias>`
@@ -134,7 +136,8 @@ export interface ClientLinkSupervisorDeps extends ClientLinkTunnelDeps, OrphanRe
   /** The link key for the keyed readiness probe. The runtime passes its cached key source. */
   linkKey?: () => string | null;
   /** Async local IPv4 LISTEN ownership; an unknown or foreign owner never receives the link key. */
-  ownsLoopbackListener?: (port: number, pid: number) => Promise<boolean>;
+  inspectLoopbackListener?: (port: number, pid: number) => Promise<LoopbackOwnerLookupResult>;
+  diagnostic?: LinkDiagnosticSink;
   fetchImpl?: typeof fetch;
   now?: () => number;
   random?: () => number;
@@ -563,6 +566,10 @@ async function probeTunnel(fetchImpl: typeof fetch, tunnelPort: number, key: str
   }
 }
 
+/**
+ * Own the Child's SSH lifecycle and reconnect holds. Each connected() call checks fresh listener
+ * ownership and fences results against tunnel replacement or stop; diagnostics cannot admit it.
+ */
 export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}): ClientLinkSupervisor {
   const sidecarPath = (): string => clientLinkStatePath(deps.configDir);
   const readSidecar = deps.readSidecar ?? readWhenFileChanges(sidecarPath, () => readClientLinkState(sidecarPath()));
@@ -573,7 +580,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
   const policy = CLIENT_TUNNEL_RETRY_POLICY;
   const isAlive = deps.isAlive ?? defaultIsAlive;
   const linkKey = deps.linkKey ?? (() => null);
-  const ownerLookup = deps.ownsLoopbackListener ?? ownsIpv4LoopbackListener;
+  const ownerLookup = deps.inspectLoopbackListener ?? inspectIpv4LoopbackListener;
   const fetchImpl = deps.fetchImpl ?? fetch;
   const setSupervisorTimer = deps.setTimer ?? ((callback: () => void, ms: number) => {
     const interval = setInterval(callback, ms);
@@ -620,9 +627,16 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
     if (pid === null || pid === undefined || (adopted !== null && !adoptedRecord)) return null;
     return { pid, generation: ownerGeneration };
   };
-  const listenerOwnedByTunnel = async (port: number): Promise<boolean> => {
+  const listenerOwnedByTunnel = async (port: number, context?: { requestId?: string }): Promise<LinkAdmissionResult> => {
     const candidate = ownerCandidate(port);
-    if (!candidate) return false;
+    if (!candidate) return { kind: "unavailable" };
+    const checkId = randomUUID();
+    const report = (kind: LinkAdmissionResult["kind"], elapsedMs = 0): LinkAdmissionResult => {
+      const check = { kind, elapsedMs, checkId, generation: candidate.generation, state: state.kind };
+      if (kind !== "match") try { deps.diagnostic?.({ event: "owner_lookup", outcome: kind, requestId: context?.requestId,
+        checkId, generation: candidate.generation, state: state.kind, elapsedMs }); } catch { /* best effort */ }
+      return check;
+    };
     if (adopted !== null) {
       const record = adoptedRecord;
       const identity = record ? await inspectAdoptedIdentity(record, deps) : "unknown";
@@ -640,16 +654,28 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
           invalidateOwnerProof();
           setState(IDLE);
         }
-        return false;
+        return report(identity === "mismatch" ? "identity_mismatch" : "identity_unknown");
       }
     }
-    const owned = await Promise.resolve().then(() => ownerLookup(port, candidate.pid)).catch(() => false);
-    return owned && !stopping && ownerGeneration === candidate.generation
-      && ownerCandidate(port)?.pid === candidate.pid;
+    const result = await Promise.resolve().then(() => ownerLookup(port, candidate.pid))
+      .catch((): LoopbackOwnerLookupResult => ({ kind: "lookup_error", elapsedMs: 0 }));
+    if (stopping || failure !== undefined || ownerGeneration !== candidate.generation || ownerCandidate(port)?.pid !== candidate.pid) {
+      return report("stale", result.elapsedMs);
+    }
+    return report(result.kind, result.elapsedMs);
+  };
+  const connected = async (context?: { requestId?: string }): Promise<LinkAdmissionResult> => {
+    if (!started || stopping || failure !== undefined || state.kind !== "connected" || linkId === null || tunnelPort === null) {
+      return { kind: "unavailable" };
+    }
+    const result = await listenerOwnedByTunnel(tunnelPort, context);
+    // State may change during the asynchronous lookup or an optional diagnostic callback.
+    if (result.kind === "match" && (!started || stopping || failure !== undefined
+      || state.kind !== "connected" || result.generation !== ownerGeneration)) {
+      return { ...result, kind: "stale" };
+    }
+    return result;
   };
-  const connected = async (): Promise<boolean> => started && !stopping && failure === undefined
-    && state.kind === "connected" && linkId !== null && tunnelPort !== null
-    && await listenerOwnedByTunnel(tunnelPort);
 
   const settleWaiters = (): void => {
     if (waiters.size === 0) return;
@@ -733,7 +759,8 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
         peerListenerPort: sidecar.peerListenerPort,
       }, deps);
     } catch {
-      setState(failedTunnel("forward", timestamp, policy, state.kind === "failed" ? state.since : timestamp));
+      // A due retry that cannot start counts as a failed retry, so the backoff keeps its step.
+      setState(failedSpawnTunnel(state, "forward", timestamp, policy));
       deps.warn?.("client link tunnel could not be started");
       return;
     }
@@ -800,7 +827,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
     probeFlight = flight;
     const wasConnected = state.kind === "connected";
     void (async () => {
-      if (!await listenerOwnedByTunnel(tunnelPort)) return;
+      if ((await listenerOwnedByTunnel(tunnelPort)).kind !== "match") return;
       if (probeFlight !== flight || stopping || flight.abort.signal.aborted
         || child !== flight.child || adopted !== flight.adopted) return;
       const key = linkKey();
@@ -808,7 +835,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
       const result = await probeTunnel(fetchImpl, tunnelPort, key, flight.abort.signal);
       // An aborted probe, or one whose listener changed while it ran, proves nothing.
       if (probeFlight !== flight || stopping || child !== flight.child || adopted !== flight.adopted
-        || !await listenerOwnedByTunnel(tunnelPort)) return;
+        || (await listenerOwnedByTunnel(tunnelPort)).kind !== "match") return;
       applyProbe(result, wasConnected);
     })().catch(() => undefined).finally(() => {
       if (probeFlight === flight) probeFlight = undefined;
@@ -971,7 +998,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
     pending,
     connected,
     waitForConnected(timeoutMs: number, signal?: AbortSignal): Promise<boolean> {
-      if (state.kind === "connected") return connected();
+      if (state.kind === "connected") return connected().then(result => result.kind === "match");
       if (!pending() || waiters.size >= CLIENT_LINK_MAX_HOLDS || signal?.aborted || !(timeoutMs > 0)) {
         return Promise.resolve(false);
       }

package/src/client/machine-listener.ts

@@ -1,3 +1,4 @@
+import { recordLinkDiagnostic } from "../link/diagnostics";
 import type { Server } from "bun";
 import { loadConfig } from "../config";
 import { browserSecurityHeaders, requestPolicyView } from "../server/auth-cors";
@@ -21,6 +22,7 @@ import type { LinkTunnelGate } from "./link-relay";
 import { readClientLinkState, type ClientLinkState } from "./link-state";
 import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-status";
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
+import type { LinkReadiness } from "./link-readiness";
 import { packageVersion } from "../lib/package-version";
 import { createLocalAttestationProof, LOCAL_ATTESTATION_CHALLENGE_HEADER, LOCAL_ATTESTATION_PROOF_HEADER } from "../lib/local-management-attestation";
 import {
@@ -65,6 +67,11 @@ export interface MachineListenerDeps {
   linkTunnel?: LinkTunnelGate;
   /** Link mode: relay seams (deadline clock and byte cap). */
   linkRelay?: LinkIngress["relay"];
+  /**
+   * Link mode: whether relayed requests can be served now. `GET /readyz` answers 503 `pending`
+   * with `link.reason` while it is not; `/healthz` is unaffected (`link-readiness.ts`).
+   */
+  linkReadiness?: () => LinkReadiness | Promise<LinkReadiness>;
   /**
    * The bound restart (OCX-6). With it, `/healthz` proves this process's identity to a challenge,
    * advertises `restartCapability` and `startedAt`, and `POST /api/system/restart` accepts a
@@ -152,7 +159,7 @@ export function startMachineListener(
       apiKeyId: connection.apiKeyId,
       policy: requestPolicyView(config, "127.0.0.1"),
       linkKey: deps.linkKeySource ?? createLinkKeySource(connection.tokenFingerprint, deps.linkKey),
-      relay: { fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
+      relay: { diagnostic: recordLinkDiagnostic, fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
     }
     : null;
   return (deps.serve ?? (options => Bun.serve(options)))({
@@ -186,7 +193,18 @@ export function startMachineListener(
         return await handleBoundRestart(req, server, deps.restart);
       }
       if (url.pathname === "/readyz" && req.method === "GET") {
-        return Response.json({ service: "opencodex", version: VERSION, role: "client", status: "ready", uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 });
+        const identity = { service: "opencodex", version: VERSION, role: "client" } as const;
+        const facts = { uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 };
+        let link: LinkReadiness | null = null;
+        if (linkMode && deps.linkReadiness) {
+          try { link = await deps.linkReadiness(); } catch { link = { ready: false, reason: "link_unverified" }; }
+        }
+        if (link && !link.ready) {
+          // The /readyz contract: not ready is 503 with Retry-After and status pending or failed.
+          return Response.json({ ...identity, status: "pending", ...facts, link: { state: "unavailable", reason: link.reason } },
+            { status: 503, headers: { "Retry-After": "1", "Cache-Control": "no-store" } });
+        }
+        return Response.json({ ...identity, status: "ready", ...facts, ...(link ? { link: { state: "available" } } : {}) });
       }
       if (url.pathname.startsWith("/api/machine/hub-relay/")) {
         if (!relayEnabled) return json404(req);

package/src/client/runtime.ts

@@ -1,3 +1,4 @@
+import { flushLinkDiagnostics, recordLinkDiagnostic } from "../link/diagnostics";
 import { existsSync } from "node:fs";
 import type { Server } from "bun";
 import { siblingRuntimeField, withSiblingMarker } from "../codex/sibling-start";
@@ -20,6 +21,7 @@ import type { ReplacementStartRequest } from "../server/restart-replacement";
 import type { OcxClientConnectionConfig } from "../types";
 import { createLinkKeySource } from "./link-ingress";
 import { HOME_INITIATED_LINK_TUNNEL } from "./link-relay";
+import { clientInitiatedLinkReadiness, createHomeInitiatedLinkReadiness } from "./link-readiness";
 import { createClientLinkSupervisor, type ClientLinkSupervisor } from "./link-tunnel";
 import { clientLinkStatePath, isChildInitiatedLink, recordChildInitiatedLink } from "./link-state";
 import { startMachineListener, type MachineListenerDeps } from "./machine-listener";
@@ -164,6 +166,7 @@ export async function recycleStandalone(
     console.warn(`[client] listener stop failed: ${error instanceof Error ? error.message : String(error)}`);
   }
   cleanup();
+  await flushLinkDiagnostics();
   // Recycling back to standalone after `ocx disconnect` must actually bring a standalone
   // proxy back, under every launch shape.
   //
@@ -227,7 +230,7 @@ export async function bindClientListener(
     preferred: number;
     explicitPort: boolean;
     configuredPort: number;
-  } & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel" | "restart">,
+  } & Pick<MachineListenerDeps, "linkStatus" | "linkKeySource" | "linkTunnel" | "linkReadiness" | "restart">,
   io: ClientRuntimeIo = {},
 ): Promise<{ server: Server<unknown>; port: number }> {
   const { linkMode } = request;
@@ -267,6 +270,7 @@ export async function bindClientListener(
         ...(request.linkStatus ? { linkStatus: request.linkStatus } : {}),
         ...(request.linkKeySource ? { linkKeySource: request.linkKeySource } : {}),
         ...(request.linkTunnel ? { linkTunnel: request.linkTunnel } : {}),
+        ...(request.linkReadiness ? { linkReadiness: request.linkReadiness } : {}),
         ...(request.restart ? { restart: request.restart } : {}),
       });
       return { server, port: server.port ?? port };
@@ -318,10 +322,19 @@ export async function startClientRuntime(
   const serve = async (rollback?: { port: number; portWaitMs: number }): Promise<boolean> => {
     const supervisor = supervised
       ? createClientLinkSupervisor({
+        diagnostic: recordLinkDiagnostic,
         onLinkEnded: () => scheduleStandaloneRecycle(state.value.tokenFingerprint),
         linkKey,
       })
       : null;
+    // What `/readyz` reports about the link: the supervisor's tunnel, or for a Home-initiated
+    // link the shared relay preflight. A link with neither refuses every relayed request.
+    const link = state.value.link;
+    const linkReadiness: MachineListenerDeps["linkReadiness"] = !linkMode ? undefined
+      : supervisor ? () => clientInitiatedLinkReadiness(supervisor.status())
+      : homeInitiated && link && linkKey
+        ? createHomeInitiatedLinkReadiness({ target: { tunnelPort: link.tunnelPort, linkId: link.linkId, apiKeyId: state.value.apiKeyId }, linkKey })
+        : () => ({ ready: false, reason: "tunnel_unavailable" });
     const { server, port: boundPort } = await bindClientListener({
       state: state.value,
       linkMode,
@@ -332,6 +345,7 @@ export async function startClientRuntime(
       restart: { attestationSecret, startedAt: CLIENT_RUNTIME_STARTED_AT, request: () => restartController.request() },
       ...(linkMode ? { linkStatus: () => activeSupervisor?.status() ?? { kind: "stopped" as const }, linkKeySource: linkKey } : {}),
       ...(supervisor ? { linkTunnel: supervisor } : homeInitiated ? { linkTunnel: HOME_INITIATED_LINK_TUNNEL } : {}),
+      ...(linkReadiness ? { linkReadiness } : {}),
     }, rollback === undefined ? io : { ...io, portWaitMs: rollback.portWaitMs });
     const publish = (): void => {
       activeServer = server;
@@ -417,7 +431,10 @@ export async function startClientRuntime(
         await recycleStandalone(state.value.tokenFingerprint);
       }
     },
-    exitProcess: code => { process.exit(code); },
+    exitProcess: async code => {
+      await flushLinkDiagnostics();
+      process.exit(code);
+    },
   });
 
   installCrashGuards();
@@ -444,6 +461,7 @@ export async function startClientRuntime(
         console.warn(`[client] listener stop failed: ${error instanceof Error ? error.message : String(error)}`);
       } finally {
         cleanup();
+        await flushLinkDiagnostics();
         // launchd relaunches only unsuccessful exits; an external signal must still count.
         process.exit(handledSignalExitCode(signal));
       }

package/src/codex/account-store.ts

@@ -12,13 +12,15 @@ import {
   backupInvalidConfig,
   hardenConfigDir,
   hardenExistingSecret,
+  loadConfig,
   withConfigMutationLockSync,
 } from "../config";
 import { notifyCodexStoreLoaded } from "../lib/decision-quota-sink";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
-import type { CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
+import type { CodexAccount, CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
 import { isValidCodexAccountId } from "./account-id";
+import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "./account-label";
 import type { PoolQuotaWriter } from "./quota-types";
 import { CODEX_REFRESH_FLIGHT_CEILING_MS } from "./quota-recovery-timing";
 
@@ -183,6 +185,18 @@ function persistCredentialMutation(store: CodexAccountStore): void {
   advanceCodexCredentialMutationEpoch();
 }
 
+/**
+ * The durable `p<hex6>` label the dashboard and usage log show for this pool account, so a refresh
+ * failure line can be matched to the account row (#7592). The id hash is only the label of a
+ * legacy row that never received one. A config read failure must not replace the refresh error
+ * being reported, so it degrades to that same hash.
+ */
+function poolAccountLogLabel(id: string): string {
+  let account: CodexAccount | undefined;
+  try { account = loadConfig().codexAccounts?.find(row => row.id === id); } catch { account = undefined; }
+  return account ? codexAccountLogLabel(account) : fallbackCodexAccountLogLabel(id);
+}
+
 /**
  * Validation metadata that survives a credential write.
  *
@@ -1055,7 +1069,7 @@ export async function forceRefreshCodexPoolToken(
       if (isTerminalCodexPoolRefreshFailure(error) || isOperationalCodexPoolRefreshFailure(error)) {
         if (isTerminalCodexPoolRefreshFailure(error)) clearCodexPoolRefreshFailure(id);
       } else {
-        noteCodexPoolRefreshFailure(id, classifyCodexPoolRefreshFailureReason(error), undefined, refreshFence);
+        noteCodexPoolRefreshFailure(id, classifyCodexPoolRefreshFailureReason(error), undefined, refreshFence, poolAccountLogLabel);
       }
       settle({ kind: "failed", error });
     },
@@ -1376,7 +1390,7 @@ async function resolveCodexToken(
         .catch(() => undefined);
       const failure = classifyChatgptRefreshFailure(res.status, body?.displaySafe ? body.text : "");
       const { reason } = failure;
-      noteChatgptRefreshFailure("pool", res.status, failure);
+      noteChatgptRefreshFailure("pool", res.status, failure, poolAccountLogLabel(id));
       throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`, res.status, failure.code);
     }
     const data = (await res.json()) as { access_token: string; refresh_token?: string; expires_in: number };

package/src/codex/app-server-restart-service.ts

@@ -182,11 +182,12 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   // Decided here, before the early returns, because the model picker lives in the DESKTOP
   // app: "no app-server is running" is not a reason to leave a stale roster on screen.
   //
-  // The shell restarts only when its picker predates the catalog (#4761). Quitting it
-  // discards composer drafts, unsent picker selections and pending approvals, and when
-  // the picker is already current the app-server restart below is all the operator
-  // needs: the desktop respawns its app-server child, which rereads config and catalog.
-  // An unreadable picker state takes the full restart, the behaviour before #4761.
+  // The shell gets a restart attempt whenever its picker cannot be proven current: at
+  // or before the catalog mtime it is stale, and newer is unknown because an earlier
+  // sync may have rebound an already-existing catalog file (#4761). Quitting it
+  // discards composer drafts, unsent picker selections and pending approvals. The
+  // attempt is explicit, not a guarantee: the restart helper can refuse or partially
+  // fail, and desktopApp reports that outcome.
   //
   // allowHandoff is false and that is deliberate. The handoff waits for the CALLING
   // process to exit, and this runs inside a long-lived proxy that does not, so every

package/src/codex/catalog/effort.ts

@@ -55,6 +55,12 @@ import {
 export function nativeEffortClamp(slug: string, effort: string | undefined): string | null {
   if (!effort || (effort !== "max" && effort !== "ultra")) return null;
   if (slug.includes("/")) return null; // routed models map efforts in their adapters
+  // `ultra` is a client-facing catalog choice (max reasoning plus proactive delegation) that
+  // codex-rs converts to `max` before any request (core/src/client.rs
+  // `reasoning_effort_for_request`). The ChatGPT backend rejects it with HTTP 400 even for a
+  // model whose pinned ladder lists it (#7590), so it is never a native wire value: fold it to
+  // `max`, then clamp `max` like a direct selection.
+  const wire = "max";
   const entry = UPSTREAM_NATIVE_ENTRIES.get(slug);
   const levels = Array.isArray(entry?.supported_reasoning_levels)
     ? entry.supported_reasoning_levels as Array<{ effort?: string }>
@@ -65,10 +71,11 @@ export function nativeEffortClamp(slug: string, effort: string | undefined): str
     // a retired slug a client still asks for, and future old-ladder slugs)
     // really stops at xhigh — the ChatGPT backend error names exactly none..xhigh — so clamp
     // the synthetic top tier.
-    return isGpt56NativeSlug(slug) ? null : "xhigh";
+    if (!isGpt56NativeSlug(slug)) return "xhigh";
+    return effort === wire ? null : wire;
   }
   const supported = levels.flatMap(l => typeof l.effort === "string" ? [l.effort] : []);
-  if (supported.includes(effort)) return null;
+  if (supported.includes(wire)) return effort === wire ? null : wire;
   const rank = ["minimal", "low", "medium", "high", "xhigh", "max"];
   const highest = supported
     .filter(e => rank.includes(e))

package/src/codex/catalog/gather-capture.ts

@@ -119,6 +119,7 @@ export interface CatalogGatherProviderModelOutcome {
   readonly state: "authoritative" | "degraded";
 }
 export interface ModelsAuthResolution {
+  readonly workbuddy?: import("../../oauth/types").WorkBuddyOAuthMetadata;
   readonly apiKey: string | undefined;
   readonly observed: boolean;
   readonly oauthAccountId?: string;
@@ -334,8 +335,9 @@ export function captureModelsRequest(
   name: string,
   provider: OcxProviderConfig,
   oauthApiBaseUrl: string | undefined,
+  workbuddy?: import("../../oauth/types").WorkBuddyOAuthMetadata,
 ): CapturedModelsRequest {
-  const observed = { oauthApiBaseUrl };
+  const observed = { oauthApiBaseUrl, workbuddy };
   const withoutCredential = buildModelsRequest(provider, undefined, name, observed);
   const withCredential = buildModelsRequest(provider, REQUEST_CREDENTIAL_SENTINEL, name, observed);
   const method = withoutCredential.method ?? "GET";
@@ -400,7 +402,7 @@ export function captureProviderGather(
     : authResolver.kind === "refreshing" && provider.authMode === "oauth" && mayResolveModelsOAuth(name, provider)
       ? getOAuthCredentialApiBaseUrl(name)
       : undefined;
-  const request = captureModelsRequest(name, provider, oauthApiBaseUrl);
+  const request = captureModelsRequest(name, provider, oauthApiBaseUrl, observedAuth?.workbuddy);
   const refreshingOAuthAccountId = !observedAuth && authResolver.kind === "refreshing" && provider.authMode === "oauth" && mayResolveModelsOAuth(name, provider)
     ? getAccountSet(name)?.activeAccountId
     : undefined;