@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/account-extended.ts

@@ -1,4 +1,11 @@
 import { loadConfig } from "../config";
+import { closeSync, openSync, readSync } from "node:fs";
+import {
+  MAX_ACCOUNT_PRIORITY,
+  MIN_ACCOUNT_PRIORITY,
+  normalizeAccountPriority,
+  parseAccountPriority,
+} from "../codex/pool-rotation";
 import {
   apiError,
   apiJson,
@@ -11,6 +18,20 @@ import {
   type AccountDeps, type AccountStdin, type FamilyRows,
   type ProviderQuotaDto, type ProviderQuotaReportDto,
 } from "./account-api";
+import {
+  codexCatalogRefreshPending,
+  warnIfCodexCatalogRefreshPending,
+} from "./account-catalog-refresh";
+import {
+  ACCOUNT_IMPORT_DEADLINE_MS,
+  ACCOUNT_IMPORT_FORMAT,
+  ACCOUNT_IMPORT_MAX_BYTES,
+  ACCOUNT_IMPORT_PROVIDER,
+  type AccountImportCode,
+  type AccountImportRecordResult,
+  type AccountImportResult,
+  type AccountImportStatus,
+} from "../oauth/account-import";
 
 const MAIN_ID = "__main__";
 const AUTO_NOTE = "auto (no pin — lowest-usage account is selected per request)";
@@ -18,12 +39,20 @@ const EXTENDED_USAGE = `Usage:
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account alias <provider> <id|main> <display-name|-> [--json]
+  ocx account priority <provider> <id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
+  ocx account pause <provider> <id|main> [--json]
+  ocx account resume <provider> <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> <id|main> --yes [--json]
   ocx account clear-cooldown <provider> <id|main> [--json]
-  ocx account add-key <provider> [--label <label>] [--json]`;
+  ocx account add-key <provider> [--label <label>] [--json]
+  ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]`;
 const PIPE_GUIDANCE = `Pipe the API key on stdin, for example:
   ocx account add-key <provider> <<< "$MY_KEY"
   security find-generic-password -w <item> | ocx account add-key <provider>`;
+const ACCOUNT_IMPORT_TIMEOUT_MS = ACCOUNT_IMPORT_DEADLINE_MS;
 
 function flag(args: string[], value: string): boolean {
   const index = args.indexOf(value);
@@ -41,6 +70,162 @@ function flagValue(args: string[], value: string): { found: boolean; value?: str
   return { found: true, value: result };
 }
 
+function boundedUtf8(bytes: Uint8Array): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("invalid_document");
+  }
+}
+
+function readBoundedImportFile(path: string): string {
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(path, "r");
+    const buffer = Buffer.allocUnsafe(ACCOUNT_IMPORT_MAX_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const read = readSync(descriptor, buffer, offset, buffer.length - offset, null);
+      if (read === 0) break;
+      offset += read;
+    }
+    if (offset > ACCOUNT_IMPORT_MAX_BYTES) throw new Error("invalid_document");
+    return boundedUtf8(buffer.subarray(0, offset));
+  } catch (error) {
+    if (error instanceof Error && error.message === "invalid_document") throw error;
+    throw new Error("source_read_failed");
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+async function readBoundedImportStdin(deps: AccountDeps): Promise<string> {
+  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
+  if (input.isTTY) throw new Error("stdin_required");
+  const timeoutMs = deps.stdinTimeoutMs ?? 15_000;
+  return await new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timer);
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("error", onError);
+    };
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn();
+    };
+    const onData = (chunk: unknown) => {
+      const encoded = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      bytes += encoded.byteLength;
+      if (bytes > ACCOUNT_IMPORT_MAX_BYTES) {
+        finish(() => reject(new Error("invalid_document")));
+        return;
+      }
+      chunks.push(encoded);
+    };
+    const onEnd = () => finish(() => {
+      try { resolve(boundedUtf8(Buffer.concat(chunks, bytes))); }
+      catch (error) { reject(error); }
+    });
+    const onError = () => finish(() => reject(new Error("source_read_failed")));
+    const timer = setTimeout(() => finish(() => reject(new Error("stdin_timeout"))), timeoutMs);
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+  });
+}
+
+const IMPORT_STATUSES = new Set<AccountImportStatus>(["imported", "updated", "failed", "unsupported"]);
+const IMPORT_CODES = new Set<AccountImportCode>([
+  "imported", "updated", "import_cancelled", "unsupported_provider", "unsupported_format", "invalid_document",
+  "invalid_record", "credential_rejected", "identity_mismatch", "missing_project", "persist_failed",
+]);
+const IMPORT_RESULT_FIELDS = new Set([
+  "totalCount", "importedCount", "updatedCount", "failedCount", "unsupportedCount", "results",
+]);
+const IMPORT_RECORD_FIELDS = new Set(["index", "status", "code"]);
+const IMPORT_STATUS_CODES: Record<AccountImportStatus, ReadonlySet<AccountImportCode>> = {
+  imported: new Set(["imported"]),
+  updated: new Set(["updated"]),
+  failed: new Set(["invalid_record", "credential_rejected", "identity_mismatch", "missing_project", "persist_failed"]),
+  unsupported: new Set(["unsupported_provider", "unsupported_format"]),
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function hasExactFields(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+  const fields = Object.keys(value);
+  return fields.length === allowed.size && fields.every(field => allowed.has(field));
+}
+
+function isNonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && Number.isSafeInteger(value) && value >= 0;
+}
+
+function safeImportResult(json: unknown): AccountImportResult | null {
+  if (!isPlainObject(json) || !hasExactFields(json, IMPORT_RESULT_FIELDS)) return null;
+  if (
+    !isNonNegativeSafeInteger(json.totalCount)
+    || !isNonNegativeSafeInteger(json.importedCount)
+    || !isNonNegativeSafeInteger(json.updatedCount)
+    || !isNonNegativeSafeInteger(json.failedCount)
+    || !isNonNegativeSafeInteger(json.unsupportedCount)
+  ) return null;
+  if (!Array.isArray(json.results)) return null;
+  if (json.results.length !== json.totalCount) return null;
+
+  const results: AccountImportRecordResult[] = [];
+  const indices = new Set<number>();
+  const aggregate: Record<AccountImportStatus, number> = {
+    imported: 0,
+    updated: 0,
+    failed: 0,
+    unsupported: 0,
+  };
+  for (const raw of json.results) {
+    if (!isPlainObject(raw) || !hasExactFields(raw, IMPORT_RECORD_FIELDS)) return null;
+    const item = raw;
+    if (!isNonNegativeSafeInteger(item.index) || item.index >= json.totalCount || indices.has(item.index)) return null;
+    if (!IMPORT_STATUSES.has(item.status as AccountImportStatus)) return null;
+    if (!IMPORT_CODES.has(item.code as AccountImportCode)) return null;
+    const status = item.status as AccountImportStatus;
+    const code = item.code as AccountImportCode;
+    if (!IMPORT_STATUS_CODES[status].has(code)) return null;
+    indices.add(item.index);
+    aggregate[status] += 1;
+    results.push({
+      index: item.index,
+      status,
+      code,
+    });
+  }
+  if (
+    indices.size !== json.totalCount
+    || aggregate.imported !== json.importedCount
+    || aggregate.updated !== json.updatedCount
+    || aggregate.failed !== json.failedCount
+    || aggregate.unsupported !== json.unsupportedCount
+  ) return null;
+
+  return {
+    totalCount: json.totalCount,
+    importedCount: json.importedCount,
+    updatedCount: json.updatedCount,
+    failedCount: json.failedCount,
+    unsupportedCount: json.unsupportedCount,
+    results,
+  };
+}
+
 function usage(message?: string): number {
   if (message) console.error(message);
   console.error(EXTENDED_USAGE);
@@ -52,8 +237,8 @@ function configAndType(deps: AccountDeps, name: string) {
 }
 
 function familyFailure(result: FamilyRows, fallback: string): number | null {
-  if (result.networkDown) return proxyUnreachable();
-  if (result.errorJson) return apiError(result.errorJson, fallback);
+  if (result.networkDown) return proxyUnreachable(result.transportError);
+  if (result.errorJson) return apiError(result.errorJson, fallback, result.status);
   return null;
 }
 
@@ -69,17 +254,14 @@ function resetIso(value: number | undefined): string | null {
 
 function refreshLine(row: FamilyRows["rows"][number]): string {
   const parts = [row.id === MAIN_ID ? "main" : row.id, row.email, row.plan];
-  const quota = row.quota;
-  if (!quota || (quota.weeklyPercent === undefined && quota.monthlyPercent === undefined)) {
-    parts.push("quota: unknown");
-  } else {
-    if (quota.weeklyPercent !== undefined) parts.push(`weekly ${quota.weeklyPercent}%`);
-    const weeklyReset = resetIso(quota.weeklyResetAt);
-    if (weeklyReset) parts.push(`resets ${weeklyReset}`);
-    if (quota.monthlyPercent !== undefined) parts.push(`monthly ${quota.monthlyPercent}%`);
-    const monthlyReset = resetIso(quota.monthlyResetAt);
-    if (monthlyReset) parts.push(`resets ${monthlyReset}`);
-  }
+  if (row.paused) parts.push("paused");
+  // Was a second quota dialect: it gated the whole block on weekly/monthly, so an account
+  // reporting only a 5h window printed `quota: unknown` while `quotaParts` five lines below
+  // rendered the same data correctly for the provider path (#2703). Two halves of one file
+  // disagreeing about how to read one DTO is the defect; delegating removes it rather than
+  // teaching the second dialect a third window.
+  const quotaText = row.quota ? quotaParts(row.quota).join(" ") : "";
+  parts.push(quotaText.length > 0 ? quotaText : "quota: unknown");
   if (row.needsReauth) parts.push("needs-reauth");
   return parts.filter(Boolean).join(" ");
 }
@@ -99,7 +281,7 @@ function quotaParts(quota: ProviderQuotaDto): string[] {
   return parts;
 }
 
-function providerQuotaLine(name: string, report: ProviderQuotaReportDto): string {
+export function providerQuotaLine(name: string, report: ProviderQuotaReportDto): string {
   return [name, ...quotaParts(report.quota)].join(" ");
 }
 
@@ -145,8 +327,8 @@ export async function cmdRefresh(args: string[], deps: AccountDeps): Promise<num
   if (!baseUrl) return proxyUnreachable();
   if (classified.type !== "codex") {
     const result = await fetchProviderQuotaReport(deps, baseUrl, name);
-    if (result.status === 0) return proxyUnreachable();
-    if (result.status !== 200) return apiError(result.errorJson ?? {}, `failed to refresh ${name}`);
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.errorJson ?? {}, `failed to refresh ${name}`, result.status);
     if (wantsJson) console.log(JSON.stringify({ provider: name, report: result.report }, null, 2));
     else console.log(result.report ? providerQuotaLine(name, result.report) : `no quota report available for ${name}`);
     return 0;
@@ -180,15 +362,15 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
   if (!baseUrl) return proxyUnreachable();
   if (action === "status") {
     const response = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
-    if (response.status === 0) return proxyUnreachable();
+    if (response.status === 0) return proxyUnreachable(response.transportError);
     if (response.status !== 200 || typeof response.json.autoSwitchThreshold !== "number") {
-      return apiError(response.json, "failed to read auto-switch status");
+      return apiError(response.json, "failed to read auto-switch status", response.status);
     }
     threshold = response.json.autoSwitchThreshold;
   } else {
     const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
-    if (response.status === 0) return proxyUnreachable();
-    if (response.status !== 200) return apiError(response.json, "failed to update auto-switch");
+    if (response.status === 0) return proxyUnreachable(response.transportError);
+    if (response.status !== 200) return apiError(response.json, "failed to update auto-switch", response.status);
   }
   const enabled = threshold! > 0;
   if (wantsJson) console.log(JSON.stringify({ provider: name, autoSwitchThreshold: threshold, enabled }, null, 2));
@@ -234,18 +416,28 @@ export async function cmdRemove(args: string[], deps: AccountDeps): Promise<numb
   const response = await apiJson(deps, baseUrl, "DELETE", deletePath(classified.type, name, id));
   if (response.status === 0) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
   if (response.status !== 200) return fail(errorText(response.json, `failed to remove ${requestedId}`));
+  const catalogRefreshPending = classified.type === "codex"
+    && codexCatalogRefreshPending(response.json);
   const after = await fetchRows(deps, baseUrl, name, classified.type);
   if (after.networkDown || after.errorJson) {
     const detail = after.networkDown ? "proxy not reachable" : typeof after.errorJson?.error === "string" ? after.errorJson.error : "unknown error";
     return fail(`post-delete verification failed; delete may have succeeded: ${detail}`);
   }
   const removedActive = before.activeId === id;
-  const result = { ok: true, provider: name, id, removedActive, promotedActiveId: after.activeId };
+  const result = {
+    ok: true,
+    provider: name,
+    id,
+    removedActive,
+    promotedActiveId: after.activeId,
+    ...(classified.type === "codex" ? { catalogRefreshPending } : {}),
+  };
   if (wantsJson) console.log(JSON.stringify(result, null, 2));
   else if (classified.type === "codex" && removedActive && after.activeId === null) console.log(`openai: ${AUTO_NOTE}`);
   else if (classified.type === "oauth") console.log(after.rows.length ? `${name}: active account is now ${after.activeId}` : `${name}: no accounts remaining`);
   else if (classified.type === "api-key") console.log(after.rows.length ? `${name}: active key is now ${after.activeId}` : `${name}: no keys remaining`);
   else console.log(`${name}: removed account ${requestedId}`);
+  if (!wantsJson && catalogRefreshPending) warnIfCodexCatalogRefreshPending(response.json);
   return 0;
 }
 
@@ -269,8 +461,8 @@ export async function cmdAddKey(args: string[], deps: AccountDeps): Promise<numb
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   const response = await apiJson(deps, baseUrl, "POST", "/api/providers/keys", { name, key, ...(label ? { label } : {}) });
-  if (response.status === 0) return proxyUnreachable();
-  if (response.status !== 201) return apiError(response.json, `failed to add a key for ${name}`);
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 201) return apiError(response.json, `failed to add a key for ${name}`, response.status);
   const id = typeof response.json.id === "string" ? response.json.id : null;
   // Redact the key inside the label BEFORE serialization — a key containing
   // JSON-escaped characters (" or \) would otherwise survive the whole-output
@@ -283,6 +475,98 @@ export async function cmdAddKey(args: string[], deps: AccountDeps): Promise<numb
   return 0;
 }
 
+export async function cmdImport(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const formatArg = flagValue(args, "--format");
+  const fileArg = flagValue(args, "--file");
+  const fromStdin = flag(args, "--stdin");
+  const provider = args.shift();
+
+  // Admission happens before source I/O. In particular, an inline JSON positional argument is
+  // rejected without inspecting or echoing it, keeping secrets out of any subsequent surface.
+  if (
+    provider !== ACCOUNT_IMPORT_PROVIDER
+    || formatArg.value !== ACCOUNT_IMPORT_FORMAT
+    || formatArg.found !== true
+  ) {
+    const code = provider === ACCOUNT_IMPORT_PROVIDER ? "unsupported_format" : "unsupported_provider";
+    console.error(`Error: ${code}`);
+    return 1;
+  }
+  const hasFile = fileArg.found && typeof fileArg.value === "string" && fileArg.value.length > 0;
+  if (args.length > 0 || hasFile === fromStdin || (fileArg.found && !hasFile)) {
+    return usage("Error: choose exactly one bounded source: --file <path> or --stdin");
+  }
+
+  let source: string;
+  try {
+    source = hasFile ? readBoundedImportFile(fileArg.value!) : await readBoundedImportStdin(deps);
+  } catch (error) {
+    const code = error instanceof Error ? error.message : "source_read_failed";
+    console.error(`Error: ${["invalid_document", "source_read_failed", "stdin_required", "stdin_timeout"].includes(code) ? code : "source_read_failed"}`);
+    return 1;
+  }
+
+  let document: unknown;
+  try {
+    document = JSON.parse(source) as unknown;
+  } catch {
+    console.error("Error: invalid_document");
+    return 1;
+  }
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  const configuredImportTimeout = deps.importTimeoutMs;
+  const importTimeoutMs = typeof configuredImportTimeout === "number" && Number.isFinite(configuredImportTimeout)
+    ? Math.min(ACCOUNT_IMPORT_TIMEOUT_MS, Math.max(1, Math.floor(configuredImportTimeout)))
+    : ACCOUNT_IMPORT_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, importTimeoutMs);
+  let response;
+  try {
+    response = await apiJson(deps, baseUrl, "POST", "/api/oauth/accounts/import", {
+      provider,
+      format: formatArg.value,
+      document,
+    }, { signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 0) {
+    if (!timedOut) return proxyUnreachable(response.transportError);
+    console.error(`Error: import_timeout after ${importTimeoutMs}ms`);
+    return 1;
+  }
+  if (response.status !== 200) {
+    if (IMPORT_CODES.has(response.json.code as AccountImportCode)) {
+      console.error(`Error: ${response.json.code as AccountImportCode}`);
+    } else {
+      console.error(`Error: import_request_failed (status ${response.status})`);
+    }
+    return 1;
+  }
+  const result = safeImportResult(response.json);
+  if (!result) {
+    console.error("Error: invalid_response");
+    return 1;
+  }
+
+  if (wantsJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(
+      `${provider}: ${result.importedCount} imported, ${result.updatedCount} updated, ${result.failedCount} failed, ${result.unsupportedCount} unsupported`,
+    );
+    for (const item of result.results) console.log(`  #${item.index + 1} ${item.status} (${item.code})`);
+  }
+  return result.failedCount > 0 || result.unsupportedCount > 0 ? 1 : 0;
+}
+
 /**
  * Lift a quota cooldown on a Codex account.
  *
@@ -307,8 +591,8 @@ export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promi
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   const response = await apiJson(deps, baseUrl, "POST", "/api/codex-auth/accounts/clear-cooldown", { id });
-  if (response.status === 0) return proxyUnreachable();
-  if (response.status !== 200) return apiError(response.json, `failed to clear cooldown for ${requestedId}`);
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, `failed to clear cooldown for ${requestedId}`, response.status);
   const cleared = response.json?.cleared === true;
   if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, id, cleared }, null, 2));
   else if (cleared) console.log(`${name}: cooldown lifted for ${requestedId}`);
@@ -316,6 +600,342 @@ export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promi
   return 0;
 }
 
+/**
+ * Named selection orders. The words convey sequence rather than rank because the
+ * pool moves down the list only when everything above it is drained — "high
+ * priority" would suggest the account gets more traffic, which is not what
+ * ordering does.
+ */
+const PRIORITY_PRESETS: Record<string, number> = {
+  first: 2,
+  earlier: 1,
+  normal: 0,
+  later: -1,
+  last: -2,
+};
+
+function priorityPresetName(priority: number): string | null {
+  return Object.entries(PRIORITY_PRESETS).find(([, value]) => value === priority)?.[0] ?? null;
+}
+
+function formatPriority(priority: number): string {
+  const preset = priorityPresetName(priority);
+  const signed = priority > 0 ? `+${priority}` : String(priority);
+  return preset ? `${signed} (${preset})` : signed;
+}
+
+/** `null` = reset to the default; `undefined` = unparseable. */
+function parsePriorityArgument(raw: string): number | null | undefined {
+  const word = raw.trim().toLowerCase();
+  if (word === "reset") return null;
+  // Own keys only: `in` also matches "constructor", "__proto__", and friends.
+  if (Object.hasOwn(PRIORITY_PRESETS, word)) return PRIORITY_PRESETS[word];
+  // The regex only rules out shapes Number() would coerce ("1e2", " 1 ", ""); the range
+  // itself comes from the core parser so the CLI cannot drift from what the API accepts.
+  if (!/^[+-]?\d+$/.test(word)) return undefined;
+  return parseAccountPriority(Number(word)) ?? undefined;
+}
+
+export async function cmdPriority(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = args.shift();
+  const requestedPriority = args.shift();
+  if (!name || !requestedId || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  if (classified.type !== "codex") {
+    return usage("Error: selection order only applies to the openai Codex account pool");
+  }
+  const id = requestedId === "main" ? MAIN_ID : requestedId;
+
+  // Validate before touching the network so a typo never reaches the proxy.
+  let priority: number | null | undefined;
+  if (requestedPriority !== undefined) {
+    priority = parsePriorityArgument(requestedPriority);
+    if (priority === undefined) {
+      return usage(`Error: selection order must be an integer ${MIN_ACCOUNT_PRIORITY}..${MAX_ACCOUNT_PRIORITY}, one of ${Object.keys(PRIORITY_PRESETS).join("/")}, or reset`);
+    }
+  }
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  // No value means "show" — a read must not rewrite what it is reporting.
+  if (priority === undefined) {
+    const result = await fetchCodexRows(deps, baseUrl);
+    const failed = familyFailure(result, `failed to read ${name} accounts`);
+    if (failed !== null) return failed;
+    const row = result.rows.find(candidate => candidate.id === id);
+    if (!row) return usage(`Error: no ${name} account ${requestedId}`);
+    const current = normalizeAccountPriority(row.priority);
+    if (wantsJson) {
+      console.log(JSON.stringify(
+        { ok: true, provider: name, id, priority: current, preset: priorityPresetName(current) },
+        null,
+        2,
+      ));
+    } else {
+      console.log(`${name}: ${requestedId} selection order is ${formatPriority(current)}`);
+    }
+    return 0;
+  }
+
+  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/priority", { id, priority });
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, `failed to set selection order for ${requestedId}`, response.status);
+  const applied = typeof response.json.priority === "number" ? response.json.priority : (priority ?? 0);
+  if (wantsJson) {
+    console.log(JSON.stringify(
+      { ok: true, provider: name, id, priority: applied, preset: priorityPresetName(applied) },
+      null,
+      2,
+    ));
+  } else {
+    console.log(`${name}: ${requestedId} selection order is now ${formatPriority(applied)}`);
+  }
+  // Not cmdUse's note: re-ordering takes effect on the next unbound request rather than
+  // only on new sessions, because preemption moves those requests up immediately.
+  console.error("Takes effect from the next unbound request; running threads keep their current account until drained.");
+  // The release is not optional and not conditional on the value changing, so it has to be
+  // stated: this route is the only way to clear a pin without immediately setting another,
+  // which means a write storing the order an account already had still releases it. Without
+  // this line that is a silent side effect of a command that looks purely declarative.
+  console.error('Also releases any manual "use this account now" pin, on any account.');
+  return 0;
+}
+
+/**
+ * `ocx account pause|resume <provider> <id>` (#2702).
+ *
+ * The server routes have always existed; only the CLI caller was missing, so pausing an
+ * account was dashboard-only. The issue reports these as POST; the code is PUT
+ * (`auth-api.ts:1494`), and the route is shared by both directions with a `paused` boolean
+ * rather than being two endpoints.
+ */
+export async function cmdPause(args: string[], deps: AccountDeps, paused: boolean): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = args.shift();
+  const verb = paused ? "pause" : "resume";
+  if (!name || !requestedId || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  if (classified.type !== "codex") {
+    return usage(`Error: ${verb} applies to the openai Codex account pool`);
+  }
+  const id = requestedId === "main" ? MAIN_ID : requestedId;
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause", { id, paused });
+  // Transport sentinel first: status 0 means the proxy never answered, and comparing it to
+  // 200 would report an unreachable proxy as a management error.
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, `failed to ${verb} ${requestedId}`, response.status);
+
+  if (wantsJson) {
+    console.log(JSON.stringify({ ok: true, provider: name, id, paused }, null, 2));
+  } else {
+    console.log(`${name}: ${requestedId} ${paused ? "paused" : "resumed"}`);
+  }
+  if (paused) {
+    // Both are server-side effects of this route (auth-api.ts:1508-1510), not consequences
+    // the operator would infer from the word "pause".
+    console.error("Threads bound to this account are unbound, and a fallback account is selected if this one was active.");
+  }
+  return 0;
+}
+
+/**
+ * `ocx account pause-exhausted [--off]` (#2702).
+ *
+ * Pauses every account whose quota is spent. The route refreshes quota for each account, so
+ * it can partially fail; the response distinguishes "checked none and some failed" from
+ * "checked some", and that distinction is reported rather than flattened into ok/not-ok.
+ */
+export async function cmdPauseExhausted(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  if (!name || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  if (classified.type !== "codex") {
+    return usage("Error: pause-exhausted applies to the openai Codex account pool");
+  }
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause-exhausted", {});
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, "failed to pause exhausted accounts", response.status);
+
+  const pausedIds = Array.isArray(response.json.pausedAccountIds)
+    ? (response.json.pausedAccountIds as unknown[]).filter((value): value is string => typeof value === "string")
+    : [];
+  const checked = typeof response.json.checkedAccountCount === "number" ? response.json.checkedAccountCount : null;
+  const failed = typeof response.json.failedAccountCount === "number" ? response.json.failedAccountCount : null;
+
+  const complete = failed === null || failed === 0;
+  const ok = complete;
+  if (failed !== null && failed > 0) {
+    console.error(`Quota refresh failed for ${failed} account(s); those were not evaluated.`);
+  }
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      ok,
+      complete,
+      provider: name,
+      pausedAccountIds: pausedIds,
+      checkedAccountCount: checked,
+      failedAccountCount: failed,
+    }, null, 2));
+    return ok ? 0 : 1;
+  }
+  console.log(pausedIds.length > 0
+    ? `${name}: paused ${pausedIds.length} exhausted account(s): ${pausedIds.join(", ")}`
+    : `${name}: no exhausted accounts to pause`);
+  return ok ? 0 : 1;
+}
+
+/**
+ * Two pools expose strategy and sticky, and they are NOT reached the same way:
+ *
+ * |  | Codex pool | Anthropic pool |
+ * |---|---|---|
+ * | read | `GET /api/codex-auth/active` | `GET /api/oauth/accounts/pool?provider=` |
+ * | write | `PUT /api/codex-auth/pool-strategy` | `PUT /api/oauth/accounts/pool` |
+ * | keys | `accountPoolStrategy`/`accountPoolStickyLimit` | `strategy`/`stickyLimit` |
+ * | body | bare field | field **plus** a mandatory `provider` |
+ *
+ * Omitting `provider` from the Anthropic write body earns a 400
+ * (`oauth-account-routes.ts:344`), so the asymmetry has to be encoded somewhere. Encoding it
+ * here keeps ONE verb pair working on both pools. The alternative the plan left open -- a second
+ * `provider-strategy`/`provider-sticky` pair -- would double the surface an operator must learn
+ * to express one idea, and a CLI that can steer one pool and not the other is exactly the trap
+ * this unit exists to remove.
+ */
+interface PoolTransport {
+  readPath: string;
+  writePath: string;
+  /** Response key carrying the applied strategy. */
+  strategyKey: string;
+  /** Response key carrying the applied sticky limit. */
+  stickyKey: string;
+  writeBody: (field: "strategy" | "stickyLimit", value: unknown) => Record<string, unknown>;
+}
+
+const CODEX_POOL_TRANSPORT: PoolTransport = {
+  readPath: "/api/codex-auth/active",
+  writePath: "/api/codex-auth/pool-strategy",
+  strategyKey: "accountPoolStrategy",
+  stickyKey: "accountPoolStickyLimit",
+  writeBody: (field, value) => ({ [field]: value }),
+};
+
+function anthropicPoolTransport(provider: string): PoolTransport {
+  return {
+    readPath: `/api/oauth/accounts/pool?provider=${encodeURIComponent(provider)}`,
+    writePath: "/api/oauth/accounts/pool",
+    strategyKey: "strategy",
+    stickyKey: "stickyLimit",
+    writeBody: (field, value) => ({ provider, [field]: value }),
+  };
+}
+
+/**
+ * The pool-config route supports `anthropic` only and says so with a 400. Any other OAuth
+ * provider is refused here with the same wording rather than spending a round-trip to learn it.
+ */
+function poolTransportFor(
+  classified: { type: "codex" | "oauth" | "api-key" },
+  name: string,
+): PoolTransport | string {
+  if (classified.type === "codex") return CODEX_POOL_TRANSPORT;
+  if (classified.type === "oauth" && name === "anthropic") return anthropicPoolTransport(name);
+  return `pool settings apply to the openai Codex pool and the anthropic pool, not "${name}"`;
+}
+
+/**
+ * `ocx account strategy <provider> [<name>]` and `ocx account sticky <provider> [<n>]` (#2702).
+ *
+ * One implementation rather than two near-duplicates, because strategy and sticky are two
+ * fields of one setting on every pool that has them.
+ *
+* Values are NOT re-validated here. The server owns both contracts -- three strategy names,
+* a 1-100 sticky bound -- and a duplicated bound is a second thing to keep in sync. Its 400
+* is actionable now that the CLI prints `reason`.
+*/
+async function poolSetting(
+  args: string[],
+  deps: AccountDeps,
+  field: "strategy" | "stickyLimit",
+): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requested = args.shift();
+  const label = field === "strategy" ? "pool strategy" : "sticky limit";
+  if (!name || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  const transport = poolTransportFor(classified, name);
+  if (typeof transport === "string") return usage(`Error: ${transport}`);
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  // No value means show. A read must not rewrite what it is reporting.
+  if (requested === undefined) {
+    const response = await apiJson(deps, baseUrl, "GET", transport.readPath);
+    if (response.status === 0) return proxyUnreachable(response.transportError);
+    if (response.status !== 200) return apiError(response.json, `failed to read ${label}`, response.status);
+    const strategy = response.json[transport.strategyKey];
+    const sticky = response.json[transport.stickyKey];
+    if (wantsJson) {
+      // Pool-neutral key names: the two routes spell the same two settings differently, and a
+      // `--json` consumer should not have to branch on which pool answered.
+      console.log(JSON.stringify({ ok: true, provider: name, strategy, stickyLimit: sticky }, null, 2));
+    } else {
+      console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
+    }
+    return 0;
+  }
+
+  // Sent as a number when it parses as one so the server sees the type it validates;
+  // a non-numeric string still goes through and earns the server's own 400.
+  const value = field === "strategy"
+    ? requested
+    : (Number.isNaN(Number(requested)) ? requested : Number(requested));
+  const response = await apiJson(deps, baseUrl, "PUT", transport.writePath, transport.writeBody(field, value));
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, `failed to set ${label}`, response.status);
+
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      ok: true,
+      provider: name,
+      strategy: response.json[transport.strategyKey],
+      stickyLimit: response.json[transport.stickyKey],
+    }, null, 2));
+  } else {
+    // Echo the APPLIED value from the response, not the requested one: the server normalizes,
+    // and printing the request would hide a normalization the operator should see.
+    const applied = field === "strategy" ? response.json[transport.strategyKey] : response.json[transport.stickyKey];
+    console.log(`${name}: ${label} is now ${String(applied)}`);
+  }
+  return 0;
+}
+
+export function cmdStrategy(args: string[], deps: AccountDeps): Promise<number> {
+  return poolSetting(args, deps, "strategy");
+}
+
+export function cmdSticky(args: string[], deps: AccountDeps): Promise<number> {
+  return poolSetting(args, deps, "stickyLimit");
+}
+
 export async function cmdAlias(args: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = flag(args, "--json");
   const name = args.shift();
@@ -341,8 +961,8 @@ export async function cmdAlias(args: string[], deps: AccountDeps): Promise<numbe
       ? { provider: name, accountId: id, alias }
       : { name, id, alias };
   const response = await apiJson(deps, baseUrl, "PUT", path, body);
-  if (response.status === 0) return proxyUnreachable();
-  if (response.status !== 200) return apiError(response.json, `failed to rename ${requestedId}`);
+  if (response.status === 0) return proxyUnreachable(response.transportError);
+  if (response.status !== 200) return apiError(response.json, `failed to rename ${requestedId}`, response.status);
   const result = { ok: true, provider: name, id, alias: alias || null };
   if (wantsJson) console.log(JSON.stringify(result, null, 2));
   else console.log(alias ? `${name}: ${requestedId} is now “${alias}”` : `${name}: cleared alias for ${requestedId}`);