claude-multiacc 2.0.5 → 2.0.7

package/bin/claude-accounts

@@ -1273,6 +1273,7 @@ cmd_limits() {
 import hashlib, json, os, sys, time, urllib.request
 sys.path = [sys.argv[6]] + [p for p in sys.path if p not in ('', '.')]
 import keychain  # noqa: E402  (macOS Keychain-held logins; a no-op elsewhere)
+from audit import creds_doc_state  # noqa: E402  (one rule for "can this credential work")
 
 root, threshold, quiet, url, force = sys.argv[1], int(sys.argv[2]), sys.argv[3] == '1', sys.argv[4], sys.argv[5] == '1'
 now = time.time()
@@ -1655,6 +1656,18 @@ for acct in manifest.get('accounts', []):
     locked = store == 'locked'
     if locked:
         store = None
+    # "This account has an OAuth login that could still work." A Keychain-held one
+    # only the Mac's own launchd probe can open counts: it is unusable HERE, not
+    # broken. A provably DEAD grant (no refresh token, or a refresh token that has
+    # itself expired) does not count — for that account the setup token really is
+    # the only bearer left, and it must still get its one try.
+    oauth_alive = locked
+    if store is not None:
+        try:
+            oauth_alive = creds_doc_state(store.read(), now)[0] == 'ok'
+        except Exception:
+            oauth_alive = True   # unreadable is not proof of death: do not spend the token
+    has_oauth = oauth_alive
     if store is not None:
         try:
             c = store.read().get('claudeAiOauth', {})
@@ -1672,7 +1685,19 @@ for acct in manifest.get('accounts', []):
             tok = None
         if tok:
             bearer, source = tok, 'oauth'
-    if not bearer and os.path.isfile(tpath):
+    # A setup token is a LAST RESORT and only for an account that has no OAuth
+    # credential at all. Where one exists but could not be used this pass — its
+    # access token expired moments ago (refresh_oauth waits REFRESH_MIN_EXPIRED to
+    # prove no live session owns it), a refresh backoff, or a Keychain this session
+    # cannot open — spending the token is guaranteed to earn a 403 it can never not
+    # earn, and that 403 used to park the whole ACCOUNT for six hours. Telemetry then
+    # froze for an account whose OAuth would have worked on the very next pass, and
+    # the shim ranked the pool on hour-old readings. Waiting for the next pass costs
+    # minutes; the token costs six hours and answers nothing.
+    if not bearer and has_oauth:
+        say(f'{aid}: oauth credential not usable this pass; NOT spending the setup '
+            f'token on a usage endpoint that always refuses it — retrying next pass')
+    elif not bearer and os.path.isfile(tpath):
         # Once this endpoint has refused THIS token file for lacking a scope, asking
         # again is guaranteed to fail and only spends the account's hourly budget —
         # which is how a permanent authorization problem disguised itself as a rate
@@ -1717,6 +1742,14 @@ for acct in manifest.get('accounts', []):
         except Exception:
             pass
 
+        def save_prev():
+            """Persist the account's telemetry state as-is (no backoff, no invented
+            freshness) — used when what failed says nothing about the ACCOUNT."""
+            tmp = lpath + '.tmp'
+            with open(tmp, 'w') as f:
+                json.dump(prev, f, indent=1)
+            os.replace(tmp, lpath)
+
         def park(wait, note):
             """Record a failed fetch WITHOUT inventing freshness: fetched_at is left
             exactly as it was, so a parked account still reads as stale everywhere."""
@@ -1724,10 +1757,7 @@ for acct in manifest.get('accounts', []):
             prev['backoff'] = wait
             prev['last_error'] = note
             prev['last_error_at'] = int(now)
-            tmp = lpath + '.tmp'
-            with open(tmp, 'w') as f:
-                json.dump(prev, f, indent=1)
-            os.replace(tmp, lpath)
+            save_prev()
 
         if e.code == 429:
             # Respect Retry-After; otherwise exponential backoff capped at 30 min.
@@ -1765,8 +1795,16 @@ for acct in manifest.get('accounts', []):
                 tdigest = token_digest(tpath)
                 if tdigest:
                     prev['token_scope_denied'] = tdigest
-            park(wait, f'HTTP {e.code} (source={source})'
-                       + (' — permanent, server said do not retry' if denied else ''))
+            if scope_denied and source == 'token':
+                # A refusal of the TOKEN is a fact about that credential, not about
+                # the account: parking the account here also blocked the OAuth path,
+                # so an account that merely missed one refresh went dark for six
+                # hours. The digest above already stops this token being spent again;
+                # leave the account free to try its OAuth login next pass.
+                save_prev()
+            else:
+                park(wait, f'HTTP {e.code} (source={source})'
+                           + (' — permanent, server said do not retry' if denied else ''))
             if scope_denied and source == 'token':
                 # The exact shape of this outage: a setup token is minted WITHOUT the
                 # user:profile scope the usage endpoint requires, so an account whose
@@ -1775,7 +1813,8 @@ for acct in manifest.get('accounts', []):
                 say(f'{aid}: usage endpoint refuses the setup token (HTTP {e.code} — a '
                     f'setup token has no user:profile scope). Telemetry is DEAD for this '
                     f'account until it has an OAuth login here: claude-accounts login {aid}. '
-                    f'Backing off {wait}s.')
+                    f'This token will not be offered again; the ACCOUNT is not parked, so '
+                    f'an OAuth login works the moment it lands.')
             elif denied:
                 say(f'{aid}: usage fetch refused for good (HTTP {e.code}, source={source}); '
                     f'backing off {wait}s — re-login needed: claude-accounts login {aid}')

