feat(codex): selection order for the account pool

.gitignore

@@ -26,6 +26,9 @@ devlog/
 .omo/
 **/.omo/
 
+# Local development worktrees
+.worktrees/
+
 # Test-generated artifacts
 tests/.tmp-*/
 .claude/

README.md

@@ -56,7 +56,9 @@ opencodex is a lightweight local proxy that translates Codex's Responses API int
 It can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
 refresh their 5h / weekly / 30d quota in the dashboard, and let new sessions auto-route to the
 lowest-usage healthy account. Existing Codex threads stay pinned to the account that started them,
-so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation.
+so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation. Give the
+accounts a selection order when one of them — usually your Codex Desktop login — should only be
+reached for once the others are drained.
 
 ```
 Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider

docs-site/src/content/docs/guides/web-dashboard.md

@@ -100,8 +100,16 @@ catalog entry.
 
 The **Codex Auth** page manages the native ChatGPT/Codex route:
 
-- Manually choosing an account changes the next new Codex session; an already-bound thread keeps its
-  current account for that manual switch.
+- Manually choosing an account applies immediately: an already-bound thread moves to it on its next
+  request, and only requests already in flight keep the account they captured. A manual choice is also
+  pinned: the card shows a **PINNED** badge, and a higher selection order cannot preempt that account
+  until it is drained, you select another account, or you change any account's selection order.
+- Each account card carries a **Selection order** control (First, Earlier, Normal, Later, Last).
+  Higher order is used first, and the pool drops to a lower order only once every account above it is
+  drained or unavailable. A changed order applies from the next unbound request and never moves a
+  thread that is already bound. The Codex Desktop (main) account is ordered like any other, so it can
+  be set to **Last** and kept as the reserve. An order set from `ocx account priority` outside those
+  five presets stays visible and selectable on the card.
 - Thread affinity prevents per-request flapping. With quota auto-switch enabled, a long-running
   thread is periodically re-evaluated and may rebind after its relevant usage reaches the threshold
   and a strictly lower-usage eligible account exists.
@@ -136,6 +144,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
 | `POST /api/oauth/login` · `GET /api/oauth/status` | Start a provider OAuth flow and poll for completion. |
 | `GET /api/codex-auth/accounts?refresh=1` | List main and pool accounts, force quota refresh, and report main-account `hasCredential` / terminal `needsReauth` state. |
 | `PUT /api/codex-auth/active` · `PUT /api/codex-auth/auto-switch` · `PUT /api/codex-auth/failover` | Select the account for the next request and configure pool routing. |
+| `GET /api/codex-auth/active` · `PUT /api/codex-auth/accounts/priority` | Read the effective account (including `pinned` and which account is `pinnedAccountId`) and set one account's selection order. |
 | `POST /api/codex-auth/login` · `GET /api/codex-auth/login-status` | Add a pool account through browser login. |
 | `GET /api/logs?tail=50&provider=...&status=5xx` | Read recent request metadata with optional tail, provider, and exact/class status filters. |
 | `GET` / `PUT /api/subagent-models` | Read or set the five featured `spawn_agent` override models. |

docs-site/src/content/docs/ja/guides/web-dashboard.md

@@ -81,8 +81,16 @@ Codex タスクだけに適用され、このオプション自体が委任を
 
 **Codex 認証**ページはネイティブ ChatGPT/Codex ルートを管理します。
 
-- アカウントを直接選ぶと次の新規 Codex セッションから変わります。すでにアカウントが紐付いた thread はこの手動切り替えだけでは
-  途中で移動しません。
+- アカウントを直接選ぶとすぐに反映されます。すでにアカウントが紐付いた thread も次のリクエストで選んだ
+  アカウントに移り、すでに送信中のリクエストだけが取得済みのアカウントを使い続けます。手動で選んだアカウントは固定もされます。
+  カードに **固定中** バッジが付き、そのアカウントが使い切られるか、別のアカウントを選ぶか、いずれかの
+  アカウントの選択順序を変更するまで、より上位の選択順序が割り込むことはありません。
+- 各アカウントカードには **選択順序** のコントロール（最初 / 早め / 標準 / 遅め / 最後）があります。
+  順序が上のものから使われ、その上にあるアカウントがすべて使い切られるか利用できなくなって初めて
+  下の順序へ下がります。順序を変更すると **次の未バインドリクエスト** から適用され、すでにアカウントに
+  紐づいた thread を移動させることはありません。Codex Desktop（メイン）アカウントも同じように
+  並べ替えられるので、**最後** にして予備に回せます。`ocx account priority` でプリセット以外の値を設定した場合も、カード上に
+  選択肢として残ります。
 - Thread affinity がリクエストごとにアカウントが揺れるのを防ぎます。クォータ自動切り替えがオンなら長く
   実行される thread も定期的に再評価します。関連使用量がしきい値以上で、使用量が確実により低い
   健全アカウントがあればそのアカウントに再紐付けできます。
@@ -112,6 +120,7 @@ GUI はプロキシの JSON 管理 API を使うシンクライアントです
 | `POST /api/oauth/login` · `GET /api/oauth/status` | プロバイダー OAuth ログインを開始し完了可否を確認します。 |
 | `GET /api/codex-auth/accounts?refresh=1` | メインおよびプールアカウントを参照しクォータを強制更新し、メインの `hasCredential` / terminal `needsReauth` 状態を返します。 |
 | `PUT /api/codex-auth/active` · `PUT /api/codex-auth/auto-switch` · `PUT /api/codex-auth/failover` | 次のリクエストで使うアカウントとプールルーティングポリシーを設定します。 |
+| `GET /api/codex-auth/active` · `PUT /api/codex-auth/accounts/priority` | 実効アカウント（固定中かどうかを示す `pinned` と、固定されているアカウントを示す `pinnedAccountId` を含む）を読み、アカウント 1 件の選択順序を設定します。 |
 | `POST /api/codex-auth/login` · `GET /api/codex-auth/login-status` | ブラウザログインでプールアカウントを追加します。 |
 | `GET /api/logs?tail=50&provider=...&status=5xx` | tail、プロバイダー、正確な状態コードまたは状態等級で最近のリクエストメタデータを参照します。 |
 | `GET` / `PUT /api/subagent-models` | `spawn_agent` に優先公開するモデル 5 つを読むか設定します。 |

docs-site/src/content/docs/ja/reference/cli.md

@@ -202,7 +202,7 @@ ocx models --provider anthropic --json
 コマンド面は次のとおりです。
 
 ```text
