@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/lib/request-resend-gate.ts

@@ -0,0 +1,138 @@
+/**
+ * Whether one leg of a logical request may send it again, asked in the #5266 vocabulary.
+ *
+ * Two pull requests arrived at this question from opposite sides of the response head. #4942
+ * asked it for a connection that died before any head; #4989 asked it for an SSE body that
+ * died after the head while carrying only control events. Both are the same row of the stage
+ * table: a stage the caller observed nothing at, with a cause that cannot prove the origin did
+ * not run the turn. `resendPermission` answers `refused-ambiguous` for both, and
+ * request-failure-model.ts already names the only thing that may override that answer -- a
+ * narrowly scoped recovery a maintainer opted into and bounded.
+ *
+ * One override, not two. The reason this module exists rather than a boolean in each caller is
+ * that a request which resets before the head and again after it would otherwise buy a
+ * replacement send on each side, and the second one is exactly the duplicated inference the
+ * refusal exists to prevent. The allowance is claimed HERE, at the moment of authorisation, so
+ * a caller cannot ask without paying.
+ *
+ * MUST stay a leaf. It imports the vocabulary as values and everything else as types, so it
+ * reaches no request path that did not already have it.
+ */
+import {
+  causeForRecoveryKind,
+  permitsResend,
+  resendPermission,
+  resendSendClass,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type ResendPermission,
+} from "./request-failure-model";
+import type { SendClass } from "./request-execution-budget";
+import type { AttemptRecoveryKind } from "../usage/telemetry-contract";
+
+/**
+ * Why an authorisation was refused.
+ *
+ * The three ambiguous members are separate because they need different operator responses: no
+ * policy is a configuration choice, a request the proxy cannot judge is a property of the turn,
+ * and a spent allowance means the replacement already went somewhere else in this request.
+ */
+export const RESEND_REFUSALS = Object.freeze([
+  /** The caller already observed output, an effect, or the delivered answer. */
+  "committed",
+  /** Identical bytes would get the identical answer. */
+  "futile",
+  /** The origin's execution state is unknown and no operator policy overrides that. */
+  "ambiguous-no-policy",
+  /** An operator policy exists, but this request's second send could do more than re-infer. */
+  "ambiguous-request-not-replayable",
+  /** The operator policy exists and its replacement was already spent by this request. */
+  "ambiguous-allowance-spent",
+] as const);
+
+export type ResendRefusal = typeof RESEND_REFUSALS[number];
+
+/**
+ * The operator-granted replacement for ONE logical request.
+ *
+ * `claim` is the single counter both stages draw on. It is a method rather than a number
+ * because the holder is the request's send ledger, which a combo child shares with its parent;
+ * a number passed down per leg is what let each leg hold its own.
+ */
+export interface AmbiguousResendAllowance {
+  /** True when a second send of this request's body can only repeat the inference. */
+  readonly selfContained: boolean;
+  /** Spend one replacement. False once the request has none left. */
+  claim(): boolean;
+}
+
+interface ResendDecisionBase {
+  readonly stage: RequestFailureStage;
+  readonly cause: RequestFailureCause;
+  readonly permission: ResendPermission;
+  /**
+   * The recovery this send will be recorded as, when the caller asked in those terms. Carried
+   * back rather than re-chosen at the call site: the cause was derived from it, so recording a
+   * different kind would describe the send by a reason the gate never evaluated.
+   */
+  readonly recoveryKind?: AttemptRecoveryKind;
+}
+
+export type ResendDecision =
+  | ResendDecisionBase & {
+    readonly allowed: true;
+    /** Which request-wide send class funds it, or null when the cause funds no resend. */
+    readonly sendClass: SendClass | null;
+    /** True when the table refused and an operator allowance was spent to proceed. */
+    readonly spentOperatorAllowance: boolean;
+  }
+  | ResendDecisionBase & { readonly allowed: false; readonly refusal: ResendRefusal };
+
+/**
+ * Decide whether this proxy may send the request again after a failure at `stage` caused by
+ * `cause`, spending `allowance` when the table refuses only because the upstream state is
+ * unknown.
+ *
+ * The allowance is touched on exactly one path: a decision the table would otherwise refuse as
+ * ambiguous, for a request whose body the caller has judged replayable. A committed or futile
+ * failure never reaches it, so a turn that already produced output cannot quietly drain the
+ * replacement a later ambiguous reset would have been entitled to.
+ */
+export function authorizeResend(
+  stage: RequestFailureStage,
+  cause: RequestFailureCause,
+  allowance?: AmbiguousResendAllowance,
+  recoveryKind?: AttemptRecoveryKind,
+): ResendDecision {
+  const permission = resendPermission(stage, cause);
+  const base = { stage, cause, permission, ...(recoveryKind ? { recoveryKind } : {}) };
+  if (permitsResend(permission)) {
+    return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: false };
+  }
+  if (permission === "refused-committed") return { ...base, allowed: false, refusal: "committed" };
+  if (permission === "refused-futile") return { ...base, allowed: false, refusal: "futile" };
+  if (!allowance) return { ...base, allowed: false, refusal: "ambiguous-no-policy" };
+  if (!allowance.selfContained) {
+    return { ...base, allowed: false, refusal: "ambiguous-request-not-replayable" };
+  }
+  // Claimed last, and only here. Asking earlier would spend the request's one replacement on a
+  // question whose answer was already no.
+  if (!allowance.claim()) return { ...base, allowed: false, refusal: "ambiguous-allowance-spent" };
+  return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: true };
+}
+
+/**
+ * The same decision, asked in terms of the recovery this proxy will RECORD for the send.
+ *
+ * Deriving the cause from the recorded kind is what keeps the log honest: the reason an
+ * operator reads beside a send count is the reason the gate weighed, because it is the same
+ * value. A call site that recorded one kind and reasoned about another is how a send count
+ * stops meaning anything.
+ */
+export function authorizeResendForRecovery(
+  stage: RequestFailureStage,
+  kind: AttemptRecoveryKind,
+  allowance?: AmbiguousResendAllowance,
+): ResendDecision {
+  return authorizeResend(stage, causeForRecoveryKind(kind), allowance, kind);
+}

