docs(devlog): fold two audit rounds into the phase 2 kernel plan

Author: codex

devlog/_plan/260911_account_pool_unification/020_phase2_shared_kernel.md

@@ -22,10 +22,22 @@ are not:
   file in the round with four open PRs, which is also why the wp4b call-site
   wiring could not follow #4277 immediately.
 
-This cycle therefore takes the kernel plus the generic consumer and leaves the
-Codex and Anthropic import swaps to a later layer. That ordering is not a
-concession: a kernel that nothing imports yet is still verifiable through the
-generic kind, and it keeps the contended files out of this PR entirely.
+This cycle takes the kernel, the Anthropic import swap and the generic consumer.
+Only the CODEX import swap is deferred, and it is deferred for free: once
+`pool-rotation.ts` re-exports the kernel, `src/codex/` keeps its existing import
+path and needs no edit at all. So the contended files stay out of this PR without
+the kernel being an orphan.
+
+Two kinds of change are moving here and they carry different risk, which is why
+only one of them is behind the flag:
+
+- **Relocation** is behaviour-preserving. Moving the state and primitives into
+  `pool-kernel.ts` and re-exporting them changes no selection outcome, so it is
+  not flagged. `git` history and a green existing suite are its proof.
+- **Behaviour** is flagged. The generic kind consuming `strategy` and
+  `autoSwitchThreshold`, and the DTO reporting `inert: false`, only happen when
+  `pool.kernel` is on. Flag off restores today's outcomes exactly, because the
+  pre-kernel path is the same code reached through the shim.
 
 Anchors confirmed present on `origin/dev`: `selectPriorityTier` :86,
 `pickRoundRobinAccount` :189, `notePoolRotationSuccess` :213,
@@ -69,29 +81,73 @@ and stamps `inert: true` on the generic DTO (`:40-54`, `:57-67`).
 ## Change surface
 
 NEW `src/oauth/pool-kernel.ts`
-- move `SelectionState`, `pickRoundRobinAccount`, `peekRoundRobinAccount`,
-  `seedPoolRotationAccount`, `notePoolRotationSuccess`, `notePoolRotationFailure`,
-  `selectPriorityTier`, and the strategy/sticky normalizers
+- move the WHOLE private `selectionState` map together with
+  `pickRoundRobinAccount`, `peekRoundRobinAccount`, `seedPoolRotationAccount`,
+  `notePoolRotationSuccess`, `notePoolRotationFailure`, `clearPoolRotationState`,
+  `selectPriorityTier`, the priority parsers, `POOL_KEY_*` and the strategy and
+  sticky normalizers. Moving a function subset while leaving the map behind would
+  split one piece of state across two modules.
+- the move is safe: `pool-rotation.ts` imports only two TYPES,
+  `OcxAccountPoolRotationStrategy` from `../types` and `GenerationContext` from
+  `../lib/state-store-sweeper`. Neither creates a cycle into `src/oauth`.
 - add `genericPoolKey(provider) => \`generic:\${provider}\``
-- lift fill-first to `pickFillFirst(ids, afterId, hasHeadroom)` so both existing
-  copies call one implementation
-- extend the reconcile sweep to `generic:*` keys, which `:270-276` currently skips
+- add a fill-first helper with the signature
+  `pickFillFirst(ids, afterId, hasHeadroom, stableAll)`. The earlier three-argument
+  shape was rejected by the audit: both existing copies walk a STABLE FULL roster
+  and not the eligible subset, so dropping `stableAll` changes the wrap order
+  whenever an ineligible id sits between two eligible ones.
+- extend the reconcile sweep to `generic:*`. `buildGenerationContext` already fills
+  `oauthAccountKeys` from `listLiveOAuthAccountKeys` as `provider\0id` for every
+  live OAuth provider, so the sweep needs no new field and no Codex dependency;
+  today those keys are simply skipped as `valid === null`.
+
+NOT moved, deliberately: the Codex fill-first copy in `src/codex/routing.ts` stays
+where it is. Deleting it is the only thing that would force an edit to a file lane
+L3 owns, and the audit flagged that as a blocker against this unit's own freeze.
+Only `anthropic-routing.ts` and the generic kind switch to the kernel helper, and
+the Anthropic caller keeps its weekly `exhausted5h` pre-filter rather than pushing
+that rule into the shared helper.
 
 MODIFY `src/codex/pool-rotation.ts` — re-export the kernel so existing importers
 and `tests/codex-integration/codex-pool-rotation.test.ts` keep working unchanged.
 
