@bitkyc08/opencodex 2.10.2 → 2.11.0-preview.20260808

package/src/claude/desktop-3p.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
@@ -103,6 +103,45 @@ interface Desktop3pMetadata {
   [key: string]: unknown;
 }
 
+export type Desktop3pLibraryKind =
+  | "not_installed"
+  | "standard"
+  | "gateway_ours"
+  | "gateway_drifted"
+  | "foreign"
+  | "no_owned_state"
+  | "broken"
+  | "unsafe";
+
+export interface Desktop3pLibraryInspection {
+  kind: Desktop3pLibraryKind;
+  libraryPath: string;
+  selectedProfilePath: string | null;
+  appliedId: string | null;
+  /** Paths of opencodex-owned rows that are not selected by Desktop. */
+  residualPaths: string[];
+  /** Bounded reason code; never includes metadata or profile contents. */
+  reason?: "metadata_unreadable" | "unsafe_applied_id" | "invalid_owned_profile";
+  fingerprint?: string;
+  /**
+   * Whether Desktop's applied selection is our owned entry, by ID match alone.
+   * `null` = undeterminable (no metadata, unreadable metadata, or no appliedId);
+   * a readable appliedId with no owned entry is a KNOWN false, not unknown.
+   * Deliberately independent of profile-file health: the status contract
+   * predates this inspector and callers render tri-state.
+   */
+  ownedProfileActive: boolean | null;
+}
+
+export interface Desktop3pRemovalResult {
+  ok: boolean;
+  changed: boolean;
+  kind: "removed" | "noop" | "cleanup_incomplete" | "unsafe" | "write_failed";
+  libraryPath: string;
+  residualPaths?: string[];
+  reason?: string;
+}
+
 let desktop3pRegistry = new Map<string, string>();
 let desktop3pAliasesByRoute = new Map<string, string>();
 
@@ -327,6 +366,186 @@ function parseMetadata(path: string): Desktop3pMetadata {
   return { ...parsed, entries: parsed.entries };
 }
 
