codex-multi-auth 2.3.0-beta.0 → 2.3.0-beta.2

package/dist/lib/runtime/first-run.js

@@ -0,0 +1,327 @@
+// Lazy first-run setup (audit roadmap §4.5.4).
+//
+// The npm postinstall script used to detect the packaged Codex desktop app,
+// auto-bind runtime rotation, and install OS launcher shortcuts. That work now
+// runs here, on the first CLI invocation, so package installs stay
+// side-effect-free. The hook is guarded by a marker file under the runtime
+// root (~/.codex/multi-auth), claimed with an exclusive create so concurrent
+// first invocations run the setup at most once, and every step is best-effort:
+// a failure is debug-logged (messages only — never tokens or emails) and the
+// command proceeds normally.
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { open, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { getCodexRuntimeRotationProxy, loadPluginConfig } from "../config.js";
+import { withFileOperationRetry } from "../fs-retry.js";
+import { createLogger } from "../logger.js";
+import { getCodexMultiAuthDir } from "../runtime-paths.js";
+import { bindCodexAppRuntimeRotation, getAppBindStatus } from "./app-bind.js";
+const log = createLogger("first-run");
+const FIRST_RUN_MARKER_FILE = "first-run-setup.json";
+export const FIRST_RUN_MARKER_VERSION = 1;
+const TRUE_VALUES = new Set(["1", "true", "yes"]);
+const FALSE_VALUES = new Set(["0", "false", "no"]);
+const CI_ENV_KEYS = [
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "BUILDKITE",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+    "JENKINS_URL",
+    "TRAVIS",
+    "APPVEYOR",
+    "BITBUCKET_BUILD_NUMBER",
+];
+export function readOptionalBoolean(value) {
+    if (value === undefined || value.trim().length === 0)
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (TRUE_VALUES.has(normalized))
+        return true;
+    if (FALSE_VALUES.has(normalized))
+        return false;
+    return null;
+}
+function isEnabledEnvFlag(env, key) {
+    const value = env[key];
+    if (value === undefined || value.trim().length === 0)
+        return false;
+    return readOptionalBoolean(value) !== false;
+}
+export function isCiEnvironment(env = process.env) {
+    if (readOptionalBoolean(env.npm_config_ignore_scripts) === true)
+        return true;
+    return CI_ENV_KEYS.some((key) => isEnabledEnvFlag(env, key));
+}
+function directoryContainsEntryWithPrefix(directory, prefix) {
+    try {
+        return readdirSync(directory, { withFileTypes: true }).some((entry) => entry.name.startsWith(prefix));
+    }
+    catch {
+        return false;
+    }
+}
+export function hasCodexDesktopApp(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const home = options.home ?? homedir();
+    if (platform === "win32") {
+        const localAppData = (env.LOCALAPPDATA ?? "").trim() || join(home, "AppData", "Local");
+        const programFiles = (env.ProgramFiles ?? env.ProgramW6432 ?? "").trim() || "C:\\Program Files";
+        return (directoryContainsEntryWithPrefix(join(localAppData, "Packages"), "OpenAI.Codex_") ||
+            directoryContainsEntryWithPrefix(join(programFiles, "WindowsApps"), "OpenAI.Codex_"));
+    }
+    if (platform === "darwin") {
+        return (existsSync("/Applications/Codex.app") ||
+            existsSync(join(home, "Applications", "Codex.app")));
+    }
+    return false;
+}
+export function resolveRotationEnabled(env = process.env, readConfigRotation = () => getCodexRuntimeRotationProxy(loadPluginConfig()) === true) {
+    const envOverride = readOptionalBoolean(env.CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY);
+    if (envOverride !== null)
+        return envOverride;
+    try {
+        return readConfigRotation();
+    }
+    catch {
+        // Rotation defaults on; a malformed config must not block first-run setup.
+        return true;
+    }
+}
+export function shouldBindCodexAppOnFirstRun(options) {
+    const env = options.env ?? process.env;
+    if (isCiEnvironment(env))
+        return false;
+    const bindOverride = readOptionalBoolean(env.CODEX_MULTI_AUTH_APP_BIND);
+    if (bindOverride !== null)
+        return bindOverride;
+    const installOverride = readOptionalBoolean(env.CODEX_MULTI_AUTH_APP_BIND_INSTALL);
+    if (installOverride !== null)
+        return installOverride;
+    if (!options.rotationEnabled)
+        return false;
+    return options.appDetected;
+}
+export function shouldInstallCodexAppLauncherOnFirstRun(options) {
+    const env = options.env ?? process.env;
+    if (isCiEnvironment(env))
+        return false;
+    const installOverride = readOptionalBoolean(env.CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL);
+    if (installOverride !== null)
+        return installOverride;
+    return options.rotationEnabled;
+}
+/**
+ * First-run setup only fires for a durable, global-style install. The old
+ * postinstall gate was `npm_config_global`, which does not exist at CLI
+ * runtime, so this approximates it from the module location instead:
+ *
+ * - must live under a `node_modules` segment (a dev checkout or the test
+ *   suite runs straight from the repository tree and stays side-effect-free)
+ * - must NOT be an npx cache run (`.../_npx/<hash>/node_modules/...`):
+ *   someone trying the tool once must not get app bind/launcher mutations,
+ *   and must not burn the once-only marker before a real install
+ * - must NOT be a project-local install (module path inside the invoking
+ *   working directory): `npm install` into an app's node_modules is not a
+ *   machine-level install either
+ */
+export function isInstalledPackageContext(modulePath = fileURLToPath(import.meta.url), cwd = process.cwd()) {
+    const segments = modulePath.split(sep);
+    if (!segments.includes("node_modules"))
+        return false;
+    if (segments.includes("_npx"))
+        return false;
+    const fromCwd = relative(cwd, modulePath);
+    if (fromCwd && !fromCwd.startsWith("..") && !isAbsolute(fromCwd)) {
+        return false;
+    }
+    return true;
+}
+export function getFirstRunMarkerPath() {
+    return join(getCodexMultiAuthDir(), FIRST_RUN_MARKER_FILE);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isErrnoCode(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === code);
+}
+/**
+ * Claims the marker with an exclusive create so that, across processes, at
+ * most one first invocation runs the setup. Returns false when another
+ * process already holds (or completed) the claim.
+ */
+function claimFirstRunMarker(markerPath, startedAt) {
+    mkdirSync(dirname(markerPath), { recursive: true });
+    const payload = `${JSON.stringify({ version: FIRST_RUN_MARKER_VERSION, startedAt }, null, "\t")}\n`;
+    try {
+        writeFileSync(markerPath, payload, { flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch (error) {
+        if (isErrnoCode(error, "EEXIST"))
+            return false;
+        throw error;
+    }
+}
+async function atomicWriteMarker(target, content) {
+    await withFileOperationRetry(async () => {
+        const tempPath = join(dirname(target), [
+            `.${basename(target)}`,
+            String(process.pid),
+            String(Date.now()),
+            randomBytes(4).toString("hex"),
+            "tmp",
+        ].join("."));
+        let moved = false;
+        let handle = null;
+        try {
+            handle = await open(tempPath, "w", 0o600);
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = null;
+            await rename(tempPath, target);
+            moved = true;
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+            if (!moved) {
+                await unlink(tempPath).catch(() => undefined);
+            }
+        }
+    });
+}
+async function finalizeFirstRunMarker(markerPath, startedAt, outcome, now) {
+    const payload = `${JSON.stringify({
+        version: FIRST_RUN_MARKER_VERSION,
+        startedAt,
+        completedAt: now(),
+        appBind: outcome.appBind,
+        launcher: outcome.launcher,
+    }, null, "\t")}\n`;
+    try {
+        await atomicWriteMarker(markerPath, payload);
+    }
+    catch (error) {
+        // The claim file already guarantees once-only behavior; losing the
+        // completion details is acceptable.
+        log.debug("first-run marker finalize failed", {
+            error: errorMessage(error),
+        });
+    }
+}
+/**
+ * Resolves the launcher installer from the packaged scripts/ directory,
+ * trying the dist layout first and the source layout second.
+ *
+ * @internal `candidateOverride` exists only so tests can exercise the
+ * fallback order and failure modes with real temp files.
+ */
+export async function loadLauncherInstall(candidateOverride) {
+    const candidates = candidateOverride ?? [
+        fileURLToPath(new URL("../../../scripts/codex-app-launcher.js", import.meta.url)),
+        fileURLToPath(new URL("../../scripts/codex-app-launcher.js", import.meta.url)),
+    ];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate))
+            continue;
+        const launcherModule = (await import(pathToFileURL(candidate).href));
+        return typeof launcherModule.installCodexAppLauncher === "function"
+            ? launcherModule.installCodexAppLauncher
+            : null;
+    }
+    return null;
+}
+async function defaultBindCodexApp(env, rotationEnabled, detectDesktopApp, notify) {
+    const currentStatus = await getAppBindStatus().catch(() => null);
+    const appDetected = detectDesktopApp() || currentStatus?.bound === true;
+    if (!shouldBindCodexAppOnFirstRun({ env, rotationEnabled, appDetected })) {
+        return "skipped";
+    }
+    const result = await bindCodexAppRuntimeRotation();
+    if (result?.message) {
+        notify(result.message);
+    }
+    return "completed";
+}
+async function defaultInstallLauncher(env, rotationEnabled, notify) {
+    if (!shouldInstallCodexAppLauncherOnFirstRun({ env, rotationEnabled })) {
+        return "skipped";
+    }
+    const installLauncher = await loadLauncherInstall();
+    if (!installLauncher)
+        return "skipped";
+    await installLauncher({ log: notify });
+    return "completed";
+}
+/**
+ * Runs the lazily deferred install setup (Codex app bind + launcher routing)
+ * exactly once per runtime root. Never throws and never blocks a command on
+ * failure: every error path resolves with a skip/failed status and only
+ * debug-logs sanitized messages.
+ */
+export async function ensureFirstRunSetup(deps = {}) {
+    try {
+        const env = deps.env ?? process.env;
+        if (isCiEnvironment(env))
+            return { ran: false, reason: "ci" };
+        const installed = deps.installedContext ?? isInstalledPackageContext();
+        if (!installed)
+            return { ran: false, reason: "not-installed" };
+        const markerPath = deps.markerPath ?? getFirstRunMarkerPath();
+        if (existsSync(markerPath))
+            return { ran: false, reason: "already-done" };
+        const now = deps.now ?? Date.now;
+        const startedAt = now();
+        if (!claimFirstRunMarker(markerPath, startedAt)) {
+            return { ran: false, reason: "claim-race" };
+        }
+        // Library default goes through the structured logger; the CLI entrypoint
+        // passes a stderr notify so interactive users still see bind messages.
+        const notify = deps.notify ?? ((message) => log.info(message));
+        const detectDesktopApp = deps.detectDesktopApp ?? (() => hasCodexDesktopApp({ env }));
+        const rotationEnabled = deps.resolveRotation
+            ? deps.resolveRotation()
+            : resolveRotationEnabled(env);
+        const outcome = {
+            appBind: "skipped",
+            launcher: "skipped",
+        };
+        try {
+            outcome.appBind = await (deps.bindCodexApp
+                ? deps.bindCodexApp()
+                : defaultBindCodexApp(env, rotationEnabled, detectDesktopApp, notify));
+        }
+        catch (error) {
+            outcome.appBind = "failed";
+            log.debug("first-run app bind skipped", { error: errorMessage(error) });
+        }
+        try {
+            outcome.launcher = await (deps.installLauncher
+                ? deps.installLauncher()
+                : defaultInstallLauncher(env, rotationEnabled, notify));
+        }
+        catch (error) {
+            outcome.launcher = "failed";
+            log.debug("first-run launcher install skipped", {
+                error: errorMessage(error),
+            });
+        }
+        await finalizeFirstRunMarker(markerPath, startedAt, outcome, now);
+        return { ran: true, ...outcome };
+    }
+    catch (error) {
+        log.debug("first-run setup skipped", { error: errorMessage(error) });
+        return { ran: false, reason: "error" };
+    }
+}

package/dist/lib/runtime/flagged-verify-types.js

@@ -4,4 +4,3 @@ export function createFlaggedVerificationState() {
         restored: [],
     };
 }
