@bitkyc08/opencodex 2.26.0 → 2.28.0

package/src/responses/state.ts

@@ -1,4 +1,5 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { uptime } from "node:os";
 import { dirname, join } from "node:path";
 import { atomicWriteFileAsync, getConfigDir, resolveWriteTarget } from "../config";
 import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
@@ -31,6 +32,17 @@ const SNAPSHOT_FILE_MAX_BYTES = 32 * 1024 * 1024;
 const STALE_TEMP_GRACE_MS = 15 * 60 * 1_000;
 const STALE_TEMP_MAX_ENTRIES = 4_096;
 const STALE_TEMP_MAX_CLEANUPS = 512;
+/** Absorbs `os.uptime()` granularity only. It is deliberately NOT the safety margin:
+ *  the unconditional 15-minute grace above is (see the boot floor in the scan loop). */
+const BOOT_FLOOR_SKEW_MS = 60 * 1_000;
+/** Per-tick budget for the periodic reclaim. Smaller than the startup budget because the
+ *  periodic pass runs synchronously on the serving process's event loop every 60 s. */
+const PERIODIC_TEMP_MAX_ENTRIES = 512;
+const PERIODIC_TEMP_MAX_CLEANUPS = 64;
+/** Wall-clock ceiling for one periodic scan. An entry cap bounds syscalls, not time: on a
+ *  network-mounted config dir each `lstat` can cost 10-20 ms, which would stall in-flight
+ *  streams. Reclaim is idempotent, so a truncated tick simply resumes on the next one. */
+const PERIODIC_TEMP_SCAN_DEADLINE_MS = 25;
 const RESPONSE_STATE_TEMP_NAME = /^responses-state\.json\.ocx\.(\d+)\.(\d+)\.tmp$/;
 const MAX_SNAPSHOT_REWRITE_ATTEMPTS = 4;
 
@@ -494,19 +506,37 @@ export interface ResponseStateTempRecoveryResult {
   removed: number;
   failed: number;
   bytesRemoved: number;
+  /** Entries that passed EVERY gate and would be reclaimed. In a dry run nothing is
+   *  unlinked, so this is the only honest count to show an operator: `matched` is
+   *  incremented before the file-type, age, boot-floor, and liveness gates. */
+  eligible: number;
+  /** Total size of the `eligible` entries. */
+  eligibleBytes: number;
+  /** The scan stopped on a budget (entry cap, cleanup cap, or deadline) rather than reaching
+   *  the end of the directory, so the counts below describe a prefix of the backlog and not
+   *  the backlog. `eligible > removed + failed` cannot express this: outside a dry run every
+   *  eligible entry is unlinked or failed on the same iteration, so the two are always equal
+   *  and a comparison between them is dead code. */
+  truncated: boolean;
 }
 
 interface ResponseStateTempRecoveryIO {
   now: () => number;
+  /** Approximate epoch ms of the current boot; see the boot floor in the scan loop. */
+  bootTime: () => number;
   list: (dir: string) => Iterable<string>;
   inspect: (path: string) => { isFile: boolean; mtimeMs: number; size: number };
   isProcessAlive: (pid: number) => boolean;
   unlink: (path: string) => void;
 }
 
