@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/claude/intercept/runtime.ts

@@ -1,4 +1,5 @@
 import type { Server } from "bun";
+import { supportsDesktopPicker } from "../desktop-picker-platform";
 import type { OcxConfig } from "../../types";
 import { getConfigDir } from "../../config/paths";
 import type { DesktopPickerController } from "../desktop-picker";
@@ -12,6 +13,7 @@ import { discardPickerCaKey } from "./picker-ca";
 import { preparePersistentPickerAuthority } from "./picker-ca-startup";
 import type { PickerCaStore } from "./picker-ca-store";
 import type { PickerRouteInput } from "./picker-models";
+import { CLAUDE_INTERCEPT_PORT_OFFSET, claudeInterceptEnabled, claudeInterceptProxyPort, claudePickerProxyPort } from "./port-policy";
 import { createPickerRuntime, pickerDesired, type CreatePickerRuntimeOptions, type PickerRuntime } from "./picker-runtime";
 import type { SecurityRunner } from "./picker-trust";
 import { ensureClaudeInterceptProxyToken, readClaudeInterceptProxyToken } from "./proxy-auth";
@@ -28,7 +30,7 @@ import { buildClaudeInterceptEnv, migrateClaudeInterceptSettings } from "./setti
  * proxy. Desktop also hands that proxy to the Claude Code processes it spawns, so the choice is per
  * client: Claude Code (no User-Agent on CONNECT) trusts only the intercept CA and gets the
  * api.anthropic.com intercept and nothing else; the app itself (a browser User-Agent) trusts only
- * the login keychain and never meets the api.anthropic.com intercept, and only its claude.ai
+ * the OS root store and never meets the api.anthropic.com intercept, and only its claude.ai
  * tunnels may be terminated by the picker runtime (src/claude/intercept/picker-runtime.ts).
  */
 
@@ -41,25 +43,7 @@ const PICKER_AUTHORITY_ERROR_CODES = new Set([
   "picker_ca_unsupported_platform",
 ]);
 
-export const CLAUDE_INTERCEPT_PORT_OFFSET = 100;
-
-export function claudeInterceptEnabled(config: Pick<OcxConfig, "claudeCode" | "runtimeRole">): boolean {
-  if (config.runtimeRole === "client") return false;
-  if (config.claudeCode?.enabled === false) return false;
-  return config.claudeCode?.intercept?.enabled !== false;
-}
-
-export function claudeInterceptProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
-  const configured = config.claudeCode?.intercept?.port;
-  if (typeof configured === "number" && Number.isInteger(configured) && configured >= 1 && configured <= 65535) return configured;
-  return publicPort + CLAUDE_INTERCEPT_PORT_OFFSET;
-}
-
-/** Desktop's egress proxy for picker mode: the port after the intercept proxy (before it at 65535). */
-export function claudePickerProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
-  const interceptPort = claudeInterceptProxyPort(config, publicPort);
-  return interceptPort < 65535 ? interceptPort + 1 : interceptPort - 1;
-}
+export { CLAUDE_INTERCEPT_PORT_OFFSET, claudeInterceptEnabled, claudeInterceptProxyPort, claudePickerProxyPort } from "./port-policy";
 
 export type ClaudeInterceptOutcome = { ok: true; state: ClaudeInterceptState } | { ok: false; reason: "disabled" | "client_role" | "ephemeral_port" | "port_in_use" | "stopped" | "failed"; port?: number; message?: string };
 
@@ -144,7 +128,7 @@ export interface StartClaudeInterceptOptions<T> {
   createPicker?: (options: CreatePickerRuntimeOptions) => PickerRuntime;
   /** Test seam: bind real CONNECT handlers on kernel-assigned ports without probe-and-release races. */
   startProxy?: typeof startConnectProxy;
-  /** Test seams: the macOS `security` runner and platform for the picker runtime and controller. */
+  /** Test seams: the platform trust runner and platform for the picker runtime and controller. */
   pickerCaStore?: PickerCaStore;
   pickerSecurity?: SecurityRunner;
   pickerPlatform?: NodeJS.Platform;
@@ -167,18 +151,6 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
   const startProxy = options.startProxy ?? startConnectProxy;
   const authToken = ensureClaudeInterceptProxyToken(configDir);
   const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS);
