@bitkyc08/opencodex 2.91.0 → 2.92.0

package/src/cli/link.ts

@@ -1,7 +1,10 @@
 import { clientLinkStatusIdentity } from "../client/link-status";
 import { clientLinkTunnelStatus } from "../client/link-tunnel";
 import { loadConfig } from "../config";
-import { projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto } from "../link/status-projection";
+import {
+  projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto, type LinkTunnelDiagnostics, type LinkWireState,
+} from "../link/status-projection";
+import { TUNNEL_CAUSES } from "../link/tunnel-history";
 import { isEpochMs, type LinkChildParity } from "../link/child-parity";
 import { CODEX_SETTINGS_DIGEST_PATTERN } from "../link/codex-settings";
 import type { LinkLocalPeer, LinkPeerStatus } from "../link/compatibility";
@@ -40,30 +43,11 @@ export const LINK_USAGE = `Usage:
 Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.
 Cleanup finds Windows Children and explains how to move them to Hub mode; it changes nothing.`;
 
-type LinkState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
-type ListenerState = "off" | "listening" | "failed";
-
-export interface LinkStatusPayload {
-  role: "standalone" | "home" | "child";
-  listener: { state: ListenerState; port: number | null };
-  links: Array<LinkChildParity & {
-    id: string;
-    alias: string;
-    direction: LinkDirection;
-    state: LinkState;
-    since: string;
-    reason: string | null;
-    tunnelPort: number;
-    peer?: LinkPeerStatus;
-  }>;
-  child: null | {
-    alias: string;
-    state: LinkState;
-    since: string;
-    reason: string | null;
-  };
-  local?: LinkLocalPeer;
-}
+/**
+ * What `ocx link status` prints: the runtime's status DTO itself, so a field the server adds (like
+ * `peer` or the diagnostics `tunnel`) is part of this type the moment it is part of the wire.
+ */
+export type LinkStatusPayload = LinkStatusDto;
 
 export interface LinkIssuePayload {
   linkId: string;
@@ -165,11 +149,11 @@ function validateStatus(value: unknown): LinkStatusPayload {
     throw new Error("invalid link API response: listener port");
   }
   if (!Array.isArray(value.links)) throw new Error("invalid link API response: links");
-  const links = value.links.map((candidate, index) => {
+  const links = value.links.map((candidate, index): LinkStatusPayload["links"][number] => {
     if (!isRecord(candidate)) throw new Error(`invalid link API response: link ${index}`);
     // The OCX-6 parity fields are optional on the wire (an older runtime omits them) and always
     // present in this output, null when absent.
-    assertKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], [...PARITY_KEYS, "peer"], `link ${index}`);
+    assertKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], [...PARITY_KEYS, "peer", "tunnel"], `link ${index}`);
     const parity = validateParity(candidate, index);
     if (typeof candidate.id !== "string" || !LINK_ID.test(candidate.id)
       || !validString(candidate.alias) || (candidate.direction !== "hub-initiated" && candidate.direction !== "client-initiated")
@@ -180,14 +164,15 @@ function validateStatus(value: unknown): LinkStatusPayload {
     return {
       id: candidate.id,
       alias: candidate.alias,
-      direction: candidate.direction,
-      state: candidate.state,
+      direction: candidate.direction as LinkDirection,
+      state: candidate.state as LinkWireState,
       since: candidate.since,
       reason: candidate.reason,
       tunnelPort: candidate.tunnelPort,
       ...parity,
       ...(candidate.peer !== undefined ? { peer: validatePeer(candidate.peer, index) } : {}),
-    } as LinkStatusPayload["links"][number];
+      ...(candidate.tunnel !== undefined ? { tunnel: validateTunnel(candidate.tunnel, index) } : {}),
+    };
   });
   let child: LinkStatusPayload["child"] = null;
   if (value.child !== null) {
@@ -310,8 +295,9 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
     }
     throw error;
   }
-  // A proxy older than the compatibility report ignores the query and answers the exact K16 shape.
-  const result = validateStatus(await linkRequest<unknown>("/api/link/status?compatibility=1", {}, { ...deps, baseUrl }));
+  // A proxy older than the compatibility report or the tunnel diagnostics ignores the query and
+  // answers without those fields.
+  const result = validateStatus(await linkRequest<unknown>("/api/link/status?compatibility=1&diagnostics=1", {}, { ...deps, baseUrl }));
   console.log(JSON.stringify(result));
 }
 
