@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/access-data-response.ts

@@ -0,0 +1,76 @@
+/** Whitelist native text completions; never serialize arbitrary provider payloads. */
+import { redactSelectedKey } from "./access-data-client";
+export type DataProtocol = "chat" | "responses" | "messages";
+export interface SafeModelResponse {
+  protocol: DataProtocol;
+  text: string[];
+  completion: "complete" | "limited";
+  usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number };
+}
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function usageOf(raw: unknown, protocol: DataProtocol): SafeModelResponse["usage"] {
+  if (raw === undefined || raw === null) return undefined;
+  const usage = record(raw);
+  if (!usage) throw new Error("Invalid usage.");
+  const result: NonNullable<SafeModelResponse["usage"]> = {};
+  const fields = protocol === "chat"
+    ? { inputTokens: "prompt_tokens", outputTokens: "completion_tokens", totalTokens: "total_tokens" } as const
+    : { inputTokens: "input_tokens", outputTokens: "output_tokens", totalTokens: "total_tokens" } as const;
+  for (const name of ["inputTokens", "outputTokens", "totalTokens"] as const) {
+    const value = usage[fields[name]];
+    if (value === undefined) continue;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error("Invalid usage.");
+    result[name] = value;
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+export function projectModelResponse(raw: unknown, protocol: DataProtocol, key: string): SafeModelResponse {
+  const row = record(raw);
+  if (!row || (row.error !== undefined && row.error !== null)) throw new Error("Unsupported response.");
+  const text: string[] = [];
+  let limited = false;
+  if (protocol === "responses") {
+    if (row.object !== "response" || (row.status !== "completed" && row.status !== "incomplete") || !Array.isArray(row.output)) throw new Error("Unsupported response.");
+    if (record(row.incomplete_details)?.reason === "content_filter") throw new Error("Unsupported response.");
+    limited = row.status === "incomplete";
+    for (const value of row.output) {
+      const item = record(value);
+      if (!item || item.type !== "message" || item.role !== "assistant" || !Array.isArray(item.content)) {
+        // Reasoning/tool entries are not text evidence and are never exposed.
+        continue;
+      }
+      for (const blockValue of item.content) {
+        const block = record(blockValue);
+        if (block?.type !== "output_text" || typeof block.text !== "string") throw new Error("Unsupported response.");
+        text.push(block.text);
+      }
+    }
+  } else if (protocol === "chat") {
+    if (row.object !== "chat.completion" || !Array.isArray(row.choices) || row.choices.length === 0) throw new Error("Unsupported response.");
+    for (const value of row.choices) {
+      const choice = record(value);
+      const message = record(choice?.message);
+      if (!choice || (choice.finish_reason !== "stop" && choice.finish_reason !== "length")
+        || !message || message.role !== "assistant" || typeof message.content !== "string"
+        || (message.refusal !== undefined && message.refusal !== null)) throw new Error("Unsupported response.");
+      limited ||= choice.finish_reason === "length";
+      text.push(message.content);
+    }
+  } else {
+    if (row.type !== "message" || row.role !== "assistant" || !Array.isArray(row.content)
+      || (row.stop_reason !== "end_turn" && row.stop_reason !== "stop_sequence" && row.stop_reason !== "max_tokens")) {
+      throw new Error("Unsupported response.");
+    }
+    limited = row.stop_reason === "max_tokens";
+    for (const value of row.content) {
+      const block = record(value);
+      if (block?.type === "text" && typeof block.text === "string") text.push(block.text);
+      else if (block?.type !== "thinking" && block?.type !== "redacted_thinking") throw new Error("Unsupported response.");
+    }
+  }
+  if (!text.length) throw new Error("Unsupported response.");
+  const usage = usageOf(row.usage, protocol);
+  return { protocol, text: text.map(value => redactSelectedKey(value, key)), completion: limited ? "limited" : "complete", ...(usage ? { usage } : {}) };
+}

package/src/cli/access.ts

@@ -4,15 +4,20 @@ import {
   rejectArgs,
   runCliAction,
   runtimeRequest,
+  runtimeBaseUrl,
   takeFlag,
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
 
+import { handleSelectedKeyTest, type SelectedKeyTestDeps } from "./access-data-plane";
+import { handleAccessAudioCommand } from "./access-audio";
+
 const USAGE = `Usage:
   ocx access key [list] [--json]
   ocx access key create [name] [--json]
   ocx access key get <id-or-name> [--json]
+  ocx access key rename <id-or-name> <name> [--json]
   ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]
   ocx access key rotate <id> [--json]
   ocx access key rotate commit <id> <rotation-id> [--json]
@@ -20,7 +25,9 @@ const USAGE = `Usage:
   ocx access key remove <id> --yes [--json]
   ocx access endpoints [--json]
   ocx access models [--json]
-  ocx access test <model> [--protocol <chat|responses|messages>] [--json]`;
+  ocx access test <model> [--protocol <chat|responses|messages>] [--api-key-stdin] [--json]
+  ocx access audio transcribe <file> --model <id> --api-key-stdin [--json]
+  ocx access audio live-check --model <id> --api-key-stdin [--json]`;
 
 const UTC_ISO_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
 
@@ -234,6 +241,56 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   throw new CliUsageError(`unknown key command ${action}`, USAGE);
 }
 
+/** Rename never sends or prints a secret, and cannot silently choose duplicate ids. */
+async function renameKey(argv: string[], deps: RuntimeApiDeps): Promise<number> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const [selector, rawName] = args;
+  if (args.length !== 2 || !selector?.trim() || selector.startsWith("-") || !rawName
+    || /[\u0000-\u001f\u007f]/.test(rawName) || !rawName.trim() || rawName.trim().length > 64) {
+    console.error("Error: Supply one key id or unambiguous name and a new name of 1–64 characters without controls.");
+    return 2;
+  }
+  const name = rawName.trim();
+  try {
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const before = await runtimeRequest<unknown>("/api/keys", { redirect: "error", credentials: "omit" }, pinned);
+    if (!before || typeof before !== "object" || !("keys" in before) || !Array.isArray(before.keys)
+      || before.keys.some(row => !row || typeof row !== "object" || Array.isArray(row)
+        || typeof row.id !== "string" || !row.id || typeof row.name !== "string")) throw new Error();
+    const rows = before.keys as Array<Record<string, unknown>>;
+    const wanted = selector.trim().toLowerCase();
+    if (rows.filter(row => (row.id as string).toLowerCase() === wanted).length > 1) {
+      throw new CliUsageError("Ambiguous key identity.");
+    }
+    const target = findKeyRow(rows, selector);
+    if (rows.filter(row => (row.id as string).toLowerCase() === (target.id as string).toLowerCase()).length !== 1) {
+      throw new CliUsageError("Ambiguous key identity.");
+    }
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {
+      method: "PATCH", body: JSON.stringify({ id: target.id, name }), redirect: "error", credentials: "omit",
+    }, pinned);
+    if (!result || typeof result !== "object" || Array.isArray(result) || result.id !== target.id || result.name !== name
+      || typeof result.createdAt !== "string" || !isUtcIsoInstant(result.createdAt)) throw new Error();
+    const projected: Record<string, unknown> = { id: result.id, name: result.name, createdAt: result.createdAt };
+    for (const scope of ["allowedProviders", "allowedModels"] as const) {
+      if (result[scope] === undefined) continue;
+      const value = result[scope];
+      if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim() || item.length > 256)) throw new Error();
+      projected[scope] = [...value];
+    }
+    printData(projected, wantsJson, ["API key renamed.", ...scopeLines(projected)]);
+    return 0;
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      console.error("Error: API key selector is missing or ambiguous. List keys and use a unique id.");
+      return 2;
+    }
+    console.error("Error: API key rename was not confirmed. List keys to check the current name before retrying.");
+    return 1;
+  }
+}
+
 async function endpoints(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
@@ -271,7 +328,13 @@ async function testModel(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`${model}: ${protocol} request succeeded.`]);
 }
 
