codex-multi-auth 2.8.6 → 2.8.7

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-multi-auth",
-	"version": "2.8.6",
+	"version": "2.8.7",
   "description": "Install and operate codex-multi-auth for the official @openai/codex CLI with multi-account OAuth rotation, switching, health checks, and recovery tools.",
   "interface": {
     "composerIcon": "./assets/codex-multi-auth-icon.svg"

package/README.md

@@ -392,7 +392,7 @@ codex-multi-auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v2.8.6.md](docs/releases/v2.8.6.md) — install via `npm i -g codex-multi-auth`
+- Current stable: [docs/releases/v2.8.7.md](docs/releases/v2.8.7.md) — install via `npm i -g codex-multi-auth`
 - Previous stable: [docs/releases/v2.8.3.md](docs/releases/v2.8.3.md)
 - Previous stable: [docs/releases/v2.8.2.md](docs/releases/v2.8.2.md)
 - Previous stable: [docs/releases/v2.7.1.md](docs/releases/v2.7.1.md)

package/dist/lib/request/rate-limit-decision.d.ts

@@ -40,6 +40,33 @@ export interface PinnedUnavailableContext {
     pinSource?: "forced" | "manual" | null;
     /** Epoch ms when the blocking record ends (rate limit or cooldown). */
     resetAtMs?: number | null;
+    /**
+     * Which class of record supplies `resetAtMs`. That deadline is the max
+     * across every gating record, so a `rate-limited` skip reason can carry a
+     * deadline supplied by a breaker or cooldown that ends later, and the
+     * quota phrasing is only true when the rate limit itself is that bound.
+     *
+     * - `"rate-limit"` — the rate-limit records bound it; word it as a reset.
+     * - `"other"` — a cooldown or breaker ends later and bounds it instead.
+     * - `"unknown"` (the default) — the caller did not measure; trust the
+     *   skip reason.
+     *
+     * Deliberately a value rather than the presence of a second deadline
+     * field. The previous shape branched on `"rateLimitResetAtMs" in context`,
+     * so a caller that spread the key with an `undefined` value got the
+     * opposite wording from one that omitted it — a contract no type could
+     * express and no compiler could check.
+     */
+    recoveryBound?: "rate-limit" | "other" | "unknown";
+    /**
+     * The pin's CURRENT runtime skip reason, re-read from account state at the
+     * moment the 503 is built. `accountSkipReasons` holds the SELECTION
+     * verdict, and on the dominant path the retry loop has already overwritten
+     * it with its own bookkeeping token ("already-attempted") — wording the
+     * sentence from that is what issue #675 reported. Omitted when the caller
+     * did not re-read runtime state.
+     */
+    currentSkipReason?: string | null;
     now?: number;
 }
 export declare function buildPinnedUnavailableErrorBody(pinnedIndex: number | null | undefined, accountSkipReasons: ReadonlyMap<number, string>, context?: PinnedUnavailableContext): PinnedUnavailableErrorBody;