-//# sourceMappingURL=flagged-verify-types.js.map

package/dist/lib/runtime/hydrate-emails.js

@@ -58,4 +58,3 @@ export async function hydrateRuntimeEmails(storage, deps) {
     }
     return storage;
 }
-//# sourceMappingURL=hydrate-emails.js.map

package/dist/lib/runtime/live-sync-entry.js

@@ -15,4 +15,3 @@ export async function ensureLiveAccountSyncEntry(params) {
         pluginName: params.pluginName,
     });
 }
-//# sourceMappingURL=live-sync-entry.js.map

package/dist/lib/runtime/live-sync.js

@@ -76,4 +76,3 @@ export async function ensureRuntimeLiveAccountSync(deps) {
     }
     return { sync, path: nextPath, configKey, cleanupRegistered };
 }
-//# sourceMappingURL=live-sync.js.map

package/dist/lib/runtime/loader-setup.js

@@ -5,4 +5,3 @@ export function applyLoaderRuntimeSetup(params) {
     params.ensureRefreshGuardian(params.pluginConfig);
     params.applyPreemptiveQuotaSettings(params.pluginConfig);
 }
-//# sourceMappingURL=loader-setup.js.map

package/dist/lib/runtime/login-menu-accounts.js

@@ -35,4 +35,3 @@ export function buildLoginMenuAccounts(accounts, deps) {
         };
     });
 }