-export async function handleAccessCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleAccessCommand(argv: string[], deps: SelectedKeyTestDeps = {}): Promise<number> {
+  const [command, ...args] = argv;
+  if (command === "audio") return handleAccessAudioCommand(args, deps);
+  if (command === "test" && args.some(arg => arg === "--api-key-stdin" || arg.startsWith("--api-key-stdin="))) {
+    return handleSelectedKeyTest(args, deps);
+  }
+  if ((command === "key" || command === "keys") && args[0] === "rename") return renameKey(args.slice(1), deps);
   return runCliAction(async () => {
     const [sub = "key", ...rest] = argv;
     if (sub === "key" || sub === "keys") await key(rest, deps);

package/src/cli/account-api.ts

@@ -1,4 +1,4 @@
-import { parseQuotaFailureCode, type QuotaFailureCode } from "../providers/quota-types";
+import { parseQuotaFailureCode, type QuotaFailureCode, type ProviderQuota, type AccountQuotaMode } from "../providers/quota-types";
 /**
  * Data-access layer for `ocx account` (issue #180) — live-proxy HTTP client and
  * per-family account readers. Kept separate from account.ts (command handlers)
@@ -11,6 +11,10 @@ import { getProviderRegistryEntry, providerCodexAccountMode } from "../providers
 import type { OcxConfig } from "../types";
 import { projectCodexQuotaRefreshOutcome, type CodexQuotaRefreshOutcome } from "../codex/quota-refresh-outcome";
 
+import { projectApiKeyQuotaRows } from "./account-key-quota";
+import { projectAccountHealth } from "./account-next-actions";
+import type { OAuthHealthLabel } from "../oauth/health";
+
 export type AccountType = "codex" | "oauth" | "api-key";
 
 export interface AccountRow {
@@ -27,6 +31,12 @@ export interface AccountRow {
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  /** Validated server health label and locally generated recovery guidance. */
+  health?: OAuthHealthLabel;
+  healthAction?: string;
+  /** Explicit paid-credit consent, reported only when supplied by the Codex API. */
+  creditsAfterLimit?: boolean;
+  needsReauthReason?: "verify_account";
   autoSelectable?: boolean;
   skipReason?: "paused" | "needs_reauth" | "suspended" | "cooldown" | "quota_exhausted";
   selectionExcludedReason?: "plan_excluded";
@@ -37,7 +47,8 @@ export interface AccountRow {
   priority?: number;
   /** Null means the account inherits the global usage-switch threshold. */
   autoSwitchThresholdOverride?: number | null;
-  quota?: CodexQuotaDto | null;
+  quota?: (CodexQuotaDto & Partial<ProviderQuota>) | null;
+  quotaMode?: AccountQuotaMode;
   quotaRefresh?: CodexQuotaRefreshOutcome;
   quotaUnavailable?: boolean;
   quotaFailure?: QuotaFailureCode;
@@ -122,7 +133,7 @@ export async function apiJson(
   method: "GET" | "PUT" | "POST" | "DELETE",
   path: string,
   body?: unknown,
-  options: { signal?: AbortSignal } = {},
+  options: { signal?: AbortSignal; redirect?: RequestRedirect } = {},
 ): Promise<ApiResult> {
   const fetchImpl = deps.fetchImpl ?? fetch;
   try {
@@ -131,6 +142,7 @@ export async function apiJson(
       headers: runningProxyUpdateHeaders(),
       body: body === undefined ? undefined : JSON.stringify(body),
       signal: options.signal,
+      ...(options.redirect ? { redirect: options.redirect } : {}),
     });
     const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
     return { status: res.status, json };
@@ -255,6 +267,8 @@ interface CodexAccountDto {
   selectionExcludedReason?: "plan_excluded";
   selectionExcludedPlan?: string;
   health?: { reason?: string };
+  healthLabel?: unknown;
+  creditsAfterLimit?: unknown;
   priority?: number;
   autoSwitchThresholdOverride?: number | null;
   quota?: CodexQuotaDto | null;
@@ -321,6 +335,8 @@ export async function fetchCodexRows(
     plan: a.plan,
     active: a.id === activeId,
     needsReauth: a.needsReauth,
+    ...projectAccountHealth(a, "openai", a.id),
+    ...(typeof a.creditsAfterLimit === "boolean" ? { creditsAfterLimit: a.creditsAfterLimit } : {}),
     ...(a.selectionExcludedReason === "plan_excluded" ? {
       selectionExcludedReason: "plan_excluded" as const,
       ...(typeof a.selectionExcludedPlan === "string" ? { selectionExcludedPlan: a.selectionExcludedPlan } : {}),
@@ -345,9 +361,11 @@ interface OAuthAccountDto {
   email?: string;
   active?: boolean;
   needsReauth?: boolean;
+  healthLabel?: unknown;
   /** Present only for providers that support operator pause (generic OAuth pools). */
   paused?: boolean;
   autoSwitchThresholdOverride?: number | null;
+  needsReauthReason?: "verify_account";
   autoSelectable?: boolean;
   skipReason?: unknown;
   /** Always sent by the management route; explicitly `null` when the tier is unknown. */
@@ -388,8 +406,10 @@ async function fetchOAuthRows(
     email: a.email,
     active: a.active ?? a.id === activeId,
     needsReauth: a.needsReauth,
+    ...projectAccountHealth(a, name, a.id),
     ...(a.paused === true ? { paused: true } : {}),
     ...(name === "anthropic" && Object.hasOwn(a, "autoSwitchThresholdOverride") ? { autoSwitchThresholdOverride: a.autoSwitchThresholdOverride } : {}),
+    ...(a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     ...(name === "kiro" && typeof a.autoSelectable === "boolean"
       ? { autoSelectable: a.autoSelectable } : {}),
     ...(name === "kiro" && a.autoSelectable === false && isKiroSkipReason(a.skipReason)
@@ -413,12 +433,19 @@ interface ApiKeyDto {
   active?: boolean;
 }
 
-async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string): Promise<FamilyRows> {
-  const res = await apiJson(deps, baseUrl, "GET", `/api/providers/keys?name=${encodeURIComponent(name)}`);
+async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string, quota?: { refresh?: boolean }): Promise<FamilyRows> {
+  const query = `?name=${encodeURIComponent(name)}${quota ? `&quota=1${quota.refresh ? "&refresh=1" : ""}` : ""}`;
+  const res = await apiJson(deps, baseUrl, "GET", `/api/providers/keys${query}`, undefined, quota ? { redirect: "error" } : {});
   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 };
+  if (quota) {
+    try { return projectApiKeyQuotaRows(res.json, name); }
+    catch (error) {
+      return { rows: [], activeId: null, status: 200, errorJson: { error: error instanceof Error ? error.message : "Malformed API-key quota response." } };
+    }
+  }
   const activeId = typeof res.json.activeId === "string" ? res.json.activeId : null;
   const keys = Array.isArray(res.json.keys) ? res.json.keys as ApiKeyDto[] : [];
   const rows = keys.map(k => ({
@@ -441,7 +468,7 @@ export function fetchRows(
 ): Promise<FamilyRows> {
   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);
+  return fetchKeyRows(deps, baseUrl, name, quota);
 }
 
 export async function fetchProviderQuotaReport(

package/src/cli/account-auth.ts

@@ -1,4 +1,6 @@
 import { writeSync } from "node:fs";
+import { isValidProviderName } from "../config/provider-name";
+import { runCatalogAction } from "./catalog-command-result";
 import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
 import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
 import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
@@ -10,6 +12,8 @@ import {
   rejectArgs,
   runCliAction,
   runtimeRequest,
+  runtimeBaseUrl,
+  terminalSafeText,
   takeFlag,
   takeOption,
   takeOptionWithSyntax,
@@ -34,7 +38,7 @@ function writeStdoutFully(text: string): void {
 }
 
 const USAGE = `Usage:
-  ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--method builder-id|google|github] [--code -] [--no-wait] [--json]
+  ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--method builder-id|google|github] [--open-browser on|off] [--add-account on|off] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json] (--flow required for codex)
   ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]
@@ -81,6 +85,62 @@ interface LoginStart {
   warning?: string;
 }
 
+/** Public handoff only. Never spread runtime bodies into terminal or JSON output. */
+function loginObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid login reply");
+  return value as Record<string, unknown>;
+}
+function publicLoginStart(value: unknown, kiro = false): LoginStart {
+  const data = loginObject(value);
+  const out: LoginStart = {};
+  const strings = kiro
+    ? ["flowId", "userCode", "verificationUri", "verificationUriComplete"] as const
+    : ["url", "flowId", "instructions", "deviceCode"] as const;
+  for (const key of strings) {
+    if (data[key] !== undefined && typeof data[key] !== "string") throw new Error("Invalid login handoff field");
+    if (typeof data[key] === "string") out[key] = data[key];
+  }
+  if (typeof data.browserLaunch === "string" && ["started", "failed", "skipped"].includes(data.browserLaunch)) out.browserLaunch = data.browserLaunch as LoginStart["browserLaunch"];
+  if (typeof data.method === "string" && ["builder-id", "google", "github"].includes(data.method)) out.method = data.method as LoginStart["method"];
+  if (typeof data.state === "string" && ["pending", "done", "failed", "expired", "cancelled"].includes(data.state)) out.state = data.state as string;
+  if (typeof data.warning === "string" && ["duplicate_profile_arn", "manual_review_required"].includes(data.warning)) out.warning = data.warning as string;
+  if (typeof data.expiresAt === "number" && Number.isFinite(data.expiresAt)) out.expiresAt = data.expiresAt;
+  return out;
+}
+function publicLoginStatus(value: unknown): Record<string, unknown> {
+  const data = loginObject(value);
+  const out: Record<string, unknown> = {};
+  for (const key of ["accountId", "activeAccountId", "email"]) if (typeof data[key] === "string") out[key] = data[key];
+  for (const key of ["loggedIn", "done", "needsReauth", "validationPending", "catalogRefreshPending"]) {
+    if (data[key] !== undefined && typeof data[key] !== "boolean") throw new Error("Invalid login completion field");
+    if (typeof data[key] === "boolean") out[key] = data[key];
+  }
+  if (typeof data.status === "string" && ["starting", "pending", "done", "error", "expired", "cancelled", "idle"].includes(data.status)) out.status = data.status;
+  if (typeof data.source === "string" && ["oauth", "local-cli", "credential-file", "environment", "manual"].includes(data.source)) out.source = data.source;
+  if (data.hint && typeof data.hint === "object" && !Array.isArray(data.hint)) out.hint = publicLoginStart(data.hint);
+  if (Array.isArray(data.accounts)) out.accounts = data.accounts.map(value => {
+    const row = loginObject(value);
+    const account: Record<string, unknown> = {};
+    for (const key of ["id", "alias", "email"]) if (typeof row[key] === "string") account[key] = row[key];
+    for (const key of ["active", "needsReauth"]) if (typeof row[key] === "boolean") account[key] = row[key];
+    if (row.needsReauthReason === "verify_account") account.needsReauthReason = "verify_account";
+    if (typeof row.expiresAt === "number" && Number.isFinite(row.expiresAt)) account.expiresAt = row.expiresAt;
+    if (row.plan === null) account.plan = null;
+    return account;
+  });
+  return out;
+}
+function loginBoolean(args: string[], flag: string): boolean | undefined {
+  const option = takeOptionWithSyntax(args, flag);
+  if (!option) return undefined;
+  if (option.value !== "on" && option.value !== "off") throw new CliUsageError(`${flag} must be on or off`, USAGE);
+  return option.value === "on";
+}
+function writeLoginInstructions(lines: readonly string[]): void {
+  const block = lines.filter(line => line !== "").flatMap(line => line.split("\n")).map(terminalSafeText).join("\n");
+  if (block) writeStdoutFully(`${block}\n`);
+}
+
 /**
  * Said only when the host could not open a browser (#5261).
  *
@@ -136,7 +196,7 @@ async function resolveCode(
   return await readSecretLine(deps, "authorization code");
 }
 
-async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function login(argv: string[], deps: RuntimeApiDeps): Promise<number | void> {
   const args = [...argv];
   const provider = args.shift()?.trim().toLowerCase();
   const wantsJson = takeFlag(args, "--json");
@@ -146,34 +206,39 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const method = takeOption(args, "--method");
   const id = takeOption(args, "--id");
   const suppliedCode = takeOptionWithSyntax(args, "--code");
+  const openBrowser = loginBoolean(args, "--open-browser");
+  const addAccount = loginBoolean(args, "--add-account");
+  if (provider && !isValidProviderName(provider)) throw new CliUsageError("invalid provider name", USAGE);
   if (!provider) throw new CliUsageError("provider is required", USAGE);
   if (method !== undefined) {
     if (provider !== "kiro" || !["builder-id", "google", "github"].includes(method)) {
       throw new CliUsageError("--method requires kiro and builder-id, google, or github", USAGE);
     }
     if (reauth || id) throw new CliUsageError("native Kiro device login only adds accounts; remove and re-add to reauthenticate", USAGE);
+    if (openBrowser !== undefined || addAccount !== undefined) throw new CliUsageError("native Kiro --method does not accept --open-browser or --add-account", USAGE);
     if (device || suppliedCode) throw new CliUsageError("--method cannot be combined with --device or --code", USAGE);
   }
-  // A bare leftover here is plausibly the authorization code itself: this flow takes one
-  // through --code, and a user who pastes it as a positional would otherwise see it echoed
-  // back in the usage error. `ocx login codex` reaches this parser too, so the paste lands
-  // one word away from a command people run constantly. Flag-shaped leftovers stay visible,
-  // because a mistyped flag is exactly what the message has to name.
-  rejectArgs(args, USAGE, { redactValues: true });
+  // A malformed leftover may contain pasted authorization input, even inside an
+  // unknown flag. New login parsing reports only a fixed usage diagnostic.
+  if (args.length) throw new CliUsageError("Unexpected arguments or repeated options", USAGE);
   // kimi, nous, and github-copilot are already device flows, so --device is a
   // true statement about them and is accepted as a no-op rather than an error.
   // Anything else has no device grant at all and must fail loudly.
   if (device && !CODEX_NAMES.has(provider) && !DEVICE_NATIVE_PROVIDERS.has(provider)) {
-    throw new CliUsageError(`--device is not supported for provider '${provider}'`, USAGE);
+    throw new CliUsageError("--device is not supported for this provider", USAGE);
   }
+  if (addAccount !== undefined && (reauth || CODEX_NAMES.has(provider))) throw new CliUsageError("--add-account is only valid for fresh provider OAuth login", USAGE);
+  if (openBrowser !== undefined && (device || DEVICE_NATIVE_PROVIDERS.has(provider))) throw new CliUsageError("--open-browser is not supported for device login", USAGE);
+  if (!CODEX_NAMES.has(provider) && id && !reauth) throw new CliUsageError("--id is only valid with --reauth for provider OAuth accounts", USAGE);
   // Only resolve when --code was actually given: a plain `ocx account login`
   // opens the browser flow and polls, and must not block on stdin.
   const code = await resolveCode(suppliedCode, deps, false);
+  const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
 
   if (method) {
-    const start = await runtimeRequest<LoginStart>("/api/oauth/login", {
-      method: "POST", body: JSON.stringify({ provider: "kiro", method }),
-    }, deps);
+    const start = publicLoginStart(await runtimeRequest<unknown>("/api/oauth/login", {
+      method: "POST", redirect: "error", body: JSON.stringify({ provider: "kiro", method }),
+    }, pinned), true);
     if (!wantsJson) {
       const block = formatKiroDeviceInstructions(start);
       if (block) writeStdoutFully(`${block}\n`);
@@ -182,7 +247,7 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (!start.flowId) throw new CliUsageError("Kiro device login did not return a flow id");
     for (let attempt = 0; attempt < 450; attempt++) {
       await Bun.sleep(2_000);
-      const state = await runtimeRequest<LoginStart>(`/api/oauth/status?provider=kiro&flowId=${encodeURIComponent(start.flowId)}`, {}, deps);
+      const state = publicLoginStart(await runtimeRequest<unknown>(`/api/oauth/status?provider=kiro&flowId=${encodeURIComponent(start.flowId)}`, { redirect: "error" }, pinned), true);
       if (state.state === "done") {
         printData(state, wantsJson, ["Logged in to kiro.", ...(state.warning ? [`Warning: ${state.warning}`] : [])]);
         return;
@@ -195,31 +260,33 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }
 
   if (CODEX_NAMES.has(provider)) {
-    const start = await runtimeRequest<LoginStart>("/api/codex-auth/login", {
-      method: "POST",
+    const start = publicLoginStart(await runtimeRequest<unknown>("/api/codex-auth/login", {
+      method: "POST", redirect: "error",
       body: JSON.stringify({
         ...(id ? { id } : {}),
         ...(reauth ? { reauth: true } : {}),
         ...(device ? { device: true } : {}),
+        ...(openBrowser === undefined ? {} : { openBrowser }),
       }),
-    }, deps);
+    }, pinned));
     if (!wantsJson) {
       // One atomic pre-poll block, flushed synchronously so a piped parent
       // reads the URL before the polling window starts (#1007).
-      const block = [
+      writeLoginInstructions([
         start.url ? `Open this URL to sign in:\n${start.url}` : "",
         start.deviceCode ? `Device code: ${start.deviceCode}` : "",
         start.instructions ?? "",
         start.browserLaunch === "failed" ? BROWSER_LAUNCH_FAILED_HINT : "",
         start.flowId ? `Flow: ${start.flowId}` : "",
-      ].filter(line => line !== "").join("\n");
-      if (block) writeStdoutFully(`${block}\n`);
+      ]);
     }
+    if (code && !start.flowId) throw new Error("Code submission requires a returned flow id");
     if (code && start.flowId) {
-      await runtimeRequest("/api/codex-auth/login/code", {
-        method: "POST",
+      const submitted = await runtimeRequest("/api/codex-auth/login/code", {
+        method: "POST", redirect: "error",
         body: JSON.stringify({ flowId: start.flowId, input: code }),
-      }, deps);
+      }, pinned);
+      if (loginObject(submitted).ok !== true) throw new Error("Code submission was not accepted");
     }
     if (noWait) {
       printData({ ...start, modelSelection: modelSelectionNextSteps("openai", true) }, wantsJson, modelSelectionGuidance("openai", true));
@@ -233,10 +300,11 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const maxAttempts = device ? 480 : 150;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       await Bun.sleep(2_000);
-      const state = await runtimeRequest<Record<string, unknown>>(
+      const state = publicLoginStatus(await runtimeRequest<unknown>(
         `/api/codex-auth/login-status?flowId=${encodeURIComponent(start.flowId)}${id ? `&accountId=${encodeURIComponent(id)}` : ""}${reauth ? "&reauth=1" : ""}`,
-        {}, deps,
-      );
+        { redirect: "error" }, pinned,
+      ));
+      if (start.flowId) state.flowId = start.flowId;
       if (state.status === "done") {
         if (state.validationPending === true) {
           printData({ ...state, recoveryCommand: "ocx gui", recoveryAction: "After quota recovers, click Refresh quotas in the dashboard Codex account pool." }, wantsJson, [
@@ -247,33 +315,32 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
           printData({ ...state, modelSelection: modelSelectionNextSteps("openai") }, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`, ...modelSelectionGuidance("openai")]);
         }
         if (!wantsJson) warnIfCodexCatalogRefreshPending(state);
-        return;
+        return state.validationPending === true || state.catalogRefreshPending === true ? 1 : 0;
       }
-      if (state.status === "error" || state.status === "expired") {
-        throw new CliUsageError(String(state.error ?? `login ${state.status}`));
+      if (state.status === "error" || state.status === "expired" || state.status === "cancelled") {
+        throw new Error("Login failed or expired");
       }
     }
     throw new CliUsageError("login timed out");
   }
 
-  if (id && !reauth) throw new CliUsageError("--id is only valid with --reauth for provider OAuth accounts", USAGE);
-  const start = await runtimeRequest<LoginStart>("/api/oauth/login", {
-    method: "POST",
-    body: JSON.stringify({ provider, addAccount: !reauth, ...(reauth && id ? { accountId: id, reauth: true } : {}) }),
-  }, deps);
+  const start = publicLoginStart(await runtimeRequest<unknown>("/api/oauth/login", {
+    method: "POST", redirect: "error",
+    body: JSON.stringify({ provider, addAccount: addAccount ?? !reauth, ...(openBrowser === undefined ? {} : { openBrowser }), ...(reauth && id ? { accountId: id, reauth: true } : {}) }),
+  }, pinned));
   if (!wantsJson) {
-    const block = [
+    writeLoginInstructions([
       start.url ? `Open this URL to sign in:\n${start.url}` : "",
       start.instructions ?? "",
       start.deviceCode ? `Device code: ${start.deviceCode}` : "",
-    ].filter(line => line !== "").join("\n");
-    if (block) writeStdoutFully(`${block}\n`);
+    ]);
   }
   if (code) {
-    await runtimeRequest("/api/oauth/login/code", {
-      method: "POST",
+    const submitted = await runtimeRequest("/api/oauth/login/code", {
+      method: "POST", redirect: "error",
       body: JSON.stringify({ provider, input: code }),
-    }, deps);
+    }, pinned);
+    if (loginObject(submitted).ok !== true) throw new Error("Code submission was not accepted");
   }
   if (noWait) {
     printData({ ...start, modelSelection: modelSelectionNextSteps(provider, true) }, wantsJson, modelSelectionGuidance(provider, true));
@@ -281,8 +348,10 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }
   for (let attempt = 0; attempt < 100; attempt++) {
     await Bun.sleep(2_000);
-    const state = await runtimeRequest<Record<string, unknown>>(`/api/oauth/status?provider=${encodeURIComponent(provider)}`, {}, deps);
-    if (state.error) throw new CliUsageError(String(state.error));
+    const raw = await runtimeRequest<Record<string, unknown>>(`/api/oauth/status?provider=${encodeURIComponent(provider)}`, { redirect: "error" }, pinned);
+    if (loginObject(raw).error) throw new Error("Provider login failed");
+    const state = publicLoginStatus(raw);
+    if (state.done === true && state.loggedIn !== true) throw new Error("Provider login ended without authentication");
     if (state.loggedIn === true) {
       printData({ ...state, modelSelection: modelSelectionNextSteps(provider) }, wantsJson, [`Logged in to ${provider}.`, ...modelSelectionGuidance(provider)]);
       return;
@@ -413,7 +482,7 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
 
 export async function handleAccountAuthCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
   let action: (() => Promise<void>) | undefined;
-  if (sub === "login" || sub === "reauth") action = () => login(sub === "reauth" ? [...argv, "--reauth"] : argv, deps);
+  if (sub === "login" || sub === "reauth") return runCatalogAction(() => login(sub === "reauth" ? [...argv, "--reauth"] : argv, deps));
   else if (sub === "code") action = () => code(argv, deps);
   else if (sub === "cancel") action = () => cancel(argv, deps);
   else if (sub === "reset-credits") action = () => resetCredits(argv, deps);