@bitkyc08/opencodex 2.84.0 → 2.87.0

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.
  *
@@ -11,7 +12,7 @@
  *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
  */
 import { createHash } from "node:crypto";
-import { httpStatusFromTerminalError } from "../lib/errors";
+import { httpStatusFromTerminalError, UNDECLARED_TOOL_CALL_ERROR_CODE } from "../lib/errors";
 import { isTransientUpstreamStatus } from "../lib/upstream-retry";
 import {
   isTranslatorBudgetExceededError,
@@ -81,12 +82,16 @@ export function anthropicErrorType(status: number): string {
  * (devlog/_plan/261009_claude_1m_default/010).
  */
 const CLAUDE_PROMPT_TOO_LONG_RE = /prompt is too long|input is too long for requested model/i;
-const STATED_CONTEXT_COUNTS_RE = /maximum context length is (\d+) tokens[\s\S]*?(?:resulted in|you requested) (\d+) tokens/i;
+const MAX_OVERFLOW_MESSAGE_CHARS = 64 * 1024;
+const STATED_CONTEXT_LIMIT_RE = /maximum context length is (\d+) tokens/i;
+const STATED_REQUEST_COUNT_RE = /(?:resulted in|you requested) (\d+) tokens/i;
 
 export function claudePromptTooLongMessage(message: string): string {
+  message = message.slice(0, MAX_OVERFLOW_MESSAGE_CHARS);
   if (CLAUDE_PROMPT_TOO_LONG_RE.test(message)) return message;
-  const counts = STATED_CONTEXT_COUNTS_RE.exec(message);
-  if (counts) return `prompt is too long: ${counts[2]} tokens > ${counts[1]} maximum`;
+  const limit = STATED_CONTEXT_LIMIT_RE.exec(message);
+  const requested = limit && STATED_REQUEST_COUNT_RE.exec(message.slice(limit.index + limit[0].length));
+  if (limit && requested) return `prompt is too long: ${requested[1]} tokens > ${limit[1]} maximum`;
   return `prompt is too long: ${message}`;
 }
 
@@ -218,10 +223,20 @@ 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 `fetch_result` is Anthropic's
+ * server-side web_fetch and maps to web_fetch + its web_fetch_tool_result, verbatim.
+ * Shared by the SSE and JSON translation paths.
  */
-export function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
+export function webSearchPairFromItem(item: Rec): {
+  id: string; name: "web_search" | "web_fetch"; resultType: string; input: Rec; resultContent: unknown; completed: boolean;
+} {
   const action = isRec(item.action) ? item.action : {};
+  const id = typeof item.id === "string" && item.id.length > 0 ? item.id : `srvtoolu_${uuid()}`;
+  const completed = item.status !== "failed";
+  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)
     : [];
@@ -229,7 +244,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[] = [];
@@ -244,8 +258,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 };
 }
 
 /**
@@ -549,7 +562,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": {
@@ -701,7 +720,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,
@@ -711,10 +730,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
@@ -768,6 +787,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();
@@ -804,11 +832,14 @@ export function responsesSseToAnthropicSse(
             // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic
             // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to
             // overloaded_error by design.
+            // The undeclared-tool refusal is deterministic and proxy-owned, not an upstream
+            // condition: keep its api_error type and code instead of a retryable overload.
+            const deterministic = code === UNDECLARED_TOOL_CALL_ERROR_CODE;
             fail(
               status,
               message,
-              true,
-              code === "context_length_exceeded" ? code : undefined,
+              !deterministic,
+              deterministic || code === "context_length_exceeded" ? code : undefined,
             );
             break;
           }
@@ -969,7 +1000,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": {
@@ -1003,7 +1035,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) });
         }
@@ -1027,9 +1059,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.

package/src/cli/advisor.ts

@@ -0,0 +1,165 @@
+import { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION, ADVISOR_CONTEXT_SHARING_DISCLOSURE } from "../advisor/disclosure";
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx advisor status [--json]
+  ocx advisor activity [--json]
+  ocx advisor on [--ack-context-sharing] [--json]
+  ocx advisor off [--json]
+  ocx advisor consent [--revoke] [--json]
+  ocx advisor set [--model <model>] [--effort <effort>] [--policy <manual|preflight|adaptive>] [--max-consultations <1-3>] [--timeout-ms <ms>] [--json]`;
+
+const VALUED_FLAGS = new Set(["--model", "--effort", "--policy", "--timeout-ms", "--max-consultations"]);
+
+interface SetOptions {
+  model?: string;
+  effort?: string;
+  policy?: string;
+  timeoutMs?: string;
+  maxConsultations?: string;
+}
+
+function parseSetArgs(args: string[]): SetOptions {
+  const options: SetOptions = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (!VALUED_FLAGS.has(arg)) throw new CliUsageError(`unknown advisor set option ${arg}`, USAGE);
+    const value = args[++index];
+    if (value === undefined || value.startsWith("--")) throw new CliUsageError(`${arg} requires a value`, USAGE);
+    // An explicitly supplied empty value is meaningful for --model alone: the settings route
+    // treats "" as the supported "clear the model" state. Every other valued flag still needs one.
+    if (value === "" && arg !== "--model") throw new CliUsageError(`${arg} requires a value`, USAGE);
+    if (arg === "--model") options.model = value;
+    else if (arg === "--effort") options.effort = value;
+    else if (arg === "--policy") options.policy = value;
+    else if (arg === "--max-consultations") options.maxConsultations = value;
+    else options.timeoutMs = value;
+  }
+  if (Object.keys(options).length === 0) {
+    throw new CliUsageError("advisor set requires a model, effort, policy, task limit, or timeout option", USAGE);
+  }
+  return options;
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/advisor/settings", {}, deps), wantsJson);
+}
+
+function printDisclosure(): void {
+  console.error(ADVISOR_CONTEXT_SHARING_DISCLOSURE);
+}
+
+async function readConsent(deps: RuntimeApiDeps): Promise<unknown> {
+  const current = await runtimeRequest("/api/advisor/settings", {}, deps) as {
+    settings?: { contextSharingConsent?: unknown };
+  };
+  return current.settings?.contextSharingConsent;
+}
+
+async function setEnabled(enabled: boolean, argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const acknowledge = takeFlag(args, "--ack-context-sharing");
+  rejectArgs(args, USAGE);
+  if (!enabled) {
+    if (acknowledge) {
+      throw new CliUsageError(
+        "--ack-context-sharing has no effect with `ocx advisor off`; it never records consent.",
+        USAGE,
+      );
+    }
+    printData(await runtimeRequest("/api/advisor/settings", {
+      method: "PUT",
+      body: JSON.stringify({ enabled: false }),
+    }, deps), wantsJson, ["Advisor disabled."]);
+    return;
+  }
+  const consent = await readConsent(deps);
+  if (acknowledge) {
+    printDisclosure();
+    printData(await runtimeRequest("/api/advisor/settings", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: true,
+        contextSharingConsent: ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+      }),
+    }, deps), wantsJson, ["Advisor enabled with context-sharing consent v1."]);
+    return;
+  }
+  if (consent !== ADVISOR_CONTEXT_SHARING_CONSENT_VERSION) {
+    printDisclosure();
+    throw new CliUsageError(
+      "Advisor context-sharing consent is required before consultations can send task content. "
+      + "Re-run `ocx advisor on --ack-context-sharing` after reading the disclosure, or run `ocx advisor consent`.",
+      USAGE,
+    );
+  }
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify({ enabled: true }),
+  }, deps), wantsJson, ["Advisor enabled."]);
+}
+
+async function consent(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const revoke = takeFlag(args, "--revoke");
+  rejectArgs(args, USAGE);
+  if (!revoke) printDisclosure();
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify({
+      contextSharingConsent: revoke ? null : ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+    }),
+  }, deps), wantsJson, [revoke
+    ? "Advisor context-sharing consent removed. Consultations will not send task content."
+    : "Advisor context-sharing consent v1 recorded.",
+  ]);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const options = parseSetArgs(args);
+  const patch: Record<string, unknown> = {};
+  if (options.model !== undefined) patch.model = options.model;
+  if (options.effort !== undefined) patch.effort = options.effort;
+  if (options.policy !== undefined) patch.policy = options.policy;
+  if (options.maxConsultations !== undefined) {
+    const limit = Number(options.maxConsultations);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 3) throw new CliUsageError("--max-consultations must be an integer between 1 and 3", USAGE);
+    patch.maxConsultationsPerTask = limit;
+  }
+  if (options.timeoutMs !== undefined) {
+    const parsed = Number(options.timeoutMs);
+    if (!Number.isFinite(parsed)) throw new CliUsageError("--timeout-ms must be a number", USAGE);
+    patch.timeoutMs = parsed;
+  }
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify(patch),
+  }, deps), wantsJson, ["Advisor settings saved."]);
+}
+
+export async function handleAdvisorCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "activity") {
+      const args = [...rest];
+      const wantsJson = takeFlag(args, "--json");
+      rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/advisor/activity", {}, deps), wantsJson);
+    }
+    else if (sub === "on") await setEnabled(true, rest, deps);
+    else if (sub === "off") await setEnabled(false, rest, deps);
+    else if (sub === "consent") await consent(rest, deps);
+    else if (sub === "set") await set(rest, deps);
+    else throw new CliUsageError(`unknown advisor command ${sub}`, USAGE);
+  });
+}
+
+export const ADVISOR_USAGE = USAGE;

package/src/cli/auxiliary-listener-preflight.ts

@@ -0,0 +1,37 @@
+import type { OcxConfig } from "../types";
+import { AuxiliaryListenerBindError } from "../server/ports";
+import { createServer } from "node:net";
+
+/**
+ * Reject impossible auxiliary binds before startup creates private state. On Windows
+ * that publication requires several synchronous ACL subprocesses. This is only an
+ * early rejection: startServer still owns the actual bind and transactional rollback
+ * if another process takes the port between this probe and startup.
+ */
+export async function assertAuxiliaryListenerPortsAvailable(config: OcxConfig): Promise<void> {
+  const loopback = config.unauthenticatedLoopbackListener;
+  const management = config.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
+  const targets = [
+    { listener: "unauthenticatedLoopbackListener", port: loopback?.enabled ? loopback.port : undefined },
+    { listener: "hub.managementIngress", port: management?.enabled ? management.port : undefined },
+  ] as const;
+  // Each probe releases its socket, so two listeners configured for one port would both
+  // pass and startup would still fail on the second bind. Reject the collision directly.
+  if (targets[0].port !== undefined && targets[0].port === targets[1].port) {
+    throw new AuxiliaryListenerBindError(
+      "hub.managementIngress", targets[1].port, "127.0.0.1",
+      new Error("port is also configured for unauthenticatedLoopbackListener"),
+    );
+  }
+  for (const { listener, port } of targets) {
+    // The port-less companion shares the public bind; it has no independent target.
+    if (port === undefined) continue;
+    await new Promise<void>((resolve, reject) => {
+      const probe = createServer(socket => socket.destroy());
+      const fail = (cause: unknown) => reject(new AuxiliaryListenerBindError(listener, port, "127.0.0.1", cause));
+      probe.once("error", fail);
+      probe.once("listening", () => probe.close(error => error ? fail(error) : resolve()));
+      try { probe.listen({ port, host: "127.0.0.1" }); } catch (error) { fail(error); }
+    });
+  }
+}

