@iislee/opencodex 2.11.0 → 2.31.0

package/src/server/management-auth.ts

@@ -13,7 +13,33 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { adminApiTokenFilePath } from "../lib/admin-secrets";
-import { forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import {
+  LOCAL_MANAGEMENT_CAPABILITY_HEADER,
+  LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
+  LOCAL_MANAGEMENT_EXPECTED_PID_HEADER,
+  LOCAL_MANAGEMENT_NONCE_HEADER,
+  parseExpectedLocalManagementPid,
+  verifyLocalManagementReadCapability,
+} from "../lib/local-management-capability";
+import {
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  parseExpectedSystemRestartPid,
+  verifySystemRestartCapability,
+} from "../lib/system-restart-contract";
+import {
+  LOCAL_PROVIDER_RELOAD_CAPABILITY_HEADER,
+  LOCAL_PROVIDER_RELOAD_EXPECTED_PID_HEADER,
+  LOCAL_PROVIDER_RELOAD_EXPIRES_AT_HEADER,
+  LOCAL_PROVIDER_RELOAD_NAME_HEADER,
+  LOCAL_PROVIDER_RELOAD_NONCE_HEADER,
+  LOCAL_PROVIDER_RELOAD_PATH,
+  parseExpectedLocalProviderReloadPid,
+  verifyLocalProviderReloadCapability,
+} from "../lib/local-provider-reload-contract";
+import { forgetEphemeralSecretPath, forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import type { OcxConfig } from "../types";
 import {
   isAllowedManagementOrigin,
@@ -26,6 +52,12 @@ import {
 
 const GUI_SESSION_TTL_MS = 5 * 60_000;
 const GUI_SESSION_LIMIT = 128;
+const LOCAL_READ_REPLAY_LIMIT = 256;
+const consumedLocalReadCapabilities = new Map<string, number>();
+const admittedLocalReadRequests = new WeakSet<Request>();
+const LOCAL_PROVIDER_RELOAD_REPLAY_LIMIT = 256;
+const consumedLocalProviderReloadCapabilities = new Map<string, number>();
+const admittedLocalProviderReloadRequests = new WeakSet<Request>();
 
 interface GuiSessionRecord {
   csrfToken: string;
@@ -95,12 +127,17 @@ function readExistingToken(path: string): string {
 export function removeManagementTokenPathBestEffort(
   path: string,
   remove: (path: string) => void = unlinkSync,
+  options?: { ephemeral?: boolean },
 ): void {
+  // Temps get the full ephemeral release (success + both timeout namespaces);
+  // stable token paths drop only the success memo — destination-keyed timeout
+  // memos are intentional anti-restall state.
+  const forget = options?.ephemeral ? forgetEphemeralSecretPath : forgetHardenedSecretPath;
   try {
     remove(path);
-    forgetHardenedSecretPath(path);
+    forget(path);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") forgetHardenedSecretPath(path);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") forget(path);
     /* other failures retain fail-closed state for the caller */
   }
 }
@@ -120,7 +157,8 @@ function createTokenFile(path: string): string {
     chmodSync(temporary, 0o600);
     let temporaryHardened: { ok: boolean };
     try {
-      temporaryHardened = hardenSecretPath(temporary, { required: true });
+      // Destination-keyed timeout memo (the final token path), not the temp.
+      temporaryHardened = hardenSecretPath(temporary, { required: true, timeoutMemoKey: path });
     } catch {
       temporaryHardened = { ok: false };
     }
@@ -155,7 +193,7 @@ function createTokenFile(path: string): string {
     if (fd !== null) {
       try { closeSync(fd); } catch { /* best effort */ }
     }
-    removeManagementTokenPathBestEffort(temporary);
+    removeManagementTokenPathBestEffort(temporary, unlinkSync, { ephemeral: true });
   }
 }
 
@@ -231,11 +269,188 @@ export function issueGuiSession(
   return { token, ...session };
 }
 
+/**
+ * Which credential actually authorized a management request.
+ *
+ * `admin-token` is the raw token from disk/env: anything running as the user can
+ * read it, including a coding agent. `gui-session` is a session token this process
+ * minted for a browser, and it only authorizes a mutation after the origin and the
+ * per-session CSRF token match. Consent-bearing routes must key off this value
+ * rather than off request headers, which the token holder can forge freely.
+ * The capability principals are process-scoped HMACs bound to the current process
+ * PID and listening port. Local reads are accepted only for two exact GET paths;
+ * restart and provider reload remain separate wire contracts for their exact POSTs.
+ */
+export type ManagementPrincipal =
+  | "admin-token"
+  | "gui-session"
+  | "local-read-capability"
+  | "local-provider-reload-capability"
+  | "system-restart-capability";
+
+export interface LocalManagementAuthContext {
+  attestationSecret: string;
+  pid: number;
+  port: number;
+}
+
+function hasSystemRestartCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+): boolean {
+  if (!local || req.method !== "POST") return false;
+  let path: string;
+  try {
+    path = new URL(req.url).pathname;
+  } catch {
+    return false;
+  }
+  if (path !== SYSTEM_RESTART_PATH) return false;
+  const expectedPid = parseExpectedSystemRestartPid(
+    req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
+  );
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  return verifySystemRestartCapability(
+    local.attestationSecret,
+    req.headers.get(SYSTEM_RESTART_NONCE_HEADER),
+    req.method,
+    path,
+    local.pid,
+    local.port,
+    req.headers.get(SYSTEM_RESTART_CAPABILITY_HEADER),
+  );
+}
+
+function hasLocalReadCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+): boolean {
+  // requireManagementAuth and managementPrincipal inspect the same Request in
+  // sequence. Preserve that one admission without accepting a replayed request.
+  if (admittedLocalReadRequests.has(req)) return true;
+  if (!local || req.method !== "GET") return false;
+  let url: URL;
+  try {
+    url = new URL(req.url);
+  } catch {
+    return false;
+  }
+  // Do not let a future query-bearing variant silently inherit this narrow grant.
+  if (url.search !== "") return false;
+  const expectedPid = parseExpectedLocalManagementPid(
+    req.headers.get(LOCAL_MANAGEMENT_EXPECTED_PID_HEADER),
+  );
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  const expiresAtRaw = req.headers.get(LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER);
+  if (!expiresAtRaw || !/^[1-9]\d*$/.test(expiresAtRaw)) return false;
+  const expiresAt = Number(expiresAtRaw);
+  if (!Number.isSafeInteger(expiresAt)) return false;
+  const capability = req.headers.get(LOCAL_MANAGEMENT_CAPABILITY_HEADER);
+  const now = Date.now();
+  if (!verifyLocalManagementReadCapability(
+    local.attestationSecret,
+    req.headers.get(LOCAL_MANAGEMENT_NONCE_HEADER),
+    req.method,
+    url.pathname,
+    local.pid,
+    local.port,
+    expiresAt,
+    capability,
+    now,
+  )) return false;
+  for (const [consumed, retainedUntil] of consumedLocalReadCapabilities) {
+    if (retainedUntil <= now) consumedLocalReadCapabilities.delete(consumed);
+  }
+  if (!capability || consumedLocalReadCapabilities.has(capability)) return false;
+  if (consumedLocalReadCapabilities.size >= LOCAL_READ_REPLAY_LIMIT) return false;
+  consumedLocalReadCapabilities.set(capability, expiresAt);
+  admittedLocalReadRequests.add(req);
+  return true;
+}
+
+function hasLocalProviderReloadCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+): boolean {
+  if (admittedLocalProviderReloadRequests.has(req)) return true;
+  if (!local || req.method !== "POST") return false;
+  let url: URL;
+  try {
+    url = new URL(req.url);
+  } catch {
+    return false;
+  }
+  if (url.pathname !== LOCAL_PROVIDER_RELOAD_PATH || url.search !== "") return false;
+  const contentLength = req.headers.get("content-length");
+  if (contentLength !== "0" || req.headers.has("transfer-encoding")) return false;
+  const expectedPid = parseExpectedLocalProviderReloadPid(
+    req.headers.get(LOCAL_PROVIDER_RELOAD_EXPECTED_PID_HEADER),
+  );
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  const expiresAtRaw = req.headers.get(LOCAL_PROVIDER_RELOAD_EXPIRES_AT_HEADER);
+  if (!expiresAtRaw || !/^[1-9]\d*$/.test(expiresAtRaw)) return false;
+  const expiresAt = Number(expiresAtRaw);
+  if (!Number.isSafeInteger(expiresAt)) return false;
+  const name = req.headers.get(LOCAL_PROVIDER_RELOAD_NAME_HEADER);
+  const capability = req.headers.get(LOCAL_PROVIDER_RELOAD_CAPABILITY_HEADER);
+  const now = Date.now();
+  if (!verifyLocalProviderReloadCapability(
+    local.attestationSecret,
+    req.headers.get(LOCAL_PROVIDER_RELOAD_NONCE_HEADER),
+    req.method,
+    url.pathname,
+    name,
+    local.pid,
+    local.port,
+    expiresAt,
+    capability,
+    now,
+  )) return false;
+  for (const [consumed, retainedUntil] of consumedLocalProviderReloadCapabilities) {
+    if (retainedUntil <= now) consumedLocalProviderReloadCapabilities.delete(consumed);
+  }
+  if (!capability || consumedLocalProviderReloadCapabilities.has(capability)) return false;
+  if (consumedLocalProviderReloadCapabilities.size >= LOCAL_PROVIDER_RELOAD_REPLAY_LIMIT) return false;
+  consumedLocalProviderReloadCapabilities.set(capability, expiresAt);
+  admittedLocalProviderReloadRequests.add(req);
+  return true;
+}
+
+/**
+ * The principal for a request that already passed `requireManagementAuth`. Kept as a
+ * separate resolution (rather than a changed return type) so every existing caller
+ * keeps its `Response | null` contract. Browser and admin principals are derived
+ * from the same session table and CSRF comparison the gate uses; the restart
+ * principal is derived from the same process-scoped capability check.
+ */
+export function managementPrincipal(
+  req: Request,
+  state: ManagementAuthState,
+  config?: OcxConfig,
+  local?: LocalManagementAuthContext,
+): ManagementPrincipal | null {
+  if (hasSystemRestartCapability(req, local)) return "system-restart-capability";
+  if (hasLocalProviderReloadCapability(req, local)) return "local-provider-reload-capability";
+  if (hasLocalReadCapability(req, local)) return "local-read-capability";
+  if (!state.available) return null;
+  const actual = req.headers.get("x-opencodex-api-key")?.trim()
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!actual) return null;
+  if (equalSecret(actual, state.token)) return "admin-token";
+  if (!config) return null;
+  removeExpiredSessions(state);
+  return state.sessions.has(actual) ? "gui-session" : null;
+}
+
 export function requireManagementAuth(
   req: Request,
   state: ManagementAuthState,
   config?: OcxConfig,
+  local?: LocalManagementAuthContext,
 ): Response | null {
+  if (hasSystemRestartCapability(req, local)) return null;
+  if (hasLocalProviderReloadCapability(req, local)) return null;
+  if (hasLocalReadCapability(req, local)) return null;
   if (!state.available) {
     return Response.json({
       error: "management API unavailable",

package/src/server/passive-route-linker.ts

@@ -0,0 +1,66 @@
+/**
+ * Optional per-attempt route-identity linker.
+ *
+ * Compatibility Lab attaches an opaque route-subject digest to request attempts so its
+ * passive-production surface (CL-09) can correlate them later. That is an opt-in
+ * subsystem, so the core request path holds only a slot: null on installs that never
+ * activate Lab, which is every install without a routing profile.
+ *
+ * Contract for any registered implementation: synchronous, free of side effects with
+ * respect to the request, and non-throwing. The upstream request must never be delayed,
+ * retried, or altered by identity linkage. The try/catch lives here rather than at the
+ * call site so the guarantee belongs to the mechanism instead of being restated by every
+ * caller.
+ *
+ * See devlog/_fin/260814_lab_core_decoupling/020_request_path_gate.md
+ */
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { InboundWire } from "../providers/registry";
+
+export type PassiveRouteLinker = (
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+) => string | null;
+
+let linker: PassiveRouteLinker | null = null;
+
+/** Install the linker. Returns a detach function. */
+export function setPassiveRouteLinker(next: PassiveRouteLinker): () => void {
+  linker = next;
+  return () => {
+    // Only detach our own registration: a later activation may have replaced it.
+    if (linker === next) linker = null;
+  };
+}
+
+/**
+ * Resolve the attempt identity, or null when no subsystem is active.
+ * Never throws: linkage is best-effort metadata and must not affect the request.
+ */
+export function resolvePassiveRouteSubjectId(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+): string | null {
+  if (!linker) return null;
+  try {
+    return linker(config, providerName, modelId, routed, inboundWire);
+  } catch {
+    return null;
+  }
+}
+
+/** True when an optional subsystem has installed a linker. Test/diagnostic use. */
+export function hasPassiveRouteLinker(): boolean {
+  return linker !== null;
+}
+
+/** Test-only reset. */
+export function resetPassiveRouteLinkerForTests(): void {
+  linker = null;
+}

package/src/server/ports.ts

@@ -57,6 +57,16 @@ export type FindAvailablePortOptions = {
    * update restart cannot hop to a random ephemeral listener (PR #152 gap).
    */
   allowEphemeralFallback?: boolean;
+  /**
+   * A port this selection must never return, even when it is free (#1102).
+   *
+   * The unauthenticated loopback listener binds a fixed port from config. If the public
+   * listener took that port first — via an explicit `--port`, a `config.port` of 0, or the
+   * ephemeral fallback happening to land on it — the loopback bind would then fail with
+   * EADDRINUSE, and the startup transaction would roll back a public listener that had
+   * nothing wrong with it. Excluding the port here fails the right thing at the right time.
+   */
+  reservedPort?: number;
 };
 
 export class PortUnavailableError extends Error {
@@ -75,6 +85,12 @@ export async function findAvailablePort(
 ): Promise<number> {
   const preferRetryMs = opts.preferRetryMs ?? 0;
   const allowEphemeral = opts.allowEphemeralFallback !== false;
+  const reserved = opts.reservedPort;
+  // An explicit preference for the reserved port is a configuration mistake, not a busy
+  // socket: retrying or hopping would hide it. Refuse before probing anything.
+  if (reserved !== undefined && preferredPort === reserved) {
+    throw new PortUnavailableError(preferredPort, hostname);
+  }
   // Port 0 asks the OS to select an ephemeral port. Resolve it to that concrete
   // port here so callers never persist or advertise an unusable `:0` endpoint.
   if (preferredPort > 0 && preferRetryMs > 0) {
@@ -92,7 +108,31 @@ export async function findAvailablePort(
     throw new PortUnavailableError(preferredPort, hostname);
   }
 
-  return await new Promise((resolve, reject) => {
+  // Bounded, not recursive. The OS can hand back the reserved port, and a redraw practically
+  // always differs — but "practically always" is not a termination argument, and an unbounded
+  // async recursion has no way to stop if the assumption is ever wrong.
+  for (let attempt = 0; attempt < EPHEMERAL_REDRAW_LIMIT; attempt += 1) {
+    const port = await allocateEphemeralPort(hostname);
+    if (port !== reserved) return port;
+  }
+  throw new Error("failed to allocate an available port");
+}
+
+/** How many times an ephemeral draw may come back reserved before we give up. */
+const EPHEMERAL_REDRAW_LIMIT = 8;
+
+/** Test seam: replace the OS ephemeral allocator so the redraw path is reachable. */
+let ephemeralAllocator: ((hostname: string) => Promise<number>) | null = null;
+
+export function setEphemeralPortAllocatorForTests(
+  allocator: ((hostname: string) => Promise<number>) | null,
+): void {
+  ephemeralAllocator = allocator;
+}
+
+async function allocateEphemeralPort(hostname: string): Promise<number> {
+  if (ephemeralAllocator) return ephemeralAllocator(hostname);
+  return await new Promise<number>((resolve, reject) => {
     const server = createServer();
     server.once("error", reject);
     server.once("listening", () => {

package/src/server/proxy-liveness.ts

@@ -10,6 +10,7 @@
  * Lives outside cli.ts (which dispatches argv at module top level) so tests can import it.
  */
 import { loadConfig, readAlivePid, readRuntimePort, verifyPidIdentity } from "../config";
+import { directLocalHttpFetch } from "./direct-local-http";
 
 export interface HealthzIdentity {
   service?: unknown;
@@ -17,6 +18,9 @@ export interface HealthzIdentity {
   version?: unknown;
   uptime?: unknown;
   pid?: unknown;
+  port?: unknown;
+  restartCapability?: unknown;
+  providerReloadCapability?: unknown;
 }
 
 export interface LivenessIo {
@@ -47,6 +51,9 @@ export interface LivenessIo {
   nowFn?: () => number;
 }
 
+/** Default per-probe fetch ceiling shared by liveness and readiness probes. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 750;
+
 /** Default probe options for service stop / orphan cleanup — a just-bound proxy can miss a single 750ms probe. */
 export const SERVICE_STOP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"> = {
   timeoutMs: 1500,
@@ -92,10 +99,10 @@ export async function proxyIdentityAt(
   opts: { hostname?: string; expectedPid?: number } = {},
   io: LivenessIo = {},
 ): Promise<{ pid: number | null } | null> {
-  const fetchFn = io.fetchFn ?? fetch;
+  const fetchFn = io.fetchFn ?? directLocalHttpFetch;
   const sleepFn = io.sleepFn ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
   const nowFn = io.nowFn ?? Date.now;
-  const baseTimeoutMs = io.timeoutMs ?? 750;
+  const baseTimeoutMs = io.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
   const requestedAttempts = Math.trunc(io.attempts ?? 1);
   const attempts = Number.isNaN(requestedAttempts)
     ? 1
@@ -138,6 +145,11 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
   const verifyPidFn = io.verifyPidFn ?? verifyPidIdentity;
   const readRuntimeFn = io.readRuntimeFn ?? readRuntimePort;
   const configFn = io.configFn ?? loadConfig;
+  const nowFn = io.nowFn ?? Date.now;
+  const deadlineAt = io.deadlineAt;
+  const probeIo: LivenessIo = io;
+  const budgetExhausted = (): boolean =>
+    deadlineAt !== undefined && nowFn() >= deadlineAt;
 
   // The cheap pid is discovery-only. Before it can appear in a returned (killable) result
   // it must pass the full identity check AND the verifier must echo the exact candidate —
@@ -160,8 +172,9 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
   if (pid) {
     const runtime = readRuntimeFn(pid);
     if (runtime?.port) {
+      if (budgetExhausted()) return null;
       probedPort = runtime.port;
-      const identity = await proxyIdentityAt(runtime.port, { hostname: runtime.hostname, expectedPid: pid }, io);
+      const identity = await proxyIdentityAt(runtime.port, { hostname: runtime.hostname, expectedPid: pid }, probeIo);
       if (identity) {
         // healthz confirmed the pid itself → trusted; a pidless legacy body did not,
         // so the cheap pid must pass full identity verification before it is returned.
@@ -176,8 +189,9 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
   // identity-probe it so ensure/update/stop see the live proxy instead of shadowing it.
   const record = readRuntimeFn();
   if (record?.port && record.port !== probedPort) {
+    if (budgetExhausted()) return null;
     const expectedPid = typeof record.pid === "number" ? record.pid : undefined;
-    const identity = await proxyIdentityAt(record.port, { hostname: record.hostname, expectedPid }, io);
+    const identity = await proxyIdentityAt(record.port, { hostname: record.hostname, expectedPid }, probeIo);
     // Only the healthz-reported pid is authoritative here. The record's pid may be stale
     // (its process dead, the port reused by a pidless legacy proxy) — synthesizing it
     // would hand destructive callers (stopProxy → kill fallback) a reusable pid.
@@ -188,7 +202,8 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
 
   const config = configFn();
   const port = config.port ?? 10100;
-  const identity = await proxyIdentityAt(port, { hostname: config.hostname }, io);
+  if (budgetExhausted()) return null;
+  const identity = await proxyIdentityAt(port, { hostname: config.hostname }, probeIo);
   if (identity) {
     return {
       pid: verifiedReportedPid(identity.pid) ?? killablePid(pid),
@@ -199,3 +214,115 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
   }
   return null;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Readiness (/readyz) strict probe.
+//
+// Liveness (/healthz) confirms the process answers; readiness confirms the
+// post-startup Codex sync has settled. A readiness probe is identity-checked the
+// same way liveness is, AND additionally enforces the full /readyz contract so
+// an adversarial or malformed body can never count as ready:
+//
+//  - HTTP 200 is required for status="ready"; HTTP 503 is required for pending
+//    or failed. Any other HTTP/body-status pairing is an invalid contract.
+//  - body.service must be exactly "opencodex".
+//  - body.version must be a non-empty string.
+//  - body.uptime must be a finite nonnegative number.
+//  - body.pid must be a positive integer; when `expectedPid` is supplied it must
+//    match exactly.
+//  - body.port must be an integer in 1..65535 and equal the probed port.
+//  - body.status must be exactly one of pending|ready|failed.
+//
+// Any unreachable, foreign, legacy, malformed, mismatched, or self-inconsistent
+// response returns `null` so callers can never treat an invalid identity/contract
+// as ready.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface ReadyzBody {
+  service?: unknown;
+  version?: unknown;
+  uptime?: unknown;
+  pid?: unknown;
+  port?: unknown;
+  status?: unknown;
+}
+
+export interface ReadinessProbeResult {
+  /** True ONLY for a valid 200 + status="ready" body with a matching pid. */
+  ready: boolean;
+  /** Fixed sanitized status. A foreign/unreadable body yields a `null` RESULT, never a `null` status. */
+  status: "ready" | "pending" | "failed";
+  /** Positive integer pid from a valid body. */
+  pid: number;
+  /** Integer port from a valid body. */
+  port: number;
+}
+
+export interface ReadinessProbeIo {
+  fetchFn?: typeof fetch;
+  timeoutMs?: number;
+}
+
+const READYZ_STATUS_VALUES = new Set<"ready" | "pending" | "failed">(["ready", "pending", "failed"]);
+
+/**
+ * Validate a parsed /readyz body against the strict contract. Returns the
+ * sanitized probe result, or `null` when the body is foreign, legacy,
+ * malformed, or fails the pid/port checks. Pure (no I/O) so it is fully
+ * deterministic and unit-testable.
+ */
+export function validateReadyzBody(
+  body: unknown,
+  port: number,
+  opts: { expectedPid?: number } = {},
+): ReadinessProbeResult | null {
+  if (!body || typeof body !== "object") return null;
+  const b = body as ReadyzBody;
+  if (b.service !== "opencodex") return null;
+  if (typeof b.version !== "string" || b.version.length === 0) return null;
+  if (typeof b.uptime !== "number" || !Number.isFinite(b.uptime) || b.uptime < 0) return null;
+  if (typeof b.pid !== "number" || !Number.isInteger(b.pid) || b.pid <= 0) return null;
+  if (
+    typeof b.port !== "number"
+    || !Number.isInteger(b.port)
+    || b.port < 1
+    || b.port > 65535
+    || b.port !== port
+  ) return null;
+  if (typeof b.status !== "string" || !READYZ_STATUS_VALUES.has(b.status as "ready" | "pending" | "failed")) return null;
+  const status = b.status as "ready" | "pending" | "failed";
+  if (opts.expectedPid !== undefined && b.pid !== opts.expectedPid) return null;
+  return { ready: status === "ready", status, pid: b.pid, port: b.port };
+}
+
+/**
+ * Identity- and contract-checked /readyz probe. Returns `null` when the
+ * endpoint is unreachable or the body fails the strict contract (foreign 200,
+ * legacy health-only body, non-JSON, missing/malformed/mismatched fields,
+ * wrong port/pid, or an HTTP/body-status inconsistency). Returns
+ * `{ready:false, ...}` when the body is ours but pending or failed. Returns
+ * `{ready:true, ...}` ONLY for a valid 200 body with `status:"ready"` and (when
+ * requested) a matching pid.
+ */
+export async function probeReadiness(
+  port: number,
+  opts: { hostname?: string; expectedPid?: number } = {},
+  io: ReadinessProbeIo = {},
+): Promise<ReadinessProbeResult | null> {
+  const fetchFn = io.fetchFn ?? directLocalHttpFetch;
+  try {
+    const res = await fetchFn(`http://${probeHostname(opts.hostname)}:${port}/readyz`, {
+      signal: AbortSignal.timeout(io.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS),
+    });
+    // Parse even on 503: /readyz returns JSON with a sanitized status while pending.
+    const body = (await res.json().catch(() => null)) as unknown;
+    const parsed = validateReadyzBody(body, port, opts);
+    if (!parsed) return null;
+    // HTTP/body-status consistency: ready requires 200; pending/failed require 503.
+    if (parsed.status === "ready" && res.status !== 200) return null;
+    if (parsed.status !== "ready" && res.status !== 503) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}