-//# sourceMappingURL=login-menu-accounts.js.map

package/dist/lib/runtime/manual-oauth-flow.js

@@ -68,4 +68,3 @@ export function buildManualOAuthFlow(paramsOrPkce, url, expectedState, deps) {
     }
     return buildManualOAuthFlowFromParams(paramsOrPkce);
 }
-//# sourceMappingURL=manual-oauth-flow.js.map

package/dist/lib/runtime/oauth-browser-flow.js

@@ -31,4 +31,3 @@ export async function runOAuthBrowserFlow(deps) {
     }
     return exchangeAuthorizationCode(result.code, pkce.verifier, REDIRECT_URI);
 }
-//# sourceMappingURL=oauth-browser-flow.js.map

package/dist/lib/runtime/preemptive-quota.js

@@ -6,4 +6,3 @@ export function applyRuntimePreemptiveQuotaSettings(pluginConfig, deps) {
         maxDeferralMs: deps.getPreemptiveQuotaMaxDeferralMs(pluginConfig),
     });
 }
-//# sourceMappingURL=preemptive-quota.js.map

package/dist/lib/runtime/quota-headers.js

@@ -128,4 +128,3 @@ export function formatCodexQuotaLine(snapshot) {
         parts.push("rate-limited");
     return parts.join(", ");
 }