package/lib/selector_policy.py

@@ -6,6 +6,7 @@ from datetime import datetime
 from decimal import Decimal, localcontext
 
 from selector_primitives import (
+    DEFAULT_HEADROOM_BAND,
     SCHEMA,
     SELECTOR_VERSION,
     canonical_sha256,
@@ -125,6 +126,47 @@ def _winner_key(row: dict) -> tuple:
         row["engine"], row["account_id"], row["runner_id"], row["runner_generation"])
 
 
+def _band_floor(rows: list[dict], band: Decimal) -> Decimal | None:
+    """The lowest headroom still counted as "as good as the best" this round.
+
+    Ranking strictly by headroom hands every task to whichever account is on top,
+    which is precisely how one account's limit gets burned to zero while three
+    others idle: the runner-up only ever wins after the leader has been spent
+    below it. Accounts within ``band`` points of the leader are treated as equally
+    good, and the tie-break below spreads work across them.
+    """
+    known = [Decimal(row["effective_headroom"]) for row in rows
+             if row["quota_known"] and row["effective_headroom"] is not None]
+    return max(known) - band if known else None
+
+
+def _spread(reservation_key: str, row: dict) -> str:
+    """A stable pseudo-random ordinal for this row IN THIS REQUEST.
+
+    Real randomness cannot live here — the response carries a reproducible
+    digest of its own inputs, and two runs of the same request must agree. A
+    digest over (reservation key, identity) gives every task its own order over
+    the band while staying a pure function of the request, so a burst of
+    parallel launches spreads instead of stacking on one account.
+    """
+    return canonical_sha256({"reservation_key": reservation_key,
+                             "identity": list(_row_identity(row))})
+
+
+def _band_key(reservation_key: str):
+    """Order INSIDE the band: least-recently-used first, then the spread digest.
+
+    Headroom deliberately does not appear — inside the band it is what we are
+    choosing to ignore. LRU is what makes this rotate rather than merely jitter:
+    with three banded accounts, three sequential tasks touch all three.
+    """
+    def key(row: dict) -> tuple:
+        return (row["last_selected_at"] is not None, row["last_selected_at"] or "",
+                _spread(reservation_key, row),
+                row["engine"], row["account_id"], row["runner_id"], row["runner_generation"])
+    return key
+
+
 def _snapshot_key(row: dict) -> tuple:
     if row["identity_valid"]:
         return 0, row["runner_id"], row["runner_generation"], row["engine"], row["account_id"]
@@ -154,7 +196,17 @@ def select(request: object) -> dict:
     eligible = [row for row in rows if row["eligible"]]
     if not eligible:
         return _error("no_candidate", {"eligible_count": 0})
-    winner = min(eligible, key=_winner_key)
+    band, band_text = decimal_value(request.get("headroom_band", DEFAULT_HEADROOM_BAND))
+    floor = _band_floor(eligible, band) if band is not None else None
+    if floor is None:
+        # No usable quota anywhere: nothing to band, so keep the plain ordering
+        # (which already ranks unknown-quota rows last and rotates on ties).
+        banded = eligible
+        winner = min(banded, key=_winner_key)
+    else:
+        banded = [row for row in eligible if row["quota_known"]
+                  and Decimal(row["effective_headroom"]) >= floor]
+        winner = min(banded, key=_band_key(request["reservation_key"]))
     rows.sort(key=_snapshot_key)
     snapshot = canonical_sha256(rows)
     chosen = dict(zip(("runner_id", "runner_generation", "engine", "account_id"), _row_identity(winner)))
