Account Pool: model-family-aware routing and guarded account_uuid rewrite

[SawyerHood]

Standalone follow-up to the Account Pool stack (#3035, #3036, #3042, #3049); based on main.

Human comments

What was wrong

Account Pool selected accounts using only shared 5-hour and 7-day quota observations, even though Anthropic applies separate weekly limits to model families such as Fable. Scoped 7d_<bucket> headers were recorded as opaque diagnostics and never governed selection, the OAuth usage endpoint was not polled, and Claude Code request metadata could retain an account UUID belonging to a different OAuth account after routing. Part of #1552.

What changed

• Replaced opaque bucket exhaustion diagnostics with fixed Fable, Sonnet, Opus, Haiku, and other weekly quota slots carrying utilization, reset, status, observation time, and source.
• Added five-minute idle OAuth usage refreshes, immediate refresh after add or enable, scoped usage-limit parsing, and lazy account UUID backfill through the OAuth profile endpoint. Refresh failures preserve the last known state.
• Parsed the request model once and made eligibility and reset tie-breaking use its governing family bucket. Scoped 429 responses now rotate accounts without globally exhausting the rejected account.
• Stored account UUIDs during Claude Code import and OAuth sign-in, and guarded request rewriting to the selected account for recognized stringified-JSON and user_*_account_<uuid>_session_* metadata forms. Unrecognized, absent, non-JSON, or UUID-less requests remain byte-identical.
• Added dynamic family columns to bb pool account list and updated the CLI skill, plugin guide, and configuration docs.
• Added focused migration, usage parsing/refresh, family routing, scoped-header/429, UUID import/sign-in/backfill/rewrite, passthrough, CLI, and app regression coverage. There is no Plugin SDK or server/host-daemon wire change, so neither protocol version changed.

How you verified

• pnpm exec turbo run typecheck test --filter=bb-plugin-account-pool --continue --force — 6 tasks passed; 4 test files and 35 tests passed. The new routing, scoped-429, refresh, migration, and UUID tests fail against the prior implementation and pass with this change.
• pnpm exec turbo run typecheck test --filter=@bb/templates --continue --force — 7 tasks passed; 7 test files and 43 tests passed.
• pnpm exec turbo run typecheck --filter=@bb/server --continue — 5 tasks passed.
• pnpm --silent bb plugin build plugins/account-pool — server and app bundles built successfully.
• git diff --check origin/main...HEAD — passed after rebasing onto current origin/main.
• Isolated dev-app proof with two OAuth accounts and switchThreshold=0.70: Account A had shared 7d at 43% but Fable at 80%; Account B had Fable at 7%. A real claude-fable-5-1 turn completed through Account B, then a real claude-sonnet-5 turn completed through Account A, proving family-only exhaustion does not disable the account globally. A redacted shape probe on a further real turn found metadata.user_id present without a recognized account UUID component, so the production path correctly preserved it byte-for-byte. The probe was removed, both imported test accounts were removed from the isolated store, and the dev app was stopped. Evidence is attached to BB-94.

Part of #1552

AGENT GENERATED