@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/account-key-quota.ts

@@ -0,0 +1,118 @@
+/** Public API-key quota projection; private probe identity stays on the server. */
+import { parseQuotaFailureCode, type AccountQuotaFields, type ProviderQuota, type ProviderQuotaWindow, type ProviderQuotaCreditsUsd } from "../providers/quota-types";
+import { terminalSafeText } from "./runtime-api";
+import type { AccountRow, FamilyRows } from "./account-api";
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Malformed API-key quota response.");
+  return value as Record<string, unknown>;
+}
+function finite(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("Malformed API-key quota response.");
+  return value;
+}
+function optionalString(row: Record<string, unknown>, key: string): string | undefined {
+  if (row[key] === undefined) return undefined;
+  if (typeof row[key] !== "string") throw new Error("Malformed API-key quota response.");
+  return row[key];
+}
+function optionalBoolean(row: Record<string, unknown>, key: string): boolean | undefined {
+  if (row[key] === undefined) return undefined;
+  if (typeof row[key] !== "boolean") throw new Error("Malformed API-key quota response.");
+  return row[key];
+}
+function windowProjection(value: unknown): ProviderQuotaWindow {
+  const row = record(value);
+  const label = optionalString(row, "label");
+  if (label === undefined) throw new Error("Malformed API-key quota response.");
+  const result: ProviderQuotaWindow = { label, percent: finite(row.percent) };
+  if (row.resetAt !== undefined) result.resetAt = finite(row.resetAt);
+  if (row.passiveObservedAt !== undefined) result.passiveObservedAt = finite(row.passiveObservedAt);
+  if (row.scope !== undefined) {
+    if (row.scope !== "model") throw new Error("Malformed API-key quota response.");
+    result.scope = row.scope;
+  }
+  if (row.rejected !== undefined) {
+    if (row.rejected !== true) throw new Error("Malformed API-key quota response.");
+    result.rejected = true;
+  }
+  return result;
+}
+function creditsProjection(value: unknown): ProviderQuotaCreditsUsd {
+  const row = record(value);
+  const result: ProviderQuotaCreditsUsd = {
+    used: finite(row.used), limit: finite(row.limit), remaining: finite(row.remaining), percent: finite(row.percent),
+  };
+  if (row.expiresAt !== undefined) result.expiresAt = finite(row.expiresAt);
+  const unlimited = optionalBoolean(row, "unlimited");
+  if (unlimited !== undefined) result.unlimited = unlimited;
+  return result;
+}
+function quotaProjection(value: unknown): ProviderQuota | null {
+  if (value === null) return null;
+  const row = record(value);
+  const result: ProviderQuota = { updatedAt: finite(row.updatedAt) };
+  for (const key of ["fiveHourPercent", "fiveHourResetAt", "weeklyPercent", "weeklyResetAt", "monthlyPercent", "monthlyResetAt", "kiroCreditsUsed", "kiroCreditsLimit"] as const) {
+    if (row[key] !== undefined) result[key] = finite(row[key]);
+  }
+  if (row.customWindows !== undefined) {
+    if (!Array.isArray(row.customWindows)) throw new Error("Malformed API-key quota response.");
+    result.customWindows = row.customWindows.map(windowProjection);
+  }
+  if (row.creditsUsd !== undefined) result.creditsUsd = creditsProjection(row.creditsUsd);
+  return result;
+}
+
+/** Only opt-in reads use the strict DTO boundary; legacy cheap lists retain their contract. */
+export function projectApiKeyQuotaRows(value: unknown, provider: string): FamilyRows {
+  const body = record(value);
+  if (!Array.isArray(body.keys) || (body.activeId !== null && typeof body.activeId !== "string")) {
+    throw new Error("Malformed API-key quota response.");
+  }
+  const activeId = body.activeId;
+  const rows: AccountRow[] = body.keys.map(value => {
+    const row = record(value);
+    const id = optionalString(row, "id");
+    if (!id) throw new Error("Malformed API-key quota response.");
+    const quotaMode = row.quotaMode;
+    if (quotaMode === undefined) throw new Error("API-key quota is unverified: server did not report quotaMode. Update the proxy and retry.");
+    if (quotaMode !== "probe" && quotaMode !== "passive" && quotaMode !== "unsupported") throw new Error("Malformed API-key quota response.");
+    const fields: AccountQuotaFields = { quotaMode };
+    if (row.quota !== undefined) fields.quota = quotaProjection(row.quota);
+    const unavailable = optionalBoolean(row, "quotaUnavailable");
+    if (unavailable !== undefined) fields.quotaUnavailable = unavailable;
+    if (row.quotaFailure !== undefined) {
+      const failure = parseQuotaFailureCode(row.quotaFailure);
+      if (!failure) throw new Error("Malformed API-key quota response.");
+      if (unavailable === true) fields.quotaFailure = failure;
+    }
+    const masked = optionalString(row, "masked");
+    return { provider, type: "api-key", id, label: optionalString(row, "label") ?? masked,
+      masked, active: optionalBoolean(row, "active") ?? id === activeId, ...fields };
+  });
+  return { rows, activeId, status: 200 };
+}
+
+export function apiKeyQuotaText(row: AccountRow): string {
+  const mode = row.quotaMode;
+  if (!mode) return "unverified";
+  if (mode === "unsupported") return "unsupported";
+  if (row.quotaUnavailable) return `${mode}: unavailable${row.quotaFailure ? ` (${row.quotaFailure})` : ""}`;
+  const quota = row.quota;
+  if (!quota) return `${mode}: not measured`;
+  const parts: string[] = [];
+  for (const [label, percent] of [["5h", quota.fiveHourPercent], ["wk", quota.weeklyPercent], ["mo", quota.monthlyPercent]] as const) {
+    if (percent !== undefined) parts.push(`${label} ${percent}%`);
+  }
+  for (const window of quota.customWindows ?? []) {
+    // Labels are upstream text: keep terminal controls out of the human table.
+    const label = terminalSafeText(window.label);
+    parts.push(`${label} ${window.percent}%${window.rejected ? " (rejected)" : ""}`);
+  }
+  if (quota.creditsUsd) {
+    const c = quota.creditsUsd;
+    parts.push(`USD ${c.used}/${c.unlimited ? "unlimited" : c.limit} used; ${c.remaining} remaining (${c.percent}%)`);
+  }
+  if (quota.kiroCreditsUsed !== undefined || quota.kiroCreditsLimit !== undefined) parts.push(`credits ${quota.kiroCreditsUsed ?? "?"}/${quota.kiroCreditsLimit ?? "?"}`);
+  return `${mode}: ${parts.join("; ") || "not measured"}`;
+}