@@ -162,6 +214,8 @@ def select(request: object) -> dict:
         "schema": SCHEMA, "selector_version": SELECTOR_VERSION,
         "database_now": canonical_now, "policy": request["policy"],
         "required_engine": request.get("required_engine"), "reservation_key": request["reservation_key"],
+        # The band changes which account wins, so it belongs in the proof.
+        "headroom_band": band_text,
         "candidate_snapshot_digest": snapshot, "selected_identity": chosen}
     score_fields = ("quota_known", "weekly_pct", "session_pct", "weekly_remaining",
                     "session_remaining", "effective_headroom", "last_selected_at")
@@ -169,6 +223,11 @@ def select(request: object) -> dict:
                 "score_basis": {name: winner[name] for name in score_fields},
                 "eligible_count": len(eligible),
                 "eligible_alternative_count": alternatives,
+                # Observability: which accounts were considered interchangeable,
+                # so "why did it not pick the emptiest one" has an answer.
+                "headroom_band": band_text,
+                "band_floor": format(floor, "f") if floor is not None else None,
+                "band_count": len(banded),
                 "candidate_snapshot_digest": snapshot,
                 "selection_digest": canonical_sha256(digest_input)}
     if request["policy"] == "reviewer" and not alternatives and _row_identity(winner) == producer:

package/lib/selector_primitives.py

@@ -11,6 +11,13 @@ from datetime import datetime, timezone
 from decimal import Decimal, InvalidOperation
 
 SCHEMA = "claude-multiacc/pool-selection.v2"
+# NOT bumped for the headroom band. This string is a BUILD FENCE, not a changelog:
+# a queued task records the version that reserved its account, and the claim function
+# (agent-sdk 0005_delivery_claim_functions.sql) only lets a runner advertising the same
+# string claim it — while the runner's value is a hardcoded constant shipped in its
+# bundle. With Macs routinely several builds behind, bumping this stops every lagging
+# Mac from claiming any new work until it updates. The band is additive and optional:
+# the request shape, the response shape and every consumer are unchanged.
 SELECTOR_VERSION = "2.0.1"
 TIME_RE = re.compile(
     r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9]"
@@ -25,6 +32,10 @@ CANDIDATE_KEYS = IDENTITY_KEYS | {
 REQUEST_KEYS = {
     "schema", "database_now", "policy", "required_engine", "producer_identity",
     "excluded_identities", "candidates", "reservation_key"}
+# Optional because a caller pinned to an older panel build still sends exactly
+# REQUEST_KEYS; absent, the policy applies its own default band.
+OPTIONAL_REQUEST_KEYS = {"headroom_band"}
+DEFAULT_HEADROOM_BAND = "30"
 POLICIES = {
     "default_claude", "default_codex", "default_both", "explicit", "producer_retry", "reviewer"}
 
@@ -166,8 +177,16 @@ def request_error(request: object) -> tuple[str, dict] | None:
         return "invalid_request", {"field": "schema"}
     if request.get("schema") != SCHEMA:
         return "unsupported_schema", {"field": "schema"}
-    if set(request) != REQUEST_KEYS:
+    keys = set(request)
+    if not REQUEST_KEYS <= keys or keys - REQUEST_KEYS - OPTIONAL_REQUEST_KEYS:
         return "invalid_request", {"field": "$"}
+    if "headroom_band" in request:
+        band, _text = decimal_value(request["headroom_band"])
+        # decimal_value clamps to [0,100] and rejects non-numeric shapes; a band
+        # the caller cannot express exactly must fail loudly rather than silently
+        # widen selection to the whole pool.
+        if band is None or isinstance(request["headroom_band"], bool):
+            return "invalid_request", {"field": "headroom_band"}
     try:
         timestamp(request["database_now"])
     except ValueError:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {

package/tests/run-tests.sh

@@ -1791,17 +1791,21 @@ EOF
          claude-accounts limits --force 2>&1)"
   check "a scope-denied 403 names the missing scope" "user:profile" "$out"
   check "a scope-denied 403 names the ceremony that fixes it" "claude-accounts login acct-01" "$out"
-  check "a scope-denied 403 backs off instead of retrying" "Backing off" "$out"
+  # The CREDENTIAL is refused for good (the digest below stops it being offered
+  # again); the ACCOUNT is deliberately NOT parked, because parking it also blocked
+  # the OAuth path and froze telemetry for hours on accounts whose login was fine.
+  check "a scope-denied 403 retires the token, not the account" \
+    "This token will not be offered again" "$out"
   python3 - "$SD/acct-01/limits.json" "$now" <<'EOF'
 import json, sys
 lim = json.load(open(sys.argv[1]))
 now = int(sys.argv[2])
-assert lim['retry_after'] > now + 3600, lim          # parked for hours, not minutes
+assert lim.get('token_scope_denied'), lim            # THIS token is retired
+assert not lim.get('retry_after'), lim               # ...but the account is not parked
 assert lim['fetched_at'] == now - 950000, lim        # a FAILURE never invents freshness
-assert 'HTTP 403' in lim['last_error'], lim
 EOF
-  [ $? -eq 0 ] && t_ok "a refused fetch records a long backoff and keeps its stale fetched_at" \
-    || t_fail "403 backoff state" "see $SD/acct-01/limits.json"
+  [ $? -eq 0 ] && t_ok "a refused token is retired without parking the account, keeping its stale fetched_at" \
+    || t_fail "403 credential-scoped state" "see $SD/acct-01/limits.json"
 
   # The whole point: the next scheduled pass must NOT spend another request. Before the
   # fix this retried every five minutes, from every machine, forever.
@@ -1809,9 +1813,12 @@ EOF
   out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
          claude-accounts limits 2>&1)"
   after="$(wc -l < "$uhits")"
