@@ -161,6 +161,112 @@ singleton-versus-scope-keyed state, the missing invalidation rule in the absence
161161of an account-side revision, the pin-versus-preference disagreement after a
162162released 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+
164270The generic OAuth kind gets no preference in this layer; that arrives with the
165271kernel 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
183289coordination risk: L3 still owns these files for the dispatch round, so the B
184290phase of this work-phase must not open until that ownership clears. Re-run this
185291table 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