package/src/lib/standalone.ts

@@ -0,0 +1,16 @@
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Compiled Bun binaries expose their bundled module tree through the `$bunfs` marker. */
+export function isStandaloneBinary(): boolean {
+  return isStandaloneModuleUrl(import.meta.url);
+}
+
+export function isStandaloneModuleUrl(url: string): boolean {
+  return url.includes("/$bunfs/") || /^file:\/\/\/[A-Za-z]:\/~BUN\//.test(url);
+}
+
+/** Directory containing the compiled executable and its copied runtime assets. */
+export function standaloneRoot(): string {
+  return dirname(realpathSync(process.execPath));
+}

package/src/lib/upstream-retry.ts

@@ -8,13 +8,15 @@
  * becomes a terminal, non-replayable response unless the operation is explicitly safe.
  *
  * Deliberately narrow: timeouts, aborts, ECONNREFUSED/DNS/TLS failures, and HTTP error
- * statuses (returned as Response, never thrown) are NOT retried. Mid-stream SSE resets are
- * out of scope — the response has already resolved by then.
+ * statuses (returned as Response, never thrown) are NOT retried. A reset after the response
+ * head is out of scope here, because the response has already resolved by then; the Responses
+ * transport asks the same question at that stage through the shared resend gate.
  *
  * MUST stay a leaf module: imports nothing from server.ts or adapters (kiro-retry imports
  * the shared abort helpers from here).
  */
 import { clearableDeadline } from "./abort";
+import { redactSecretString } from "./redact";
 
 /**
  * Responses the origin may already be executing. RFC 9110 §9.2.2 forbids an intermediary
@@ -96,6 +98,55 @@ export function isReplayRefusalCode(code: unknown): boolean {
 /** Client-facing status for {@link UPSTREAM_RESET_REPLAY_REFUSED_CODE}. */
 export const REPLAY_REFUSED_STATUS = 429;
 
