@yansigit/opencodex 2.36.1-dev.20260829.48 → 2.36.1

package/src/cli/account-api.ts

@@ -24,6 +24,14 @@ export interface AccountRow {
   /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */
   priority?: number;
   quota?: CodexQuotaDto | null;
+  /**
+   * Whether the pool is holding this account out of rotation.
+   *
+   * The server has always sent it (auth-api.ts:286 for pool accounts, :1315 for main) and the
+   * CLI dropped it, so a paused account was indistinguishable from an available one in every
+   * human listing (#2703).
+   */
+  paused?: boolean;
 }
 
 export type ClassifyResult = { type: AccountType } | { error: string };
@@ -83,6 +91,12 @@ export interface ApiResult {
   /** 0 = network-level failure (proxy unreachable). */
   status: number;
   json: Record<string, unknown>;
+  /**
+   * Message from the thrown transport error when `status` is 0. Previously the
+   * error was swallowed by a catch block with an empty body, so an unreachable proxy, a DNS
+   * failure and a TLS error were indistinguishable (#2698).
+   */
+  transportError?: string;
 }
 
 export async function apiJson(
@@ -103,8 +117,14 @@ export async function apiJson(
     });
     const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
     return { status: res.status, json };
-  } catch {
-    return { status: 0, json: {} };
+  } catch (error) {
+    // status 0 stays the transport sentinel, but keep the cause: callers can now
+    // tell the operator why the request never reached the proxy (#2698).
+    return {
+      status: 0,
+      json: {},
+      transportError: error instanceof Error ? error.message : String(error),
+    };
   }
 }
 
