claude-multiacc 2.0.4 → 2.0.6

package/bin/claude-accounts

@@ -2351,6 +2351,15 @@ cmd_self_update() {
         ulog "self-update: no npm found (looked in $prefix/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin, PATH); skipping"
         return 0
       }
+      # Finding npm is not the same as being able to RUN it: npm ships as
+      # `#!/usr/bin/env node`, so an agent PATH without the node that owns it makes
+      # every invocation die with "env: node: No such file or directory" — and npm
+      # exits 0 on that, so the version probe just came back empty and the update
+      # "failed" with nothing to explain it. node lives beside npm, so every npm call
+      # below runs with that directory in front (command-scoped: nothing else in this
+      # process has its PATH changed underneath it).
+      local npm_path
+      npm_path="$(dirname "$npm_bin"):$PATH"
       # Update THE COPY THAT IS RUNNING, not whichever one the ambient npm prefix
       # happens to point at. my-mini had two global installs — homebrew's on PATH and
       # nvm's under `npm root -g` — and self-update kept upgrading the nvm one and
@@ -2359,13 +2368,13 @@ cmd_self_update() {
       # A deploy nobody runs is not a deploy, and one that announces success is worse
       # than one that fails.
       cur="$(pkg_version_at "$REPO_DIR")"
-      lat="$("$npm_bin" view claude-multiacc version 2>/dev/null)"
+      lat="$(PATH="$npm_path" "$npm_bin" view claude-multiacc version 2>/dev/null)"
       if [ -n "$lat" ] && [ "$cur" = "$lat" ]; then
         ulog "self-update: already latest ($cur)"
         return 0
       fi
       ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix, npm $npm_bin)"
-      if "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
+      if PATH="$npm_path" "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
            >>"$ACC_ROOT/update.log" 2>&1; then
         # Verify by re-reading the file on disk. npm reporting success says nothing
         # about which tree it wrote to.

package/bin/codex-accounts

@@ -1899,14 +1899,23 @@ cmd_self_update() {
         ulog "self-update: no npm found (looked in $prefix/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin, PATH); skipping"
         return 0
       }
+      # Finding npm is not the same as being able to RUN it: npm ships as
+      # `#!/usr/bin/env node`, so an agent PATH without the node that owns it makes
+      # every invocation die with "env: node: No such file or directory" — and npm
+      # exits 0 on that, so the version probe just came back empty and the update
+      # "failed" with nothing to explain it. node lives beside npm, so every npm call
+      # below runs with that directory in front (command-scoped: nothing else in this
+      # process has its PATH changed underneath it).
+      local npm_path
+      npm_path="$(dirname "$npm_bin"):$PATH"
       cur="$(pkg_version_at "$REPO_DIR")"
-      lat="$("$npm_bin" view claude-multiacc version 2>/dev/null)"
+      lat="$(PATH="$npm_path" "$npm_bin" view claude-multiacc version 2>/dev/null)"
       if [ -n "$lat" ] && [ "$cur" = "$lat" ]; then
         ulog "self-update: already latest ($cur)"
         return 0
       fi
       ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix, npm $npm_bin)"
-      if "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
+      if PATH="$npm_path" "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
            >>"$ACC_ROOT/update.log" 2>&1; then
         after="$(pkg_version_at "$REPO_DIR")"
         if [ -n "$lat" ] && [ "$after" != "$lat" ]; then

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

package/tests/run-tests.sh

@@ -2451,8 +2451,17 @@ if command -v node >/dev/null 2>&1; then
     mkdir -p "$NPMROOT" "$PFX/bin"
     cp -R "$REPO_DIR/bin" "$REPO_DIR/lib" "$REPO_DIR/package.json" "$NPMROOT/"
     # A fake npm that records how it was called and "installs" by bumping package.json.
-    cat > "$PFX/bin/npm" <<NPMEOF
+    # Its shebang names an interpreter that exists ONLY beside it, mirroring the real
+    # npm's `#!/usr/bin/env node`: resolving npm by absolute path is not enough if the
+    # agent's PATH cannot find npm's own interpreter, which is how the update failed
+    # with an empty version probe and no explanation.
+    cat > "$PFX/bin/multiacc-fake-node" <<'NODEEOF'
 #!/usr/bin/env bash
+exec /bin/bash "$@"
+NODEEOF
+    chmod +x "$PFX/bin/multiacc-fake-node"
+    cat > "$PFX/bin/npm" <<NPMEOF
+#!/usr/bin/env multiacc-fake-node
 echo "npm \$*" >> "$WORK/npm-calls-$_cli.log"
 case "\${1:-}" in
   view) echo 9.9.9 ;;
@@ -2488,6 +2497,9 @@ NPMEOF
       && t_fail "$_cli npm choice" "used the npm from PATH instead of the running prefix's" \
       || t_ok "$_cli: a stray npm on PATH never wins over the running prefix's"
     check "$_cli: self-update verifies the tree it wrote" "npm update ok (9.9.9)" "$out"
+    grep -q "^npm view " "$WORK/npm-calls-$_cli.log" \
+      && t_ok "$_cli: npm ran despite its interpreter being off PATH" \
+      || t_fail "$_cli npm interpreter" "npm never executed — its shebang interpreter was not found"
   done
   # The agents install.sh writes must carry a PATH for the same reason (a future tool
   # that is not resolved by absolute path would hit exactly this again).

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