+/**
+ * The header every surface attaches to a replay refusal, and its only accepted value.
+ *
+ * Dropping `Retry-After` is necessary and not sufficient. The Stainless-generated clients --
+ * `openai` and `anthropic` for both Python and Node, which is what most callers of this proxy
+ * actually are -- decide from a status table (408, 409, 429 and every 5xx) and compute their own
+ * backoff when no wait is named, so a 429 with no header is still resent. `x-should-retry` is
+ * the one signal each of them reads BEFORE that table, and `"false"` is the exact string they
+ * compare against.
+ */
+export const REPLAY_REFUSAL_NO_RETRY_HEADER = "x-should-retry";
+export const REPLAY_REFUSAL_NO_RETRY_VALUE = "false";
+
+/** Spreadable form for the surfaces that build their headers as an object literal. */
+export const REPLAY_REFUSAL_CLIENT_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  [REPLAY_REFUSAL_NO_RETRY_HEADER]: REPLAY_REFUSAL_NO_RETRY_VALUE,
+});
+
+/**
+ * Apply the one client-facing retry policy a refusal carries: no wait, and no automatic resend.
+ *
+ * Kept as a single function rather than two rules each surface repeats, because the two halves
+ * are only correct together -- a surface that removed the wait but not the suppression still
+ * hands a retrying client a turn it may already have run.
+ */
+export function applyReplayRefusalClientHeaders(headers: Headers): void {
+  headers.delete("retry-after");
+  headers.set(REPLAY_REFUSAL_NO_RETRY_HEADER, REPLAY_REFUSAL_NO_RETRY_VALUE);
+}
+
+/**
+ * Mark a response that re-wraps a refusal as the same refusal.
+ *
+ * The verdict has to be a property of the result the surfaces pass around, because the thing it
+ * would otherwise be read from is the status, and 429 is exactly what a refusal and a real rate
+ * limit have in common. Every formatter between the helper that made the refusal and the client
+ * builds a new Response, so each of them restates the verdict rather than dropping it.
+ */
+export function retainReplayRefusal<T extends Response>(response: T): T {
+  markResponseNonReplayable(response);
+  markReplayRefusalResponse(response);
+  return response;
+}
+
+/** Carry the verdict from a response onto the one that replaces it. */
+export function carryReplayRefusal<T extends Response>(source: Response, rewrapped: T): T {
+  return isReplayRefusalResponse(source) ? retainReplayRefusal(rewrapped) : rewrapped;
+}
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -421,6 +472,20 @@ export interface ResetRetryOptions {
    * uncounted but UNCOUNTABLE: the callback existed on a type those call sites never reach.
    */
   onSendsConsumed?: (sends: number) => void;
+  /**
+   * Spend one operator-granted replacement for a pre-header reset this helper would otherwise
+   * refuse. Absent means no operator policy, which is the fail-closed answer.
+   *
+   * A callback rather than a count, and the difference is the whole point. A count handed to
+   * each leg of a request is a count each leg holds: a rotation leg, a refresh leg and a
+   * same-target 429 leg carry the same turn, so three numbers is three replacements of one
+   * possibly-executed inference. The callback draws on ONE allowance held by the logical
+   * request, which the post-header protocol gate draws on too.
+   *
+   * It never widens the send budget. A claimed replacement still has to fit inside
+   * `attempts`, exactly like every other send this leg makes.
+   */
+  claimAmbiguousResend?: () => boolean;
 }
 
 export interface TransientRetryOptions extends ResetRetryOptions {
@@ -494,6 +559,24 @@ export function applyUpstreamRecoveryInit<T extends RequestInit>(
   return { ...init, headers, keepalive: false };
 }
 
+/**
+ * The refusal this proxy returns for an ambiguous reset it will not replace. The WeakSet
+ * markers protect in-process recovery and the code survives JSON re-wrapping, so a combo or
+ * account-recovery layer downstream cannot read it as a replayable upstream fault. The raw
+ * exception is never exposed: it can carry credentials or request data.
+ */
+export function replayRefusalResponse(): Response {
+  const response = new Response(JSON.stringify({ error: {
+    type: "upstream_error",
+    code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+    message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
+  } }), {
+    status: REPLAY_REFUSED_STATUS,
+    headers: { "content-type": "application/json", ...REPLAY_REFUSAL_CLIENT_HEADERS },
+  });
+  return retainReplayRefusal(response);
+}
+
 /**
  * Run `doFetch` within one send budget. Connection-reset-shaped rejections are
  * terminal by default; only an explicitly replay-safe operation receives reset retries
@@ -511,6 +594,10 @@ export async function fetchWithResetRetry(
   if (attempts === 0) throw new SendBudgetExhaustedError(opts.label);
   let lastError: unknown;
   let sawReset = false;
+  // True once this leg has spent the request's operator allowance. From that point the leg can
+  // only settle as the refusal: a second send of a possibly-executed turn is already out, and
+  // handing the client anything it would retry compounds it.
+  let spentOperatorReplacement = false;
   for (let attempt = 0; attempt < attempts; attempt++) {
     if (opts.abortSignal?.aborted) throw abortError(opts.abortSignal);
     // Reported before the await, one physical send at a time: a send that rejects has still
@@ -522,31 +609,37 @@ export async function fetchWithResetRetry(
     } catch (err) {
       if (opts.abortSignal?.aborted) throw err;
       if (!isConnectionResetError(err)) {
+        // Whatever ended the leg, an operator replacement already went out, so the first send
+        // may have run the turn. Settle it as the refusal instead of throwing into a caller
+        // whose transport-failure path answers with a client-retryable 502.
+        if (spentOperatorReplacement) return replayRefusalResponse();
         // A reset that already reached the origin is credential-visible
         // evidence: keep it attached so the terminal rejection cannot be
         // downgraded to the pre-connection neutral class (#914 review).
         if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
         throw err;
       }
-      if (opts.replaySafe !== true) {
-        // Return evidence instead of throwing a generic transport error: outer catches
+      if (opts.replaySafe === true) {
+        // Repeating this operation cannot duplicate anything, so an exhausted budget rethrows
+        // and the caller's own error path takes over.
+        if (attempt === attempts - 1) throw err;
+      } else {
+        // The stage table refuses an ambiguous pre-header reset. The only thing that overrides
+        // it is an operator allowance, and claiming it here is what keeps the grant single --
+        // the post-header protocol gate spends the same counter for the same logical request.
+        // Return evidence rather than throwing a generic transport error: outer catches
         // otherwise turn it into a replayable 502 and a combo/account recovery resends it.
-        // The WeakSet protects in-process recovery; the code survives JSON re-wrapping.
-        // Never expose the raw exception, which can contain credentials or request data.
-        const response = new Response(JSON.stringify({ error: {
-          type: "upstream_error",
-          code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
-          message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
-        } }), { status: REPLAY_REFUSED_STATUS, headers: { "content-type": "application/json" } });
-        markResponseNonReplayable(response);
-        markReplayRefusalResponse(response);
-        return response;
+        if (attempt + 1 >= attempts || opts.claimAmbiguousResend?.() !== true) {
+          return replayRefusalResponse();
+        }
+        spentOperatorReplacement = true;
       }
-      if (attempt === attempts - 1) throw err;
       sawReset = true;
       lastError = err;
       console.warn(
-        `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
+        `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — ${
+          spentOperatorReplacement ? "replacing" : "retrying"
+        } (${attempt + 2}/${attempts})`,
       );
       await sleepWithAbort(retryBackoffDelayMs(attempt, {
         baseDelayMs: RESET_RETRY_BASE_DELAY_MS,
@@ -661,3 +754,61 @@ export async function fetchWithTransientRetry(
     opts.onSendsConsumed?.(sent);
   }
 }
+
+export type ProtocolSafeRefetch = (signal?: AbortSignal) => Promise<Response>;
+
+export interface ProtocolSafeRefetchOptions extends ResetRetryOptions {
+  /** The replacement must match the response contract already selected for the client. */
+  acceptResponse?: (response: Response) => boolean;
+  /**
+   * Spend the logical request's allowance, immediately before the replacement send.
+   *
+   * Asked here and not earlier so a failure this helper would refuse on its own terms -- a
+   * non-reset error, a cancelled caller, a spent send budget -- cannot drain the one
+   * replacement a later ambiguous reset was entitled to. False refuses the replacement.
+   */
+  authorize?: () => boolean;
+}
+
+/**
+ * Attempt ONE caller-authorized replacement of a stream that died after the response head.
+ *
+ * The caller owns the proof that nothing was observed -- it comes from protocol inspection,
+ * not from this module -- and owns the physical-send budget. What lives here is the part that
+ * is easy to get wrong: a replacement is only usable if it is a fresh, unlocked, unread body
+ * that matches the contract already promised to the client, and anything else has to be
+ * cancelled and the original failure preserved.
+ */
+export async function refetchAfterProtocolSafeReset(
+  doFetch: ProtocolSafeRefetch,
+  err: unknown,
+  opts: ProtocolSafeRefetchOptions = {},
+): Promise<Response | null> {
+  if (!isConnectionResetError(err) || opts.abortSignal?.aborted || opts.attempts === 0) return null;
+  const label = opts.label
+    ? " (" + redactSecretString(opts.label).replace(/[\r\n\u0000-\u001f\u007f]/g, "").slice(0, 128) + ")"
+    : "";
+  if (opts.authorize && !opts.authorize()) {
+    console.warn("[upstream-retry] post-header reset replacement refused" + label + "; preserving original stream error");
+    return null;
+  }
+  let replacement: Response;
+  try {
+    replacement = await doFetch(opts.abortSignal);
+  } catch {
+    console.warn("[upstream-retry] protocol-safe refetch failed" + label + "; preserving original stream error");
+    return null;
+  }
+  const body = replacement.body;
+  let accepted = !opts.abortSignal?.aborted && replacement.ok && body !== null
+    && !replacement.bodyUsed && !body.locked && !isNonReplayableResponse(replacement);
+  try { if (accepted && opts.acceptResponse) accepted = opts.acceptResponse(replacement); }
+  catch { accepted = false; }
+  if (!accepted || opts.abortSignal?.aborted || body?.locked) {
+    try { void body?.cancel().catch(() => {}); } catch { /* already locked or closed */ }
+    console.warn("[upstream-retry] protocol-safe refetch rejected" + label + "; preserving original stream error");
+    return null;
+  }
+  console.warn("[upstream-retry] pre-output Responses reset" + label + "; using one replacement stream");
+  return replacement;
+}