+const SAFE_DESKTOP_PROFILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isOwnedDesktopEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
+  return entry?.name === "opencodex" || entry?.name === "opencodex-standard";
+}
+
+/** A gateway row is removable; the selected standard row must always remain. */
+function isOwnedDesktopGatewayEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
+  return entry?.name === "opencodex";
+}
+
+function profilePath(libraryPath: string, id: string): string {
+  return join(libraryPath, `${id}.json`);
+}
+
+/**
+ * Read Desktop's selected config without changing its library.
+ *
+ * This is intentionally separate from the eager writer below: status probes must
+ * never manufacture a config-library directory on a machine without Desktop.
+ */
+export function inspectDesktop3pConfigLibrary(
+  options: Desktop3pConfigLibraryOptions & { appliedFingerprint?: string | null } = {},
+): Desktop3pLibraryInspection {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  if (!existsSync(libraryPath)) {
+    return { kind: "not_installed", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+
+  const metadataPath = join(libraryPath, "_meta.json");
+  if (!existsSync(metadataPath)) {
+    return { kind: "no_owned_state", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+
+  let metadata: Desktop3pMetadata;
+  try {
+    metadata = parseMetadata(metadataPath);
+  } catch {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], reason: "metadata_unreadable", ownedProfileActive: null,
+    };
+  }
+  const appliedId = typeof metadata.appliedId === "string" ? metadata.appliedId : null;
+  if (appliedId === null) {
+    return { kind: "no_owned_state", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+  const selected = metadata.entries.find(entry => entry?.id === appliedId);
+  // A readable appliedId with no owned entry is a KNOWN false, not unknown.
+  const ownedProfileActive = isOwnedDesktopEntry(selected);
+  if (!SAFE_DESKTOP_PROFILE_ID.test(appliedId)) {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath: null, appliedId, residualPaths: [], reason: "unsafe_applied_id", ownedProfileActive,
+    };
+  }
+
+  const selectedProfilePath = profilePath(libraryPath, appliedId);
+  const residualPaths = metadata.entries
+    .filter(entry => isOwnedDesktopGatewayEntry(entry) && entry.id !== appliedId && SAFE_DESKTOP_PROFILE_ID.test(entry.id))
+    .flatMap(entry => [profilePath(libraryPath, entry.id), `${profilePath(libraryPath, entry.id)}.bak`])
+    .filter(existsSync);
+  if (!existsSync(selectedProfilePath)) {
+    return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+  }
+
+  let profile: Record<string, unknown>;
+  let fingerprint: string;
+  try {
+    const source = readFileSync(selectedProfilePath, "utf8");
+    const parsed = JSON.parse(source) as unknown;
+    if (!isRecord(parsed)) return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+    profile = parsed;
+    fingerprint = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  } catch {
+    return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+  }
+  if (!isOwnedDesktopEntry(selected)) {
+    return { kind: "foreign", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive };
+  }
+  if (profile.inferenceProvider === undefined) {
+    return { kind: "standard", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive };
+  }
+  const validGateway = profile.inferenceProvider === "gateway"
+    && profile.inferenceCredentialKind === "static"
+    && typeof profile.inferenceGatewayBaseUrl === "string"
+    && typeof profile.inferenceGatewayApiKey === "string";
+  if (!validGateway) {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, reason: "invalid_owned_profile", ownedProfileActive,
+    };
+  }
+  return {
+    kind: options.appliedFingerprint && options.appliedFingerprint === fingerprint ? "gateway_ours" : "gateway_drifted",
+    libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive,
+  };
+}
+
+/**
+ * Select a credential-free standard profile before deleting an owned gateway.
+ * The old metadata row remains as a retry locator only until both its profile
+ * and backup are absent; successful cleanup removes it in the same operation.
+ */
+export function removeDesktop3pStandardPivot(
+  options: Desktop3pConfigLibraryOptions & {
+    appliedFingerprint?: string | null;
+    unlink?: (path: string) => void;
+  } = {},
+): Desktop3pRemovalResult {
+  const inspected = inspectDesktop3pConfigLibrary(options);
+  if (inspected.kind === "not_installed" || inspected.kind === "no_owned_state") {
+    return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
+  }
+  if (inspected.kind === "broken" || inspected.kind === "unsafe" || inspected.kind === "gateway_drifted") {
+    return { ok: false, changed: false, kind: "unsafe", libraryPath: inspected.libraryPath, reason: inspected.reason };
+  }
+  if (!inspected.appliedId || !SAFE_DESKTOP_PROFILE_ID.test(inspected.appliedId)) {
+    return { ok: false, changed: false, kind: "unsafe", libraryPath: inspected.libraryPath, reason: "unsafe_applied_id" };
+  }
+
+  const metadataPath = join(inspected.libraryPath, "_meta.json");
+  try {
+    const metadata = parseMetadata(metadataPath);
+    const selectedId = inspected.appliedId;
+    // When Desktop is actively using our gateway, pivot only that selected row
+    // first. Any second owned row is residue for a later standard-mode retry;
+    // this preserves the selected-row preference after an interrupted cleanup.
+    const targetIds = inspected.kind === "gateway_ours"
+      ? [selectedId]
+      : metadata.entries
+        .filter(isOwnedDesktopGatewayEntry)
+        .map(entry => entry.id)
+        .filter(id => SAFE_DESKTOP_PROFILE_ID.test(id));
+    if (targetIds.length === 0) return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
+
+    let metadataAfterPivot = metadata;
+    if (inspected.kind === "gateway_ours") {
+      const standardId = randomUUID();
+      const standardPath = profilePath(inspected.libraryPath, standardId);
+      atomicWriteFile(standardPath, "{}\n");
+      const standardEntry: Desktop3pMetadataEntry = { id: standardId, name: "opencodex-standard" };
+      metadataAfterPivot = { ...metadata, appliedId: standardId, entries: [...metadata.entries, standardEntry] };
+      atomicWriteFile(metadataPath, JSON.stringify(metadataAfterPivot, null, 2) + "\n");
+    }
+
+    const residualPaths: string[] = [];
+    for (const id of targetIds) {
+      for (const candidate of [profilePath(inspected.libraryPath, id), `${profilePath(inspected.libraryPath, id)}.bak`]) {
+        try {
+          if (existsSync(candidate)) (options.unlink ?? unlinkSync)(candidate);
+        } catch {
+          // Only the path is allowed to leave this credential-bearing cleanup boundary.
+        }
+        if (existsSync(candidate)) residualPaths.push(candidate);
+      }
+    }
+    const ownedResiduePaths = metadataAfterPivot.entries
+      .filter(entry => isOwnedDesktopGatewayEntry(entry) && !targetIds.includes(entry.id) && SAFE_DESKTOP_PROFILE_ID.test(entry.id))
+      .flatMap(entry => [profilePath(inspected.libraryPath, entry.id), `${profilePath(inspected.libraryPath, entry.id)}.bak`])
+      .filter(existsSync);
+    if (residualPaths.length > 0 || ownedResiduePaths.length > 0) {
+      return {
+        ok: false, changed: true, kind: "cleanup_incomplete", libraryPath: inspected.libraryPath,
+        residualPaths: [...new Set([...residualPaths, ...ownedResiduePaths])],
+      };
+    }
+    // Do not leave a metadata row pointing at a deleted profile. For a foreign
+    // selection this only removes proven opencodex residues; appliedId is kept.
+    atomicWriteFile(
+      metadataPath,
+      JSON.stringify({ ...metadataAfterPivot, entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)) }, null, 2) + "\n",
+    );
+    return { ok: true, changed: true, kind: "removed", libraryPath: inspected.libraryPath };
+  } catch {
+    return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath };
+  }
+}
+
 /** Write and apply the opencodex config in Claude Desktop 3P's config library. */
 export function writeDesktop3pConfig(
   port: number,
@@ -343,7 +562,8 @@ export function writeDesktop3pConfig(
   try {
     mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
     const metadata = parseMetadata(metadataPath);
-    const existing = metadata.entries.find(entry => entry?.name === "opencodex" && typeof entry.id === "string");
+    const selected = metadata.entries.find(entry => entry?.id === metadata.appliedId && isOwnedDesktopGatewayEntry(entry));
+    const existing = selected ?? metadata.entries.find(entry => isOwnedDesktopGatewayEntry(entry) && typeof entry.id === "string");
     const id = existing?.id ?? randomUUID();
     configPath = join(libraryPath, `${id}.json`);
     const entry: Desktop3pMetadataEntry = existing ? { ...existing, id, name: "opencodex" } : { id, name: "opencodex" };

package/src/claude/outbound.ts

@@ -16,6 +16,7 @@ import {
   TranslatorBudgetExceededError,
   type TranslatorBudget,
 } from "../lib/translator-budget";
+import { sseFieldOffset, sseFieldValue } from "../lib/sse-decoder";
 
 type Rec = Record<string, unknown>;
 
@@ -588,10 +589,16 @@ export function responsesSseToAnthropicSse(
                       while (lineStart <= rawFrame.length) {
                         const newline = rawFrame.indexOf("\n", lineStart);
                         const lineEnd = newline === -1 ? rawFrame.length : newline;
-                        if (rawFrame.startsWith("event: ", lineStart)) {
-                          eventName = rawFrame.slice(lineStart + 7, lineEnd).trim();
-                        } else if (rawFrame.startsWith("data: ", lineStart)) {
-                          const fragmentStart = lineStart + 6;
+                        // The space after the colon is optional in text/event-stream (#1170);
+                        // compute the value offset the same way sseFieldValue does, without
+                        // slicing the line first — the byte accounting below is keyed to
+                        // offsets into rawFrame.
+                        const eventOffset = sseFieldOffset(rawFrame, lineStart, lineEnd, "event");
+                        const dataOffset = sseFieldOffset(rawFrame, lineStart, lineEnd, "data");
+                        if (eventOffset !== -1) {
+                          eventName = rawFrame.slice(eventOffset, lineEnd).trim();
+                        } else if (dataOffset !== -1) {
+                          const fragmentStart = dataOffset;
                           const fragmentBytes = utf8SliceBytes(rawFrame, fragmentStart, lineEnd);
                           const fragmentReservation = translatorBudget.reserveTransient(fragmentBytes, { kind: "live_transient" });
                           let fragmentCommitted = false;
@@ -861,8 +868,10 @@ export async function collectAnthropicMessage(
         let eventName = "";
         let dataLine = "";
         for (const line of rawFrame.split("\n")) {
-          if (line.startsWith("event: ")) eventName = line.slice(7).trim();
-          else if (line.startsWith("data: ")) dataLine += line.slice(6);
+          const eventValue = sseFieldValue(line, "event");
+          if (eventValue !== null) { eventName = eventValue.trim(); continue; }
+          const dataValue = sseFieldValue(line, "data");
+          if (dataValue !== null) dataLine += dataValue;
         }
         if (!eventName || !dataLine) continue;
         let data: unknown;

package/src/cli/account-api.ts

@@ -21,6 +21,8 @@ export interface AccountRow {
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */
+  priority?: number;
   quota?: CodexQuotaDto | null;
 }
 
@@ -172,6 +174,7 @@ interface CodexAccountDto {
   plan?: string;
   isMain?: boolean;
   needsReauth?: boolean;
+  priority?: number;
   quota?: CodexQuotaDto | null;
 }
 
@@ -219,6 +222,7 @@ export async function fetchCodexRows(
     plan: a.plan,
     active: a.id === activeId,
     needsReauth: a.needsReauth,
+    priority: typeof a.priority === "number" ? a.priority : 0,
     ...(forceRefresh ? { quota: projectQuota(a.quota) } : {}),
   }));
   return { rows, activeId, autoSwitchThreshold, status: 200 };

package/src/cli/account-extended.ts

@@ -1,4 +1,10 @@
 import { loadConfig } from "../config";
+import {
+  MAX_ACCOUNT_PRIORITY,
+  MIN_ACCOUNT_PRIORITY,
+  normalizeAccountPriority,
+  parseAccountPriority,
+} from "../codex/pool-rotation";
 import {
   apiError,
   apiJson,
@@ -18,6 +24,7 @@ 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 remove <provider> <id|main> --yes [--json]
   ocx account clear-cooldown <provider> <id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]`;
@@ -316,6 +323,111 @@ export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promi
   return 0;
 }
 
+/**
+ * Named selection orders. The words convey sequence rather than rank because the
+ * pool moves down the list only when everything above it is drained — "high
+ * priority" would suggest the account gets more traffic, which is not what
+ * ordering does.
+ */
+const PRIORITY_PRESETS: Record<string, number> = {
+  first: 2,
+  earlier: 1,
+  normal: 0,
+  later: -1,
+  last: -2,
+};
+
+function priorityPresetName(priority: number): string | null {
+  return Object.entries(PRIORITY_PRESETS).find(([, value]) => value === priority)?.[0] ?? null;
+}
+
+function formatPriority(priority: number): string {
+  const preset = priorityPresetName(priority);
+  const signed = priority > 0 ? `+${priority}` : String(priority);
+  return preset ? `${signed} (${preset})` : signed;
+}
+
+/** `null` = reset to the default; `undefined` = unparseable. */
+function parsePriorityArgument(raw: string): number | null | undefined {
+  const word = raw.trim().toLowerCase();
+  if (word === "reset") return null;
+  // Own keys only: `in` also matches "constructor", "__proto__", and friends.
+  if (Object.hasOwn(PRIORITY_PRESETS, word)) return PRIORITY_PRESETS[word];
+  // The regex only rules out shapes Number() would coerce ("1e2", " 1 ", ""); the range
+  // itself comes from the core parser so the CLI cannot drift from what the API accepts.
+  if (!/^[+-]?\d+$/.test(word)) return undefined;
+  return parseAccountPriority(Number(word)) ?? undefined;
+}
+
+export async function cmdPriority(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = args.shift();
+  const requestedPriority = args.shift();
+  if (!name || !requestedId || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  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) {
+    priority = parsePriorityArgument(requestedPriority);
+    if (priority === undefined) {
+      return usage(`Error: selection order must be an integer ${MIN_ACCOUNT_PRIORITY}..${MAX_ACCOUNT_PRIORITY}, one of ${Object.keys(PRIORITY_PRESETS).join("/")}, or reset`);
+    }
+  }
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  // No value means "show" — a read must not rewrite what it is reporting.
+  if (priority === undefined) {
+    const result = await fetchCodexRows(deps, baseUrl);
+    const failed = familyFailure(result, `failed to read ${name} accounts`);
+    if (failed !== null) return failed;
+    const row = result.rows.find(candidate => candidate.id === id);
+    if (!row) return usage(`Error: no ${name} account ${requestedId}`);
+    const current = normalizeAccountPriority(row.priority);
+    if (wantsJson) {
+      console.log(JSON.stringify(
+        { ok: true, provider: name, id, priority: current, preset: priorityPresetName(current) },
+        null,
+        2,
+      ));
+    } else {
+      console.log(`${name}: ${requestedId} selection order is ${formatPriority(current)}`);
+    }
+    return 0;
+  }
+
+  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/priority", { id, priority });
+  if (response.status === 0) return proxyUnreachable();
+  if (response.status !== 200) return apiError(response.json, `failed to set selection order for ${requestedId}`);
+  const applied = typeof response.json.priority === "number" ? response.json.priority : (priority ?? 0);
+  if (wantsJson) {
+    console.log(JSON.stringify(
+      { ok: true, provider: name, id, priority: applied, preset: priorityPresetName(applied) },
+      null,
+      2,
+    ));
+  } else {
+    console.log(`${name}: ${requestedId} selection order is now ${formatPriority(applied)}`);
+  }
+  // Not cmdUse's note: re-ordering takes effect on the next unbound request rather than
+  // only on new sessions, because preemption moves those requests up immediately.
+  console.error("Takes effect from the next unbound request; running threads keep their current account until drained.");
+  // The release is not optional and not conditional on the value changing, so it has to be
+  // stated: this route is the only way to clear a pin without immediately setting another,
+  // which means a write storing the order an account already had still releases it. Without
+  // this line that is a silent side effect of a command that looks purely declarative.
+  console.error('Also releases any manual "use this account now" pin, on any account.');
+  return 0;
+}
+
 export async function cmdAlias(args: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = flag(args, "--json");
   const name = args.shift();

package/src/cli/account.ts

@@ -2,7 +2,7 @@
 import { loadConfig } from "../config";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { OcxConfig } from "../types";
-import { cmdAddKey, cmdAlias, cmdAutoSwitch, cmdClearCooldown, cmdRefresh, cmdRemove } from "./account-extended";
+import { cmdAddKey, cmdAlias, cmdAutoSwitch, cmdClearCooldown, cmdPriority, cmdRefresh, cmdRemove } from "./account-extended";
 import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
   from "./account-api";
 
@@ -22,6 +22,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account alias <provider> <account-or-key-id> <display-name|-> [--json]
+  ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
   ocx account remove <provider> <account-or-key-id|main> --yes [--json]
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
@@ -67,11 +68,24 @@ function statusText(row: AccountRow): string {
   return parts.join(" ");
 }
 
+/** Signed so the sort direction reads off the column; "-" where ordering does not apply. */
+function priorityText(row: AccountRow): string {
+  if (row.priority === undefined) return "-";
+  return row.priority > 0 ? `+${row.priority}` : String(row.priority);
+}
+
 export function formatAccountTable(rows: AccountRow[]): string {
-  const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "STATUS"];
+  const header = ["PROVIDER", "TYPE", "ID", "PLAN/LABEL", "PRIORITY", "STATUS"];
   const data = rows.map(r => {
     const keyLabel = r.masked && r.label !== r.masked ? `${r.masked} (${r.label})` : r.masked;
-    return [r.provider, r.type, displayId(r.id), r.type === "api-key" ? keyLabel ?? "-" : r.label ?? "-", statusText(r)];
+    return [
+      r.provider,
+      r.type,
+      displayId(r.id),
+      r.type === "api-key" ? keyLabel ?? "-" : r.label ?? "-",
+      priorityText(r),
+      statusText(r),
+    ];
   });
   const widths = header.map((h, i) => Math.max(h.length, ...data.map(d => d[i]!.length)));
   const line = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i]!)).join("  ").trimEnd();
@@ -244,9 +258,11 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
   if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, type: c.type, activeId }, null, 2));
   else console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
   if (c.type === "codex") {
-    console.error("Applies to the next request after clearing existing pool affinity; in-flight requests keep their captured account.");
-    console.error("Note: pool strategy, quota/cooldown/reauthentication state, and failure recovery may later select another eligible account.");
-    console.error("Conversation context is replayed after account changes, but the provider-side prompt cache may be cold.");
+    console.error("Takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.");
+    const active = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
+    if (active.status === 200 && typeof active.json.autoSwitchThreshold === "number" && active.json.autoSwitchThreshold > 0) {
+      console.error(`Note: auto-switch (threshold ${active.json.autoSwitchThreshold}%) may override this pin.`);
+    }
   }
   return 0;
 }
@@ -260,6 +276,7 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "refresh") return await cmdRefresh(rest, deps);
     if (sub === "auto-switch") return await cmdAutoSwitch(rest, deps);
     if (sub === "alias" || sub === "rename") return await cmdAlias(rest, deps);
+    if (sub === "priority") return await cmdPriority(rest, deps);
     if (sub === "remove") return await cmdRemove(rest, deps);
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);

package/src/cli/claude-desktop.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
+import { setIntegrationEnabled } from "../codex/desired-state";
 import {
   DESKTOP_FAMILIES,
   moveDesktopRoute,
@@ -41,7 +42,11 @@ export async function applyProfile(
   profile: DesktopProfile,
   mode: Desktop3pConfigMode,
   deps: ApplyProfileDeps = {},
-): Promise<{ ok: boolean; path: string; reason?: string }> {
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  // Explicit apply is an enable action. Persist intent before any Desktop write
+  // so a process crash cannot leave a gateway profile that startup immediately removes.
+  const desired = setIntegrationEnabled("claude-desktop", true);
+  if (!desired.ok) return { ok: false, path: "", reason: desired.message };
   const config = loadConfig();
   const state = await buildClaudeDesktopState(config, profile);
   config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
@@ -52,7 +57,7 @@ export async function applyProfile(
     // serving process installs the map there; a local-only write leaves the
     // daemon unable to decode aliases, and the provider rejects them (400).
     const post = deps.postApplyImpl ?? (async (m: Desktop3pConfigMode, p: DesktopProfile) =>
-      runtimeRequest<{ ok?: boolean; path?: string; error?: string }>(
+      runtimeRequest<{ ok?: boolean; path?: string; error?: string; saved?: boolean; warning?: string }>(
         "/api/claude-desktop/apply",
         // The daemon's config may be older than what we just saved, so the
         // profile travels with the request instead of being re-read there.
@@ -61,12 +66,26 @@ export async function applyProfile(
     try {
       const applied = await post(mode, state.profile);
       if (applied.ok === false) return { ok: false, path: applied.path ?? "", reason: applied.error ?? "daemon apply failed" };
-      return { ok: true, path: applied.path ?? "" };
+      // Partial success: Desktop was written but the applied marker was not
+      // persisted. Pass the degradation up instead of reporting a clean apply.
+      const partial = (applied as { saved?: boolean; warning?: string }).saved === false;
+      return {
+        ok: true,
+        path: applied.path ?? "",
+        ...(partial ? { warning: (applied as { warning?: string }).warning ?? "applied marker was not saved" } : {}),
+      };
     } catch (error) {
       return { ok: false, path: "", reason: error instanceof Error ? error.message : String(error) };
     }
   }
   const allModels = await fetchAllModels(config);
+  // The toggle can persist OFF while fetchAllModels was awaiting (same race the
+  // management writers fence). Re-read persisted intent immediately before the
+  // writer; a lost race is a discriminated skip, not a write.
+  const { claudeDesktopIntegrationEnabledNow } = await import("../codex/desired-state");
+  if (!claudeDesktopIntegrationEnabledNow()) {
+    return { ok: false, path: "", reason: "desired_state_changed" };
+  }
   const routed = filterCatalogVisibleModels(allModels, config).map(model => ({
     provider: model.provider,
     id: model.id,
@@ -111,6 +130,9 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
         return 1;
       }
       console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      // The write landed; only the bookkeeping marker did not. Saying nothing
+      // would leave the saved-vs-applied display wrong with no explanation.
+      if (result.warning) console.warn(`⚠️  ${result.warning}`);
       console.log("Claude Desktop을 완전히 종료한 뒤 다시 열어 주세요.");
       return 0;
     } catch (error) {
@@ -175,6 +197,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       if (flags.includes("--apply")) {
         const result = await applyProfile(reconciled, "static", deps);
         if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
+        if (result.warning) console.warn(`⚠️  ${result.warning}`);
       }
       console.log("Claude Desktop 프로필을 가져왔습니다.");
       return 0;

package/src/cli/config-command.ts

@@ -1,4 +1,5 @@
 import { readFileSync, writeFileSync } from "node:fs";
+import { clearCodexAccountPin } from "../codex/account-priority";
 import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
 import type { OcxConfig } from "../types";
 import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
@@ -102,6 +103,14 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
       const config = validate(candidate);
       const savedValue = action === "unset" ? null : getPath(config, path);
+      // Setting the order here is the operator restating it, exactly as through
+      // `ocx account priority` or the management route, so it releases the manual pin
+      // for the same reason those do: a pin made before any order existed would
+      // otherwise outrank every order set afterwards, capping the pool at the pinned
+      // account's tier with nothing on any surface explaining why. `import` is
+      // deliberately not covered — that file supplies its own pin, so there is no
+      // stale one to release.
+      if (pathSegments(path)[0] === "codexAccountPriorities") clearCodexAccountPin(config);
       saveConfig(config);
       printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
         [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);