@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/account-main.ts

@@ -0,0 +1,317 @@
+import { isAbsolute } from "node:path";
+import { codexExecInvocation } from "../codex/exec-invocation";
+import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
+import type { ResolveDeps, SpawnInvocation } from "../lib/win-exec";
+import {
+  apiError,
+  apiJson,
+  proxyUnreachable,
+  resolveBaseUrl,
+  type AccountDeps,
+  type NativeMainLoginChild,
+  type StageLeaseClock,
+} from "./account-api";
+
+const USAGE = `Usage:
+  ocx account main doctor [--json]
+  ocx account main list [--json]
+  ocx account main register <label> [--json]
+  ocx account main add <label>
+  ocx account main switch <profile-id-or-label> --yes [--json]
+  ocx account main recover [--rollback --yes] [--json]
+
+Native main login profiles change the physical Codex App/CLI login in the effective CODEX_HOME.
+They are independent from the OpenCodex Pool selected by 'ocx account use openai'.`;
+
+const STAGE_LEASE_SAFETY_MARGIN_MS = 30_000;
+
+const systemStageLeaseClock: StageLeaseClock = {
+  now: Date.now,
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: timer => clearTimeout(timer),
+};
+
+interface PublicProfile {
+  id: string;
+  label: string;
+  identityHint: string;
+  state: "active" | "inactive";
+}
+
+export type NativeMainCodexLoginInvocationDeps =
+  & ResolveDeps
+  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">;
+
+function flag(args: string[], name: string): boolean {
+  const index = args.indexOf(name);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+function reject(args: string[]): number {
+  if (args.length > 0) console.error(`Unexpected argument(s): ${args.join(", ")}`);
+  console.error(USAGE);
+  return 1;
+}
+
+function effectiveCodexHome(result: Record<string, unknown>): string {
+  return typeof result.effectiveCodexHome === "string" && result.effectiveCodexHome.length > 0
+    ? result.effectiveCodexHome
+    : "the effective CODEX_HOME";
+}
+
+function printProfiles(profiles: PublicProfile[]): void {
+  if (profiles.length === 0) { console.log("No native main login profiles registered."); return; }
+  const rows = profiles.map(profile => [profile.state === "active" ? "*" : " ", profile.label, profile.id, profile.identityHint]);
+  const header = ["", "LABEL", "PROFILE ID", "IDENTITY"];
+  const widths = header.map((value, index) => Math.max(value.length, ...rows.map(row => row[index]!.length)));
+  const line = (columns: string[]) => columns.map((value, index) => value.padEnd(widths[index]!)).join("  ").trimEnd();
+  console.log([line(header), ...rows.map(line)].join("\n"));
+}
+
+export function nativeMainCodexLoginInvocation(
+  platform: NodeJS.Platform = process.platform,
+  deps: NativeMainCodexLoginInvocationDeps = {},
+): SpawnInvocation {
+  const command = resolveAndPersistCodexRuntime({
+    env: deps.env ?? process.env,
+    platform,
+    existsSync: deps.existsSync,
+    execFileSync: deps.execFileSync,
+    configDir: deps.configDir,
+    readFileSync: deps.readFileSync,
+    discoverAlternatives: false,
+  }).runtime.command || "codex";
+  return codexExecInvocation(command, ["login"], platform, deps);
+}
+
+function spawnOfficialCodexLogin(codexHome: string): NativeMainLoginChild {
+  const invocation = nativeMainCodexLoginInvocation();
+  const child = Bun.spawn([invocation.file, ...invocation.args], {
+    env: { ...process.env, CODEX_HOME: codexHome },
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    ...(invocation.options.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+  });
+  return child;
+}
+
+function abortableDelay(ms: number, signal: AbortSignal, clock: StageLeaseClock): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise(resolve => {
+    const timer = clock.setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+    function done(): void {
+      clock.clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+  });
+}
+
+async function maintainStageLease(
+  deps: AccountDeps,
+  baseUrl: string,
+  stageId: string,
+  writerToken: string,
+  initialLeaseExpiresAt: number,
+  heartbeatIntervalMs: number,
+  child: NativeMainLoginChild,
+  signal: AbortSignal,
+  clock: StageLeaseClock,
+): Promise<{ lost: boolean }> {
+  let leaseExpiresAt = initialLeaseExpiresAt;
+  for (;;) {
+    if (signal.aborted) return { lost: false };
+    const deadlineAt = leaseExpiresAt - STAGE_LEASE_SAFETY_MARGIN_MS;
+    if (clock.now() >= deadlineAt) {
+      try { child.kill(); } catch { /* child exit below is authoritative */ }
+      return { lost: true };
+    }
+
+    const heartbeatAbort = new AbortController();
+    const deadlineReached = Symbol("heartbeat-deadline");
+    const parentCancelled = Symbol("heartbeat-parent-cancelled");
+    let resolveInterruption!: (result: typeof deadlineReached | typeof parentCancelled) => void;
+    const interruption = new Promise<typeof deadlineReached | typeof parentCancelled>(resolve => {
+      resolveInterruption = resolve;
+    });
+    const cancelHeartbeat = () => {
+      heartbeatAbort.abort();
+      resolveInterruption(parentCancelled);
+    };
+    signal.addEventListener("abort", cancelHeartbeat, { once: true });
+    const deadlineTimer = clock.setTimeout(() => {
+      heartbeatAbort.abort();
+      resolveInterruption(deadlineReached);
+    }, Math.max(0, deadlineAt - clock.now()));
+    const heartbeatRequest = apiJson(
+      deps,
+      baseUrl,
+      "POST",
+      "/api/native-main-profiles/stage/heartbeat",
+      { stageId, writerToken },
+      { signal: heartbeatAbort.signal },
+    );
+    const heartbeat = await Promise.race([heartbeatRequest, interruption]);
+    clock.clearTimeout(deadlineTimer);
+    signal.removeEventListener("abort", cancelHeartbeat);
+    if (signal.aborted) return { lost: false };
+    if (heartbeat === parentCancelled) return { lost: false };
+    if (heartbeat === deadlineReached) {
+      try { child.kill(); } catch { /* child exit below is authoritative */ }
+      return { lost: true };
+    }
+    if (heartbeat.status === 200 && typeof heartbeat.json.leaseExpiresAt === "number") {
+      leaseExpiresAt = heartbeat.json.leaseExpiresAt;
+      await abortableDelay(Math.min(heartbeatIntervalMs, Math.max(0, leaseExpiresAt - STAGE_LEASE_SAFETY_MARGIN_MS - clock.now())), signal, clock);
+      continue;
+    }
+    if (heartbeat.status === 0 && clock.now() < leaseExpiresAt - STAGE_LEASE_SAFETY_MARGIN_MS) {
+      await abortableDelay(Math.min(5_000, heartbeatIntervalMs, leaseExpiresAt - STAGE_LEASE_SAFETY_MARGIN_MS - clock.now()), signal, clock);
+      continue;
+    }
+    try { child.kill(); } catch { /* child exit below is authoritative */ }
+    return { lost: true };
+  }
+}
+
+export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): Promise<number> {
+  const sub = args.shift();
+  const wantsJson = flag(args, "--json");
+  const confirmed = flag(args, "--yes");
+  const rollback = flag(args, "--rollback");
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  if (sub === "doctor" || sub === "list") {
+    if (args.length > 0 || confirmed || rollback) return reject(args);
+    const path = sub === "doctor" ? "/api/native-main-profiles/doctor" : "/api/native-main-profiles";
+    const result = await apiJson(deps, baseUrl, "GET", path);
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, `failed to ${sub} native profiles`, result.status);
+    if (wantsJson || sub === "doctor") console.log(JSON.stringify(result.json, null, 2));
+    else printProfiles(Array.isArray(result.json.profiles) ? result.json.profiles as PublicProfile[] : []);
+    return 0;
+  }
+
+  if (sub === "register") {
+    const label = args.shift();
+    if (!label || args.length > 0 || confirmed || rollback) return reject(args);
+    const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/register", { label });
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to register the current native login", result.status);
+    if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
+    else console.log(`Registered '${label}' for ${effectiveCodexHome(result.json)}.`);
+    return 0;
+  }
+
+  if (sub === "add") {
+    const label = args.shift();
+    if (!label || args.length > 0 || wantsJson || confirmed || rollback) return reject(args);
+    const stage = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/stage", {});
+    if (stage.status === 0) return proxyUnreachable(stage.transportError);
+    if (stage.status !== 200) return apiError(stage.json, "failed to prepare native login staging", stage.status);
+    const stageId = typeof stage.json.stageId === "string" ? stage.json.stageId : "";
+    const writerToken = typeof stage.json.writerToken === "string" ? stage.json.writerToken : "";
+    const stagingHome = typeof stage.json.stagingCodexHome === "string" ? stage.json.stagingCodexHome : "";
+    const leaseExpiresAt = typeof stage.json.leaseExpiresAt === "number" ? stage.json.leaseExpiresAt : 0;
+    const heartbeatIntervalMs = typeof stage.json.heartbeatIntervalMs === "number"
+      ? Math.min(5 * 60_000, Math.max(deps.stageHeartbeatIntervalMinMs ?? 5_000, stage.json.heartbeatIntervalMs))
+      : 60_000;
+    const stageLeaseClock = deps.stageLeaseClock ?? systemStageLeaseClock;
+    const stagedEffectiveHome = effectiveCodexHome(stage.json);
+    let exitCode = 1;
+    let finished = false;
+    let leaseLost = false;
+    try {
+      if (!stageId || !writerToken || !isAbsolute(stagingHome) || leaseExpiresAt <= stageLeaseClock.now()) {
+        throw new Error("The proxy returned an invalid staging session.");
+      }
+      console.error(`Effective CODEX_HOME: ${stagedEffectiveHome}`);
+      console.error(`Starting official Codex login in restricted staging home: ${stagingHome}`);
+      const child = deps.spawnCodexLoginImpl
+        ? deps.spawnCodexLoginImpl(stagingHome)
+        : deps.runCodexLoginImpl
+          ? { exited: deps.runCodexLoginImpl(stagingHome), kill: () => {} }
+          : spawnOfficialCodexLogin(stagingHome);
+      const heartbeatAbort = new AbortController();
+      const heartbeat = maintainStageLease(
+        deps,
+        baseUrl,
+        stageId,
+        writerToken,
+        leaseExpiresAt,
+        heartbeatIntervalMs,
+        child,
+        heartbeatAbort.signal,
+        stageLeaseClock,
+      );
+      try {
+        exitCode = await child.exited;
+      } finally {
+        heartbeatAbort.abort();
+        leaseLost = (await heartbeat).lost;
+      }
+      if (leaseLost) throw new Error("The native-login staging lease was lost before login completed.");
+      if (exitCode !== 0) throw new Error("Official Codex login did not complete successfully.");
+      const finish = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/stage/finish", { stageId, writerToken, label });
+      if (finish.status === 0) return proxyUnreachable(finish.transportError);
+      if (finish.status !== 200) return apiError(finish.json, "failed to encrypt the staged native login", finish.status);
+      finished = true;
+      console.log(`Added encrypted native profile '${label}' for ${effectiveCodexHome(finish.json)}.`);
+      return 0;
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : "Official Codex login failed."}`);
+      return exitCode === 0 ? 1 : exitCode;
+    } finally {
+      if (stageId && !finished) {
+        const cleanup = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/stage/cancel", { stageId, writerToken });
+        if (cleanup.status !== 200 || cleanup.json.plaintextMayRemain === true) {
+          console.error("Error: the proxy could not confirm native-login staging cleanup; run account main doctor.");
+        }
+      }
+    }
+  }
+
+  if (sub === "switch") {
+    const target = args.shift();
+    if (!target || args.length > 0 || rollback || !confirmed) {
+      if (!confirmed) console.error("Close Codex App/CLI, then pass --yes to confirm it is stopped.");
+      return reject(args);
+    }
+    const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/switch", { target, confirmedStopped: true });
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to switch the native login", result.status);
+    if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
+    else {
+      const profile = result.json.activeProfile as PublicProfile | undefined;
+      console.log(`Native Codex login for ${effectiveCodexHome(result.json)} is now '${profile?.label ?? target}'. Restart Codex App/CLI before continuing.`);
+    }
+    return 0;
+  }
+
+  if (sub === "recover") {
+    if (args.length > 0 || (rollback && !confirmed)) {
+      if (rollback && !confirmed) console.error("--rollback changes the native login and requires --yes.");
+      return reject(args);
+    }
+    const result = await apiJson(deps, baseUrl, "POST", "/api/native-main-profiles/recover", rollback
+      ? { rollback: true, confirmedStopped: true }
+      : { rollback: false });
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, "failed to recover the native-profile transaction", result.status);
+    if (wantsJson) console.log(JSON.stringify(result.json, null, 2));
+    else {
+      const home = effectiveCodexHome(result.json);
+      console.log(result.json.recovered === true
+        ? `Recovery completed for ${home}: ${String(result.json.action ?? "converged")}.`
+        : `No recovery journal is pending for ${home}.`);
+    }
+    return 0;
+  }
+
+  return reject(args);
+}

package/src/cli/account.ts

@@ -2,7 +2,20 @@
 import { loadConfig } from "../config";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { OcxConfig } from "../types";
-import { cmdAddKey, cmdAlias, cmdAutoSwitch, cmdClearCooldown, cmdRefresh, cmdRemove } from "./account-extended";
+import {
+  cmdAddKey,
+  cmdAlias,
+  cmdAutoSwitch,
+  cmdClearCooldown,
+  cmdImport,
+  cmdPause,
+  cmdPauseExhausted,
+  cmdPriority,
+  cmdRefresh,
+  cmdRemove,
+  cmdSticky,
+  cmdStrategy,
+} from "./account-extended";
 import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
   from "./account-api";
 
@@ -16,19 +29,27 @@ const MAIN_CODEX_ID = "__main__";
 const REPLACEMENT_STYLE_OAUTH = new Set(["kiro"]);
 
 const ACCOUNT_USAGE = `Usage:
-  ocx account list [provider] [--json] [--all]
+  ocx account list [provider] [--json] [--all] [--quota [--refresh]]
   ocx account current <provider> [--json]
   ocx account use <provider> <account-or-key-id|main> [--json]
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account alias <provider> <account-or-key-id> <display-name|-> [--json]
+  ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
+  ocx account pause <provider> <account-id|main> [--json]
+  ocx account resume <provider> <account-id|main> [--json]
+  ocx account pause-exhausted <provider> [--json]
+  ocx account strategy <provider> [<quota|round-robin|fill-first>] [--json]
+  ocx account sticky <provider> [<1-100>] [--json]
   ocx account remove <provider> <account-or-key-id|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
+  ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]
   ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
   ocx account reset-credits <account-id|main> [--consume --yes] [--json]
+  ocx account main <doctor|list|register|add|switch|recover> ...
 
 List and switch provider accounts and API-key pools (masked output only).
 'main' selects the Codex App login for the openai account pool.`;
@@ -61,16 +82,53 @@ function displayId(id: string): string {
 
 function statusText(row: AccountRow): string {
   const parts: string[] = [];
+  // `paused` leads, and does NOT replace `selected`. A paused-but-selected account is the
+  // state an operator most needs named -- requests route to it while the pool believes it is
+  // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
+  if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth) parts.push("needs-reauth");
   return parts.join(" ");
 }
 
-export function formatAccountTable(rows: AccountRow[]): string {
-  const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "STATUS"];
+/** Signed so the sort direction reads off the column; "-" where ordering does not apply. */
+function priorityText(row: AccountRow): string {
+  if (row.priority === undefined) return "-";
+  return row.priority > 0 ? `+${row.priority}` : String(row.priority);
+}
+
+/**
+ * Compact per-account quota for the opt-in QUOTA column: the two windows an operator actually
+ * decides on before a long session. The full breakdown stays in `--json`.
+ */
+function quotaText(row: AccountRow): string {
+  if ((row as { quotaUnavailable?: boolean }).quotaUnavailable) return "unavailable";
+  const quota = row.quota;
+  if (!quota) return "-";
+  const parts: string[] = [];
+  // Two spellings reach this DTO: the per-account provider probe reports `fiveHourPercent`,
+  // while the Codex pool reports the same idea as `shortPercent`.
+  const short = quota.fiveHourPercent ?? quota.shortPercent;
+  if (typeof short === "number") parts.push(`5h ${short}%`);
+  if (typeof quota.weeklyPercent === "number") parts.push(`wk ${quota.weeklyPercent}%`);
+  return parts.length > 0 ? parts.join(" ") : "-";
+}
+
+export function formatAccountTable(rows: AccountRow[], withQuota = false): string {
+  const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "PRIORITY", "STATUS"];
+  if (withQuota) header.push("QUOTA");
   const data = rows.map(r => {
     const keyLabel = r.masked && r.label !== r.masked ? `${r.masked} (${r.label})` : r.masked;
-    return [r.provider, r.type, displayId(r.id), r.type === "api-key" ? keyLabel ?? "-" : r.label ?? "-", statusText(r)];
+    const cols = [
+      r.provider,
+      r.type,
+      displayId(r.id),
+      r.type === "api-key" ? keyLabel ?? "-" : r.label ?? "-",
+      priorityText(r),
+      statusText(r),
+    ];
+    if (withQuota) cols.push(quotaText(r));
+    return cols;
   });
   const widths = header.map((h, i) => Math.max(h.length, ...data.map(d => d[i]!.length)));
   const line = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i]!)).join("  ").trimEnd();
@@ -80,6 +138,10 @@ export function formatAccountTable(rows: AccountRow[]): string {
 async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = consumeFlag(rest, "--json");
   const showAll = consumeFlag(rest, "--all");
+  // Opt-in: the server probes the upstream once per stored credential, so the default listing
+  // stays a cheap local read (#2566). --refresh bypasses the server-side TTL.
+  const wantsQuota = consumeFlag(rest, "--quota");
+  const refreshQuota = consumeFlag(rest, "--refresh");
   const name = rest.shift();
   const leftover = leftoverArgsError(rest);
   if (leftover) {
@@ -110,8 +172,8 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     };
     push("openai", "codex");
     const providersRes = await apiJson(deps, baseUrl, "GET", "/api/oauth/providers");
-    if (providersRes.status === 0) return proxyUnreachable();
-    if (providersRes.status !== 200) return apiError(providersRes.json, "failed to list OAuth providers");
+    if (providersRes.status === 0) return proxyUnreachable(providersRes.transportError);
+    if (providersRes.status !== 200) return apiError(providersRes.json, "failed to list OAuth providers", providersRes.status);
     if (Array.isArray(providersRes.json.providers)) {
       for (const p of providersRes.json.providers) {
         if (typeof p === "string") push(p, "live-oauth-list");
@@ -123,10 +185,11 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
   const rows: AccountRow[] = [];
   const notes: string[] = [];
   for (const t of targets) {
-    const r = await fetchRows(deps, baseUrl, t.name, t.type);
-    if (r.networkDown) return proxyUnreachable();
+    const r = await fetchRows(deps, baseUrl, t.name, t.type, wantsQuota ? { refresh: refreshQuota } : undefined);
+    if (r.networkDown) return proxyUnreachable(r.transportError);
     if (r.errorJson) {
-      if (name) return apiError(r.errorJson, `failed to list ${t.name}`);
+      if (name) return apiError(r.errorJson, `failed to list ${t.name}`, r.status);
+
       const errorText = typeof r.errorJson.error === "string" ? r.errorJson.error : "";
       const skipUnknownKey = t.type === "api-key"
         && r.status === 404
@@ -136,7 +199,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
         && r.status === 400
         && errorText.includes("unknown oauth provider");
       if (skipUnknownKey || skipConfigOAuth) continue;
-      return apiError(r.errorJson, `failed to list ${t.name}`);
+      return apiError(r.errorJson, `failed to list ${t.name}`, r.status);
     }
     if (r.rows.length === 0) {
       if (showAll) notes.push(`${t.name}: no stored accounts or keys`);
@@ -158,7 +221,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     console.log(JSON.stringify({ accounts: rows, notes }, null, 2));
     return 0;
   }
-  if (rows.length > 0) console.log(formatAccountTable(rows));
+  if (rows.length > 0) console.log(formatAccountTable(rows, wantsQuota));
   for (const n of notes) console.log(n);
   if (rows.length === 0 && notes.length === 0) console.log("No stored accounts or keys.");
   return 0;
@@ -182,8 +245,8 @@ async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   const r = await fetchRows(deps, baseUrl, name, c.type);
-  if (r.networkDown) return proxyUnreachable();
-  if (r.errorJson) return apiError(r.errorJson, `failed to read ${name}`);
+  if (r.networkDown) return proxyUnreachable(r.transportError);
+  if (r.errorJson) return apiError(r.errorJson, `failed to read ${name}`, r.status);
 
   const activeRow = r.rows.find(row => row.active) ?? null;
   if (wantsJson) {
@@ -237,15 +300,17 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
     activeId = id;
     res = await apiJson(deps, baseUrl, "PUT", "/api/providers/keys/active", { name, id });
   }
-  if (res.status === 0) return proxyUnreachable();
-  if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`);
+  if (res.status === 0) return proxyUnreachable(res.transportError);
+  if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`, res.status);
 
   if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, type: c.type, activeId }, null, 2));
   else console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
   if (c.type === "codex") {
-    console.error("Applies to the next request after clearing existing pool affinity; in-flight requests keep their captured account.");
-    console.error("Note: pool strategy, quota/cooldown/reauthentication state, and failure recovery may later select another eligible account.");
-    console.error("Conversation context is replayed after account changes, but the provider-side prompt cache may be cold.");
+    console.error("Takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.");
+    const active = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
+    if (active.status === 200 && typeof active.json.autoSwitchThreshold === "number" && active.json.autoSwitchThreshold > 0) {
+      console.error(`Note: auto-switch (threshold ${active.json.autoSwitchThreshold}%) may override this pin.`);
+    }
   }
   return 0;
 }
@@ -259,9 +324,22 @@ 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 === "priority") return await cmdPriority(rest, deps);
+    // #2702: the server routes existed and only the CLI caller was missing, so these were
+    // dashboard-only capabilities.
+    if (sub === "pause") return await cmdPause(rest, deps, true);
+    if (sub === "resume") return await cmdPause(rest, deps, false);
+    if (sub === "pause-exhausted") return await cmdPauseExhausted(rest, deps);
+    if (sub === "strategy") return await cmdStrategy(rest, deps);
+    if (sub === "sticky") return await cmdSticky(rest, deps);
     if (sub === "remove") return await cmdRemove(rest, deps);
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);
+    if (sub === "import") return await cmdImport(rest, deps);
+    if (sub === "main") {
+      const { cmdNativeMainAccount } = await import("./account-main");
+      return await cmdNativeMainAccount(rest, deps);
+    }
     if (["login", "reauth", "code", "cancel", "reset-credits"].includes(sub ?? "")) {
       const { handleAccountAuthCommand } = await import("./account-auth");
       return await handleAccountAuthCommand(sub!, rest, deps) ?? 1;

package/src/cli/agent.ts

@@ -13,6 +13,13 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 
+interface WebSearchModelOption {
+  value: string;
+  model: string;
+  backend: "openai" | "anthropic";
+  authSlot?: boolean;
+}
+
 const USAGE = `Usage:
   ocx agent [status] [--json]
   ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