package/src/lib/winsw.ts

@@ -72,7 +72,7 @@ export interface WinswEntry {
   bun: string;
   /** Provenance of `bun`, resolved together with it so the two can never disagree. */
   bunRuntimeSource: BunRuntimeSource;
-  cli: string;
+  cli: string | null;
 }
 
 /**
@@ -118,7 +118,7 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   <name>OpenCodex Proxy (native)</name>
   <description>OpenCodex proxy running as a native Windows service (windowless, starts at boot).</description>
   <executable>${xmlEscape(entry.bun)}</executable>
-  <arguments>${xmlEscape(`"${entry.cli}" start --port ${safeListenPort}`)}</arguments>
+  <arguments>${xmlEscape(`${entry.cli ? `"${entry.cli}" ` : ""}start --port ${safeListenPort}`)}</arguments>
 ${envLines.join("\n")}
   <logpath>${xmlEscape(winswLogDir())}</logpath>
   <log mode="roll-by-size">

package/src/oauth/index.ts

@@ -1273,6 +1273,29 @@ const OAUTH_RECONCILE_FIELDS: (keyof OcxProviderConfig)[] = [
 // existing rows through enrichProviderFromRegistry, which is fill-only and
 // preserves explicit saved values.
 
+/**
+ * Output-budget fields an OAuth preset may refresh but must never erase.
+ *
+ * These stay on the reconcile list so a preset that does declare a budget still
+ * refreshes the saved row. What changes is the other branch: when the preset
+ * declares nothing, the operator's value survives instead of being deleted.
+ *
+ * Without that, the fields behaved as if they could not be configured at all.
+ * No OAuth preset seeds either one, so the delete branch was the only branch
+ * these two ever took, and a hand-edited `defaultMaxOutputTokens` was gone
+ * before the first turn of the next startup — leaving the adapter's own
+ * fallback as the only reachable output cap (#5190).
+ *
+ * Scoped to the output budget on purpose. The input side (`contextWindow`,
+ * `modelContextWindows`) describes what the account's models are, which the
+ * preset and live discovery do own; an output budget is a spend decision the
+ * operator makes.
+ */
+const OAUTH_PRESERVE_WHEN_PRESET_UNSET: ReadonlySet<keyof OcxProviderConfig> = new Set([
+  "defaultMaxOutputTokens",
+  "modelMaxOutputTokens",
+]);
+
 const GOOGLE_ANTIGRAVITY_PROVIDER = "google-antigravity";
 const GOOGLE_ANTIGRAVITY_LIVE_DISCOVERY_VERSION = 2 as const;
 
