@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/claude/intercept/proxy-auth.ts

@@ -0,0 +1,166 @@
+import { randomBytes } from "node:crypto";
+import {
+  closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync,
+  openSync, readSync, unlinkSync, writeFileSync, type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import { forgetEphemeralSecretPath, hardenSecretDir, hardenSecretPath } from "../../lib/windows-secret-acl";
+
+const TOKEN_FILE = "proxy-token";
+const TOKEN_LENGTH = 43; // 32 random bytes encoded as unpadded base64url.
+const TOKEN_MAX_BYTES = TOKEN_LENGTH + 2; // Optional LF or CRLF, never arbitrary whitespace.
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const NONBLOCK = constants.O_NONBLOCK ?? 0;
+
+export function claudeInterceptProxyTokenPath(configDir: string): string {
+  return join(configDir, "claude-intercept", TOKEN_FILE);
+}
+
+function invalidCredential(): Error {
+  return new Error("Claude intercept credential is not a safe, valid owner-controlled file");
+}
+
+function assertOwnedNode(stat: Stats, directory = false): void {
+  if (stat.isSymbolicLink() || !(directory ? stat.isDirectory() : stat.isFile())) throw invalidCredential();
+  if (process.platform !== "win32" && typeof process.geteuid === "function" && stat.uid !== process.geteuid()) {
+    throw invalidCredential();
+  }
+}
+
+function assertSameNode(path: string, expected: Stats, directory = false): void {
+  const current = lstatSync(path);
+  assertOwnedNode(current, directory);
+  if (current.dev !== expected.dev || current.ino !== expected.ino) throw invalidCredential();
+}
+
+/** Read only through the validated descriptor, with a fixed maximum allocation and no links. */
+function readPinnedToken(configDir: string, harden: boolean): string {
+  const dir = join(configDir, "claude-intercept");
+  const directory = lstatSync(dir);
+  assertOwnedNode(directory, true);
+  if (process.platform !== "win32" && (directory.mode & 0o077) !== 0) throw invalidCredential();
+  const path = claudeInterceptProxyTokenPath(configDir);
+  const entry = lstatSync(path);
+  assertOwnedNode(entry);
+  if (entry.size < TOKEN_LENGTH || entry.size > TOKEN_MAX_BYTES) throw invalidCredential();
+  // NONBLOCK prevents a raced-in FIFO from blocking before fstat can reject it.
+  const fd = openSync(path, constants.O_RDONLY | NOFOLLOW | NONBLOCK);
+  try {
+    const opened = fstatSync(fd);
+    assertOwnedNode(opened);
+    if (opened.dev !== entry.dev || opened.ino !== entry.ino
+      || opened.size < TOKEN_LENGTH || opened.size > TOKEN_MAX_BYTES) throw invalidCredential();
+    const bytes = Buffer.alloc(TOKEN_MAX_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, length);
+      if (count === 0) break;
+      length += count;
+    }
+    const contents = bytes.subarray(0, length).toString("utf8");
+    const token = contents.slice(0, TOKEN_LENGTH);
+    const ending = contents.slice(TOKEN_LENGTH);
+    if (token.length !== TOKEN_LENGTH || !/^[A-Za-z0-9_-]+$/.test(token)
+      || !["", "\n", "\r\n"].includes(ending)) throw invalidCredential();
+    const afterRead = fstatSync(fd);
+    if (length !== afterRead.size || afterRead.mtimeMs !== opened.mtimeMs) throw invalidCredential();
+    assertSameNode(path, opened);
+    assertSameNode(dir, directory, true);
+    if (harden) {
+      if (process.platform === "win32") hardenSecretPath(path, { required: true });
+      else fchmodSync(fd, 0o600); // Never chmod a followed/replaced pathname.
+      assertSameNode(path, opened);
+      assertSameNode(dir, directory, true);
+    } else if (process.platform !== "win32" && (afterRead.mode & 0o077) !== 0) {
+      throw invalidCredential();
+    }
+    return token;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The current usable credential, or null. Inspection and CONNECT admission never create one. */
+export function readClaudeInterceptProxyToken(configDir: string): string | null {
+  try {
+    return readPinnedToken(configDir, false);
+  } catch { // no-excuse-ok: catch -- unusable credentials fail closed without exposing filesystem or token details.
+    return null;
+  }
+}
+
+function ensurePrivateDirectory(configDir: string): Stats {
+  const dir = join(configDir, "claude-intercept");
+  mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  try {
+    mkdirSync(dir, { mode: 0o700 });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const entry = lstatSync(dir);
+  assertOwnedNode(entry, true);
+  if (process.platform === "win32") {
+    hardenSecretDir(dir, { required: true });
+  } else {
+    const fd = openSync(dir, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | NOFOLLOW);
+    try {
+      const opened = fstatSync(fd);
+      assertOwnedNode(opened, true);
+      if (entry.dev !== opened.dev || entry.ino !== opened.ino) throw invalidCredential();
+      fchmodSync(fd, 0o700);
+    } finally {
+      closeSync(fd);
+    }
+  }
+  assertSameNode(dir, entry, true);
+  return entry;
+}
+
+/** Create once without replacing a winner, invalid file, symlink, or other existing entry. */
+export function ensureClaudeInterceptProxyToken(configDir: string): string {
+  const dir = join(configDir, "claude-intercept");
+  const directory = ensurePrivateDirectory(configDir);
+  try {
+    return readPinnedToken(configDir, true);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  assertSameNode(dir, directory, true);
+  const path = claudeInterceptProxyTokenPath(configDir);
+  const token = randomBytes(32).toString("base64url");
+  const temp = join(dir, `.${TOKEN_FILE}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW, 0o600);
+  const created = fstatSync(fd);
+  try {
+    writeFileSync(fd, `${token}\n`, { encoding: "utf8" });
+    if (process.platform !== "win32") fchmodSync(fd, 0o600);
+    else hardenSecretPath(temp, { required: true, timeoutMemoKey: path });
+    assertSameNode(temp, created);
+    assertSameNode(dir, directory, true);
+    try {
+      linkSync(temp, path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      // A concurrent winner is validated below. No rename/overwrite fallback is safe here.
+    }
+    return readPinnedToken(configDir, true);
+  } finally {
+    // Cleanup cannot turn a committed credential into a failed apply or hide the
+    // original publication error. Do not retry close: its fd may already be reused.
+    let cleanupFailed = false;
+    try { closeSync(fd); } catch { cleanupFailed = true; }
+    let removed = false;
+    try {
+      assertSameNode(temp, created);
+      unlinkSync(temp);
+      removed = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") removed = true;
+      else cleanupFailed = true;
+    }
+    if (removed) forgetEphemeralSecretPath(temp);
+    if (cleanupFailed) {
+      console.warn("[claude] Credential temporary cleanup incomplete; review retained temporary state.");
+    }
+  }
+}

package/src/claude/intercept/runtime.ts

@@ -8,6 +8,8 @@ import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocal
 import type { PickerRouteInput } from "./picker-models";
 import { createPickerRuntime, type CreatePickerRuntimeOptions, type PickerRuntime } from "./picker-runtime";
 import type { SecurityRunner } from "./picker-trust";
+import { ensureClaudeInterceptProxyToken, readClaudeInterceptProxyToken } from "./proxy-auth";
+import { buildClaudeInterceptEnv, migrateClaudeInterceptSettings } from "./settings";
 
 /**
  * Lifecycle for the Claude intercept pair (CONNECT proxy + TLS listener).
@@ -126,7 +128,20 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
   if (options.requestedPort === 0 && !explicitPort) return null;
   const configDir = options.configDir ?? getConfigDir();
   const ca = await ensureLocalInterceptCaForStartup(configDir);
+  const authToken = ensureClaudeInterceptProxyToken(configDir);
   const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS);
+  // Refresh an env we already own (e.g. a pre-auth proxy URL left by an upgrade) before the
+  // authenticated proxy takes over the port — a plain `ocx start` after an update would
+  // otherwise 407 every CONNECT until the next `ocx ensure` or apply. Only `stale` state is
+  // rewritten, so installs that never applied first-party are untouched.
+  try {
+    const proxyPort = claudeInterceptProxyPort(options.config, options.publicPort);
+    migrateClaudeInterceptSettings(buildClaudeInterceptEnv(proxyPort, claudeInterceptCaCertPath(configDir), authToken));
+  } catch (error) {
+    // A skipped rewrite degrades to the pre-migration behaviour and ensure/apply retries it,
+    // but silence here leaves upgraded clients hitting 407 with no recorded cause.
+    console.warn(`[claude-intercept] settings migration skipped: ${error instanceof Error ? error.message : String(error)}`);
+  }
   const listener = startClaudeInterceptListener<T>({
     leaf,
     dispatch: options.dispatch,
@@ -137,6 +152,9 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
   try {
     proxy = await startConnectProxy(claudeInterceptProxyPort(options.config, options.publicPort), {
       interceptPort: listener.port!,
+      // A real apply may recreate a missing token while this listener remains live.
+      // Read current validated authority per CONNECT; absent/invalid means deny, not mint.
+      authToken: () => readClaudeInterceptProxyToken(configDir),
     });
   } catch (error) {
     await listener.stop(true);
@@ -165,6 +183,9 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
       try {
         pickerProxy = await startConnectProxy(claudePickerProxyPort(options.config, options.publicPort), {
           interceptPort,
+          // No authToken: Desktop's egressProxyUrl cannot present proxy credentials, so this
+          // listener stays an unauthenticated loopback relay until the profile format can carry
+          // one. The intercept proxy above is the credential-bearing hop.
           // No host list here: the choice below depends on which client opened the tunnel.
           interceptHosts: [],
           selectTunnel: (host, port, request) => {

package/src/claude/intercept/settings.ts

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { atomicWriteFile } from "../../config/atomic-write";
 import { claudeConfigDir } from "../auth-detect";
 
 /**
@@ -10,7 +11,7 @@ import { claudeConfigDir } from "../auth-detect";
  * call. Two keys make every Claude Code process route through the local CONNECT proxy while
  * the app itself stays a first-party install:
  *
- *   env.HTTPS_PROXY         = http://127.0.0.1:<proxy port>
+ *   env.HTTPS_PROXY         = http://opencodex:<token>@127.0.0.1:<proxy port>
  *   env.NODE_EXTRA_CA_CERTS = <configDir>/claude-intercept/ca.pem
  *
  * Ownership is tracked by value, never by a marker key. The CA path is the anchor: it lives
@@ -26,12 +27,12 @@ export interface ClaudeInterceptEnv {
   NODE_EXTRA_CA_CERTS: string;
 }
 
-export function claudeInterceptProxyUrl(port: number): string {
-  return `http://127.0.0.1:${port}`;
+export function claudeInterceptProxyUrl(port: number, authToken: string): string {
+  return `http://opencodex:${encodeURIComponent(authToken)}@127.0.0.1:${port}`;
 }
 
-export function buildClaudeInterceptEnv(proxyPort: number, caCertPath: string): ClaudeInterceptEnv {
-  return { HTTPS_PROXY: claudeInterceptProxyUrl(proxyPort), NODE_EXTRA_CA_CERTS: caCertPath };
+export function buildClaudeInterceptEnv(proxyPort: number, caCertPath: string, authToken: string): ClaudeInterceptEnv {
+  return { HTTPS_PROXY: claudeInterceptProxyUrl(proxyPort, authToken), NODE_EXTRA_CA_CERTS: caCertPath };
 }
 
 export type ClaudeInterceptSettingsState =
@@ -69,7 +70,7 @@ function envRecord(doc: SettingsDoc): Record<string, unknown> {
 
 /** Loopback proxy URLs are the only shape opencodex ever writes. */
 export function isClaudeInterceptProxyUrl(value: unknown): value is string {
-  return typeof value === "string" && /^http:\/\/127\.0\.0\.1:\d{1,5}\/?$/.test(value.trim());
+  return typeof value === "string" && /^http:\/\/(?:opencodex:[^@/]+@)?127\.0\.0\.1:\d{1,5}\/?$/.test(value.trim());
 }
 
 function isOwnedCaPath(value: unknown, ownedCaPath: string): value is string {
@@ -111,9 +112,9 @@ export function inspectClaudeInterceptSettings(
 
 function writeSettings(path: string, doc: SettingsDoc): void {
   mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
-  renameSync(tmp, path);
+  // The managed env embeds the proxy token, so the file must stay owner-only:
+  // atomicWriteFile applies the real NTFS ACL on Windows where chmod is a no-op.
+  atomicWriteFile(path, `${JSON.stringify(doc, null, 2)}\n`);
 }
 
 export type ClaudeInterceptSettingsWrite =
@@ -123,7 +124,7 @@ export type ClaudeInterceptSettingsWrite =
 /** Capture only the managed keys. Rollback preserves unrelated edits and refuses
  * to overwrite a newer proxy/CA choice made after this apply. */
 export function captureClaudeInterceptSettingsRollback(
-  expected: ClaudeInterceptEnv,
+  expected: ClaudeInterceptEnv | (() => ClaudeInterceptEnv),
   configDir = claudeConfigDir(),
 ): () => boolean {
   const path = settingsPath(configDir);
@@ -132,10 +133,11 @@ export function captureClaudeInterceptSettingsRollback(
   const previous = "doc" in before ? { ...envRecord(before.doc) } : {};
   return () => {
     try {
+      const target = typeof expected === "function" ? expected() : expected;
       const current = readSettings(path);
       if (!("doc" in current)) return false;
       const env = envRecord(current.doc);
-      if (CLAUDE_INTERCEPT_MANAGED_ENV.some(key => env[key] !== expected[key])) return false;
+      if (CLAUDE_INTERCEPT_MANAGED_ENV.some(key => env[key] !== target[key])) return false;
       for (const key of CLAUDE_INTERCEPT_MANAGED_ENV) {
         if (previous[key] === undefined) delete env[key];
         else env[key] = previous[key];
@@ -168,6 +170,25 @@ export function applyClaudeInterceptSettings(
   return { ok: true, changed: true, path };
 }
 
+/**
+ * Rewrite an env block opencodex already owns when it no longer matches what this run
+ * would write — a pre-auth `http://127.0.0.1:<port>` left behind by an upgrade would get
+ * a 407 from the now-authenticated proxy until `ocx ensure` or an apply ran. Unlike apply
+ * this never creates an absent env: only `stale` (owned) state is rewritten, so the
+ * runtime can call it on every start without enabling the integration for anyone else.
+ */
+export function migrateClaudeInterceptSettings(
+  env: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsWrite {
+  const path = settingsPath(configDir);
+  const state = inspectClaudeInterceptSettings(env, configDir);
+  if (state.kind === "unreadable") return { ok: false, reason: "unreadable", path };
+  if (state.kind === "foreign") return { ok: false, reason: "foreign_env", path };
+  if (state.kind !== "stale") return { ok: true, changed: false, path };
+  return applyClaudeInterceptSettings(env, configDir);
+}
+
 /** Remove the managed keys, but only the values opencodex owns. */
 export function removeClaudeInterceptSettings(
   ownedCaPath: string,

package/src/claude/outbound.ts

@@ -33,7 +33,7 @@ function reasoningIdentityDigest(value: string): string {
 }
 
 /** Fixed-size identity that preserves protocol boundaries without retaining upstream strings. */
-function boundedReasoningIdentity(value: unknown): string {
+export function boundedReasoningIdentity(value: unknown): string {
   if (typeof value === "number") {
     if (Number.isSafeInteger(value) && value >= 0) return `n${value}`;
     if (Number.isFinite(value)) return `d${value}`;
@@ -104,7 +104,7 @@ export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
   };
 }
 
-function sseFrame(name: string, data: Rec): string {
+export function sseFrame(name: string, data: Rec): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
 }
 
@@ -161,7 +161,7 @@ export function sanitizeWebSearchInput(input: unknown): Rec {
  * input (query/queries) and the web_search_tool_result content (hits, or the error
  * object when the search failed). Shared by the SSE and JSON translation paths.
  */
-function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
+export function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultContent: unknown; completed: boolean } {
   const action = isRec(item.action) ? item.action : {};
   const queries = Array.isArray(action.queries)
     ? action.queries.filter((q): q is string => typeof q === "string" && q.length > 0)
@@ -205,7 +205,7 @@ function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultConte
  * is not a claim about upstream's tokenizer, and it is not final — `message_delta` carries the
  * authoritative count for every reader that waits for it, exactly as before.
  */
-function messageSnapshot(model: string, confirmedUsage?: Rec, inputTokenFloor?: number): Rec {
+export function messageSnapshot(model: string, confirmedUsage?: Rec, inputTokenFloor?: number): Rec {
   const usage = confirmedUsage
     ?? (typeof inputTokenFloor === "number" && Number.isFinite(inputTokenFloor) && inputTokenFloor > 0
       ? { input_tokens: Math.trunc(inputTokenFloor), output_tokens: 0 }
@@ -222,6 +222,43 @@ function messageSnapshot(model: string, confirmedUsage?: Rec, inputTokenFloor?:
   };
 }
 
+/**
+ * A Responses incomplete reason as the Anthropic client sees it: an output cap and a content
+ * filter are real stop reasons; every other reason is a retryable overload so Claude Code backs
+ * off instead of accepting a truncated turn.
+ */
+export function anthropicIncompleteOutcome(
+  reason: unknown,
+  message: unknown,
+): { stopReason: "max_tokens" | "refusal" } | { failMessage: string } {
+  if (reason === "max_output_tokens") return { stopReason: "max_tokens" };
+  if (reason === "content_filter") return { stopReason: "refusal" };
+  return {
+    failMessage: typeof message === "string" && message.trim()
+      ? message
+      : `upstream response was incomplete${typeof reason === "string" ? ` (${reason})` : ""}`,
+  };
+}
+
+/**
+ * The HTTP status a Responses `response.failed` error object maps to on the Anthropic wire.
+ * Internal failure envelopes carry the classified {type, code, message} but no numeric status,
+ * so it is derived with the same mapping /api/logs uses; a classified 429/401/400 then reaches
+ * Claude Code as its real Anthropic error type instead of a retryable overload.
+ */
+export function anthropicFailedStatus(error: Rec, message: string): number {
+  const code = typeof error.code === "string" ? error.code : undefined;
+  return code === "translation_buffer_limit"
+    ? 413
+    : typeof error.status === "number"
+      ? error.status
+      : httpStatusFromTerminalError({
+        type: typeof error.type === "string" ? error.type : undefined,
+        code: typeof error.code === "string" ? error.code : null,
+        message,
+      });
+}
+
 interface OpenBlock {
   kind: "text" | "thinking" | "tool_use";
   index: number;
@@ -668,16 +705,9 @@ export function responsesSseToAnthropicSse(
           case "response.incomplete": {
             const response = isRec(data.response) ? data.response : {};
             const details = isRec(response.incomplete_details) ? response.incomplete_details : {};
-            if (details.reason === "max_output_tokens") {
-              finish("max_tokens", response.usage);
-            } else if (details.reason === "content_filter") {
-              finish("refusal", response.usage);
-            } else {
-              const message = typeof details.message === "string" && details.message.trim()
-                ? details.message
-                : `upstream response was incomplete${typeof details.reason === "string" ? ` (${details.reason})` : ""}`;
-              fail(529, message, true);
-            }
+            const outcome = anthropicIncompleteOutcome(details.reason, details.message);
+            if ("stopReason" in outcome) finish(outcome.stopReason, response.usage);
+            else fail(529, outcome.failMessage, true);
             break;
           }
           case "response.failed": {
@@ -688,19 +718,7 @@ export function responsesSseToAnthropicSse(
             if (code === "translation_buffer_limit") {
               throw new TranslatorBudgetExceededError("live_transient", TRANSLATOR_MAX_TURN_BYTES);
             }
-            const status = code === "translation_buffer_limit"
-              ? 413
-              : typeof error.status === "number"
-                ? error.status
-                // Internal response.failed envelopes carry the classified {type, code, message}
-                // but no numeric status. Derive it with the same mapping /api/logs uses so a
-                // classified 429/401/400 reaches Claude Code as its real Anthropic error type
-                // instead of being masked as retryable overload.
-                : httpStatusFromTerminalError({
-                  type: typeof error.type === "string" ? error.type : undefined,
-                  code: typeof error.code === "string" ? error.code : null,
-                  message,
-                });
+            const status = anthropicFailedStatus(error, message);
             // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic
             // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to
             // overloaded_error by design.

package/src/cli/account-extended.ts

@@ -1,4 +1,5 @@
 import { loadConfig } from "../config";
+import { isReservedCodexAccountWord, reportCodexAccountTargetError, resolveCodexAccountTarget } from "./account-target";
 import { hasPassiveAccountQuota } from "../providers/quota";
 import { closeSync, openSync, readSync } from "node:fs";
 import {
@@ -39,15 +40,15 @@ const AUTO_NOTE = "auto (no pin — lowest-usage account is selected per request
 const EXTENDED_USAGE = `Usage:
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
-  ocx account alias <provider> <id|main> <display-name|-> [--json]
-  ocx account priority <provider> <id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
-  ocx account pause <provider> <id|main> [--json]
-  ocx account resume <provider> <id|main> [--json]
+  ocx account alias <provider> <id|alias|main> <display-name|-> [--json]
+  ocx account priority <provider> <id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
+  ocx account pause <provider> <id|alias|main> [--json]
+  ocx account resume <provider> <id|alias|main> [--json]
   ocx account pause-exhausted <provider> [--json]
   ocx account strategy <provider> [<quota|round-robin|fill-first|reset-first>] [--json]
   ocx account sticky <provider> [<1-100>] [--json]
-  ocx account remove <provider> <id|main> --yes [--json]
-  ocx account clear-cooldown <provider> <id|main> [--json]
+  ocx account remove <provider> <id|alias|main> --yes [--json]
+  ocx account clear-cooldown <provider> <id|alias|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
   ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]`;
 const PIPE_GUIDANCE = `Pipe the API key on stdin, for example:
@@ -447,12 +448,24 @@ export async function cmdRemove(args: string[], deps: AccountDeps): Promise<numb
   }
   const classified = configAndType(deps, name);
   if ("error" in classified) return wantsJson ? fail(classified.error) : usage(`Error: ${classified.error}`);
-  const id = classified.type === "codex" && requestedId === "main" ? MAIN_ID : requestedId;
-  if (classified.type === "codex" && id === MAIN_ID) return wantsJson
+  if (classified.type === "codex" && (requestedId === "main" || requestedId === MAIN_ID)) return wantsJson
     ? fail("the main Codex App login cannot be removed")
     : usage("Error: the main Codex App login cannot be removed");
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
+  let id = requestedId;
+  if (classified.type === "codex") {
+    const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
+    if ("networkDown" in target) {
+      const reason = target.transportError ? ` reason: ${target.transportError}` : "";
+      return fail(`Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.${reason}`);
+    }
+    if ("error" in target) {
+      const message = target.kind === "not_found" ? `account or key "${requestedId}" was not found` : target.error;
+      return wantsJson ? fail(message) : usage(`Error: ${message}`);
+    }
+    id = target.id;
+  }
   const before = await fetchRows(deps, baseUrl, name, classified.type);
   if (before.networkDown) return fail("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
   if (before.errorJson) return fail(errorText(before.errorJson, `failed to verify ${name} before removal`));
@@ -633,9 +646,12 @@ export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promi
   if (classified.type !== "codex") {
     return usage(`Error: ${name} is not a Codex account pool; cooldown clearing applies to Codex accounts only`);
   }
-  const id = requestedId === "main" ? MAIN_ID : requestedId;
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
+  const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
+  if ("networkDown" in target) return proxyUnreachable(target.transportError);
+  if ("error" in target) return reportCodexAccountTargetError(target);
+  const id = target.id;
   const response = await apiJson(deps, baseUrl, "POST", "/api/codex-auth/accounts/clear-cooldown", { id });
   if (response.status === 0) return proxyUnreachable(response.transportError);
   if (response.status !== 200) return apiError(response.json, `failed to clear cooldown for ${requestedId}`, response.status);
@@ -693,8 +709,6 @@ export async function cmdPriority(args: string[], deps: AccountDeps): Promise<nu
   if (classified.type !== "codex") {
     return usage("Error: selection order only applies to the openai Codex account pool");
   }
-  const id = requestedId === "main" ? MAIN_ID : requestedId;
-
   // Validate before touching the network so a typo never reaches the proxy.
   let priority: number | null | undefined;
   if (requestedPriority !== undefined) {
@@ -706,6 +720,13 @@ export async function cmdPriority(args: string[], deps: AccountDeps): Promise<nu
 
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
+  const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
+  if ("networkDown" in target) return proxyUnreachable(target.transportError);
+  if ("error" in target) {
+    if (target.kind === "not_found" && priority === undefined) return usage(`Error: no ${name} account ${requestedId}`);
+    return reportCodexAccountTargetError(target);
+  }
+  const id = target.id;
 
   // No value means "show" — a read must not rewrite what it is reporting.
   if (priority === undefined) {
@@ -770,10 +791,12 @@ export async function cmdPause(args: string[], deps: AccountDeps, paused: boolea
   if (classified.type !== "codex") {
     return usage(`Error: ${verb} applies to the openai Codex account pool`);
   }
-  const id = requestedId === "main" ? MAIN_ID : requestedId;
-
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
+  const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
+  if ("networkDown" in target) return proxyUnreachable(target.transportError);
+  if ("error" in target) return reportCodexAccountTargetError(target);
+  const id = target.id;
 
   const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/pause", { id, paused });
   // Transport sentinel first: status 0 means the proxy never answered, and comparing it to
@@ -996,12 +1019,21 @@ export async function cmdAlias(args: string[], deps: AccountDeps): Promise<numbe
   if (!name || !requestedId || requestedAlias === undefined || args.length) return usage();
   const classified = configAndType(deps, name);
   if ("error" in classified) return usage(`Error: ${classified.error}`);
-  const id = classified.type === "codex" && requestedId === "main" ? MAIN_ID : requestedId;
-  if (id === MAIN_ID) return usage("Error: the main Codex App login cannot be renamed");
+  if (classified.type === "codex" && (requestedId === "main" || requestedId === MAIN_ID)) {
+    return usage("Error: the main Codex App login cannot be renamed");
+  }
   const alias = requestedAlias === "-" ? "" : requestedAlias.trim();
   if (alias.length > 80 || /[\x00-\x1f\x7f]/.test(alias)) return usage("Error: alias must be at most 80 printable characters");
+  if (classified.type === "codex" && isReservedCodexAccountWord(alias)) return usage(`Error: "${alias}" is reserved for \`ocx account use\` and cannot be an alias`);
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
+  let id = requestedId;
+  if (classified.type === "codex") {
+    const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
+    if ("networkDown" in target) return proxyUnreachable(target.transportError);
+    if ("error" in target) return reportCodexAccountTargetError(target);
+    id = target.id;
+  }
   const path = classified.type === "codex"
     ? "/api/codex-auth/accounts/alias"
     : classified.type === "oauth"