@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/client/link-relay-transport.ts

@@ -4,9 +4,12 @@ import { Readable } from "node:stream";
 import { createBrotliDecompress, createGunzip, createInflate } from "node:zlib";
 import { serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { clearableDeadline } from "../lib/abort";
+import { packageVersion } from "../lib/package-version";
+import { linkPeerReportHeaders } from "../link/peer-report";
+import { buildPeerFeatures } from "../remote/features";
 import {
   LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION,
-  LINK_RELAY_SESSION_HEADER, linkRelayChallenge, linkRelayProofMatches,
+  LINK_RELAY_PROBE_HEADER, LINK_RELAY_SESSION_HEADER, linkRelayChallenge, linkRelayProofMatches,
 } from "../link/relay-auth";
 
 export interface BoundLinkRelayTarget {
@@ -24,6 +27,14 @@ export class LinkRelayAuthenticationError extends Error {
   }
 }
 
+/** Only the credential-free preflight deadline expired; no data request has begun. */
+export class LinkRelayAuthTimeoutError extends Error {
+  constructor() {
+    super("link relay authentication timed out");
+    this.name = "LinkRelayAuthTimeoutError";
+  }
+}
+
 /** One physical connection, ever. A closed keep-alive socket cannot trigger a silent reconnect. */
 class SingleConnectionAgent extends Agent {
   socket: Socket | undefined;
@@ -148,19 +159,78 @@ async function responseOnConnection(incoming: IncomingMessage, agent: SingleConn
   }, { highWaterMark: 0 }), { status, headers });
 }
 
-/** Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch. */
-export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destination: string, init: RequestInit): Promise<Response> {
+let peerReport: Record<string, string> | undefined;
+
+/** The credential-free challenge for one connection; the proof binds this nonce to the link key. */
+function relayChallenge(target: BoundLinkRelayTarget, origin: URL) {
+  const challenge = linkRelayChallenge(serviceApiTokenFingerprint(target.admissionKey), target.apiKeyId!, target.linkId!);
+  const probe = new URL(LINK_RELAY_AUTH_PATH, origin);
+  probe.search = new URLSearchParams({ version: LINK_RELAY_AUTH_VERSION, key: target.apiKeyId!,
+    link: target.linkId!, nonce: challenge.nonce, proof: challenge.caller }).toString();
+  // The challenge also carries this Child's version and features for the Home's link status.
+  peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), buildPeerFeatures());
+  return { challenge, probe, headers: peerReport };
+}
+
+/**
+ * The outcome of the credential-free preflight alone: `ok` when the Home answered with a proof
+ * only the holder of the link key can make, `unrecognized` for a peer without the route (404),
+ * `auth_failed` for any other answer, and `unreachable` when nothing answered in time.
+ */
+export type LinkRelayPreflightResult = "ok" | "unreachable" | "auth_failed" | "unrecognized";
+
+/**
+ * Run only the preflight a relayed request starts with, on its own connection, and close it. It
+ * sends no link key, no data request and no body; the Child's readiness uses it to learn whether
+ * the Home answers through the tunnel right now. It is marked probe-only, so the Home reserves no
+ * session for a data request that never comes. The response body is never read.
+ */
+export async function probeLinkRelayPreflight(
+  target: BoundLinkRelayTarget, options: { timeoutMs?: number } = {},
+): Promise<LinkRelayPreflightResult> {
+  const timeoutMs = options.timeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new RangeError("invalid link relay preflight timeout");
+  if (!target.linkId || !target.apiKeyId) return "auth_failed";
+  const origin = new URL(`http://127.0.0.1:${target.tunnelPort}`);
+  let request: ReturnType<typeof relayChallenge>;
+  try { request = relayChallenge(target, origin); } catch { return "auth_failed"; }
+  const agent = new SingleConnectionAgent({ keepAlive: false, maxSockets: 1, maxFreeSockets: 0 });
+  const deadline = clearableDeadline(timeoutMs);
+  try {
+    const response = await requestOnConnection(request.probe, {
+      method: "GET", signal: deadline.signal, headers: { ...request.headers, [LINK_RELAY_PROBE_HEADER]: "1" },
+    }, agent);
+    const proof = response.headers["x-opencodex-link-proof"];
+    if (response.statusCode === 204 && typeof proof === "string" && linkRelayProofMatches(proof, request.challenge.expected)) return "ok";
+    return response.statusCode === 404 ? "unrecognized" : "auth_failed";
+  } catch {
+    return "unreachable";
+  } finally {
+    deadline.clear();
+    await agent.close();
+  }
+}
+
+/**
+ * Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch.
+ * LinkRelayAuthTimeoutError certifies that only the credential-free preflight expired before
+ * data-request construction. Caller aborts and failures after that boundary keep their own errors.
+ */
+export async function fetchBoundLinkRelay(
+  target: BoundLinkRelayTarget, destination: string, init: RequestInit,
+  options: { authTimeoutMs?: number } = {},
+): Promise<Response> {
+  const authTimeoutMs = options.authTimeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
+  if (!Number.isFinite(authTimeoutMs) || authTimeoutMs <= 0) throw new RangeError("invalid link relay auth timeout");
   if (!target.linkId || !target.apiKeyId) throw new LinkRelayAuthenticationError();
   const url = new URL(destination);
   if (url.origin !== `http://127.0.0.1:${target.tunnelPort}`) throw new LinkRelayAuthenticationError();
-  const challenge = linkRelayChallenge(serviceApiTokenFingerprint(target.admissionKey), target.apiKeyId, target.linkId);
-  const probe = new URL(LINK_RELAY_AUTH_PATH, url);
-  probe.search = new URLSearchParams({ version: LINK_RELAY_AUTH_VERSION, key: target.apiKeyId,
-    link: target.linkId, nonce: challenge.nonce, proof: challenge.caller }).toString();
+  const { challenge, probe, headers: preflightHeaders } = relayChallenge(target, url);
   const agent = new SingleConnectionAgent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });
