@bitkyc08/opencodex 2.77.0 → 2.78.0

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 {
@@ -117,6 +126,8 @@ function statusText(row: AccountRow): string {
   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"})`);
   }
@@ -134,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 "-";
@@ -167,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> {
@@ -177,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);
@@ -237,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);
@@ -252,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;
@@ -264,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);
@@ -365,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);
@@ -403,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");

package/src/cli/agent-runtime-settings.ts

@@ -0,0 +1,130 @@
+import { isValidVisionTimeoutMs } from "../vision/plan";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
+import { runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+import { projectSettingsApply } from "./settings-result";
+import { CliUsageError, desktopSwitchApplyReason, printData, runtimeBaseUrl, runtimeRequest,
+  takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boolean(args: string[], flag: string): boolean | undefined {
+  const value = takeOptionWithSyntax(args, flag)?.value;
+  if (value === undefined) return undefined;
+  if (["on", "true", "yes", "1", "enabled"].includes(value.toLowerCase())) return true;
+  if (["off", "false", "no", "0", "disabled"].includes(value.toLowerCase())) return false;
+  throw new CliUsageError(`${flag} must be on or off`);
+}
+function invalid(): never { throw new Error("Invalid agent settings receipt"); }
+
+/** Additive default-sync option; normalized server state, not a native-write claim. */
+export async function handleInjectionDefaults(argsInput: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argsInput];
+    if (args.shift() !== "set") throw new CliUsageError("--sync-codex-defaults requires agent injection set");
+    const wantsJson = takeFlag(args, "--json");
+    const sync = boolean(args, "--sync-codex-defaults");
+    const guidance = boolean(args, "--guidance");
+    const body: Record<string, unknown> = {};
+    for (const [flag, key] of [["--model", "model"], ["--effort", "effort"], ["--prompt", "prompt"]] as const) {
+      const value = takeOptionWithSyntax(args, flag)?.value;
+      if (value !== undefined) body[key] = value === "-" ? null : value;
+    }
+    if (sync === undefined || args.length) throw new CliUsageError("Provide --sync-codex-defaults on or off and supported injection options");
+    body.syncCodexSubagentDefaults = sync;
+    if (guidance !== undefined) body.multiAgentGuidanceEnabled = guidance;
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const value = await runtimeRequest("/api/injection-model", { method: "PUT", redirect: "error", body: serializeManagementJson(body) }, pinned);
+    if (!record(value) || value.ok !== true || typeof value.multiAgentGuidanceEnabled !== "boolean"
+      || typeof value.syncCodexSubagentDefaults !== "boolean"
+      || ["model", "effort", "prompt"].some(key => value[key] !== null && typeof value[key] !== "string")) invalid();
+    const data = { ok: true, multiAgentGuidanceEnabled: value.multiAgentGuidanceEnabled,
+      syncCodexSubagentDefaults: value.syncCodexSubagentDefaults, model: value.model, effort: value.effort, prompt: value.prompt };
+    printData(data, wantsJson, ["Injection settings saved.", `Guidance: ${data.multiAgentGuidanceEnabled}`,
+      `Effective default-sync setting: ${data.syncCodexSubagentDefaults}`]);
+    return 0;
+  });
+}
+
+/** New sidecar fields share the existing candidate normalization and partial PUT contract. */
+export async function handleSidecarRuntimeSettings(argsInput: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argsInput], section = args.shift();
+    if (section !== "web" && section !== "vision") throw new CliUsageError("Sidecar settings require web or vision");
+    const wantsJson = takeFlag(args, "--json");
+    const model = takeOptionWithSyntax(args, "--model")?.value;
+    const backend = takeOptionWithSyntax(args, "--backend")?.value;
+    const reasoning = takeOptionWithSyntax(args, "--reasoning")?.value;
+    const max = takeOptionWithSyntax(args, "--max-descriptions")?.value;
+    const timeout = takeOptionWithSyntax(args, "--timeout-ms")?.value;
+    const enabled = boolean(args, "--enabled");
+    const stream = boolean(args, "--stream-routed-output");
+    if (args.length || (section === "web" && (max !== undefined || timeout !== undefined))
+      || (section === "vision" && stream !== undefined)) throw new CliUsageError("Unsupported option for this sidecar section");
+    const settings: Record<string, unknown> = {};
+    if (model !== undefined) settings.model = model === "-" ? "" : model;
+    if (backend !== undefined) settings.backend = backend === "-" ? null : backend;
+    if (reasoning !== undefined) settings.reasoning = reasoning;
+    if (enabled !== undefined) settings.enabled = enabled;
+    if (stream !== undefined) settings.streamRoutedModelOutput = stream;
+    if (max !== undefined) {
+      const value = Number(max);
+      if (!max.trim() || !Number.isSafeInteger(value) || value < 1) throw new CliUsageError("--max-descriptions requires a positive integer");
+      settings.maxDescriptionsPerTurn = value;
+    }
+    if (timeout !== undefined) {
+      const value = Number(timeout);
+      if (!timeout.trim() || !isValidVisionTimeoutMs(value)) throw new CliUsageError("--timeout-ms requires an integer from 1 to 2147483647");
+      settings.timeoutMs = value;
+    }
+    if (!Object.keys(settings).length) throw new CliUsageError("Provide at least one sidecar setting");
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    if (section === "web" && model !== undefined && model !== "-") {
+      const offered = await runtimeRequest("/api/sidecar-settings", { redirect: "error" }, pinned);
+      if (!record(offered) || !Array.isArray(offered.webSearchModels)) invalid();
+      const requestedBackend = backend === "-" ? "openai" : backend;
+      const option = offered.webSearchModels.find(row => record(row)
+        && (row.value === model || row.model === model)
+        && (requestedBackend === undefined || row.backend === requestedBackend));
+      if (option !== undefined) {
+        if (!record(option) || typeof option.model !== "string" || typeof option.backend !== "string"
+          || !["openai", "anthropic", "xai", "gemini", "exa"].includes(option.backend)) invalid();
+        settings.model = option.model;
+        if (backend !== "-") settings.backend = option.backend;
+      }
+    }
+    const value = await runtimeRequest("/api/sidecar-settings", { method: "PUT", redirect: "error",
+      body: serializeManagementJson(section === "web" ? { webSearch: settings } : { vision: settings }) }, pinned);
+    if (!record(value) || value.ok !== true) invalid();
+    const raw = section === "web" ? value.webSearch : value.vision;
+    const backends = section === "web" ? ["openai", "anthropic", "xai", "gemini", "exa"] : ["openai", "anthropic", "routed"];
+    if (!record(raw) || typeof raw.enabled !== "boolean" || typeof raw.model !== "string" || !raw.model.trim()
+      || (raw.backend !== undefined && (typeof raw.backend !== "string" || !backends.includes(raw.backend)))) invalid();
+    const selected: Record<string, unknown> = { enabled: raw.enabled, model: raw.model,
+      ...(raw.backend !== undefined ? { backend: raw.backend } : {}) };
+    let verified = true;
+    if (section === "web") {
+      if (typeof raw.streamRoutedModelOutput !== "boolean") invalid();
+      selected.streamRoutedModelOutput = raw.streamRoutedModelOutput;
+      if (stream !== undefined && raw.streamRoutedModelOutput !== stream) verified = false;
+    } else {
+      if (!isValidVisionTimeoutMs(raw.timeoutMs) || typeof raw.maxDescriptionsPerTurn !== "number"
+        || !Number.isSafeInteger(raw.maxDescriptionsPerTurn) || raw.maxDescriptionsPerTurn < 1
+        || (raw.reasoning !== undefined && (typeof raw.reasoning !== "string" || !isDeclaredReasoningEffort(raw.reasoning)))) invalid();
+      selected.timeoutMs = raw.timeoutMs;
+      selected.maxDescriptionsPerTurn = raw.maxDescriptionsPerTurn;
+      if (raw.reasoning !== undefined) selected.reasoning = raw.reasoning;
+      if (timeout !== undefined && raw.timeoutMs !== Number(timeout)) verified = false;
+    }
+    const apply = projectSettingsApply(value.codexWebSearch);
+    if (!apply) invalid();
+    const data = { ok: true, [section === "web" ? "webSearch" : "vision"]: selected, codexWebSearch: apply,
+      ...(!verified ? { verification: "unverified" } : {}) };
+    const lines = [`${section} sidecar settings saved.`];
+    if (!apply.applied) lines.push(`Native apply: ${desktopSwitchApplyReason(apply.reason)}.`);
+    if (!verified) lines.push("The target did not confirm the requested new setting. Read back before retrying.");
+    printData(data, wantsJson, lines);
+    return !verified || (!apply.applied && apply.reason !== "not_requested") ? 1 : 0;
+  });
+}