package/src/cli/account-main.ts

@@ -1,4 +1,5 @@
 import { isAbsolute } from "node:path";
+import { redactSecretArgs } from "./secret-args";
 import { codexExecInvocation } from "../codex/exec-invocation";
 import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 import type { ResolveDeps, SpawnInvocation } from "../lib/win-exec";
@@ -53,7 +54,7 @@ function flag(args: string[], name: string): boolean {
 }
 
 function reject(args: string[]): number {
-  if (args.length > 0) console.error(`Unexpected argument(s): ${args.join(", ")}`);
+  if (args.length > 0) console.error(`Unexpected argument(s): ${redactSecretArgs(args).join(", ")}`);
   console.error(USAGE);
   return 1;
 }
@@ -64,8 +65,10 @@ function effectiveCodexHome(result: Record<string, unknown>): string {
     : "the effective CODEX_HOME";
 }
 
+const EMPTY_PROFILES_NOTES = ["No native main login profiles registered.", "Next: ocx account main add <label>"];
+
 function printProfiles(profiles: PublicProfile[]): void {
-  if (profiles.length === 0) { console.log("No native main login profiles registered."); return; }
+  if (profiles.length === 0) { for (const note of EMPTY_PROFILES_NOTES) console.log(note); return; }
   const rows = profiles.map(profile => [profile.state === "active" ? "*" : " ", profile.label, profile.id, profile.identityHint]);
   const header = ["", "LABEL", "PROFILE ID", "IDENTITY"];
   const widths = header.map((value, index) => Math.max(value.length, ...rows.map(row => row[index]!.length)));
@@ -272,8 +275,12 @@ export async function cmdNativeMainAccount(args: string[], deps: AccountDeps): P
     const result = await apiJson(deps, baseUrl, "GET", path);
     if (result.status === 0) return proxyUnreachable(result.transportError);
     if (result.status !== 200) return apiError(result.json, `failed to ${sub} native profiles`, result.status);
-    if (wantsJson || sub === "doctor") console.log(JSON.stringify(result.json, null, 2));
-    else printProfiles(Array.isArray(result.json.profiles) ? result.json.profiles as PublicProfile[] : []);
+    const profiles = Array.isArray(result.json.profiles) ? result.json.profiles as PublicProfile[] : [];
+    if (wantsJson || sub === "doctor") console.log(JSON.stringify({
+      ...result.json,
+      ...(sub === "list" && profiles.length === 0 ? { notes: [...(Array.isArray(result.json.notes) ? result.json.notes : []), ...EMPTY_PROFILES_NOTES] } : {}),
+    }, null, 2));
+    else printProfiles(profiles);
     return 0;
   }
 

