@iislee/opencodex 2.11.0

package/src/cli/account-extended.ts

@@ -0,0 +1,350 @@
+import { loadConfig } from "../config";
+import {
+  apiError,
+  apiJson,
+  classifyAccount,
+  fetchCodexRows,
+  fetchProviderQuotaReport,
+  fetchRows,
+  proxyUnreachable,
+  resolveBaseUrl,
+  type AccountDeps, type AccountStdin, type FamilyRows,
+  type ProviderQuotaDto, type ProviderQuotaReportDto,
+} from "./account-api";
+
+const MAIN_ID = "__main__";
+const AUTO_NOTE = "auto (no pin — lowest-usage account is selected per request)";
+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 remove <provider> <id|main> --yes [--json]
+  ocx account clear-cooldown <provider> <id|main> [--json]
+  ocx account add-key <provider> [--label <label>] [--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>`;
+
+function flag(args: string[], value: string): boolean {
+  const index = args.indexOf(value);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+function flagValue(args: string[], value: string): { found: boolean; value?: string } {
+  const index = args.indexOf(value);
+  if (index < 0) return { found: false };
+  if (index + 1 >= args.length) return { found: true };
+  const result = args[index + 1];
+  args.splice(index, 2);
+  return { found: true, value: result };
+}
+
+function usage(message?: string): number {
+  if (message) console.error(message);
+  console.error(EXTENDED_USAGE);
+  return 1;
+}
+
+function configAndType(deps: AccountDeps, name: string) {
+  return classifyAccount(deps.loadConfigImpl?.() ?? loadConfig(), name);
+}
+
+function familyFailure(result: FamilyRows, fallback: string): number | null {
+  if (result.networkDown) return proxyUnreachable();
+  if (result.errorJson) return apiError(result.errorJson, fallback);
+  return null;
+}
+
+function errorText(json: Record<string, unknown> | undefined, fallback: string): string {
+  return typeof json?.error === "string" ? json.error : fallback;
+}
+
+function resetIso(value: number | undefined): string | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const date = new Date(value < 10_000_000_000 ? value * 1000 : value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+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.needsReauth) parts.push("needs-reauth");
+  return parts.filter(Boolean).join(" ");
+}
+
+function quotaParts(quota: ProviderQuotaDto): string[] {
+  const parts: string[] = [];
+  const add = (label: string, percent: number | undefined, resetAt?: number) => {
+    if (percent === undefined) return;
+    parts.push(`${label} ${percent}%`);
+    const reset = resetIso(resetAt);
+    if (reset) parts.push(`resets ${reset}`);
+  };
+  add("5h", quota.fiveHourPercent, quota.fiveHourResetAt);
+  add("weekly", quota.weeklyPercent, quota.weeklyResetAt);
+  add("monthly", quota.monthlyPercent, quota.monthlyResetAt);
+  for (const window of quota.customWindows ?? []) add(window.label, window.percent, window.resetAt);
+  return parts;
+}
+
+function providerQuotaLine(name: string, report: ProviderQuotaReportDto): string {
+  return [name, ...quotaParts(report.quota)].join(" ");
+}
+
+export async function readStdinLine(deps: AccountDeps): Promise<string> {
+  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
+  const timeoutMs = deps.stdinTimeoutMs ?? 15_000;
+  return await new Promise<string>((resolve, reject) => {
+    let buffer = "";
+    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) => {
+      buffer += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+      const newline = buffer.search(/[\r\n]/);
+      if (newline >= 0) finish(() => resolve(buffer.slice(0, newline).trim()));
+    };
+    const onEnd = () => finish(() => resolve(buffer.trim()));
+    const onError = (error: Error) => finish(() => reject(error));
+    const timer = setTimeout(() => finish(() => reject(new Error("timed out waiting for API key on stdin"))), timeoutMs);
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+  });
+}
+
+export async function cmdRefresh(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}`);
+  const baseUrl = await resolveBaseUrl(deps);
+  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 (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;
+  }
+  const result = await fetchCodexRows(deps, baseUrl, true);
+  const failed = familyFailure(result, `failed to refresh ${name}`);
+  if (failed !== null) return failed;
+  if (wantsJson) console.log(JSON.stringify({ accounts: result.rows }, null, 2));
+  else for (const row of result.rows) console.log(refreshLine(row));
+  return 0;
+}
+
+export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const action = args.shift();
+  if (!name || !action) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified || classified.type !== "codex") {
+    return usage("Error: auto-switch only applies to the openai Codex account pool");
+  }
+  let threshold: number | undefined;
+  if (action === "on" && args.length === 0) threshold = 80;
+  else if (action === "off" && args.length === 0) threshold = 0;
+  else if (action === "threshold" && args.length === 1 && /^\d+$/.test(args[0]!)) threshold = Number(args[0]);
+  else if (action !== "status" || args.length !== 0) return usage();
+  if (threshold !== undefined && (!Number.isInteger(threshold) || threshold < 0 || threshold > 100)) {
+    return usage("Error: threshold must be an integer 0-100");
+  }
+  const baseUrl = await resolveBaseUrl(deps);
+  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 !== 200 || typeof response.json.autoSwitchThreshold !== "number") {
+      return apiError(response.json, "failed to read auto-switch 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");
+  }
+  const enabled = threshold! > 0;
+  if (wantsJson) console.log(JSON.stringify({ provider: name, autoSwitchThreshold: threshold, enabled }, null, 2));
+  else console.log(enabled ? `auto-switch: on (threshold ${threshold}%)` : "auto-switch: off");
+  return 0;
+}
+
+function deletePath(type: "codex" | "oauth" | "api-key", name: string, id: string): string {
+  if (type === "codex") return `/api/codex-auth/accounts?id=${encodeURIComponent(id)}`;
+  if (type === "oauth") return `/api/oauth/accounts?provider=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
+  return `/api/providers/keys?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`;
+}
+
+export async function cmdRemove(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const fail = (message: string): number => {
+    if (wantsJson) console.error(JSON.stringify({ error: message }));
+    else console.error(`Error: ${message}`);
+    return 1;
+  };
+  const confirmed = flag(args, "--yes");
+  const name = args.shift();
+  const requestedId = args.shift();
+  if (!name || !requestedId || args.length) return wantsJson ? fail("provider and account id are required") : usage();
+  if (!confirmed) {
+    const message = `Confirmation required. Re-run: ocx account remove ${name} ${requestedId} --yes`;
+    return wantsJson ? fail(message) : usage(message);
+  }
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return wantsJson ? fail(classified.error) : usage(`Error: ${classified.error}`);
+  const id = classified.type === "codex" && requestedId === "main" ? MAIN_ID : requestedId;
+  if (classified.type === "codex" && id === MAIN_ID) return wantsJson
+    ? fail("the main Codex App login cannot be removed")
+    : usage("Error: the main Codex App login cannot be removed");
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  const before = await fetchRows(deps, baseUrl, name, classified.type);
+  if (before.networkDown) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  if (before.errorJson) return fail(errorText(before.errorJson, `failed to verify ${name} before removal`));
+  if (!before.rows.some(row => row.id === id)) return wantsJson
+    ? fail(`account or key "${requestedId}" was not found`)
+    : usage(`Error: account or key "${requestedId}" was not found`);
+  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 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 };
+  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}`);
+  return 0;
+}
+
+export async function cmdAddKey(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const labelArg = flagValue(args, "--label");
+  const name = args.shift();
+  if (!name || args.length || (labelArg.found && labelArg.value === undefined)) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified || classified.type !== "api-key") return usage("Error: add-key only applies to API-key providers");
+  const input: AccountStdin = deps.stdinImpl ?? process.stdin;
+  if (input.isTTY) return usage(PIPE_GUIDANCE);
+  let key: string;
+  try {
+    key = await readStdinLine(deps);
+  } catch (error) {
+    return usage(`Error: ${error instanceof Error ? error.message : String(error)}\n${PIPE_GUIDANCE}`);
+  }
+  if (!key) return usage(`Error: API key input was empty\n${PIPE_GUIDANCE}`);
+  const label = labelArg.value?.trim();
+  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}`);
+  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
+  // pass in escaped form (audit finding, Carver WP3-C).
+  const safeLabel = label ? label.replaceAll(key, "[redacted]") : undefined;
+  const result = { ok: true, id, ...(safeLabel ? { label: safeLabel } : {}) };
+  const output = wantsJson ? JSON.stringify(result, null, 2)
+    : `${name}: added API key ${id ?? ""}${safeLabel ? ` (${safeLabel})` : ""}`.trim();
+  console.log(output.replaceAll(key, "[redacted]"));
+  return 0;
+}
+
+/**
+ * Lift a quota cooldown on a Codex account.
+ *
+ * This is the user-facing escape from the lockout described in
+ * `devlog/_plan/260726_cooldown_lockout_hardening`: injected routing makes the proxy the
+ * only model path for Codex Desktop, so a stuck cooldown reads as "the whole app is dead".
+ *
+ * Codex accounts only. API-key pools already reset their own 429 cooldowns through key
+ * management (`clearKeyCooldowns`), and OAuth providers have no equivalent state here.
+ */
+export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = 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: ${name} is not a Codex account pool; cooldown clearing applies to Codex accounts only`);
+  }
+  const id = requestedId === "main" ? MAIN_ID : requestedId;
+  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}`);
+  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}`);
+  else console.log(`${name}: no active cooldown for ${requestedId}`);
+  return 0;
+}
+
+export async function cmdAlias(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = args.shift();
+  const requestedAlias = args.shift();
+  if (!name || !requestedId || requestedAlias === undefined || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  const id = classified.type === "codex" && requestedId === "main" ? MAIN_ID : requestedId;
+  if (id === MAIN_ID) return usage("Error: the main Codex App login cannot be renamed");
+  const alias = requestedAlias === "-" ? "" : requestedAlias.trim();
+  if (alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) return usage("Error: alias must be at most 80 printable characters");
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+  const path = classified.type === "codex"
+    ? "/api/codex-auth/accounts/alias"
+    : classified.type === "oauth"
+      ? "/api/oauth/accounts/alias"
+      : "/api/providers/keys/alias";
+  const body = classified.type === "codex"
+    ? { id, alias }
+    : classified.type === "oauth"
+      ? { 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}`);
+  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}`);
+  return 0;
+}