-//# sourceMappingURL=quota-headers.js.map

package/dist/lib/runtime/quota-probe.js

@@ -76,4 +76,3 @@ export async function fetchRuntimeCodexQuotaSnapshot(params) {
     }
     throw lastError ?? new Error("Failed to fetch quotas");
 }
-//# sourceMappingURL=quota-probe.js.map

package/dist/lib/runtime/quota-settings.js

@@ -9,4 +9,3 @@ export function applyPreemptiveQuotaSettingsFromConfig(pluginConfig, deps) {
 export function resolveUiRuntimeFromConfig(loadPluginConfig, applyUiRuntimeFromConfig) {
     return applyUiRuntimeFromConfig(loadPluginConfig());
 }
-//# sourceMappingURL=quota-settings.js.map

package/dist/lib/runtime/refresh-guardian-entry.js

@@ -9,4 +9,3 @@ export function ensureRefreshGuardianEntry(params) {
         registerCleanup: params.registerCleanup,
     });
 }
-//# sourceMappingURL=refresh-guardian-entry.js.map

package/dist/lib/runtime/refresh-guardian.js

@@ -29,4 +29,3 @@ export function ensureRuntimeRefreshGuardian(deps) {
     }
     return { guardian, configKey, cleanupRegistered };
 }
-//# sourceMappingURL=refresh-guardian.js.map