package/src/cli/account-next-actions.ts

@@ -0,0 +1,63 @@
+import type { AccountType } from "./account-api";
+import type { OAuthHealthLabel } from "../oauth/health";
+
+const HEALTH_LABELS: readonly OAuthHealthLabel[] = [
+  "Healthy", "Rate limited", "Quota limited", "Reauthentication required",
+  "Verification required", "Refresh failed", "Metadata mismatch", "Credential conflict", "Validation pending",
+];
+
+// Commands are hints, never executed. Admit only bounded, shell-safe selectors;
+// arbitrary server summaries/actions may contain credentials or terminal controls.
+function commandSelector(value: string): string | undefined {
+  return /^[A-Za-z0-9_][A-Za-z0-9_.:@/-]{0,199}$/.test(value) ? value : undefined;
+}
+
+/** Account label for recovery lines; ids that fail the selector allowlist are never echoed. */
+export function recoveryAccountLabel(id: string, display: string): string {
+  return commandSelector(id) ? display : "<unprintable id>";
+}
+
+export function emptyAccountNextAction(provider?: string, type?: AccountType): string {
+  const name = provider && commandSelector(provider);
+  if (!name) return "Next: ocx account login <provider> (see ocx help account login)";
+  return type === "api-key"
+    ? `Next: ocx account add-key ${name} (pipe the key from a human-controlled stdin source; see ocx help account add-key)`
+    : `Next: ocx account login ${name}`;
+}
+
+export function projectAccountHealth(
+  account: { healthLabel?: unknown },
+  provider: string,
+  id: string,
+): { health?: OAuthHealthLabel; healthAction?: string } {
+  const health = HEALTH_LABELS.find(label => label === account.healthLabel);
+  if (!health) return {};
+  const name = commandSelector(provider);
+  const selector = commandSelector(id);
+  const reauth = provider === "openai" && id === "__main__"
+    ? "ocx account main reauth --device"
+    : name && selector ? `ocx account reauth ${name} --id ${selector}` : "ocx help account reauth";
+  let healthAction: string | undefined;
+  switch (health) {
+    case "Reauthentication required":
+    case "Refresh failed":
+      healthAction = reauth;
+      break;
+    case "Verification required":
+      healthAction = `Verify the account with the provider in a browser, then run: ${reauth}`;
+      break;
+    case "Credential conflict":
+      healthAction = "Ensure only one proxy process writes the credential store, then run: ocx doctor";
+      break;
+    case "Validation pending":
+      healthAction = "Wait for quota recovery, then click Refresh quotas in the dashboard Codex account pool";
+      break;
+    case "Rate limited":
+      healthAction = "Wait for the rate-limit cooldown or use another eligible account";
+      break;
+    case "Quota limited":
+      healthAction = "Wait for quota recovery or use another eligible account";
+      break;
+  }
+  return { health, ...(healthAction ? { healthAction } : {}) };
+}