package/src/cli/capabilities-accounts.ts

@@ -2,6 +2,14 @@ import type { Capability } from "./capability-types";
 
 /** Account pool operations and physical native-login profiles have separate owners. */
 export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["account", "preserve-signed-in"], summary: "Prefer other Codex identities and reserve the native sign-in as fallback.",
+    usage: "ocx account preserve-signed-in openai [on|off|status] [--apply-to-bound] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/preserve-signed-in" }, { method: "PUT", path: "/api/codex-auth/preserve-signed-in" }],
+    flags: [{ name: "--apply-to-bound", value: "boolean", summary: "With on, release protected bindings and pins for the next request." }, { name: "--json", value: "boolean", summary: "Emit affected entries, next unbound choice and pin/binding semantics." }],
+    mutates: true, json: "payload",
+    details: ["Default/status reads. Custom priorities are preserved. Bound threads and manual pins remain unless explicitly released. Exact-account models override the preference. Fallback can spend signed-in quota; linked pause excludes it instead."],
+  },
   {
     command: ["logout"],
     summary: "Remove the active stored OAuth credential for a provider locally.",
@@ -157,11 +165,22 @@ export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
     usage: "ocx account pool <provider> [--enabled <on|off>] [--threshold <0-100>] [--strategy <name>] [--sticky <1-100>] [--quota-window <five-hour|weekly|max-utilization>] [--json]",
     summary: "Read or edit the selected runtime's supported pool policy fields.",
     routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
-    flags: [{"name":"--enabled","value":"string","summary":"Stored pool preference; unsupported for Codex. Not equivalent to threshold0."},{"name":"--threshold","value":"number","summary":"Auto-switch threshold0–100."},{"name":"--strategy","value":"string","summary":"Use a strategy supported by this provider kind; reset-first is Codex, least-loaded is Kiro."},{"name":"--sticky","value":"number","summary":"Sticky limit1–100."},{"name":"--quota-window","value":"string","summary":"Anthropic only: five-hour, weekly or max-utilization."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    flags: [{"name":"--enabled","value":"string","summary":"Stored pool preference; unsupported for Codex. Not equivalent to threshold0."},{"name":"--threshold","value":"number","summary":"Auto-switch threshold0–100."},{"name":"--strategy","value":"string","summary":"Use a strategy supported by this provider kind; reset-first is Codex or generic OAuth, least-loaded is Kiro."},{"name":"--sticky","value":"number","summary":"Sticky limit1–100."},{"name":"--quota-window","value":"string","summary":"Anthropic only: five-hour, weekly or max-utilization."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
     mutates: true,
     json: "envelope",
     details: ["Reads the target supported-field list before a narrow PUT. Null/unsupported, stored/effective and generic inert policy stay distinct; disabling does not promise that reactive429 rotation stops.","No local classification/defaults are round-tripped into the live target; supported-field reads are not CAS."],
   },
+  {
+    command: ["account", "use-remaining"],
+    usage: "ocx account use-remaining openai <id|alias|main> <on|off|status> [--json]",
+    summary: "Choose whether one Codex account keeps using its remaining included quota.",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" },
+      { method: "GET", path: "/api/codex-auth/accounts/use-remaining" }, { method: "PUT", path: "/api/codex-auth/accounts/use-remaining" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the validated account policy." }],
+    mutates: true, json: "envelope",
+    details: ["On disables proactive usage switching for the selected account and raises main-account protection to 100%. Off restores the configured thresholds.",
+      "This is a persistent preference, not account selection. Pause, reauthentication, cooldown, entitlement and paid-credit policy still apply."],
+  },
   {
     command: ["account","credits"],
     usage: "ocx account credits openai <id|alias|main> <on|off> [--json]; ocx account credits openai --all <on|off> [--json]",