@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/server/management/system-routes.ts

@@ -14,16 +14,20 @@
  * it is not a standalone leak discriminator. `responseState` attributes growth
  * further: it is the proxy's previous_response_id continuation store, so a
  * growing responseState.totalBytes under rising observed memory points at
- * conversation retention rather than the runtime allocator.
+ * conversation retention rather than the runtime allocator. Spill counts,
+ * payload-byte totals, tombstones, and failure counters remain finite scalars;
+ * response ids, filenames, digests, paths, and payload content never leave the owner.
  *
  * `activeTurnCount` / `isDraining` are scalar lifecycle counters for the
  * dashboard drain-and-restart confirm UX — never request bodies or IDs.
  */
-import { decideEagerRelay } from "../../lib/bun-stream-caps";
+import { selectEagerPath } from "../../lib/bun-stream-caps";
 import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
 import { responseStateMetrics } from "../../responses/state";
+import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
 import { jsonResponse } from "../auth-cors";
+import { getInspectionCounters } from "../relay";
 import type { ManagementContext } from "./context";
 import { acceptSystemRestart } from "./system-restart";
 
@@ -64,6 +68,12 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       })()
       : null;
     const streamMode = config.streamMode ?? "auto";
+    /**
+     * No request-specific rewrite context exists on this route, so report the
+     * effective no-client-rewrite baseline. Individual rewrite requests still
+     * stay on tee even when this baseline says eager.
+     */
+    const eagerRelay = selectEagerPath(process.platform, false, streamMode);
     return jsonResponse({
       pid: process.pid,
       bunVersion: Bun.version,
@@ -79,8 +89,10 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
 	      observedMetric: observed.observedMetric,
 	      jscHeap,
       responseState: responseStateMetrics(),
+      appOwnedBytes: appOwnedBytesSnapshot(),
+      inspectionCounters: getInspectionCounters(),
       streamMode,
-      eagerRelay: process.platform === "win32" ? decideEagerRelay(streamMode) : null,
+      eagerRelay,
       watchdog,
       activeTurnCount: getActiveTurnCount(),
       isDraining: isDraining(),

package/src/server/management/usage-summary-cache.ts

@@ -0,0 +1,86 @@
+import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../../lib/app-owned-memory";
+import type { UsageSummary } from "../../usage/summary";
+
+export type CachedUsageSummary = UsageSummary & {
+  historyTruncated: boolean;
+  truncatedPrefixBytes: number;
+  entriesTruncated: boolean;
+  entriesDropped: number;
+};
+
+interface UsageSummaryCacheEntry {
+  revisionKey: string;
+  expiresAt: number;
+  summary: CachedUsageSummary;
+  revisionReadAt: number;
+  sizeBytes: number;
+}
+
+const usageSummaryCache = new Map<string, UsageSummaryCacheEntry>();
+let usageSummaryCacheBytes = 0;
+let oldestUsageSummaryKey: string | undefined;
+let oldestUsageSummaryAt: number | null = null;
+
+function recomputeOldestUsageSummary(): void {
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+  for (const [key, entry] of usageSummaryCache) {
+    const readAt = entry.revisionReadAt;
+    if (oldestUsageSummaryAt !== null && readAt >= oldestUsageSummaryAt) continue;
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = readAt;
+  }
+}
+
+function deleteUsageSummaryCacheEntry(key: string): number {
+  const entry = usageSummaryCache.get(key);
+  if (!entry) return 0;
+  usageSummaryCache.delete(key);
+  usageSummaryCacheBytes = Math.max(0, usageSummaryCacheBytes - entry.sizeBytes);
+  if (oldestUsageSummaryKey === key) recomputeOldestUsageSummary();
+  return entry.sizeBytes;
+}
+
+export function getUsageSummaryCacheEntry(key: string): UsageSummaryCacheEntry | undefined {
+  return usageSummaryCache.get(key);
+}
+
+export function discardUsageSummaryCacheEntry(key: string): number {
+  return deleteUsageSummaryCacheEntry(key);
+}
+
+export function setUsageSummaryCacheEntry(
+  key: string,
+  entry: Omit<UsageSummaryCacheEntry, "sizeBytes">,
+): void {
+  deleteUsageSummaryCacheEntry(key);
+  const sizeBytes = Buffer.byteLength(JSON.stringify({ key, ...entry }), "utf8");
+  usageSummaryCache.set(key, { ...entry, sizeBytes });
+  usageSummaryCacheBytes += sizeBytes;
+  if (oldestUsageSummaryAt === null || entry.revisionReadAt < oldestUsageSummaryAt) {
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = entry.revisionReadAt;
+  }
+  enforceAppOwnedMemoryBudget();
+}
+
+export function usageSummaryRetainedStoreSnapshot(): RetainedStoreSnapshot {
+  return {
+    count: usageSummaryCache.size,
+    bytes: usageSummaryCacheBytes,
+    evictableBytes: usageSummaryCacheBytes,
+    pinnedBytes: 0,
+    oldestAt: oldestUsageSummaryAt,
+  };
+}
+
+export function evictOldestUsageSummaryForBudget(): number {
+  return oldestUsageSummaryKey === undefined ? 0 : deleteUsageSummaryCacheEntry(oldestUsageSummaryKey);
+}
+
+export function resetUsageSummaryCacheForTests(): void {
+  usageSummaryCache.clear();
+  usageSummaryCacheBytes = 0;
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+}

package/src/server/management-api.ts

@@ -21,7 +21,7 @@ import {
   submitManualLoginCode,
   upsertOAuthProvider,
 } from "../oauth";
-import { removeCredential } from "../oauth/store";
+import { OAuthMutationBusyError, removeCredential } from "../oauth/store";
 import { providerDestinationResolvedError } from "../lib/destination-policy";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../oauth/key-providers";
 import { deriveProviderPresets } from "../providers/derive";
@@ -69,6 +69,8 @@ import { handleSidebarRoutes } from "./management/sidebar-routes";
 import type { ManagementContext } from "./management/context";
 export type { ManagementApiDeps } from "./management/context";
 import { fetchAllModels } from "./management/shared";
+import { CatalogGatherBusyError } from "../codex/catalog/provider-fetch";
+import { managementBodyTooLargeResponse } from "./management/body";
 
 // installed npm version instead of a stale hardcode.
 export const VERSION = (() => {
@@ -123,8 +125,9 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     } catch { /* best-effort */ }
   }
   const ctx: ManagementContext = { req, url, config, deps, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort };
-  const routed =
-    (await handleConfigRoutes(ctx))
+  let routed: Response | null;
+  try {
+    routed = (await handleConfigRoutes(ctx))
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleProviderRoutes(ctx))
     ??     (await handleModelRoutes(ctx))
@@ -132,7 +135,22 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     ??     (await handleOauthAccountRoutes(ctx))
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
-    ??     (await handleSidebarRoutes(ctx));
+      ?? (await handleSidebarRoutes(ctx));
+  } catch (error) {
+    const tooLarge = managementBodyTooLargeResponse(error, req, config);
+    if (tooLarge) return tooLarge;
+    if (error instanceof OAuthMutationBusyError) {
+      return new Response(JSON.stringify({ error: { type: "server_error", code: "oauth_mutation_busy", message: error.message } }), {
+        status: 503,
+        headers: { "content-type": "application/json", "Retry-After": "1" },
+      });
+    }
+    if (!(error instanceof CatalogGatherBusyError)) throw error;
+    return new Response(JSON.stringify({ error: { type: "server_error", code: "catalog_busy", message: error.message } }), {
+      status: 503,
+      headers: { "content-type": "application/json", "Retry-After": "1" },
+    });
+  }
   if (routed) return routed;
 
   if (url.pathname === "/api/stop" && req.method === "POST") {
@@ -167,7 +185,23 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
 
   if (url.pathname.startsWith("/api/codex-auth/")) {
     const { handleCodexAuthAPI } = await import("../codex/auth-api");
-    return handleCodexAuthAPI(req, url, config);
+    const { ConfigMutationLockError } = await import("../config");
+    const { CodexCredentialRefreshLockTimeoutError } = await import("../codex/account-store");
+    try {
+      return await handleCodexAuthAPI(req, url, config);
+    } catch (error) {
+      // Credential writers remap ConfigMutationLockError to CodexCredentialRefreshLockTimeoutError;
+      // treat both as the same retryable busy response.
+      if (error instanceof ConfigMutationLockError || error instanceof CodexCredentialRefreshLockTimeoutError) {
+        return jsonResponse(
+          { error: "Configuration is busy; retry shortly", code: "CONFIG_MUTATION_LOCK_UNAVAILABLE" },
+          503,
+          req,
+          config,
+        );
+      }
+      throw error;
+    }
   }
 
   return null;

package/src/server/management-auth.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { adminApiTokenFilePath } from "../lib/admin-secrets";
-import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import type { OcxConfig } from "../types";
 import {
   isAllowedManagementOrigin,
@@ -55,8 +55,19 @@ function assertSafeDirectory(path: string): void {
   const stat = lstatSync(path);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("management token directory is not a regular directory");
   chmodSync(path, 0o700);
-  const hardened = hardenSecretDir(path, { required: true });
-  if (!hardened.ok) throw new Error("management token directory ACL hardening did not complete");
+  let hardened: { ok: boolean };
+  try {
+    hardened = hardenSecretDir(path, { required: true });
+  } catch {
+    // required:true hardening now fails closed on genuine ACL timeouts too;
+    // keep the actionable guidance in the surfaced reason.
+    hardened = { ok: false };
+  }
+  if (!hardened.ok) {
+    throw new Error(
+      "management token directory ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+    );
+  }
 }
 
 function readExistingToken(path: string): string {
@@ -65,15 +76,33 @@ function readExistingToken(path: string): string {
     throw new Error("management token path is not a regular secret file");
   }
   chmodSync(path, 0o600);
-  const hardened = hardenSecretPath(path, { required: true });
-  if (!hardened.ok) throw new Error("management token file ACL hardening did not complete");
+  let hardened: { ok: boolean };
+  try {
+    hardened = hardenSecretPath(path, { required: true });
+  } catch {
+    hardened = { ok: false };
+  }
+  if (!hardened.ok) {
+    throw new Error(
+      "management token file ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+    );
+  }
   const token = readFileSync(path, "utf8").trim();
   if (!/^ocx_admin_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error("management token file is invalid");
   return token;
 }
 
-function removeBestEffort(path: string): void {
-  try { unlinkSync(path); } catch { /* fail-closed state is preserved by the caller */ }
+export function removeManagementTokenPathBestEffort(
+  path: string,
+  remove: (path: string) => void = unlinkSync,
+): void {
+  try {
+    remove(path);
+    forgetHardenedSecretPath(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") forgetHardenedSecretPath(path);
+    /* other failures retain fail-closed state for the caller */
+  }
 }
 
 function createTokenFile(path: string): string {
@@ -89,8 +118,17 @@ function createTokenFile(path: string): string {
     closeSync(fd);
     fd = null;
     chmodSync(temporary, 0o600);
-    const temporaryHardened = hardenSecretPath(temporary, { required: true });
-    if (!temporaryHardened.ok) throw new Error("management token temporary ACL hardening did not complete");
+    let temporaryHardened: { ok: boolean };
+    try {
+      temporaryHardened = hardenSecretPath(temporary, { required: true });
+    } catch {
+      temporaryHardened = { ok: false };
+    }
+    if (!temporaryHardened.ok) {
+      throw new Error(
+        "management token temporary ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+      );
+    }
     try {
       linkSync(temporary, path);
       linked = true;
@@ -98,17 +136,26 @@ function createTokenFile(path: string): string {
       if ((error as NodeJS.ErrnoException).code === "EEXIST") return readExistingToken(path);
       throw error;
     }
-    const finalHardened = hardenSecretPath(path, { required: true });
-    if (!finalHardened.ok) throw new Error("management token file ACL hardening did not complete");
+    let finalHardened: { ok: boolean };
+    try {
+      finalHardened = hardenSecretPath(path, { required: true });
+    } catch {
+      finalHardened = { ok: false };
+    }
+    if (!finalHardened.ok) {
+      throw new Error(
+        "management token file ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+      );
+    }
     return token;
   } catch (error) {
-    if (linked) removeBestEffort(path);
+    if (linked) removeManagementTokenPathBestEffort(path);
     throw error;
   } finally {
     if (fd !== null) {
       try { closeSync(fd); } catch { /* best effort */ }
     }
-    removeBestEffort(temporary);
+    removeManagementTokenPathBestEffort(temporary);
   }
 }
 
@@ -190,7 +237,11 @@ export function requireManagementAuth(
   config?: OcxConfig,
 ): Response | null {
   if (!state.available) {
-    return Response.json({ error: "management API unavailable" }, { status: 503 });
+    return Response.json({
+      error: "management API unavailable",
+      reason: state.reason,
+      hint: "Set OPENCODEX_ADMIN_AUTH_TOKEN to bypass file-backed admin token ACL hardening",
+    }, { status: 503 });
   }
   const actual = req.headers.get("x-opencodex-api-key")?.trim()
     || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();

package/src/server/port-reclaim.ts

@@ -2,8 +2,11 @@
  * Reclaim a listen port after stop/update so restart can stay on the configured
  * port instead of hopping to an ephemeral one (Windows CLOSE_WAIT / leftover ocx).
  *
- * Killing is never the default: a process may be killed only when the caller
- * supplies a non-empty explicit PID allowlist for a process it just stopped.
+ * Killing is never the default. A process may be killed only when the caller
+ * sets `killOcxHolders` and either supplies a non-empty `onlyKillPids` allowlist
+ * (trusted teardown PIDs, including allowlisted holders that fail ocx revalidate)
+ * or enables `killAllOcxOnPort` for revalidated ocx listeners. Unknown foreign
+ * (non-ocx, non-allowlisted) processes are never killed.
  */
 import { execFileSync } from "node:child_process";
 import { verifyPidIdentity } from "../config";
@@ -19,13 +22,24 @@ export type ReclaimListenPortOptions = WaitForPortOptions & {
   /**
    * When true AND `onlyKillPids` is a non-empty allowlist, those PIDs may be
    * killed after revalidation. Default false — never kill without an allowlist.
+   * When {@link killAllOcxOnPort} is also true, any ocx listener on this port
+   * may be killed even if it is not in `onlyKillPids`.
    */
   killOcxHolders?: boolean;
   /**
    * Explicit PIDs the caller just stopped / hard-killed. An omitted or empty
-   * list means no process may be killed.
+   * list means no process may be killed — unless {@link killAllOcxOnPort} is set.
    */
   onlyKillPids?: number[];
+  /**
+   * When true with `killOcxHolders`, every live ocx listener on this port may be
+   * killed (re-checked each scan). Used by post-update restart so a Windows
+   * service wrapper that respawns a *new* bun PID mid-reclaim cannot stay
+   * protected just because it was absent from the pre-wait allowlist snapshot.
+   * Never kills foreign (non-ocx) processes — only allowlisted teardown PIDs
+   * and revalidated ocx listeners.
+   */
+  killAllOcxOnPort?: boolean;
   /**
    * On Windows, force-delete IPv4 TCP rows for this local port via SetTcpEntry.
    * Default true on win32. Never kills foreign processes, never runs while a
@@ -157,9 +171,9 @@ export function listListenPids(port: number): number[] {
 
 /**
  * Wait until `port` can bind.
- * Never kills a process unless `killOcxHolders === true` and `onlyKillPids` is a
- * non-empty allowlist of PIDs the caller itself just stopped — then revalidates
- * immediately before each kill.
+ * Never kills a process unless `killOcxHolders === true` and either
+ * `onlyKillPids` is a non-empty allowlist or `killAllOcxOnPort` is set — then
+ * revalidates immediately before each kill.
  * Never kills foreign processes. Never drops TCP rows while a live foreign or
  * protected ocx listener owns the port, or when the listener scan failed.
  */
@@ -174,7 +188,9 @@ export async function reclaimListenPort(
   const allowedKillPids = new Set(
     (opts.onlyKillPids ?? []).filter(pid => Number.isSafeInteger(pid) && pid > 0),
   );
-  const mayKill = opts.killOcxHolders === true && allowedKillPids.size > 0;
+  const killAllOcx = opts.killAllOcxOnPort === true;
+  const mayKill = opts.killOcxHolders === true
+    && (allowedKillPids.size > 0 || killAllOcx);
   const dropTcpRows = opts.dropTcpRows ?? process.platform === "win32";
   const listFn = opts.listListenPidsFn ?? scanListenPids;
   const isAliveFn = opts.isAliveFn ?? isProcessAlive;
@@ -207,20 +223,44 @@ export async function reclaimListenPort(
 
       for (const pid of scan.pids) {
         if (pid === process.pid) continue;
-        if (!isAliveFn(pid)) continue; // Windows may still list a dead owner briefly
+        if (!isAliveFn(pid)) {
+          // Clear "already tried" so a later respawn that reuses this PID slot
+          // is not skipped (Windows service :loop / npm rename respawns).
+          killed.delete(pid);
+          continue; // Windows may still list a dead owner briefly
+        }
         const isOcx = verifyOcxFn(pid) === pid;
+        const allowlisted = allowedKillPids.has(pid);
+        // Pre-update PIDs can fail verify while still LISTENing (dead owner still
+        // listed, or cmdline probe raced). Allowlisted teardown PIDs may be killed;
+        // unknown foreign claimants must remain fail-closed.
         if (!isOcx) {
+          if (mayKill && allowlisted) {
+            if (!killed.has(pid)) {
+              try {
+                killFn(pid);
+                killed.add(pid);
+              } catch {
+                // Kill failed: never SetTcpEntry while the process may still own the port.
+                protectedOcxListener = true;
+              }
+            }
+            if (!isAliveFn(pid)) killed.delete(pid);
+            else protectedOcxListener = true;
+            continue;
+          }
           foreignLive = true;
           continue;
         }
-        if (!mayKill || !allowedKillPids.has(pid)) {
+        const mayKillThis = allowlisted || killAllOcx;
+        if (!mayKill || !mayKillThis) {
           // Healthy / intentional ocx proxy — never steal its port.
           protectedOcxListener = true;
           continue;
         }
         if (!killed.has(pid)) {
           // Revalidate immediately before termination.
-          if (isAliveFn(pid) && verifyOcxFn(pid) === pid && allowedKillPids.has(pid)) {
+          if (isAliveFn(pid) && verifyOcxFn(pid) === pid && mayKillThis) {
             try {
               killFn(pid);
               killed.add(pid);
@@ -233,8 +273,14 @@ export async function reclaimListenPort(
             protectedOcxListener = true;
           }
         }
-        // Only reset TCP rows after confirmed process death.
-        if (isAliveFn(pid)) protectedOcxListener = true;
+        // Respawning supervisors (Windows service :loop) mint a new PID after each
+        // kill — clear the per-PID "already tried" bit once the process is gone so a
+        // later child with a reused slot is not skipped, and keep reclaiming while live.
+        if (!isAliveFn(pid)) {
+          killed.delete(pid);
+        } else {
+          protectedOcxListener = true;
+        }
       }
 
       if (foreignLive || protectedOcxListener) {

package/src/server/ports.ts

@@ -16,6 +16,8 @@ export function isAddrInUse(err: unknown): boolean {
 export async function isPortAvailable(port: number, hostname = "127.0.0.1"): Promise<boolean> {
   return await new Promise(resolve => {
     const server = createServer();
+    // Fail closed: EACCES / EADDRNOTAVAIL / EPERM / unknown listen errors mean the
+    // requested bind is not available. Only the listening event reports free.
     server.once("error", () => resolve(false));
     server.once("listening", () => {
       server.close(() => resolve(true));

package/src/server/proxy-liveness.ts

@@ -30,8 +30,29 @@ export interface LivenessIo {
   readRuntimeFn?: (pid?: number) => { pid?: number; port: number; hostname?: string } | null;
   configFn?: () => { port?: number; hostname?: string };
   timeoutMs?: number;
+  /**
+   * How many times to retry a probe that failed with a transport error (timeout /
+   * connection refused). Definitive answers (non-OK HTTP, foreign /healthz body, pid
+   * mismatch) do not retry. Default 1 = no retry. Stop paths should pass 2–3 (#764).
+   */
+  attempts?: number;
+  sleepFn?: (ms: number) => Promise<void>;
+  /**
+   * Absolute wall-clock deadline for discovery. When set, each probe attempt aborts
+   * once the remaining budget cannot cover another fetch — so multi-candidate
+   * `findLiveProxy` under `SERVICE_STOP_LIVENESS` cannot overrun the stop-path
+   * verification window (#764 / CodeRabbit).
+   */
+  deadlineAt?: number;
+  nowFn?: () => number;
 }
 
+/** 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,
+  attempts: 3,
+};
+
 export interface LiveProxy {
   pid: number | null;
   port: number;
@@ -72,19 +93,37 @@ export async function proxyIdentityAt(
   io: LivenessIo = {},
 ): Promise<{ pid: number | null } | null> {
   const fetchFn = io.fetchFn ?? fetch;
-  try {
-    const res = await fetchFn(`http://${probeHostname(opts.hostname)}:${port}/healthz`, {
-      signal: AbortSignal.timeout(io.timeoutMs ?? 750),
-    });
-    if (!res.ok) return null;
-    const body = (await res.json().catch(() => null)) as HealthzIdentity | null;
-    if (!isOpencodexHealthz(body)) return null;
-    const pid = typeof body?.pid === "number" ? body.pid : null;
-    if (opts.expectedPid !== undefined && pid !== null && pid !== opts.expectedPid) return null;
-    return { pid };
-  } catch {
-    return null;
+  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 requestedAttempts = Math.trunc(io.attempts ?? 1);
+  const attempts = Number.isNaN(requestedAttempts)
+    ? 1
+    : Math.max(1, Math.min(requestedAttempts, 5));
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const remainingMs = io.deadlineAt === undefined ? baseTimeoutMs : io.deadlineAt - nowFn();
+    if (remainingMs <= 0) return null;
+    const timeoutMs = Math.min(baseTimeoutMs, remainingMs);
+    try {
+      const res = await fetchFn(`http://${probeHostname(opts.hostname)}:${port}/healthz`, {
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!res.ok) return null;
+      const body = (await res.json().catch(() => null)) as HealthzIdentity | null;
+      if (!isOpencodexHealthz(body)) return null;
+      const pid = typeof body?.pid === "number" ? body.pid : null;
+      if (opts.expectedPid !== undefined && pid !== null && pid !== opts.expectedPid) return null;
+      return { pid };
+    } catch {
+      // Transport failure (timeout / refused) — retry while budget remains; a proxy that
+      // has only just begun listening can miss a single short probe (#764).
+      if (attempt >= attempts) return null;
+      if (io.deadlineAt !== undefined && io.deadlineAt - nowFn() <= 0) return null;
+      await sleepFn(100);
+    }
   }
+  return null;
 }
 
 /**
@@ -109,6 +148,13 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
     return verified === candidate ? verified : null;
   };
 
+  const verifiedReportedPid = (reported: number | null): number | null => {
+    if (reported === null) return null;
+    if (!Number.isSafeInteger(reported) || reported <= 0) return null;
+    const verified = verifyPidFn(reported);
+    return verified === reported ? verified : null;
+  };
+
   const pid = readPidFn();
   let probedPort: number | null = null;
   if (pid) {
@@ -136,7 +182,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
     // (its process dead, the port reused by a pidless legacy proxy) — synthesizing it
     // would hand destructive callers (stopProxy → kill fallback) a reusable pid.
     if (identity) {
-      return { pid: identity.pid ?? null, port: record.port, hostname: record.hostname, source: "runtime" };
+      return { pid: verifiedReportedPid(identity.pid), port: record.port, hostname: record.hostname, source: "runtime" };
     }
   }
 
@@ -145,7 +191,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
   const identity = await proxyIdentityAt(port, { hostname: config.hostname }, io);
   if (identity) {
     return {
-      pid: identity.pid ?? killablePid(pid),
+      pid: verifiedReportedPid(identity.pid) ?? killablePid(pid),
       port,
       hostname: config.hostname,
       source: "config",

package/src/server/relay-eager.ts

@@ -24,11 +24,15 @@
  * up to the drain window.
  */
 
+import { buildFailedTailPayload } from "./relay";
+
 export type EagerRelayHooks = {
   /** Feed one upstream chunk through SSE inspection (createSseInspector.feed). */
   inspectChunk: (chunk: Uint8Array) => void;
   /** Flush inspection at upstream end (createSseInspector.finish). */
   finishInspection: () => void;
+  /** Drop inspector-owned frame/item state during producer teardown. */
+  disposeInspection?: () => void;
   /** True once inspection has reported a protocol terminal (inspector.reported). */
   sawTerminal: () => boolean;
   /** Record a synthetic terminal (caller decides incomplete vs failed-502). */
@@ -151,25 +155,37 @@ export function relaySseEagerBounded(
           await paused();
         }
       }
-    } catch {
+    } catch (err) {
       // Upstream read failure. Distinguish genuine mid-stream reset from
       // abort-driven teardown (shutdown/cancel-expiry) — audit M3.
       if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
-        syntheticKind = "failed";
-        try { controllerRef?.error(new Error("upstream stream failed")); } catch { /* torn down */ }
+        // Serializing `err` can run user-defined accessors (Error.message
+        // getters, toString) that re-entrantly cancel the client or abort the
+        // upstream. Build the tail FIRST, then re-check eligibility before
+        // committing to the synthetic terminal (adversarial review blocker).
+        const tail = new TextEncoder().encode(
+          `\n\nevent: response.failed\ndata: ${buildFailedTailPayload(err)}\n\ndata: [DONE]\n\n`,
+        );
+        if (!hooks.sawTerminal() && !cancelled && !upstream.signal.aborted) {
+          syntheticKind = "failed";
+          queuedBytes += tail.byteLength;
+          try { controllerRef?.enqueue(tail); } catch { /* client already torn down */ }
+          try { controllerRef?.close(); } catch { /* client already torn down */ }
+        }
       }
     } finally {
       if (syntheticKind) hooks.onSynthetic(syntheticKind);
       if (cancelled && !hooks.sawTerminal()) {
         hooks.onClientCancel();
       }
-      if (cancelled || upstream.signal.aborted) {
+      if (cancelled || upstream.signal.aborted || syntheticKind === "failed") {
         upstream.abort();
         reader.cancel().catch(() => {});
       }
       if (!cancelled) {
         try { controllerRef?.close(); } catch { /* already closed/errored */ }
       }
+      try { hooks.disposeInspection?.(); } catch { /* inspection teardown must not block lifecycle cleanup */ }
       fireDone();
     }
   };