codex-multi-auth 2.3.2 → 2.4.0

package/dist/lib/request/response-handler.js

@@ -1,5 +1,5 @@
 import { createLogger, logRequest, LOGGING_ENABLED } from "../logger.js";
-import { PLUGIN_NAME } from "../constants.js";
+import { HTTP_STATUS, PLUGIN_NAME } from "../constants.js";
 import { isRecord } from "../utils.js";
 const log = createLogger("response-handler");
 const MAX_SSE_SIZE = 10 * 1024 * 1024; // 10MB limit to prevent memory exhaustion
@@ -456,7 +456,23 @@ function maybeCaptureResponseEvent(state, data, onResponseId) {
         state.encounteredError = true;
         return;
     }
-    if (data.type === "response.done" || data.type === "response.completed") {
+    // response.failed is a genuine terminal failure: the turn did not produce a
+    // usable result even though HTTP opened 200. Treat it as an error so the
+    // stream is not misclassified as a successful response and misattributed as
+    // an account success (stress audit H7).
+    if (data.type === "response.failed") {
+        log.warn("SSE terminal failure event received", { type: data.type });
+        state.encounteredError = true;
+        return;
+    }
+    // response.completed / response.done / response.incomplete are all terminal
+    // envelopes that carry a final response object. response.incomplete (e.g.
+    // hitting max_output_tokens or a content filter) is a NORMAL early stop whose
+    // partial output is the answer — it must be delivered to the client and
+    // counts as a healthy account, not a failure (re-audit correction to H7).
+    if (data.type === "response.done" ||
+        data.type === "response.completed" ||
+        data.type === "response.incomplete") {
         if (isRecord(data.response)) {
             state.finalResponse = { ...data.response };
         }
@@ -518,15 +534,19 @@ function parseSseStream(sseText, onResponseId) {
     let firstMalformedSample = null;
     for (const line of lines) {
         const trimmedLine = line.trim();
-        if (trimmedLine.startsWith("data: ")) {
-            const payload = trimmedLine.substring(6).trim();
+        // Accept "data:" with or without the optional trailing space. The SSE
+        // spec allows "data:value"; requiring the space silently dropped every
+        // event on an upstream/proxy formatting change (stress audit M1).
+        if (trimmedLine.startsWith("data:")) {
+            const payload = trimmedLine.substring(5).trim();
             if (!payload || payload === "[DONE]")
                 continue;
             try {
                 const data = JSON.parse(payload);
                 maybeCaptureResponseEvent(state, data, onResponseId);
-                if (state.encounteredError)
-                    return null;
+                if (state.encounteredError) {
+                    return { finalResponse: null, encounteredError: true };
+                }
             }
             catch (error) {
                 // AUDIT-H9 / H-03: previously these malformed chunks were
@@ -553,7 +573,10 @@ function parseSseStream(sseText, onResponseId) {
             firstSample: firstMalformedSample,
         });
     }
-    return finalizeParsedResponse(state);
+    return {
+        finalResponse: finalizeParsedResponse(state),
+        encounteredError: state.encounteredError,
+    };
 }
 /**
  * Convert SSE stream response to JSON for generateText()
@@ -597,13 +620,42 @@ export async function convertSseToJson(response, headers, options) {
             logRequest("stream-full", { fullContent: fullText });
         }
         // Parse SSE events to extract the final response
-        const finalResponse = parseSseStream(fullText, options?.onResponseId);
+        const { finalResponse, encounteredError } = parseSseStream(fullText, options?.onResponseId);
+        // A terminal failure event (mid-stream `error`, `response.failed`, or
+        // `response.incomplete`) means the upstream turn failed even though HTTP
+        // opened 200. Returning the raw SSE at 200 here makes the proxy record an
+        // account success and skip rotation/retry (stress audit H6+H7). Synthesize
+        // a non-2xx so the caller routes to failure. (A stream that simply yields
+        // no final response WITHOUT an error — empty/truncated — is left as the
+        // original passthrough below so the empty-response retry path still runs.)
+        if (encounteredError) {
+            log.warn("SSE stream ended with a terminal failure event");
+            logRequest("stream-error", {
+                error: "SSE stream terminated with an error/failed/incomplete event",
+            });
+            const upstreamFailed = typeof response.status === "number" && response.status >= 400;
+            const status = upstreamFailed ? response.status : HTTP_STATUS.BAD_GATEWAY;
+            const errorHeaders = new Headers(headers);
+            errorHeaders.set("content-type", "application/json; charset=utf-8");
+            return new Response(JSON.stringify({
+                error: {
+                    message: "Upstream SSE stream terminated with a failure event",
+                    type: "upstream_stream_error",
+                    code: "sse_terminal_error",
+                },
+            }), {
+                status,
+                statusText: upstreamFailed ? response.statusText : "Bad Gateway",
+                headers: errorHeaders,
+            });
+        }
         if (!finalResponse) {
             log.warn("Could not find final response in SSE stream");
             logRequest("stream-error", {
                 error: "No terminal response event found in SSE stream",
             });
-            // Return original stream if we can't parse
+            // Return original stream if we can't parse (no error event, just no
+            // terminal response). Preserves the empty-response retry path.
             return new Response(fullText, {
                 status: response.status,
                 statusText: response.statusText,
@@ -650,9 +702,9 @@ function createResponseIdCapturingStream(body, onResponseId) {
         }
         for (const rawLine of lines) {
             const trimmedLine = rawLine.trim();
-            if (!trimmedLine.startsWith("data: "))
+            if (!trimmedLine.startsWith("data:"))
                 continue;
-            const payload = trimmedLine.slice(6).trim();
+            const payload = trimmedLine.slice(5).trim();
             if (!payload || payload === "[DONE]")
                 continue;
             try {

package/dist/lib/runtime/rotation-proxy-state.d.ts

@@ -29,6 +29,13 @@ export interface RotationProxyStateInit {
     quotaRemainingPercentThreshold: number;
     sessionAffinityStore: SessionAffinityStore | null;
     lastObservedAffinityGeneration: number;
+    /**
+     * Ephemeral per-invocation account pin (0-based) or null. When a number,
+     * the request handler treats it exactly like a manual `switch` pin — a
+     * deterministic, fail-hard selection — but it is never written to disk, so
+     * concurrent invocations with different pins never interfere (issue #623).
+     */
+    forcedAccountIndex: number | null;
 }
 /**
  * Mutable rotation-loop state shared by every request of one proxy instance.

package/dist/lib/runtime/rotation-proxy-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rotation-proxy-state.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-proxy-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKhD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACtC,oBAAoB,EAAE,cAAc,CAAC;IACrC,gBAAgB,EAAE,SAAS,GAAG,QAAQ,CAAC;IACvC,kBAAkB,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC5C,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B,EAAE,MAAM,CAAC;IACpC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yBAAyB,EAAE,MAAM,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8BAA8B,EAAE,MAAM,CAAC;IACvC,oBAAoB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClD,8BAA8B,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzD,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yBAAyB,EAAE,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,wBAAwB,EAAE,MAAM,CAAC;CACjC;AAID,gBAAgB;AAChB,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,sBAAsB,GAC1B,kBAAkB,CAuBpB;AAED,gBAAgB;AAChB,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,kBAAkB,GACvB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkDhC"}
+{"version":3,"file":"rotation-proxy-state.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-proxy-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKhD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACtC,oBAAoB,EAAE,cAAc,CAAC;IACrC,gBAAgB,EAAE,SAAS,GAAG,QAAQ,CAAC;IACvC,kBAAkB,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC5C,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B,EAAE,MAAM,CAAC;IACpC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yBAAyB,EAAE,MAAM,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8BAA8B,EAAE,MAAM,CAAC;IACvC,oBAAoB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClD,8BAA8B,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,oBAAoB,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzD,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yBAAyB,EAAE,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,wBAAwB,EAAE,MAAM,CAAC;CACjC;AAID,gBAAgB;AAChB,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,sBAAsB,GAC1B,kBAAkB,CAuBpB;AAED,gBAAgB;AAChB,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,kBAAkB,GACvB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkDhC"}

package/dist/lib/runtime/rotation-server-types.d.ts

@@ -32,6 +32,15 @@ export interface RuntimeRotationProxyOptions {
     maxRequestBodyBytes?: number;
     fetchTimeoutMs?: number;
     streamStallTimeoutMs?: number;
+    /**
+     * Ephemeral, per-instance account pin (0-based) for a single invocation
+     * (issue #623: `codex-multi-auth-codex --account`). When set, this proxy
+     * routes every request to exactly this account and never rotates, without
+     * touching the persisted `switch` pin on disk. Falls back to
+     * `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX` in the environment when omitted so
+     * the value survives the launcher -> detached app-helper process boundary.
+     */
+    forcedAccountIndex?: number | null;
 }
 export interface RequestContext {
     body: Buffer;

package/dist/lib/runtime/rotation-server-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rotation-server-types.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-server-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,0BAA0B,CAAC;CAC5C;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,cAAc,GACd,eAAe,GACf,cAAc,GACd,QAAQ,GACR,aAAa,GACb,YAAY,CAAC;AAChB,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"rotation-server-types.d.ts","sourceRoot":"","sources":["../../../lib/runtime/rotation-server-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,0BAA0B,CAAC;CAC5C;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GACzB,YAAY,GACZ,cAAc,GACd,eAAe,GACf,cAAc,GACd,QAAQ,GACR,aAAa,GACb,YAAY,CAAC;AAChB,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,8BAA8B;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CAClB"}

package/dist/lib/runtime-rotation-proxy.d.ts

@@ -5,5 +5,15 @@ export type { PinnedUnavailableErrorBody } from "./request/rate-limit-decision.j
 export { chooseAccount } from "./runtime/rotation-account-selection.js";
 export { maybeInvalidateAffinityFromDisk, readPinnedAccountIndexFromDisk, readStorageMetaFromDisk, resetPinCacheForTesting, } from "./runtime/rotation-storage-meta.js";
 export type { StorageMeta } from "./runtime/rotation-storage-meta.js";
+/**
+ * Coerce a forced-account pin from an option (number) or the launcher's env
+ * string into a normalized 0-based index, or null when absent/invalid. Invalid
+ * or negative values collapse to null so an out-of-range env value can never
+ * throw at proxy startup; chooseAccount reports the deterministic
+ * pinned-account failure per-request instead. Exported for unit tests.
+ *
+ * @internal
+ */
+export declare function normalizeForcedAccountIndex(value: number | string | null | undefined): number | null;
 export declare function startRuntimeRotationProxy(options: RuntimeRotationProxyOptions): Promise<RuntimeRotationProxyServer>;
 //# sourceMappingURL=runtime-rotation-proxy.d.ts.map

package/dist/lib/runtime-rotation-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-rotation-proxy.d.ts","sourceRoot":"","sources":["../../lib/runtime-rotation-proxy.ts"],"names":[],"mappings":"AAwEA,OAAO,KAAK,EAKX,2BAA2B,EAC3B,0BAA0B,EAE1B,MAAM,oCAAoC,CAAC;AAe5C,YAAY,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACN,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EACN,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AA6etE,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA+IrC"}
+{"version":3,"file":"runtime-rotation-proxy.d.ts","sourceRoot":"","sources":["../../lib/runtime-rotation-proxy.ts"],"names":[],"mappings":"AAwEA,OAAO,KAAK,EAKX,2BAA2B,EAC3B,0BAA0B,EAE1B,MAAM,oCAAoC,CAAC;AAe5C,YAAY,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACN,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EACN,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AA6etE;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,GAAG,IAAI,CAUf;AAED,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA6JrC"}

package/dist/lib/runtime-rotation-proxy.js

@@ -420,6 +420,25 @@ function writePoolExhausted(params) {
         },
     });
 }
