Skip to content

Commit 29d632f

Browse files
authored
Merge pull request #4284 from lidge-jun/codex/manual-selection-wins
fix(codex): let an operator account selection outrank the pool cursor
2 parents e02578e + eec1f9b commit 29d632f

3 files changed

Lines changed: 461 additions & 3 deletions

File tree

‎devlog/_plan/260911_account_pool_unification/010_phase1_manual_selection.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,112 @@ singleton-versus-scope-keyed state, the missing invalidation rule in the absence
161161
of an account-side revision, the pin-versus-preference disagreement after a
162162
released pin, and the test gap against criterion c-2.
163163

164+
## Implementation-entry audit, after the lane freeze lifted
165+
166+
Lane L3 PR #4230 and lane L1 PR #4226 merged, so this work became writable. A
167+
fresh audit against the post-merge file returned FAIL with three more blockers.
168+
All anchors survived the merge (`codexPoolKeyForScope` 225,
169+
`resetCodexRoutingForManualSelection` 870, `pickUnboundStrategyAccount` 1446,
170+
`getEffectiveActiveCodexAccountId` 1625, `rememberActiveCodexAccount` 1644,
171+
`setActiveCodexAccount` 1660, `promoteActiveCodexAccount` 1669), but L3 added
172+
independent-scope cursor isolation and runtime-only preemption, which changes what
173+
the design may assume.
174+
175+
1. **BLOCKER. The preference is scope-keyed but `getEffectiveActiveCodexAccountId`
176+
is not.** It takes only a config and has no `quotaScope`, so it can read the
177+
shared `POOL_KEY_CODEX` entry and nothing else. `resolveCodexAccountForThreadDetailed`
178+
and `previewCodexAccountForRequest` look up `codexPoolKeyForScope(quotaScope)`
179+
themselves. A scope with no entry means NO preference; it must never fall back to
180+
the shared key, or an independent scope would consume a one-shot it was not given.
181+
2. **BLOCKER. Consuming inside `setActiveCodexAccount` is wrong.** That function is
182+
also the persist path for pool-driven moves: quota auto-switch (1807), affinity
183+
re-evaluation (2166), unbound persist (2231 and 2252) and the quota promote
184+
(1671) all call it. Consuming there would let the pool spend the operator's
185+
one-shot. Consume only on the path where the preference was actually honoured
186+
and the dispatch succeeded, plus on an operator reset.
187+
3. **BLOCKER. An unconditional honour traps a cooled account.** With
188+
`rememberActiveCodexAccount` a no-op, a 429 or failover on the preferred account
189+
(2527, 2576, 1878) could not move `getEffectiveActiveCodexAccountId` away from
190+
it. Honour the preference only while that account is selectable and not cooling;
191+
otherwise treat it as absent for this dispatch without spending it.
192+
4. **The preview path must mirror resolve.** The check belongs immediately before
193+
BOTH `pickUnboundStrategyAccount` calls, at 2020 and 2193, after affinity and
194+
model-detour handling, not at function entry.
195+
5. **Pause and exclusion never route through the reset.** `reconcileCodexActiveAfterExclusion`
196+
(1692) and the health-clear path (317-320) bypass it, so a preference would
197+
outlive an excluded or paused account. Drop the key when the preferred account is
198+
excluded or paused.
199+
6. **Minor, but decide it deliberately.** `isEffectiveCodexAccountPinned` (1637)
200+
would read true while the preference equals the pin, and L3 now documents that
201+
`getEffectiveActiveCodexAccountId` is what surfaces automatic picks to the API
202+
and dashboard. Either keep the pin check reading persisted and runtime only, or
203+
accept and document that `GET /api/codex-auth/active` is manual-sticky until the
204+
preference is consumed.
205+
206+
## Measured: the consume call site is the whole design, not a detail
207+
208+
A first implementation pass built the preference map, the seeding inside
209+
`resetCodexRoutingForManualSelection`, the `rememberActiveCodexAccount` guard, the
210+
`getEffectiveActiveCodexAccountId` overlay and the exclusion revoke, and left the
211+
consume call site unwired. It typechecked, and then
212+
`tests/codex-integration/codex-pool-rotation.test.ts` went from green to **15 failures
213+
out of 69**, including "fill-first picks the same sequence with no stored order as
214+
before the feature".
215+
216+
That is the correct result, and it is worth recording rather than repeating. Without a
217+
consume site the one-shot is permanent: the first operator selection freezes the
218+
automatic cursor forever, because `rememberActiveCodexAccount` stays a no-op and no
219+
code path ever clears the entry. Every rotation-strategy test that expects the pool to
220+
keep moving after a manual selection fails, and they are right to.
221+
222+
So the implementation order matters. Build the consume path FIRST, not last:
223+
224+
1. Find the point that already records a successful upstream outcome for the resolved
225+
account and call `consumeCodexManualPreference(poolKey)` there, for a non-quota
226+
success only. This is the Codex analogue of `commitAnthropicSelectionRouting`
227+
(`anthropic-routing.ts` :799-800), which Codex has no direct equivalent of.
228+
2. Only then add the `rememberActiveCodexAccount` guard, so the suite never passes
229+
through a state where the cursor can freeze.
230+
3. Gate honouring on the account being selectable, per blocker 3 above, so a cooled
231+
preferred account is skipped for that dispatch without being spent.
232+
233+
The pass was reverted rather than pushed. The branch `codex/manual-selection-wins`
234+
carries this document and no source change.
235+
236+
## Measured again: guarding the writer is right, but the 429 path needs an exemption
237+
238+
A second pass followed the order above. The consume site went in first, at the
239+
`outcomeClass === "success"` branch of `recordCodexUpstreamOutcome` (:2356), keyed by
240+
`codexPoolKeyForScope(quotaScope)` which that function already computes. Seeding and the
241+
exclusion revoke followed. At each of those two steps
242+
`tests/codex-integration/codex-pool-rotation.test.ts` stayed **69 pass, 0 fail**, which
243+
confirms the ordering advice above is correct.
244+
245+
Adding the `rememberActiveCodexAccount` guard then produced **6 failures out of 69**, down
246+
from 15, and every single one is a 429 promotion case:
247+
248+
- fill-first 429 advances to next stable account, not lowest usage
249+
- RR 429 promotes via ring, not lowest usage
250+
- 429 retry reuse promoteAccountId avoids a second RR ring advance
251+
- fill-first transient failover advances stable order, not lowest usage
252+
- scoped reset 429s retain strategy while excluding only the affected native quota
253+
- fill-first preserves its pre-feature fallback when every ordered tier is drained
254+
255+
That is exactly the hazard blocker 3 named, and it is sharper than the blocker stated it.
256+
Gating the guard on `isCodexAccountSelectable(preferred)` is NOT sufficient: at the moment
257+
`promoteActiveCodexAccount` runs, the preferred account can still read as selectable
258+
because the 429 cooldown is recorded on a different path, so the guard holds and the
259+
promotion cannot land.
260+
261+
The conclusion for the next pass: guarding the writer closes all four call sites at once,
262+
which is still the right shape, but the failover promote needs an explicit exemption. It
263+
only ever runs because the account in use just failed, so it is never an automatic pick
264+
competing with the operator. Either pass an explicit "this is a failover promote" flag
265+
through `rememberActiveCodexAccount`, or leave the writer unguarded and guard the two
266+
strategy commit sites plus preemption instead, accepting three guards rather than one.
267+
268+
Reverted again rather than pushed. The measurement is the deliverable.
269+
164270
The generic OAuth kind gets no preference in this layer; that arrives with the
165271
kernel in phase 2. No management or GUI change.
166272