-Usage: ocx account <list|current|use|refresh|auto-switch|remove|add-key> ...
+Usage: ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits> ...
 
 List and switch provider accounts and API-key pools (GUI parity).
 
@@ -211,9 +211,13 @@ current <provider>  Show the active account or key.
 use <provider> <id> Switch the active credential; 'main' selects the Codex App login.
 refresh <provider>  Force-refresh Codex or provider quota reports.
 auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
+priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.
 remove <provider> <id> --yes  Remove a stored account or key after an existence check.
 add-key <provider> [--label <label>]  Add a key read only from piped stdin.
-Codex pool switches apply to new sessions; running threads keep their account.
+login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
+reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
+Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
+A selection-order change applies from the next unbound request and never moves a bound thread.
 ```
 
 すべてのサブコマンドはプロキシが実行中である必要があり、CLI が記録されたランタイムポートを自動的に探します。成功は
@@ -231,6 +235,7 @@ API エラーは終了コード 1 です。認証情報フィールドは manage
   "email": "m***@example.com",
   "plan": "plus",
   "masked": "sk-ab****wxyz",
+  "priority": 0,
   "active": true,
   "needsReauth": false,
   "quota": null
@@ -240,8 +245,8 @@ API エラーは終了コード 1 です。認証情報フィールドは manage
 #### `ocx account list [provider] [--json] [--all]`
 
 プロバイダーを省略すると Codex pool、OAuth アカウント、設定された API-key pool をすべて一覧します。空の
-プロバイダーは `--all` を指定しない限り飛ばし、プロバイダーを指定するとその認証情報 family だけを照会します。通常出力列は `PROVIDER TYPE ID PLAN/LABEL STATUS` で固定 Codex 行には
-`selected` が表示されます。保存された Kiro アカウントがある場合、ログインスロットは 1 つで再ログインすると現在のアカウントが差し替わる旨の案内が出ます。結果が空でも成功です。`--json` は次を返します。
+プロバイダーは `--all` を指定しない限り飛ばし、プロバイダーを指定するとその認証情報 family だけを照会します。通常出力列は `PROVIDER TYPE ID PLAN/LABEL PRIORITY STATUS` で固定 Codex 行には
+`selected` が表示されます。`PRIORITY` は符号付きの Codex 選択順（未設定なら `0`）で、OAuth アカウントや API key など順序が適用されない行には `-` が入ります。保存された Kiro アカウントがある場合、ログインスロットは 1 つで再ログインすると現在のアカウントが差し替わる旨の案内が出ます。結果が空でも成功です。`--json` は次を返します。
 
 ```text
 { accounts: AccountRow[], notes: string[] }
