@bitkyc08/opencodex 2.68.0 → 2.69.0-preview.20260928

package/src/providers/quota/account-cache.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { getValidAccessTokenForAccount } from "../../oauth";
-import { getAccountCredential, getAccountSet } from "../../oauth/store";
+import { getAccountCredential, getAccountCredentialWithStatus, getAccountSet } from "../../oauth/store";
 import type { GenerationContext } from "../../lib/state-store-sweeper";
 import { ACCOUNT_QUOTA_TTL_MS, toFiniteNumber } from "../quota-wire";
 import { clearKiroAccountUsageState, hydrateKiroUsageVerdict, kiroPersistableVerdicts, reconcileKiroAccountUsageState } from "../kiro-usage";
@@ -437,8 +437,11 @@ export function clearAccountQuotaCache(provider?: string): void {
  *   Anthropic's lock only adopts disk credentials for `local-cli` rows.
  */
 export async function getTokenForAccountQuotaProbe(provider: string, accountId: string): Promise<string> {
-  const stored = getAccountCredential(provider, accountId);
-  if (!stored) throw new Error("account credential missing");
+  const row = getAccountCredentialWithStatus(provider, accountId);
+  if (!row) throw new Error("account credential missing");
+  // An operator-paused account is excluded from every automatic upstream use, quota reads included.
+  if (row.paused) throw new Error("account is paused; quota probe skipped");
+  const stored = row.credential;
   if (stored.expires > Date.now() + ACCOUNT_TOKEN_SKEW_MS) return stored.access;
   const activeId = getAccountSet(provider)?.activeAccountId;
   if (activeId !== accountId && stored.source === "local-cli") {
@@ -447,6 +450,17 @@ export async function getTokenForAccountQuotaProbe(provider: string, accountId:
   return getValidAccessTokenForAccount(provider, accountId);
 }
 
+/**
+ * Rows that must not be probed: an unsupported provider reads as unavailable, and a paused
+ * account returns its last reading unchanged (its `ts` shows the age) or an unavailable row,
+ * without writing the cache. Undefined means "probe normally".
+ */
+export function accountQuotaProbeSkip(provider: string, accountId: string): AccountQuotaCacheEntry | undefined {
+  if (!supportsPerAccountQuota(provider)) return { ts: Date.now(), quota: null, unavailable: true };
+  if (getAccountCredentialWithStatus(provider, accountId)?.paused !== true) return undefined;
+  return accountQuotaCache.get(accountCacheKey(provider, accountId)) ?? { ts: Date.now(), quota: null, unavailable: true };
+}
+
 export function explicitQuotaConfig(provider: string, configured?: OcxProviderConfig): OcxProviderConfig | undefined {
   if (configured) return configured;
   const entry = getProviderRegistryEntry(provider);

package/src/providers/quota/vendor-probes-oauth.ts

@@ -400,6 +400,8 @@ export async function fetchKiroQuota(provider: string): Promise<ProviderQuotaRep
 export async function fetchMuseKeyQuota(provider: string): Promise<ProviderQuotaReport | null> {
   const probedAccountId = getAccountSet(provider)?.activeAccountId;
   if (!probedAccountId) return null;
+  // A paused account is excluded from every automatic upstream use; a key mint is one.
+  if (getAccountSet(provider)?.accounts.find(account => account.id === probedAccountId)?.paused === true) return null;
   const oauthAccessToken = getAccountCredential(provider, probedAccountId)?.muse?.oauthAccessToken;
   // An imported or pasted credential has no account token and never will: it is
   // capability, not provider id, that decides whether a probe is possible.

package/src/providers/quota.ts

@@ -45,7 +45,7 @@ import {
   explicitQuotaConfig,
   explicitQuotaDestination,
   explicitQuotaIdentity,
-  getTokenForAccountQuotaProbe,
+  accountQuotaProbeSkip, getTokenForAccountQuotaProbe,
   hasPassiveAccountQuota,
   hydrateAccountQuotaCache,
   mayCommitAccountQuotaKey,
@@ -421,7 +421,7 @@ async function fetchAccountQuota(
   forceRefresh: boolean,
   providerConfig?: OcxProviderConfig,
 ): Promise<AccountQuotaCacheEntry> {
-  if (!supportsPerAccountQuota(provider)) return { ts: Date.now(), quota: null, unavailable: true };
+  if (accountQuotaProbeSkip(provider, accountId)) return accountQuotaProbeSkip(provider, accountId)!;
   if (explicitAccountReader(provider)) return fetchExplicitAccountQuota(provider, accountId, forceRefresh, providerConfig);
   if (provider === "anthropic" || provider === "kiro") hydrateAccountQuotaCache();
   const key = accountCacheKey(provider, accountId);

package/src/responses/code-mode-helper-compat.ts

@@ -3,13 +3,16 @@ import {
   normalizeApplyPatchDelimiters,
   unwrapFreeformToolInput,
 } from "./apply-patch-envelope";
-import { declaresCodeModeExec } from "../types/tools";
+import { declaresCodeModeExec, isCodeModeMcpDirectName } from "../types/tools";
 import { parseCodeModeShellInput } from "./code-mode-shell-input";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+/** A nested host tool reachable as `tools.<name>` when the flattened name is one identifier. */
+const CODE_MODE_IDENTIFIER_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
 /**
  * Convert a nested Code Mode helper call into unified-exec JavaScript.
  *
@@ -95,6 +98,16 @@ export function compileCodeModeHelperInput(
   if (helperName === "create_goal" || helperName === "get_goal" || helperName === "update_goal") {
     return `const result = await tools.${helperName}(${JSON.stringify(args)});\ntext(result);`;
   }
+  if (isCodeModeMcpDirectName(helperName)) {
+    // Direct `mcp__<server>__<tool>` call under a code-mode catalog: the emitted name IS the
+    // nested host tool's name, so compile to the same `tools.<name>(args)` the model could
+    // have written. Dot access when the name is a clean identifier (the common case); bracket
+    // access otherwise, so a hyphenated server name still addresses the same tool.
+    const target = CODE_MODE_IDENTIFIER_NAME.test(helperName)
+      ? `tools.${helperName}`
+      : `tools[${JSON.stringify(helperName)}]`;
+    return `const result = await ${target}(${JSON.stringify(args)});\ntext(result);`;
+  }
   return `const result = await tools.exec_command(${JSON.stringify(args)});\ntext(result);`;
 }
 

package/src/responses/custom-tool-compat.ts

@@ -76,7 +76,7 @@ export function routedCustomToolTargetName(
   if (wireName === undefined) return undefined;
   if (names.has(wireName)) return wireName;
   if (!isPlainObject(value) || typeof value.namespace === "string") return undefined;
-  const normalized = normalizeDeclaredToolName(wireName, declaredNames);
+  const normalized = normalizeDeclaredToolName(wireName, declaredNames, undefined, names);
   return normalized !== wireName && names.has(normalized) ? normalized : undefined;
 }
 

package/src/server/auth-cors.ts

@@ -973,6 +973,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   mcpMaxResultBytes: "editor",
   modelAdapters: "editor",
   fastWire: "editor",
+  responseTierAuthoritative: "editor",
   fastEnabled: "editor",
   baseUrl: "editor",
   responsesPath: "editor",

package/src/server/images.ts

@@ -37,7 +37,7 @@ import type { DataPlaneAdmission } from "./auth-cors";
 import { admissionScopeDenial } from "./admission-model-scope";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
-import { getValidAccessToken, getOAuthCredentialProjectId } from "../oauth/index";
+import { getValidAccessToken, getOAuthCredentialProjectId, OAuthAccountPausedError } from "../oauth/index";
 import { safeAntigravityHttpErrorMessage } from "../adapters/google-errors";
 import { sanitizeUpstreamErrorText } from "../adapters/upstream-http-error";
 import { ANTIGRAVITY_REQUEST_UA } from "../adapters/google-antigravity-wire";
@@ -56,6 +56,14 @@ import { codexModelAvailabilityErrorResponse } from "./responses/codex-auth-erro
 
 export type ImagesEndpoint = "generations" | "edits";
 
+function assertImagesUpstreamAuthorization(headers: Headers, config: OcxConfig): void {
+  const authorization = headers.get("authorization")?.trim() ?? "";
+  if (!/^Bearer[\t ]+[^\s,]+$/i.test(authorization)) {
+    throw new TypeError("invalid image upstream authorization");
+  }
+  validateForwardAdmissionCredential(headers, config);
+}
+
 /** Image generation is slow (tens of seconds); bound a hung upstream, not a working one. */
 const IMAGES_UPSTREAM_TIMEOUT_MS = 300_000;
 
@@ -275,6 +283,9 @@ async function tryCcaImageGeneration(
     if (linkedSignal.signal.aborted) {
       return formatErrorResponse(504, "upstream_error", "CCA image generation timed out during authentication");
     }
+    if (err instanceof OAuthAccountPausedError) {
+      return formatErrorResponse(403, "permission_error", err.message);
+    }
     // Missing/revoked credential → 401 (re-login required); transient refresh/network → 502.
     const errName = err instanceof Error ? err.name : "";
     if (errName === "OAuthLoginRequiredError") {
@@ -659,25 +670,41 @@ export async function handleImages(
   }
   const explicitKeyedProvider = config.images?.provider !== undefined && candidates.keyed !== undefined;
   // Admission bearer is valid proxy auth (requireApiAuth already passed) but must never be
-  // forwarded as OpenAI ChatGPT credentials. When the caller sent it, skip OpenAI forward
-  // and allow CCA / keyed paths instead of rejecting the whole request.
-  let skipOpenAiForwardForAdmissionBearer = false;
+  // forwarded as OpenAI ChatGPT credentials. Pool replaces it with a stored credential;
+  // Direct would consume the caller bearer, so only Direct becomes ineligible.
+  let callerBearerMayBeForwarded = true;
   if (!explicitKeyedProvider) {
     try { validateForwardAdmissionCredential(req.headers, config); }
     catch (err) {
       if (err instanceof ForwardAdmissionCredentialError) {
-        skipOpenAiForwardForAdmissionBearer = true;
+        callerBearerMayBeForwarded = false;
       } else {
         throw err;
       }
     }
   }
 
-  const canUseOpenAiForward = !skipOpenAiForwardForAdmissionBearer && candidates.forwardCandidates.length > 0;
+  // Both relay branches copy the body upstream, so the destination is the
+  // provider chosen in that branch and the model the caller named. A scoped key
+  // is checked against each forward destination BEFORE any stored credential is
+  // resolved, refreshed or leased, so a forbidden destination spends nothing.
+  const relaySelector = requestedImageSelector(body);
+  let forwardScopeDenial: Response | undefined;
+  const eligibleForwardCandidates = candidates.forwardCandidates.filter(candidate => {
+    if (!callerBearerMayBeForwarded && candidate.accountMode === "direct") return false;
+    const denial = admissionScopeDenial(config, admission, relaySelector, {
+      providerName: candidate.providerName,
+      modelId: relaySelector,
+    });
+    if (denial) forwardScopeDenial ??= denial;
+    return denial === undefined;
+  });
+  const canUseOpenAiForward = eligibleForwardCandidates.length > 0;
 
   if (!canUseOpenAiForward && !candidates.keyed) {
     const ccaResponse = await tryCcaImageGeneration(body, config, logCtx, req.signal, endpoint, admission);
     if (ccaResponse) return ccaResponse;
+    if (forwardScopeDenial) return forwardScopeDenial;
     // 400, not 5xx: codex retries every 5xx up to 5 total attempts, and this is a permanent
     // configuration state that must surface on the first attempt.
     return formatErrorResponse(
@@ -696,7 +723,7 @@ export async function handleImages(
   let forwardAuthError: Response | undefined;
   if (canUseOpenAiForward) {
     try {
-      forward = await resolveFirstUsableOpenAiSidecar(candidates.forwardCandidates, req.headers, config, {
+      forward = await resolveFirstUsableOpenAiSidecar(eligibleForwardCandidates, req.headers, config, {
         beginCodexAccountSelection: codexAccountSelectionForTurn(turnAdmissionLease),
       });
       if (forward) logCtx.provider = formatCodexProviderForLog(forward.providerName, codexLogAccountId(forward.authContext), config);
@@ -708,38 +735,48 @@ export async function handleImages(
       } else if (err instanceof CodexThreadAffinityExpiredError) {
         forwardAuthError = formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
       } else if (err instanceof CodexAuthContextError) {
-        const safeAccountLabel = formatCodexProviderForLog("openai", err.accountId, config);
-        console.error(`[images] Pool account ${safeAccountLabel} token failed; reauthentication required`);
+        console.error("[images] Pool credential failed; reauthentication required");
         forwardAuthError = formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
       } else if (err instanceof CodexModelAvailabilityError) {
         forwardAuthError = codexModelAvailabilityErrorResponse(err);
       } else if (err instanceof CodexPoolAuthenticationError) {
         forwardAuthError = formatErrorResponse(401, "authentication_error", err.message);
+      } else if (err instanceof TypeError) {
+        // The sidecar releases any acquired probe lease if credential materialization fails.
+        return formatErrorResponse(500, "internal_error", "image generation request failed forward credential validation");
       } else {
         throw err;
       }
     }
   }
 
-  const headers: Record<string, string> = { "content-type": "application/json" };
+  const headers = new Headers({ "content-type": "application/json" });
+  const releaseForwardProbe = (): void => {
+    try { forward?.releaseProbeLease?.(); }
+    catch { console.error("[images] Failed to release probe lease"); }
+  };
   let url: string;
-  // Both relay branches copy the body upstream, so the destination is the
-  // provider chosen in that branch and the model the caller named. Each branch
-  // is checked as it is entered, before it resolves a credential or commits a
-  // key rotation, so a refused request spends nothing.
-  const relaySelector = requestedImageSelector(body);
+  // Each branch is re-checked as it is entered: the forward check is defence in
+  // depth for the pre-filter above, and the keyed check runs before a key
+  // rotation is committed.
   if (forward) {
     const denial = admissionScopeDenial(config, admission, relaySelector, {
       providerName: forward.providerName,
       modelId: relaySelector,
     });
     if (denial) {
-      forward.releaseProbeLease?.();
+      releaseForwardProbe();
       return denial;
     }
     const { provider } = forward;
-    if (provider.headers) Object.assign(headers, provider.headers);
-    for (const [name, value] of forward.headers) headers[name] = value;
+    try {
+      for (const [name, value] of Object.entries(provider.headers ?? {})) headers.set(name, value);
+      for (const [name, value] of forward.headers) headers.set(name, value);
+      assertImagesUpstreamAuthorization(headers, config);
+    } catch {
+      releaseForwardProbe();
+      return formatErrorResponse(500, "internal_error", "image generation request failed forward credential validation");
+    }
     // The ChatGPT codex backend takes bare paths (matches the adapter's `${baseUrl}/responses`).
     url = `${provider.baseUrl}/images/${endpoint}`;
   } else if (forwardAuthError) {
@@ -783,8 +820,13 @@ export async function handleImages(
       );
     }
     const apiKey = warmKeyProvider?.apiKey ?? candidates.keyed.apiKey;
-    if (provider.headers) Object.assign(headers, provider.headers);
-    headers["authorization"] = `Bearer ${apiKey}`;
+    try {
+      for (const [name, value] of Object.entries(provider.headers ?? {})) headers.set(name, value);
+      headers.set("authorization", `Bearer ${apiKey}`);
+      assertImagesUpstreamAuthorization(headers, config);
+    } catch {
+      return formatErrorResponse(500, "internal_error", "image generation request failed forward credential validation");
+    }
     logCtx.provider = providerName;
     // Keyed providers tolerate baseUrl with or without /v1 (mirrors openai-responses.ts).
     url = `${provider.baseUrl.replace(/\/v1\/?$/, "")}/v1/images/${endpoint}`;
@@ -799,6 +841,11 @@ export async function handleImages(
     );
   }
 
+  if (req.signal.aborted) {
+    releaseForwardProbe();
+    return formatErrorResponse(499, "client_closed_request", `image ${endpoint} request canceled by client`);
+  }
+
   const timeoutMs = config.images?.timeoutMs ?? IMAGES_UPSTREAM_TIMEOUT_MS;
   const linkedSignal = signalWithTimeout(timeoutMs, req.signal);
   const sidecarExit = sidecarEnter("images");
@@ -846,6 +893,9 @@ export async function handleImages(
     // Client cancel first: it aborts the linked signal too, and must not be logged as an
     // upstream failure (499 maps to client_closed_request in the request log).
     if (req.signal.aborted) {
+      // No upstream outcome is recorded for a client cancel, so a recovery probe
+      // lease taken by the selected Pool account must be returned explicitly.
+      releaseForwardProbe();
       return formatErrorResponse(499, "client_closed_request", `image ${endpoint} request canceled by client`);
     }
     if (linkedSignal.signal.aborted || (err instanceof Error && err.name === "TimeoutError")) {

package/src/server/index/link-listener.ts

@@ -1,3 +1,4 @@
+import { createLinkRelaySessions } from "./link-relay-sessions";
 import type { Server } from "bun";
 import {
   emptyLinkStore,
@@ -13,6 +14,7 @@ export const LINK_INGRESS_HOSTNAME = "opencodex-link.invalid";
 export interface LinkListenerStartContext<T> {
   dispatch: (req: Request, server: Server<T>) => Promise<Response>;
   maxRequestBodySize: number;
+  keyFingerprints?: (apiKeyId: string) => readonly string[];
 }
 
 export interface LinkListenerDeps {
@@ -58,6 +60,7 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
   const serve = deps.serve ?? (options => Bun.serve(options));
   const warn = deps.warn ?? ((message: string) => console.warn(message));
   let listener: Server<T> | null = null;
+  let relaySessions: ReturnType<typeof createLinkRelaySessions> | undefined;
   let startContext: LinkListenerStartContext<T> | undefined;
   let ensureFlight: Promise<void> | undefined;
   let closeFlight: Promise<void> | undefined;
@@ -92,6 +95,10 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
       return;
     }
     const requestedPort = store.listenerPort ?? 0;
+    const sessions = createLinkRelaySessions({ fingerprints: (keyId, linkId) => {
+      if (!readStoreForAdmission().links.some(link => link.id === linkId && link.apiKeyId === keyId)) return [];
+      return startContext?.keyFingerprints?.(keyId) ?? [];
+    } });
     let bound: Server<unknown>;
     try {
       bound = serve({
@@ -101,7 +108,7 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
         // relayed turn that the Home holds or that streams with a long gap.
         idleTimeout: 255,
         maxRequestBodySize: startContext.maxRequestBodySize,
-        fetch: (req: Request, server: Server<unknown>) => startContext!.dispatch(req, server as Server<T>),
+        fetch: (req: Request, server: Server<unknown>) => sessions.dispatch(req, server as Server<T>, startContext!.dispatch),
       } as Parameters<typeof Bun.serve>[0]);
     } catch (error) {
       reportFailure("bind", error, "bind");
@@ -136,6 +143,7 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
       }
     }
     listener = bound as Server<T>;
+    relaySessions = sessions;
     setStatus("listening", bound.port ?? (requestedPort > 0 ? requestedPort : null), null);
   };
 
@@ -159,8 +167,13 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
     const flight = (async () => {
       if (ensureFlight) await ensureFlight;
       const current = listener;
-      listener = null;
-      if (current) await current.stop(true);
+      // Retain the bound port AND ingress ownership while an authenticated connection is
+      // reserved or a dispatched response is still being consumed. No new proofs are issued.
+      if (current) {
+        await relaySessions?.drain();
+        await current.stop(false);
+      }
+      if (listener === current) { listener = null; relaySessions = undefined; }
       // Closing is the caller saying "no links now": an earlier bind or persist failure no
       // longer describes anything, so the status reads off either way.
       setStatus("off", null, null);
@@ -194,6 +207,10 @@ export function createLinkListenerLifecycle<T>(deps: LinkListenerDeps = {}): Lin
     close,
     async stop() {
       stopped = true;
+      // Process shutdown is deliberately forceful, unlike last-link removal. Every
+      // authenticated socket is closed, and the client transport cannot reconnect it.
+      relaySessions?.abortReservations();
+      if (listener) await listener.stop(true);
       await close();
       startContext = undefined;
       setStatus("off", null, null);

package/src/server/index/link-relay-sessions.ts

@@ -0,0 +1,138 @@
+import type { Server } from "bun";
+import {
+  LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION,
+  LINK_RELAY_SESSION_HEADER, linkRelayProof, linkRelayProofMatches,
+} from "../../link/relay-auth";
+
+interface Session {
+  peer: string;
+  keyId: string;
+  linkId: string;
+  fingerprint: string;
+  expiresAt: number;
+  timer: ReturnType<typeof setTimeout>;
+  release: () => void;
+}
+
+export interface LinkRelaySessionOptions {
+  fingerprints: (keyId: string, linkId: string) => readonly string[];
+  /** Tests can use a bounded shorter reservation; production uses five seconds. */
+  reservationMs?: number;
+}
+
+/** One book per bound listener. A pending proof reserves the bind before the data request arrives. */
+export function createLinkRelaySessions(options: LinkRelaySessionOptions) {
+  const sessions = new Map<string, Session>();
+  const drains = new Set<() => void>();
+  let closing = false;
+  let active = 0;
+  const reservationMs = options.reservationMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
+  const refuse = () => new Response(null, { status: 404 });
+  const peerOf = (req: Request, server: Server<unknown>): string | null => {
+    const peer = server.requestIP(req);
+    return peer ? `${peer.address}:${peer.port}` : null;
+  };
+  const acquire = () => {
+    active += 1;
+    let done = false;
+    return () => {
+      if (done) return;
+      done = true;
+      if (--active === 0) { for (const resolve of drains) resolve(); drains.clear(); }
+    };
+  };
+  const consume = (nonce: string): Session | undefined => {
+    const session = sessions.get(nonce);
+    if (session) { clearTimeout(session.timer); sessions.delete(nonce); }
+    return session;
+  };
+
+  return {
+    /** Forced process shutdown retires unused proofs before closing their sockets. */
+    abortReservations(): void {
+      closing = true;
+      for (const nonce of [...sessions.keys()]) consume(nonce)?.release();
+    },
+    /** Refuse new work, but keep reservations and active bodies alive until they settle. */
+    async drain(): Promise<void> {
+      closing = true;
+      if (active > 0) await new Promise<void>(resolve => drains.add(resolve));
+    },
+    async dispatch<T>(req: Request, server: Server<T>, dispatch: (req: Request, server: Server<T>) => Promise<Response>): Promise<Response> {
+      const url = new URL(req.url);
+      if (url.pathname === LINK_RELAY_AUTH_PATH) {
+        if (closing || req.method !== "GET" || sessions.size >= 256 || req.headers.has("upgrade")
+          || req.headers.has("authorization") || req.headers.has("x-opencodex-api-key")) return refuse();
+        const q = url.searchParams;
+        if (q.get("version") !== LINK_RELAY_AUTH_VERSION || [...q.keys()].length !== 5
+          || ["version", "key", "link", "nonce", "proof"].some(name => q.getAll(name).length !== 1)) return refuse();
+        const keyId = q.get("key")!, linkId = q.get("link")!, nonce = q.get("nonce")!;
+        const peer = peerOf(req, server as Server<unknown>);
+        if (!peer || sessions.has(nonce)) return refuse();
+        const fingerprint = options.fingerprints(keyId, linkId).find(candidate =>
+          linkRelayProofMatches(q.get("proof"), linkRelayProof(candidate, "caller", keyId, linkId, nonce)));
+        if (!fingerprint) return refuse();
+        const release = acquire();
+        const timer = setTimeout(() => { consume(nonce)?.release(); }, reservationMs);
+        sessions.set(nonce, { peer, keyId, linkId, fingerprint, release, timer, expiresAt: Date.now() + reservationMs });
+        return new Response(null, { status: 204, headers: {
+          "x-opencodex-link-proof": linkRelayProof(fingerprint, "listener", keyId, linkId, nonce)!,
+          "cache-control": "no-store",
+        } });
+      }
+      const nonce = req.headers.get(LINK_RELAY_SESSION_HEADER);
+      let release: () => void;
+      if (nonce !== null) {
+        // A proof received on one HTTP socket never authorizes another socket, even on the same port.
+        const session = consume(nonce);
+        if (!session) return refuse();
+        release = session.release;
+        if (session.peer !== peerOf(req, server as Server<unknown>) || Date.now() >= session.expiresAt
+          || !options.fingerprints(session.keyId, session.linkId).includes(session.fingerprint)) {
+          release(); return refuse();
+        }
+        // Keep the native Request identity: Bun's requestIP/timeout APIs need the original request.
+        try { req.headers.delete(LINK_RELAY_SESSION_HEADER); } catch { release(); return refuse(); }
+      } else {
+        if (closing) return new Response(null, { status: 503 });
+        // Older peers may still use the ordinary key admission. Its response also owns a drain lease.
+        release = acquire();
+      }
+      // Socket cancellation before headers is terminal too; an upstream handler that is
+      // settling its own cleanup cannot keep a dead transport's listener lease forever.
+      const beforeHeadersAbort = () => release();
+      req.signal.addEventListener("abort", beforeHeadersAbort, { once: true });
+      if (req.signal.aborted) beforeHeadersAbort();
+      try {
+        const response = await dispatch(req, server);
+        req.signal.removeEventListener("abort", beforeHeadersAbort);
+        if (!response.body || req.method === "HEAD") { release(); return response; }
+        const reader = response.body.getReader();
+        let ended = false;
+        const finish = () => {
+          if (ended) return;
+          ended = true;
+          req.signal.removeEventListener("abort", aborted);
+          release();
+        };
+        const cancel = async (reason?: unknown) => {
+          try { await reader.cancel(reason); } finally { finish(); }
+        };
+        const aborted = () => { void cancel(req.signal.reason).catch(() => {}); };
+        req.signal.addEventListener("abort", aborted, { once: true });
+        if (req.signal.aborted) aborted();
+        const body = new ReadableStream<Uint8Array>({
+          async pull(controller) {
+            try {
+              const next = await reader.read();
+              if (next.done) { finish(); controller.close(); }
+              else controller.enqueue(next.value);
+            } catch (error) { finish(); controller.error(error); }
+          },
+          cancel,
+        }, { highWaterMark: 0 });
+        return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+      } catch (error) { req.signal.removeEventListener("abort", beforeHeadersAbort); release(); throw error; }
+    },
+  };
+}

package/src/server/index/optional-listeners.ts

@@ -1,3 +1,4 @@
+import { serviceApiTokenFingerprint } from "../../lib/service-secrets";
 import type { Server } from "bun";
 import type { OcxConfig } from "../../types";
 import {
@@ -81,7 +82,16 @@ export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): O
     linkSupervisor: () => supervisor,
     start(ctx) {
       activeConfig = ctx.config;
-      linkListener.start({ dispatch: ctx.dispatch, maxRequestBodySize: ctx.maxRequestBodySize });
+      linkListener.start({ dispatch: ctx.dispatch, maxRequestBodySize: ctx.maxRequestBodySize,
+        keyFingerprints: apiKeyId => {
+          const entry = activeConfig?.apiKeys?.find(candidate => candidate.id === apiKeyId);
+          if (!entry?.key) return [];
+          const fingerprints = [serviceApiTokenFingerprint(entry.key)];
+          const pending = entry.pendingRotation;
+          if (pending && Date.parse(pending.expiresAt) > Date.now()) fingerprints.push(serviceApiTokenFingerprint(pending.key));
+          return fingerprints;
+        },
+      });
       unregisterSupervisorAdmission ??= linkListener.onAuthenticatedCatalog(apiKeyId => supervisor.notifyAuthenticatedRequest?.(apiKeyId));
       if (linkListenerOwnsTarget(linkListener.status())) {
         supervisor.start();

package/src/server/index/serve-options.ts

@@ -170,6 +170,7 @@ import {
   createLocalAttestationProof,
 } from "../../lib/local-management-attestation";
 import { SYSTEM_RESTART_CAPABILITY_VERSION } from "../../lib/system-restart-contract";
+import { LOCAL_MANAGEMENT_NONCE_HEADER } from "../../lib/local-management-capability";
 import { LOCAL_PROVIDER_RELOAD_CAPABILITY_VERSION } from "../../lib/local-provider-reload-contract";
 import { LOCAL_ASIDE_SYNC_CAPABILITY_VERSION } from "../../lib/local-aside-sync-contract";
 import {
@@ -697,6 +698,17 @@ export function createServeOptions(ctx: ServeOptionsContext) {
           trustedLoopback: trustedLoopbackForIngress(ingress, config.hostname ?? "127.0.0.1"),
           guiSessionIssuance: managementSessionIssuance(req, managementAuth),
         });
+        // A local read capability authenticates the request; sign its single-use nonce so the
+        // caller can tell this answer came from this process and not from whoever holds the port.
+        const readNonce = principal === "local-read-capability" ? req.headers.get(LOCAL_MANAGEMENT_NONCE_HEADER) : null;
+        const readProof = readNonce
+          ? createLocalAttestationProof(localAttestationSecret, readNonce, process.pid, localManagementAuth.port) : null;
+        if (mgmtResponse && readProof) {
+          const headers = new Headers(mgmtResponse.headers);
+          headers.set(LOCAL_ATTESTATION_PROOF_HEADER, readProof);
+          const signed = new Response(mgmtResponse.body, { status: mgmtResponse.status, statusText: mgmtResponse.statusText, headers });
+          return withManagementCors(signed, req, config);
+        }
         if (mgmtResponse) return withManagementCors(mgmtResponse, req, config);
         return withManagementCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
       }

package/src/server/inference/client-encoder-delivery.ts

@@ -91,6 +91,7 @@ export interface ClientEncodedDelivery {
     declaredToolNames?: ReadonlySet<string>;
     toolParameterSchemas?: ReadonlyMap<string, Record<string, unknown>>;
     freeformToolNames?: Set<string>;
+    bareCustomToolNames?: ReadonlySet<string>;
     toolSearchToolNames?: Set<string>;
   };
   stallTimeoutSec?: number;

package/src/server/local-management-read-client.ts

@@ -1,5 +1,9 @@
 import { readRuntimePort, type RuntimePortState } from "../config/process-state";
-import { createLocalAttestationChallenge } from "../lib/local-management-attestation";
+import {
+  LOCAL_ATTESTATION_PROOF_HEADER,
+  createLocalAttestationChallenge,
+  verifyLocalAttestationProof,
+} from "../lib/local-management-attestation";
 import {
   LOCAL_MANAGEMENT_CAPABILITY_HEADER,
   LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
@@ -14,7 +18,10 @@ import { probeHostname, type LiveProxy } from "./proxy-liveness";
 
 export type LocalManagementReadResult =
   | { kind: "response"; response: Response; targetPid: number }
-  | { kind: "unavailable"; reason: "unattested-target" | "runtime-mismatch" | "capability-unavailable" | "transport" };
+  | {
+    kind: "unavailable";
+    reason: "unattested-target" | "runtime-mismatch" | "capability-unavailable" | "transport" | "unattested-response";
+  };
 
 export interface LocalManagementReadDeps {
   fetchImpl?: typeof fetch;
@@ -25,6 +32,12 @@ export interface LocalManagementReadDeps {
 
 export interface LocalManagementReadRequestDeps extends LocalManagementReadDeps {
   timeoutMs?: number;
+  /**
+   * Require the response to carry the server's attestation over this request's nonce. The
+   * capability authenticates the request to the real server; only this proof tells the caller
+   * that the answer came from it and not from whatever process now holds the port.
+   */
+  requireResponseProof?: boolean;
 }
 
 /**
@@ -83,6 +96,12 @@ export async function fetchBoundLocalManagementRead(
         signal: AbortSignal.timeout(deps.timeoutMs ?? 4_000),
       },
     );
+    if (deps.requireResponseProof && !verifyLocalAttestationProof(
+      runtime.attestationSecret, nonce, target.pid, target.port, response.headers.get(LOCAL_ATTESTATION_PROOF_HEADER),
+    )) {
+      void response.body?.cancel().catch(() => {});
+      return { kind: "unavailable", reason: "unattested-response" };
+    }
     return { kind: "response", response, targetPid: target.pid };
   } catch {
     return { kind: "unavailable", reason: "transport" };