@@ -183,3 +289,65 @@ The design therefore survives the lane's landings. What does not change is the
183289
coordination risk: L3 still owns these files for the dispatch round, so the B
184290
phase of this work-phase must not open until that ownership clears. Re-run this
185291
table at that point, because the guarantee above is a snapshot of `16f18d654`.
292+
293+
## Audit round 4 — the shipped tests proved nothing
294+
295+
The first implementation landed as PR #4284 with three new cases under
296+
`an operator selection outranks the pool cursor`, and a reviewer was asked one
297+
question the earlier rounds never asked: does each test fail without the production
298+
change? It does not. Measured by reverting only `src/codex/routing.ts` to the parent
299+
branch and keeping the new tests:
300+
301+
```
302+
bun test tests/codex-integration/codex-pool-rotation.test.ts \
303+
-t "an operator selection outranks the pool cursor"
304+
3 pass, 0 fail # production change reverted
305+
```
306+
307+
All three passed against a tree with no guard, no preference map and no consume site.
308+
They were re-assertions of things that already held: case 1 of
309+
`resetCodexRoutingForManualSelection` clearing the runtime cursor and seeding the ring,
310+
cases 2 and 3 of the failover promote, which this design deliberately leaves exempt. A
311+
test that cannot fail is not weak coverage, it is an empty claim, and criteria c-1 and
312+
c-2 had been recorded `met` against it.
313+
314+
Three real defects were behind that blind spot.
315+
316+
**Deletion never revoked the preference.** Pause and exclusion both route through
317+
`reconcileCodexActiveAfterExclusion`, which forgets it. Delete does not: the
318+
account-lifecycle path reaches routing through `clearCodexUpstreamHealthForAccount`
319+
(`routing.ts:327`, called from `account-lifecycle.ts:43`), which cleared two health maps
320+
and left the preference behind. Once the named account is gone nothing can ever succeed
321+
on it, so the one-shot can never be spent, and every later automatic write is suppressed
322+
until the process restarts. The generation sweep in `reconcileCodexRoutingHealth` had the
323+
same hole for an account removed by an edit the runtime never observed.
324+
325+
**The model-detour promote was reported as unguarded — REBUTTED.** `promoteActiveCodexAccount`
326+
at the model-detour site sits twelve lines above the preemption site this design guards, so
327+
the symmetry argument is tempting. It is wrong, and the measurement says so: guarding it
328+
fails 8 cases in `tests/codex-integration/codex-routing.test.ts`, the
329+
`cannot re-pick a quota-drained shared account that remains model-eligible` family and its
330+
siblings. Those encode an older contract. A model detour is not the pool exercising
331+
discretion — it runs because the operator's account cannot serve the requested model at
332+
all — and under a rotating strategy that promote moves only the process-local cursor to
333+
whoever is actually serving, then releases the pin. `config.activeCodexAccountId`, the
334+
operator's persisted selection and the thing this preference exists to protect, is
335+
untouched either way. The guard was written, measured red, and reverted with the reason
336+
recorded at the call site.
337+
338+
**The independent-scope entries were dead state.** Every write site the guard protects is
339+
already skipped for independent scopes, so those keys were seeded and consumed but never
340+
read. Removed: state nothing reads is what the next reader mistakes for a rule.
341+
342+
The replacement cases are each red against the variant that removes the piece they cover:
343+
344+
| Case | Red against |
345+
|---|---|
346+
| an over-threshold operator account is served around, not replaced | parent branch: reads `b`, expected `a` |
347+
| deleting the preferred account releases the hold | pre-fix head `63217d161`: reads `undefined`, expected `b` |
348+
| a successful dispatch spends the one-shot so the pool may move again | guard without consume: 15 of 69 rotation tests fail |
349+
350+
The over-threshold case is also the one that states the user-facing rule plainly. An
351+
account past its switch threshold is temporarily spent, not wrong: the pool serves the
352+
request from elsewhere, and the operator's selection stays pointed where the operator put
353+
it, so the window rolling over returns routing to it without a second manual pick.

0 commit comments

Comments
 (0)