-type ResponseStateTempRecoveryOptions = Partial<ResponseStateTempRecoveryIO> & {
+export type ResponseStateTempRecoveryOptions = Partial<ResponseStateTempRecoveryIO> & {
   maxEntries?: number;
   maxCleanups?: number;
+  /** Wall-clock ceiling for the scan, or null/undefined for no deadline (startup path). */
+  deadlineMs?: number | null;
+  /** Report only: apply every gate, count what would be reclaimed, unlink nothing. */
+  dryRun?: boolean;
 };
 
 function processIsAlive(pid: number): boolean {
@@ -523,6 +553,7 @@ function processIsAlive(pid: number): boolean {
 
 const responseStateTempRecoveryIO: ResponseStateTempRecoveryIO = {
   now: Date.now,
+  bootTime: () => Date.now() - uptime() * 1_000,
   list: function* list(dir) {
     const handle = opendirSync(dir);
     try {
@@ -549,26 +580,56 @@ export function recoverStaleResponseStateTemps(
   dir = getConfigDir(),
   options: ResponseStateTempRecoveryOptions = {},
 ): ResponseStateTempRecoveryResult {
-  const { maxEntries = STALE_TEMP_MAX_ENTRIES, maxCleanups = STALE_TEMP_MAX_CLEANUPS, ...overrides } = options;
+  const {
+    maxEntries = STALE_TEMP_MAX_ENTRIES,
+    maxCleanups = STALE_TEMP_MAX_CLEANUPS,
+    deadlineMs = null,
+    dryRun = false,
+    ...overrides
+  } = options;
   const io = { ...responseStateTempRecoveryIO, ...overrides };
   const result: ResponseStateTempRecoveryResult = {
     matched: 0,
     removed: 0,
     failed: 0,
     bytesRemoved: 0,
+    eligible: 0,
+    eligibleBytes: 0,
+    truncated: false,
   };
+  const startedAt = io.now();
+  // One probe per scan, not one per entry. A non-finite or future-dated boot is anomalous, and
+  // clamping it to "now" would be the WORST response: the floor would then retire the liveness
+  // probe for every file older than the skew, which is every file past the grace. Disable it
+  // instead -- an absent floor only costs a missed reclaim, never a wrong one.
+  const rawBoot = io.bootTime();
+  const bootMs = Number.isFinite(rawBoot) && rawBoot <= startedAt ? rawBoot : Number.NEGATIVE_INFINITY;
   let names: Iterable<string>;
   try { names = io.list(dir); } catch { return result; }
   let iterator: Iterator<string>;
   try { iterator = names[Symbol.iterator](); } catch { return result; }
   let scanned = 0;
+  // Every early exit runs through this. The production `list` is a generator that closes its
+  // directory handle in a `finally`, and a `finally` does NOT run when the consumer simply
+  // stops calling `next()` -- only `return()` resumes the generator to completion. Breaking
+  // out of the loop directly therefore leaked one directory handle per truncated scan, and the
+  // periodic reclaim truncates on purpose (entry cap, cleanup cap, deadline), so on a slow
+  // filesystem that is a leak per tick, forever.
+  const stopScan = (): ResponseStateTempRecoveryResult => {
+    try { iterator.return?.(); } catch { /* closing is best-effort; never fail a reclaim on it */ }
+    return result;
+  };
   for (;;) {
     let next: IteratorResult<string>;
     try { next = iterator.next(); } catch { return result; }
     if (next.done) break;
     const name = next.value;
     scanned += 1;
-    if (scanned > maxEntries || result.removed + result.failed >= maxCleanups) break;
+    // A dry run performs no cleanups, so bounding it by the cleanup budget would truncate
+    // the very report an operator uses to size the problem.
+    if (scanned > maxEntries) { result.truncated = true; return stopScan(); }
+    if (!dryRun && result.removed + result.failed >= maxCleanups) { result.truncated = true; return stopScan(); }
+    if (deadlineMs !== null && io.now() - startedAt > deadlineMs) { result.truncated = true; return stopScan(); }
     const match = RESPONSE_STATE_TEMP_NAME.exec(name);
     if (!match) continue;
     result.matched += 1;
@@ -579,13 +640,34 @@ export function recoverStaleResponseStateTemps(
     let file: ReturnType<ResponseStateTempRecoveryIO["inspect"]>;
     try { file = io.inspect(path); } catch { continue; }
     if (!file.isFile || io.now() - file.mtimeMs < STALE_TEMP_GRACE_MS) continue;
-    if (pid === process.pid || io.isProcessAlive(pid)) continue;
+    // Boot floor. After a reboot the original writer's pid is routinely reused, which makes
+    // the liveness skip PERMANENT: the 15-minute grace above is a lower bound and never
+    // expires it, so the file is skipped on every future pass forever. A temp older than
+    // this boot cannot be owned by the pid we would probe, so the probe is vacuous and we
+    // retire it. This does NOT claim the file is provably dead: under a shared-volume
+    // container, suspend-excluding uptime, or a network config dir the computed boot can
+    // land after the real one. The unconditional 15-minute grace above remains the safety
+    // floor, and this process's own temps are never touched.
+    const predatesBoot = file.mtimeMs < bootMs - BOOT_FLOOR_SKEW_MS;
+    if (pid === process.pid) continue;
+    if (!predatesBoot && io.isProcessAlive(pid)) continue;
+
+    result.eligible += 1;
+    result.eligibleBytes += file.size;
+    if (dryRun) continue;
 
     try {
       io.unlink(path);
       result.removed += 1;
       result.bytesRemoved += file.size;
-    } catch {
+    } catch (error) {
+      // Another proxy sharing this config dir may have won the race. A file that is already
+      // gone is reclaimed, not a failure -- reporting it as one would surface "in use or
+      // locked" to an operator for a file nobody holds.
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+        result.removed += 1;
+        continue;
+      }
       // Locked files remain for a later startup. Do not truncate by path: a same-user
       // replacement could turn that fallback into an arbitrary symlink-target write.
       result.failed += 1;
@@ -594,6 +676,23 @@ export function recoverStaleResponseStateTemps(
   return result;
 }
 
+/**
+ * Literal config dir plus the snapshot's resolved dir. Atomic writes place their temp beside
+ * the RESOLVED target, so a symlinked snapshot (dotfiles-managed config dir) strands temps in
+ * the link's real directory where a scan of the literal dir would never see them. The two
+ * collapse to one when nothing is symlinked.
+ */
+function responseStateSweepDirectories(): Set<string> {
+  const path = snapshotPath();
+  let resolvedDir = dirname(path);
+  try {
+    resolvedDir = dirname(resolveWriteTarget(path));
+  } catch {
+    /* unresolvable link: sweep the literal dir only */
+  }
+  return new Set([dirname(path), resolvedDir]);
+}
+
 /**
  * Best-effort disk snapshot so previous_response_id chains survive a proxy restart (the
  * dominant expansion-miss cause: an in-memory-only store dies with the process, and the next
@@ -898,6 +997,64 @@ export function sweepExpiredResponseStates(at = now()): number {
   return removed;
 }
 
+/**
+ * Periodic disk reclaim for abandoned atomic-write temps.
+ *
+ * `ensureLoaded` sweeps once per process, at load, BEFORE that process writes anything:
+ * every `schedulePersist` site is downstream of it. So a process that abandons a temp has
+ * already had its only look, the 15-minute grace hides the temp its predecessor's crash
+ * just produced, and `maxCleanups` caps a single pass below a large backlog. A restart
+ * loop therefore accumulates monotonically. Repeating the reclaim on a timer fixes all
+ * three: the grace expires into a later tick and the per-pass cap becomes a per-tick rate.
+ *
+ * Registered on the sweeper's LIVENESS tick, not the TTL tick: `sweepExpiredOnWrite` puts
+ * `sweepExpired` on hot write paths, and a directory scan does not belong there.
+ */
+export function reclaimAbandonedResponseStateTemps(
+  options: ResponseStateTempRecoveryOptions = {},
+): ResponseStateTempRecoveryResult {
+  const total: ResponseStateTempRecoveryResult = {
+    matched: 0, removed: 0, failed: 0, bytesRemoved: 0, eligible: 0, eligibleBytes: 0, truncated: false,
+  };
+  // The try encloses responseStateSweepDirectories() deliberately: recoverStaleResponseStateTemps
+  // already swallows its own enumeration failures, so a catch around only that call would be
+  // unreachable. snapshotPath()/getConfigDir() are the paths that can genuinely throw.
+  try {
+    for (const dir of responseStateSweepDirectories()) {
+      const result = recoverStaleResponseStateTemps(dir, options);
+      total.matched += result.matched;
+      total.removed += result.removed;
+      total.failed += result.failed;
+      total.bytesRemoved += result.bytesRemoved;
+      total.eligible += result.eligible;
+      total.eligibleBytes += result.eligibleBytes;
+      // Truncation anywhere makes the whole total a prefix.
+      total.truncated ||= result.truncated;
+    }
+  } catch {
+    /* best-effort: disk reclaim must never destabilize the caller */
+  }
+  return total;
+}
+
+/**
+ * Report-only counterpart for `ocx doctor`: applies every selection gate and unlinks
+ * nothing. It runs the SAME predicate as the reclaim, so the report and the subsequent
+ * removal cannot disagree about which files are reclaimable.
+ */
+export function inspectAbandonedResponseStateTemps(): ResponseStateTempRecoveryResult {
+  return reclaimAbandonedResponseStateTemps({ dryRun: true });
+}
+
+/** Sweeper adapter: narrows the reclaim to the `() => number` the liveness tick expects. */
+export function sweepAbandonedResponseStateTemps(): number {
+  return reclaimAbandonedResponseStateTemps({
+    maxEntries: PERIODIC_TEMP_MAX_ENTRIES,
+    maxCleanups: PERIODIC_TEMP_MAX_CLEANUPS,
+    deadlineMs: PERIODIC_TEMP_SCAN_DEADLINE_MS,
+  }).removed;
+}
+
 export function responseContinuationRetainedStoreSnapshot(): RetainedStoreSnapshot {
   return {
     count: states.size,

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

@@ -0,0 +1,301 @@
+export const TOOL_SEARCH_FUNCTION_NAME = "tool_search";
+export const TOOL_SEARCH_DEFAULT_DESCRIPTION = "Search for additional tools to load for the next turn.";
+const TOOL_SEARCH_WIRE_ALIAS_PREFIX = "opencodex_tool_search";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function toolSearchDescription(tool: unknown): string {
+  return isPlainObject(tool) && typeof tool.description === "string"
+    ? tool.description
+    : TOOL_SEARCH_DEFAULT_DESCRIPTION;
+}
+
+export function toolSearchParameters(tool: unknown): Record<string, unknown> {
+  if (isPlainObject(tool) && isPlainObject(tool.parameters)) return tool.parameters;
+  // Fresh per parse/build: downstream normalizers are allowed to clone or extend schemas, and a
+  // shared mutable default would couple otherwise unrelated requests.
+  return {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query for tools to load." },
+      limit: { type: "number", description: "Maximum number of tools to return." },
+    },
+    required: ["query"],
+  };
+}
+
+function collectToolDeclarationNames(tools: unknown[], names: Set<string>, namespace?: string): void {
+  for (const tool of tools) {
+    if (!isPlainObject(tool) || tool.type === "tool_search") continue;
+    if (tool.type === "function" && isPlainObject(tool.function) && typeof tool.function.name === "string") {
+      names.add(tool.function.name);
+    }
+    if (typeof tool.name === "string") {
+      names.add(tool.name);
+      if (namespace) names.add(`${namespace}__${tool.name}`);
+    }
+    if (tool.type === "namespace" && Array.isArray(tool.tools)) {
+      collectToolDeclarationNames(tool.tools, names, typeof tool.name === "string" ? tool.name : undefined);
+    }
+  }
+}
+
+function declaredToolNames(body: Record<string, unknown>): Set<string> {
+  const names = new Set<string>();
+  if (Array.isArray(body.tools)) collectToolDeclarationNames(body.tools, names);
+  if (Array.isArray(body.input)) {
+    for (const item of body.input) {
+      if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
+        collectToolDeclarationNames(item.tools, names);
+      }
+    }
+  }
+  return names;
+}
+
+function hasToolSearchDeclaration(tools: unknown[]): boolean {
+  return tools.some(tool => isPlainObject(tool) && tool.type === "tool_search");
+}
+
+function chooseToolSearchWireName(usedNames: ReadonlySet<string>): string {
+  if (!usedNames.has(TOOL_SEARCH_FUNCTION_NAME)) return TOOL_SEARCH_FUNCTION_NAME;
+  if (!usedNames.has(TOOL_SEARCH_WIRE_ALIAS_PREFIX)) return TOOL_SEARCH_WIRE_ALIAS_PREFIX;
+  for (let suffix = 2; ; suffix++) {
+    const candidate = `${TOOL_SEARCH_WIRE_ALIAS_PREFIX}_${suffix}`;
+    if (!usedNames.has(candidate)) return candidate;
+  }
+}
+
+function rewriteToolList(tools: unknown[], wireName: string): { tools: unknown[]; changed: boolean } {
+  let changed = false;
+  const rewritten = tools.map(tool => {
+    if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
+    const {
+      execution: _execution,
+      defer_loading: _deferLoading,
+      ...rest
+    } = tool;
+    changed = true;
+    return {
+      ...rest,
+      type: "function",
+      name: wireName,
+      description: toolSearchDescription(tool),
+      parameters: toolSearchParameters(tool),
+    };
+  });
+  return changed ? { tools: rewritten, changed: true } : { tools, changed: false };
+}
+
+function rewriteToolChoice(choice: unknown, wireName: string): unknown {
+  if (!isPlainObject(choice)) return choice;
+  if (choice.type === "tool_search") {
+    return { type: "function", name: wireName };
+  }
+  if (choice.type !== "allowed_tools" || !Array.isArray(choice.tools)) return choice;
+  let changed = false;
+  const tools = choice.tools.map(tool => {
+    if (!isPlainObject(tool) || tool.type !== "tool_search") return tool;
+    changed = true;
+    return { type: "function", name: wireName };
+  });
+  return changed ? { ...choice, tools } : choice;
+}
+
+function toolChoiceAllowsPrivateSearch(choice: unknown): boolean {
+  if (choice === undefined || choice === null || choice === "auto" || choice === "required") return true;
+  if (choice === "none") return false;
+  if (!isPlainObject(choice)) return true;
+  if (choice.type === "tool_search") return true;
+  if (choice.type === "allowed_tools" && Array.isArray(choice.tools)) {
+    return choice.tools.some(tool => isPlainObject(tool) && tool.type === "tool_search");
+  }
+  // A forced ordinary function named `tool_search` is distinct from the private tool kind.
+  return false;
+}
+
+function upstreamToolSearchItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("tsc_") ? `fc_${id.slice(4)}` : id;
+}
+
+function toolSearchArgumentsText(value: unknown): string {
+  if (typeof value === "string") return value;
+  return JSON.stringify(isPlainObject(value) ? value : {});
+}
+
+function toolSearchOutputText(value: Record<string, unknown>): string {
+  const payload: Record<string, unknown> = {
+    tools: Array.isArray(value.tools) ? value.tools : [],
+  };
+  if (typeof value.status === "string") payload.status = value.status;
+  return JSON.stringify(payload);
+}
+
+function rewriteHistoryItem(item: Record<string, unknown>, wireName: string): Record<string, unknown> {
+  if (item.type === "tool_search_call") {
+    const {
+      execution: _execution,
+      arguments: argumentsValue,
+      id,
+      ...rest
+    } = item;
+    return {
+      ...rest,
+      type: "function_call",
+      ...(id === undefined ? {} : { id: upstreamToolSearchItemId(id) }),
+      name: wireName,
+      arguments: toolSearchArgumentsText(argumentsValue),
+    };
+  }
+  if (item.type === "tool_search_output") {
+    const {
+      execution: _execution,
+      id: _id,
+      tools: _tools,
+      status: _status,
+      ...rest
+    } = item;
+    return {
+      ...rest,
+      type: "function_call_output",
+      output: toolSearchOutputText(item),
+    };
+  }
+  return item;
+}
+
+/**
+ * Third-party Responses gateways generally implement the public function-tool schema, not Codex's
+ * private client-executed `tool_search` declaration. Lower only request catalogs sent to a
+ * noncanonical upstream; the caller-facing response is restored separately.
+ */
+export function rewriteRoutedToolSearchForUpstream(body: unknown): {
+  body: unknown;
+  names: Set<string>;
+} {
+  const names = new Set<string>();
+  if (!isPlainObject(body)) return { body, names };
+
+  const topLevelSearch = Array.isArray(body.tools) && hasToolSearchDeclaration(body.tools);
+  const inputItems = Array.isArray(body.input) ? body.input : [];
+  const additionalSearch = inputItems.some(item =>
+    isPlainObject(item)
+    && item.type === "additional_tools"
+    && Array.isArray(item.tools)
+    && hasToolSearchDeclaration(item.tools));
+  const historySearch = inputItems.some(item =>
+    isPlainObject(item)
+    && (item.type === "tool_search_call" || item.type === "tool_search_output"));
+  if (!topLevelSearch && !additionalSearch && !historySearch) return { body, names };
+
+  const wireName = chooseToolSearchWireName(declaredToolNames(body));
+  const declarationChanged = topLevelSearch || additionalSearch;
+
+  let tools = body.tools;
+  if (Array.isArray(tools)) {
+    const result = rewriteToolList(tools, wireName);
+    tools = result.tools;
+  }
+
+  let input = body.input;
+  let historyLowered = false;
+  if (Array.isArray(input)) {
+    input = input.map(item => {
+      if (!isPlainObject(item)) return item;
+      if (item.type === "additional_tools" && Array.isArray(item.tools)) {
+        const result = rewriteToolList(item.tools, wireName);
+        return result.changed ? { ...item, tools: result.tools } : item;
+      }
+      const rewritten = rewriteHistoryItem(item, wireName);
+      if (rewritten !== item) historyLowered = true;
+      return rewritten;
+    });
+  }
+
+  // A turn can replay `tool_search_call` history WITHOUT re-declaring the tool — Codex normally
+  // sends the declaration, but a history-only body is legal. The history is lowered to
+  // `function_call` either way, so restoration has to be armed on that too: leaving `names`
+  // empty there would hand the client a public `function_call` for what it issued as a private
+  // search call, and the round trip would silently stop matching.
+  if ((declarationChanged || historyLowered) && toolChoiceAllowsPrivateSearch(body.tool_choice)) {
+    names.add(wireName);
+  }
+  const toolChoice = declarationChanged ? rewriteToolChoice(body.tool_choice, wireName) : body.tool_choice;
+  return {
+    body: {
+      ...body,
+      ...(tools !== body.tools ? { tools } : {}),
+      ...(input !== body.input ? { input } : {}),
+      ...(toolChoice !== body.tool_choice ? { tool_choice: toolChoice } : {}),
+    },
+    names,
+  };
+}
+
+export function toolSearchItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("fc_") ? `tsc_${id.slice(3)}` : id;
+}
+
+function toolSearchArguments(value: unknown): Record<string, unknown> {
+  if (isPlainObject(value)) return value;
+  if (typeof value !== "string" || value.length === 0) return {};
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return isPlainObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function restoreRoutedToolSearchCalls(
+  value: unknown,
+  names: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreRoutedToolSearchCalls(entry, names);
+      changed ||= result.changed;
+      return result.value;
+    });
+    return changed ? { value: restored, changed: true } : { value, changed: false };
+  }
+  if (!isPlainObject(value)) return { value, changed: false };
+
+  let changed = false;
+  const restored: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const result = restoreRoutedToolSearchCalls(entry, names);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  if (value.type === "function_call" && typeof value.name === "string" && names.has(value.name)) {
+    restored.type = "tool_search_call";
+    restored.id = toolSearchItemId(value.id);
+    restored.execution = "client";
+    restored.arguments = toolSearchArguments(value.arguments);
+    delete restored.name;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+export function restoreRoutedToolSearchCallsInJson(
+  text: string,
+  names: ReadonlySet<string>,
+): string {
+  if (names.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreRoutedToolSearchCalls(payload, names);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}

package/src/router.ts

@@ -8,10 +8,16 @@ import {
   type ComboPick,
 } from "./combos";
 import type { NormalizedComboConfig } from "./combos/types";
-import { hasOwnProvider, resolveEnvValue } from "./config";
+import { hasOwnProvider } from "./config/provider-name";
+import { resolveEnvValue } from "./config";
 import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
-import { PROVIDER_REGISTRY, providerCodexAccountMode } from "./providers/registry";
+import {
+  PROVIDER_REGISTRY,
+  mergeRegistryStaticHeaders,
+  providerCodexAccountMode,
+  registryModelServiceTierCapabilityApplies,
+} from "./providers/registry";
 import { applyDirectReasoningEffortContracts, hasLegacyClinePassReasoningEfforts } from "./providers/derive";
 import { cloneFastWire } from "./providers/fastwire";
 import {
@@ -291,12 +297,19 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ? mergePositiveNumberCaps(registryEntry.modelContextWindows, provider.modelContextWindows)
     : mergeRecordFill(registryEntry.modelContextWindows, provider.modelContextWindows);
   const modelInputModalities = mergeRecordFill(registryEntry.modelInputModalities, provider.modelInputModalities);
+  // Registry static headers are documented as applying to every upstream request, so they are
+  // filled at resolve time rather than only at seed time: a config written before a header
+  // existed, or one carrying any header of its own, would otherwise never receive it. User
+  // headers win, matched case-insensitively so an override replaces rather than duplicates.
+  const headers = mergeRegistryStaticHeaders(registryEntry.staticHeaders, provider.headers);
   const modelMaxInputTokens = providerName === OPENAI_API_PROVIDER_ID
     ? mergePositiveNumberCaps(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens)
     : mergeRecordFill(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens);
   const modelMaxOutputTokens = mergeRecordFill(registryEntry.modelMaxOutputTokens, provider.modelMaxOutputTokens);
   const modelSupportsServiceTier = mergeRecordFill(
-    registryEntry.modelSupportsServiceTier,
+    registryModelServiceTierCapabilityApplies(registryEntry, provider)
+      ? registryEntry.modelSupportsServiceTier
+      : undefined,
     provider.modelSupportsServiceTier,
   );
   const noVisionModels = mergeStringArray(registryEntry.noVisionModels, provider.noVisionModels);
@@ -365,6 +378,7 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     authMode: canonicalAuthMode,
     apiKey: resolvedApiKey,
     ...(staticModelCatalog ? { liveModels: false } : {}),
+    ...(headers ? { headers } : {}),
     // Backfill the Google wire mode + Vertex project/location from the registry when the user
     // config omits them, so a minimal `google-vertex`/`google-antigravity` entry still routes
     // through the correct branch (CCA/Vertex) instead of falling back to AI Studio.

package/src/routing/capability.ts

@@ -10,7 +10,7 @@
  * how that affects eligibility.
  */
 
-import type { OcxConfig } from "../types";
+import { modelInList, type OcxConfig } from "../types";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { serviceTierSupportForModel } from "../providers/service-tier";
 import { PROVIDER_REGISTRY } from "../providers/registry";
@@ -21,6 +21,7 @@ import {
   nativeReasoningEfforts,
 } from "../codex/catalog/metadata";
 import { readCatalog, readCodexCatalogPath } from "../codex/catalog/parsing";
+import { modelRecordValue } from "../reasoning-effort";
 import { statSync } from "node:fs";
 import type { RouteCapabilityEvidence } from "./trace";
 
@@ -159,9 +160,14 @@ export function candidateCapabilityEvidence(
   const catalogRow = cachedCatalogModels().find(model => model.provider === providerName && model.id === modelId);
   const isNative = providerName === OPENAI_CODEX_PROVIDER_ID && !modelId.includes("/");
 
-  const rawContextWindow = provider?.modelContextWindows?.[modelId]
+  // `modelRecordValue`, not a bare lookup: every runtime reader of these three maps
+  // resolves them that way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw
+  // made the evidence disagree with the resolver it claims to describe — and for the
+  // window it did not even degrade to unknown, it fell through to the provider-wide
+  // value, which is a definite wrong answer rather than an absent one.
+  const rawContextWindow = modelRecordValue(provider?.modelContextWindows, modelId)
     ?? provider?.contextWindow
-    ?? registryEntry?.modelContextWindows?.[modelId]
+    ?? modelRecordValue(registryEntry?.modelContextWindows, modelId)
     ?? catalogRow?.contextWindow
     ?? (isNative ? nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) : undefined);
   // Native rows go through the accessor (raise-to-ceiling + opt-in). Routed rows keep
@@ -170,10 +176,21 @@ export function candidateCapabilityEvidence(
     ? (nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) ?? rawContextWindow)
     : rawContextWindow;
 
-  const modalities = provider?.modelInputModalities?.[modelId]
-    ?? registryEntry?.modelInputModalities?.[modelId]
-    ?? catalogRow?.inputModalities
-    ?? (isNative ? nativeInputModalities(modelId) : undefined);
+  // `noVisionModels` is checked before the modality chain because that is the order
+  // `isModelTextOnly` uses: it matches the no-vision list and returns true before it
+  // ever reads `modelInputModalities` (`src/vision/index.ts:32`). So a `gpt-oss`
+  // no-vision entry beats an exact `gpt-oss:120b` entry that lists "image", and
+  // deriving `image` from the modality chain alone reported vision on a model the
+  // runtime refuses it for. That matters more here than on the CLI surface fixed in
+  // #2086: routing *acts* on this evidence, so it would select the candidate for image
+  // work that execution then rejects.
+  const noVision = modelInList(provider?.noVisionModels, modelId);
+  const modalities = noVision
+    ? ["text"]
+    : (modelRecordValue(provider?.modelInputModalities, modelId)
+      ?? modelRecordValue(registryEntry?.modelInputModalities, modelId)
+      ?? catalogRow?.inputModalities
+      ?? (isNative ? nativeInputModalities(modelId) : undefined));
   const image = Array.isArray(modalities)
     ? modalities.includes("image")
     : undefined;
@@ -196,8 +213,8 @@ export function candidateCapabilityEvidence(
     || provider?.parallelToolCalls === true
     || undefined;
 
-  const reasoningEfforts = provider?.modelReasoningEfforts?.[modelId]
-    ?? registryEntry?.modelReasoningEfforts?.[modelId]
+  const reasoningEfforts = modelRecordValue(provider?.modelReasoningEfforts, modelId)
+    ?? modelRecordValue(registryEntry?.modelReasoningEfforts, modelId)
     ?? (isNative ? nativeReasoningEfforts(modelId) : undefined);
 
   const tierSupport = provider