Skip to content

Commit f5f474b

Browse files
committed
docs: separate manual-switch timing from selection-order timing
A manual Codex switch and a selection-order write have different timings, and five docs surfaces still described the pre-PR guarantee for the first one. `resetCodexRoutingForManualSelection` calls `clearThreadAccountMap`, so a switch moves running threads on their next request; only requests already in flight keep the account they captured. An order write never touches affinity and applies from the next unbound request. - The `ocx account use` subsection in all five `reference/cli.md` locales still said Codex selections "apply only to new sessions; existing threads keep their account". CodeRabbit flagged ru and zh-cn and asked me to double-check the canonical English; English was wrong too, so all five are corrected against `account.ts:260`, which is the wording the command actually prints. - The blanket line in the `account` help block covered both verbs with the switch's timing. Split into two sentences, one per verb, and the switch half now says running threads move rather than only naming in-flight requests. The five cli.md help blocks mirror the block verbatim, so they carry the same split. - `guides/web-dashboard.md` in all five locales carried the same false bound-thread claim -- the file I missed when correcting seven other surfaces -- and listed only two of the three pin-clearing triggers. Both fixed, plus the order bullet now states the from-next-unbound-request timing. - `structure/05` claimed the priority route is the only operator-facing way to clear a pin without selecting another account. A null-id `PUT /active` clears one too; the priority route is the only one that clears it while leaving the selected account in place. The spark-scope regression test asserted only that shared state was untouched, which would also hold if the request never reached `applyFailureFailover`. It now asserts the routed account first: "a" is selectable again by then, so routing away from it is what proves the guarded branch ran.
1 parent cb70148 commit f5f474b

13 files changed

Lines changed: 71 additions & 50 deletions

File tree

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

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,16 @@ catalog entry.
100100

101101
The **Codex Auth** page manages the native ChatGPT/Codex route:
102102

103-
- Manually choosing an account changes the next new Codex session; an already-bound thread keeps its
104-
current account for that manual switch. A manual choice is also pinned: the card shows a **PINNED**
105-
badge, and a higher selection order cannot preempt that account until it is drained or you select
106-
another one.
103+
- Manually choosing an account applies immediately, to new and already-bound threads alike; only
104+
requests already in flight keep the account they captured. A manual choice is also pinned: the card
105+
shows a **PINNED** badge, and a higher selection order cannot preempt that account until it is
106+
drained, you select another account, or you change any account's selection order.
107107
- Each account card carries a **Selection order** control (First, Earlier, Normal, Later, Last).
108108
Higher order is used first, and the pool drops to a lower order only once every account above it is
109-
drained or unavailable. The Codex Desktop (main) account is ordered like any other, so it can be
110-
set to **Last** and kept as the reserve. An order set from `ocx account priority` outside those five
111-
presets stays visible and selectable on the card.
109+
drained or unavailable. A changed order applies from the next unbound request and never moves a
110+
thread that is already bound. The Codex Desktop (main) account is ordered like any other, so it can
111+
be set to **Last** and kept as the reserve. An order set from `ocx account priority` outside those
112+
five presets stays visible and selectable on the card.
112113
- Thread affinity prevents per-request flapping. With quota auto-switch enabled, a long-running
113114
thread is periodically re-evaluated and may rebind after its relevant usage reaches the threshold
114115
and a strictly lower-usage eligible account exists.

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

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,15 @@ Codex タスクだけに適用され、このオプション自体が委任を
8181

8282
**Codex 認証**ページはネイティブ ChatGPT/Codex ルートを管理します。
8383