package/src/cli/account.ts

@@ -0,0 +1,275 @@
+/** `ocx account` — list and switch provider credentials (issue #180). */
+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 { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
+  from "./account-api";
+
+export { classifyAccount } from "./account-api";
+export type { AccountDeps, AccountRow, AccountType, ClassifyResult } from "./account-api";
+type TargetProvenance = "live-oauth-list" | "config" | "codex";
+
+const MAIN_ALIAS = "main";
+const MAIN_CODEX_ID = "__main__";
+/** Replacement-style single-slot OAuth (no stable identity; not HTTP-derivable). */
+const REPLACEMENT_STYLE_OAUTH = new Set(["kiro"]);
+
+const ACCOUNT_USAGE = `Usage:
+  ocx account list [provider] [--json] [--all]
+  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 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 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]
+
+List and switch provider accounts and API-key pools (masked output only).
+'main' selects the Codex App login for the openai account pool.`;
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return false;
+  args.splice(idx, 1);
+  return true;
+}
+
+/** Returns an error message for leftover args, or null when clean. */
+function leftoverArgsError(args: string[]): string | null {
+  if (args.length === 0) return null;
+  const unknown = args.filter(a => a.startsWith("-"));
+  return unknown.length > 0
+    ? `Unknown flag(s): ${unknown.join(", ")}`
+    : `Unexpected argument(s): ${args.join(", ")}`;
+}
+
+function candidateNames(config: OcxConfig): string {
+  const names = new Set<string>(["openai"]);
+  for (const n of Object.keys(config.providers ?? {})) names.add(n);
+  return [...names].join(", ");
+}
+
+function displayId(id: string): string {
+  return id === MAIN_CODEX_ID ? MAIN_ALIAS : id;
+}
+
+function statusText(row: AccountRow): string {
+  const parts: string[] = [];
+  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"];
+  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 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();
+  return [line(header), ...data.map(line)].join("\n");
+}
+
+async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const showAll = consumeFlag(rest, "--all");
+  const name = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (leftover) {
+    console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  const targets: { name: string; type: AccountType; provenance: TargetProvenance }[] = [];
+  if (name) {
+    const c = classifyAccount(config, name);
+    if ("error" in c) {
+      console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+      return 1;
+    }
+    targets.push({ name, type: c.type, provenance: "config" });
+  } else {
+    const seen = new Set<string>();
+    const push = (n: string, provenance: TargetProvenance) => {
+      if (seen.has(n)) return;
+      seen.add(n);
+      const c = classifyAccount(config, n);
+      if ("error" in c) return; // fan-out silently skips no-credential providers
+      targets.push({ name: n, type: c.type, provenance });
+    };
+    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 (Array.isArray(providersRes.json.providers)) {
+      for (const p of providersRes.json.providers) {
+        if (typeof p === "string") push(p, "live-oauth-list");
+      }
+    }
+    for (const n of Object.keys(config.providers ?? {})) push(n, "config");
+  }
+
+  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();
+    if (r.errorJson) {
+      if (name) return apiError(r.errorJson, `failed to list ${t.name}`);
+      const errorText = typeof r.errorJson.error === "string" ? r.errorJson.error : "";
+      const skipUnknownKey = t.type === "api-key"
+        && r.status === 404
+        && errorText.includes("unknown provider");
+      const skipConfigOAuth = t.type === "oauth"
+        && t.provenance === "config"
+        && r.status === 400
+        && errorText.includes("unknown oauth provider");
+      if (skipUnknownKey || skipConfigOAuth) continue;
+      return apiError(r.errorJson, `failed to list ${t.name}`);
+    }
+    if (r.rows.length === 0) {
+      if (showAll) notes.push(`${t.name}: no stored accounts or keys`);
+      continue;
+    }
+    rows.push(...r.rows);
+    if (t.type === "codex") {
+      if (r.activeId === null) notes.push("openai: auto (no pin — lowest-usage account is selected per request)");
+      if (providerCodexAccountMode("openai", config.providers?.openai) === "direct") {
+        notes.push("openai is in direct mode — the selection takes effect when pool mode is enabled");
+      }
+    }
+    if (t.type === "oauth" && REPLACEMENT_STYLE_OAUTH.has(t.name)) {
+      notes.push(`${t.name}: single login slot — re-login replaces the current account`);
+    }
+  }
+
+  if (wantsJson) {
+    console.log(JSON.stringify({ accounts: rows, notes }, null, 2));
+    return 0;
+  }
+  if (rows.length > 0) console.log(formatAccountTable(rows));
+  for (const n of notes) console.log(n);
+  if (rows.length === 0 && notes.length === 0) console.log("No stored accounts or keys.");
+  return 0;
+}
+
+async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const name = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (!name || leftover) {
+    if (leftover) console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const c = classifyAccount(config, name);
+  if ("error" in c) {
+    console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+    return 1;
+  }
+  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}`);
+
+  const activeRow = r.rows.find(row => row.active) ?? null;
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      provider: name,
+      type: c.type,
+      activeId: r.activeId,
+      autoSwitchThreshold: r.autoSwitchThreshold,
+      account: activeRow,
+    }, null, 2));
+    return 0;
+  }
+  if (activeRow) {
+    console.log(formatAccountTable([activeRow]));
+  } else if (c.type === "codex" && r.activeId === null) {
+    console.log("openai: auto (no pin — lowest-usage account is selected per request)");
+  } else {
+    console.log(`${name}: no active account or key`);
+  }
+  return 0;
+}
+
+async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = consumeFlag(rest, "--json");
+  const name = rest.shift();
+  const id = rest.shift();
+  const leftover = leftoverArgsError(rest);
+  if (!name || !id || leftover) {
+    if (leftover) console.error(leftover);
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  }
+  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const c = classifyAccount(config, name);
+  if ("error" in c) {
+    console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
+    return 1;
+  }
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  let res: ApiResult;
+  let activeId: string;
+  if (c.type === "codex") {
+    activeId = id === MAIN_ALIAS ? MAIN_CODEX_ID : id;
+    res = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/active", { accountId: activeId });
+  } else if (c.type === "oauth") {
+    activeId = id;
+    res = await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/active", { provider: name, accountId: id });
+  } else {
+    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 (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.");
+  }
+  return 0;
+}
+
+export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promise<number> {
+  const [sub, ...rest] = args;
+  try {
+    if (sub === "list") return await cmdList(rest, deps);
+    if (sub === "current") return await cmdCurrent(rest, deps);
+    if (sub === "use") return await cmdUse(rest, deps);
+    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 === "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 (["login", "reauth", "code", "cancel", "reset-credits"].includes(sub ?? "")) {
+      const { handleAccountAuthCommand } = await import("./account-auth");
+      return await handleAccountAuthCommand(sub!, rest, deps) ?? 1;
+    }
+    console.error(ACCOUNT_USAGE);
+    return 1;
+  } catch (err) {
+    console.error(`account: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}