-  // Refresh an env we already own (e.g. a pre-auth proxy URL left by an upgrade) before the
-  // authenticated proxy takes over the port — a plain `ocx start` after an update would
-  // otherwise 407 every CONNECT until the next `ocx ensure` or apply. Only `stale` state is
-  // rewritten, so installs that never applied first-party are untouched.
-  try {
-    const proxyPort = claudeInterceptProxyPort(options.config, options.publicPort);
-    migrateClaudeInterceptSettings(buildClaudeInterceptEnv(proxyPort, claudeInterceptCaCertPath(configDir), authToken));
-  } catch (error) {
-    // A skipped rewrite degrades to the pre-migration behaviour and ensure/apply retries it,
-    // but silence here leaves upgraded clients hitting 407 with no recorded cause.
-    console.warn(`[claude-intercept] settings migration skipped: ${error instanceof Error ? error.message : String(error)}`);
-  }
   const listener = startClaudeInterceptListener<T>({
     leaf,
     dispatch: options.dispatch,
@@ -203,15 +175,25 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     await listener.stop(true);
     throw new ClaudeInterceptProxyBindError(error, claudeInterceptProxyPort(options.config, options.publicPort));
   }
+  // Publish only a successfully bound endpoint, using the handle's actual port. A failed
+  // fixed-port bind leaves settings untouched; an ephemeral test binder never publishes :0
+  // or a probed port another process can steal. Only stale, owned env blocks are rewritten.
+  try {
+    migrateClaudeInterceptSettings(buildClaudeInterceptEnv(proxy.port, claudeInterceptCaCertPath(configDir), authToken));
+  } catch (error) {
+    // Ensure/apply retries a skipped migration; upgraded clients otherwise keep hitting 407.
+    console.warn(`[claude-intercept] settings migration skipped: ${error instanceof Error ? error.message : String(error)}`);
+  }
   // Widened on purpose: assignments happen in nested awaits the catch below must still see.
   let picker = null as PickerRuntime | null;
   let pickerProxy = null as ConnectProxyHandle | null;
   let controller = null as DesktopPickerController | null;
   let pickerProxyLive = false;
+  let stopped = false;
   let pickerReason: ClaudeInterceptState["pickerReason"] = null;
   let pickerFailurePort: number | undefined;
   try {
-    if (options.loadPickerRoutes && (options.pickerPlatform ?? process.platform) === "darwin") {
+    if (options.loadPickerRoutes && supportsDesktopPicker(options.pickerPlatform ?? process.platform)) {
       // Remove any legacy plaintext key before inspecting or activating picker state.
       discardPickerCaKey(configDir);
       const { inspectDesktopPickerProfile } = await import("../desktop-picker-profile");
@@ -225,11 +207,15 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
       });
       const pickerProfileApplied = pickerProfile.kind === "applied";
       let pickerBlocked = false;
+      let pickerWired = false;
       try {
         const { observeClaudeDesktopMode, resolveClaudeDesktopMode } = await import("../desktop-first-party");
         const fresh = options.config;
         const platform = options.pickerPlatform ?? process.platform;
-        if (pickerProfileApplied || pickerDesired(fresh, resolveClaudeDesktopMode(fresh, observeClaudeDesktopMode(fresh)), platform)) {
+        const pickerRequired = pickerProfileApplied || pickerDesired(fresh, resolveClaudeDesktopMode(fresh, observeClaudeDesktopMode(fresh)), platform);
+        // Preserve macOS's dormant relay; Windows defers binding until enable or profile recovery.
+        pickerWired = platform !== "win32" || pickerRequired;
+        if (pickerRequired) {
           await preparePersistentPickerAuthority({ configDir, store: options.pickerCaStore, security: options.pickerSecurity, platform });
         }
       } catch (error) {
@@ -276,63 +262,76 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
         const runtime = picker;
         const interceptPort = listener.port!;
         const pickerPort = claudePickerProxyPort(options.config, options.publicPort);
-        try {
-          pickerProxy = await startProxy(pickerPort, {
-            interceptPort,
-            // No authToken: Desktop's egressProxyUrl cannot present proxy credentials, so this
-            // listener stays an unauthenticated loopback relay until the profile format can carry
-            // one. The intercept proxy above is the credential-bearing hop.
-            // No host list here: the choice below depends on which client opened the tunnel.
-            interceptHosts: [],
-            selectTunnel: (host, port, request) => {
-              // Desktop hands its pinned egress proxy to the Claude Code processes it spawns, so their
-              // api.anthropic.com traffic arrives here too and gets the same intercept as on the Claude
-              // Code proxy. Those processes trust only the intercept CA, so the picker never terminates
-              // their claude.ai tunnels; only the app's own (browser) CONNECTs reach the picker.
-              if (!isBrowserConnect(request)) {
-                return port === 443 && (CLAUDE_INTERCEPT_HOSTS as readonly string[]).includes(host.toLowerCase())
-                  ? { kind: "intercept", port: interceptPort }
-                  : { kind: "blind" };
-              }
-              return runtime.selectTunnel(host, port);
+        const bindPickerProxy = async (): Promise<void> => {
+          if (stopped || pickerProxyLive) return;
+          try {
+            pickerProxy = await startProxy(pickerPort, {
+              interceptPort,
+              // No authToken: Desktop's egressProxyUrl cannot present proxy credentials, so this
+              // listener stays an unauthenticated loopback relay until the profile format can carry
+              // one. The intercept proxy above is the credential-bearing hop.
+              // No host list here: the choice below depends on which client opened the tunnel.
+              interceptHosts: [],
+              selectTunnel: (host, port, request) => {
+                // Desktop hands its pinned egress proxy to the Claude Code processes it spawns, so their
+                // api.anthropic.com traffic arrives here too and gets the same intercept as on the Claude
+                // Code proxy. Those processes trust only the intercept CA, so the picker never terminates
+                // their claude.ai tunnels; only the app's own (browser) CONNECTs reach the picker.
+                if (!isBrowserConnect(request)) {
+                  return port === 443 && (CLAUDE_INTERCEPT_HOSTS as readonly string[]).includes(host.toLowerCase())
+                    ? { kind: "intercept", port: interceptPort }
+                    : { kind: "blind" };
+                }
+                return runtime.selectTunnel(host, port);
+              },
+            });
+            if (stopped) { await pickerProxy.close(); return; }
+            pickerProxyLive = true;
+            pickerReason = null;
+            pickerFailurePort = undefined;
+          } catch (error) {
+            // Picker mode is optional: a busy port leaves the intercept pair running without it.
+            // The selected profile row survives; a dormant enable can retry after the port is free.
+            pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed";
+            if (pickerReason === "port_in_use") pickerFailurePort = pickerPort;
+            console.warn(`⚠ Claude Desktop picker proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+          }
+        };
+        if (pickerWired) {
+          try { await bindPickerProxy(); }
+          catch { await runtime.stop(); picker = null; }
+        }
+        if (picker) {
+          // Dynamic: the controller reaches desktop-first-party, which imports this module.
+          const [{ createDesktopPickerController }, { loadConfig }, persistPreference] = await Promise.all([
+            import("../desktop-picker"),
+            import("../../config"),
+            createPickerPreferenceWriter(options.config),
+          ]);
+          controller = createDesktopPickerController({
+            runtime: picker,
+            readConfig: loadConfig,
+            persistPreference,
+            proxyPort: () => (pickerProxyLive ? pickerProxy?.port ?? null : null),
+            ensureProxy: async () => {
+              await bindPickerProxy();
+              if (!pickerProxyLive) return;
+              await runtime.start();
+              if (!stopped && activeController === controller) activePicker = runtime;
             },
+            configDir,
+            persistentAuthority: { store: options.pickerCaStore },
+            ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}),
+            ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}),
           });
-          pickerProxyLive = true;
-        } catch (error) {
-          // Picker mode is optional: a busy port leaves the intercept pair running without it.
-          // The selected profile row survives, so the next startup retries the restore once the
-          // port is free again.
-          pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed";
-          if (pickerReason === "port_in_use") pickerFailurePort = pickerPort;
-          console.warn(`⚠ Claude Desktop picker proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
-          await runtime.stop();
-          picker = null;
-        }
-      }
-      if (picker) {
-        // Dynamic: the controller reaches desktop-first-party, which imports this module.
-        const [{ createDesktopPickerController }, { loadConfig }, persistPreference] = await Promise.all([
-          import("../desktop-picker"),
-          import("../../config"),
-          createPickerPreferenceWriter(options.config),
-        ]);
-        const boundProxy = pickerProxy;
-        controller = createDesktopPickerController({
-          runtime: picker,
-          readConfig: loadConfig,
-          persistPreference,
-          proxyPort: () => (pickerProxyLive && boundProxy ? boundProxy.port : null),
-          configDir,
-          persistentAuthority: { store: options.pickerCaStore },
-          ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}),
-          ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}),
-        });
-        await picker.start();
-        // Restore inspects the retained identity without installing trust. Explicit enable/trust
-        // owns consent when trust was revoked or legacy migration introduced a new authority.
-        if (pickerProfileApplied && controller) {
-          void controller.enable({ persist: false, context: "server", allowTrustPrompt: false })
-            .catch(error => console.warn(`⚠ Claude Desktop picker restore failed: ${error instanceof Error ? error.message : String(error)}`));
+          if (pickerWired) await picker.start();
+          // Restore inspects the retained identity without installing trust. Explicit enable/trust
+          // owns consent when trust was revoked or legacy migration introduced a new authority.
+          if (pickerProfileApplied && controller) {
+            void controller.enable({ persist: false, context: "server", allowTrustPrompt: false })
+              .catch(error => console.warn(`⚠ Claude Desktop picker restore failed: ${error instanceof Error ? error.message : String(error)}`));
+          }
         }
       }
     }
@@ -348,21 +347,25 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     throw error;
   }
   const state: ClaudeInterceptState = {
-    pickerReason,
-    pickerFailurePort,
+    get pickerReason() { return pickerReason; },
+    get pickerFailurePort() { return pickerFailurePort; },
     proxyPort: proxy.port,
     caCertPath: claudeInterceptCaCertPath(configDir),
-    pickerProxyPort: pickerProxy?.port ?? null,
+    get pickerProxyPort() { return pickerProxyLive ? pickerProxy?.port ?? null : null; },
   };
   activeState = state;
-  activePicker = picker;
+  activePicker = pickerProxyLive ? picker : null;
   activeController = controller;
   const ownPicker = picker;
   const ownController = controller;
   return {
     ...state,
+    get pickerProxyPort() { return state.pickerProxyPort; },
+    get pickerReason() { return state.pickerReason; },
+    get pickerFailurePort() { return state.pickerFailurePort; },
     listener,
     stop: async () => {
+      stopped = true;
       if (activeState === state) activeState = null;
       if (activePicker === ownPicker) activePicker = null;
       if (activeController === ownController) activeController = null;

package/src/claude/outbound.ts

@@ -1,3 +1,4 @@
+import { anthropicProgressEnvelope, isAnthropicProgressMirror } from "../responses/anthropic-progress";
 /**
  * Claude Code outbound: internal /v1/responses output -> Anthropic Messages API shapes.
  *
@@ -222,10 +223,28 @@ export function sanitizeWebSearchInput(input: unknown): Rec {
 /**
  * Map a Responses `web_search_call` item to its Anthropic pair: the server_tool_use
  * input (query/queries) and the web_search_tool_result content (hits, or the error
- * object when the search failed). Shared by the SSE and JSON translation paths.
+ * object when the search failed). An item carrying `anthropic_blocks` came from Anthropic's
+ * own server-side call and maps back to those blocks verbatim (`srvtoolu_` id,
+ * `encrypted_content`, web_fetch), so the client can replay them on its next turn.
+ * Shared by the SSE, JSON and direct translation paths.
  */
-export function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
+export function webSearchPairFromItem(item: Rec): {
+  id: string; name: string; resultType: string; input: Rec; resultContent: unknown; completed: boolean;
+} {
   const action = isRec(item.action) ? item.action : {};
+  const completed = item.status !== "failed";
+  const { use, result } = isRec(item.anthropic_blocks) ? item.anthropic_blocks : {};
+  if (isRec(use) && isRec(result) && typeof use.id === "string" && isRec(use.input)
+    && (use.name === "web_search" || use.name === "web_fetch")
+    && result.tool_use_id === use.id && result.type === `${use.name}_tool_result`) {
+    return { id: use.id, name: use.name, resultType: result.type, input: use.input, resultContent: result.content, completed };
+  }
+  const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
+  // An item emitted before `anthropic_blocks` carried a server web_fetch as `fetch_result`.
+  if (item.fetch_result !== undefined) {
+    const input = { url: typeof action.url === "string" ? action.url : "" };
+    return { id, name: "web_fetch", resultType: "web_fetch_tool_result", input, resultContent: item.fetch_result, completed };
+  }
   const queries = Array.isArray(action.queries)
     ? action.queries.filter((q): q is string => typeof q === "string" && q.length > 0)
     : [];
@@ -233,7 +252,6 @@ export function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resu
   const input = sanitizeWebSearchInput(
     queries.length > 1 ? { queries } : { query: queries[0] ?? query },
   );
-  const completed = item.status !== "failed";
   let resultContent: unknown;
   if (completed) {
     const hits: Rec[] = [];
@@ -248,8 +266,7 @@ export function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resu
   } else {
     resultContent = { type: "web_search_tool_result_error", error_code: "unavailable" };
   }
-  const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
-  return { id, input, resultContent, completed };
+  return { id, name: "web_search", resultType: "web_search_tool_result", input, resultContent, completed };
 }
 
 /**
@@ -553,7 +570,13 @@ export function responsesSseToAnthropicSse(
         terminalDelivered = true;
       };
 
+      let progressMirrorId: string | undefined;
       const handleFrame = (eventName: string, data: Rec) => {
+        const frameItem = isRec(data.item) ? data.item : null;
+        if (progressMirrorId && (data.item_id === progressMirrorId || frameItem?.id === progressMirrorId)) {
+          if (eventName === "response.output_item.done") progressMirrorId = undefined;
+          return;
+        }
         switch (eventName) {
           case "response.created":
           case "response.in_progress": {
@@ -705,7 +728,7 @@ export function responsesSseToAnthropicSse(
               const toolIndex = blockIndex++;
               emit("content_block_start", {
                 type: "content_block_start", index: toolIndex,
-                content_block: { type: "server_tool_use", id: pair.id, name: "web_search" },
+                content_block: { type: "server_tool_use", id: pair.id, name: pair.name },
               });
               emit("content_block_delta", {
                 type: "content_block_delta", index: toolIndex,
@@ -715,10 +738,10 @@ export function responsesSseToAnthropicSse(
               const resultIndex = blockIndex++;
               emit("content_block_start", {
                 type: "content_block_start", index: resultIndex,
-                content_block: { type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent },
+                content_block: { type: pair.resultType, tool_use_id: pair.id, content: pair.resultContent },
               });
               emit("content_block_stop", { type: "content_block_stop", index: resultIndex });
-              if (pair.completed) webSearchRequests++;
+              if (pair.completed && pair.name === "web_search") webSearchRequests++;
               break;
             }
             // Close the matching open block (message/reasoning items close implicitly on
@@ -772,6 +795,15 @@ export function responsesSseToAnthropicSse(
                 ensureBlock("thinking");
               }
               if (open?.kind === "thinking") {
+                if (env?.upd && typeof env.txt === "string") {
+                  // This plaintext was deliberately surfaced as commentary, unlike hidden reasoning.
+                  progressMirrorId = env.upd;
+                  const bytes = Buffer.byteLength(env.txt);
+                  translatorBudget.chargeRetained(bytes, { kind: "reasoning" });
+                  translatorBudget.releaseRetained(open.thinkingBufBytes ?? 0, { kind: "reasoning" });
+                  open.thinkingBuf = env.txt;
+                  open.thinkingBufBytes = bytes;
+                }
                 if (env?.sig) open.reasoningSig = env.sig;
                 if (native) open.reasoningNative = typeof item.id === "string" && item.id.length > 0 ? { enc: native, id: item.id } : { enc: native };
                 closeOpenBlock();
@@ -976,7 +1008,8 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string, tr
   let sawToolUse = false;
   let webSearchRequests = 0;
 
-  for (const raw of output) {
+  for (const [index, raw] of output.entries()) {
+    if (index > 0 && isAnthropicProgressMirror(raw, anthropicProgressEnvelope(output[index - 1], translatorBudget))) continue;
     if (!isRec(raw)) continue;
     switch (raw.type) {
       case "message": {
@@ -1010,7 +1043,7 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string, tr
         const native = nativeEncryptedReasoning(encrypted);
         const tag = native && nativeReasoningTagFor?.(native);
         if (parts.length > 0 || env?.sig || tag) {
-          const text = parts.join("\n\n");
+          const text = env?.upd ? env.txt! : parts.join("\n\n");
           const nat = tag ? { enc: native, model, tag, ...(typeof raw.id === "string" && raw.id.length > 0 ? { id: raw.id } : {}) } : undefined;
           content.push({ type: "thinking", thinking: text, signature: env?.sig ?? encodeReasoningEnvelope({ txt: text, ...(nat ? { nat } : {}) }, translatorBudget) });
         }
@@ -1034,9 +1067,9 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string, tr
       case "web_search_call": {
         // Server-side search: emit the Anthropic pair. Does NOT set sawToolUse.
         const pair = webSearchPairFromItem(raw);
-        content.push({ type: "server_tool_use", id: pair.id, name: "web_search", input: pair.input });
-        content.push({ type: "web_search_tool_result", tool_use_id: pair.id, content: pair.resultContent });
-        if (pair.completed) webSearchRequests++;
+        content.push({ type: "server_tool_use", id: pair.id, name: pair.name, input: pair.input });
+        content.push({ type: pair.resultType, tool_use_id: pair.id, content: pair.resultContent });
+        if (pair.completed && pair.name === "web_search") webSearchRequests++;
         break;
       }
       default:

package/src/cli/account-api.ts

@@ -306,6 +306,7 @@ export interface ProviderQuotaWindowDto {
   label: string;
   percent: number;
   resetAt?: number;
+  modelId?: string;
 }
 
 export interface ProviderQuotaDto extends CodexQuotaDto {

package/src/cli/account-policy-dto.ts

@@ -8,6 +8,7 @@ export const threshold = z.number().int().min(0).max(100);
 const nullableThreshold = threshold.nullable();
 const row = z.object({
   id: accountId, alias: text.optional(), autoSwitchThresholdOverride: nullableThreshold.optional(),
+  useRemainingQuota: z.boolean().optional(),
   quota: z.object({ shortWindowSeconds: z.number().finite().optional(), shortResetAt: z.number().finite().optional(),
     weeklyResetAt: z.number().finite().optional() }).nullable().optional(),
   quotaAutoRefresh: z.object({ fiveHourAvailable: z.boolean(), weeklyAvailable: z.boolean(),
@@ -39,6 +40,11 @@ export const poolSchema = z.object({
 export const thresholdReceipt = z.object({ ok: z.literal(true), id: accountId,
   autoSwitchThresholdOverride: nullableThreshold, autoSwitchThreshold: threshold });
 export const creditReceipt = z.object({ ok: z.literal(true), id: accountId, creditsAfterLimit: z.boolean() });
+export const remainingQuotaReceipt = z.object({ ok: z.literal(true), id: accountId,
+  useRemainingQuota: z.boolean(), autoSwitchThreshold: threshold,
+  mainAccountHardLock: z.object({ enabled: z.boolean(), state: z.enum(["off", "unknown", "ready", "blocked"]),
+    thresholds: z.object({ short: threshold, long: threshold }) }).optional(),
+});
 export const creditAllReceipt = z.object({ ok: z.literal(true), all: z.boolean(),
   ids: z.array(accountId).refine(ids => new Set(ids).size === ids.length) });
 const window = z.enum(["five_hour", "seven_day", "seven_day_overage_included"]);

package/src/cli/account-policy.ts

@@ -5,14 +5,15 @@ import { resolveCodexAccountTargetFromRows } from "./account-target";
 import { runCatalogAction } from "./catalog-command-result";
 import { serializeManagementJson } from "./json-input";
 import { creditAllReceipt, creditReceipt, grantsSchema, parseDto, poolSchema, record,
-  rosterSchema, threshold, thresholdReceipt } from "./account-policy-dto";
+  rosterSchema, threshold, thresholdReceipt, remainingQuotaReceipt } from "./account-policy-dto";
 import { CliUsageError, RuntimeApiError, printData, runtimeBaseUrl, runtimeRequest, summaryLines,
   takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
 
-type Subcommand = "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants";
+type Subcommand = "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants" | "use-remaining";
 const USAGE = "Usage: ocx account pool <provider> [--enabled on|off] [--threshold 0-100] [--strategy NAME] [--sticky 1-100] [--quota-window NAME] [--json]\n"
   + "       ocx account auto-switch openai <status|on|off|inherit|threshold N> --account ID [--json]\n"
   + "       ocx account credits openai <ID on|off|--all on|off> [--json]\n"
+  + "       ocx account use-remaining openai ID <on|off|status> [--json]\n"
   + "       ocx account quota-activation openai ID --window <fiveHour|weekly> <on|off> [--json]\n"
   + "       ocx account anthropic-reset-grants [ID] [--provider anthropic|anthropic2] [--json]";
 const READ_ERRORS = { no_account: "No matching Anthropic OAuth account.", auth_failed: "Sign in to this Anthropic account again.",
@@ -53,6 +54,32 @@ function output(data: Record<string, unknown>, json: boolean, note?: string): nu
 }
 function requireEqual(actual: unknown, expected: unknown): void { if (actual !== expected) throw new Error("Unverified account policy result"); }
 
+async function useRemaining(args: string[], json: boolean, deps: RuntimeApiDeps): Promise<number> {
+  if (args.shift() !== "openai") usage();
+  const requested = selector(args.shift()), action = args.shift();
+  if (!["on", "off", "status"].includes(action ?? "")) usage();
+  done(args);
+  const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+  const { id } = await target(pinned, requested);
+  const path = "/api/codex-auth/accounts/use-remaining";
+  const result = parseDto(remainingQuotaReceipt, await request(
+    action === "status" ? path + "?id=" + encodeURIComponent(id) : path,
+    pinned, action === "status" ? undefined : { id, useRemainingQuota: action === "on" },
+  ));
+  requireEqual(result.id, id);
+  if (action !== "status") requireEqual(result.useRemainingQuota, action === "on");
+  if (result.useRemainingQuota) {
+    requireEqual(result.autoSwitchThreshold, 0);
+    if (id === MAIN_CODEX_ACCOUNT_ID) {
+      requireEqual(result.mainAccountHardLock?.thresholds.short, 100);
+      requireEqual(result.mainAccountHardLock?.thresholds.long, 100);
+    }
+  }
+  return output(result, json, result.useRemainingQuota
+    ? "Use remaining included quota: on. Paid-credit permission is unchanged."
+    : "Use remaining included quota: off. Configured usage thresholds apply.");
+}
+
 async function pool(args: string[], json: boolean, deps: RuntimeApiDeps): Promise<number> {
   const provider = selector(args.shift()).toLowerCase();
   if (!isValidProviderName(provider)) usage();
@@ -63,7 +90,8 @@ async function pool(args: string[], json: boolean, deps: RuntimeApiDeps): Promis
   if (limit !== undefined) patch.autoSwitchThreshold = integer(limit, 0);
   if (sticky !== undefined) patch.stickyLimit = integer(sticky, 1);
   if (strategy !== undefined) {
-    if (!["quota", "round-robin", "fill-first", ...(provider === "openai" ? ["reset-first"] : []),
+    // reset-first is a Codex and generic-pool strategy; the Anthropic pool does not run it.
+    if (!["quota", "round-robin", "fill-first", ...(isAnthropicInstanceId(provider) ? [] : ["reset-first"]),
       ...(provider === "kiro" ? ["least-loaded"] : [])].includes(strategy)) usage();
     patch.strategy = strategy;
   }
@@ -122,12 +150,12 @@ async function codex(sub: "auto-switch" | "credits" | "quota-activation", args:
       const override = selected?.autoSwitchThresholdOverride;
       if (override === undefined) throw new Error("Missing account threshold evidence");
       const active = record(await request("/api/codex-auth/active", pinned));
-      const effective = override ?? parseDto(threshold, active.autoSwitchThreshold);
+      const effective = selected?.useRemainingQuota ? 0 : override ?? parseDto(threshold, active.autoSwitchThreshold);
       return output({ ok: true, id, autoSwitchThresholdOverride: override, autoSwitchThreshold: effective }, json);
     }
     const result = parseDto(thresholdReceipt, await request("/api/codex-auth/auto-switch", pinned, { id, threshold: value }));
     requireEqual(result.id, id); requireEqual(result.autoSwitchThresholdOverride, value);
-    if (value !== null) requireEqual(result.autoSwitchThreshold, value);
+    if (value !== null && !rows.find(row => row.id === id)?.useRemainingQuota) requireEqual(result.autoSwitchThreshold, value);
     return output(result, json, "Account threshold saved.");
   }
   if (sub === "credits") {
@@ -157,6 +185,7 @@ export async function handleAccountPolicyCommand(sub: Subcommand, args: string[]
     const rest = [...args], json = takeFlag(rest, "--json");
     if (rest.includes("--json")) usage();
     if (sub === "pool") return pool(rest, json, deps);
+    if (sub === "use-remaining") return useRemaining(rest, json, deps);
     if (sub !== "anthropic-reset-grants") return codex(sub, rest, json, deps);
     const selectedProvider = option(rest, "--provider");
     const provider = selectedProvider ?? "anthropic";

package/src/cli/account-preservation.ts

@@ -0,0 +1,44 @@
+import { apiError, apiJson, proxyUnreachable, resolveBaseUrl, type AccountDeps } from "./account-api";
+
+/** This operation follows the selected runtime; never read a local account/config roster. */
+export async function cmdPreserveSignedIn(args: string[], deps: AccountDeps): Promise<number> {
+  const provider = args.shift();
+  let mode = "status";
+  let hasMode = false;
+  let json = false;
+  let applyToBound = false;
+  for (const arg of args) {
+    if (arg === "--json" && !json) json = true;
+    else if (arg === "--apply-to-bound" && !applyToBound) applyToBound = true;
+    else if (["on", "off", "status"].includes(arg) && !hasMode) { mode = arg; hasMode = true; }
+    else return usage();
+  }
+  if (provider !== "openai" || (applyToBound && mode !== "on")) return usage();
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  const result = await apiJson(deps, baseUrl, mode === "status" ? "GET" : "PUT", "/api/codex-auth/preserve-signed-in",
+    mode === "status" ? undefined : { enabled: mode === "on", applyToBound });
+  if (result.status === 0) return proxyUnreachable(result.transportError);
+  if (result.status !== 200) return apiError(result.json, "Signed-in quota policy unavailable", result.status);
+  if (typeof result.json.enabled !== "boolean" || !Array.isArray(result.json.affectedAccountIds)
+    || !result.json.affectedAccountIds.every(id => typeof id === "string")
+    || (result.json.nextAccountId !== null && typeof result.json.nextAccountId !== "string")) {
+    return apiError({}, "Invalid signed-in quota policy response", 502);
+  }
+  if (json) console.log(JSON.stringify(result.json, null, 2));
+  else {
+    console.log(`Preserve signed-in quota: ${result.json.enabled ? "on" : "off"}`);
+    console.log(`Affected pool entries: ${result.json.affectedAccountIds.join(", ")}`);
+    console.log(`Next unbound choice: ${result.json.nextAccountId ?? "none"}`);
+    console.log(`Bindings: ${result.json.bindings}; manual pin: ${result.json.pinnedAccountId ?? "none"}`);
+    if (result.json.priorityFailbackEnabled === true) console.log("Existing priority failback can move bound work when its quota and freshness conditions hold.");
+    console.log("Fallback can consume signed-in quota. Exact-account models override this preference.");
+    console.log("Use on --apply-to-bound to release affected bindings and pins for the next request.");
+  }
+  return 0;
+}
+
+function usage(): number {
+  console.error("Usage: ocx account preserve-signed-in openai [on|off|status] [--apply-to-bound] [--json]");
+  return 1;
+}

package/src/cli/account.ts

@@ -54,6 +54,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account auto-switch <anthropic|anthropic2> <on|off|status|inherit|threshold <0-100>> --account <id> [--json]
   ocx account alias <provider> <account-or-key-id|alias> <display-name|-> [--json]
+  ocx account preserve-signed-in openai [on|off|status] [--apply-to-bound] [--json]
   ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
   ocx account pause <provider> <account-id|alias|main> [--json]
   ocx account resume <provider> <account-id|alias|main> [--json]
@@ -69,6 +70,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account login <provider> [--id <account-id>] [--reauth] [--open-browser on|off] [--add-account on|off] [--code -] [--no-wait] [--json]
   ocx account pool <provider> [--enabled on|off] [--threshold N] [--strategy NAME] [--sticky N] [--quota-window W] [--json]
   ocx account credits openai <ID on|off|--all on|off> [--json]
+  ocx account use-remaining openai <ID|main> <on|off|status> [--json]
   ocx account quota-activation openai ID --window fiveHour|weekly <on|off> [--json]
   ocx account anthropic-reset-grants [ID] [--provider anthropic|anthropic2] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
@@ -459,11 +461,11 @@ async function cmdClear(rest: string[], deps: AccountDeps): Promise<number> {
 export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promise<number> {
   const [sub, ...rest] = args;
   try {
-    if (["pool", "credits", "quota-activation", "anthropic-reset-grants"].includes(sub ?? "")
+    if (["pool", "credits", "quota-activation", "anthropic-reset-grants", "use-remaining"].includes(sub ?? "")
       || (sub === "auto-switch" && rest[0]?.trim().toLowerCase() === "openai"
         && rest.some(arg => arg === "--account" || arg.startsWith("--account=")))) {
       const { handleAccountPolicyCommand } = await import("./account-policy");
-      return handleAccountPolicyCommand(sub as "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants", rest, deps);
+      return handleAccountPolicyCommand(sub as "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants" | "use-remaining", rest, deps);
     }
     if (sub === "list") return await cmdList(rest, deps);
     if (sub === "history") {
@@ -476,6 +478,10 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "refresh") return await cmdRefresh(rest, deps);
     if (sub === "auto-switch") return await cmdAutoSwitch(rest, deps);
     if (sub === "alias" || sub === "rename") return await cmdAlias(rest, deps);
+    if (sub === "preserve-signed-in") {
+      const { cmdPreserveSignedIn } = await import("./account-preservation");
+      return cmdPreserveSignedIn(rest, deps);
+    }
     if (sub === "priority") return await cmdPriority(rest, deps);
     // #2702: the server routes existed and only the CLI caller was missing, so these were
     // dashboard-only capabilities.