@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/codex/routing/pool-recovery.ts

@@ -0,0 +1,79 @@
+/**
+ * When another stored pool account can serve again, for a main-account hard-lock refusal (#7046).
+ *
+ * A pool request that fell through to the main login and met the main-account quota guard used
+ * to be told to come back at main's own reset, which can be days away while a sibling pool
+ * account recovers within hours. This module answers one question: the earliest KNOWN instant at
+ * which a stored pool account's every temporary hold ends. It changes no routing state, selects
+ * nothing, and never lifts the main guard. The client retries at that time, and ordinary selection
+ * decides again from fresh state; a reset timestamp is a hint, not proof of fresh quota.
+ *
+ * Conservative by construction (the policy Jun is asked to confirm in #7046):
+ * - An account is a candidate only when it is a selectable stored pool account that is not
+ *   paused, plan-excluded, quarantined for sign-in, otherwise unusable, or denied for the model.
+ *   Those are operator or credential states no clock lifts.
+ * - Its recovery time is the LATEST of every routing hold with a known end: quota-health cooldown,
+ *   quota avoidance, transient soft avoidance, pool-refresh backoff, and the credits-off
+ *   usage-limit reset. An account under a hold whose end is unknown, or under the sliding
+ *   failure-window guard (whose end moves with every failure), is skipped rather than guessed.
+ * - For an account-gated model, only accounts the resolved entitlement roster admits count, and
+ *   with no resolved roster nothing does.
+ * - An account with no recorded hold is skipped: nothing says when it became unavailable, so
+ *   nothing says when it will be available again.
+ * - Main itself is never a candidate; its own reset stays on the refusal.
+ */
+import { isCodexAccountPaused } from "../account-pause";
+import { codexUsageLimitResetAt } from "../account-credit-use";
+import { isSelectableCodexPoolAccount } from "../account-id";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { isCodexAccountUsable } from "../account-usability";
+import { getCodexPoolRefreshCooldownUntil } from "../pool-refresh-backoff";
+import { getAccountQuota } from "../quota";
+import type { OcxConfig } from "../../types";
+import { failureWindowSteersNewThreads } from "./failure-window";
+import {
+  codexQuotaAvoidUntil, getCodexAccountSoftAvoidUntil, getCodexQuotaHealthSnapshot, type CodexQuotaScope,
+} from "./health-store";
+import { getPoolAccountPlanForSelection, isCodexAccountHeldAtUsageLimit, isCodexAccountPlanExcluded } from "./selection";
+
+export function nextCodexPoolRecoveryAt(
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+  options: {
+    deniedAccountIds?: ReadonlySet<string>;
+    /** When set, only these accounts may serve the model (account-gated models). */
+    eligibleAccountIds?: ReadonlySet<string>;
+  } = {},
+): number | undefined {
+  let earliest: number | undefined;
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const id = account.id;
+    if (options.deniedAccountIds?.has(id) || (options.eligibleAccountIds && !options.eligibleAccountIds.has(id))
+      || isCodexAccountPaused(config, id)
+      || isCodexAccountPlanExcluded(config, id) || isAccountNeedsReauth(id)
+      || !isCodexAccountUsable(config, id) || failureWindowSteersNewThreads(config, id, now)) continue;
+    const holds: number[] = [];
+    const health = getCodexQuotaHealthSnapshot(id, quotaScope, now);
+    if (health) {
+      if (typeof health.cooldownUntil !== "number" || !Number.isFinite(health.cooldownUntil)) continue;
+      holds.push(health.cooldownUntil);
+    }
+    const avoidUntil = codexQuotaAvoidUntil(id, quotaScope, now);
+    if (avoidUntil !== null) holds.push(avoidUntil);
+    const softAvoidUntil = getCodexAccountSoftAvoidUntil(id, now);
+    if (softAvoidUntil !== null) holds.push(softAvoidUntil);
+    const refreshCooldownUntil = getCodexPoolRefreshCooldownUntil(id, now);
+    if (refreshCooldownUntil !== null) holds.push(refreshCooldownUntil);
+    if (isCodexAccountHeldAtUsageLimit(config, id, now)) {
+      const resetAt = codexUsageLimitResetAt(getAccountQuota(id), getPoolAccountPlanForSelection(config, id), now);
+      if (resetAt === undefined) continue;
+      holds.push(resetAt);
+    }
+    if (holds.length === 0) continue;
+    const recoveryAt = Math.max(...holds);
+    if (recoveryAt > now && (earliest === undefined || recoveryAt < earliest)) earliest = recoveryAt;
+  }
+  return earliest;
+}