package/dist/lib/runtime/request-init.js

@@ -47,4 +47,3 @@ export async function parseRuntimeRequestBody(body, deps) {
     }
     return {};
 }
-//# sourceMappingURL=request-init.js.map

package/dist/lib/runtime/rotation-account-selection.d.ts

@@ -0,0 +1,38 @@
+import type { AccountManager, ManagedAccount } from "../accounts.js";
+import type { ModelFamily } from "../prompts/codex.js";
+import type { RuntimePolicyDecision } from "../policy/runtime-policy.js";
+import type { SessionAffinityStore } from "../session-affinity.js";
+/**
+ * `chooseAccount` is a SYNC selector that internally advances the rotation
+ * cursor (the session-affinity-preferred branch and the round-robin fallback
+ * both call `accountManager.markSwitched(...)`, and the hybrid selector advances
+ * its own cursor). It does NOT acquire the routing mutex itself.
+ *
+ * Concurrency (L4): when `routingMutex === "enabled"`, the proxy hot path runs
+ * this whole call AND the subsequent `markSwitchedLocked` commit inside a single
+ * `withRoutingMutex` acquisition, so concurrent requests serialize selection +
+ * cursor advance and cannot stampede the same account. `withRoutingMutex` is
+ * reentrant (AsyncLocalStorage), so the nested `markSwitchedLocked` — and the
+ * later one in `persistRuntimeActiveAccount` — run inline without re-acquiring
+ * the non-reentrant FIFO queue (no deadlock). In legacy mode the inline
+ * `markSwitched` calls below are used unchanged and no lock is taken, so default
+ * behavior and perf are identical. See the hot-path caller in
+ * `startRuntimeRotationProxy` and the regression in
+ * `test/runtime-rotation-proxy.test.ts`.
+ */
+export declare function chooseAccount(params: {
+    accountManager: AccountManager;
+    sessionAffinityStore: SessionAffinityStore | null;
+    sessionKey: string | null;
+    family: ModelFamily;
+    model: string | null;
+    attemptedIndexes: ReadonlySet<number>;
+    now: number;
+    policy: RuntimePolicyDecision | null;
+    pinnedIndex: number | null;
+    skipReasons?: Map<number, string>;
+    stickyBoostByAccount?: Record<number, number>;
+    pidOffsetEnabled?: boolean;
+    schedulingStrategy?: "hybrid" | "sequential";
+}): ManagedAccount | null;
+//# sourceMappingURL=rotation-account-selection.d.ts.map

package/dist/lib/runtime/rotation-account-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation-account-selection.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-account-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACrC,cAAc,EAAE,cAAc,CAAC;IAC/B,oBAAoB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC7C,GAAG,cAAc,GAAG,IAAI,CAsJxB"}

package/dist/lib/runtime/rotation-account-selection.js