84-
- アカウントを直接選ぶと次の新規 Codex セッションから変わります。すでにアカウントが紐付いた thread はこの手動切り替えだけでは
85-
途中で移動しません。手動で選んだアカウントは固定もされます。カードに **固定中** バッジが付き、
86-
そのアカウントが使い切られるか別のアカウントを選ぶまで、より上位の選択順序が割り込むことはありません。
84+
- アカウントを直接選ぶと、新しい thread もすでにアカウントが紐付いた thread も含めてすぐに反映されます。
85+
すでに送信中のリクエストだけは、取得済みのアカウントを使い続けます。手動で選んだアカウントは固定もされます。
86+
カードに **固定中** バッジが付き、そのアカウントが使い切られるか、別のアカウントを選ぶか、いずれかの
87+
アカウントの選択順序を変更するまで、より上位の選択順序が割り込むことはありません。
8788
- 各アカウントカードには **選択順序** のコントロール(最初 / 早め / 標準 / 遅め / 最後)があります。
8889
順序が上のものから使われ、その上にあるアカウントがすべて使い切られるか利用できなくなって初めて
89-
下の順序へ下がります。Codex Desktop(メイン)アカウントも同じように並べ替えられるので、**最後**
90-
にして予備に回せます。`ocx account priority` でプリセット以外の値を設定した場合も、カード上に
90+
下の順序へ下がります。順序を変更すると **次の未バインドリクエスト** から適用され、すでにアカウントに
91+
紐づいた thread を移動させることはありません。Codex Desktop(メイン)アカウントも同じように
92+
並べ替えられるので、**最後** にして予備に回せます。`ocx account priority` でプリセット以外の値を設定した場合も、カード上に
9193
選択肢として残ります。
9294
- Thread affinity がリクエストごとにアカウントが揺れるのを防ぎます。クォータ自動切り替えがオンなら長く
9395
実行される thread も定期的に再評価します。関連使用量がしきい値以上で、使用量が確実により低い

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,8 @@ remove <provider> <id> --yes Remove a stored account or key after an existence
216216
add-key <provider> [--label <label>] Add a key read only from piped stdin.
217217
login/reauth/code/cancel Run browser or manual-code auth from a headless shell.
218218
reset-credits <id|main> [--consume --yes] Inspect or consume Codex reset credits.
219-
Codex pool switches take effect immediately; in-flight requests keep their captured account.
219+
Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
220+
A selection-order change applies from the next unbound request and never moves a bound thread.
220221
```
221222

222223
すべてのサブコマンドはプロキシが実行中である必要があり、CLI が記録されたランタイムポートを自動的に探します。成功は
@@ -262,9 +263,9 @@ API エラーは終了コード 1 です。認証情報フィールドは manage
262263
#### `ocx account use <provider> <account-or-key-id|main> [--json]`
263264

264265
既存の Codex アカウント、OAuth アカウント、または API key を選びます。`openai``main` は Codex App ログインを
265-
選択します。Codex の選択は **新しいセッション** から適用され、既存の thread は現在のアカウントを維持します。auto-switch
266-
threshold がオンなら後で手動 pin を上書きできます。不明なプロバイダーや id は終了
267-
コード 1 です。`--json` は次を返します。
266+
選択します。Codex の選択は **すぐに反映** されます。実行中の thread は次のリクエストで移動し、すでに送信中の
267+
リクエストだけが取得済みのアカウントを使い続けます。auto-switch threshold がオンなら後で手動 pin
268+
上書きできます。不明なプロバイダーや id は終了コード 1 です。`--json` は次を返します。
268269

269270
```text
270271
{ ok: true, provider, type, activeId }

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,12 +81,14 @@ Dashboard의 **Sub-agent delegation** 선택기는 `injectionModel`과 선택적
8181

8282
**Codex Auth** 페이지는 네이티브 ChatGPT/Codex 라우트를 관리합니다.
8383

