claude-multiacc 2.0.5 → 2.0.6

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.6",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {

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()