-  const deadline = clearableDeadline(LINK_RELAY_AUTH_TIMEOUT_MS, init.signal ?? undefined);
+  const deadline = clearableDeadline(authTimeoutMs, init.signal ?? undefined);
+  let dataRequestStarted = false;
   try {
-    const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal }, agent);
+    const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: preflightHeaders }, agent);
     const socket = agent.socket;
     const proof = response.headers["x-opencodex-link-proof"];
     if (response.statusCode !== 204 || typeof proof !== "string" || !linkRelayProofMatches(proof, challenge.expected)) {
@@ -170,15 +240,20 @@ export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destinat
     for await (const chunk of response) {
       if (chunk.length) throw new LinkRelayAuthenticationError();
     }
+    deadline.signal.throwIfAborted();
     deadline.clear();
     init.signal?.throwIfAborted();
     if (!socket || socket.destroyed || socket !== agent.socket) throw new LinkRelayAuthenticationError();
     const headers = new Headers(init.headers);
     headers.set(LINK_RELAY_SESSION_HEADER, challenge.nonce);
+    dataRequestStarted = true;
     const incoming = await requestOnConnection(url, { ...init, headers }, agent, socket);
     return await responseOnConnection(incoming, agent, init.method ?? "GET");
   } catch (error) {
+    const authDeadlineExpired = !dataRequestStarted && deadline.didExpire()
+      && !(error instanceof LinkRelayAuthenticationError);
     await agent.close();
+    if (authDeadlineExpired && !init.signal?.aborted) throw new LinkRelayAuthTimeoutError();
     throw error;
   } finally { deadline.clear(); }
 }

package/src/client/link-relay.ts

@@ -1,10 +1,13 @@
-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,
   filterRelayHeaders,
   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";