package/src/cli/account-policy-dto.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "../codex/account-id";
+import { parseAnthropicModelRoutes } from "../oauth/anthropic-model-routes";
+
+const text = z.string().max(4096);
+export const accountId = z.string().refine(id => id === MAIN_CODEX_ACCOUNT_ID || isValidCodexAccountId(id));
+export const threshold = z.number().int().min(0).max(100);
+const nullableThreshold = threshold.nullable();
+const row = z.object({
+  id: accountId, alias: text.optional(), autoSwitchThresholdOverride: nullableThreshold.optional(),
+  quota: z.object({ shortWindowSeconds: z.number().finite().optional(), shortResetAt: z.number().finite().optional(),
+    weeklyResetAt: z.number().finite().optional() }).nullable().optional(),
+  quotaAutoRefresh: z.object({ fiveHourAvailable: z.boolean(), weeklyAvailable: z.boolean(),
+    fiveHourEnabled: z.boolean(), weeklyEnabled: z.boolean() }).optional(),
+});
+export const rosterSchema = z.object({ accounts: z.array(row).refine(rows => new Set(rows.map(r => r.id)).size === rows.length) });
+const fields = z.enum(["enabled", "strategy", "stickyLimit", "autoSwitchThreshold", "quotaWindow", "maxConcurrentPerAccount", "routes", "nativeMessages"]);
+export const poolSchema = z.object({
+  provider: z.string(), kind: z.enum(["codex", "anthropic", "generic"]), supported: z.array(fields),
+  enabled: z.boolean().nullable(), enabledEffective: z.boolean(),
+  strategy: z.enum(["quota", "round-robin", "fill-first", "reset-first", "least-loaded"]).nullable(),
+  stickyLimit: z.number().int().min(1).max(100).nullable(), autoSwitchThreshold: nullableThreshold,
+  quotaWindow: z.enum(["five-hour", "weekly", "max-utilization"]).nullable(),
+  maxConcurrentPerAccount: z.number().int().min(1).max(100).nullable(),
+  // Anthropic native Messages preference; null for kinds that do not honour it. Optional for older servers.
+  nativeMessages: z.boolean().nullable().optional(),
+  routes: z.unknown().transform((value, ctx) => {
+    if (value === null) return null;
+    const parsed = parseAnthropicModelRoutes(value);
+    if (parsed.ok) return parsed.routes;
+    ctx.addIssue({ code: "custom", message: "Invalid routes" });
+    return z.NEVER;
+  }),
+  // The server returns a static validation diagnostic here; never forward its text.
+  routesError: z.string().transform(() => "Stored model routes are invalid.").optional(), inert: z.boolean().optional(),
+  // Saved, but post-save bookkeeping failed. Only this fixed code is projected.
+  warning: z.literal("config_bookkeeping_failed").optional(),
+});
+export const thresholdReceipt = z.object({ ok: z.literal(true), id: accountId,
+  autoSwitchThresholdOverride: nullableThreshold, autoSwitchThreshold: threshold });
+export const creditReceipt = z.object({ ok: z.literal(true), id: accountId, creditsAfterLimit: z.boolean() });
+export const creditAllReceipt = z.object({ ok: z.literal(true), all: z.boolean(),
+  ids: z.array(accountId).refine(ids => new Set(ids).size === ids.length) });
+const window = z.enum(["five_hour", "seven_day", "seven_day_overage_included"]);
+// The server preserves any Date.parse-compatible timestamp; do not narrow it to Z-only ISO.
+const date = text.refine(value => !Number.isNaN(Date.parse(value))).nullable();
+const grantId = z.string().regex(/^[a-z0-9_-]{1,40}$/);
+const grant = z.object({ id: grantId, label: text, resetsTotal: z.number().int().nonnegative(),
+  resetsLeft: z.number().int().nonnegative(), startsAt: date, endsAt: date, clears: z.array(window),
+  paused: z.boolean(), usableNow: z.boolean(), useRequiresLimit: z.boolean(),
+  percentUsed: z.object({ five_hour: threshold.optional(), seven_day: threshold.optional(),
+    seven_day_overage_included: threshold.optional() }),
+}).refine(value => value.resetsLeft <= value.resetsTotal);
+export const grantsSchema = z.object({ accountId: text.min(1), eligible: z.boolean(),
+  ineligibleReason: z.enum(["config_off", "tier", "seat", "mobile", "surface", "cli_version", "no_grant", "tenure", "other_experiment", "unavailable", "unknown"]).nullable(),
+  atLimit: z.boolean(), grants: z.array(grant).refine(values => new Set(values.map(value => value.id)).size === values.length), nextGrantId: grantId.nullable(), weeklyResetsAt: date, cooldownUntil: date,
+  pendingOperation: z.object({ operationId: z.string().uuid(), grantId, createdAt: z.number().finite(),
+    retryableUntil: z.number().finite() }).nullable(), journalAvailable: z.boolean(),
+});
+export function parseDto<T>(schema: z.ZodType<T>, value: unknown): T {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) throw new Error("Invalid account policy response");
+  return parsed.data;
+}
+export function record(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid account policy response");
+  return value as Record<string, unknown>;
+}

package/src/cli/account-policy.ts