@@ -385,6 +371,33 @@ export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}):
 }
 
 const PARITY_KEYS = ["lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "reportedAt"] as const;
+const WIRE_STATES = new Set(["connecting", "connected", "reconnecting", "failed", "idle"]);
+const CAUSES = new Set<string>(TUNNEL_CAUSES);
+
+function validIso(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 64 && Number.isFinite(Date.parse(value));
+}
+
+function validateTunnel(value: unknown, index: number): LinkTunnelDiagnostics {
+  const fail = (): never => { throw new Error(`invalid link API response: link ${index} tunnel`); };
+  if (!isRecord(value)) return fail();
+  assertExactKeys(value, ["attempt", "nextRetryAt", "lastTransition", "lastFailure"], `link ${index} tunnel`);
+  const { attempt, nextRetryAt, lastTransition, lastFailure } = value;
+  if (typeof attempt !== "number" || !Number.isSafeInteger(attempt) || attempt < 0) fail();
+  if (nextRetryAt !== null && !validIso(nextRetryAt)) fail();
+  if (lastTransition !== null) {
+    if (!isRecord(lastTransition)) return fail();
+    assertExactKeys(lastTransition, ["from", "to", "at", "cause"], `link ${index} tunnel transition`);
+    if (!WIRE_STATES.has(lastTransition.from as string) || !WIRE_STATES.has(lastTransition.to as string)
+      || !validIso(lastTransition.at) || (lastTransition.cause !== null && !CAUSES.has(lastTransition.cause as string))) fail();
+  }
+  if (lastFailure !== null) {
+    if (!isRecord(lastFailure)) return fail();
+    assertExactKeys(lastFailure, ["cause", "at"], `link ${index} tunnel failure`);
+    if (!CAUSES.has(lastFailure.cause as string) || !validIso(lastFailure.at)) fail();
+  }
+  return value as unknown as LinkTunnelDiagnostics;
+}
 
 function validateParity(candidate: Record<string, unknown>, index: number): LinkChildParity {
   const time = (key: "lastApplyAt" | "runtimeStartedAt" | "reportedAt"): number | null => {

package/src/cli/provider.ts

@@ -191,7 +191,7 @@ function handleList(args: string[], active: boolean = localProvidersActive()): v
     console.log(`  ${name}${isDefault}${source}  adapter=${prov.adapter}${model}`);
   }
 
-  const available = PROVIDER_REGISTRY.filter(e => !configured.includes(e.id));
+  const available = PROVIDER_REGISTRY.filter(e => !e.deprecated && !configured.includes(e.id));
   if (available.length > 0) {
     console.log(`\nAvailable from registry (${available.length}):\n`);
     for (const entry of available) {
@@ -265,6 +265,7 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
   const registryEntry = getProviderRegistryEntry(name);
 
   if (registryEntry) {
+    if (registryEntry.deprecated) console.warn(`Warning: provider "${name}" is deprecated: ${registryEntry.deprecated}`);
     provConfig = providerConfigSeed(registryEntry);
     if (apiKey) {
       const candidateError = providerCredentialInputError({ apiKey });

package/src/cli/usage-compare.ts

@@ -8,7 +8,11 @@ import { readClientConnectionState, sameClientConnectionOwner } from "../client/
 import { fetchHubUsage } from "../client/hub-client";
 import { readServiceApiTokenState, serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { readRuntimePort, type RuntimePortState } from "../config/process-state";
+import { isLocalAttestationSecret } from "../lib/local-management-attestation";
 import { redactSecretString } from "../lib/redact";
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { fetchBoundLocalManagementRead, type LocalManagementReadDeps } from "../server/local-management-read-client";
 import { rangeWindow, USAGE_SURFACES } from "../usage/summary";
 import type { UsageTimeWindow } from "../usage/time-range";
 import {
@@ -16,8 +20,7 @@ import {
   printData,
   rejectArgs,
   RuntimeApiError,
-  runtimeRequest,
-  runtimeBaseUrl,
+  PROXY_NOT_RUNNING_MESSAGE,
   takeFlag,
   takeOption,
   takeOptionWithSyntax,
@@ -29,7 +32,10 @@ export const USAGE_COMPARE_USAGE = `Usage:
       [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]`;
 
 export type CompareRange = "today" | "7d" | "30d";
-export type UsageCompareDeps = RuntimeApiDeps & { now?: () => number };
+export type UsageCompareDeps = RuntimeApiDeps & Pick<LocalManagementReadDeps, "directFetch"> & {
+  now?: () => number;
+  readRuntime?: typeof readRuntimePort;
+};
 
 const METRICS = ["requests", "totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "estimatedCostUsd"] as const;
 type Metric = typeof METRICS[number];
@@ -189,10 +195,60 @@ function captureUsageOwner() {
   const headers = runningProxyUpdateHeaders();
   const fingerprint = connection.kind === "connected" ? connection.value.tokenFingerprint
     : serviceApiTokenFingerprint(headers.get("X-OpenCodex-API-Key") ?? "");
-  return { connection, token, headers, fingerprint };
+  return { connection, token, fingerprint };
 }
 type UsageOwner = ReturnType<typeof captureUsageOwner>;
 
+function pinUsageRuntime(deps: UsageCompareDeps, owner: UsageOwner): (suffix: string) => Promise<ScopedUsage> {
+  const readRuntime = deps.readRuntime ?? readRuntimePort;
+  const initial = readRuntimePortForComparison();
+  const pinned = { ...initial };
+  let liveIdentity: string | undefined;
+  function readRuntimePortForComparison(): RuntimePortState {
+    const runtime = readRuntime();
+    if (!runtime || !isLocalAttestationSecret(runtime.attestationSecret)) {
+      throw new Error("Usage runtime unavailable: restart the proxy with an attested runtime record.");
+    }
+    return runtime;
+  }
+  function assertRuntime(): RuntimePortState {
+    const current = readRuntimePortForComparison();
+    if (current.pid !== pinned.pid || current.port !== pinned.port || current.hostname !== pinned.hostname
+      || current.attestationSecret !== pinned.attestationSecret) {
+      throw new Error("Usage runtime changed during comparison; no comparison was produced. Retry for the current runtime.");
+    }
+    return current;
+  }
+  return async suffix => {
+    assertRuntime();
+    const live = await (deps.findLiveProxy ?? findLiveProxy)();
+    assertRuntime();
+    assertUsageOwner(owner);
+    if (!live) throw new RuntimeApiError(PROXY_NOT_RUNNING_MESSAGE, 503, null, "proxy_not_running");
+    const identity = JSON.stringify([live.pid, live.port, live.hostname, live.source, live.role]);
+    if (live.source !== "runtime" || live.pid !== pinned.pid || live.port !== pinned.port
+      || probeHostname(live.hostname) !== probeHostname(pinned.hostname) || live.role === "client"
+      || (liveIdentity !== undefined && liveIdentity !== identity)) {
+      throw new Error("Usage runtime changed during comparison; no comparison was produced. Retry for the current runtime.");
+    }
+    liveIdentity = identity;
+    const read = await fetchBoundLocalManagementRead(live, `/api/usage?${suffix.replace(/^\?/, "")}`, {
+      fetchImpl: deps.fetchImpl, directFetch: deps.directFetch, readRuntime: assertRuntime,
+      timeoutMs: 60_000, requireResponseProof: true,
+    });
+    assertRuntime();
+    if (read.kind === "unavailable") {
+      throw new RuntimeApiError(`Local usage read unavailable (${read.reason}). No comparison was produced.`, 503, null);
+    }
+    if (!read.response.ok) {
+      throw new RuntimeApiError(`Usage request failed (HTTP ${read.response.status}). No comparison was produced.`, read.response.status, null);
+    }
+    const result = await read.response.json() as ScopedUsage;
+    assertRuntime();
+    return result;
+  };
+}
+
 function assertUsageOwner(owner: UsageOwner): void {
   const current = readClientConnectionState();
   const expected = owner.connection;
@@ -216,6 +272,7 @@ async function readUsage(
   apiKeyId: string | undefined,
   deps: RuntimeApiDeps,
   owner: UsageOwner,
+  localRead?: (suffix: string) => Promise<ScopedUsage>,
 ): Promise<ScopedUsage> {
   assertUsageOwner(owner);
   const { connection, token } = owner;
@@ -233,16 +290,15 @@ async function readUsage(
     result = await fetchHubUsage(connection.value.serverUrl, token.token, new URLSearchParams(suffix.replace(/^\?/, "")), {
       fetchImpl: peerFetch, timeoutMs: 60_000, ...(link ? { peer: "Home" as const } : {}),
     });
-  } else if (apiKeyId === undefined) {
-    result = await runtimeRequest(`/api/usage${suffix}`, { headers: owner.headers }, deps);
   } else {
     try {
-      result = await runtimeRequest(`/api/usage${suffix}`, { redirect: "error", credentials: "omit", headers: owner.headers }, deps);
+      result = await localRead!(suffix);
     } catch (error) {
-      if (error instanceof RuntimeApiError && error.code === "proxy_not_running") throw error;
+      if (apiKeyId === undefined) throw error;
+      if (error instanceof RuntimeApiError) throw error;
       throw new Error("Key-scoped usage could not be read. Check runtime access and retry.");
     }
-    if (result.filter?.apiKeyId !== apiKeyId) {
+    if (apiKeyId !== undefined && result.filter?.apiKeyId !== apiKeyId) {
       throw new Error("The server did not confirm the requested API key scope. Upgrade and restart the proxy, then retry.");
     }
   }
@@ -276,9 +332,9 @@ export async function handleUsageCompareCommand(argv: string[], deps: UsageCompa
   const windows = compareUsageWindows(range, now);
   const filters = { range, surface, provider, model, apiKeyId };
   const owner = captureUsageOwner();
-  const readDeps = owner.connection.kind === "disconnected" ? { ...deps, baseUrl: await runtimeBaseUrl(deps) } : deps;
-  const currentReport = await readUsage(query({ ...filters, since: windows.current.since, until: windows.current.until }), windows.current, apiKeyId, readDeps, owner);
-  const previousReport = await readUsage(query({ ...filters, since: windows.previous.since, until: windows.previous.until }), windows.previous, apiKeyId, readDeps, owner);
+  const localRead = owner.connection.kind === "disconnected" ? pinUsageRuntime(deps, owner) : undefined;
+  const currentReport = await readUsage(query({ ...filters, since: windows.current.since, until: windows.current.until }), windows.current, apiKeyId, deps, owner, localRead);
+  const previousReport = await readUsage(query({ ...filters, since: windows.previous.since, until: windows.previous.until }), windows.previous, apiKeyId, deps, owner, localRead);
   const current = totalsOf(currentReport);
   const previous = totalsOf(previousReport);
   const deltaTotals: Totals = {};

package/src/client/link-ingress.ts

@@ -76,7 +76,7 @@ function liftRequestIdleTimer(req: Request, server: Pick<Server<unknown>, "timeo
  *   fetch, so a rebinding or cross-site browser page cannot reach the Home through this port.
  * - Without the committed link key nothing is fetched, and the caller gets
  *   `503 link_credential_unavailable`.
- * - `/readyz` stays local: it reports this listener, not the tunnel.
+ * - `/readyz` stays local and is never relayed; the listener answers it from `link-readiness.ts`.
  * - A relayed request is exempt from the listener's idle limit, like a standalone data route.
  */
 export function handleLinkIngress(

package/src/client/link-readiness.ts

@@ -0,0 +1,97 @@
+/**
+ * Whether a Remote Link Child can serve relayed requests right now, for its `GET /readyz`.
+ *
+ * `/healthz` keeps meaning "this process answers". A Child whose tunnel is down still answers it,
+ * yet every relayed turn fails with 503, so readiness is where that shows: not ready, with one
+ * fixed reason word. Nothing here carries ssh output, host names, ports or keys.
+ *
+ * - A Child-initiated link reads its own tunnel supervisor; no network traffic.
+ * - A Home-initiated link has no local tunnel to inspect (the Home runs `ssh -R`), so it runs
+ *   the credential-free relay preflight through the tunnel port. One preflight runs at a time, a
+ *   verdict is reused for `LINK_READINESS_TTL_MS`, and a request waits at most
+ *   `LINK_READINESS_WAIT_MS` for a running preflight before it answers `link_unverified`. An
+ *   unauthenticated caller can therefore cause at most one preflight per TTL.
+ */
+import { LINK_RELAY_AUTH_TIMEOUT_MS } from "../link/relay-auth";
+import { isLinkPort } from "../link/ports";
+import { probeLinkRelayPreflight, type BoundLinkRelayTarget, type LinkRelayPreflightResult } from "./link-relay-transport";
+import type { ClientLinkSupervisorStatus } from "./link-tunnel";
+
+export type LinkReadinessReason =
+  | "tunnel_idle" | "tunnel_connecting" | "tunnel_failed" | "tunnel_unavailable" | "sidecar_invalid"
+  | "home_unreachable" | "home_unauthorized" | "link_auth_failed" | "link_credential_unavailable"
+  | "link_unverified";
+
+export type LinkReadiness = { ready: true } | { ready: false; reason: LinkReadinessReason };
+
+export const LINK_READINESS_TTL_MS = 5_000;
+export const LINK_READINESS_WAIT_MS = 500;
+
+const READY: LinkReadiness = { ready: true };
+const notReady = (reason: LinkReadinessReason): LinkReadiness => ({ ready: false, reason });
+
+/**
+ * A Child-initiated link from its supervisor. The keyed probe the supervisor runs every 30 seconds
+ * while connected is display-only for the tunnel, but a Home that stopped answering or refuses the
+ * key cannot serve a turn, so readiness follows it. A Home whose own startup readiness is pending
+ * still serves relayed requests (the probe's `home_not_ready`), so that reads ready.
+ */
+export function clientInitiatedLinkReadiness(status: ClientLinkSupervisorStatus): LinkReadiness {
+  if (status.kind === "failed") return notReady("sidecar_invalid");
+  if (status.kind === "stopped") return notReady("tunnel_idle");
+  const { state, probe } = status;
+  if (state.kind === "connected") {
+    if (probe === "home_unreachable") return notReady("home_unreachable");
+    if (probe === "unauthorized") return notReady("home_unauthorized");
+    return READY;
+  }
+  if (state.kind === "connecting" || state.kind === "reconnecting") return notReady("tunnel_connecting");
+  if (state.kind === "failed") return notReady(state.inFlight ? "tunnel_connecting" : "tunnel_failed");
+  return notReady("tunnel_idle");
+}
+
+function fromPreflight(result: LinkRelayPreflightResult): LinkReadiness {
+  if (result === "ok") return READY;
+  return notReady(result === "unreachable" ? "home_unreachable" : "link_auth_failed");
+}
+
+export interface HomeInitiatedLinkReadinessDeps {
+  target: Omit<BoundLinkRelayTarget, "admissionKey">;
+  linkKey: () => string | null;
+  probe?: (target: BoundLinkRelayTarget, options: { timeoutMs: number }) => Promise<LinkRelayPreflightResult>;
+  now?: () => number;
+  /** Resolves after `ms`; the wait for a running preflight. */
+  delay?: (ms: number) => Promise<void>;
+}
+
+/** The readiness of a Home-initiated link, from a shared, rate-limited relay preflight. */
+export function createHomeInitiatedLinkReadiness(deps: HomeInitiatedLinkReadinessDeps): () => Promise<LinkReadiness> {
+  const probe = deps.probe ?? probeLinkRelayPreflight;
+  const now = deps.now ?? Date.now;
+  const delay = deps.delay ?? (ms => new Promise<void>(resolve => {
+    const timer = setTimeout(resolve, ms);
+    (timer as { unref?: () => void }).unref?.();
+  }));
+  let last: { at: number; verdict: LinkReadiness } | undefined;
+  let flight: Promise<LinkReadiness> | undefined;
+  const run = (admissionKey: string): Promise<LinkReadiness> => {
+    flight ??= probe({ ...deps.target, admissionKey }, { timeoutMs: LINK_RELAY_AUTH_TIMEOUT_MS })
+      .then(fromPreflight, () => notReady("home_unreachable"))
+      .then(verdict => {
+        last = { at: now(), verdict };
+        return verdict;
+      })
+      .finally(() => { flight = undefined; });
+    return flight;
+  };
+  return async () => {
+    if (!isLinkPort(deps.target.tunnelPort)) return notReady("tunnel_unavailable");
+    let admissionKey: string | null;
+    try { admissionKey = deps.linkKey(); } catch { admissionKey = null; }
+    if (!admissionKey) return notReady("link_credential_unavailable");
+    const at = now();
+    if (last && at >= last.at && at - last.at < LINK_READINESS_TTL_MS) return last.verdict;
+    const unverified = notReady("link_unverified");
+    return await Promise.race([run(admissionKey), delay(LINK_READINESS_WAIT_MS).then(() => unverified)]);
+  };
+}

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

@@ -9,7 +9,7 @@ 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 {
@@ -27,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;
@@ -153,21 +161,76 @@ async function responseOnConnection(incoming: IncomingMessage, agent: SingleConn
 
 let peerReport: Record<string, string> | undefined;
 
-/** 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> {
+/** 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 {
-    // The challenge also carries this Child's version and features for the Home's link status.
-    peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), buildPeerFeatures());
-    const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: peerReport }, 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)) {
@@ -177,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(); }
 }