@bitkyc08/opencodex 2.43.0 → 2.44.0

package/src/server/responses/fetch-helpers.ts

@@ -61,6 +61,8 @@ export interface ProviderFetchOptions {
   onCodexWsQuota?: CodexWsQuotaObserver;
   /** Synchronous admission at actual credential dispatch, after pacing/backoff. */
   beforeDispatch?: (headers: Headers) => void;
+  /** Revalidate/rebuild a queued request at its physical send boundary, after pacing. */
+  dispatchOverride?: (input: Parameters<typeof globalThis.fetch>[0], init: RequestInit, execute: typeof globalThis.fetch) => Promise<Response>;
 }
 
 export function providerFetch(
@@ -75,7 +77,10 @@ export function providerFetch(
   const httpFetch = Object.assign(
     async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
       options.beforeDispatch?.(new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)));
-      return base(input, { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 });
+      const dispatchInit = { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 };
+      return options.dispatchOverride
+        ? options.dispatchOverride(input, dispatchInit, base)
+        : base(input, dispatchInit);
     },
     { preconnect },
   ) as typeof globalThis.fetch;

package/src/server/responses/ws-upstream.ts

@@ -13,6 +13,7 @@
 // (passthrough relay, adapter parsers, usage sniffing) is unchanged.
 
 import { compareBunVersions } from "../../lib/bun-stream-caps";
+import { resolveProxyRoute } from "../../lib/proxy-env";
 import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
 import { CODEX_RESPONSES_HTTP_URL, CODEX_RESPONSES_WS_URL, prepareCodexHttpInit, prepareCodexWsRequest } from "./codex-ws-request";
 import { codexWsExchange } from "./codex-ws-exchange";
@@ -150,6 +151,10 @@ export function codexWsUpstreamFetch(
     return sseFallback(url, init);
   }
 
+  const wsUrl = wsUpstreamUrlFor(url);
+  const proxyRoute = resolveProxyRoute(new URL(wsUrl));
+  if (proxyRoute.kind === "fallback") return sseFallback(url, init);
+  const proxy = proxyRoute.kind === "proxy" ? proxyRoute.proxy : undefined;
   // A genuine caller `originator` is already in these headers via the forward
   // set. Never fabricate one here: pool/forward traffic must not impersonate
   // Codex CLI, per the metadata-integrity contract. (The backend's fast lane