@@ -258,9 +263,9 @@ API エラーは終了コード 1 です。認証情報フィールドは manage
 #### `ocx account use <provider> <account-or-key-id|main> [--json]`
 
 既存の Codex アカウント、OAuth アカウント、または API key を選びます。`openai` で `main` は Codex App ログインを
-選択します。Codex の選択は **新しいセッション** から適用され、既存の thread は現在のアカウントを維持します。auto-switch
-threshold がオンなら後で手動 pin を上書きできます。不明なプロバイダーや id は終了
-コード 1 です。`--json` は次を返します。
+選択します。Codex の選択は **すぐに反映** されます。実行中の thread は次のリクエストで移動し、すでに送信中の
+リクエストだけが取得済みのアカウントを使い続けます。auto-switch threshold がオンなら後で手動 pin を
+上書きできます。不明なプロバイダーや id は終了コード 1 です。`--json` は次を返します。
 
 ```text
 { ok: true, provider, type, activeId }
@@ -286,6 +291,28 @@ OAuth および API-key プロバイダーでは provider quota-report endpoint
 { provider, autoSwitchThreshold: number, enabled: boolean }
 ```
 
+#### `ocx account priority <provider> <account-id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
+
+Codex pool のアカウント別選択順を読み書きします。**値が大きいほど先に使われ**、既定は `0`、範囲は
+`-100` から `100` です。順序を持つのは `openai` の Codex pool だけなので、他のプロバイダーは終了コード
+1 です。`main` は Codex Desktop ログインを指し、他の pool アカウントと同じように並べ替えられます。
+`ocx account priority openai main last` とすれば予備として最後に回せます。
+
+プリセット語は小さな整数の別名です。`first` が `+2`、`earlier` が `+1`、`normal` が `0`、`later` が
+`-1`、`last` が `-2` です。`reset` は既定に戻し、保存されたエントリを削除します。**値を省略すると
+読み取り**になり、現在の順序を書き換えません。
+
+順序が決めるのは「どのアカウントから見るか」であって「どれが使えるか」ではありません。選択は引き続き
+適格なアカウントの中で行われ、まだ quota に余裕がある最上位 tier を取り、その中は
+`accountPoolStrategy` が選びます。一時停止、cooldown、再認証には影響しません。変更は新しいセッションだけでなく **次の未バインドリクエスト** から適用されます。上位の順序に余裕が戻れば
+preemption が未バインドリクエストを直ちに引き上げます。既にアカウントに紐づいた thread は、通常はそのアカウントを
+使い切るまで維持します。ただし再認証エラー、quota cooldown、一時的な失敗の連続はそれより早く紐付けを解除します。受理された書き込みは、どのアカウントの手動の「今すぐこのアカウントを使う」固定も解除します。すでに設定済みの順序を書き込んだ場合も同様で、これは現在選択中のアカウントを保ったまま固定を解除する唯一の方法です（管理 API でアクティブアカウントを解除しても固定は解除されますが、その選択自体も失われます）。プロキシに接続できない場合、
+不明なアカウント id、受け付けない値はいずれも終了コード 1 です。`--json` は次を返します。
+
+```text
+{ ok: true, provider, id, priority: number, preset: string | null }
+```
+
 #### `ocx account remove <provider> <id|main> --yes [--json]`
 
 保護された非対話型削除のため `--yes` が必須です。削除前に id の存在を確認し、不明な id は DELETE を送らずに終了コード 1 を返します。メインの Codex App ログインは削除できないため