@@ -0,0 +1,172 @@
+/**
+ * `chooseAccount` is a SYNC selector that internally advances the rotation
+ * cursor (the session-affinity-preferred branch and the round-robin fallback
+ * both call `accountManager.markSwitched(...)`, and the hybrid selector advances
+ * its own cursor). It does NOT acquire the routing mutex itself.
+ *
+ * Concurrency (L4): when `routingMutex === "enabled"`, the proxy hot path runs
+ * this whole call AND the subsequent `markSwitchedLocked` commit inside a single
+ * `withRoutingMutex` acquisition, so concurrent requests serialize selection +
+ * cursor advance and cannot stampede the same account. `withRoutingMutex` is
+ * reentrant (AsyncLocalStorage), so the nested `markSwitchedLocked` — and the
+ * later one in `persistRuntimeActiveAccount` — run inline without re-acquiring
+ * the non-reentrant FIFO queue (no deadlock). In legacy mode the inline
+ * `markSwitched` calls below are used unchanged and no lock is taken, so default
+ * behavior and perf are identical. See the hot-path caller in
+ * `startRuntimeRotationProxy` and the regression in
+ * `test/runtime-rotation-proxy.test.ts`.
+ */
+export function chooseAccount(params) {
+    const { accountManager, sessionAffinityStore, sessionKey, family, model, attemptedIndexes, now, policy, pinnedIndex, skipReasons, stickyBoostByAccount, pidOffsetEnabled, schedulingStrategy, } = params;
+    // Manual pin (from `codex-multi-auth switch <n>`) overrides every other
+    // selection signal. We do NOT call markSwitched here — the proxy must not
+    // clobber the pin set by the CLI. See issue #474.
+    if (typeof pinnedIndex === "number") {
+        if (attemptedIndexes.has(pinnedIndex)) {
+            skipReasons?.set(pinnedIndex, "already-attempted");
+            return null;
+        }
+        if (pinnedIndex < 0 || pinnedIndex >= accountManager.getAccountCount()) {
+            skipReasons?.set(pinnedIndex, "missing");
+            return null;
+        }
+        if (policy?.blockedAccountIndexes.has(pinnedIndex)) {
+            skipReasons?.set(pinnedIndex, "policy-blocked");
+            return null;
+        }
+        const pinned = accountManager.getAccountByIndex(pinnedIndex);
+        if (!pinned || pinned.enabled === false) {
+            skipReasons?.set(pinnedIndex, "disabled");
+            return null;
+        }
+        const reason = accountManager.getAccountRuntimeSkipReason(pinnedIndex, family, model);
+        if (reason) {
+            skipReasons?.set(pinnedIndex, reason);
+            return null;
+        }
+        return pinned;
+    }
+    // Sequential / drain-first mode (issue #509): the active account governs ALL
+    // new requests, so we deliberately SKIP the per-session affinity tier — there
+    // is no per-chat stickiness, every request follows the single active account.
+    // The manual pin above still wins (handled first). When the active account is
+    // exhausted the selector advances to the next available account and earlier
+    // accounts reclaim the slot once their quota recovers.
+    if (schedulingStrategy === "sequential") {
+        const selected = accountManager.getCurrentOrNextForFamilySequential(family, model, policy?.blockedAccountIndexes);
+        if (selected &&
+            !attemptedIndexes.has(selected.index) &&
+            !policy?.blockedAccountIndexes.has(selected.index)) {
+            const reason = accountManager.getAccountRuntimeSkipReason(selected.index, family, model);
+            if (!reason)
+                return selected;
+            skipReasons?.set(selected.index, reason);
+        }
+        // Active account was attempted/blocked/skipped this request (e.g. it just
+        // rate-limited mid-loop): fall through to the shared linear scan to find
+        // the next eligible account to TRY. Pass advanceActivePointer=false so a
+        // transient, non-exhausting failure on the active account does not
+        // permanently move the drain-first primary — only
+        // getCurrentOrNextForFamilySequential advances it, and only on true
+        // exhaustion.
+        return chooseLinearScanFallback({
+            accountManager,
+            family,
+            model,
+            attemptedIndexes,
+            policy,
+            skipReasons,
+            advanceActivePointer: false,
+        });
+    }
+    const preferredIndex = sessionAffinityStore?.getPreferredAccountIndex(sessionKey, now);
+    if (typeof preferredIndex === "number" &&
+        !attemptedIndexes.has(preferredIndex) &&
+        !policy?.blockedAccountIndexes.has(preferredIndex)) {
+        const preferred = accountManager.getAccountByIndex(preferredIndex);
+        if (preferred) {
+            const reason = accountManager.getAccountRuntimeSkipReason(preferred.index, family, model);
+            if (reason) {
+                skipReasons?.set(preferred.index, reason);
+            }
+            else {
+                // L4 (deferred): unlocked cursor mutation — see chooseAccount header.
+                accountManager.markSwitched(preferred, "rotation", family);
+                return preferred;
+            }
+        }
+    }
+    const selected = accountManager.getCurrentOrNextForFamilyHybrid(family, model, {
+        scoreBoostByAccount: {
+            ...(policy?.scoreBoostByAccount ?? {}),
+            ...(stickyBoostByAccount ?? {}),
+        },
+        // accounts-05: carry the PID-offset distribution into the default-on proxy
+        // path too (index.ts already does). Without it, parallel proxy processes can
+        // stampede the same account instead of spreading across the pool.
+        pidOffsetEnabled,
+    });
+    if (selected &&
+        !attemptedIndexes.has(selected.index) &&
+        !policy?.blockedAccountIndexes.has(selected.index)) {
+        const reason = accountManager.getAccountRuntimeSkipReason(selected.index, family, model);
+        if (!reason)
+            return selected;
+        skipReasons?.set(selected.index, reason);
+    }
+    return chooseLinearScanFallback({
+        accountManager,
+        family,
+        model,
+        attemptedIndexes,
+        policy,
+        skipReasons,
+    });
+}
+/**
+ * Shared linear-scan fallback used by both the hybrid and sequential selection
+ * paths in `chooseAccount`. Walks every account in pool order and returns the
+ * first one that is not already attempted, not policy-blocked, and has no
+ * runtime skip reason (rate-limited / cooling down / circuit-open), recording a
+ * skip reason for each rejected candidate. Returns null when no eligible
+ * account remains.
+ *
+ * `advanceActivePointer` (default `true`) controls whether the winner is
+ * committed as the new active/cursor position via `markSwitched`. The hybrid
+ * path wants this (round-robin advance). The sequential path passes `false`:
+ * its within-request fallback only needs an account to TRY this request, and
+ * must NOT move `currentAccountIndexByFamily` — otherwise a transient,
+ * non-exhausting failure on the active account (which leaves it `isUsable` but
+ * present in `attemptedIndexes`) would permanently switch the drain-first
+ * primary even though it was never exhausted (issue #509 regression caught in
+ * review). In sequential mode only `getCurrentOrNextForFamilySequential` is
+ * allowed to advance the active pointer, and only on true exhaustion.
+ */
+function chooseLinearScanFallback(params) {
+    const { accountManager, family, model, attemptedIndexes, policy, skipReasons, advanceActivePointer = true, } = params;
+    for (const account of accountManager.getAccountsSnapshot()) {
+        if (attemptedIndexes.has(account.index)) {
+            skipReasons?.set(account.index, "already-attempted");
+            continue;
+        }
+        if (policy?.blockedAccountIndexes.has(account.index)) {
+            skipReasons?.set(account.index, "policy-blocked");
+            continue;
+        }
+        const reason = accountManager.getAccountRuntimeSkipReason(account.index, family, model);
+        if (!reason) {
+            const live = accountManager.getAccountByIndex(account.index);
+            if (!live)
+                continue;
+            // L4 (deferred): unlocked cursor mutation — see chooseAccount header.
+            // Skipped in sequential mode (advanceActivePointer=false) so a
+            // within-request retry never reassigns the drain-first primary.
+            if (advanceActivePointer) {
+                accountManager.markSwitched(live, "rotation", family);
+            }
+            return live;
+        }
+        skipReasons?.set(account.index, reason);
+    }
+    return null;
+}