@@ -25,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;
   /**
@@ -50,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;
@@ -112,6 +125,30 @@ function jsonError(status: number, error: string, retry = false): Response {
   return Response.json({ error }, { status, headers });
 }
 
+/** A retryable 503 for a Home this Child cannot reach (OCX-11 `home_unreachable`). */
+function homeUnreachable(error: string): Response {
+  return Response.json(homeUnreachableBody(error), {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
+/**
+ * The peer answered but the connection-bound relay authentication failed. That is not a Home
+ * outage (an unrecognized protocol needs an upgrade or a re-link), so it must never read as
+ * `home_unreachable`, which GOAT's device-local fallback keys on. The status and Retry-After it
+ * carried before OCX-11 are kept: a lost bound socket can succeed on a fresh connection.
+ */
+export const LINK_RELAY_AUTH_FAILED_CODE = "link_relay_auth_failed";
+
+function relayAuthenticationFailed(error: string): Response {
+  return Response.json({ error, code: LINK_RELAY_AUTH_FAILED_CODE }, {
+    status: 503,
+    headers: { "Retry-After": String(LINK_RELAY_RETRY_AFTER_SECONDS) },
+  });
+}
+
+/** 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");
@@ -156,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));
@@ -304,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,
@@ -328,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(() => {
@@ -366,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 jsonError(503, "link tunnel unavailable", true);
+    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,
@@ -391,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 jsonError(503, error.message, true);
+        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 jsonError(503, "link tunnel unavailable", true);
+    return await tunnelUnavailable();
   }
 
   const sse = isSse(upstream.headers);
@@ -425,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,10 +22,25 @@ 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 {
+  CLIENT_RESTART_BUDGET_MS,
+  parseExpectedSystemRestartPid,
+  RESTART_SUPERVISED_ERROR,
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_CAPABILITY_VERSION,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_METHOD,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  verifySystemRestartCapability,
+} from "../lib/system-restart-contract";
 import { linkRouteAllowed } from "../link/routes";
 import { linkHomeName, linkHomePhrase } from "./link-home";
 import { relayLinkManagementRead } from "./link-management-relay";
+import type { ClientRestartAdmission } from "./runtime-restart";
 
 const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
@@ -51,6 +67,22 @@ 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
+   * capability signed with `attestationSecret` for this pid and port, and nothing else.
+   */
+  restart?: {
+    attestationSecret: string;
+    /** ISO start time of this runtime's process. */
+    startedAt: string;
+    request: () => Promise<ClientRestartAdmission>;
+  };
   serve?: (options: Parameters<typeof Bun.serve>[0]) => Server<unknown>;
 }
 
@@ -68,6 +100,8 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
   if (linkMode && linkRouteAllowed(url, req)) return true;
   const path = url.pathname;
   if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
+  // The bound restart. Only a capability signed for this exact process admits it (see the handler).
+  if (req.method === SYSTEM_RESTART_METHOD && path === SYSTEM_RESTART_PATH) return true;
   if ((req.method === "GET" || req.method === "HEAD") && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
   // The one link route a connected Child serves: its own read-only link status.
   if (linkMode && (req.method === "GET" || req.method === "HEAD") && path === "/api/link/status") return true;
@@ -125,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)))({
@@ -143,10 +177,34 @@ export function startMachineListener(
       }
       if (!machineRouteAllowed(url, req, relayEnabled, linkMode)) return json404(req);
       if (url.pathname === "/healthz" && req.method === "GET") {
-        return Response.json({ service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port });
+        const restart = deps.restart;
+        const response = Response.json({
+          service: "opencodex", version: VERSION, role: "client", uptime: process.uptime(), pid: process.pid, port: server.port,
+          ...(restart ? { startedAt: restart.startedAt, restartCapability: SYSTEM_RESTART_CAPABILITY_VERSION, restartBudgetMs: CLIENT_RESTART_BUDGET_MS } : {}),
+        });
+        const challenge = restart ? req.headers.get(LOCAL_ATTESTATION_CHALLENGE_HEADER) : null;
+        const proof = challenge && server.port
+          ? createLocalAttestationProof(restart!.attestationSecret, challenge, process.pid, server.port)
+          : null;
+        if (proof) response.headers.set(LOCAL_ATTESTATION_PROOF_HEADER, proof);
+        return response;
+      }
+      if (url.pathname === SYSTEM_RESTART_PATH && req.method === SYSTEM_RESTART_METHOD) {
+        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);
@@ -232,3 +290,45 @@ export function startMachineListener(
     },
   } as Parameters<typeof Bun.serve>[0]);
 }
+
+/**
+ * `POST /api/system/restart` on the client listener (OCX-6). The only accepted principal is the
+ * process-bound restart capability `ocx restart` derives from this runtime's attestation secret:
+ * no dashboard session, admin token or link key reaches it, and a browser cannot mint it.
+ */
+async function handleBoundRestart(
+  req: Request,
+  server: Server<unknown>,
+  restart: MachineListenerDeps["restart"],
+): Promise<Response> {
+  const noStore = { "cache-control": "no-store" };
+  if (!restart || !server.port) return json404(req);
+  const expected = parseExpectedSystemRestartPid(req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER));
+  if (expected.kind !== "present" || expected.pid !== process.pid) {
+    return Response.json({ success: false, error: "Restart target identity changed." }, { status: 409, headers: noStore });
+  }
+  const authorized = verifySystemRestartCapability(
+    restart.attestationSecret,
+    req.headers.get(SYSTEM_RESTART_NONCE_HEADER),
+    SYSTEM_RESTART_METHOD,
+    SYSTEM_RESTART_PATH,
+    process.pid,
+    server.port,
+    req.headers.get(SYSTEM_RESTART_CAPABILITY_HEADER),
+  );
+  if (!authorized) return Response.json({ success: false, error: "restart capability required" }, { status: 401, headers: noStore });
+  const admission = await restart.request();
+  if (admission.kind === "supervised") {
+    return Response.json({
+      success: false,
+      error: { code: RESTART_SUPERVISED_ERROR, supervisor: admission.supervisor },
+    }, { status: 409, headers: noStore });
+  }
+  return Response.json({
+    success: true,
+    message: admission.alreadyRestarting ? "Restart already in progress." : "Restarting the client runtime.",
+    activeTurnCount: 0,
+    drainTimeoutMs: CLIENT_RESTART_BUDGET_MS,
+    alreadyDraining: admission.alreadyRestarting,
+  }, { status: 202, headers: noStore });
+}