@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/cli/provider-runtime.ts

@@ -15,6 +15,7 @@ import {
 const USAGE = `Usage:
   ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
       [--auth-mode <key|forward|oauth|local|->] [--note <text|->]
+      [--api-key-transport <x-api-key|bearer|->]
       [--enabled <on|off>] [--live-models <on|off>] [--allow-private-network <on|off>] [--json]
   ocx provider test <name> [--json]
   ocx provider quota [--refresh] [--json]
@@ -37,6 +38,7 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const defaultModel = cleared(takeOption(args, "--default-model"));
   const authMode = cleared(takeOption(args, "--auth-mode"));
   const note = cleared(takeOption(args, "--note"));
+  const apiKeyTransport = cleared(takeOption(args, "--api-key-transport"));
   const enabled = takeBooleanOption(args, "--enabled");
   const liveModels = takeBooleanOption(args, "--live-models");
   const allowPrivateNetwork = takeBooleanOption(args, "--allow-private-network");
@@ -46,6 +48,7 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (defaultModel !== undefined) patch.defaultModel = defaultModel;
   if (authMode !== undefined) patch.authMode = authMode;
   if (note !== undefined) patch.note = note;
+  if (apiKeyTransport !== undefined) patch.apiKeyTransport = apiKeyTransport;
   if (enabled !== undefined) patch.disabled = !enabled;
   if (liveModels !== undefined) patch.liveModels = liveModels;
   if (allowPrivateNetwork !== undefined) patch.allowPrivateNetwork = allowPrivateNetwork;

package/src/cli/provider.ts

@@ -8,13 +8,14 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
+import { apiKeyTransportConfigError, hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import type { OcxProviderConfig } from "../types";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { syncModelsToCodex } from "../codex/sync";
+import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 
 // ---------------------------------------------------------------------------
 // Arg helpers
@@ -124,7 +125,7 @@ function handleList(args: string[]): void {
 // provider add
 // ---------------------------------------------------------------------------
 
-const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--default-model <model>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
 
 async function handleAdd(args: string[]): Promise<void> {
   const name = args[0];
@@ -138,13 +139,14 @@ async function handleAdd(args: string[]): Promise<void> {
     process.exit(1);
   }
 
- const restArgs = args.slice(1);
- const force = consumeFlag(restArgs, "--force");
- const setDefault = consumeFlag(restArgs, "--set-default");
- const wantsJson = consumeFlag(restArgs, "--json");
- const wantsSync = consumeFlag(restArgs, "--sync");
+  const restArgs = args.slice(1);
+  const force = consumeFlag(restArgs, "--force");
+  const setDefault = consumeFlag(restArgs, "--set-default");
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const wantsSync = consumeFlag(restArgs, "--sync");
   const allowPrivateNetwork = consumeFlag(restArgs, "--allow-private-network");
- const apiKey = consumeFlagValue(restArgs, "--api-key");
+  const apiKey = consumeFlagValue(restArgs, "--api-key");
+  const apiKeyTransport = consumeFlagValue(restArgs, "--api-key-transport");
   const adapter = consumeFlagValue(restArgs, "--adapter");
   const baseUrl = consumeFlagValue(restArgs, "--base-url");
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
@@ -152,6 +154,12 @@ async function handleAdd(args: string[]): Promise<void> {
 
   const config = loadConfig();
 
+  const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
+  if (namespaceCollision) {
+    console.error(`Error: ${namespaceCollision}.`);
+    process.exit(1);
+  }
+
   if (hasOwnProvider(config.providers, name) && !force) {
     console.error(`Provider "${name}" already exists. Use --force to overwrite.`);
     process.exit(1);
@@ -188,9 +196,22 @@ async function handleAdd(args: string[]): Promise<void> {
     };
   }
 
- config.providers[name] = provConfig;
+  if (apiKeyTransport !== undefined) {
+    if (apiKeyTransport !== "x-api-key" && apiKeyTransport !== "bearer") {
+      console.error('Error: --api-key-transport must be "x-api-key" or "bearer".');
+      process.exit(1);
+    }
+    const transportError = apiKeyTransportConfigError({ ...provConfig, apiKeyTransport });
+    if (transportError) {
+      console.error(`Error: ${transportError}.`);
+      process.exit(1);
+    }
+    provConfig.apiKeyTransport = apiKeyTransport;
+  }
+
+  config.providers[name] = provConfig;
   if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
- if (setDefault) config.defaultProvider = name;
+  if (setDefault) config.defaultProvider = name;
 
   validateAndSave(config);
 

package/src/cli/star-prompt.ts

@@ -1,8 +1,11 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { createInterface } from "node:readline/promises";
 import { getConfigDir } from "../config";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { commandInvocation } from "../lib/win-exec";
+import { isAgentDriven } from "./agent-driven";
+import { interactiveConfirm } from "./interactive-confirm";
 
 const REPO = "lidge-jun/opencodex";
 /** Fires exactly once from the first interactive `ocx start`. */
@@ -21,24 +24,74 @@ export function hasStarPromptRun(): boolean {
   }
 }
 
+/**
+ * Whether `gh` is both installed and logged in. Starring goes through the
+ * user's own `gh` auth, so an unauthenticated CLI cannot fulfil a "Yes" — in
+ * that case the prompt stays silent instead of asking for something it would
+ * then fail to do.
+ */
+/**
+ * On Windows `gh` is a `.cmd` shim; a shell-less spawn of the bare name skips
+ * PATHEXT and refuses `.cmd` targets, so it stalls until the timeout instead of
+ * failing fast. Route every call through the launcher the rest of the CLI uses.
+ */
+/** Resolve `gh` once; callers keep their own spawnSync overload. */
+function ghInvocation(args: string[]) {
+  const invocation = commandInvocation("gh", args);
+  return {
+    file: invocation.file,
+    args: invocation.args,
+    verbatim: invocation.options.windowsVerbatimArguments === true,
+  };
+}
+
 function ghAvailable(): boolean {
-  const r = spawnSync("gh", ["--version"], { stdio: "ignore", timeout: 3000, windowsHide: true });
-  return !r.error && r.status === 0;
+  const v = ghInvocation(["--version"]);
+  const version = spawnSync(v.file, v.args,
+    { stdio: "ignore", timeout: 3000, windowsHide: true, windowsVerbatimArguments: v.verbatim });
+  if (version.error || version.status !== 0) return false;
+  const a = ghInvocation(["auth", "status"]);
+  const auth = spawnSync(a.file, a.args,
+    { stdio: "ignore", timeout: 5000, windowsHide: true, windowsVerbatimArguments: a.verbatim });
+  return !auth.error && auth.status === 0;
 }
 
 function starRepo(): { ok: boolean; error?: string } {
-  const r = spawnSync("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`],
-    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true });
+  const star = ghInvocation(["api", "-X", "PUT", `/user/starred/${REPO}`]);
+  const r = spawnSync(star.file, star.args,
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true,
+      windowsVerbatimArguments: star.verbatim });
   if (r.error) return { ok: false, error: r.error.message };
   if (r.status !== 0) return { ok: false, error: (r.stderr || r.stdout || "").trim() || `gh exited ${r.status}` };
   return { ok: true };
 }
 
 /**
- * First interactive `ocx start`: a one-time `[y/N]` "star on GitHub?" prompt.
- * On yes, stars the repo via the user's `gh` auth. No-op under the background
- * service, for non-TTY/piped runs, when already prompted, or when `gh` is
- * unavailable. Never throws.
+ * Shown instead of the prompt when an agent is driving `ocx start`. The agent
+ * reads this as its instruction: it must not answer, it must ask the person.
+ * Deliberately addressed to the agent rather than silently skipped, so the
+ * request reaches the user through the agent instead of disappearing.
+ */
+function printAgentDeferral(): void {
+  console.log(
+    `\n  \x1b[38;5;141m⭐ opencodex isn't starred on GitHub yet.\x1b[0m\n` +
+    `  \x1b[2mAgent: do not answer this yourself — it uses the user's GitHub identity.\n` +
+    `  Ask the user whether to star ${REPO}, and only run\n` +
+    `  \`gh api -X PUT /user/starred/${REPO}\` if they say yes.\x1b[0m\n`,
+  );
+}
+
+/**
+ * First interactive `ocx start`: a one-time "star on GitHub?" question with an
+ * explicit Yes/No selector (arrow keys, `y`/`n`, Enter), starring through the
+ * user's own `gh` login.
+ *
+ * The selector is only rendered when the account owner is there to answer it:
+ * it is skipped under the background service, for non-TTY/piped runs, and when
+ * `gh` is missing or logged out. When an agent is driving the process the
+ * question is not auto-answered — the agent is told to ask the user instead,
+ * and the one-time marker stays unwritten so a later hand-typed run can still
+ * show the real prompt. Never throws.
  */
 export async function maybeShowStarPrompt(): Promise<void> {
   try {
@@ -46,17 +99,25 @@ export async function maybeShowStarPrompt(): Promise<void> {
     const dir = getConfigDir();
     const marker = join(dir, MARKER);
     if (existsSync(marker)) return;
-    if (!ghAvailable()) return; // can't star without gh — stay silent and re-check on a later start
-    try { mkdirSync(dir, { recursive: true }); writeFileSync(marker, new Date().toISOString()); } catch { /* best-effort */ }
+    if (!ghAvailable()) return; // can't star without an authenticated gh — stay silent and re-check on a later start
 
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let yes = false;
-    try {
-      const ans = (await rl.question("\n  \x1b[38;5;141m⭐ Enjoying opencodex? Star it on GitHub?\x1b[0m [y/N] ")).trim().toLowerCase();
-      yes = ans === "y" || ans === "yes";
-    } finally {
-      rl.close();
+    // An agent would answer this on the user's behalf, using the user's GitHub
+    // identity. Hand the question to the agent to relay, and leave the marker
+    // unwritten so the user still gets the real prompt on their own run.
+    if (isAgentDriven()) {
+      printAgentDeferral();
+      return;
     }
+    try {
+      recordOwnedConfigPath(dir, marker);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(marker, new Date().toISOString());
+    } catch { /* best-effort */ }
+
+    const yes = await interactiveConfirm({
+      question: "\n  \x1b[38;5;141m⭐ Enjoying opencodex? Star it on GitHub (via gh)?\x1b[0m",
+      defaultYes: true,
+    });
     if (!yes) return;
     const r = starRepo();
     console.log(r.ok ? "  Thanks for the star! ⭐\n" : `  Couldn't star automatically (${r.error}) — ${REPO}\n`);

package/src/cli/status.ts

@@ -1,7 +1,7 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
 import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
-import { isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { diagnoseService } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
@@ -102,6 +102,14 @@ export function selectListenTarget(
   };
 }
 
+/** Prefer live result (including authoritative null pid) over the on-disk pid file. */
+export function resolveStatusPid(
+  live: { pid: number | null } | null,
+  pidFile: number | null,
+): number | null {
+  return live ? live.pid : pidFile;
+}
+
 async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
   const url = target.healthUrl;
   const controller = new AbortController();
@@ -132,9 +140,33 @@ async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
 export async function collectStatus(): Promise<CliStatusView> {
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;
-  const pid = readPid();
-  const listen = selectListenTarget(config, pid, pid ? readRuntimePort(pid) : null);
-  const health = await checkProxyHealth(listen);
+  // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618).
+  // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and
+  // warn on malformed config.json (status --json must stay stderr-clean).
+  const live = await findLiveProxy({
+    configFn: () => ({ port: config.port, hostname: config.hostname }),
+  });
+  const pidFile = readPid();
+  // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
+  const pid = resolveStatusPid(live, pidFile);
+  const listen = live
+    ? {
+      port: live.port,
+      hostname: live.hostname,
+      source: live.source,
+      healthUrl: `http://${probeHostname(live.hostname)}:${live.port}/healthz`,
+      dashboardUrl: `http://localhost:${live.port}/`,
+    }
+    : selectListenTarget(config, pidFile, pidFile ? readRuntimePort(pidFile) : null);
+  // findLiveProxy already identity-probed /healthz; avoid a second fetch that can race.
+  const health = live
+    ? {
+      ok: true,
+      url: listen.healthUrl,
+      message: `ok (pid ${live.pid ?? "unknown"})`,
+      label: `${listen.healthUrl} ok (live)`,
+    }
+    : await checkProxyHealth(listen);
   const bunRuntime = durableBunRuntime();
   const service = diagnoseService();
   const serviceSummary = service.summary;
@@ -228,13 +260,15 @@ export async function collectStatus(): Promise<CliStatusView> {
       runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
     },
   };
-  const proxyLabel = pid && health.ok
-    ? `running (PID ${pid})`
-    : pid
-      ? `PID file points to PID ${pid}, but health check failed`
-      : health.ok
-        ? "reachable, but PID file is missing or stale"
-        : "not running";
+  const proxyLabel = live
+    ? `running (PID ${live.pid ?? pid ?? "unknown"})`
+    : pid && health.ok
+      ? `running (PID ${pid})`
+      : pid
+        ? `PID file points to PID ${pid}, but health check failed`
+        : health.ok
+          ? "reachable, but PID file is missing or stale"
+          : "not running";
 
   return {
     proxyLabel,
@@ -242,8 +276,8 @@ export async function collectStatus(): Promise<CliStatusView> {
     json: {
       schemaVersion: 1,
       proxy: {
-        running: Boolean(pid && health.ok),
-        pid,
+        running: Boolean(live) || Boolean(pid && health.ok),
+        pid: live?.pid ?? pid,
         health: {
           ok: health.ok,
           url: health.url,

package/src/cli/v2.ts

@@ -11,7 +11,7 @@
  *  - nothing in the catalog build path calls this module; no auto-flip exists.
  */
 import { execFileSync } from "node:child_process";
-import { getLogicalMaxThreads, hasAgentsMaxThreads, isMultiAgentV2Enabled, transitionMultiAgentV2 } from "../codex/features";
+import { getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
 import { loadConfig, saveConfig } from "../config";
@@ -85,6 +85,15 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
     const threads = getLogicalMaxThreads();
     log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
+    const v2Active = isEnabled();
+    const agentsEnabled = getAgentsEnabled();
+    log.log(`agents.enabled: ${agentsEnabled === null ? "(unset — upstream default true)" : agentsEnabled}`);
+    const maxDepth = getAgentsMaxDepth();
+    // max_depth is V1-only upstream; say so whenever V2 is active so the number
+    // cannot be misread as an effective V2 limit.
+    log.log(`agents.max_depth: ${maxDepth ?? "(unset — upstream default 1)"}${v2Active ? " (V1-only — ignored while multi_agent_v2 is enabled)" : ""}`);
+    const instructions = getSubagentDeveloperInstructions();
+    log.log(`subagent_developer_instructions: ${instructions === null ? "(unset — children inherit)" : instructions === "" ? '"" (clears inherited instructions)' : JSON.stringify(instructions)}`);
     if (isEnabled() && hasMaxThreads()) {
       log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
     }

package/src/codex/account-id.ts

@@ -0,0 +1,34 @@
+/** Canonical persisted Codex pool-account id format. */
+export const CODEX_ACCOUNT_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+// Account credentials are persisted in JSON object maps. These names have
+// special meaning on ordinary JavaScript objects and must never be admitted as
+// user-controlled keys.
+const RESERVED_CODEX_ACCOUNT_IDS = new Set(["__proto__", "prototype", "constructor"]);
+
+/**
+ * Stable internal id under which the Codex Desktop login participates in account rotation.
+ * It is reserved and must never be used as a public namespace target or pool-account id.
+ */
+export const MAIN_CODEX_ACCOUNT_ID = "__main__";
+
+export function isValidCodexAccountId(accountId: unknown): accountId is string {
+  return typeof accountId === "string"
+    && accountId !== MAIN_CODEX_ACCOUNT_ID
+    && CODEX_ACCOUNT_ID_RE.test(accountId)
+    && !RESERVED_CODEX_ACCOUNT_IDS.has(accountId.toLowerCase());
+}
+
+type CodexAccountIdentityRow = { id: string; isMain: boolean };
+
+/** Legacy invalid rows remain loadable for cleanup, but never participate in routing. */
+export function isSelectableCodexPoolAccount(account: CodexAccountIdentityRow): boolean {
+  return !account.isMain && isValidCodexAccountId(account.id);
+}
+
+/** A pre-validation pool row that collides with the internal Desktop-account sentinel. */
+export function hasLegacyMainCodexPoolAccount(
+  accounts: readonly CodexAccountIdentityRow[] | undefined,
+): boolean {
+  return accounts?.some(account => !account.isMain && account.id === MAIN_CODEX_ACCOUNT_ID) ?? false;
+}

package/src/codex/account-lifecycle.ts

@@ -6,6 +6,7 @@ import { clearAccountQuota } from "./quota";
 import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
 import { clearMainAccountInfoCache } from "./main-account-cache";
+import { forgetCodexAccountPause } from "./account-pause";
 import type { OcxConfig } from "../types";
 
 let observedMainChatgptAccountId: string | undefined;
@@ -45,7 +46,9 @@ export function resetMainCodexAccountIdentityTrackingForTests(): void {
 
 export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string): void {
   removeCodexAccountCredential(accountId);
-  runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? []).filter(account => account.id !== accountId);
+  runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? [])
+    .filter(account => account.isMain || account.id !== accountId);
+  forgetCodexAccountPause(runtimeConfig, accountId);
   if (runtimeConfig.activeCodexAccountId === accountId) runtimeConfig.activeCodexAccountId = undefined;
   purgeCodexAccountRuntimeState(accountId);
   invalidateCodexWebSocketsForAccount(accountId);

package/src/codex/account-namespace-match.ts

@@ -0,0 +1,63 @@
+import { isValidCodexAccountId } from "./account-id";
+
+/** Config-only sentinel for the Codex Desktop account; outside the pool-account id grammar. */
+export const MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET = "@main";
+
+export const CODEX_ACCOUNT_NAMESPACE_COMBO_ALIAS_COLLISION_ERROR =
+  "combo alias must not use a configured Codex account namespace";
+
+const CODEX_ACCOUNT_ID_NAMESPACE_COLLISION_ERROR =
+  "account id must not collide with a configured Codex account namespace";
+
+/** Provider ids are compared case-insensitively at namespace admission boundaries. */
+export function codexProviderNamespaceKey(value: string): string {
+  return value.toLowerCase();
+}
+
+export function hasCodexAccountNamespace(
+  namespaces: unknown,
+  namespace: string,
+): boolean {
+  return !!namespaces
+    && typeof namespaces === "object"
+    && !Array.isArray(namespaces)
+    && Object.hasOwn(namespaces, namespace);
+}
+
+export function codexAccountNamespaceProviderCollisionError(
+  namespaces: unknown,
+  providerName: string,
+): string | undefined {
+  const normalizedProvider = codexProviderNamespaceKey(providerName);
+  const collides = !!namespaces
+    && typeof namespaces === "object"
+    && !Array.isArray(namespaces)
+    && Object.keys(namespaces)
+      .some(namespace => codexProviderNamespaceKey(namespace) === normalizedProvider);
+  return collides
+    ? "provider name must not collide with a configured Codex account namespace"
+    : undefined;
+}
+
+export function codexAccountIdNamespaceCollisionError(
+  namespaces: unknown,
+  accountId: string,
+): string | undefined {
+  return hasCodexAccountNamespace(namespaces, accountId)
+    ? CODEX_ACCOUNT_ID_NAMESPACE_COLLISION_ERROR
+    : undefined;
+}
+
+export function codexAccountNamespaceForModel(
+  namespaces: unknown,
+  modelId: string,
+): string | undefined {
+  const slash = modelId.indexOf("/");
+  if (slash <= 0) return undefined;
+  const namespace = modelId.slice(0, slash);
+  return hasCodexAccountNamespace(namespaces, namespace) ? namespace : undefined;
+}
+
+export function isValidCodexAccountNamespaceTarget(accountId: unknown): accountId is string {
+  return accountId === MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET || isValidCodexAccountId(accountId);
+}

package/src/codex/account-namespaces.ts

@@ -0,0 +1,149 @@
+import type { CodexAccount, OcxConfig } from "../types";
+import { COMBO_NAMESPACE } from "../combos/types";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import {
+  CODEX_ACCOUNT_LOG_LABEL_RE,
+  createCodexAccountLogLabel,
+  fallbackCodexAccountLogLabel,
+} from "./account-label";
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import {
+  codexAccountIdNamespaceCollisionError,
+  codexProviderNamespaceKey,
+  MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET,
+} from "./account-namespace-match";
+
+export { isValidCodexAccountNamespaceTarget } from "./account-namespace-match";
+
+const RESERVED_NAMESPACE_KEYS = new Set([
+  "__proto__",
+  "prototype",
+  "constructor",
+  COMBO_NAMESPACE,
+  OPENAI_CODEX_PROVIDER_ID,
+].map(codexProviderNamespaceKey));
+const PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS = 16;
+
+function comboAliasNamespaces(config: Pick<OcxConfig, "combos">): string[] {
+  return Object.values(config.combos ?? {}).flatMap((combo) => {
+    const alias = typeof combo?.alias === "string" ? combo.alias.trim() : "";
+    const slash = alias.indexOf("/");
+    return slash > 0 ? [alias.slice(0, slash)] : [];
+  });
+}
+
+function privateAccountSelectorCandidates(accountIds: Iterable<string>): Set<string> {
+  const candidates = new Set<string>();
+  for (const accountId of accountIds) {
+    candidates.add(accountId);
+    candidates.add(fallbackCodexAccountLogLabel(accountId));
+  }
+  return candidates;
+}
+
+function defaultPublicAccountSelector(
+  account: Pick<CodexAccount, "id" | "logLabel">,
+  allPrivateCandidates: ReadonlySet<string>,
+): string {
+  const privateCandidates = new Set(allPrivateCandidates);
+  privateCandidates.add(account.id);
+  privateCandidates.add(fallbackCodexAccountLogLabel(account.id));
+  if (CODEX_ACCOUNT_LOG_LABEL_RE.test(account.logLabel ?? "")
+    && !privateCandidates.has(account.logLabel!)) return account.logLabel!;
+
+  // Legacy or hand-edited rows may predate persisted random log labels. Allocate a fresh public
+  // selector rather than exposing the stable, id-derived fallback used only to redact old logs.
+  for (let attempt = 0; attempt < PUBLIC_ACCOUNT_SELECTOR_MAX_ATTEMPTS; attempt += 1) {
+    const selector = createCodexAccountLogLabel(privateCandidates);
+    if (!privateCandidates.has(selector)) return selector;
+  }
+  throw new Error("Unable to allocate a unique Codex account selector");
+}
+
+function claimNamespace(requested: string, used: Set<string>): string {
+  let namespace = requested;
+  let suffix = 2;
+  while (used.has(namespace)) namespace = `${requested}-${suffix++}`;
+  used.add(namespace);
+  return namespace;
+}
+
+function occupiedNamespaces(config: Pick<OcxConfig, "combos" | "providers">): Set<string> {
+  return new Set([
+    ...Object.keys(config.providers).map(codexProviderNamespaceKey),
+    ...comboAliasNamespaces(config),
+    ...RESERVED_NAMESPACE_KEYS,
+  ]);
+}
+
+/** Build an initial account-selector map without deriving public selectors from aliases or ids. */
+export function defaultCodexAccountNamespaces(
+  config: Pick<OcxConfig, "codexAccounts" | "combos" | "providers">,
+): Record<string, string> {
+  const namespaces: Record<string, string> = {};
+  const used = occupiedNamespaces(config);
+  const accounts = config.codexAccounts ?? [];
+  const privateCandidates = privateAccountSelectorCandidates(
+    accounts
+      .filter(account => account.id !== MAIN_CODEX_ACCOUNT_ID)
+      .map(account => account.id),
+  );
+  for (const candidate of privateCandidates) used.add(candidate);
+
+  namespaces[claimNamespace("main", used)] = MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET;
+  for (const account of accounts) {
+    if (account.isMain || !isValidCodexAccountId(account.id)) continue;
+    const namespace = claimNamespace(defaultPublicAccountSelector(account, privateCandidates), used);
+    namespaces[namespace] = account.id;
+  }
+  return namespaces;
+}
+
+/**
+ * Add one account to a generated map without renaming or replacing explicit existing entries.
+ * The account-creation layer must reject a new id that already equals an existing selector key.
+ * A true result means the map was mutated in place; callers must persist the updated config.
+ */
+export function appendDefaultCodexAccountNamespace(
+  config: Pick<OcxConfig, "codexAccountNamespaces" | "codexAccounts" | "combos" | "providers">,
+  account: Pick<CodexAccount, "id" | "isMain" | "logLabel">,
+): boolean {
+  const namespaces = config.codexAccountNamespaces;
+  if (account.isMain
+    || !isValidCodexAccountId(account.id)
+    || !namespaces
+    || Object.keys(namespaces).length === 0
+    || codexAccountIdNamespaceCollisionError(namespaces, account.id)
+    || Object.values(namespaces).includes(account.id)) return false;
+
+  const used = occupiedNamespaces(config);
+  for (const namespace of Object.keys(namespaces)) used.add(namespace);
+  const privateCandidates = privateAccountSelectorCandidates([
+    ...(config.codexAccounts ?? [])
+      .filter(existing => existing.id !== MAIN_CODEX_ACCOUNT_ID)
+      .map(existing => existing.id),
+    ...Object.values(namespaces),
+    account.id,
+  ]);
+  for (const candidate of privateCandidates) used.add(candidate);
+  const namespace = claimNamespace(defaultPublicAccountSelector(account, privateCandidates), used);
+  namespaces[namespace] = account.id;
+  return true;
+}
+
+export function isMainCodexAccountTarget(accountId: string): boolean {
+  return accountId === MAIN_CODEX_ACCOUNT_NAMESPACE_TARGET || accountId === MAIN_CODEX_ACCOUNT_ID;
+}
+
+function normalizeCodexAccountNamespaceTarget(accountId: string): string {
+  return isMainCodexAccountTarget(accountId)
+    ? MAIN_CODEX_ACCOUNT_ID
+    : accountId;
+}
+
+export function codexAccountNamespaceEntries(
+  config: Pick<OcxConfig, "codexAccountNamespaces">,
+): Array<[string, string]> {
+  return Object.entries(config.codexAccountNamespaces ?? {})
+    .map(([namespace, accountId]) => [namespace, normalizeCodexAccountNamespaceTarget(accountId)]);
+}

package/src/codex/account-pause.ts

@@ -0,0 +1,20 @@
+import type { OcxConfig } from "../types";
+
+/** Whether an account is administratively excluded from future pool selection. */
+export function isCodexAccountPaused(config: OcxConfig, accountId: string): boolean {
+  return config.pausedCodexAccountIds?.includes(accountId) ?? false;
+}
+
+/** Persist the account's pool eligibility without changing credentials or runtime health. */
+export function setCodexAccountPaused(config: OcxConfig, accountId: string, paused: boolean): void {
+  const pausedIds = new Set(config.pausedCodexAccountIds ?? []);
+  if (paused) pausedIds.add(accountId);
+  else pausedIds.delete(accountId);
+
+  if (pausedIds.size > 0) config.pausedCodexAccountIds = [...pausedIds];
+  else delete config.pausedCodexAccountIds;
+}
+
+export function forgetCodexAccountPause(config: OcxConfig, accountId: string): void {
+  setCodexAccountPaused(config, accountId, false);
+}