84-
- 계정을 직접 고르면 다음 새 Codex 세션부터 바뀝니다. 이미 계정이 묶인 thread는 이 수동 전환만으로
85-
중간에 이동하지 않습니다. 직접 고른 계정은 고정되기도 합니다. 카드에 **고정됨** 배지가 붙고, 그
86-
계정이 소진되거나 다른 계정을 고를 때까지 더 높은 선택 순서가 끼어들지 못합니다.
84+
- 계정을 직접 고르면 새 thread와 이미 계정이 묶인 thread 모두에 곧바로 적용됩니다. 이미 전송 중인
85+
요청만 가져간 계정을 그대로 씁니다. 직접 고른 계정은 고정되기도 합니다. 카드에 **고정됨** 배지가
86+
붙고, 그 계정이 소진되거나, 다른 계정을 고르거나, 어느 계정의 선택 순서를 바꿀 때까지 더 높은 선택
87+
순서가 끼어들지 못합니다.
8788
- 각 계정 카드에는 **선택 순서** 컨트롤(가장 먼저 / 먼저 / 기본 / 나중에 / 가장 마지막)이 있습니다.
8889
순서가 높은 계정부터 쓰이며, 그 위의 계정이 모두 소진되거나 사용할 수 없게 된 뒤에야 낮은 순서로
89-
내려갑니다. Codex Desktop(메인) 계정도 똑같이 정렬되므로 **가장 마지막**으로 두어 예비로 남길 수
90+
내려갑니다. 순서를 바꾸면 **다음 미바인딩 요청** 부터 적용되며, 이미 계정에 바인딩된 thread를 옮기지
91+
않습니다. Codex Desktop(메인) 계정도 똑같이 정렬되므로 **가장 마지막**으로 두어 예비로 남길 수
9092
있습니다. `ocx account priority`로 프리셋 밖의 값을 지정해도 카드에서 그대로 보이고 선택할 수
9193
있습니다.
9294
- Thread affinity가 요청마다 계정이 흔들리는 일을 막습니다. 할당량 자동 전환이 켜져 있으면 오래

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,8 @@ remove <provider> <id> --yes Remove a stored account or key after an existence
220220
add-key <provider> [--label <label>] Add a key read only from piped stdin.
221221
login/reauth/code/cancel Run browser or manual-code auth from a headless shell.
222222
reset-credits <id|main> [--consume --yes] Inspect or consume Codex reset credits.
223-
Codex pool switches take effect immediately; in-flight requests keep their captured account.
223+
Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
224+
A selection-order change applies from the next unbound request and never moves a bound thread.
224225
```
225226

226227
모든 하위 명령은 프록시가 실행 중이어야 하며 CLI가 기록된 런타임 포트를 자동으로 찾습니다. 성공은
@@ -275,9 +276,9 @@ API 오류는 종료 코드 1입니다. 자격 증명 필드는 management API
275276
#### `ocx account use <provider> <account-or-key-id|main> [--json]`
276277

277278
기존 Codex 계정, OAuth 계정 또는 API key를 선택합니다. `openai`에서 `main`은 Codex App 로그인을
278-
선택합니다. Codex 선택은 **새 세션**부터 적용되며 기존 thread는 현재 계정을 유지합니다. auto-switch
279-
threshold가 켜져 있으면 나중에 수동 pin을 덮어쓸 수 있습니다. 알 수 없는 프로바이더나 id는 종료
280-
코드 1입니다. `--json`은 다음을 반환합니다.
279+
선택합니다. Codex 선택은 **곧바로 적용**됩니다. 실행 중인 thread는 다음 요청에서 옮겨가고, 이미 전송
280+
중인 요청만 가져간 계정을 그대로 씁니다. auto-switch threshold가 켜져 있으면 나중에 수동 pin을
281+
덮어쓸 수 있습니다. 알 수 없는 프로바이더나 id는 종료 코드 1입니다. `--json`은 다음을 반환합니다.
281282

282283
```text
283284
{ ok: true, provider, type, activeId }

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -276,7 +276,8 @@ remove <provider> <id> --yes Remove a stored account or key after an existence
276276
add-key <provider> [--label <label>] Add a key read only from piped stdin.
277277
login/reauth/code/cancel Run browser or manual-code auth from a headless shell.
278278
reset-credits <id|main> [--consume --yes] Inspect or consume Codex reset credits.
279-
Codex pool switches take effect immediately; in-flight requests keep their captured account.
279+
Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
280+
A selection-order change applies from the next unbound request and never moves a bound thread.
280281
```
281282

282283
All subcommands require the proxy to be running; the CLI auto-resolves its recorded runtime port.
@@ -332,8 +333,9 @@ returns:
332333
#### `ocx account use <provider> <account-or-key-id|main> [--json]`
333334

334335
Selects an existing Codex account, OAuth account, or API key. For `openai`, `main` selects the Codex
335-
App login. Codex selections apply only to **new sessions**; existing threads keep their account, and
336-
an enabled auto-switch threshold may later override the manual pin. Unknown providers or ids exit 1.
336+
App login. A Codex selection **takes effect immediately**: running threads move on their next request,
337+
and only requests already in flight keep the account they captured. An enabled auto-switch threshold
338+
may later override the manual pin. Unknown providers or ids exit 1.
337339
`--json` returns:
338340

339341
```text

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

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -84,16 +84,18 @@ bun run dev:gui
8484

8585
Страница **Codex Auth** управляет нативным маршрутом ChatGPT/Codex:
8686