@@ -0,0 +1,167 @@
+import { MAIN_CODEX_ACCOUNT_ID } from "../codex/account-id";
+import { isValidProviderName } from "../config/provider-name";
+import { resolveCodexAccountTargetFromRows } from "./account-target";
+import { runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import { creditAllReceipt, creditReceipt, grantsSchema, parseDto, poolSchema, record,
+  rosterSchema, threshold, thresholdReceipt } from "./account-policy-dto";
+import { CliUsageError, RuntimeApiError, printData, runtimeBaseUrl, runtimeRequest, summaryLines,
+  takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+type Subcommand = "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants";
+const USAGE = "Usage: ocx account pool <provider> [--enabled on|off] [--threshold 0-100] [--strategy NAME] [--sticky 1-100] [--quota-window NAME] [--json]\n"
+  + "       ocx account auto-switch openai <status|on|off|inherit|threshold N> --account ID [--json]\n"
+  + "       ocx account credits openai <ID on|off|--all on|off> [--json]\n"
+  + "       ocx account quota-activation openai ID --window <fiveHour|weekly> <on|off> [--json]\n"
+  + "       ocx account anthropic-reset-grants [ID] [--json]";
+const READ_ERRORS = { no_account: "No matching Anthropic OAuth account.", auth_failed: "Sign in to this Anthropic account again.",
+  upstream_unavailable: "Anthropic did not return the reset-grant status.", ledger_unavailable: "The reset journal is unavailable.",
+  ledger_busy: "The reset journal is busy. No grant was consumed." };
+function usage(): never { throw new CliUsageError("Invalid account policy arguments.", USAGE); }
+function onOff(value: string | undefined): boolean { if (value !== "on" && value !== "off") usage(); return value === "on"; }
+function integer(value: string, min: number): number {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > 100) usage();
+  return Number(value);
+}
+function selector(value: string | undefined): string {
+  if (!value || value.trim() !== value || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value) || value.startsWith("-")) usage();
+  return value;
+}
+function option(args: string[], name: string): string | undefined { return takeOptionWithSyntax(args, name)?.value; }
+function done(args: string[]): void { if (args.length) usage(); }
+async function request(path: string, deps: RuntimeApiDeps, body?: Record<string, unknown>): Promise<unknown> {
+  return runtimeRequest(path, { redirect: "error", ...(body === undefined ? {} : {
+    method: "PUT", headers: { "Content-Type": "application/json" }, body: serializeManagementJson(body),
+  }) }, deps);
+}
+async function roster(deps: RuntimeApiDeps) {
+  return parseDto(rosterSchema, await request("/api/codex-auth/accounts", deps)).accounts;
+}
+async function target(deps: RuntimeApiDeps, requested: string) {
+  const rows = await roster(deps);
+  const selected = resolveCodexAccountTargetFromRows(rows, requested);
+  if (!("id" in selected)) {
+    if ("error" in selected && selected.kind === "not_found") throw new RuntimeApiError("Account not found", 404, null);
+    throw new CliUsageError("Account selector is reserved, ambiguous or unavailable. Use a unique account ID.");
+  }
+  return { id: selected.id, rows };
+}
+function output(data: Record<string, unknown>, json: boolean, note?: string): number {
+  printData(data, json, [...(note ? [note] : []), ...summaryLines(data)]);
+  return 0;
+}
+function requireEqual(actual: unknown, expected: unknown): void { if (actual !== expected) throw new Error("Unverified account policy result"); }
+
+async function pool(args: string[], json: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const provider = selector(args.shift()).toLowerCase();
+  if (!isValidProviderName(provider)) usage();
+  const patch: Record<string, unknown> = {};
+  const enabled = option(args, "--enabled"), limit = option(args, "--threshold"), sticky = option(args, "--sticky");
+  const strategy = option(args, "--strategy"), window = option(args, "--quota-window");
+  if (enabled !== undefined) patch.enabled = onOff(enabled);
+  if (limit !== undefined) patch.autoSwitchThreshold = integer(limit, 0);
+  if (sticky !== undefined) patch.stickyLimit = integer(sticky, 1);
+  if (strategy !== undefined) {
+    if (!["quota", "round-robin", "fill-first", ...(provider === "openai" ? ["reset-first"] : []),
+      ...(provider === "kiro" ? ["least-loaded"] : [])].includes(strategy)) usage();
+    patch.strategy = strategy;
+  }
+  if (window !== undefined) {
+    if (provider !== "anthropic" || !["five-hour", "weekly", "max-utilization"].includes(window)) usage();
+    patch.quotaWindow = window;
+  }
+  done(args);
+  const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+  const before = parseDto(poolSchema, await request(`/api/pool/settings?provider=${encodeURIComponent(provider)}`, pinned));
+  requireEqual(before.provider, provider);
+  requireEqual(before.kind, provider === "openai" ? "codex" : provider === "anthropic" ? "anthropic" : "generic");
+  if (Object.keys(patch).some(key => !(before.supported as string[]).includes(key))
+    || (before.kind === "codex" && enabled !== undefined)) throw new CliUsageError("The selected pool does not support a requested field.");
+  if (!Object.keys(patch).length) return output(before, json);
+  const after = parseDto(poolSchema, await request("/api/pool/settings", pinned, { provider, ...patch }));
+  requireEqual(after.provider, provider); requireEqual(after.kind, before.kind);
+  for (const [key, value] of Object.entries(patch)) requireEqual(record(after)[key], value);
+  return output(after, json, after.warning === "config_bookkeeping_failed"
+    ? "Pool policy saved, but configuration bookkeeping failed. Re-read the pool policy to confirm the current state."
+    : "Pool policy saved.");
+}
+
+async function codex(sub: "auto-switch" | "credits" | "quota-activation", args: string[], json: boolean, deps: RuntimeApiDeps): Promise<number> {
+  if (args.shift() !== "openai") usage();
+  let requested: string | undefined, action: string | undefined, all = false, window: string | undefined;
+  let value: number | null | undefined, enabled: boolean | undefined;
+  if (sub === "auto-switch") {
+    requested = selector(option(args, "--account")); action = args.shift();
+    if (action === "threshold") value = integer(args.shift() ?? "", 0);
+    else if (action === "on") value = 80;
+    else if (action === "off") value = 0;
+    else if (action === "inherit") value = null;
+    else if (action !== "status") usage();
+  } else if (sub === "credits") {
+    all = takeFlag(args, "--all");
+    if (!all) requested = selector(args.shift());
+    enabled = onOff(args.shift());
+  } else {
+    window = option(args, "--window");
+    if (window !== "fiveHour" && window !== "weekly") usage();
+    requested = selector(args.shift()); enabled = onOff(args.shift());
+  }
+  done(args);
+  const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+  if (all) {
+    const result = parseDto(creditAllReceipt, await request("/api/codex-auth/accounts/credits", pinned, { all: enabled }));
+    requireEqual(result.all, enabled);
+    if ((!enabled && result.ids.length !== 0) || (enabled && !result.ids.includes(MAIN_CODEX_ACCOUNT_ID))) throw new Error("Invalid credit scope");
+    return output(result, json, enabled ? "Paid-credit use enabled for the returned current accounts." : "Paid-credit use disabled for all accounts.");
+  }
+  const { id, rows } = await target(pinned, requested!);
+  if (sub === "auto-switch") {
+    if (action === "status") {
+      const selected = rows.find(row => row.id === id);
+      const override = selected?.autoSwitchThresholdOverride;
+      if (override === undefined) throw new Error("Missing account threshold evidence");
+      const active = record(await request("/api/codex-auth/active", pinned));
+      const effective = override ?? parseDto(threshold, active.autoSwitchThreshold);
+      return output({ ok: true, id, autoSwitchThresholdOverride: override, autoSwitchThreshold: effective }, json);
+    }
+    const result = parseDto(thresholdReceipt, await request("/api/codex-auth/auto-switch", pinned, { id, threshold: value }));
+    requireEqual(result.id, id); requireEqual(result.autoSwitchThresholdOverride, value);
+    if (value !== null) requireEqual(result.autoSwitchThreshold, value);
+    return output(result, json, "Account threshold saved.");
+  }
+  if (sub === "credits") {
+    const result = parseDto(creditReceipt, await request("/api/codex-auth/accounts/credits", pinned, { id, creditsAfterLimit: enabled }));
+    requireEqual(result.id, id); requireEqual(result.creditsAfterLimit, enabled);
+    return output(result, json, enabled ? "Paid-credit use enabled for this account." : "Paid-credit use disabled for this account.");
+  }
+  const reply = record(await request("/api/settings", pinned, { codexQuotaAutoRefresh: { id, window, enabled } }));
+  requireEqual(reply.ok, true);
+  const settings = record(reply.codexQuotaAutoRefresh);
+  // Disabling the last window removes the settings entry, by the existing server contract.
+  const setting = Object.hasOwn(settings, id) ? record(settings[id]) : { fiveHour: false, weekly: false };
+  if (typeof setting.fiveHour !== "boolean" || typeof setting.weekly !== "boolean") throw new Error("Invalid window settings");
+  requireEqual(setting[window!], enabled);
+  const selected = (await roster(pinned)).find(row => row.id === id);
+  if (!selected || selected.quota === undefined) throw new Error("Missing quota evidence after save");
+  const available = selected.quotaAutoRefresh
+    ? selected.quotaAutoRefresh[window === "fiveHour" ? "fiveHourAvailable" : "weeklyAvailable"]
+    : window === "fiveHour" ? selected.quota?.shortWindowSeconds === 18000 && typeof selected.quota.shortResetAt === "number"
+      : typeof selected.quota?.weeklyResetAt === "number";
+  return output({ ok: true, id, window, enabled: setting[window!], available }, json, "Quota activation setting saved; scheduled refresh is separate.");
+}
+
+/** New policy verbs use strict runtime identity; legacy pool-scope auto-switch stays in its existing owner. */
+export async function handleAccountPolicyCommand(sub: Subcommand, args: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const rest = [...args], json = takeFlag(rest, "--json");
+    if (rest.includes("--json")) usage();
+    if (sub === "pool") return pool(rest, json, deps);
+    if (sub !== "anthropic-reset-grants") return codex(sub, rest, json, deps);
+    const id = rest.length ? selector(rest.shift()) : undefined;
+    done(rest);
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const result = parseDto(grantsSchema, await request(`/api/anthropic/reset-grants${id ? `?accountId=${encodeURIComponent(id)}` : ""}`, pinned));
+    if (id) requireEqual(result.accountId, id);
+    return output(result, json, "Reset-grant status read; no grant was consumed.");
+  }, READ_ERRORS);
+}