@@ -115,18 +135,43 @@ export async function resolveBaseUrl(deps: AccountDeps): Promise<string | null>
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
-export function proxyUnreachable(): number {
+export function proxyUnreachable(transportError?: string): number {
   console.error("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  // Naming the transport cause distinguishes "nothing is listening" from a refused
+  // or reset connection, which is what made #2696-class breakage undiagnosable.
+  if (transportError) console.error(`reason: ${transportError}`);
   return 1;
 }
 
-export function apiError(json: Record<string, unknown>, fallback: string): number {
-  const message = typeof json.error === "string" ? json.error : fallback;
-  console.error(`Error: ${message}`);
+function accountStringField(json: Record<string, unknown>, key: string): string | undefined {
+  const value = json[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Report a failed management call from the account family.
+ *
+ * `reason` and `hint` are the actionable fields on a refusal — the management plane
+ * sets both on a 503, and several routes return `reason` with no `error` key at all,
+ * which used to print only the generic fallback (#2698).
+ *
+ * `status` selects the exit code so the account client speaks the same vocabulary as
+ * runtime-api.ts: 4 for not-found, 5 for conflict, 1 otherwise. Previously every
+ * failure exited 1, so a script could not distinguish a missing account from a
+ * concurrent mutation.
+ */
+export function apiError(json: Record<string, unknown>, fallback: string, status: number): number {
+  const primary = accountStringField(json, "error") ?? fallback;
+  const lines = [`Error: ${primary}`];
+  const reason = accountStringField(json, "reason");
+  if (reason && reason !== primary) lines.push(`reason: ${reason}`);
+  const hint = accountStringField(json, "hint");
+  if (hint && hint !== primary) lines.push(`hint: ${hint}`);
+  for (const line of lines) console.error(line);
   if (json.cleanupRequired === true) {
     console.error("Warning: native-login staging cleanup is still required; run 'ocx account main doctor'.");
   }
-  return 1;
+  return status === 404 ? 4 : status === 409 ? 5 : 1;
 }
 
 export interface FamilyRows {
@@ -134,19 +179,27 @@ export interface FamilyRows {
   activeId: string | null;
   autoSwitchThreshold?: number;
   /** HTTP status for a completed family read, including failures. */
-  status?: number;
+  status: number;
   /** Set when the family endpoint returned an error. */
   errorJson?: Record<string, unknown>;
   networkDown?: boolean;
+  /** Transport cause when `networkDown` is set. Callers must forward this to `proxyUnreachable`. */
+  transportError?: string;
 }
 
 export interface CodexQuotaDto {
-  fiveHourPercent?: number;
-  fiveHourResetAt?: number;
   weeklyPercent?: number;
   monthlyPercent?: number;
   weeklyResetAt?: number;
   monthlyResetAt?: number;
+  /**
+   * Five-hour window, as the per-account provider probe reports it
+   * (`/api/oauth/accounts?quota=1`). Distinct from `shortPercent`, which is the Codex pool's
+   * self-declared burst window; the two surfaces name the same idea differently and both reach
+   * this DTO.
+   */
+  fiveHourPercent?: number;
+  fiveHourResetAt?: number;
   /** Sub-day burst window, when upstream declares one (#1791). */
   shortPercent?: number;
   shortResetAt?: number;
@@ -160,6 +213,8 @@ export interface ProviderQuotaWindowDto {
 }
 
 export interface ProviderQuotaDto extends CodexQuotaDto {
+  fiveHourPercent?: number;
+  fiveHourResetAt?: number;
   customWindows?: ProviderQuotaWindowDto[];
   updatedAt?: number;
 }
@@ -182,11 +237,18 @@ interface CodexAccountDto {
   needsReauth?: boolean;
   priority?: number;
   quota?: CodexQuotaDto | null;
+  paused?: boolean;
 }
 
 function projectQuota(quota: CodexQuotaDto | null | undefined): CodexQuotaDto | null {
   if (!quota) return null;
   const projected: CodexQuotaDto = {};
+  // `fiveHourPercent`/`fiveHourResetAt` were declared on the DTO and read by two renderers
+  // -- `quotaText`'s `quota.fiveHourPercent ?? quota.shortPercent` (account.ts:89) and
+  // `quotaParts` (account-extended.ts:275) -- but omitted from this whitelist, so the first
+  // operand was unreachable and a 5h-only account rendered as unknown (#2703). A projection
+  // that silently drops a field its own type declares is worse than one that never had it:
+  // the type checks, the renderer looks correct, and only the output is wrong.
   for (const key of ["fiveHourPercent", "fiveHourResetAt", "weeklyPercent", "monthlyPercent", "weeklyResetAt", "monthlyResetAt", "shortPercent", "shortResetAt", "shortWindowSeconds"] as const) {
     if (typeof quota[key] === "number" && Number.isFinite(quota[key])) projected[key] = quota[key];
   }
@@ -197,6 +259,7 @@ export async function fetchCodexRows(
   deps: AccountDeps,
   baseUrl: string,
   forceRefresh = false,
+  includeQuota = forceRefresh,
 ): Promise<FamilyRows> {
   const accountsPath = `/api/codex-auth/accounts${forceRefresh ? "?refresh=1" : ""}`;
   const [accountsRes, activeRes] = await Promise.all([
@@ -210,7 +273,13 @@ export async function fetchCodexRows(
     return { rows: [], activeId: null, status: activeRes.status, errorJson: activeRes.json };
   }
   if (accountsRes.status === 0 || activeRes.status === 0) {
-    return { rows: [], activeId: null, status: 0, networkDown: true };
+    return {
+      rows: [],
+      activeId: null,
+      status: 0,
+      networkDown: true,
+      transportError: accountsRes.transportError ?? activeRes.transportError,
+    };
   }
   const activeId = typeof activeRes.json.activeCodexAccountId === "string"
     ? activeRes.json.activeCodexAccountId
@@ -229,7 +298,8 @@ export async function fetchCodexRows(
     active: a.id === activeId,
     needsReauth: a.needsReauth,
     priority: typeof a.priority === "number" ? a.priority : 0,
-    ...(forceRefresh ? { quota: projectQuota(a.quota) } : {}),
+    paused: a.paused === true,
+    ...(includeQuota ? { quota: projectQuota(a.quota) } : {}),
   }));
   return { rows, activeId, autoSwitchThreshold, status: 200 };
 }
@@ -256,7 +326,9 @@ async function fetchOAuthRows(
     ? `?provider=${encodeURIComponent(name)}&quota=1${quota.refresh ? "&refresh=1" : ""}`
     : `?provider=${encodeURIComponent(name)}`;
   const res = await apiJson(deps, baseUrl, "GET", `/api/oauth/accounts${query}`);
-  if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true };
+  if (res.status === 0) {
+    return { rows: [], activeId: null, status: 0, networkDown: true, transportError: res.transportError };
+  }
   if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json };
   const activeId = typeof res.json.activeAccountId === "string" ? res.json.activeAccountId : null;
   const accounts = Array.isArray(res.json.accounts) ? res.json.accounts as OAuthAccountDto[] : [];
@@ -283,7 +355,9 @@ interface ApiKeyDto {
 
 async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string): Promise<FamilyRows> {
   const res = await apiJson(deps, baseUrl, "GET", `/api/providers/keys?name=${encodeURIComponent(name)}`);
-  if (res.status === 0) return { rows: [], activeId: null, status: 0, networkDown: true };
+  if (res.status === 0) {
+    return { rows: [], activeId: null, status: 0, networkDown: true, transportError: res.transportError };
+  }
   if (res.status !== 200) return { rows: [], activeId: null, status: res.status, errorJson: res.json };
   const activeId = typeof res.json.activeId === "string" ? res.json.activeId : null;
   const keys = Array.isArray(res.json.keys) ? res.json.keys as ApiKeyDto[] : [];
@@ -305,7 +379,7 @@ export function fetchRows(
   type: AccountType,
   quota?: { refresh?: boolean },
 ): Promise<FamilyRows> {
-  if (type === "codex") return fetchCodexRows(deps, baseUrl);
+  if (type === "codex") return fetchCodexRows(deps, baseUrl, Boolean(quota?.refresh), quota !== undefined);
   if (type === "oauth") return fetchOAuthRows(deps, baseUrl, name, quota);
   return fetchKeyRows(deps, baseUrl, name);
 }
@@ -314,8 +388,11 @@ export async function fetchProviderQuotaReport(
   deps: AccountDeps,
   baseUrl: string,
   name: string,
-): Promise<{ status: number; report: ProviderQuotaReportDto | null; errorJson?: Record<string, unknown> }> {
+): Promise<{ status: number; report: ProviderQuotaReportDto | null; errorJson?: Record<string, unknown>; transportError?: string }> {
   const res = await apiJson(deps, baseUrl, "GET", "/api/provider-quotas?refresh=1");
+  if (res.status === 0) {
+    return { status: 0, report: null, errorJson: res.json, transportError: res.transportError };
+  }
   if (res.status !== 200) return { status: res.status, report: null, errorJson: res.json };
   const reports = Array.isArray(res.json.reports) ? res.json.reports as ProviderQuotaReportDto[] : [];
   return { status: 200, report: reports.find(report => report?.provider === name) ?? null };

package/src/cli/account-extended.ts

@@ -40,6 +40,11 @@ const EXTENDED_USAGE = `Usage:
   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]
@@ -232,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;
 }
 
@@ -249,24 +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;
-  const fiveHourPercent = quota?.fiveHourPercent ?? quota?.shortPercent;
-  const fiveHourResetAt = quota?.fiveHourResetAt ?? quota?.shortResetAt;
-  if (!quota || (quota.weeklyPercent === undefined && quota.monthlyPercent === undefined && fiveHourPercent === undefined)) {
-    parts.push("quota: unknown");
-  } else {
-    if (fiveHourPercent !== undefined) {
-      parts.push(`5h ${fiveHourPercent}%`);
-      const fiveHourReset = resetIso(fiveHourResetAt);
-      if (fiveHourReset) parts.push(`resets ${fiveHourReset}`);
-    }
-    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(" ");
 }
@@ -279,7 +274,7 @@ function quotaParts(quota: ProviderQuotaDto): string[] {
     const reset = resetIso(resetAt);
     if (reset) parts.push(`resets ${reset}`);
   };
-  add("5h", quota.fiveHourPercent ?? quota.shortPercent, quota.fiveHourResetAt ?? quota.shortResetAt);
+  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);
@@ -332,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;
@@ -367,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));
@@ -466,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
@@ -543,7 +538,7 @@ export async function cmdImport(args: string[], deps: AccountDeps): Promise<numb
     clearTimeout(timer);
   }
   if (response.status === 0) {
-    if (!timedOut) return proxyUnreachable();
+    if (!timedOut) return proxyUnreachable(response.transportError);
     console.error(`Error: import_timeout after ${importTimeoutMs}ms`);
     return 1;
   }
@@ -596,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}`);
@@ -687,8 +682,8 @@ export async function cmdPriority(args: string[], deps: AccountDeps): Promise<nu
   }
 
   const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/priority", { id, priority });
-  if (response.status === 0) return proxyUnreachable();
-  if (response.status !== 200) return apiError(response.json, `failed to set selection order for ${requestedId}`);
+  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(
@@ -710,6 +705,237 @@ export async function cmdPriority(args: string[], deps: AccountDeps): Promise<nu
   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();
@@ -735,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}`);