@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/codex/sync.ts

@@ -1,3 +1,4 @@
+import { approvedCodexProviders } from "./provider-routing";
 import { currentExternalCodexModelProvider, injectCodexConfig } from "./inject";
 import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE, unbackedRoutedRemovalMessage } from "./catalog/routed-removal";
 import { printProjectCodexConfigWarnings, groupProjectCodexConfigWarningsByPath, type ProjectCodexConfigWarning } from "./project-config-warnings";
@@ -33,6 +34,8 @@ export interface CodexSyncResult {
   catalogPath: string | null;
   catalogExists: boolean;
   catalogWritten: boolean;
+  /** Committed configuration-byte change, never inferred from a successful no-op. */
+  configChanged?: boolean;
   cacheSynced: boolean;
   /**
    * Whether the catalog owner committed a validated catalog or refused the
@@ -188,7 +191,7 @@ export async function syncModelsToCodex(
     };
   }
 
-  if (externalProvider) {
+  if (externalProvider && !approvedCodexProviders().includes(externalProvider)) {
     if (catalogEvenWhenNotInjected) {
       // External providers own config.toml, and the injector removes the OpenCodex
       // journal for external providers (inject.ts). This explicit catalog-only sync
@@ -214,6 +217,7 @@ export async function syncModelsToCodex(
     return {
       status: "applied",
       ok: result.success,
+      ...(result.success && result.configChanged === true ? { configChanged: true } : {}),
       added: 0,
       catalogPath: null,
       catalogExists: false,
@@ -332,6 +336,7 @@ export async function syncModelsToCodex(
   return {
     status: "applied",
     ok: result.success,
+    ...(result.success && result.configChanged === true ? { configChanged: true } : {}),
     added,
     ...(refreshOutcome ? { refreshOutcome } : {}),
     catalogPath,

package/src/codex/user-identity.ts

@@ -19,6 +19,7 @@ import { isAbsolute, join, resolve } from "node:path";
 
 import { resolveTrustedWindowsPowerShellExe } from "../lib/windows-elevation";
 import { WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS } from "../lib/windows-user-principal";
+import { resolveWindowsLocalAppData } from "./windows-local-appdata";
 
 import type {
   ResolveCodexCoordinatorDatabasePath,
@@ -209,10 +210,11 @@ export function decodeWindowsIdentityPowerShellOutputForTests(output: Uint8Array
 /**
  * Per-process memo for the Windows lookups.
  *
- * Both values -- the effective token's SID and its known-folder local AppData --
+ * Both helper values -- the effective token's SID and its known-folder local AppData --
  * are fixed for the lifetime of a process: neither can change without a new logon
  * token, and the lookups deliberately ignore the environment, so nothing a caller
- * does between two calls can alter the answer. Each call otherwise spawns a fresh
+ * does between two calls can alter the answer. The native x64 known-folder path
+ * avoids this helper entirely. Each fallback call otherwise spawns a fresh
  * PowerShell, roughly 150ms for the SID and 310ms for the folder, and the
  * coordinator asks for both on every config write and lock acquisition. That cost
  * pushed real multi-process injection tests past their budget while proving
@@ -265,6 +267,15 @@ function resolveWindowsSid(): string {
   return sid.toUpperCase();
 }
 
+function windowsLocalAppData(): string {
+  try {
+    return resolveWindowsLocalAppData(() => powershellValue(windowsLocalAppDataExpression()));
+  } catch (cause) {
+    if (cause instanceof CodexUserIdentityRefusal) throw cause;
+    refuse("Windows LocalAppData resolution failed.", cause);
+  }
+}
+
 export const resolveEffectiveUserIdentity: ResolveEffectiveUserIdentity = () => {
   if (process.platform === "win32") {
     return { platform: "win32", sid: resolveWindowsSid() };
@@ -374,7 +385,7 @@ export function probeCodexCoordinatorNamespace(identity: UserIdentity): Coordina
   }
 
   if (!SID_PATTERN.test(identity.sid)) refuse("The coordinator identity contains an invalid SID.");
-  const localAppData = powershellValue(windowsLocalAppDataExpression());
+  const localAppData = windowsLocalAppData();
   if (!isAbsolute(localAppData)) refuse("Windows LocalAppData resolution returned a relative path.");
   const root = resolve(localAppData, "OpenCodex", "Runtime", "v1", identity.sid.toUpperCase());
   let entry;
@@ -404,10 +415,10 @@ export function probeCodexCoordinatorNamespace(identity: UserIdentity): Coordina
 
 function resolveWindowsRuntimeRoot(identity: Extract<UserIdentity, { platform: "win32" }>): string {
   if (!SID_PATTERN.test(identity.sid)) refuse("The coordinator identity contains an invalid SID.");
-  const localAppData = powershellValue(windowsLocalAppDataExpression());
+  const localAppData = windowsLocalAppData();
   if (!isAbsolute(localAppData)) refuse("Windows LocalAppData resolution returned a relative path.");
 
-  // The SID and known-folder values come from the effective token/.NET OS APIs,
+  // The SID and known-folder values come from effective-token OS APIs,
   // never USERPROFILE or LOCALAPPDATA. WP11 adds descriptor/reparse/ACL checks at
   // the stable-database open boundary where those checks can cover SQLite too.
   const root = resolve(localAppData, "OpenCodex", "Runtime", "v1", identity.sid.toUpperCase());

package/src/codex/websocket-activity.ts

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { isAuthorizedProviderExecutedCall, type ProviderExecutedCallType } from "../server/responses-undeclared-tool-guard";
+
+// Logical recency avoids clock adjustments and ties between messages in one millisecond.
+let activityOrder = 0;
+const MAX_PENDING_RESULTS = 1024;
+const MAX_RESULT_ID_LENGTH = 1024;
+const resultTypes: Readonly<Record<string, string>> = {
+  function_call: "function_call_output",
+  custom_tool_call: "custom_tool_call_output",
+  local_shell_call: "function_call_output",
+  shell_call: "shell_call_output",
+  computer_call: "computer_call_output",
+  apply_patch_call: "apply_patch_call_output",
+  tool_search_call: "tool_search_output",
+  mcp_approval_request: "mcp_approval_response",
+};
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function resultKey(type: string, id: string): string {
+  return createHash("sha256").update(JSON.stringify([type, id])).digest("hex");
+}
+
+/** Content-free activity owned by one admitted incoming Responses socket. */
+export class CodexWebSocketActivity {
+  lastUsed = ++activityOrder;
+  closing = false;
+  private turns = 0;
+  private pendingResults = new Set<string>();
+  private returnedResults = new Set<string>();
+  // Hashed identities only; null marks a route-authorized provider-owned call.
+  private argumentCalls = new Map<string, { type: string; result: string | null }>();
+  // Unknown/oversized identities cannot safely prove that client work finished.
+  private untrackedResults = false;
+
+  get idle(): boolean {
+    return !this.closing && this.turns === 0 && this.pendingResults.size === 0 && !this.untrackedResults;
+  }
+
+  touch(): void {
+    this.lastUsed = ++activityOrder;
+  }
+
+  /** Each turn retains its own busy reference, including superseded async cleanup. */
+  beginTurn(input: unknown): () => void {
+    this.turns += 1;
+    this.touch();
+    this.acceptResults(input);
+    // Ordinary creates start a new response even when its upstream omits response.created.
+    // Prior results settle old waits, but cannot suppress new calls reusing their IDs.
+    this.returnedResults.clear();
+    this.argumentCalls.clear();
+    let finished = false;
+    return () => {
+      if (finished) return;
+      finished = true;
+      this.turns -= 1;
+      if (this.turns === 0) this.touch();
+    };
+  }
+
+  /** Called only after admission or native control accepts the client's results. */
+  acceptResults(input: unknown): void {
+    if (this.untrackedResults) return;
+    if (Array.isArray(input)) {
+      for (const item of input) {
+        if (!record(item) || typeof item.type !== "string") continue;
+        const id = item.type === "mcp_approval_response" ? item.approval_request_id : item.call_id;
+        if (typeof id === "string" && id.length <= MAX_RESULT_ID_LENGTH) {
+          // Ordinary Codex shell results use function_call_output; native steering
+          // also accepts its explicit local_shell_call_output continuation stub.
+          const type = item.type === "local_shell_call_output" ? "function_call_output" : item.type;
+          const key = resultKey(type, id);
+          if (this.pendingResults.delete(key)) {
+            if (this.returnedResults.size >= MAX_PENDING_RESULTS) { this.protectUntracked(); return; }
+            else this.returnedResults.add(key);
+          }
+        }
+      }
+    }
+  }
+
+  /** Preserve tool waits even when the response terminal omits its output array. */
+  observePayload(payload: string, providerExecuted?: ReadonlySet<ProviderExecutedCallType>): void {
+    if (this.untrackedResults) return;
+    let frame: unknown;
+    try { frame = JSON.parse(payload); } catch { return; }
+    if (!record(frame)) return;
+    // Native injection can return a result before the same terminal repeats its call.
+    if (frame.type === "response.created") {
+      this.returnedResults.clear();
+      this.argumentCalls.clear();
+    }
+    if (frame.type === "response.output_item.added") this.rememberArgumentCall(frame.item, providerExecuted);
+    if (frame.type === "response.function_call_arguments.done" || frame.type === "response.custom_tool_call_input.done") {
+      const type = frame.type === "response.function_call_arguments.done" ? "function_call" : "custom_tool_call";
+      const call = typeof frame.item_id === "string" && frame.item_id.length <= MAX_RESULT_ID_LENGTH
+        ? this.argumentCalls.get(resultKey("item", frame.item_id)) : undefined;
+      if (!call || call.type !== type) this.protectUntracked();
+      else if (call.result !== null) this.observeResultKey(call.result);
+    }
+    if (frame.type === "response.output_item.done") this.observeOutput(frame.item, providerExecuted);
+    if (["response.completed", "response.incomplete", "response.failed"].includes(String(frame.type))
+      && record(frame.response) && Array.isArray(frame.response.output)) {
+      for (const item of frame.response.output) this.observeOutput(item, providerExecuted);
+    }
+  }
+
+  private rememberArgumentCall(item: unknown, providerExecuted?: ReadonlySet<ProviderExecutedCallType>): void {
+    if (!record(item) || (item.type !== "function_call" && item.type !== "custom_tool_call")) return;
+    if (typeof item.id !== "string" || !item.id.length || item.id.length > MAX_RESULT_ID_LENGTH) return;
+    const key = resultKey("item", item.id);
+    const hosted = providerExecuted && isAuthorizedProviderExecutedCall(item, providerExecuted);
+    if (!hosted && (typeof item.call_id !== "string" || !item.call_id.length || item.call_id.length > MAX_RESULT_ID_LENGTH)) {
+      if (this.argumentCalls.has(key)) this.protectUntracked();
+      return;
+    }
+    const result = hosted ? null : resultKey(resultTypes[item.type]!, item.call_id as string);
+    const previous = this.argumentCalls.get(key);
+    if (previous) {
+      if (previous.type !== item.type || previous.result !== result) this.protectUntracked();
+      return;
+    }
+    if (this.argumentCalls.size >= MAX_PENDING_RESULTS) { this.protectUntracked(); return; }
+    // An unfinished argument stream alone does not prove the client started work.
+    this.argumentCalls.set(key, { type: item.type, result });
+  }
+
+  private observeOutput(item: unknown, providerExecuted?: ReadonlySet<ProviderExecutedCallType>): void {
+    if (this.untrackedResults) return;
+    if (!record(item) || typeof item.type !== "string") return;
+    // Hosted execution may publish both the call and its result in the output stream.
+    this.acceptResults([item]);
+    if (!Object.hasOwn(resultTypes, item.type)) return;
+    if (providerExecuted && isAuthorizedProviderExecutedCall(item, providerExecuted)) return;
+    if (item.type === "tool_search_call" && item.execution !== "client") return;
+    const id = item.type === "mcp_approval_request" ? item.id
+      : item.type === "local_shell_call" || item.type === "tool_search_call" ? item.call_id ?? item.id : item.call_id;
+    if (typeof id !== "string" || !id.length || id.length > MAX_RESULT_ID_LENGTH) {
+      this.protectUntracked();
+      return;
+    }
+    this.observeResultKey(resultKey(resultTypes[item.type]!, id));
+  }
+
+  private observeResultKey(key: string): void {
+    if (this.pendingResults.has(key) || this.returnedResults.has(key)) return;
+    if (this.pendingResults.size >= MAX_PENDING_RESULTS) this.protectUntracked();
+    else this.pendingResults.add(key);
+  }
+
+  private protectUntracked(): void {
+    this.untrackedResults = true;
+    this.pendingResults.clear();
+    this.returnedResults.clear();
+    this.argumentCalls.clear();
+  }
+}

package/src/codex/websocket-registry.ts

@@ -1,23 +1,47 @@
 import type { ServerWebSocket } from "bun";
 import type { WsData } from "../server/ws-bridge";
 import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
+import { CodexWebSocketActivity } from "./websocket-activity";
 
 export const MAX_TRACKED_CODEX_WEBSOCKETS = 128;
 const websocketGate = createAdmissionGate("codex_websockets", MAX_TRACKED_CODEX_WEBSOCKETS);
+const admittedSockets = new Set<ServerWebSocket<WsData>>();
+
+function reclaimOldestIdleSocket(): void {
+  let oldest: ServerWebSocket<WsData> | undefined;
+  for (const ws of admittedSockets) {
+    const activity = ws.data.responsesActivity;
+    if (!activity?.idle || ws.data.nativeControl || ws.readyState !== 1 || ws.getBufferedAmount() !== 0) continue;
+    if (!oldest || activity.lastUsed < oldest.data.responsesActivity!.lastUsed) oldest = ws;
+  }
+  if (!oldest) return;
+  // Fence late frames before closing. Only the actual close callback releases admission.
+  oldest.data.responsesActivity!.closing = true;
+  try {
+    oldest.close(1001, "Idle Responses connection reclaimed");
+  } catch {
+    // A failed/delayed close never manufactures a free slot or retries another victim.
+    if (oldest.readyState === 1) oldest.data.responsesActivity!.closing = false;
+  }
+}
 
 export function tryReserveCodexWebSocket(): AdmissionReservation<ServerWebSocket<WsData>> | null {
+  if (websocketGate.metrics().active >= MAX_TRACKED_CODEX_WEBSOCKETS) reclaimOldestIdleSocket();
   const gateLease = websocketGate.tryAcquire();
   if (!gateLease) return null;
   let socket: ServerWebSocket<WsData> | undefined;
   let active = true;
   return {
     bind(value) {
-      if (!active) return;
+      if (!active || socket) return;
       socket = value;
+      socket.data.responsesActivity = new CodexWebSocketActivity();
+      admittedSockets.add(socket);
     },
     release() {
       if (!active) return;
       active = false;
+      if (socket) admittedSockets.delete(socket);
       socket = undefined;
       gateLease.release();
     },

package/src/codex/windows-local-appdata.ts

@@ -0,0 +1,84 @@
+import { dlopen, ptr, read, type Pointer } from "bun:ffi";
+import { win32 } from "node:path";
+import { resolveTrustedWindowsSystemDirectory } from "../lib/windows-elevation";
+
+// FOLDERID_LocalAppData: GUID fields Data1/Data2/Data3 are little-endian.
+const LOCAL_APPDATA_ID = Buffer.from("8527b3f1ba6fcf4f9d557b8e7f157091", "hex");
+const KF_FLAG_DEFAULT_PATH = 0x400;
+const MAX_PATH_CODE_UNITS = 32_768;
+
+export interface WindowsKnownFolderApi {
+  getPath(id: Uint8Array, flags: number, token: null, output: BigUint64Array): number;
+  readCodeUnit(address: number, byteOffset: number): number;
+  free(address: number): void;
+}
+
+/** Same current-token/default-path API as the PowerShell fallback, without Add-Type. */
+export function readWindowsLocalAppData(api: WindowsKnownFolderApi): string {
+  const output = new BigUint64Array(1);
+  let address = 0;
+  try {
+    const hr = api.getPath(LOCAL_APPDATA_ID, KF_FLAG_DEFAULT_PATH, null, output);
+    address = Number(output[0]);
+    if (hr !== 0 || !Number.isSafeInteger(address) || address <= 0) {
+      throw new Error("Windows LocalAppData known-folder lookup failed.");
+    }
+    const units: number[] = [];
+    for (let index = 0; index < MAX_PATH_CODE_UNITS; index += 1) {
+      const unit = api.readCodeUnit(address, index * 2);
+      if (unit === 0) {
+        const path = String.fromCharCode(...units);
+        if (!win32.isAbsolute(path) || !/^[a-z]:\\|^\\\\/i.test(path)) {
+          throw new Error("Windows LocalAppData known-folder lookup returned an invalid path.");
+        }
+        return path;
+      }
+      units.push(unit);
+    }
+    throw new Error("Windows LocalAppData known-folder lookup returned an unterminated path.");
+  } finally {
+    // SHGetKnownFolderPath requires CoTaskMemFree even on a failed HRESULT.
+    if (address > 0 && Number.isSafeInteger(address)) api.free(address);
+  }
+}
+
+let nativeLookup: (() => string) | null | undefined;
+
+function loadNativeLookup(): (() => string) | null {
+  if (nativeLookup !== undefined) return nativeLookup;
+  if (process.platform !== "win32" || process.arch !== "x64") return null;
+  try {
+    const systemDirectory = resolveTrustedWindowsSystemDirectory();
+    const shell = dlopen(win32.join(systemDirectory, "shell32.dll"), {
+      SHGetKnownFolderPath: { args: ["ptr", "u32", "ptr", "ptr"], returns: "i32" },
+    });
+    let ole;
+    try {
+      ole = dlopen(win32.join(systemDirectory, "ole32.dll"), {
+        CoTaskMemFree: { args: ["ptr"], returns: "void" },
+      });
+    } catch (error) {
+      shell.close();
+      throw error;
+    }
+    const api: WindowsKnownFolderApi = {
+      getPath: (id, flags, token, output) => shell.symbols.SHGetKnownFolderPath(
+        ptr(id), flags, token, ptr(output),
+      ),
+      readCodeUnit: (address, offset) => read.u16(address as Pointer, offset),
+      free: address => { ole.symbols.CoTaskMemFree(address as Pointer); },
+    };
+    nativeLookup = () => readWindowsLocalAppData(api);
+  } catch {
+    nativeLookup = null;
+  }
+  return nativeLookup;
+}
+
+/** Unsupported FFI keeps the bounded trusted helper; an OS API failure still refuses. */
+export function resolveWindowsLocalAppData(
+  powershellLookup: () => string,
+  lookup: (() => string) | null = loadNativeLookup(),
+): string {
+  return lookup ? lookup() : powershellLookup();
+}

package/src/combos/failover.ts

@@ -403,6 +403,9 @@ const REQUEST_SHAPE_FAILURE_CODES = new Set([
   "tool_catalog_too_large",
   "cursor_root_envelope_limit",
   "target_incompatible",
+  // A route that cannot read the request's media (image input to a text-only CLI route) is
+  // healthy for every other request, so cooling it would only block unrelated turns.
+  "unsupported_input_modality",
 ]);
 
 /** Credential/billing failures that every target sharing the provider inherits. */
@@ -836,7 +839,9 @@ export function comboFailureDecision(
   // says nothing about the next combo target. Structured code only, plus the explicit prose
   // form upstreams emit when they carry no code, so an unrelated 400 stays terminal.
   const failureCode = normalizedFailureCode(options?.code || error.code);
-  if (["model_not_found", "model_unavailable", "unsupported_model"].includes(failureCode)) {
+  // The input-modality refusal is the same kind of verdict: this route cannot read the turn's
+  // media, and a later target may. Its 400 would otherwise end the chain as invalid_request_error.
+  if (["model_not_found", "model_unavailable", "unsupported_model", "unsupported_input_modality"].includes(failureCode)) {
     return "hop";
   }
   if (modelRefusal === "refusal") return "hop";

package/src/combos/index.ts

@@ -22,6 +22,7 @@ export {
 export {
   advanceComboAfterFailure,
   clearComboSelectionState,
+  comboExclusionReasons,
   NoAvailableComboTargetsError,
   noteComboFailure,
   noteComboSuccess,

package/src/combos/resolve.ts

@@ -55,17 +55,49 @@ export class UnknownComboError extends Error {
 export class NoAvailableComboTargetsError extends Error {
   readonly code = "combo_unavailable";
 
-  constructor(readonly comboId: string) {
-    super(`No available targets for combo: ${comboId}`);
+  constructor(readonly comboId: string, readonly reasons = "") {
+    super(`No available targets for combo: ${comboId}${reasons ? ` (${reasons})` : ""}`);
     this.name = "NoAvailableComboTargetsError";
   }
 }
 
+function providerExclusionReason(config: OcxConfig, target: OcxComboTarget, now: number): string | undefined {
+  const provider = Object.hasOwn(config.providers, target.provider) ? config.providers[target.provider] : undefined;
+  if (!provider) return "provider missing";
+  if (provider.disabled === true) return "provider disabled";
+  return cachedProviderQuotaIsExhausted(getCachedProviderRoutingQuota(target.provider, provider, now), now, target.model)
+    ? "quota exhausted"
+    : undefined;
+}
+
 function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget, now: number): boolean {
-  if (!Object.hasOwn(config.providers, target.provider)) return false;
-  const provider = config.providers[target.provider];
-  if (!provider || provider.disabled === true) return false;
-  return !cachedProviderQuotaIsExhausted(getCachedProviderRoutingQuota(target.provider, provider, now), now, target.model);
+  return providerExclusionReason(config, target, now) === undefined;
+}
+
+/**
+ * Why each target of a combo cannot be picked right now, for a zero-attempt refusal. Only the
+ * configured provider/model and a coarse label are named, never account or request data.
+ */
+export function comboExclusionReasons(
+  config: OcxConfig,
+  comboId: string,
+  eligible?: (target: NormalizedComboTarget) => boolean,
+  now = Date.now(),
+): string {
+  return (getCombo(config, comboId)?.targets ?? []).flatMap(target => {
+    let reason = providerExclusionReason(config, target, now);
+    const cooldown = reason ? undefined : earliestComboCooldown(comboId, [target], now);
+    if (cooldown) reason = `cooldown ${Math.max(1, Math.ceil((cooldown.expiry - now) / 1000))}s`;
+    if (!reason && eligible) {
+      try {
+        if (!eligible(target)) reason = "ineligible for this request";
+      } catch {
+        // An eligibility check can exhaust the translator budget; the target still was not picked.
+        reason = "ineligible for this request";
+      }
+    }
+    return reason ? [`${targetKey(target)}: ${reason}`] : [];
+  }).join("; ");
 }
 
 /** Capture usable providers' quota cooldowns; request eligibility is deferred to exhaustion. */
@@ -100,6 +132,9 @@ function quotaWindowExhausted(percent: number | undefined, resetAt: number | und
 const MODEL_FAMILY_WINDOW_LABELS = new Set(["fable", "opus", "sonnet"]);
 
 function customWindowAppliesToModel(window: ProviderQuotaWindow, model: string | undefined): boolean {
+  // Exact Antigravity model readings are diagnostic only. They are not permission or
+  // provider-wide exhaustion evidence until a separate eligibility contract consumes them.
+  if (window.modelId !== undefined) return false;
   if (window.scope !== "model" || model === undefined) return true;
   const family = window.label.trim().toLowerCase();
   if (!MODEL_FAMILY_WINDOW_LABELS.has(family)) return true;
@@ -408,9 +443,10 @@ export function advanceComboAfterFailure(
   // including the pool's OWN "all accounts are cooled" 429, which refuses locally before it picks
   // one. That is what keeps this from trading a blackhole for a hammer: when nothing else is
   // holding the target back, the target cooldown still does.
-  const accountScoped = options.cooldownScope === "target"
-    && options.status === 429
-    && options.failedAccount !== undefined;
+  // A 402 credit refusal is the provider-scoped twin: the caller names an account only after the
+  // pool has cooled it and still holds an eligible sibling.
+  const accountScoped = options.failedAccount !== undefined
+    && (options.status === 429 ? options.cooldownScope === "target" : options.status === 402);
   // "none" records no cooldown at all: the failure described the request, not the target, so
   // the target must stay immediately selectable for the next (differently shaped) request.
   if (options.cooldownScope !== "none" && !accountScoped) {
@@ -612,6 +648,6 @@ export function tryPickComboModel(config: OcxConfig, modelId: string, preview =
   if (!comboId) return null;
   if (!getCombo(config, comboId)) throw new UnknownComboError(comboId);
   const picked = pickComboTarget(config, comboId, { preview });
-  if (!picked) throw new NoAvailableComboTargetsError(comboId);
+  if (!picked) throw new NoAvailableComboTargetsError(comboId, comboExclusionReasons(config, comboId));
   return picked;
 }

package/src/combos/types.ts

@@ -39,12 +39,16 @@ export interface NormalizedComboTarget {
   weight: number;
   /** Emergency-only target, deferred under `cooldownWaitPolicy` (#5691). */
   lastResort: boolean;
+  /** Pay-per-use target; requires key consent or loopback-only operator consent. */
+  metered: boolean;
   reasoningEfforts?: OcxComboDefaultEffort[];
   /** Optional JEV decision description. */
   modelProfile?: string;
 }
 
 export interface NormalizedComboConfig {
+  /** Operator consent, effective only on a loopback-only proxy. */
+  allowMeteredTargets?: boolean;
   strategy: OcxComboStrategy;
   stickyLimit: number;
   cooldownMs?: number;
@@ -164,6 +168,9 @@ export function comboConfigIssues(
   }
 
   const body = raw as Record<string, unknown>;
+  if (body.allowMeteredTargets !== undefined && typeof body.allowMeteredTargets !== "boolean") {
+    issues.push({ path: ["allowMeteredTargets"], message: "allowMeteredTargets must be a boolean" });
+  }
   if (typeof body.alias === "string") {
     const alias = body.alias.toLowerCase();
     for (const [providerName, provider] of Object.entries(providers)) {
@@ -427,6 +434,12 @@ export function comboConfigIssues(
         message: `targets[${i}].lastResort must be a boolean`,
       });
     }
+    if (target.metered !== undefined && typeof target.metered !== "boolean") {
+      issues.push({
+        path: ["targets", i, "metered"],
+        message: `targets[${i}].metered must be a boolean`,
+      });
+    }
     if (target.modelProfile !== undefined
       && (typeof target.modelProfile !== "string"
         || target.modelProfile.trim().length === 0
@@ -477,6 +490,7 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
     : null;
   return {
     strategy: raw.strategy ?? "failover",
+    ...(raw.allowMeteredTargets === true ? { allowMeteredTargets: true } : {}),
     stickyLimit: raw.stickyLimit ?? 1,
     cooldownMs: raw.cooldownMs,
     waitForCooldownMs: raw.waitForCooldownMs ?? COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS,
@@ -503,6 +517,7 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
         ? { modelProfile: target.modelProfile.trim() }
         : {}),
       lastResort: target.lastResort === true,
+      metered: target.metered === true,
     })),
   };
 }