87-
- Ручной выбор аккаунта меняет следующую новую сессию Codex; уже привязанный поток при таком ручном
88-
переключении сохраняет текущий аккаунт. Выбранный вручную аккаунт также закрепляется: на карточке
89-
появляется бейдж **ЗАКРЕПЛЁН**, и более высокий порядок выбора не может вытеснить этот аккаунт,
90-
пока он не исчерпан или пока вы не выберете другой.
87+
- Ручной выбор аккаунта применяется сразу — и к новым потокам, и к уже привязанным; захваченный
88+
аккаунт сохраняют только уже выполняющиеся запросы. Выбранный вручную аккаунт также закрепляется:
89+
на карточке появляется бейдж **ЗАКРЕПЛЁН**, и более высокий порядок выбора не может вытеснить этот
90+
аккаунт, пока он не исчерпан, пока вы не выберете другой аккаунт или пока не измените порядок
91+
выбора любого аккаунта.
9192
- На карточке каждого аккаунта есть элемент управления **Порядок выбора** (Первым, Раньше,
9293
По умолчанию, Позже, Последним). Аккаунты с более высоким порядком используются раньше, а на более
93-
низкий порядок пул опускается лишь тогда, когда все аккаунты выше исчерпаны или недоступны. Аккаунт
94-
Codex Desktop (основной) упорядочивается наравне с остальными, поэтому его можно поставить
95-
**Последним** и держать в резерве. Порядок, заданный через `ocx account priority` вне этих пяти
96-
пресетов, остаётся видимым и выбираемым на карточке.
94+
низкий порядок пул опускается лишь тогда, когда все аккаунты выше исчерпаны или недоступны.
95+
Изменённый порядок действует начиная со **следующего непривязанного запроса** и никогда не
96+
перемещает уже привязанный поток. Аккаунт Codex Desktop (основной) упорядочивается наравне с
97+
остальными, поэтому его можно поставить **Последним** и держать в резерве. Порядок, заданный через
98+
`ocx account priority` вне этих пяти пресетов, остаётся видимым и выбираемым на карточке.
9799
- Привязка потока предотвращает метание между аккаунтами на каждом запросе. При включённом
98100
автопереключении по квоте долгоживущий поток периодически переоценивается и может
99101
перепривязаться, когда его релевантное использование достигает порога и существует подходящий

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,8 @@ remove <provider> <id> --yes Remove a stored account or key after an existence
232232
add-key <provider> [--label <label>] Add a key read only from piped stdin.
233233
login/reauth/code/cancel Run browser or manual-code auth from a headless shell.
234234
reset-credits <id|main> [--consume --yes] Inspect or consume Codex reset credits.
235-
Codex pool switches take effect immediately; in-flight requests keep their captured account.
235+
Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.
236+
A selection-order change applies from the next unbound request and never moves a bound thread.
236237
```
237238

238239
Все подкоманды требуют работающего прокси; CLI автоматически определяет записанный runtime-порт.
@@ -293,9 +294,10 @@ plan/label по цепочке фолбэков использует план,
293294
#### `ocx account use <provider> <account-or-key-id|main> [--json]`
294295

295296
Выбирает существующий аккаунт Codex, OAuth-аккаунт или API-ключ. Для `openai` значение `main`
296-
выбирает вход Codex App. Выбор для Codex применяется только к **новым сессиям**; существующие
297-
потоки сохраняют свой аккаунт, а включённый порог автопереключения может позже переопределить
298-
ручное закрепление. Неизвестные провайдеры или id завершаются с кодом 1. `--json` возвращает:
297+
выбирает вход Codex App. Выбор для Codex **применяется сразу**: работающие потоки переходят на новый
298+
аккаунт со следующего запроса, и только уже отправленные запросы сохраняют захваченный аккаунт.
299+
Включённый порог автопереключения может позже переопределить ручное закрепление. Неизвестные
300+
провайдеры или id завершаются с кодом 1. `--json` возвращает:
299301

300302
```text
301303
{ ok: true, provider, type, activeId }

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,12 +75,13 @@ Dashboard 的 **Sub-agent delegation** 选择器会保存 `injectionModel`,以
7575

7676
**Codex Auth** 页面用于管理原生 ChatGPT/Codex 路由:
7777

78-
- 手动选择账号会影响下一次新建的 Codex session;已经绑定账号的 thread 不会因为这次手动切换而
79-
在中途转移。手动选择的账号还会被固定:卡片上会出现 **已固定** 徽章,在该账号被耗尽或你改选其他
80-
账号之前,更高的选择顺序都无法抢占它。
78+
- 手动选择账号会立即生效,新 thread 和已经绑定账号的 thread 都会切换;只有已经在传输中的请求会继续
79+
使用它们捕获的账号。手动选择的账号还会被固定:卡片上会出现 **已固定** 徽章,在该账号被耗尽、你改选
80+
其他账号,或你改动任意账号的选择顺序之前,更高的选择顺序都无法抢占它。
8181
- 每张账号卡片都带有 **选择顺序** 控件(最先 / 较先 / 默认 / 较后 / 最后)。顺序靠前的账号先被使用,
82-
只有当它上面的账号全部耗尽或不可用时才会降到更靠后的顺序。Codex Desktop(主)账号同样参与排序,
83-
可以设为 **最后** 留作备用。用 `ocx account priority` 设置的非预设值也会保留在卡片上,仍可选择。
82+
只有当它上面的账号全部耗尽或不可用时才会降到更靠后的顺序。改动顺序会从**下一个未绑定请求**起生效,
83+
且不会移动已经绑定的 thread。Codex Desktop(主)账号同样参与排序,可以设为 **最后** 留作备用。
84+
`ocx account priority` 设置的非预设值也会保留在卡片上,仍可选择。
8485
- Thread affinity 可避免每个请求都来回切换账号。启用配额自动切换后,长时间运行的 thread 会被
8586
定期重新评估;当相关 usage 达到阈值,并且存在使用率确实更低的可用账号时,该 thread 可能会
8687
重新绑定。

0 commit comments

Comments
 (0)