-  [ "$before" = "$after" ] && t_ok "a parked account is not re-fetched on the next pass" \
+  [ "$before" = "$after" ] && t_ok "a retired token is not re-offered on the next pass" \
     || t_fail "403 retry storm" "endpoint hit again ($before -> $after requests)"
-  check "the parked account says why it is waiting" "backing off after HTTP 403" "$out"
+  # It is the CREDENTIAL that is spent, so the message names the ceremony that
+  # replaces it rather than a clock the operator would otherwise sit and watch.
+  check "and says what would fix it, not how long to wait" \
+    "telemetry stays dark until: claude-accounts login acct-01" "$out"
 
   # Any other non-2xx backs off too — a 5xx retried every pass is the same storm.
   rm -f "$SD/acct-01/limits.json"
@@ -1990,6 +1997,57 @@ EOF
   [ "$before" = "$after" ] && t_ok "a token already refused for scope is not offered again" \
     || t_fail "token re-offered" "endpoint hit again ($before -> $after)"
   check "and the message says what would fix it" "claude-accounts login acct-01" "$out"
+  # ---- an OAuth account NEVER spends its setup token here, and a token refusal
+  # ---- never parks the ACCOUNT ------------------------------------------------
+  # Live symptom (my-mini, 2026-08-28): acct-02/acct-05 sat 1-5 HOURS stale with
+  # "backing off after HTTP 403 (source=token) — permanent" while their OAuth
+  # credentials were fine. The chain: the access token had expired minutes ago, so
+  # refresh_oauth declined (REFRESH_MIN_EXPIRED proves no live session owns it),
+  # the probe fell through to the setup token, the endpoint refused it for scope,
+  # and that parked the whole ACCOUNT for six hours — blocking the OAuth path that
+  # would have worked on the very next pass. The shim then ranked the pool on
+  # hour-old readings and said so ("usage telemetry is 1h old").
+  SD2="$WORK/token-poison"
+  mkdir -p "$SD2/acct-01" "$SD2/tmp"
+  : > "$SD2/.limits-kick"
+  cat > "$SD2/accounts.json" <<EOF
+{ "version": 1, "server": "root@203.0.113.1", "server_root": "/root/.claude-accounts",
+  "server_repo": "/root/claude-multiacc", "threshold": 90,
+  "accounts": [ {"id": "acct-01", "email": "poison@test", "home": "mac",
+                 "added_at": "2026-08-28T00:00:00Z"} ] }
+EOF
+  # An OAuth credential whose ACCESS token expired a moment ago: too recent for
+  # refresh_oauth to touch, so this pass has no bearer it may use.
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-justexpired","refreshToken":"r","expiresAt":%s000,"refreshTokenExpiresAt":9999999999999}}' \
+    "$((now - 30))" > "$SD2/acct-01/.credentials.json"
+  printf 'sk-ant-oat01-PORTABLE0001\n' > "$SD2/acct-01/server.token"
+  before="$(wc -l < "$uhits")"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD2" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits 2>&1)"
+  after="$(wc -l < "$uhits")"
+  [ "$before" = "$after" ] \
+    && t_ok "an OAuth account never spends its setup token on the usage endpoint" \
+    || t_fail "token spent" "the endpoint was called ($before -> $after) with a token that can only 403"
+  check "and it says it will simply retry" "retrying next pass" "$out"
+  [ ! -f "$SD2/acct-01/limits.json" ] \
+    && t_ok "no six-hour park is written for an account that merely missed a refresh" \
+    || t_fail "account parked" "$(cat "$SD2/acct-01/limits.json")"
+
+  # A token-only account still tries once (that is the only way to learn), but the
+  # refusal must park the CREDENTIAL, not the account: the digest is remembered and
+  # no retry_after is written, so a later OAuth login is free to work immediately.
+  rm -f "$SD2/acct-01/.credentials.json" "$SD2/acct-01/limits.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD2" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+    claude-accounts limits >/dev/null 2>&1
+  python3 - "$SD2/acct-01/limits.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d.get('token_scope_denied'), d
+assert not d.get('retry_after'), f"the account was parked by a credential refusal: {d}"
+EOF
+  [ $? -eq 0 ] && t_ok "a token scope refusal parks the credential, never the account" \
+    || t_fail "token refusal parked the account" "see $SD2/acct-01/limits.json"
+
   # Re-minting the token is a new credential, so it earns a fresh try.
   printf 'sk-ant-oat01-REMINTED01\n' > "$SD/acct-01/server.token"
   before="$(wc -l < "$uhits")"