package/src/cli/account-target.ts

@@ -46,6 +46,14 @@ export async function resolveCodexAccountTarget(
   const accounts = (Array.isArray(res.json.accounts) ? res.json.accounts : [])
     .filter((entry): entry is { id: string; alias?: unknown } =>
       typeof entry === "object" && entry !== null && typeof (entry as { id?: unknown }).id === "string");
+  return resolveCodexAccountTargetFromRows(accounts, requested);
+}
+
+/** Shared precedence only; new policy callers validate their target roster before calling. */
+export function resolveCodexAccountTargetFromRows(
+  accounts: readonly { id: string; alias?: unknown }[], requested: string,
+): Exclude<CodexAccountTarget, { networkDown: true }> {
+  if (requested === MAIN_ALIAS || requested === MAIN_CODEX_ACCOUNT_ID) return { id: MAIN_CODEX_ACCOUNT_ID };
   if (accounts.some(account => account.id === requested)) return { id: requested };
   if (isReservedCodexAccountWord(requested)) {
     return { error: `"${requested}" is reserved; it clears the selection with \`ocx account use\` and names no account`, kind: "reserved" };

package/src/cli/account.ts

@@ -1,4 +1,7 @@
 /** `ocx account` — list and switch provider credentials (issue #180). */
+import { apiKeyQuotaText } from "./account-key-quota";
+import { redactSecretArgs } from "./secret-args";
+import { emptyAccountNextAction, recoveryAccountLabel } from "./account-next-actions";
 import { loadConfig } from "../config";
 import { explainCodexUseOutcome, reportCodexAccountTargetError, resolveCodexUseTarget } from "./account-target";
 import { providerCodexAccountMode } from "../providers/registry";
@@ -63,7 +66,11 @@ const ACCOUNT_USAGE = `Usage:
   ocx account add-key <provider> [--label <label>] [--json]
   ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]
   ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]
-  ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
+  ocx account login <provider> [--id <account-id>] [--reauth] [--open-browser on|off] [--add-account on|off] [--code -] [--no-wait] [--json]
+  ocx account pool <provider> [--enabled on|off] [--threshold N] [--strategy NAME] [--sticky N] [--quota-window W] [--json]
+  ocx account credits openai <ID on|off|--all on|off> [--json]
+  ocx account quota-activation openai ID --window fiveHour|weekly <on|off> [--json]
+  ocx account anthropic-reset-grants [ID] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json] (--flow required for codex)
   ocx account reset-credits <account-id|main> [--consume --yes] [--json]
@@ -87,10 +94,12 @@ function consumeFlag(args: string[], flag: string): boolean {
 /** 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("-"));
+  const shown = redactSecretArgs(args);
+  // Flags plus redaction markers only: a stray positional may be a credential operand.
+  const unknown = shown.filter(a => a.startsWith("-") || a === "<redacted>");
   return unknown.length > 0
     ? `Unknown flag(s): ${unknown.join(", ")}`
-    : `Unexpected argument(s): ${args.join(", ")}`;
+    : `Unexpected argument(s): ${shown.join(", ")}`;
 }
 
 function candidateNames(config: OcxConfig): string {
@@ -110,11 +119,15 @@ function statusText(row: AccountRow): string {
   // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
   if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
-  if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) parts.push("needs-reauth");
+  if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) {
+    parts.push(row.needsReauthReason === "verify_account" ? "needs-reauth(verify)" : "needs-reauth");
+  }
   // A paused Kiro row already says "paused"; repeating it as a skip reason adds nothing.
   if (row.provider === "kiro" && row.autoSelectable === false && !(row.paused && row.skipReason === "paused"))
     parts.push(row.skipReason ? `not-auto-selected(${row.skipReason})` : "not-auto-selected");
   if (row.validationPending) parts.push("validation-pending");
+  if (row.health && row.health !== "Healthy" && !row.needsReauth && !row.validationPending) parts.push(row.health.toLowerCase());
+  if (row.creditsAfterLimit === true) parts.push("paid-credits: on");
   if (row.selectionExcludedReason === "plan_excluded") {
     parts.push(`not-auto-selected(plan=${row.selectionExcludedPlan ?? row.plan ?? "unknown"})`);
   }
@@ -132,6 +145,7 @@ function priorityText(row: AccountRow): string {
  * decides on before a long session. The full breakdown stays in `--json`.
  */
 function quotaText(row: AccountRow): string {
+  if (row.type === "api-key") return apiKeyQuotaText(row);
   if (row.quotaUnavailable) return row.quotaFailure ? `unavailable (${row.quotaFailure})` : "unavailable";
   const quota = row.quota;
   if (!quota) return "-";
@@ -165,7 +179,8 @@ export function formatAccountTable(rows: AccountRow[], withQuota = false): strin
   });
   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");
+  const actions = rows.flatMap(row => row.healthAction ? [`${row.provider} ${recoveryAccountLabel(row.id, displayId(row.id))}: ${row.health?.toLowerCase() ?? "needs attention"}. Next: ${row.healthAction}`] : []);
+  return [line(header), ...data.map(line), ...actions].join("\n");
 }
 
 async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
@@ -175,7 +190,9 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
   // stays a cheap local read (#2566). --refresh bypasses the server-side TTL.
   const wantsQuota = consumeFlag(rest, "--quota");
   const refreshQuota = consumeFlag(rest, "--refresh");
-  const name = rest.shift();
+  // An option-shaped token is never the provider: leave it for the leftover check so a
+  // credential option keeps its operand redacted.
+  const name = rest[0]?.startsWith("-") ? undefined : rest.shift();
   const leftover = leftoverArgsError(rest);
   if (leftover) {
     console.error(leftover);
@@ -235,7 +252,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
       return apiError(r.errorJson, `failed to list ${t.name}`, r.status);
     }
     if (r.rows.length === 0) {
-      if (showAll) notes.push(`${t.name}: no stored accounts or keys`);
+      if (showAll || name) notes.push(`${t.name}: no stored accounts or keys`, emptyAccountNextAction(t.name, t.type));
       continue;
     }
     rows.push(...r.rows);
@@ -250,6 +267,7 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     }
   }
 
+  if (rows.length === 0 && !name) notes.push("No stored accounts or keys.", emptyAccountNextAction());
   if (wantsJson) {
     console.log(JSON.stringify({ accounts: rows, notes }, null, 2));
     return 0;
@@ -262,7 +280,9 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
 
 async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = consumeFlag(rest, "--json");
-  const name = rest.shift();
+  // An option-shaped token is never the provider: leave it for the leftover check so a
+  // credential option keeps its operand redacted.
+  const name = rest[0]?.startsWith("-") ? undefined : rest.shift();
   const leftover = leftoverArgsError(rest);
   if (!name || leftover) {
     if (leftover) console.error(leftover);
@@ -363,7 +383,9 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
  * named `auto` cannot shadow the verb that returns the pool to automatic selection. */
 async function cmdClear(rest: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = consumeFlag(rest, "--json");
-  const name = rest.shift();
+  // An option-shaped token is never the provider: leave it for the leftover check so a
+  // credential option keeps its operand redacted.
+  const name = rest[0]?.startsWith("-") ? undefined : rest.shift();
   const leftover = leftoverArgsError(rest);
   if (!name || leftover) {
     if (leftover) console.error(leftover);
@@ -401,6 +423,12 @@ async function cmdClear(rest: string[], deps: AccountDeps): Promise<number> {
 export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promise<number> {
   const [sub, ...rest] = args;
   try {
+    if (["pool", "credits", "quota-activation", "anthropic-reset-grants"].includes(sub ?? "")
+      || (sub === "auto-switch" && rest[0]?.trim().toLowerCase() === "openai"
+        && rest.some(arg => arg === "--account" || arg.startsWith("--account=")))) {
+      const { handleAccountPolicyCommand } = await import("./account-policy");
+      return handleAccountPolicyCommand(sub as "pool" | "auto-switch" | "credits" | "quota-activation" | "anthropic-reset-grants", rest, deps);
+    }
     if (sub === "list") return await cmdList(rest, deps);
     if (sub === "history") {
       const { cmdAccountHistory } = await import("./account-history");