@@ -1312,7 +1335,7 @@ function applyOAuthPresetCatalog(
     if (JSON.stringify(provider[field]) === JSON.stringify(preset[field])) continue;
     if (preset[field] !== undefined) {
       provider[field] = cloneProviderField(preset[field]) as never;
-    } else {
+    } else if (!OAUTH_PRESERVE_WHEN_PRESET_UNSET.has(field)) {
       delete provider[field];
     }
   }

package/src/oauth/login-cli.ts

@@ -2,6 +2,7 @@ import * as readline from "node:readline";
 import { modelSelectionGuidance } from "../cli/model-selection-guidance";
 import { initializeProviderModelSelection } from "../providers/initial-model-selection";
 import { openUrl } from "../lib/open-url";
+import { createBrowserLaunchReport } from "../lib/browser-launch-notice";
 import { loadConfig, saveConfig } from "../config";
 import { findLiveProxy } from "../server/proxy-liveness";
 import {
@@ -14,6 +15,41 @@ import type { OcxConfig, OcxProviderConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 
+/**
+ * Seams a test drives in place of a browser, a terminal and a real provider. Production passes
+ * none of them.
+ *
+ * They exist because the thing worth proving here is an ORDER — that a browser which did not
+ * open is on screen before the question that assumes it did — and an order is only observable
+ * from something that records both events. Spawning a launcher and attaching to stdin to find
+ * that out would test the operating system instead.
+ */
+export interface LoginCliDeps {
+  runLogin?: typeof runLogin;
+  openUrl?: typeof openUrl;
+  warn?: (message: string) => void;
+  /** Ask one question, read one line. Defaults to a readline prompt that owns its own lifetime. */
+  ask?: (question: string) => Promise<string>;
+}
+
+/**
+ * Run `body` with a line reader, creating and closing a real one only when the caller did not
+ * supply its own. A readline interface attaches to stdin, so building one that nothing will ask
+ * a question keeps the process alive for no reason.
+ */
+async function withPrompt<T>(
+  supplied: ((question: string) => Promise<string>) | undefined,
+  body: (ask: (question: string) => Promise<string>) => Promise<T>,
+): Promise<T> {
+  if (supplied) return await body(supplied);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await body(question => new Promise<string>(resolve => rl.question(question, resolve)));
+  } finally {
+    rl.close();
+  }
+}
+
 const LIVE_RELOAD_PROVIDERS = new Set<string>([
   ...listOAuthProviders(),
   ...Object.keys(KEY_LOGIN_PROVIDERS),
@@ -83,7 +119,7 @@ export function loginUsageMessage(): string {
     + `  API-key login: ${Object.keys(KEY_LOGIN_PROVIDERS).join(", ")}`;
 }
 
-export async function handleLogin(provider?: string): Promise<void> {
+export async function handleLogin(provider?: string, deps: LoginCliDeps = {}): Promise<void> {
   const name = (provider ?? "").trim().toLowerCase();
   // A removed provider id reached through its alias still logs in — the merged
   // successor owns the flow. Warn rather than silently reroute so scripts and
@@ -91,30 +127,40 @@ export async function handleLogin(provider?: string): Promise<void> {
   const alias = DEPRECATED_OAUTH_PROVIDER_ALIASES[name];
   if (alias) {
     console.error(`${name} is deprecated; logging in as ${alias}`);
-    return handleOAuthLogin(alias);
+    return handleOAuthLogin(alias, deps);
   }
-  if (isPublicOAuthProvider(name)) return handleOAuthLogin(name);
-  if (isKeyLoginProvider(name)) return handleKeyLogin(name);
+  if (isPublicOAuthProvider(name)) return handleOAuthLogin(name, deps);
+  if (isKeyLoginProvider(name)) return handleKeyLogin(name, deps);
   console.error(loginUsageMessage());
   process.exit(1);
 }
 
-async function handleOAuthLogin(name: string): Promise<void> {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    await runLogin(name, {
+export async function handleOAuthLogin(name: string, deps: LoginCliDeps = {}): Promise<void> {
+  const login = deps.runLogin ?? runLogin;
+  const launch = deps.openUrl ?? openUrl;
+  const browser = createBrowserLaunchReport(deps.warn);
+  await withPrompt(deps.ask, async (ask) => {
+    await login(name, {
       onAuth: ({ url, instructions }) => {
         console.log(`\n🔐 Opening browser for ${name} login...\n${url}\n`);
         if (instructions) console.log(instructions);
-        openUrl(url);
+        // The controller does not await onAuth, so the launcher's answer cannot be reported from
+        // here — this returns long before it arrives. It reports itself instead, and the one
+        // thing that could collide with it waits below (#5261).
+        browser.track(launch(url));
       },
       onProgress: (m) => console.log(`   ${m}`),
-      onManualCodeInput: () =>
-        new Promise((res) => rl.question("Paste redirect URL or code (or wait for browser): ", res)),
+      onManualCodeInput: async () => {
+        // "or wait for browser" is a lie if nothing opened, and a warning printed after readline
+        // has drawn the prompt lands on the line the user is typing on.
+        await browser.settled();
+        return await ask("Paste redirect URL or code (or wait for browser): ");
+      },
     });
-  } finally {
-    rl.close();
-  }
+  });
+  // A device or polling provider never prompts, so nothing above waited on the launcher. It is
+  // still owed an answer before this claims the login worked.
+  await browser.settled();
   const reload = await notifyRunningProxyAfterOAuthLogin(name);
   console.log(`\n✅ Logged in to ${name}. Try: ocx sync`);
   for (const line of modelSelectionGuidance(name)) console.log(line);
@@ -192,8 +238,9 @@ export async function commitKeyLoginProvider(
   return mergedProvider;
 }
 
-async function handleKeyLogin(name: string): Promise<void> {
+export async function handleKeyLogin(name: string, deps: LoginCliDeps = {}): Promise<void> {
   const def = KEY_LOGIN_PROVIDERS[name];
+  const launch = deps.openUrl ?? openUrl;
   const preflightConfig = loadConfig();
   const namespaceCollision = codexAccountNamespaceProviderCollisionError(preflightConfig.codexAccountNamespaces, name);
   if (namespaceCollision) {
@@ -201,21 +248,25 @@ async function handleKeyLogin(name: string): Promise<void> {
     process.exit(1);
   }
   console.log(`\n🔑 ${def.label} — opening ${def.dashboardUrl} so you can create/copy an API key...`);
-  openUrl(def.dashboardUrl);
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const key = (await new Promise<string>((res) => rl.question(`Paste your ${def.label} API key: `, res))).trim();
-  // Template URL with placeholders needs resolution before saving.
-  let baseUrl = def.baseUrl;
-  if (/\{[^}]*\}/.test(baseUrl)) {
-    const resolved = (await new Promise<string>((res) => rl.question(`Your endpoint URL (${baseUrl}): `, res))).trim();
-    if (!resolved) {
-      rl.close();
-      console.error("A resolved URL is required — replace the {placeholder} with your actual value.");
-      process.exit(1);
+  const browser = createBrowserLaunchReport(deps.warn);
+  browser.track(launch(def.dashboardUrl));
+  // The next question asks for a key the user gets FROM that page, so a page that never opened
+  // has to be on screen before the question rather than underneath it (#5261).
+  await browser.settled();
+  const { key, baseUrl } = await withPrompt(deps.ask, async (ask) => {
+    const entered = (await ask(`Paste your ${def.label} API key: `)).trim();
+    // Template URL with placeholders needs resolution before saving.
+    let resolvedBaseUrl = def.baseUrl;
+    if (/\{[^}]*\}/.test(resolvedBaseUrl)) {
+      const resolved = (await ask(`Your endpoint URL (${resolvedBaseUrl}): `)).trim();
+      if (!resolved) {
+        console.error("A resolved URL is required — replace the {placeholder} with your actual value.");
+        process.exit(1);
+      }
+      resolvedBaseUrl = resolved;
     }
-    baseUrl = resolved;
-  }
-  rl.close();
+    return { key: entered, baseUrl: resolvedBaseUrl };
+  });
   if (!key) {
     console.error("No key entered.");
     process.exit(1);