-MODIFY `src/oauth/generic-account-failover.ts` — route selection through the kernel
-by strategy: `quota` keeps `rankAccountsByHeadroom`, `round-robin` calls
-`pickRoundRobinAccount(genericPoolKey(name), ...)`, `fill-first` calls the lifted
-helper; seed on manual selection; note success and failure. Keep the presence
+MODIFY `src/oauth/generic-account-failover.ts` — branch BOTH paths on strategy, not
+just the proactive one. `preferredInitialAccount` currently no-ops when the active
+account is healthy and requires `hasHeadroomEvidence`, and the 429 path always ends
+in `rankAccountsByHeadroom`; leaving either unbranched keeps the strategy inert in
+practice even after the DTO says otherwise. `quota` keeps
+`rankAccountsByHeadroom`, `round-robin` calls
+`pickRoundRobinAccount(genericPoolKey(name), ...)`, and `fill-first` uses the
+kernel helper with `autoSwitchThreshold` as its headroom test. Keep the presence
 quorum, the `EXCLUDED_PROVIDERS` guard and the per-provider `health` cooldown.
 
-MODIFY `src/oauth/pool-settings-capability.ts` — drop `inert: true`, add
-`stickyLimit`. MODIFY `src/types/provider.ts:512-518` comments and
-`oauth-account-routes.ts:395` to accept `stickyLimit`.
-
-MODIFY `src/codex/routing.ts` and `src/oauth/anthropic-routing.ts` — import from
-the kernel instead of holding their own copies.
+MODIFY `src/server/management/oauth-account-routes.ts` — a manual account selection
+must seed the cursor, or the operator's pick immediately loses to sticky
+round-robin. Today that PUT calls only `forgetGenericFailoverRoster`, which clears
+the presence cache and not the rotation state. Add
+`seedPoolRotationAccount(genericPoolKey(provider), accountId)` beside it, mirroring
+what `resetAnthropicRoutingForManualSelection` already does for Anthropic.
+`clearGenericFailoverHealth` is the wrong map and `clearPoolRotationState` wipes
+where seeding is wanted.
+
+MODIFY `src/oauth/pool-settings-capability.ts` — report `inert` from the flag rather
+than as a type literal. While `pool.kernel` is off the generic DTO must keep saying
+`inert: true`, because nothing consumes the strategy yet and the reversibility rule
+below requires the old behaviour to be exactly restorable. The literal becomes a
+computed field and only turns false once the kernel is on.
+
+Known readers of that field, all of which move in the same PR:
+`src/cli/account-extended.ts` (forces generic auto-switch inactive),
+`tests/server/account-pool-management-api.test.ts` and
+`tests/cli/cli-account-pool-verbs.test.ts`. The GUI does not read it.
+Also lift the `stickyLimit` rejection at `oauth-account-routes.ts:395` and update
+`src/types/provider.ts:512-518` comments.
+
+MODIFY `src/oauth/anthropic-routing.ts` — import from the kernel. `src/codex/`
+keeps importing `./pool-rotation`, which is now a re-export, so this layer needs
+no edit inside lane L3's files at all. The audit confirmed the shim is sufficient:
+`routing.ts`, `auth-api.ts`, `account-priority.ts` and
+`state-store-registrations.ts` all keep their existing import path.
 
 ## Reversibility (audit blocker, mandatory)
 
@@ -109,6 +165,13 @@ the kernel instead of holding their own copies.
 
 ## Tests
 
+Audit record: the A-phase reviewer returned PASS-WITH-FINDINGS with two blockers,
+both folded above. The first was that lifting fill-first out of its Codex copy
+would have forced an edit inside lane L3's freeze. The second was that dropping
+`inert: true` unconditionally contradicts this document's own reversibility rule,
+which requires `pool.kernel` to default off and the old behaviour to be exactly
+restorable.
+
 - `tests/codex-integration/codex-pool-rotation.test.ts` — unchanged behaviour
   through the re-export (`pickRoundRobinAccount` `:270`, `selectPriorityTier` `:111`)
 - `tests/oauth/generic-oauth-failover.test.ts` — a configured strategy changes the