package/src/codex/routing/selection.ts

@@ -1,7 +1,8 @@
 import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
 import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use";
 import { isCodexAccountPaused } from "../account-pause";
-import { codexAccountPriorityLookup, pinnedCodexAccountId } from "../account-priority";
+import { pinnedCodexAccountId } from "../account-priority";
+import { codexSelectionPriorityLookup } from "../account-preservation";
 import { isSelectableCodexPoolAccount } from "../account-id";
 import { isAccountNeedsReauth } from "../account-runtime-state";
 import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "../account-usability";
@@ -248,7 +249,7 @@ export function getEligiblePoolAccounts(
   const pinned = pinnedCodexAccountId(config);
   return selectPriorityTier(
     withoutModelDeniedAccounts(ids, selectionOptions?.deniedModelAccountIds, pinned),
-    codexAccountPriorityLookup(config),
+    codexSelectionPriorityLookup(config),
     id => hasCodexQuotaHeadroom(config, id, selectionOptions, now),
     pinned,
   );
@@ -767,7 +768,7 @@ export function pickPriorityPreemption(
     && eligible.includes(pinned)
     && hasCodexQuotaHeadroom(config, pinned, selectionOptions, now)
   ) return null;
-  const priorityOf = codexAccountPriorityLookup(config);
+  const priorityOf = codexSelectionPriorityLookup(config);
   if (priorityOf(eligible[0]!) <= priorityOf(active)) return null;
   // Members without headroom are in the tier only because a sibling has some;
   // picking one would hand the request straight back to a drained account.

package/src/codex/routing/thread-affinity.ts

@@ -1,5 +1,5 @@
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "../account-store";
-import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { MAIN_CODEX_ACCOUNT_ID } from "../account-id";
 import { retainedUtf8Bytes } from "../../lib/admission";
 import { clearAllCodexPoolRefreshFailures } from "../pool-refresh-backoff";
 import type { CodexThreadLineage } from "../lineage";

package/src/codex/shim-diagnostics.ts

@@ -29,6 +29,12 @@ export interface CodexShimDiagnostic {
   summary: string;
   runnable?: boolean;
   active?: boolean | null;
+  /**
+   * PATH overlay only: the wrapper and its private state are intact and runnable, but this process
+   * could not see it first on PATH. Reinstalling cannot change that; the shell must source the
+   * environment file. The dashboard's PATH can also differ from the user's shell (#6971).
+   */
+  activationPending?: boolean;
 }
 
 /** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */

package/src/codex/shim-overlay.ts

@@ -44,6 +44,10 @@ export function overlayActivationHint(configDir = getConfigDir()): string {
 function sameId(left: OverlayIdentity | null | undefined, right: OverlayIdentity | null | undefined): boolean {
   return !!left && !!right && left.dev === right.dev && left.ino === right.ino;
 }
+/** APFS device numbers can change after reboot; persisted ownership still requires the same inode. */
+function samePersistedInode(current: OverlayIdentity, recorded: OverlayIdentity | undefined): boolean {
+  return !!recorded && current.ino === recorded.ino;
+}
 function lexical(path: string): Stats | null {
   try { return lstatSync(path); }
   catch (error) { if (fileErrorCode(error) === "ENOENT") return null; throw error; }
@@ -128,7 +132,7 @@ function shellEnvironment(): string {
     'unset ocx_shim_dir ocx_shim_rest ocx_shim_path ocx_shim_more ocx_shim_part', ""].join("\n");
 }
 function ownedWrapper(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.wrapperIdentity)
+  return samePersistedInode(value.identity, state.wrapperIdentity)
     && value.content.includes(SHIM_MARKER) && value.content.includes(`exec ${shQuote(state.launcherPath)} "$@"`);
 }
 function requireOverlayIdentities(state: OverlayState): void {
@@ -137,7 +141,7 @@ function requireOverlayIdentities(state: OverlayState): void {
   }
 }
 function ownedEnvironment(value: Snapshot, state: OverlayState): boolean {
-  return sameId(value.identity, state.envIdentity) && value.content === shellEnvironment();
+  return samePersistedInode(value.identity, state.envIdentity) && value.content === shellEnvironment();
 }
 function revalidateOverlay(state: OverlayState, saved: Snapshot | null, wrapper: Snapshot | null, env: Snapshot | null): void {
   if (!unchanged(statePath(), saved) || !unchanged(state.wrapperPath, wrapper) || !unchanged(overlayPaths().env, env)) {
@@ -201,6 +205,7 @@ export function overlayDiagnostic(state: ShimState): CodexShimDiagnostic {
     inspection?.revalidate();
   } catch (error) { active = null; runnable = false; integrityMessage = failure(error).message; }
   return { installed: true, healthy: complete && runnable && active === true, runnable, active,
+    activationPending: complete && runnable && active !== true,
     summary: `Codex PATH shim: ${complete && runnable ? "ready" : "unhealthy"} at ${state.wrapperPath}; launcher ${state.launcherPath}; PATH ${active === null ? "unverified" : active ? "active" : "inactive"}. ${complete && runnable ? overlayActivationHint() : integrityMessage || "Run ocx codex-shim install to repair the shim."}` };
 }
 

package/src/codex/signed-in-identity.ts

@@ -0,0 +1,43 @@
+import { extractEmail, inspectChatGptDomainClaim } from "../oauth/chatgpt";
+import type { CodexTokens } from "./auth-collision";
+
+export type CodexLoginIdentity = Readonly<{ accountId: string; email: string }>;
+let observed: CodexLoginIdentity | undefined;
+
+export function codexLoginIdentity(accountId: unknown, email: unknown): CodexLoginIdentity | undefined {
+  const member = typeof email === "string" ? email.trim().toLowerCase() : "";
+  const workspace = typeof accountId === "string" ? accountId.trim() : "";
+  return workspace && member ? { accountId: workspace, email: member } : undefined;
+}
+
+/** Undefined is insufficient evidence; null means conflicting or malformed token evidence. */
+export function codexTokenIdentity(tokens: CodexTokens): CodexLoginIdentity | undefined | null {
+  if (typeof tokens.access_token !== "string" || typeof tokens.account_id !== "string"
+    || (tokens.id_token !== undefined && typeof tokens.id_token !== "string")) return null;
+  const claims = [tokens.id_token, tokens.access_token]
+    .filter((token): token is string => typeof token === "string")
+    .map(inspectChatGptDomainClaim);
+  if (claims.some(claim => claim.kind === "invalid")) return null;
+  const claimIds = claims.flatMap(claim => claim.kind === "valid" ? [claim.accountId] : []);
+  const accountId = tokens.account_id.trim() || claimIds[0];
+  if (claimIds.some(claim => claim !== accountId)) return null;
+  const emails = new Set([extractEmail(tokens.id_token), extractEmail(undefined, tokens.access_token)]
+    .flatMap(email => email?.trim() ? [email.trim().toLowerCase()] : []));
+  if (emails.size > 1) return null;
+  return codexLoginIdentity(accountId, [...emails][0]);
+}
+
+/** Publish only from an existing physical-login observation, never an incoming bearer. */
+export function observeSignedInCodexIdentity(tokens?: CodexTokens): void {
+  if (!tokens) { observed = undefined; return; }
+  const next = codexTokenIdentity(tokens);
+  // Conflicting claims can be a partial external write, never proof of a new login.
+  if (next !== null) observed = next;
+}
+
+/** Routing reads memory only, including while the native profile is fenced. */
+export function getSignedInCodexIdentity(): CodexLoginIdentity | undefined { return observed; }
+
+export function sameCodexLogin(a: CodexLoginIdentity, b: CodexLoginIdentity | undefined): boolean {
+  return a.accountId === b?.accountId && a.email === b.email;
+}

package/src/codex/subagent-model-fallback.ts

@@ -591,7 +591,7 @@ export function maybePrimeSubagentQuota(
       if (subagentQuotaPrimeForTests) {
         await subagentQuotaPrimeForTests(config, "subagent-spawn");
       } else {
-        const { primeCodexPoolQuotas } = await import("./auth-api");
+        const { primeCodexPoolQuotas } = await import("./auth-api/pool-mode-gate");
         await primeCodexPoolQuotas(config, "subagent-spawn");
       }
       quotaPrimedAt.set("global", Date.now());

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/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,
     })),
   };
 }