@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/adapters/responses-tool-schema.ts

@@ -107,66 +107,96 @@ function usesUnicodePropertyEscape(pattern: string): boolean {
  * preserved: loosening a nested constraint can instead reject an input in those contexts.
  * Unsupported patterns there remain the destination's validation responsibility.
  *
- * Returns `node` itself when nothing was dropped. Uses an explicit stack for caller-controlled
- * nesting depth; the separate Responses-only encrypted-marker normalization is unchanged.
+ * Returns `node` itself when nothing was dropped. Traversal keeps only the active path and clones
+ * only ancestors of a removed constraint, so a broad no-op schema does not create an output tree
+ * or one pending closure per sibling. The explicit stack still handles caller-controlled nesting
+ * depth; the separate Responses-only encrypted-marker normalization is unchanged.
  */
 export function stripUnicodePropertyPatterns(node: unknown, inNameBag = false): unknown {
-  type Assign = (value: unknown) => void;
-  interface Frame { node: unknown; inNameBag: boolean; assign: Assign }
-
-  let result: unknown;
-  let dropped = 0;
-  const stack: Frame[] = [{ node, inNameBag, assign: value => { result = value; } }];
+  interface Frame {
+    node: unknown[] | Record<string, unknown>;
+    inNameBag: boolean;
+    parent?: Frame;
+    parentKey?: string | number;
+    output?: unknown[] | Record<string, unknown>;
+    index?: number;
+    entries?: IterableIterator<[string, unknown]>;
+  }
 
-  while (stack.length > 0) {
-    const frame = stack.pop()!;
-    const current = frame.node;
+  function * ownEntries(value: Record<string, unknown>): IterableIterator<[string, unknown]> {
+    // Unlike Object.entries(), this does not materialize every key/value pair before traversal.
+    for (const key in value) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) yield [key, value[key]];
+    }
+  }
 
-    if (Array.isArray(current)) {
-      const out: unknown[] = new Array(current.length);
-      frame.assign(out);
-      // Array items are schemas in their own right, never a name bag.
-      for (let i = current.length - 1; i >= 0; i--) {
-        stack.push({ node: current[i], inNameBag: false, assign: value => { out[i] = value; } });
-      }
-      continue;
+  function cloneContainer(frame: Frame): unknown[] | Record<string, unknown> {
+    if (frame.output) return frame.output;
+    if (Array.isArray(frame.node)) {
+      frame.output = frame.node.slice();
+      return frame.output;
     }
-    if (!current || typeof current !== "object") {
-      frame.assign(current);
-      continue;
+    const output: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    for (const key in frame.node) {
+      if (Object.prototype.hasOwnProperty.call(frame.node, key)) output[key] = frame.node[key];
     }
+    frame.output = output;
+    return output;
+  }
 
-    // A schema name may be `__proto__`; a null-prototype record keeps it as data.
-    const out: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-    frame.assign(out);
+  function finish(frame: Frame): void {
+    if (!frame.output || !frame.parent) return;
+    const parent = cloneContainer(frame.parent);
+    if (Array.isArray(parent)) parent[frame.parentKey as number] = frame.output;
+    else parent[frame.parentKey as string] = frame.output;
+  }
 
-    for (const [key, value] of Object.entries(current as Record<string, unknown>)) {
-      if (frame.inNameBag) {
-        // Inside a name bag every key is a caller-chosen name, so `pattern` here is a property
-        // name; its value is still a schema and is walked as one.
-        stack.push({ node: value, inNameBag: false, assign: v => { out[key] = v; } });
-        continue;
-      }
-      if (PRESERVED_PATTERN_SUBTREES.has(key)) {
-        out[key] = value;
-        continue;
-      }
-      if (key === "pattern" && typeof value === "string" && usesUnicodePropertyEscape(value)) {
-        dropped++;
+  if (!node || typeof node !== "object") return node;
+  const root: Frame = { node: node as unknown[] | Record<string, unknown>, inNameBag };
+  const stack: Frame[] = [root];
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1]!;
+
+    if (Array.isArray(frame.node)) {
+      const index = frame.index ?? 0;
+      if (index >= frame.node.length) {
+        stack.pop();
+        finish(frame);
         continue;
       }
-      if (SCHEMA_LITERAL_VALUE_KEYS.has(key)) {
-        // Literal payloads are values, not schemas: a `pattern` key inside them is data.
-        out[key] = value;
-        continue;
+      frame.index = index + 1;
+      const child = frame.node[index];
+      if (child && typeof child === "object") {
+        stack.push({ node: child as unknown[] | Record<string, unknown>, inNameBag: false, parent: frame, parentKey: index });
       }
+      continue;
+    }
+
+    frame.entries ??= ownEntries(frame.node);
+    const next = frame.entries.next();
+    if (next.done) {
+      stack.pop();
+      finish(frame);
+      continue;
+    }
+    const [key, value] = next.value;
+    if (!frame.inNameBag && key === "pattern" && typeof value === "string" && usesUnicodePropertyEscape(value)) {
+      delete (cloneContainer(frame) as Record<string, unknown>)[key];
+      continue;
+    }
+    if (!frame.inNameBag && (PRESERVED_PATTERN_SUBTREES.has(key) || SCHEMA_LITERAL_VALUE_KEYS.has(key))) {
+      continue;
+    }
+    if (value && typeof value === "object") {
       stack.push({
-        node: value,
-        inNameBag: SCHEMA_NAME_BAG_KEYS.has(key),
-        assign: v => { out[key] = v; },
+        node: value as unknown[] | Record<string, unknown>,
+        inNameBag: !frame.inNameBag && SCHEMA_NAME_BAG_KEYS.has(key),
+        parent: frame,
+        parentKey: key,
       });
     }
   }
 
-  return dropped === 0 ? node : result;
+  return root.output ?? node;
 }

package/src/adapters/run-turn-queue.ts

@@ -28,6 +28,7 @@ export interface AdapterEventPreflight {
   stream: AsyncIterable<AdapterEvent>;
   error?: Extract<AdapterEvent, { type: "error" }>;
   empty: boolean;
+  replayUnsafe: boolean;
 }
 
 async function* replay(
@@ -51,10 +52,12 @@ export async function preflightAdapterEvents(
 ): Promise<AdapterEventPreflight> {
   const iterator = source[Symbol.asyncIterator]();
   const buffered: AdapterEvent[] = [];
+  let replayUnsafe = false;
   while (true) {
     const next = await iterator.next();
-    if (next.done) return { stream: replay(buffered, iterator), empty: true };
+    if (next.done) return { stream: replay(buffered, iterator), empty: true, replayUnsafe };
     if (next.value.type === "heartbeat") {
+      replayUnsafe ||= next.value.replayUnsafe === true;
       buffered.push(next.value);
       if (buffered.length > PREFLIGHT_HEARTBEAT_RETAIN_LIMIT) buffered.shift();
       continue;
@@ -62,9 +65,9 @@ export async function preflightAdapterEvents(
     buffered.push(next.value);
     if (next.value.type === "error") {
       await iterator.return?.();
-      return { stream: replay(buffered, iterator), error: next.value, empty: false };
+      return { stream: replay(buffered, iterator), error: next.value, empty: false, replayUnsafe };
     }
-    return { stream: replay(buffered, iterator), empty: false };
+    return { stream: replay(buffered, iterator), empty: false, replayUnsafe };
   }
 }
 
@@ -90,7 +93,17 @@ export function createAdapterEventQueue(opts?: {
   const coalesceIntoTail = (event: AdapterEvent): boolean => {
     const tail = queued[queued.length - 1];
     if (!tail) return false;
-    if (event.type === "heartbeat") return tail.type === "heartbeat";
+    if (event.type === "heartbeat") {
+      if (tail.type !== "heartbeat") return false;
+      // Heartbeats carry no ordering between themselves, but the replay-unsafe
+      // marker is not ordering — it is a latch. Dropping the incoming event
+      // would discard the only record that Cursor already performed a local
+      // side effect, and preflight would then permit an OAuth replay of it.
+      if (event.replayUnsafe === true && tail.replayUnsafe !== true) {
+        queued[queued.length - 1] = { type: "heartbeat", replayUnsafe: true };
+      }
+      return true;
+    }
     if (event.type === "text_delta" && tail.type === "text_delta" && tail.phase === event.phase) {
       if (tail.text.length + event.text.length > COALESCE_MAX_CHUNK_LENGTH) return false;
       queued[queued.length - 1] = { type: "text_delta", text: tail.text + event.text, phase: tail.phase };

package/src/bridge/response-json.ts

@@ -203,7 +203,7 @@ function buildResponseJSONWithBudget(
   ): string => {
     const helper = resolveCodeModeHelperName(codeModeHelperName, toolName, args, namespace, options?.declaredToolNames);
     return helper
-      ? compileCodeModeHelperInput(args, helper)
+      ? compileCodeModeHelperInput(args, helper, codeModeHelperName ?? toolName)
       : repairFreeformToolInput(args, toolName, namespace);
   };
   const parseArgsObj = (args: string): Record<string, unknown> => {

package/src/bridge/sse.ts

@@ -16,7 +16,11 @@ import {
   type OcxErrorPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
-import { mayBecomePatchEnvelope, repairFreeformToolInput } from "../responses/apply-patch-envelope";
+import {
+  mayBecomePatchEnvelope,
+  repairFreeformToolInput,
+} from "../responses/apply-patch-envelope";
+import { progressiveFreeformInput } from "../responses/progressive-freeform-input";
 import { encodeCompactionSummary } from "../responses/compaction";
 import { compileCodeModeHelperInput, resolveCodeModeHelperName } from "../responses/code-mode-helper-compat";
 import { isTruncatedStopReason, truncationReasonFor } from "../responses/truncated-stop-reason";
@@ -145,37 +149,9 @@ export function bridgeToResponsesSSE(
   ): string => {
     const helper = resolveCodeModeHelperName(codeModeHelperName, toolName, args, namespace, options?.declaredToolNames);
     return helper
-      ? compileCodeModeHelperInput(args, helper)
+      ? compileCodeModeHelperInput(args, helper, codeModeHelperName ?? toolName)
       : repairFreeformToolInput(args, toolName, namespace);
   };
-  // Best-effort unwrap of a PARTIAL freeform arg buffer for live input streaming
-  // (`response.custom_tool_call_input.delta` — codex-rs uses it for UI preview only;
-  // the completed custom_tool_call item stays authoritative). Compact `{"input":"...`
-  // buffers get their string value progressively unescaped; anything else streams raw.
-  const FREEFORM_WRAP_PREFIX = '{"input":"';
-  const freeformPartialInput = (args: string): string => {
-    if (!args.startsWith(FREEFORM_WRAP_PREFIX)) return args;
-    const body = args.slice(FREEFORM_WRAP_PREFIX.length);
-    let out = "";
-    for (let i = 0; i < body.length; i++) {
-      const c = body[i];
-      if (c === '"') break; // unescaped closing quote: value complete
-      if (c === "\\") {
-        const n = body[i + 1];
-        if (n === undefined) break; // escape split across chunks: wait for more
-        i++;
-        if (n === "n") out += "\n";
-        else if (n === "t") out += "\t";
-        else if (n === "r") out += "\r";
-        else if (n === "u") {
-          const hex = body.slice(i + 1, i + 5);
-          if (hex.length === 4 && /^[0-9a-fA-F]{4}$/.test(hex)) { out += String.fromCharCode(parseInt(hex, 16)); i += 4; }
-          else break; // incomplete \uXXXX: wait for more
-        } else out += n; // \" \\ \/ etc.
-      } else out += c;
-    }
-    return out;
-  };
   // tool_search_call carries arguments as a JSON object ({query, limit}); parse the model's arg string.
   const parseArgsObj = (args: string): Record<string, unknown> => {
     try { const o = JSON.parse(args); return o && typeof o === "object" ? o : {}; } catch { return {}; }
@@ -1075,10 +1051,21 @@ export function bridgeToResponsesSSE(
                   });
                 }
                 if (currentToolCall.freeform && !currentToolCall.codeModeHelperName) {
-                  // Hold while the buffer is still an ambiguous prefix of the JSON wrapper,
-                  // then stream only the unwrapped input suffix (never rewind on mode flips).
-                  if (!FREEFORM_WRAP_PREFIX.startsWith(currentToolCall.args)) {
-                    const full = freeformPartialInput(currentToolCall.args);
+                  // `progressiveFreeformInput` holds while the buffer is still an ambiguous prefix
+                  // of a JSON wrapper; otherwise stream only the unwrapped input suffix, never
+                  // rewinding on a mode flip.
+                  //
+                  // The name is dropped for a namespaced tool that does not own the apply-patch
+                  // grammar, because `repairFreeformToolInput` drops it at completion for the
+                  // same reason. Streaming under a vocabulary the completed item does not use
+                  // is the same disagreement in the other direction.
+                  const ownsFreeformGrammar = currentToolCall.namespace === undefined
+                    || currentToolCall.namespace === "functions";
+                  const full = progressiveFreeformInput(
+                    currentToolCall.args,
+                    ownsFreeformGrammar ? currentToolCall.name : "",
+                  );
+                  if (full !== null) {
                     const emitted = currentToolCall.inputEmitted ?? "";
                     // Also hold a buffer that could still become a complete patch envelope:
                     // at completion such a body is recompiled into an apply_patch helper call,
@@ -1086,7 +1073,13 @@ export function bridgeToResponsesSSE(
                     const mayCompile = declaresCodeModeExec(options?.declaredToolNames)
                       && !currentToolCall.namespace
                       && currentToolCall.name === "exec";
-                    if (!(mayCompile && mayBecomePatchEnvelope(full)) && full.startsWith(emitted) && full.length > emitted.length) {
+                    // `apply_patch` holds for a different reason with the same shape:
+                    // `normalizeApplyPatchDelimiters` rewrites a decorated `*** Begin Patch ***`
+                    // envelope at completion, so streaming the decorated markers would be
+                    // replaced by the normalized ones.
+                    const mayNormalize = ownsFreeformGrammar && currentToolCall.name === "apply_patch";
+                    if (!((mayCompile || mayNormalize) && mayBecomePatchEnvelope(full))
+                      && full.startsWith(emitted) && full.length > emitted.length) {
                       emit("response.custom_tool_call_input.delta", {
                         item_id: currentToolCall.itemId, output_index: currentToolCall.outputIndex,
                         delta: full.slice(emitted.length),

package/src/claude/context-windows.ts

@@ -86,6 +86,28 @@ export function resolveAutoContext(claudeCode: AutoContextConfigSlice | undefine
   return { enabled: true, compactWindow };
 }
 
+/**
+ * Config value -> ENABLE_TOOL_SEARCH wire value (#4838).
+ *
+ * Claude Code parses this variable itself and accepts more than a boolean:
+ * "true", "auto", "auto:N" (N is a percentage floor for non-deferred tools; its
+ * parser rejects anything under 100) and "force", which also overrides an
+ * OS-level managed-settings suppression. Passing a string through verbatim keeps
+ * that whole vocabulary reachable instead of flattening it to a boolean that
+ * would have to be re-expanded here later.
+ *
+ * `false`, absent and blank inject nothing rather than injecting "false". Every
+ * caller injects with user-wins semantics, so an operator's own export survives
+ * either way, and writing "false" would be the one path that could quietly
+ * disagree with it.
+ */
+export function claudeToolSearchEnv(value: boolean | string | undefined): string | undefined {
+  if (value === true) return "true";
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
  * [1m]-marking predicate. Windows >= 1M always mark (CLI accounts exactly 1M).
  * Auto-context additionally marks windows > 200k that can safely host the compact

package/src/claude/outbound.ts

@@ -189,7 +189,27 @@ function webSearchPairFromItem(item: Rec): { id: string; input: Rec; resultConte
   return { id, input, resultContent, completed };
 }
 
-function messageSnapshot(model: string, confirmedUsage?: Rec): Rec {
+/**
+ * `inputTokenFloor` is this proxy's own count of the prompt it forwarded, used only when the
+ * upstream sent no confirmed usage before the first frame.
+ *
+ * Real Anthropic fills `message_start.message.usage.input_tokens` with the turn's prompt size,
+ * and third-party clients read it there — Paseo's context meter takes input from this frame and
+ * output from `message_delta`, so a hardcoded zero showed a nearly-empty ring for a turn whose
+ * `/context` reported ~97k (#4857). #4891 fixed the destinations that report usage up front;
+ * the internal bridge attaches `usage: null` to its lifecycle frames, so those paths had
+ * nothing to report and kept sending zero.
+ *
+ * A floor is a measurement, which is what makes it publishable here: it counts the prompt this
+ * proxy actually sent, the same estimate `claude-messages.ts` already trusts as a log floor. It
+ * 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 {
+  const usage = confirmedUsage
+    ?? (typeof inputTokenFloor === "number" && Number.isFinite(inputTokenFloor) && inputTokenFloor > 0
+      ? { input_tokens: Math.trunc(inputTokenFloor), output_tokens: 0 }
+      : { input_tokens: 0, output_tokens: 0 });
   return {
     id: `msg_${uuid()}`,
     type: "message",
@@ -198,7 +218,7 @@ function messageSnapshot(model: string, confirmedUsage?: Rec): Rec {
     model,
     stop_reason: null,
     stop_sequence: null,
-    usage: confirmedUsage ?? { input_tokens: 0, output_tokens: 0 },
+    usage,
   };
 }
 
@@ -228,7 +248,15 @@ interface OpenBlock {
 export function responsesSseToAnthropicSse(
   upstream: ReadableStream<Uint8Array>,
   model: string,
-  opts: { pingIntervalMs?: number; translatorBudget: TranslatorBudget },
+  opts: {
+    pingIntervalMs?: number;
+    translatorBudget: TranslatorBudget;
+    /**
+     * This proxy's count of the prompt it forwarded, published on `message_start` only when the
+     * upstream sent no confirmed usage before the first frame. See `messageSnapshot` (#4857).
+     */
+    inputTokenFloor?: number;
+  },
 ): ReadableStream<Uint8Array> {
   const translatorBudget = opts.translatorBudget;
   const pingIntervalMs = opts?.pingIntervalMs ?? 20_000;
@@ -283,7 +311,10 @@ export function responsesSseToAnthropicSse(
       const ensureStarted = () => {
         if (started) return;
         started = true;
-        emit("message_start", { type: "message_start", message: messageSnapshot(model, earlyAnthropicUsage) });
+        emit("message_start", {
+          type: "message_start",
+          message: messageSnapshot(model, earlyAnthropicUsage, opts.inputTokenFloor),
+        });
         emit("ping", { type: "ping" });
       };
       // Keepalive pings protect remote deployments behind LB/NAT idle timeouts even

package/src/cli/account-api.ts

@@ -370,9 +370,10 @@ async function fetchOAuthRows(
     email: a.email,
     active: a.active ?? a.id === activeId,
     needsReauth: a.needsReauth,
-    // Forward the server's answer verbatim, including `null`. Collapsing null to "absent" here
-    // would destroy the one distinction this field exists to make.
-    plan: a.plan ?? null,
+    // Forward the server's answer verbatim. An absent key means the proxy predates tier
+    // reporting while `null` means it checked and found no tier — collapsing either
+    // direction would destroy the one distinction this field exists to make.
+    ...(Object.hasOwn(a, "plan") ? { plan: a.plan } : {}),
     ...(a.quota !== undefined ? { quota: a.quota } : {}),
     ...(a.quotaUnavailable !== undefined ? { quotaUnavailable: a.quotaUnavailable } : {}),
     ...(a.quotaUnavailable === true && parseQuotaFailureCode(a.quotaFailure)

package/src/cli/account-extended.ts

@@ -403,16 +403,16 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
     // shared kernel, and absent is a server that does not speak this field at all. Collapsing
     // false into absent would render the live feature as an unknown capability.
     const inert = typeof settings.inert === "boolean" ? settings.inert : null;
-    // A stored threshold only steers selection once the pool consumes it, which is exactly
-    // what `inert: false` reports.
-    const enabled = inert === false && storedThreshold !== null;
+    // A positive stored threshold only steers selection once the pool consumes it, which is
+    // exactly what `inert: false` reports. Zero remains the explicit disabled value.
+    const enabled = inert === false && storedThreshold !== null && storedThreshold > 0;
     if (wantsJson) {
       console.log(JSON.stringify({ provider: name, autoSwitchThreshold: storedThreshold, enabled, poolEnabled, inert }, null, 2));
     } else {
       const value = storedThreshold === null ? "unset" : `${storedThreshold}%`;
       const state = inert === false ? (enabled ? "on" : "off") : inert === true ? "inactive" : "unavailable";
       const why = inert === false
-        ? (enabled ? "applied by this pool" : "no threshold stored")
+        ? (enabled ? "applied by this pool" : storedThreshold === 0 ? "usage-based switching disabled" : "no threshold stored")
         : inert === true ? "not applied by this pool" : "threshold support is unknown";
       console.log(`auto-switch: ${state} (stored threshold ${value}; ${why})`);
     }
@@ -925,12 +925,32 @@ async function poolSetting(
     if (response.status !== 200) return apiError(response.json, `failed to read ${label}`, response.status);
     const strategy = response.json[transport.strategyKey];
     const sticky = response.json[transport.stickyKey];
+    const autoSwitchThreshold = typeof response.json.autoSwitchThreshold === "number"
+      ? response.json.autoSwitchThreshold
+      : undefined;
     if (wantsJson) {
       // Pool-neutral key names: the two routes spell the same two settings differently, and a
       // `--json` consumer should not have to branch on which pool answered.
-      console.log(JSON.stringify({ ok: true, provider: name, strategy, stickyLimit: sticky }, null, 2));
+      const payload: Record<string, unknown> = { ok: true, provider: name, strategy, stickyLimit: sticky };
+      if (autoSwitchThreshold !== undefined) {
+        payload.autoSwitchThreshold = autoSwitchThreshold;
+      }
+      console.log(JSON.stringify(payload, null, 2));
     } else {
-      console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
+      if (field === "strategy" && autoSwitchThreshold !== undefined) {
+        const thresholdSummary = strategy === "round-robin"
+          ? "threshold not used"
+          : autoSwitchThreshold > 0
+          ? (strategy === "fill-first"
+              ? `drain at ${autoSwitchThreshold}%`
+              : strategy === "reset-first"
+              ? `nearest reset below ${autoSwitchThreshold}%`
+              : `switch at ${autoSwitchThreshold}%`)
+          : "proactive switching off";
+        console.log(`${name}: ${label} is ${String(strategy)} (${thresholdSummary})`);
+      } else {
+        console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
+      }
     }
     return 0;
   }

package/src/cli/account-orca-import.ts

@@ -0,0 +1,63 @@
+import type { importOrcaAccounts } from "../codex/orca-import";
+
+const USAGE = "Usage: ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]";
+
+export interface OrcaImportCommandDeps {
+  importAccounts?: typeof importOrcaAccounts;
+}
+
+/** Local-only: never sends source paths or credentials to a management listener. */
+export async function cmdOrcaImport(args: string[], deps: OrcaImportCommandDeps = {}): Promise<number> {
+  let sourceDir: string | undefined;
+  let registryPath: string | undefined;
+  let apply = false;
+  const wantsJson = args.includes("--json");
+  const seen = new Set<string>();
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (seen.has(arg) || !["--source", "--registry", "--apply", "--json"].includes(arg)) {
+      console.error(USAGE);
+      return 1;
+    }
+    seen.add(arg);
+    if (arg === "--source" || arg === "--registry") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) {
+        console.error(USAGE);
+        return 1;
+      }
+      if (arg === "--source") sourceDir = value;
+      else registryPath = value;
+    } else if (arg === "--apply") apply = true;
+  }
+  if (!sourceDir || !registryPath) {
+    console.error(USAGE);
+    return 1;
+  }
+  try {
+    const run = deps.importAccounts ?? (await import("../codex/orca-import")).importOrcaAccounts;
+    const result = await run({ sourceDir, registryPath, apply });
+    if (wantsJson) console.log(JSON.stringify({
+      mode: result.mode, discovered: result.discovered, eligible: result.eligible,
+      imported: result.imported, duplicates: result.duplicates, invalid: result.invalid,
+      invalidReasons: result.invalidReasons,
+    }));
+    else {
+      console.log(`Orca: ${result.discovered} discovered, ${result.eligible} eligible, ${result.imported} imported, ${result.duplicates} duplicates, ${result.invalid} invalid.`);
+      if (result.invalid > 0) {
+        const reasons = Object.entries(result.invalidReasons).map(([reason, count]) => `${reason}=${count}`).join(", ");
+        console.log(`Invalid reasons: ${reasons}`);
+      }
+      console.log(apply
+        ? "Start the proxy and use Refresh quotas in Codex Auth to validate new accounts. Orca retains refresh ownership."
+        : "Preview only. Stop the proxy before repeating with --apply. Orca authentication files stay read-only.");
+    }
+    return result.invalid > 0 && result.eligible === 0 ? 1 : 0;
+  } catch {
+    // Filesystem/JSON exceptions may contain source paths or token fragments.
+    const error = "Orca import failed. Check the source, destination config, and stopped proxy; no successful completion is confirmed.";
+    if (wantsJson) console.log(JSON.stringify({ error: "orca_import_failed" }));
+    else console.error(error);
+    return 1;
+  }
+}

package/src/cli/account.ts

@@ -57,6 +57,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
   ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]
+  ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]
   ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
@@ -323,13 +324,36 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
   if (res.status === 0) return proxyUnreachable(res.transportError);
   if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`, res.status);
 
-  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)}`);
+  // The route reports this only when routing would drop the pin it just recorded, so an
+  // absent field means the pin survives (#4521).
+  const pinDrainReason = typeof res.json.pinDrainReason === "string" ? res.json.pinDrainReason : undefined;
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      ok: true,
+      provider: name,
+      type: c.type,
+      activeId,
+      ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    }, null, 2));
+  } else {
+    console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
+  }
   if (c.type === "codex") {
     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.`);
+    const threshold = active.status === 200 && typeof active.json.autoSwitchThreshold === "number"
+      ? active.json.autoSwitchThreshold
+      : undefined;
+    if (pinDrainReason !== undefined) {
+      // "may override" is the right caveat for a pin that is currently fine and could be
+      // overtaken later. It is the wrong sentence for one the next request will discard, and
+      // printing only that is what left the operator believing the account was pinned.
+      const because = pinDrainReason === "quota_threshold"
+        ? `is at or above the auto-switch threshold${threshold !== undefined ? ` (${threshold}%)` : ""}`
+        : `cannot currently be selected (${pinDrainReason})`;
+      console.error(`Note: ${displayId(activeId)} ${because}, so routing releases this pin on its next request.`);
+    } else if (threshold !== undefined && threshold > 0) {
+      console.error(`Note: auto-switch (threshold ${threshold}%) may override this pin.`);
     }
   }
   return 0;
@@ -360,6 +384,10 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);
     if (sub === "import") return await cmdImport(rest, deps);
+    if (sub === "import-orca") {
+      const { cmdOrcaImport } = await import("./account-orca-import");
+      return await cmdOrcaImport(rest);
+    }
     if (sub === "main") {
       const { cmdNativeMainAccount } = await import("./account-main");
       return await cmdNativeMainAccount(rest, deps);