package/dist/lib/request/rate-limit-decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit-decision.d.ts","sourceRoot":"","sources":["../../../lib/request/rate-limit-decision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAe/C,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGlE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GAAG,OAAO,CAWjG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBlF;AAYD,wBAAgB,0BAA0B,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAuB3E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBxE;AA0BD,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,MAAM,GACT,MAAM,CAcR;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAE1E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kCAAkC,CAAC;IACzC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mEAAmE;IACnE,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAQD,MAAM,WAAW,wBAAwB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACvC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,+BAA+B,CAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/C,OAAO,CAAC,EAAE,wBAAwB,GAChC,0BAA0B,CAwD5B"}
+{"version":3,"file":"rate-limit-decision.d.ts","sourceRoot":"","sources":["../../../lib/request/rate-limit-decision.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAe/C,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGlE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GAAG,OAAO,CAWjG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBlF;AAYD,wBAAgB,0BAA0B,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAuB3E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBxE;AA0BD,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,MAAM,GACT,MAAM,CAcR;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAE1E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kCAAkC,CAAC;IACzC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mEAAmE;IACnE,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAQD,MAAM,WAAW,wBAAwB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACvC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;IACnD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAwID,wBAAgB,+BAA+B,CAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/C,OAAO,CAAC,EAAE,wBAAwB,GAChC,0BAA0B,CA8E5B"}

package/dist/lib/request/rate-limit-decision.js

@@ -177,12 +177,107 @@ export function normalizeExhaustionStatus(reason) {
  * throws RangeError (ECMAScript time-value limit, ±100,000,000 days).
  */
 const MAX_ECMASCRIPT_TIME_VALUE = 8_640_000_000_000_000;
+const DEADLINE_SENTENCES = {
+    "available-again": (resetAt) => `the account is expected to be available again at ${resetAt}`,
+    "next-attempt": (resetAt) => `the next attempt is allowed at ${resetAt}`,
+    "cooldown-ends": (resetAt) => `the cooldown ends at ${resetAt}`,
+    "rate-limit-reset": (resetAt) => `the rate limit resets at ${resetAt}`,
+};
+/**
+ * Every cooldown variant is bounded by the same `coolingDownUntil` field, so
+ * they all word their deadline the same way. Two of them used to say "the next
+ * attempt is allowed at" while the rest said "the cooldown ends at", which
+ * reads as two different mechanisms to an operator comparing two 503s.
+ *
+ * `satisfies` is what keeps this honest: a new CooldownReason becomes a
+ * compile error here rather than falling through to the verbatim arm below,
+ * which would print the raw `cooling-down:<reason>` token in the sentence —
+ * the internal-token leak issue #675 was filed about.
+ */
+const COOLDOWN_DESCRIPTIONS = {
+    "auth-failure": {
+        parenthetical: "cooling down after authentication failures",
+        deadlineNoun: "cooldown-ends",
+    },
+    "network-error": {
+        parenthetical: "cooling down after network errors",
+        deadlineNoun: "cooldown-ends",
+    },
+    "server-error": {
+        parenthetical: "cooling down after upstream server errors",
+        deadlineNoun: "cooldown-ends",
+    },
+    "rate-limit": {
+        parenthetical: "cooling down after a rate limit",
+        deadlineNoun: "cooldown-ends",
+    },
+};
+const BLOCKER_DESCRIPTIONS = new Map([
+    [
+        "rate-limited",
+        // Upgraded to "rate-limit-reset" below when the caller confirms the
+        // rate limit is what bounds the advertised deadline.
+        { parenthetical: "rate-limited", deadlineNoun: "available-again" },
+    ],
+    [
+        "circuit-open",
+        {
+            parenthetical: "paused after repeated upstream errors",
+            deadlineNoun: "next-attempt",
+        },
+    ],
+    ["cooling-down", { parenthetical: "cooling down", deadlineNoun: "cooldown-ends" }],
+    ...Object.entries(COOLDOWN_DESCRIPTIONS).map(([reason, description]) => [
+        `cooling-down:${reason}`,
+        description,
+    ]),
+]);
+/** Whether the sentence has real wording for this token, or must echo it raw. */
+function isDescribedBlocker(skipReason) {
+    return BLOCKER_DESCRIPTIONS.has(skipReason);
+}
+/**
+ * The human sentence derives its parenthetical and its deadline noun from the
+ * blocker class. The deadline is max(rate-limit reset, cooldown end, breaker
+ * next-attempt), so calling it a "limit" is only true for the rate-limit
+ * class: during a provider outage a tripped breaker or a server-error
+ * cooldown printed "the recorded limit resets at …", and operators read a
+ * backend incident as a blown subscription quota. Only the message changes —
+ * the machine-readable `reason` keeps the raw skip token.
+ */
+function describePinnedBlocker(skipReason, rateLimitBoundsRecovery) {
+    if (skipReason === null) {
+        return {
+            parenthetical: null,
+            deadline: DEADLINE_SENTENCES["available-again"],
+        };
+    }
+    const described = BLOCKER_DESCRIPTIONS.get(skipReason);
+    if (described === undefined) {
+        // Permanent blockers never reach the deadline clause (the call site
+        // suppresses their reset time), and future or internal tokens stay
+        // legible verbatim.
+        return {
+            parenthetical: skipReason,
+            deadline: DEADLINE_SENTENCES["available-again"],
+        };
+    }
+    // A breaker or cooldown can outlive the rate limit; the deadline is the max
+    // of every gating record, so it is only worded as the limit's own reset
+    // when the rate limit actually supplies it.
+    const deadlineNoun = skipReason === "rate-limited" && rateLimitBoundsRecovery
+        ? "rate-limit-reset"
+        : described.deadlineNoun;
+    return {
+        parenthetical: described.parenthetical,
+        deadline: DEADLINE_SENTENCES[deadlineNoun],
+    };
+}
 export function buildPinnedUnavailableErrorBody(pinnedIndex, accountSkipReasons, context) {
     const normalizedPinnedIndex = typeof pinnedIndex === "number" ? pinnedIndex : null;
     const skipReason = normalizedPinnedIndex !== null
         ? accountSkipReasons.get(normalizedPinnedIndex) ?? null
         : null;
-    const reasonSuffix = skipReason ? ` (${skipReason})` : "";
     // On the desync path the pin index is unknown (null); claiming "account 1"
     // there would contradict the machine-readable pinnedAccountIndex: null.
     const accountPhrase = normalizedPinnedIndex === null
@@ -206,7 +301,27 @@ export function buildPinnedUnavailableErrorBody(pinnedIndex, accountSkipReasons,
     const now = context?.now ?? Date.now();
     const retryAfterMs = resetAtMs !== null ? Math.max(0, resetAtMs - now) : null;
     const resetAt = resetAtMs !== null ? new Date(resetAtMs).toISOString() : null;
-    const waitSuffix = resetAt !== null ? `; the recorded limit resets at ${resetAt}` : "";
+    // "unknown" (the default) means the caller did not measure which record
+    // bounds the deadline — older callers and unit seams — so trust the skip
+    // reason. Only a measured "other" demotes to the neutral phrasing, which
+    // stays true for a live rate limit either way.
+    const rateLimitBoundsRecovery = (context?.recoveryBound ?? "unknown") !== "other";
+    // The machine-readable `reason` below stays the recorded SELECTION verdict;
+    // only the human sentence follows the blocker actually gating the pin. A
+    // recorded verdict that names a real blocker class wins, because the
+    // selection-only classes ("missing", "policy-blocked") have no
+    // runtime-state equivalent and would be lost. Otherwise the re-read runtime
+    // state is the truth and the recorded token is the retry loop's own
+    // bookkeeping — the dominant path in issue #675, where a 503/429 on the pin
+    // re-enters selection and records "already-attempted" over the real class.
+    const describedSkipReason = skipReason !== null && isDescribedBlocker(skipReason)
+        ? skipReason
+        : context?.currentSkipReason ?? skipReason;
+    const blocker = describePinnedBlocker(describedSkipReason, rateLimitBoundsRecovery);
+    const reasonSuffix = blocker.parenthetical
+        ? ` (${blocker.parenthetical})`
+        : "";
+    const waitSuffix = resetAt !== null ? `; ${blocker.deadline(resetAt)}` : "";
     // A forced pin belongs to the launching process, not to the persisted pin
     // state, so `unpin` would clear nothing — say what actually helps.
     const remedy = pinSource === "forced"

package/dist/lib/runtime/account-status.d.ts

@@ -7,22 +7,51 @@ export declare function resolveActiveIndex(storage: {
 export declare function getRateLimitResetTimeForFamily(account: {
     rateLimitResetTimes?: Record<string, number | undefined>;
 }, now: number, family: ModelFamily): number | null;
+export interface AccountRecoveryBounds {
+    /**
+     * The moment the account becomes usable again: `rateLimitAtMs` widened by
+     * any active cooldown, because the account stays skipped while ANY gating
+     * record is active. Null when nothing bounds recovery.
+     */
+    recoveryAtMs: number | null;
+    /**
+     * The rate-limit records' own contribution to `recoveryAtMs`, cooldowns
+     * excluded. The pinned-503 uses it to decide whether the deadline it
+     * advertises is in fact the rate limit's own reset — with a breaker or
+     * cooldown ending later, the full recovery bound outlives the rate limit
+     * and must not be worded as its reset. Null when no rate-limit record
+     * gates the request.
+     */
+    rateLimitAtMs: number | null;
+}
 /**
- * The moment the account becomes usable again for a `family`/`model`
- * request: the LATEST bound among the records that actually gate that
- * request plus any active cooldown. Two deliberate differences from
- * getRateLimitResetTimeForFamily, whose earliest-reset answer feeds wait
- * displays: the account stays skipped while ANY gating record is active,
- * so the earliest reset would send clients back into a 503 — and only the
- * keys selection consults (`family`, plus `family:<model>` when a model is
- * known; see isRateLimitedForFamily) may contribute, because another
- * model's record does not block this request and would overstate its
- * recovery. Null when nothing bounds recovery.
+ * Both recovery bounds for a `family`/`model` request, from ONE pass over
+ * `rateLimitResetTimes` against a single `now`.
+ *
+ * Two deliberate differences from getRateLimitResetTimeForFamily, whose
+ * earliest-reset answer feeds wait displays: the latest bound wins, because
+ * the earliest reset would send clients back into a 503 — and only the keys
+ * selection consults (`family`, plus `family:<model>` when a model is known;
+ * see isRateLimitedForFamily) may contribute, because another model's record
+ * does not block this request and would overstate its recovery.
+ *
+ * A caller that needs both bounds must take them from one call. Measuring
+ * them separately lets a record expire between the two walks, which reports
+ * a rate-limited account as if a cooldown bounded its recovery.
  */
+export declare function getAccountRecoveryBoundsForFamily(account: {
+    rateLimitResetTimes?: Record<string, number | undefined>;
+    coolingDownUntil?: number;
+}, now: number, family: ModelFamily, model?: string | null): AccountRecoveryBounds;
+/** The `recoveryAtMs` bound alone; see getAccountRecoveryBoundsForFamily. */
 export declare function getAccountRecoveryTimeForFamily(account: {
     rateLimitResetTimes?: Record<string, number | undefined>;
     coolingDownUntil?: number;
 }, now: number, family: ModelFamily, model?: string | null): number | null;
+/** The `rateLimitAtMs` bound alone; see getAccountRecoveryBoundsForFamily. */
+export declare function getRateLimitRecoveryTimeForFamily(account: {
+    rateLimitResetTimes?: Record<string, number | undefined>;
+}, now: number, family: ModelFamily, model?: string | null): number | null;
 export declare function formatRateLimitEntry(account: {
     rateLimitResetTimes?: Record<string, number | undefined>;
 }, now: number, formatWaitTime: (ms: number) => string, family?: ModelFamily): string | null;

package/dist/lib/runtime/account-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-status.d.ts","sourceRoot":"","sources":["../../../lib/runtime/account-status.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,wBAAgB,kBAAkB,CACjC,OAAO,EAAE;IACR,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,QAAQ,EAAE,OAAO,EAAE,CAAC;CACpB,EACD,MAAM,GAAE,WAAqB,GAC3B,MAAM,CAOR;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GACjB,MAAM,GAAG,IAAI,CAgBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC9C,OAAO,EAAE;IACR,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B,EACD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,GAAG,IAAI,CAcf;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EACtC,MAAM,GAAE,WAAqB,GAC3B,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAcf"}
+{"version":3,"file":"account-status.d.ts","sourceRoot":"","sources":["../../../lib/runtime/account-status.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,wBAAgB,kBAAkB,CACjC,OAAO,EAAE;IACR,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,QAAQ,EAAE,OAAO,EAAE,CAAC;CACpB,EACD,MAAM,GAAE,WAAqB,GAC3B,MAAM,CAOR;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GACjB,MAAM,GAAG,IAAI,CAgBf;AAeD,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iCAAiC,CAChD,OAAO,EAAE;IACR,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B,EACD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,qBAAqB,CAevB;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAC9C,OAAO,EAAE;IACR,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B,EACD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,GAAG,IAAI,CAGf;AAED,8EAA8E;AAC9E,wBAAgB,iCAAiC,CAChD,OAAO,EAAE;IACR,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzD,EACD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACnB,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EACtC,MAAM,GAAE,WAAqB,GAC3B,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,EACrE,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAGf"}

package/dist/lib/runtime/account-status.js

@@ -26,36 +26,54 @@ export function getRateLimitResetTimeForFamily(account, now, family) {
     }
     return minReset;
 }
+/** The value when it is still a live bound at `now`, otherwise null. */
+function activeBound(value, now) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return value > now ? value : null;
+}
+/** The later of two bounds, treating null as "does not bound". */
+function laterBound(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return a > b ? a : b;
+}
 /**
- * The moment the account becomes usable again for a `family`/`model`
- * request: the LATEST bound among the records that actually gate that
- * request plus any active cooldown. Two deliberate differences from
- * getRateLimitResetTimeForFamily, whose earliest-reset answer feeds wait
- * displays: the account stays skipped while ANY gating record is active,
- * so the earliest reset would send clients back into a 503 — and only the
- * keys selection consults (`family`, plus `family:<model>` when a model is
- * known; see isRateLimitedForFamily) may contribute, because another
- * model's record does not block this request and would overstate its
- * recovery. Null when nothing bounds recovery.
+ * Both recovery bounds for a `family`/`model` request, from ONE pass over
+ * `rateLimitResetTimes` against a single `now`.
+ *
+ * Two deliberate differences from getRateLimitResetTimeForFamily, whose
+ * earliest-reset answer feeds wait displays: the latest bound wins, because
+ * the earliest reset would send clients back into a 503 — and only the keys
+ * selection consults (`family`, plus `family:<model>` when a model is known;
+ * see isRateLimitedForFamily) may contribute, because another model's record
+ * does not block this request and would overstate its recovery.
+ *
+ * A caller that needs both bounds must take them from one call. Measuring
+ * them separately lets a record expire between the two walks, which reports
+ * a rate-limited account as if a cooldown bounded its recovery.
  */
-export function getAccountRecoveryTimeForFamily(account, now, family, model) {
-    let latest = null;
-    const consider = (value) => {
-        if (typeof value !== "number" || !Number.isFinite(value))
-            return;
-        if (value <= now)
-            return;
-        if (latest === null || value > latest)
-            latest = value;
-    };
+export function getAccountRecoveryBoundsForFamily(account, now, family, model) {
     const times = account.rateLimitResetTimes;
-    if (times) {
-        consider(times[getQuotaKey(family)]);
-        if (model)
-            consider(times[getQuotaKey(family, model)]);
-    }
-    consider(account.coolingDownUntil);
-    return latest;
+    const rateLimitAtMs = times
+        ? laterBound(activeBound(times[getQuotaKey(family)], now), model ? activeBound(times[getQuotaKey(family, model)], now) : null)
+        : null;
+    return {
+        rateLimitAtMs,
+        recoveryAtMs: laterBound(rateLimitAtMs, activeBound(account.coolingDownUntil, now)),
+    };
+}
+/** The `recoveryAtMs` bound alone; see getAccountRecoveryBoundsForFamily. */
+export function getAccountRecoveryTimeForFamily(account, now, family, model) {
+    return getAccountRecoveryBoundsForFamily(account, now, family, model)
+        .recoveryAtMs;
+}
+/** The `rateLimitAtMs` bound alone; see getAccountRecoveryBoundsForFamily. */
+export function getRateLimitRecoveryTimeForFamily(account, now, family, model) {
+    return getAccountRecoveryBoundsForFamily(account, now, family, model)
+        .rateLimitAtMs;
 }
 export function formatRateLimitEntry(account, now, formatWaitTime, family = "codex") {
     const resetAt = getRateLimitResetTimeForFamily(account, now, family);
@@ -86,19 +104,6 @@ export function formatRateLimitEntry(account, now, formatWaitTime, family = "cod
  * model key applies and should keep the family-wide union above.
  */
 export function getRateLimitResetTimeForModel(account, now, family, model) {
-    const times = account.rateLimitResetTimes;
-    if (!times)
-        return null;
-    let latest = null;
-    const consider = (value) => {
-        if (typeof value !== "number" || !Number.isFinite(value))
-            return;
-        if (value <= now)
-            return;
-        if (latest === null || value > latest)
-            latest = value;
-    };
-    consider(times[getQuotaKey(family)]);
-    consider(times[getQuotaKey(family, model)]);
-    return latest;
+    return getAccountRecoveryBoundsForFamily(account, now, family, model)
+        .rateLimitAtMs;
 }

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

@@ -15,7 +15,7 @@ import { CodexValidationError } from "./errors.js";
 import { normalizeEmailKey } from "./storage/identity.js";
 import { buildPinnedUnavailableErrorBody, buildTokenInvalidationBody, extractErrorCodeFromBody, isTokenInvalidationError, normalizeExhaustionStatus, parseRetryAfterBodyMs, parseRetryAfterHeaderMs, } from "./request/rate-limit-decision.js";
 import { forwardStreamingResponse, HOP_BY_HOP_HEADERS, readErrorBody, responseHeadersForClient, withTimeout, } from "./request/stream-failover-runtime.js";
-import { getAccountRecoveryTimeForFamily } from "./runtime/account-status.js";
+import { getAccountRecoveryBoundsForFamily } from "./runtime/account-status.js";
 import { chooseAccount } from "./runtime/rotation-account-selection.js";
 import { createRotationProxyState, recoverStaleRuntimeState, } from "./runtime/rotation-proxy-state.js";
 import { readStorageMetaFromDisk } from "./runtime/rotation-storage-meta.js";
@@ -1219,23 +1219,45 @@ async function handleRequestInner(state, req, res, traceId) {
             // recovery — and with several overlapping records the account stays
             // skipped until the LAST one expires, so the latest bound is the one
             // worth advertising.
-            const pinnedStateRecoveryAtMs = pinnedAccount === null
+            //
+            // One clock for the whole body. The recovery bound and the
+            // rate-limit bound are compared against each other below, so
+            // reading state.now() per lookup would let a record expire between
+            // them and report a rate-limited pin as bounded by something else.
+            const evaluatedAtMs = state.now();
+            // Both bounds come from a single pass over the account's records.
+            const pinnedRecoveryBounds = pinnedAccount === null
                 ? null
-                : getAccountRecoveryTimeForFamily(pinnedAccount, state.now(), context.family, context.model);
+                : getAccountRecoveryBoundsForFamily(pinnedAccount, evaluatedAtMs, context.family, context.model);
+            const pinnedStateRecoveryAtMs = pinnedRecoveryBounds?.recoveryAtMs ?? null;
             // An open circuit outlives the short failure cooldowns that tripped
             // it; its deadline lives in the breaker, not the account record.
             const pinnedCircuitRecoveryAtMs = pinnedAccount === null
                 ? null
-                : accountManager.getCircuitRecoveryTime(pinnedAccount, state.now());
+                : accountManager.getCircuitRecoveryTime(pinnedAccount, evaluatedAtMs);
             const pinnedResetAtMs = pinnedBlockedPermanently ||
                 (pinnedStateRecoveryAtMs === null && pinnedCircuitRecoveryAtMs === null)
                 ? null
                 : Math.max(pinnedStateRecoveryAtMs ?? 0, pinnedCircuitRecoveryAtMs ?? 0);
+            // The message only words the recovery deadline as a rate-limit reset
+            // when the rate-limit records are in fact what supplies it — a
+            // breaker or cooldown can end later and then bounds it instead.
+            const pinnedRateLimitResetAtMs = pinnedRecoveryBounds?.rateLimitAtMs ?? null;
+            const recoveryBound = pinnedResetAtMs !== null &&
+                pinnedRateLimitResetAtMs !== null &&
+                pinnedRateLimitResetAtMs >= pinnedResetAtMs
+                ? "rate-limit"
+                : "other";
             const errorBody = buildPinnedUnavailableErrorBody(pinnedIndex, accountSkipReasons, {
                 // typeof check so a forced index of 0 still reads as forced.
                 pinSource: typeof state.forcedAccountIndex === "number" ? "forced" : "manual",
                 resetAtMs: pinnedResetAtMs,
-                now: state.now(),
+                recoveryBound,
+                // The recorded verdict above is the retry loop's
+                // "already-attempted" on the dominant path; the re-read runtime
+                // state is what the operator-facing sentence should describe.
+                currentSkipReason: pinnedCurrentSkipReason,
+                now: evaluatedAtMs,
             });
             if (errorBody.reason === null) {
                 state.status.lastError = `pinned-503 missing skip reason (pinnedIndex=${pinnedIndex})`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-multi-auth",
-	"version": "2.8.6",
+	"version": "2.8.7",
 	"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

@@ -421,6 +421,14 @@ function extractForcedAccountFlag(args) {
 	let sawFlag = false;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
+		// `--` ends option parsing: everything after it is Codex's root
+		// `[PROMPT]` text. A `--account` spelled in there is the user's prompt,
+		// not a launcher flag — stripping it would both mangle the prompt and
+		// silently pin the run to an account nobody selected.
+		if (arg === "--") {
+			strippedArgs.push(...args.slice(index));
+			break;
+		}
 		if (arg === "--account") {
 			sawFlag = true;
 			const next = args[index + 1];
@@ -1365,6 +1373,9 @@ function replaceRequestedModel(args, nextModel) {
 	const nextArgs = [...args];
 	for (let i = 0; i < nextArgs.length; i += 1) {
 		const arg = nextArgs[i];
+		// Past `--` the tokens are the user's prompt. Rewriting one in place
+		// would edit the prompt text itself before re-forwarding it.
+		if (arg === "--") break;
 		if ((arg === "--model" || arg === "-m") && typeof nextArgs[i + 1] === "string") {
 			nextArgs[i + 1] = nextModel;
 			return nextArgs;
@@ -1859,6 +1870,11 @@ async function forwardToRealCodex(codexBin, rawArgs, baseEnv = process.env) {
 function hasCliAuthCredentialsStoreOverride(args) {
 	for (let i = 0; i < args.length; i += 1) {
 		const arg = args[i];
+		// Everything after `--` is the root `[PROMPT]` positional, not options:
+		// a prompt whose text spells `--config=cli_auth_credentials_store=...` is
+		// not a caller override, and treating it as one would silently drop the
+		// file auth store this wrapper depends on.
+		if (arg === "--") break;
 		if (arg === "-c" || arg === "--config") {
 			const next = args[i + 1];
 			if (!next || !next.includes("=")) continue;
@@ -2357,6 +2373,10 @@ function coerceReasoningEffortForModel(model, effort) {
 function extractRequestedModel(args) {
 	for (let i = 0; i < args.length; i += 1) {
 		const arg = args[i];
+		// Past `--` every token is root `[PROMPT]` text; a `-m` in there names
+		// no model, and reading one would coerce reasoning config for a model
+		// the user never requested.
+		if (arg === "--") break;
 		if (arg === "--model" || arg === "-m") {
 			const next = args[i + 1];
 			if (typeof next === "string" && next.trim().length > 0) {
@@ -2427,6 +2447,8 @@ function rewriteReasoningConfigArgs(rawArgs) {
 	const nextArgs = [...rawArgs];
 	for (let i = 0; i < nextArgs.length; i += 1) {
 		const arg = nextArgs[i];
+		// Past `--` a `-c key=value` pair is prompt text, not a config override.
+		if (arg === "--") break;
 		if ((arg === "-c" || arg === "--config") && typeof nextArgs[i + 1] === "string") {
 			nextArgs[i + 1] = rewriteReasoningConfigAssignment(
 				nextArgs[i + 1],
@@ -4903,13 +4925,20 @@ async function createRuntimeRotationAppHelperContext(
 		}
 	};
 
+	const injectedArgs = [
+		...helperArgs,
+		"-c",
+		`model_provider=${configTomlModule.tomlStringLiteral(RUNTIME_ROTATION_PROXY_PROVIDER_ID)}`,
+	];
 	return {
-		args: [
-			...baseContext.args,
-			...helperArgs,
-			"-c",
-			`model_provider=${configTomlModule.tomlStringLiteral(RUNTIME_ROTATION_PROXY_PROVIDER_ID)}`,
-		],
+		// Root TUI argv can end in the optional `[PROMPT]` positional, and `--`
+		// binds everything after it to that positional — overrides appended
+		// there would become prompt text, so the interactive branch asks for
+		// them to be injected ahead of the prompt instead.
+		args:
+			options.injectArgsBeforeRootPrompt === true
+				? insertArgsBeforeRootPrompt(baseContext.args, injectedArgs)
+				: insertArgsBeforeForwardedSeparator(baseContext.args, injectedArgs),
 		env: {
 			...baseContext.env,
 			...helperEnv,
@@ -4991,13 +5020,19 @@ async function createRuntimeRotationProxyContextIfEnabled(
 	if (isCodexAppCommand(rawArgs)) {
 		return startAppHelperContext();
 	}
-	if (
-		isCodexInteractiveTuiCommand(rawArgs) ||
-		isCodexInteractiveResumeCommand(rawArgs)
-	) {
+	// Classify once: each predicate re-walks the whole argv, and the root-TUI
+	// answer is needed twice below.
+	const isRootTuiLaunch = isCodexInteractiveTuiCommand(rawArgs);
+	if (isRootTuiLaunch || isCodexInteractiveResumeCommand(rawArgs)) {
 		return startAppHelperContext({
 			detachOnExit: true,
 			useCanonicalHome: true,
+			// Root TUI launches may carry the optional `[PROMPT]` positional
+			// (possibly forced by `--`); the provider overrides must stay on the
+			// option side of it. `resume`/`fork` keep the appended ordering their
+			// argv has always forwarded with — their tokens are subcommand args,
+			// not the root prompt.
+			injectArgsBeforeRootPrompt: isRootTuiLaunch,
 		});
 	}
 
@@ -5088,90 +5123,257 @@ function isPureHelpOrVersionArgs(rawArgs) {
 	);
 }
 
+// Hoisted: every argv walk calls consumesNextArg once per token, and a Set
+// rebuilt per call allocated this list on every one of them.
+const OPTIONS_CONSUMING_NEXT_ARG = new Set([
+	"-c",
+	"--config",
+	"--enable",
+	"--disable",
+	"--listen",
+	"--remote",
+	"--remote-auth-token-env",
+	"--ws-auth",
+	"--ws-token-file",
+	"--ws-token-sha256",
+	"--ws-shared-secret-file",
+	"--ws-issuer",
+	"--ws-audience",
+	"--ws-max-clock-skew-seconds",
+	"--download-url",
+	"-i",
+	"--image",
+	"-m",
+	"--model",
+	"--local-provider",
+	"-p",
+	"--profile",
+	"-s",
+	"--sandbox",
+	"-a",
+	"--ask-for-approval",
+	"-C",
+	"--cd",
+	"--add-dir",
+	"--output-schema",
+	"--color",
+	"-o",
+	"--output-last-message",
+]);
+
 function consumesNextArg(arg) {
-	return new Set([
-		"-c",
-		"--config",
-		"--enable",
-		"--disable",
-		"--listen",
-		"--remote",
-		"--remote-auth-token-env",
-		"--ws-auth",
-		"--ws-token-file",
-		"--ws-token-sha256",
-		"--ws-shared-secret-file",
-		"--ws-issuer",
-		"--ws-audience",
-		"--ws-max-clock-skew-seconds",
-		"--download-url",
-		"-i",
-		"--image",
-		"-m",
-		"--model",
-		"--local-provider",
-		"-p",
-		"--profile",
-		"-s",
-		"--sandbox",
-		"-a",
-		"--ask-for-approval",
-		"-C",
-		"--cd",
-		"--add-dir",
-		"--output-schema",
-		"--color",
-		"-o",
-		"--output-last-message",
-	]).has(arg);
+	return OPTIONS_CONSUMING_NEXT_ARG.has(arg);
 }
 
-function findForwardedCommand(rawArgs) {
-	if (!Array.isArray(rawArgs) || rawArgs.length === 0) {
-		return null;
+// Codex's root grammar is `codex [OPTIONS] [PROMPT]` / `codex [OPTIONS]
+// <COMMAND> [ARGS]`, so the first positional is only a command when it names a
+// real root subcommand — otherwise it is the optional initial prompt of an
+// interactive TUI launch. The allowlist mirrors `codex --help`; treating an
+// unknown positional as a prompt matches native Codex, where an unrecognized
+// token also falls through to the prompt positional rather than erroring as a
+// bad subcommand. Routing predicates all resolve through this map so aliases
+// classify like their canonical command.
+//
+// A real root subcommand missing from this set is misrouted, not merely
+// misnamed: it classifies as an interactive prompt and takes the app-helper
+// branch with `detachOnExit: true`, so a short-lived command leaves a detached
+// helper and its loopback proxy idling until the rotation idle timeout. Keep
+// the set in sync with the upstream grammar — clap publishes the authoritative
+// root list in its own completions, so
+//   codex completion bash | grep -oE 'opts="[^"]*"' | grep ' exec '
+// prints every root command (and alias) for the installed codex-cli.
+
+const CODEX_ROOT_COMMAND_ALIASES = new Map([
+	["e", "exec"],
+	["a", "apply"],
+]);
+const CODEX_ROOT_COMMANDS = new Set([
+	"exec",
+	"review",
+	"login",
+	"logout",
+	"mcp",
+	"plugin",
+	"mcp-server",
+	"app-server",
+	"remote-control",
+	"app",
+	"completion",
+	"update",
+	"doctor",
+	"sandbox",
+	"debug",
+	"apply",
+	"resume",
+	"archive",
+	"delete",
+	"migrate-rollouts",
+	"unarchive",
+	"fork",
+	"cloud",
+	"exec-server",
+	"features",
+	"help",
+	"auth",
+	// Hidden root subcommands: absent from `codex --help`, but real — each is
+	// documented by `codex help <name>`.
+	"responses-api-proxy",
+	"cloud-tasks",
+	"execpolicy",
+	// Internal stdio/UDS relay. Hidden like the three above, and short-lived:
+	// omitting it classified `codex stdio-to-uds <socket>` as a root prompt,
+	// which took the detached app-helper branch and leaked a helper per call.
+	"stdio-to-uds",
+]);
+
+function resolveCodexRootCommand(token) {
+	const command = CODEX_ROOT_COMMAND_ALIASES.get(token) ?? token;
+	return CODEX_ROOT_COMMANDS.has(command) ? command : null;
+}
+
+// `-i/--image` is greedy (`<FILE>...`): native Codex consumes every following
+// free token up to the next option-like token, so a prompt can only follow the
+// image list after another option or a `--`. Every argv walker below skips the
+// same span, or the wrapper would disagree with native Codex about where the
+// positional side starts.
+function consumesRemainingFreeArgs(arg) {
+	return arg === "-i" || arg === "--image";
+}
+
+function skipOptionValueSpan(args, i) {
+	const arg = args[i];
+	if (consumesRemainingFreeArgs(arg)) {
+		let end = i;
+		while (
+			end + 1 < args.length &&
+			typeof args[end + 1] === "string" &&
+			args[end + 1].length > 0 &&
+			(args[end + 1] === "-" || !args[end + 1].startsWith("-"))
+		) {
+			end += 1;
+		}
+		return end;
 	}
-	for (let i = 0; i < rawArgs.length; i += 1) {
-		const arg = rawArgs[i];
+	return consumesNextArg(arg) ? i + 1 : i;
+}
+
+/**
+ * The single definition of where an argv's option side ends. Walking from
+ * `startIndex`, skips option flags and the values they consume — including a
+ * greedy `-i a.png b.png` span — and reports what stopped the walk:
+ *
+ * - `index`: the first free (positional) token, or null when there is none.
+ * - `terminatorIndex`: the bare `--` that ended option parsing, or null.
+ * - `boundary`: where option-side content ends, i.e. the positional, the
+ *   `--`, or `args.length`. This is where injected overrides belong.
+ *
+ * Callers keep their own policy for `--` (the root grammar binds everything
+ * after it to `[PROMPT]`; a subcommand's does not), but they must not keep
+ * their own copy of the walk: a classifier and an injector that disagree by
+ * one token put a `-c` override into prompt text or read prompt text as a
+ * subcommand.
+ */
+function findRootPositional(args, startIndex = 0) {
+	if (!Array.isArray(args)) {
+		return { index: null, terminatorIndex: null, boundary: 0 };
+	}
+	for (let i = startIndex; i < args.length; i += 1) {
+		const arg = args[i];
 		if (typeof arg !== "string" || arg.length === 0) continue;
 		if (arg === "--") {
-			return i + 1 < rawArgs.length
-				? { command: rawArgs[i + 1], index: i + 1 }
-				: null;
+			return { index: null, terminatorIndex: i, boundary: i };
 		}
 		if (arg.startsWith("--config=")) {
 			continue;
 		}
 		if (arg.startsWith("--") || (arg.startsWith("-") && arg !== "-")) {
-			if (consumesNextArg(arg)) {
-				i += 1;
-			}
+			i = skipOptionValueSpan(args, i);
 			continue;
 		}
-		return { command: arg, index: i };
+		return { index: i, terminatorIndex: null, boundary: i };
+	}
+	return { index: null, terminatorIndex: null, boundary: args.length };
+}
+
+function findForwardedCommand(rawArgs) {
+	if (!Array.isArray(rawArgs) || rawArgs.length === 0) {
+		return null;
+	}
+	// `--` ends option parsing: everything after it binds to the root
+	// `[PROMPT]` positional, never to a subcommand, even when the text happens
+	// to spell a command name. `findRootPositional` reports it as a terminator
+	// and yields no positional, which settles the launch as interactive.
+	//
+	// Native Codex fills the root `[PROMPT]` slot with the first free token and
+	// still tries a later one as a subcommand (`codex hello exec …` runs exec),
+	// so an unknown positional keeps the scan going.
+	for (
+		let cursor = findRootPositional(rawArgs, 0);
+		cursor.index !== null;
+		cursor = findRootPositional(rawArgs, cursor.index + 1)
+	) {
+		const command = resolveCodexRootCommand(rawArgs[cursor.index]);
+		if (command !== null) {
+			return { command, index: cursor.index };
+		}
 	}
 
 	return null;
 }
 
+// Inserts option-side args ahead of the root `[PROMPT]` positional (or the
+// `--` that forces one), so injected overrides cannot be read as prompt text.
+// With no positional at all this is a plain append, which keeps bare-TUI argv
+// byte-identical to the pre-insertion shape.
+function insertArgsBeforeRootPrompt(baseArgs, injectedArgs) {
+	const { boundary } = findRootPositional(baseArgs);
+	return [
+		...baseArgs.slice(0, boundary),
+		...injectedArgs,
+		...baseArgs.slice(boundary),
+	];
+}
+
+// Inserts args before a `--` separator when one is present, else appends.
+// Subcommand argv keeps its leading subcommand token — `resume`/`fork` argv is
+// pinned to it — but anything appended past a `--` lands in the subcommand's
+// own positional list: Codex rejects that outright for `exec`/`review`
+// ("unexpected argument '-c' found"), and worse, silently forwards it as
+// arguments for `sandbox` and into the stored config for `mcp add`. The
+// separator bounds the append.
+function insertArgsBeforeForwardedSeparator(baseArgs, injectedArgs) {
+	// Deliberately not `findRootPositional`: that reports where the option side
+	// ends, stopping at the first positional, and a subcommand's own arguments
+	// are positionals — it would answer `exec` for `exec -- hi`. The question
+	// here is only where the separator sits, and a bare `indexOf` answers it
+	// exactly: clap never consumes `--` as an option value (`codex --cd -- hi`
+	// is "a value is required for '--cd'"), so the first `--` is always the
+	// separator, and it always follows the subcommand token because
+	// `findForwardedCommand` returns null the moment it sees one.
+	const separatorIndex = baseArgs.indexOf("--");
+	if (separatorIndex === -1) {
+		return [...baseArgs, ...injectedArgs];
+	}
+	return [
+		...baseArgs.slice(0, separatorIndex),
+		...injectedArgs,
+		...baseArgs.slice(separatorIndex),
+	];
+}
+
 function findForwardedSubcommand(rawArgs, commandIndex) {
-	for (let i = commandIndex + 1; i < rawArgs.length; i += 1) {
-		const arg = rawArgs[i];
-		if (typeof arg !== "string" || arg.length === 0) continue;
-		if (arg === "--") {
-			return i + 1 < rawArgs.length ? rawArgs[i + 1] : null;
-		}
-		if (arg.startsWith("--config=")) {
-			continue;
-		}
-		if (arg.startsWith("--") || (arg.startsWith("-") && arg !== "-")) {
-			if (consumesNextArg(arg)) {
-				i += 1;
-			}
-			continue;
-		}
-		return arg;
+	const { index, terminatorIndex } = findRootPositional(
+		rawArgs,
+		commandIndex + 1,
+	);
+	// Unlike the root grammar, a subcommand's `--` still precedes its own
+	// positional args, so the token after it is the nested subcommand.
+	if (terminatorIndex !== null) {
+		return terminatorIndex + 1 < rawArgs.length
+			? rawArgs[terminatorIndex + 1]
+			: null;
 	}
-	return null;
+	return index === null ? null : rawArgs[index];
 }
 
 function hasHelpFlagAfterCommand(rawArgs, commandIndex) {
@@ -5179,8 +5381,8 @@ function hasHelpFlagAfterCommand(rawArgs, commandIndex) {
 		const arg = rawArgs[i];
 		if (arg === "--") return false;
 		if (arg === "--help" || arg === "-h" || arg === "help") return true;
-		if (typeof arg === "string" && consumesNextArg(arg)) {
-			i += 1;
+		if (typeof arg === "string") {
+			i = skipOptionValueSpan(rawArgs, i);
 		}
 	}
 	return false;
@@ -5194,6 +5396,11 @@ function isCodexAppServerCommand(rawArgs) {
 	return findForwardedCommand(rawArgs)?.command === "app-server";
 }
 
+// True for every root TUI launch: bare `codex [OPTIONS]`, and `codex
+// [OPTIONS] [PROMPT]` with the optional initial prompt — including a prompt
+// forced by `--`. Both shapes start the same interactive session and need the
+// canonical home, or Codex stalls rebuilding the omitted thread index inside
+// the shadow mirror before it can submit the already-delivered prompt.
 function isCodexInteractiveTuiCommand(rawArgs) {
 	return findForwardedCommand(rawArgs) === null;
 }
@@ -5219,7 +5426,14 @@ function shouldUseRuntimeRoutingForForwardedArgs(rawArgs) {
 
 	const command = findForwardedCommand(rawArgs);
 	if (!command) {
-		return true;
+		// A help flag alongside a root prompt (`codex "prompt" --help`) prints
+		// help and exits clean, so it must skip the transport for the same
+		// reason as the request-command help forms below: the interactive
+		// branch detaches its helper on a clean exit, and a helper started
+		// just to print help would idle until its detached timeout. The scan
+		// stops at `--`, so help-looking text inside a forced prompt still
+		// routes normally.
+		return !hasHelpFlagAfterCommand(rawArgs, -1);
 	}
 
 	const requestCommands = new Set(["exec", "review", "resume", "fork", "app"]);
@@ -5450,12 +5664,16 @@ function buildForwardArgs(rawArgs) {
 		return { args: compatibilityArgs, requestedModel };
 	}
 
+	const authStoreArgs = ["-c", 'cli_auth_credentials_store="file"'];
 	return {
-		args: [
-			...compatibilityArgs,
-			"-c",
-			'cli_auth_credentials_store="file"',
-		],
+		// A root launch may end in the `[PROMPT]` positional — possibly forced
+		// by `--`, where an appended `-c` pair would be read as prompt text —
+		// so the override is inserted on the option side of the prompt there.
+		// Subcommand argv keeps the appended ordering it has always forwarded.
+		args:
+			findForwardedCommand(compatibilityArgs) === null
+				? insertArgsBeforeRootPrompt(compatibilityArgs, authStoreArgs)
+				: insertArgsBeforeForwardedSeparator(compatibilityArgs, authStoreArgs),
 		requestedModel,
 	};
 }