+/**
+ * Coerce a forced-account pin from an option (number) or the launcher's env
+ * string into a normalized 0-based index, or null when absent/invalid. Invalid
+ * or negative values collapse to null so an out-of-range env value can never
+ * throw at proxy startup; chooseAccount reports the deterministic
+ * pinned-account failure per-request instead. Exported for unit tests.
+ *
+ * @internal
+ */
+export function normalizeForcedAccountIndex(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const parsed = typeof value === "number" ? value : Number.parseInt(value.trim(), 10);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        return null;
+    }
+    return parsed;
+}
 export async function startRuntimeRotationProxy(options) {
     const pluginConfig = loadPluginConfig();
     const activeAccountManager = options.accountManager ?? (await AccountManager.loadFromDisk());
@@ -455,6 +474,17 @@ export async function startRuntimeRotationProxy(options) {
         throw new CodexValidationError("Runtime rotation proxy requires a clientApiKey.", { field: "clientApiKey", expected: "a non-empty string" });
     }
     const now = options.now ?? Date.now;
+    // Ephemeral per-invocation pin (issue #623). Prefer an explicit option (used by
+    // tests and the in-process inline proxy); otherwise fall back to the numeric env
+    // the launcher publishes, which is how the value reaches a detached app-helper
+    // process. `??` means both `undefined` and an explicit `null` option defer to the
+    // env, so "no option" and "no pin" behave identically. Invalid/negative values
+    // are ignored (treated as "no forced pin") rather than throwing — the launcher
+    // already validated the selector, and an out-of-range index is surfaced
+    // per-request as a deterministic pinned-account failure by chooseAccount rather
+    // than crashing proxy startup.
+    const forcedAccountIndex = normalizeForcedAccountIndex(options.forcedAccountIndex ??
+        process.env.CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX);
     const tokenRefreshSkewMs = getTokenRefreshSkewMs(pluginConfig);
     const networkErrorCooldownMs = getNetworkErrorCooldownMs(pluginConfig);
     const serverErrorCooldownMs = getServerErrorCooldownMs(pluginConfig);
@@ -500,6 +530,7 @@ export async function startRuntimeRotationProxy(options) {
         quotaRemainingPercentThreshold,
         sessionAffinityStore,
         lastObservedAffinityGeneration,
+        forcedAccountIndex,
     });
     const server = createServer((req, res) => {
         void handleRequest(state, req, res);
@@ -669,7 +700,13 @@ async function handleRequestInner(state, req, res, traceId) {
         // account. The proxy itself never bumps the generation, so its own
         // debounced disk writes do not clear affinity. See issue #474.
         const storageMeta = readStorageMetaFromDisk();
-        const pinnedIndex = storageMeta.pinnedAccountIndex;
+        // The ephemeral --account pin (issue #623) takes precedence over the
+        // persisted `switch` pin for this invocation, without ever mutating disk
+        // state. Use `??` (not `||`) so a forced index of 0 is honored. When set,
+        // everything downstream — deterministic pick, no cursor advance, no
+        // stale-state recovery, the `codex_pinned_account_unavailable` failure —
+        // applies unchanged because it all keys off `pinnedIndex` / `isPinned`.
+        const pinnedIndex = state.forcedAccountIndex ?? storageMeta.pinnedAccountIndex;
         const isPinned = typeof pinnedIndex === "number";
         if (storageMeta.affinityGeneration > state.lastObservedAffinityGeneration) {
             state.sessionAffinityStore?.clearAll();

package/dist/lib/schemas.js

@@ -274,7 +274,7 @@ export const TokenSuccessSchema = z.object({
     type: z.literal("success"),
     access: z.string().min(1),
     refresh: z.string().min(1),
-    expires: z.number(),
+    expires: z.number().int().positive(),
     idToken: z.string().optional(),
     multiAccount: z.boolean().optional(),
 });
@@ -303,7 +303,7 @@ export const TokenResultSchema = z.discriminatedUnion("type", [
 export const OAuthTokenResponseSchema = z.object({
     access_token: z.string().min(1),
     refresh_token: z.string().optional(),
-    expires_in: z.number(),
+    expires_in: z.number().int().positive(),
     id_token: z.string().optional(),
     token_type: z.string().optional(),
     scope: z.string().optional(),

package/dist/lib/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../lib/storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../lib/storage.ts"],"names":[],"mappings":"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"}

package/dist/lib/storage.js

@@ -814,7 +814,12 @@ export function normalizeAccountStorage(data) {
     const baseStorage = fromVersion === 1
         ? migrateV1ToV3(data)
         : data;
-    const validAccounts = rawAccounts.filter((account) => isRecord(account) &&
+    // Build from baseStorage.accounts (the migrated V3 shape), NOT the raw V1
+    // objects. Otherwise a V1->V3 upgrade discards migrateV1ToV3's per-account
+    // transforms — most importantly the scalar `rateLimitResetTime` -> map
+    // `rateLimitResetTimes` conversion — so a rate-limited V1 account would be
+    // treated as immediately available on upgrade and burst 429s (stress audit M3).
+    const validAccounts = baseStorage.accounts.filter((account) => isRecord(account) &&
         typeof account.refreshToken === "string" &&
         !!account.refreshToken.trim());
     const deduplicatedAccounts = deduplicateAccounts(validAccounts);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-multi-auth",
-	"version": "2.3.2",
+	"version": "2.4.0",
 	"description": "Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",

package/scripts/codex.js

@@ -307,6 +307,172 @@ function findAccountIndexByIdOrEmail(accounts, id, email) {
 	return -1;
 }
 
+// --- Forced-account selection (`--account`, issue #623) ---------------------
+//
+// `codex-multi-auth-codex --account <selector>` (or the CODEX_MULTI_AUTH_FORCE_ACCOUNT
+// env var) pins ONE account for a single invocation. The selector is resolved to a
+// 0-based index here in the launcher and published as CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX,
+// which the runtime rotation proxy consumes as an ephemeral pin — never touching the
+// persisted `switch` pin on disk. The flag wins over the env var.
+const FORCE_ACCOUNT_ENV = "CODEX_MULTI_AUTH_FORCE_ACCOUNT";
+const FORCE_ACCOUNT_INDEX_ENV = "CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX";
+
+/**
+ * Extract and strip `--account <sel>` / `--account=<sel>` from a forwarded arg
+ * list. The flag is a launcher concept; real Codex has no `--account`, so it must
+ * never be forwarded. Returns { selector, strippedArgs, error }; selector is null
+ * when the flag is absent. The last occurrence wins if repeated.
+ */
+function extractForcedAccountFlag(args) {
+	const strippedArgs = [];
+	let selector = null;
+	let sawFlag = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--account") {
+			sawFlag = true;
+			const next = args[index + 1];
+			if (typeof next !== "string") {
+				return {
+					selector: null,
+					strippedArgs: args,
+					error:
+						"codex-multi-auth: --account requires a value (account index, email, or account id).",
+				};
+			}
+			selector = next;
+			index += 1;
+			continue;
+		}
+		if (typeof arg === "string" && arg.startsWith("--account=")) {
+			sawFlag = true;
+			selector = arg.slice("--account=".length);
+			continue;
+		}
+		strippedArgs.push(arg);
+	}
+	return { selector, strippedArgs, error: null, sawFlag };
+}
+
+/**
+ * Resolve the effective forced-account selector from args (flag) or environment,
+ * with the flag taking precedence. Returns { selector, strippedArgs, error };
+ * selector is null when neither source requests a forced account.
+ */
+function resolveForcedAccountSelector(rawArgs, env = process.env) {
+	const { selector: flagSelector, strippedArgs, error, sawFlag } =
+		extractForcedAccountFlag(rawArgs);
+	if (error) {
+		return { selector: null, strippedArgs, error };
+	}
+	if (sawFlag) {
+		const trimmed = flagSelector.trim();
+		if (trimmed.length === 0) {
+			return {
+				selector: null,
+				strippedArgs,
+				error:
+					"codex-multi-auth: --account requires a non-empty value (account index, email, or account id).",
+			};
+		}
+		return { selector: trimmed, strippedArgs, error: null };
+	}
+	const envSelector = (env[FORCE_ACCOUNT_ENV] ?? "").trim();
+	if (envSelector.length > 0) {
+		return { selector: envSelector, strippedArgs, error: null };
+	}
+	return { selector: null, strippedArgs, error: null };
+}
+
+function formatForcedAccountList(accounts) {
+	const lines = accounts.map((account, index) => {
+		const email =
+			typeof account?.email === "string" && account.email.trim().length > 0
+				? account.email.trim()
+				: `account ${index + 1}`;
+		return `  ${index + 1}. ${email}`;
+	});
+	return `Available accounts:\n${lines.join("\n")}`;
+}
+
+/**
+ * Resolve a forced-account selector to a 0-based index against the same scoped
+ * accounts pool the runtime rotation proxy will load. Selector forms: a 1-based
+ * integer index, an email, or an account id. Returns { ok, index } or
+ * { ok: false, error }.
+ */
+async function resolveForcedAccountIndex(selector, env = process.env) {
+	const accountsDir = await resolveStatusAccountsDir(env);
+	const storage = readJsonFileQuiet(resolveAccountsPath(env, accountsDir));
+	const accounts = Array.isArray(storage?.accounts) ? storage.accounts : [];
+	if (accounts.length === 0) {
+		return {
+			ok: false,
+			error:
+				"codex-multi-auth: --account was set but no Codex accounts are configured. Run `codex-multi-auth login` first.",
+		};
+	}
+	if (/^\d+$/.test(selector)) {
+		const oneBased = Number.parseInt(selector, 10);
+		if (oneBased < 1 || oneBased > accounts.length) {
+			return {
+				ok: false,
+				error: `codex-multi-auth: --account ${selector} is out of range (have ${accounts.length} account${
+					accounts.length === 1 ? "" : "s"
+				}).\n${formatForcedAccountList(accounts)}`,
+			};
+		}
+		return { ok: true, index: oneBased - 1 };
+	}
+	const index = findAccountIndexByIdOrEmail(accounts, selector, selector);
+	if (index < 0) {
+		return {
+			ok: false,
+			error: `codex-multi-auth: --account "${selector}" did not match any configured account.\n${formatForcedAccountList(accounts)}`,
+		};
+	}
+	return { ok: true, index };
+}
+
+/**
+ * Preflight the `--account` flag / env var before forwarding to Codex. On success
+ * returns { forwardArgs } with the flag stripped and (when a forced account was
+ * requested) CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX published on the environment for
+ * the proxy to consume. On failure returns { error } so the caller can exit
+ * non-zero WITHOUT launching Codex — a forced account must never silently fall
+ * back to a different one.
+ */
+async function applyForcedAccountSelection(rawArgs, env = process.env) {
+	const forced = resolveForcedAccountSelector(rawArgs, env);
+	if (forced.error) {
+		return { error: forced.error };
+	}
+	if (forced.selector === null) {
+		// Defensive: the resolved-index var is internal and only ever set below.
+		// Clear any stray value from the ambient environment so a request without
+		// --account can never inherit an unintended pin.
+		delete env[FORCE_ACCOUNT_INDEX_ENV];
+		return { forwardArgs: rawArgs };
+	}
+	// The pin can only be honored when the runtime rotation proxy is active for
+	// this command; otherwise the run would silently use a non-forced account,
+	// so fail hard instead of ignoring the flag.
+	if (!(await isRuntimeRotationProxyEnabled(forced.strippedArgs, env))) {
+		return {
+			error: [
+				"codex-multi-auth: --account requires the runtime rotation proxy, which is not active for this command.",
+				"Enable it with `codex-multi-auth rotation enable`, and make sure CODEX_MULTI_AUTH_BYPASS is not set.",
+			].join("\n"),
+		};
+	}
+	const resolved = await resolveForcedAccountIndex(forced.selector, env);
+	if (!resolved.ok) {
+		return { error: resolved.error };
+	}
+	env[FORCE_ACCOUNT_INDEX_ENV] = String(resolved.index);
+	return { forwardArgs: forced.strippedArgs };
+}
+
 function resolveModelFamilyForStatus(model) {
 	const normalized = typeof model === "string" ? model.trim().toLowerCase() : "";
 	if (normalized.startsWith("gpt-5.2")) return "gpt-5.2";
@@ -657,15 +823,20 @@ function maybeRefreshQuotaCacheInBackground(env = process.env) {
 	// process. The close/error handlers below remove the lock dir, but if the parent
 	// exits before the child settles they will NOT fire — in that case the lock is
 	// reclaimed by the 10-minute stale-lock recovery in acquireStatusRefreshLock.
+	const refreshChildEnv = {
+		...env,
+		CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD: "1",
+		CODEX_MULTI_AUTH_STATUSLINE: "0",
+	};
+	// A forced-account pin is scoped to a single forwarded Codex run; this
+	// management child (`forecast`) must never inherit it, so it can never be
+	// coupled to a specific account if a future change routes it through the proxy.
+	delete refreshChildEnv[FORCE_ACCOUNT_INDEX_ENV];
 	const child = spawn(
 		process.execPath,
 		[scriptPath, "forecast", "--live", "--json"],
 		{
-			env: {
-				...env,
-				CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD: "1",
-				CODEX_MULTI_AUTH_STATUSLINE: "0",
-			},
+			env: refreshChildEnv,
 			stdio: "ignore",
 			detached: true,
 		},
@@ -4766,12 +4937,22 @@ async function main() {
 		return 1;
 	}
 
+	// Resolve `--account` / CODEX_MULTI_AUTH_FORCE_ACCOUNT before forwarding: strip
+	// the launcher-only flag from the Codex args and publish the resolved pin, or
+	// fail hard so a forced account can never silently fall back to another one.
+	const forcedAccount = await applyForcedAccountSelection(rawArgs, process.env);
+	if (forcedAccount.error) {
+		console.error(forcedAccount.error);
+		return 1;
+	}
+	const forwardArgs = forcedAccount.forwardArgs;
+
 	await autoSyncManagerActiveSelectionIfEnabled();
-	await maybePrintForwardStatusLine(rawArgs);
+	await maybePrintForwardStatusLine(forwardArgs);
 	maybeRefreshQuotaCacheInBackground();
 	try {
-		return await withForwardedRuntimeObservability(rawArgs, () =>
-			forwardToRealCodex(realCodexBin, rawArgs),
+		return await withForwardedRuntimeObservability(forwardArgs, () =>
+			forwardToRealCodex(realCodexBin, forwardArgs),
 		);
 	} finally {
 		await autoSyncManagerActiveSelectionIfEnabled();