@@ -164,9 +169,9 @@ export function codexWsUpstreamFetch(
   }
   let session: CodexWsSession;
   try {
-    const identity = codexWsReuseIdentity(url, headers, frameText);
-    session = (identity ? codexWsPool.acquire(identity, wsUpstreamUrlFor(url), headers) : null)
-      ?? new CodexWsSession(wsUpstreamUrlFor(url), headers);
+    const identity = codexWsReuseIdentity(url, headers, frameText, proxy);
+    session = (identity ? codexWsPool.acquire(identity, wsUrl, headers, proxy) : null)
+      ?? new CodexWsSession(wsUrl, headers, false, undefined, proxy);
     if (!session.busy && !session.reserve()) {
       session.dispose();
       return sseFallback(url, init);

package/src/server/responses-custom-tool-repair.ts

@@ -93,7 +93,8 @@ export function createRoutedCustomToolRestoreBlockRewrite(
   declaredNames?: ReadonlySet<string>,
 ): SseBlockRewrite {
   const itemNames = new Map<string, { name: string; aliased: boolean; namespace?: string }>();
-  const customAliasItemNames = new Map<string, string>();
+  // Native helper aliases and genuine bare code-mode exec calls share completion repair.
+  const customExecItemNames = new Map<string, string>();
   const repairItemNames = new Map<string, string>();
   const ordinaryItemIds = new Set<string>();
   const openCalls = new Map<string, OpenCustomCall>();
@@ -119,7 +120,7 @@ export function createRoutedCustomToolRestoreBlockRewrite(
     }
     pendingArguments = [];
     itemNames.clear();
-    customAliasItemNames.clear();
+    customExecItemNames.clear();
     repairItemNames.clear();
     ordinaryItemIds.clear();
   };
@@ -195,15 +196,17 @@ export function createRoutedCustomToolRestoreBlockRewrite(
       const wireName = routedCustomToolWireName(parsed.item);
       const targetName = routedCustomToolTargetName(parsed.item, names, declaredNames);
       const aliased = targetName !== undefined && targetName !== wireName;
-      if (upstreamItemId && aliased) {
-        customAliasItemNames.set(upstreamItemId, parsed.item.name);
+      const codeModeExec = targetName === "exec" && parsed.item.name === "exec"
+        && parsed.item.namespace === undefined && declaresCodeModeExec(declaredNames);
+      if (upstreamItemId && (aliased || codeModeExec)) {
+        customExecItemNames.set(upstreamItemId, parsed.item.name);
         if (type === "response.output_item.added") {
           openCalls.set(upstreamItemId, { argumentsText: "", emittedInput: "", retainedBytes: 0 });
         }
       }
       const repairable = wireName !== undefined && repairNames.has(wireName);
       if (upstreamItemId && repairable) repairItemNames.set(upstreamItemId, parsed.item.name);
-      const restored = repairable || aliased
+      const restored = repairable || aliased || codeModeExec
         ? restoreRoutedCustomCalls(parsed, names, repairNames, declaredNames)
         : { value: parsed, changed: false };
       if (type === "response.output_item.done" && upstreamItemId) releaseCall(upstreamItemId);
@@ -259,7 +262,7 @@ export function createRoutedCustomToolRestoreBlockRewrite(
     if (
       type === "response.custom_tool_call_input.delta"
       && upstreamItemId
-      && customAliasItemNames.has(upstreamItemId)
+      && customExecItemNames.has(upstreamItemId)
     ) {
       const open = openCalls.get(upstreamItemId) ?? { argumentsText: "", emittedInput: "", retainedBytes: 0 };
       const delta = typeof parsed.delta === "string" ? parsed.delta : "";
@@ -268,19 +271,34 @@ export function createRoutedCustomToolRestoreBlockRewrite(
       open.argumentsText += delta;
       open.retainedBytes += deltaBytes;
       openCalls.set(upstreamItemId, open);
-      return [];
+      if (customExecItemNames.get(upstreamItemId) !== "exec"
+        || mayBecomePatchEnvelope(open.argumentsText)
+        // JSON.parse accepts whitespace, escaped keys and arbitrary property order.
+        // Any object prefix may still wrap a patch; keep it until authoritative completion.
+        || open.argumentsText.trimStart() === ""
+        || open.argumentsText.trimStart().startsWith("{")) return [];
+      // If a held prefix turns out to be ordinary JavaScript, release the entire
+      // un-emitted suffix. Native custom input remains byte-exact.
+      const inputDelta = open.argumentsText.slice(open.emittedInput.length);
+      open.emittedInput = open.argumentsText;
+      return inputDelta ? [replaceSseDataPayload(block, JSON.stringify({ ...parsed, delta: inputDelta }))] : [];
     }
     if (
       type === "response.custom_tool_call_input.done"
       && upstreamItemId
-      && customAliasItemNames.has(upstreamItemId)
+      && customExecItemNames.has(upstreamItemId)
     ) {
       const source = typeof parsed.input === "string"
         ? parsed.input
         : openCalls.get(upstreamItemId)?.argumentsText ?? "";
+      const name = customExecItemNames.get(upstreamItemId)!;
+      const helper = name === "exec"
+        ? resolveCodeModeHelperName(undefined, name, source, undefined, declaredNames)
+        : name;
+      releaseCall(upstreamItemId);
       return [replaceSseDataPayload(block, JSON.stringify({
         ...parsed,
-        input: compileCodeModeHelperInput(source, customAliasItemNames.get(upstreamItemId)!),
+        input: helper ? compileCodeModeHelperInput(source, helper) : source,
       }))];
     }
     if (
@@ -312,6 +330,8 @@ export function createRoutedCustomToolRestoreBlockRewrite(
       open.argumentsText += delta;
       open.retainedBytes += deltaBytes;
       openCalls.set(upstreamItemId, open);
+      // A helper alias will become JavaScript at completion, never raw patch/JSON.
+      if (itemNames.get(upstreamItemId)?.aliased) return [];
       // Still accumulating toward the compact wrapper, or an unrecognized shape:
       // suppress progressive emission and let the done event carry input.
       if (FREEFORM_WRAP_PREFIX.startsWith(open.argumentsText)) return [];

package/src/server/responses-function-tool-repair.ts

@@ -0,0 +1,183 @@
+import {
+  TRANSLATOR_MAX_TURN_BYTES,
+  TranslatorBudgetExceededError,
+  type TranslatorBudget,
+} from "../lib/translator-budget";
+import { repairFunctionCalls, type FunctionCallRepairSchemas } from "../responses/function-call-compat";
+import { replaceSseDataPayload, sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
+
+type Identity = {
+  itemId?: string;
+  outputIndex?: number;
+  item: Record<string, unknown>;
+  bytes: number;
+};
+type PendingCompletion = {
+  block: string;
+  itemId?: string;
+  outputIndex?: number;
+  bytes: number;
+};
+const ENTRY_OVERHEAD_BYTES = 64;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function outputIndexOf(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/** Ordinary deltas remain upstream previews; only authoritative completions are repaired. */
+export function createResponsesFunctionToolRepairBlockRewrite(
+  schemas: FunctionCallRepairSchemas,
+  budget?: TranslatorBudget,
+): SseBlockRewrite {
+  if (schemas.size === 0) return block => [block];
+  const byId = new Map<string, Identity>();
+  const byIndex = new Map<number, Identity>();
+  let pending: PendingCompletion[] = [];
+  let retainedBytes = 0;
+  let disposed = false;
+
+  const retain = (bytes: number): void => {
+    if (retainedBytes + bytes > TRANSLATOR_MAX_TURN_BYTES) {
+      throw new TranslatorBudgetExceededError("retained_collectors", TRANSLATOR_MAX_TURN_BYTES);
+    }
+    budget?.chargeRetained(bytes, { kind: "retained_collectors" });
+    retainedBytes += bytes;
+  };
+  const release = (bytes: number): void => {
+    budget?.releaseRetained(bytes, { kind: "retained_collectors" });
+    retainedBytes -= bytes;
+  };
+  const releaseIdentity = (identity: Identity): void => {
+    if (identity.itemId !== undefined) byId.delete(identity.itemId);
+    if (identity.outputIndex !== undefined) byIndex.delete(identity.outputIndex);
+    release(identity.bytes);
+  };
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    release(retainedBytes);
+    byId.clear();
+    byIndex.clear();
+    pending = [];
+  };
+  const lookup = (itemId: string | undefined, index: number | undefined): Identity | undefined => {
+    const identity = itemId === undefined ? undefined : byId.get(itemId);
+    if (identity) return index === undefined || identity.outputIndex === undefined || identity.outputIndex === index ? identity : undefined;
+    const indexed = index === undefined ? undefined : byIndex.get(index);
+    return indexed && (itemId === undefined || indexed.itemId === undefined || indexed.itemId === itemId) ? indexed : undefined;
+  };
+  const register = (item: Record<string, unknown>, index: number | undefined): Identity | undefined => {
+    const itemId = typeof item.id === "string" && item.id ? item.id : undefined;
+    if (itemId === undefined && index === undefined) return undefined;
+    // Repeated snapshots replace metadata; never retain provider argument bodies here.
+    const previous = new Set<Identity>();
+    if (itemId !== undefined && byId.has(itemId)) previous.add(byId.get(itemId)!);
+    if (index !== undefined && byIndex.has(index)) previous.add(byIndex.get(index)!);
+    for (const identity of previous) releaseIdentity(identity);
+    const metadata = {
+      type: item.type,
+      name: item.name,
+      ...("namespace" in item ? { namespace: item.namespace } : {}),
+      ...(item.status !== undefined && item.status !== "in_progress" && item.status !== "completed" ? { status: item.status } : {}),
+    };
+    const bytes = ENTRY_OVERHEAD_BYTES + Buffer.byteLength(JSON.stringify([itemId, index, metadata]), "utf8");
+    retain(bytes);
+    const identity = { itemId, outputIndex: index, item: metadata, bytes };
+    if (itemId !== undefined) byId.set(itemId, identity);
+    if (index !== undefined) byIndex.set(index, identity);
+    return identity;
+  };
+  const repairCompletion = (block: string, event: Record<string, unknown>, identity: Identity): string => {
+    if (typeof event.arguments !== "string") return block;
+    const resolved = (typeof event.item_id !== "string" || event.item_id === "") && identity.itemId !== undefined
+      ? { ...event, item_id: identity.itemId }
+      : event;
+    const repaired = repairFunctionCalls({ ...identity.item, status: identity.item.status ?? "completed", arguments: event.arguments }, schemas);
+    if (repaired.changed && isObject(repaired.value)) {
+      return replaceSseDataPayload(block, JSON.stringify({ ...resolved, arguments: repaired.value.arguments }));
+    }
+    return resolved === event ? block : replaceSseDataPayload(block, JSON.stringify(resolved));
+  };
+  const flushPending = (identity: Identity): string[] => {
+    const output: string[] = [];
+    const remaining: PendingCompletion[] = [];
+    for (const completion of pending) {
+      const matches = completion.itemId !== undefined
+        ? completion.itemId === identity.itemId
+          && (completion.outputIndex === undefined || identity.outputIndex === undefined || completion.outputIndex === identity.outputIndex)
+        : completion.outputIndex !== undefined && completion.outputIndex === identity.outputIndex;
+      if (!matches) { remaining.push(completion); continue; }
+      release(completion.bytes);
+      const payload = sseDataPayload(completion.block);
+      const event: unknown = payload === null ? undefined : JSON.parse(payload);
+      output.push(isObject(event) ? repairCompletion(completion.block, event, identity) : completion.block);
+    }
+    pending = remaining;
+    return output;
+  };
+
+  const rewrite: SseBlockRewrite = block => {
+    if (disposed) return [block];
+    const payload = sseDataPayload(block);
+    if (payload === null) return [block];
+    if (payload === "[DONE]") {
+      const unfinished = pending.map(entry => entry.block);
+      dispose();
+      return [...unfinished, block];
+    }
+    let event: unknown;
+    try { event = JSON.parse(payload); } catch { return [block]; }
+    if (!isObject(event)) return [block];
+    const index = outputIndexOf(event.output_index);
+    const itemId = typeof event.item_id === "string" && event.item_id ? event.item_id : undefined;
+    try {
+      if ((event.type === "response.output_item.added" || event.type === "response.output_item.done") && isObject(event.item)) {
+        const identity = register(event.item, index);
+        const replayed = identity ? flushPending(identity) : [];
+        const repaired = repairFunctionCalls(event, schemas);
+        const output = repaired.changed ? replaceSseDataPayload(block, JSON.stringify(repaired.value)) : block;
+        if (identity && (event.type === "response.output_item.done" || replayed.length > 0)) releaseIdentity(identity);
+        return event.type === "response.output_item.added" ? [output, ...replayed] : [...replayed, output];
+      }
+      if (event.type === "response.function_call_arguments.done" && typeof event.arguments === "string") {
+        const identity = lookup(itemId, index);
+        if (identity) {
+          const output = repairCompletion(block, event, identity);
+          releaseIdentity(identity);
+          return [output];
+        }
+        if (itemId !== undefined || index !== undefined) {
+          const bytes = ENTRY_OVERHEAD_BYTES + Buffer.byteLength(block, "utf8");
+          retain(bytes);
+          pending.push({ block, itemId, outputIndex: index, bytes });
+          return [];
+        }
+      }
+      if (typeof event.type === "string" && ["response.completed", "response.failed", "response.incomplete", "response.cancelled"].includes(event.type)) {
+        const replayed: string[] = [];
+        if (event.type === "response.completed" && isObject(event.response) && Array.isArray(event.response.output)
+          && (event.response.status === undefined || event.response.status === "completed")) {
+          for (const [slot, item] of event.response.output.entries()) {
+            if (!isObject(item)) continue;
+            const identity = register(item, slot);
+            if (identity) replayed.push(...flushPending(identity));
+          }
+        }
+        replayed.push(...pending.map(entry => entry.block));
+        const repaired = repairFunctionCalls(event, schemas);
+        dispose();
+        return [...replayed, repaired.changed ? replaceSseDataPayload(block, JSON.stringify(repaired.value)) : block];
+      }
+      return [block];
+    } catch (error) {
+      dispose();
+      throw error;
+    }
+  };
+  rewrite.dispose = dispose;
+  return rewrite;
+}

package/src/server/responses-snapshot-codec.ts

@@ -0,0 +1,14 @@
+/** Shared snapshot wire primitives; no retention state or policy. */
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export type RetainedOutputItem = {
+  item: Record<string, unknown>;
+  sourceBytes: number;
+};
+
+export function jsonBlock(event: Record<string, unknown>): string {
+  return `data: ${JSON.stringify(event)}`;
+}

package/src/server/responses-snapshot-repair.ts

@@ -26,6 +26,7 @@ import {
   MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES,
 } from "./relay";
 import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
+import { isPlainObject, jsonBlock, type RetainedOutputItem } from "./responses-snapshot-codec";
 
 const RESPONSE_EVENT_STATUSES: Readonly<Record<string, string>> = {
   "response.created": "in_progress",
@@ -42,10 +43,6 @@ type RequestDefaults = {
   tools: unknown[];
 };
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
 function isStructurallyValidToolChoice(value: unknown): boolean {
   return (typeof value === "string" && value.trim().length > 0)
     || (isPlainObject(value) && typeof value.type === "string" && value.type.trim().length > 0);
@@ -179,15 +176,6 @@ type OpenItem = {
 const MAX_OPEN_ITEMS = MAX_COMPLETED_OUTPUT_ITEMS;
 const MAX_OPEN_ITEM_AGGREGATE_TEXT_BYTES = MAX_COMPLETED_OUTPUT_ITEM_SOURCE_BYTES;
 
-type RetainedOutputItem = {
-  item: Record<string, unknown>;
-  sourceBytes: number;
-};
-
-function jsonBlock(event: Record<string, unknown>): string {
-  return `data: ${JSON.stringify(event)}`;
-}
-
 /**
  * Stateful block rewrite: field backfills + lifecycle completion injection.
  * `budget` bounds retained completed items (reconstruction only).

package/src/server/responses-undeclared-tool-guard.ts

@@ -1,3 +1,4 @@
+import { collectAmbiguousDottedAliases, dottedAliasIsUnambiguous, wireToolInnerName } from "../responses/tool-name-aliases";
 import {
   CODE_MODE_EXEC_TOOL_NAME,
   dottedToolName,
@@ -75,32 +76,6 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-/**
- * A dotted spelling is a safe alias only when it cannot ALSO be read as some other identity's
- * canonical `ns__name`.
- *
- * `{namespace: "x__y", name: "z"}` produces the dotted spelling "x__y.z", which is exactly the
- * canonical wire name of `{namespace: "x", name: "y.z"}`. If only the latter is declared, an
- * echoed call for the former would still find "x__y.z" in the declared set and be authorized as
- * a tool the caller never granted. Requiring both halves to be free of the `__` separator keeps
- * a dotted alias from ever impersonating a canonical name.
- */
-function dottedAliasIsUnambiguous(namespace: string, name: string): boolean {
-  return !namespace.includes("__") && !name.includes("__");
-}
-
-function wireToolInnerName(tool: unknown): string | undefined {
-  if (!isPlainObject(tool)) return undefined;
-  const nestedFunction = tool.type === "function" && isPlainObject(tool.function)
-    ? tool.function
-    : undefined;
-  return typeof tool.name === "string" && tool.name.length > 0
-    ? tool.name
-    : typeof nestedFunction?.name === "string" && nestedFunction.name.length > 0
-      ? nestedFunction.name
-      : undefined;
-}
-
 function addWireToolName(
   names: Set<string>,
   tool: unknown,
@@ -171,48 +146,6 @@ function addWireToolSpecs(
   }
 }
 
-/**
- * Dotted aliases that more than one declared identity would claim, plus dotted aliases that
- * collide with a canonical or bare declared name.
- *
- * Resolved over the WHOLE catalog before any name is registered, so which identity "wins" can
- * never depend on declaration order -- an order the caller controls.
- */
-function collectAmbiguousDottedAliases(specGroups: readonly unknown[]): Set<string> {
-  const owners = new Map<string, string | null>();
-  const claim = (alias: string, identity: string): void => {
-    const owner = owners.get(alias);
-    if (owner === undefined) owners.set(alias, identity);
-    else if (owner !== identity) owners.set(alias, null);
-  };
-  for (const specs of specGroups) {
-    if (!Array.isArray(specs)) continue;
-    for (const spec of specs) {
-      if (!isPlainObject(spec)) continue;
-      if (spec.type === "namespace" && Array.isArray(spec.tools)) {
-        const namespace = typeof spec.name === "string" ? spec.name : undefined;
-        if (!namespace || namespace === BUILTIN_FUNCTIONS_NAMESPACE) continue;
-        for (const inner of spec.tools) {
-          const name = wireToolInnerName(inner);
-          if (!name) continue;
-          const identity = JSON.stringify([namespace, name]);
-          claim(dottedToolName(namespace, name), identity);
-          // A canonical or bare name already owned by a different identity poisons the dotted
-          // alias that would shadow it.
-          claim(namespacedToolName(namespace, name), identity);
-          claim(name, identity);
-        }
-        continue;
-      }
-      const name = wireToolInnerName(spec);
-      if (name) claim(name, JSON.stringify([undefined, name]));
-    }
-  }
-  const ambiguous = new Set<string>();
-  for (const [alias, owner] of owners) if (owner === null) ambiguous.add(alias);
-  return ambiguous;
-}
-
 /**
  * Tool names the OUTBOUND Responses body actually declared.
  *

package/src/server/sse-payload-rewrite.ts

@@ -249,7 +249,9 @@ export function relaySseWithBlockRewrite(
       } catch (error) {
         releaseBuffer();
         disposeRewrite();
-        try { await reader.cancel(error); } catch { /* already closed */ }
+        // Cancelling one tee branch waits for its sibling. Surface the failure
+        // now so downstream can abort upstream and release the inspection branch.
+        void reader.cancel(error).catch(() => {});
         controller.error(error);
       }
     },

package/src/service.ts

@@ -1926,7 +1926,7 @@ export function buildWindowsTaskXml(
     <Enabled>true</Enabled>
     <Hidden>false</Hidden>
     <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
-    <Priority>7</Priority>
+    <Priority>4</Priority>
     <RestartOnFailure>
       <Interval>PT1M</Interval>
       <Count>3</Count>
@@ -2972,6 +2972,10 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
     const identityUpgradeNeeded = registrationHealthy
       && preferredSid !== undefined
       && !windowsTaskHasSessionRecoveryTriggers(triggers, preferredSid);
+    // Omitted Priority also defaults to 7; background priority can starve health probes under CPU load.
+    const priorityUpgradeNeeded = registrationHealthy && taskXmlOptionalValueEquals(
+      taskXmlSection(taskXmlWithoutCommentsAndCdata(registeredXml), "Settings"), "Priority", "7",
+    );
     const refreshableLegacy = windowsTaskRegistrationRefreshableLegacy(
       registeredXml,
       deps.schedulerWscript,
@@ -2998,7 +3002,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
     // Re-register only when the registered XML is actually stale, so the ordinary repair
     // stays free of `schtasks /create` and its UAC prompt.
     let startExpectedXml = registeredXml;
-    if (!registrationHealthy || identityUpgradeNeeded) {
+    if (!registrationHealthy || identityUpgradeNeeded || priorityUpgradeNeeded) {
       // The task was stopped above, so a failed replacement must not exit here: `/create /f`
       // can be rejected, elevation can be cancelled, and staging or verification can fail.
       // Any of those would leave a previously runnable proxy stopped and the user worse off

package/src/types/config.ts

@@ -409,6 +409,13 @@ export interface OcxConfig {
    * one key at a time rather than widening a shared union.
    */
   clientIntegrations?: OcxClientIntegrationsConfig;
+  /** Aside account-backed profile synchronization; individual overrides survive bulk refresh. */
+  asideProfileSync?: {
+    allProfiles?: boolean;
+    profiles?: Record<string, boolean>;
+    /** Stable provenance for the one legacy root ownership record, or no root owner. */
+    legacyProfileId?: number | null;
+  };
   /**
    * Up to 5 Codex-facing catalog ids to feature first. Values may be bare catalog ids,
    * exact account-qualified "<selector>/<native-openai-model>" ids, or routed
@@ -419,17 +426,15 @@ export interface OcxConfig {
   /** One-time featured-roster upgrade marker; later user ordering is preserved. */
   subagentModelsVersion?: number;
   /**
-   * Optional full picker ordering for the Codex model catalog, independent of the
-   * 5-slot `subagentModels` spawn_agent cap. DISPLAY-ONLY: it controls the visual order of
-   * the Codex model picker for large routed catalogs (10-20+ models) that would otherwise sort
-   * arbitrarily and reshuffle on every rebuild. Values are routed `<provider>/<model>` catalog
-   * slugs (matched by exact slug or `provider/id`); native OpenAI passthrough rows and
-   * account-qualified native rows are not reordered (order native rows via `subagentModels`).
-   * Listed routed rows appear in array order; rows not listed keep their normal display order.
-   * `subagentModels`-featured rows keep their top position. When unset or empty, catalog
-   * priority is unchanged. This changes ONLY what the user sees in the picker: the spawn_agent
-   * candidate set is derived from each row's natural priority and is provably unaffected, even
-   * when every routed row is listed (see opencodex_spawn_priority / effectiveSubagentRoster).
+   * Display-only order for the Codex picker, independent of subagentModels.
+   * Routed-only lists order non-featured routed rows; featured and native rows keep
+   * their normal positions. Including a bare native id opts into ordering the complete
+   * picker: listed ids appear first in array order, followed by unlisted rows in their
+   * natural priority order. Exact catalog ids take precedence over equivalent raw/encoded
+   * routed ids; empty entries are ignored. The separate natural priority used by
+   * OpenCodex guidance is preserved. Native Codex's advertised five follow display
+   * priority and may change; exact-name override eligibility is not restricted by that list.
+   * Unset or empty leaves catalog priorities unchanged.
    */
   modelPickerOrder?: string[];
   /**
@@ -603,8 +608,10 @@ export interface OcxConfig {
    * so absence is the only default state this feature has.
    */
   quotaResetNotify?: OcxQuotaResetNotifyConfig;
-  /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
+  /** Active provider context limits; native long windows remain within their supported ceilings. */
   providerContextCaps?: Record<string, number>;
+  /** Last selected provider caps; retained while a cap is switched off. Not an active limit. */
+  providerContextCapValues?: Record<string, number>;
   /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
   contextCapValue?: number;
   /** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
@@ -808,10 +815,10 @@ export interface OcxConfig {
    * provider has 2 or more eligible stored accounts, the same consent rule an `apiKeyPool` of
    * two keys already applies, and a single account remains a strict no-op.
    *
-   * What `enabled: false` still refuses is the PRE-DISPATCH preference: steering a request
-   * upstream has not refused toward the account with more known headroom. That moves a healthy
-   * request, so it stays a real choice. `providers.<name>.oauthAccountFailover` overrides this
-   * per provider in either direction; reactive 429 rotation remains presence-driven.
+   * Proactive avoidance of an exhausted selected account requires `enabled: true`.
+   * A healthy selected account retains priority; an unknown quota is not exhaustion.
+   * `providers.<name>.oauthAccountFailover` overrides this per provider in either direction.
+   * Reactive 429 rotation remains presence-driven even when proactive routing is disabled.
    */
   oauthAccountFailover?: {
     enabled?: boolean;

package/src/types/provider.ts

@@ -8,6 +8,13 @@ import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode }
  */
 export type RefreshPolicy = "proactive" | "lazy-only" | "disabled";
 
+/** Request-owned identity of the configured key, before env/keychain resolution. */
+export interface ProviderApiKeySelection {
+  entryId?: string;
+  reference?: string;
+  revision?: string;
+}
+
 export interface OpenRouterProviderRouting {
   /** OpenRouter provider slugs to try first, in priority order. */
   order?: string[];
@@ -329,6 +336,10 @@ export interface OcxProviderConfig {
    * `apiKey` seeds a one-entry pool on first management touch.
    */
   apiKeyPool?: Array<{ id: string; key: string; label?: string; addedAt?: number }>;
+  /** Changes on manual selection (including re-selection) and committed automatic allocation. */
+  apiKeySelectionRevision?: string;
+  /** Runtime only. Never expose in management responses or persist a routed provider. */
+  _apiKeyAttempt?: ProviderApiKeySelection;
   defaultModel?: string;
   models?: string[];
   /**
@@ -441,9 +452,9 @@ export interface OcxProviderConfig {
    *
    * Reactive 429 rotation is presence-driven and cannot be refused here — 2+ logged-in accounts
    * activate it, and a 429 with an idle second account is a defect rather than a preference.
-   * What an explicit `false` still refuses is the pre-dispatch preference that steers a HEALTHY
-   * request toward the account with more known headroom. It beats the global
-   * `oauthAccountFailover` in either direction; reactive 429 rotation remains presence-driven.
+   * Proactive exhaustion avoidance requires explicit `true`; a healthy selected account
+   * retains priority. This overrides global `oauthAccountFailover` in either direction.
+   * Reactive 429 rotation remains available even when proactive routing is disabled.
    */
   oauthAccountFailover?: {
     enabled?: boolean;

package/src/types/request.ts

@@ -68,6 +68,8 @@ export interface OcxParsedRequest {
   _cursorConversationId?: string;
   /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
   _clientThreadId?: string;
+  /** True when promptCacheKey identifies a shared cache cohort rather than one conversation. */
+  _promptCacheKeyIsSharedCohort?: boolean;
   /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */
   _cursorClientThreadId?: string;
   /** Conversation/provider/account/model-bound namespace for reasoning replay state. */

package/src/usage/log.ts

@@ -55,9 +55,14 @@ export type AttemptRecoveryKind =
   | "opaque-blob-rejection"
   | "empty-completion";
 
+/** Request-time upstream credential class, never a credential or account identifier. */
+export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
+
 export interface PersistedUsageAttempt {
   ordinal: number;
   provider: string;
+  /** Absent on historic attempts and routes whose subscription attribution is unknown. */
+  credentialSource?: UsageCredentialSource;
   model: string;
   adapter: string;
   status: number;
@@ -400,6 +405,10 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
   return {
     ordinal: attempt.ordinal as number,
     provider: attempt.provider,
+    ...(attempt.provider === "xai"
+      && (attempt.credentialSource === "grok-oauth" || attempt.credentialSource === "xai-api-key")
+      ? { credentialSource: attempt.credentialSource }
+      : {}),
     model: attempt.model,
     adapter: attempt.adapter,
     status: attempt.status,