package/tests/test_selector.py

@@ -54,7 +54,7 @@ class SelectorTests(unittest.TestCase):
             "e8ef0b4bc7b95e76231ee6da79616d92bd9251c1c991845c8c0524fcbfb6593a")
         self.assertEqual(
             response["selection_digest"],
-            "2c9607e3dc1fde3ddf4e4469fbe48cf0e6a3c8114ef0c6b5f3c82f8ed4f78e3e")
+            "8b68d69b31b2d2252a16f7b83ac46860987647aa360402caa815b2a1bd468def")
 
     def test_unicode_and_active_reservation_proof(self):
         busy = {"active_expires_at": "2026-08-25T09:00:00.000001Z", "last_selected_at": None}
@@ -68,7 +68,7 @@ class SelectorTests(unittest.TestCase):
             "29e8e7d1a611f38ee0be43622102b33875e7ff75ff9024aa43d16151575071d4")
         self.assertEqual(
             response["selection_digest"],
-            "2f018ab0e308a8465898e75a867e18d8620c03b4a49109edc1d2d590bf0d1121")
+            "72e7b31a00496fff0f6281f4dacd656d3a2a1fc438038e2c20c49274e1f61068")
 
     def test_both_chooses_each_provider_and_survives_provider_loss(self):
         codex = select(_request([
@@ -207,8 +207,106 @@ class SelectorTests(unittest.TestCase):
                             for item in bad))
         self.assertEqual(json.loads(decimal_response.stdout)["account_id"], "z-lower")
         self.assertEqual(version, "2.0.1")
+        # npm package versioning, unrelated to SELECTOR_VERSION: auto-version bumps the
+        # next patch above what is published.
         self.assertEqual(versions, ["2.0.0", "2.0.1"])
 
 
+class HeadroomBandTests(unittest.TestCase):
+    """Accounts within `headroom_band` points of the leader are interchangeable.
+
+    Ranking strictly by headroom sends every task to whichever account is on top
+    until it is spent below the runner-up, which is how one account's weekly limit
+    was burned to zero while three others sat idle.
+    """
+
+    def _pool(self, *specs) -> list[dict]:
+        # spec: (account_id, weekly_pct, last_selected_at)
+        return [_candidate(account_id=name, weekly_pct=pct, session_pct=0,
+                           reservation_history={"active_expires_at": None,
+                                                "last_selected_at": last})
+                for name, pct, last in specs]
+
+    def test_band_spreads_launches_instead_of_stacking_on_the_leader(self):
+        # headroom 100 / 80 / 70 / 60 — the first three are within 30 of the leader.
+        pool = self._pool(("a", 0, None), ("b", 20, None), ("c", 30, None), ("d", 40, None))
+        picked = {}
+        for index in range(120):
+            response = select(_request(pool, reservation_key=f"launch-{index}"))
+            self.assertTrue(response["ok"])
+            picked[response["account_id"]] = picked.get(response["account_id"], 0) + 1
+            self.assertEqual(response["band_floor"], "70")
+            self.assertEqual(response["band_count"], 3)
+        self.assertEqual(set(picked), {"a", "b", "c"},
+                         "every banded account must take work; 'd' is out of band")
+        # No account may take more than half: the point is spreading the burn.
+        self.assertLess(max(picked.values()), 60, picked)
+        self.assertGreater(min(picked.values()), 20, picked)
+
+    def test_same_request_always_selects_the_same_account(self):
+        pool = self._pool(("a", 0, None), ("b", 20, None), ("c", 30, None))
+        first = select(_request(pool, reservation_key="stable"))
+        for _ in range(5):
+            repeat = select(_request(pool, reservation_key="stable"))
+            self.assertEqual(repeat["account_id"], first["account_id"])
+            self.assertEqual(repeat["selection_digest"], first["selection_digest"])
+
+    def test_least_recently_used_wins_inside_the_band(self):
+        # The emptiest account (a) was used most recently; the band rotates past it.
+        pool = self._pool(("a", 0, "2026-08-25T08:59:00.000000Z"),
+                          ("b", 20, "2026-08-25T08:00:00.000000Z"),
+                          ("c", 30, "2026-08-25T07:00:00.000000Z"))
+        self.assertEqual(select(_request(pool))["account_id"], "c")
+        # A never-used account outranks every used one.
+        pool = self._pool(("a", 0, "2026-08-25T08:59:00.000000Z"), ("b", 20, None))
+        self.assertEqual(select(_request(pool))["account_id"], "b")
+
+    def test_out_of_band_account_never_wins_however_idle(self):
+        pool = self._pool(("a", 0, "2026-08-25T08:59:59.000000Z"),
+                          ("d", 40, "2020-01-01T00:00:00.000000Z"))
+        response = select(_request(pool))
+        self.assertEqual(response["account_id"], "a")
+        self.assertEqual(response["band_count"], 1)
+
+    def test_zero_band_restores_strict_most_headroom(self):
+        pool = self._pool(("a", 0, "2026-08-25T08:59:00.000000Z"), ("b", 20, None))
+        self.assertEqual(select(_request(pool, headroom_band=0))["account_id"], "a")
+
+    def test_band_is_configurable_and_validated(self):
+        pool = self._pool(("a", 0, None), ("d", 40, None))
+        wide = select(_request(pool, headroom_band="45"))
+        self.assertEqual(wide["band_floor"], "55")
+        self.assertEqual(wide["band_count"], 2)
+        for bad in ("abc", True, [], "1e5", None):
+            refusal = select(_request(pool, headroom_band=bad))
+            self.assertFalse(refusal["ok"], bad)
+            self.assertEqual(refusal["error_detail"], {"field": "headroom_band"}, bad)
+
+    def test_unknown_quota_never_enters_the_band(self):
+        # A row with no telemetry has no headroom to compare; it must not become
+        # "as good as the leader" just because the band is generous.
+        pool = self._pool(("a", 0, None))
+        pool.append(_candidate(account_id="blind", weekly_pct=None, session_pct=None,
+                               reservation_history={"active_expires_at": None,
+                                                    "last_selected_at": None}))
+        response = select(_request(pool))
+        self.assertEqual(response["account_id"], "a")
+        self.assertEqual(response["band_count"], 1)
+        # ...and with NO usable telemetry anywhere, the band cannot apply at all.
+        blind = [_candidate(account_id=name, weekly_pct=None, session_pct=None)
+                 for name in ("x", "y")]
+        response = select(_request(blind))
+        self.assertTrue(response["ok"])
+        self.assertIsNone(response["band_floor"])
+
+    def test_band_participates_in_the_selection_proof(self):
+        pool = self._pool(("a", 0, None), ("b", 20, None))
+        narrow = select(_request(pool, headroom_band="5"))
+        wide = select(_request(pool, headroom_band="50"))
+        self.assertNotEqual(narrow["selection_digest"], wide["selection_digest"])
+        # An omitted band is the documented default, and says so in the response.
+        self.assertEqual(select(_request(pool))["headroom_band"], "30")
+
+
 if __name__ == "__main__":
     unittest.main()