@@ -20,8 +27,10 @@ const USAGE = `Usage:
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
-  ocx agent sidecar <status|web|vision> [--model <id|->] [--backend <openai|anthropic|->]
-      [--reasoning <level>] [--max-descriptions <n>] [--json]`;
+  ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
+      [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
+      [--reasoning <level>] [--max-descriptions <n>] [--json]
+  ocx agent request-user-input [on|off] [--json]`;
 
 function clearable(value: string | undefined): string | null | undefined {
   return value === "-" ? null : value;
@@ -152,6 +161,29 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     return;
   }
   if (section !== "web" && section !== "vision") throw new CliUsageError("sidecar must be web, vision, or status", USAGE);
+  // --list must be consumed BEFORE rejectArgs sees it. It prints the server's
+  // candidate set — the exact list the GUI picker shows (#2188): the server
+  // computes it once and every surface consumes it, so the CLI cannot drift.
+  const wantsList = takeFlag(args, "--list");
+  if (wantsList) {
+    rejectArgs(args, USAGE);
+    const settings = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+      visionModels?: Array<{ value: string; backend?: string; baseline?: boolean }>;
+    };
+    if (section === "web") {
+      const options = settings.webSearchModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no runnable web-search sidecar models (log in to ChatGPT or Anthropic)"]
+        : options.map(option => `${option.value} [${option.backend}]${option.authSlot ? " (auth slot)" : ""}`));
+    } else {
+      const options = settings.visionModels ?? [];
+      printData(options, wantsJson, options.length === 0
+        ? ["no eligible vision describers"]
+        : options.map(option => `${option.value}${option.backend ? ` [${option.backend}]` : ""}${option.baseline ? " (baseline)" : ""}`));
+    }
+    return;
+  }
   const model = takeOption(args, "--model");
   const backend = takeOption(args, "--backend");
   const reasoning = takeOption(args, "--reasoning");
@@ -163,6 +195,19 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (reasoning !== undefined) settings.reasoning = reasoning;
   if (maxDescriptionsPerTurn !== undefined) settings.maxDescriptionsPerTurn = maxDescriptionsPerTurn;
   if (Object.keys(settings).length === 0) throw new CliUsageError("at least one sidecar option is required", USAGE);
+  if (section === "web" && model !== undefined && model !== "-") {
+    const offered = await runtimeRequest("/api/sidecar-settings", {}, deps) as {
+      webSearchModels?: WebSearchModelOption[];
+    };
+    const requestedBackend = backend === "-" ? "openai" : backend;
+    const option = offered.webSearchModels?.find(candidate =>
+      (candidate.value === model || candidate.model === model)
+      && (requestedBackend === undefined || candidate.backend === requestedBackend));
+    if (option) {
+      settings.model = option.model;
+      if (backend !== "-") settings.backend = option.backend;
+    }
+  }
   const body = section === "web" ? { webSearch: settings } : { vision: settings };
   const result = await runtimeRequest("/api/sidecar-settings", { method: "PUT", body: JSON.stringify(body) }, deps);
   printData(result, wantsJson, [`${section} sidecar settings updated.`]);
@@ -177,6 +222,12 @@ export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps =
     else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
     else if (sub === "fallback") await fallback(rest, deps);
     else if (sub === "sidecar") await sidecar(rest, deps);
+    // Lives here rather than as a top-level verb because it is an agent-behavior feature flag:
+    // it controls whether default mode may ask the operator a question mid-task.
+    else if (sub === "request-user-input") {
+      const { requestUserInputAction } = await import("./inspect");
+      await requestUserInputAction(rest, deps);
+    }
     else throw new CliUsageError(`unknown agent command ${sub}`, USAGE);
   });
 }