claude-multiacc 2.0.20 → 2.0.21

package/lib/selector_primitives.py

@@ -11,13 +11,15 @@ 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.
+# NOT bumped for the headroom band, and NOT bumped for the session gate either. 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. Both knobs are additive and optional: the
+# request only grows optional keys, the response only grows fields, and every existing
+# consumer keeps reading exactly what it read before.
 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]"
@@ -33,9 +35,13 @@ 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"}
+# REQUEST_KEYS; absent, the policy applies its own defaults. app-robot's panel sends
+# headroom_band from its own setting and never sends session_gate, so the gate default
+# below is what every panel launch gets (operator's 2026-09-03 decision: session
+# headroom gates FIRST, then the weekly band picks among the survivors).
+OPTIONAL_REQUEST_KEYS = {"headroom_band", "session_gate"}
 DEFAULT_HEADROOM_BAND = "30"
+DEFAULT_SESSION_GATE = "50"
 POLICIES = {
     "default_claude", "default_codex", "default_both", "explicit", "producer_retry", "reviewer"}
 
@@ -180,13 +186,16 @@ def request_error(request: object) -> tuple[str, dict] | None:
     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"}
+    for knob in ("headroom_band", "session_gate"):
+        if knob not in request:
+            continue
+        value, _text = decimal_value(request[knob])
+        # decimal_value clamps to [0,100] and rejects non-numeric shapes; a knob the
+        # caller cannot express exactly must fail loudly rather than silently widen
+        # selection to the whole pool (band) or wave every session-heavy account
+        # through (gate). Both are validated identically so the panel can send either.
+        if value is None or isinstance(request[knob], bool):
+            return "invalid_request", {"field": knob}
     try:
         timestamp(request["database_now"])
     except ValueError:

package/package.json

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

package/tests/run-tests.sh

@@ -317,7 +317,7 @@ check "passthrough with CLAUDE_CODE_OAUTH_TOKEN" "CFG=none" "$out"
 out="$(CLAUDE_MULTIACC_DISABLE=1 claude 2>&1)"
 check "passthrough when disabled" "CFG=none" "$out"
 
-# ---- 5. headroom selection: most WEEKLY headroom wins (session is only a tiebreaker) --
+# ---- 5. headroom selection: the session gate first, then the WEEKLY headroom band ----
 lj() { # lj <weekly> <session> <max>  -> a fresh limits.json body
   printf '{"fetched_at":%s,"weekly_percent":%s,"session_percent":%s,"max_percent":%s,"buckets":[]}' "$now" "$1" "$2" "$3"
 }
@@ -360,28 +360,131 @@ done
 [ "$all1" = 1 ] && t_ok "Claude headroom band 0 restores strict ranking" \
   || t_fail "Claude zero headroom band" "the runner-up was selected"
 
-# THE KEY CASE from the research: a high (but sub-threshold) SESSION bucket must NOT
-# deprioritize an account whose weekly headroom is better. acct-01: session 85, weekly 10;
-# acct-02: session 20, weekly 70. Both eligible (max<90). acct-01 is the better pick —
-# its near-full bucket is the 5h session (self-heals), weekly is nearly untouched.
+# THE KEY CASE, REVERSED on 2026-09-03. It used to assert that a high (but
+# sub-threshold) SESSION bucket must not deprioritize an account with better weekly
+# headroom. The operator asked for the opposite: "among accounts where high session
+# limits it must choose randomly from ones where highest weekly limits" — an account
+# whose 5h bucket is nearly spent is about to be rejected whatever its weekly headroom.
+# So the SESSION GATE (default 50) is the FIRST cut and the 30-point weekly band ranks
+# only what clears it. acct-01: session 85 (past the gate), weekly 10; acct-02: session
+# 20, weekly 70. Both eligible (max<90) — acct-02 wins every time now.
 lj 10 85 85 > "$ACC/acct-01/limits.json"
 lj 70 20 70 > "$ACC/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "a session bucket past the gate is skipped while a fresher one exists (70w/20s over 10w/85s)" \
+  || t_fail "session gate" "the account with its 5h bucket at 85% was still selected"
+# The pick has to be auditable: the log names the gate and how many cleared it.
+: > "$ACC/selection.log"
+claude >/dev/null 2>&1
+grep -qE 'acct-02 weekly=70% session=20% band=30 band-count=1 session-gate=50 session-ok=1 pwd=' "$ACC/selection.log" \
+  && t_ok "the selection log carries session-gate=50 session-ok=1 when one of two clears" \
+  || t_fail "session gate log" "$(tail -1 "$ACC/selection.log")"
+
+# Both session buckets inside the gate: the gate has nothing to say and weekly decides,
+# exactly as before the change.
+lj 10 45 45 > "$ACC/acct-01/limits.json"
+lj 70 20 70 > "$ACC/acct-02/limits.json"
 all1=1
 for _ in $(seq 1 15); do
   case "$(claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
 done
-[ "$all1" = "1" ] && t_ok "high session does NOT beat better weekly headroom (10w/85s over 70w/20s)" \
-  || t_fail "weekly-over-session" "ranked the account with less weekly headroom higher"
+[ "$all1" = "1" ] && t_ok "with both sessions inside the gate weekly headroom decides (10w/45s over 70w/20s)" \
+  || t_fail "session gate no-op" "the gate changed a ranking where every candidate cleared it"
 
-# In strict mode, equal weekly usage still uses session usage as its tiebreaker.
+# Nobody clears the gate: it COMPARES candidates, it never empties the pool — it steps
+# aside and weekly ranks the whole set (10w wins), and the log says session-ok=0.
+lj 10 85 85 > "$ACC/acct-01/limits.json"
+lj 70 60 70 > "$ACC/acct-02/limits.json"
+: > "$ACC/selection.log"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "with nobody inside the gate it steps aside and weekly ranks (10w/85s over 70w/60s)" \
+  || t_fail "session gate step-aside" "an empty gate emptied the pool instead of stepping aside"
+grep -qE 'acct-01 weekly=10% session=85% band=30 band-count=1 session-gate=50 session-ok=0 pwd=' "$ACC/selection.log" \
+  && t_ok "the selection log carries session-ok=0 when the gate steps aside" \
+  || t_fail "session gate log" "$(tail -1 "$ACC/selection.log")"
+
+# The gate is a knob, like the band: 100 turns it off and pure weekly ranking returns.
+lj 10 85 85 > "$ACC/acct-01/limits.json"
+lj 70 20 70 > "$ACC/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(CLAUDE_MULTIACC_SESSION_GATE=100 claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "CLAUDE_MULTIACC_SESSION_GATE=100 disables the gate" \
+  || t_fail "session gate off" "the gate still fired at 100"
+# ...and garbage in that env var falls back to the 50-point default, never to "off".
+all2=1
+for _ in $(seq 1 15); do
+  case "$(CLAUDE_MULTIACC_SESSION_GATE=abc claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "a non-numeric CLAUDE_MULTIACC_SESSION_GATE falls back to 50" \
+  || t_fail "session gate validation" "a garbage gate value changed the outcome"
+
+# Equal weekly usage: the GATE decides, not a tiebreak. Session stopped being a ranking
+# input inside the band on 2026-09-03 — acct-02's 80-point session bucket simply never
+# reaches the weekly comparison, whether the band is strict or the default 30.
 lj 40 20 40 > "$ACC/acct-01/limits.json"
 lj 40 80 80 > "$ACC/acct-02/limits.json"
 all1=1
 for _ in $(seq 1 15); do
   case "$(CLAUDE_MULTIACC_HEADROOM_BAND=0 claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
 done
-[ "$all1" = "1" ] && t_ok "strict mode: equal weekly usage uses the session tiebreak" \
-  || t_fail "session tiebreak" "did not use session to break a weekly tie"
+[ "$all1" = "1" ] && t_ok "strict mode: the session gate decides an exact weekly tie" \
+  || t_fail "session gate tie" "a weekly tie was not resolved by the session gate"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "the gate (not the band) removes the session-heavy half of a weekly tie" \
+  || t_fail "session gate tie" "the default band let the 80-point session account back in"
+
+# Inside the gate, session is NOT a tiebreaker any more: an exact weekly tie between two
+# gate-clearing accounts is a coin flip even in strict mode (it used to go to the lower
+# session, through the old weekly*1000+session score).
+lj 40 20 40 > "$ACC/acct-01/limits.json"
+lj 40 45 45 > "$ACC/acct-02/limits.json"
+hits1=0; hits2=0
+for _ in $(seq 1 20); do
+  case "$(CLAUDE_MULTIACC_HEADROOM_BAND=0 claude 2>&1)" in
+    *CFG=acct-01*) hits1=$((hits1+1)) ;;
+    *CFG=acct-02*) hits2=$((hits2+1)) ;;
+  esac
+done
+{ [ "$hits1" -gt 0 ] && [ "$hits2" -gt 0 ]; } \
+  && t_ok "strict mode: session does not break an exact weekly tie inside the gate (acct-01=$hits1 acct-02=$hits2)" \
+  || t_fail "session tiebreak removed" "acct-01=$hits1 acct-02=$hits2 (want both >0)"
+
+# Clearing the gate takes BOTH readings, as in pool-selection.v2: a fresh file with a
+# session reading but no weekly one must not become the sole gate-clearer and win the
+# all-gated tie over an account with a truthful weekly reading — not even with a
+# max_percent to fall back on (the shims used to rank on that; the policy never could).
+# (No writer produces such a file; this pins parity with lib/selector_policy.py.)
+printf '{"fetched_at":%s,"max_percent":10,"session_percent":10,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
+lj 20 80 80 > "$ACC/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "a session reading without a weekly one never clears the gate" \
+  || t_fail "gate needs both readings" "an unknown-weekly account beat a truthful weekly reading"
+
+# ...and the converse: a weekly reading without a session one is not "known" either — it
+# neither clears the gate nor ranks once the gate steps aside (10w/?s vs 70w/80s -> the
+# 70w account, as in pool-selection.v2, where quota_known needs both readings).
+printf '{"fetched_at":%s,"weekly_percent":10,"max_percent":10,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
+lj 70 80 80 > "$ACC/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "a weekly reading without a session one is unknown to both cuts" \
+  || t_fail "known needs both readings" "a session-less weekly reading ranked as known"
 
 # fully equal scores spread load across accounts
 lj 10 10 10 > "$ACC/acct-01/limits.json"
@@ -409,6 +512,10 @@ done
 { [ "$hits1" -gt 0 ] && [ "$hits2" -gt 0 ]; } \
   && t_ok "CLAUDE_SHIM_SELECT=random restores uniform spread" \
   || t_fail "random opt-out" "acct-01=$hits1 acct-02=$hits2"
+# ...and its log line must not claim a gate that never ran (codex review, 2026-09-04).
+grep -qE 'band=30 band-count=2 session-gate=off session-ok=2 pwd=' "$ACC/selection.log" \
+  && t_ok "random mode logs session-gate=off instead of a cut it never made" \
+  || t_fail "random mode gate log" "$(grep 'SHIM_SELECT\|session-gate' "$ACC/selection.log" | tail -1)"
 
 # Unknown telemetry ranks behind every truthful reading, never as neutral or free.
 printf '{"fetched_at":1,"weekly_percent":1,"session_percent":1,"max_percent":1,"buckets":[]}' > "$ACC/acct-01/limits.json"
@@ -478,17 +585,35 @@ printf '%s\nbucket=session percent=95 reason=limits\n' "$((now-10))" > "$ACC/acc
 claude >/dev/null 2>&1
 [ ! -f "$ACC/acct-01/.limited" ] && t_ok "expired marker auto-cleared" || t_fail "expired marker auto-cleared" "marker still present"
 
-# ---- 9. all limited -> least utilized fallback ------------------------------
+# ---- 9. all limited -> the still-serving accounts go through the same two cuts, strict weekly ----
 printf '%s\nx\n' "$((now+3600))" > "$ACC/acct-01/.limited"
 printf '%s\nx\n' "$((now+3600))" > "$ACC/acct-02/.limited"
-printf '{"fetched_at":%s,"max_percent":97,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
-printf '{"fetched_at":%s,"max_percent":91,"buckets":[]}' "$now" > "$ACC/acct-02/limits.json"
+lj 97 10 97 > "$ACC/acct-01/limits.json"
+lj 91 10 91 > "$ACC/acct-02/limits.json"
 out="$(claude 2>&1)"
-check "all-limited falls back to least utilized" "CFG=acct-02" "$out"
+check "all-limited falls back to the still-serving account with the most weekly headroom" "CFG=acct-02" "$out"
 grep -q "all-limited fallback=acct-02" "$ACC/selection.log" \
   && t_ok "fallback logged" || t_fail "fallback logged" "no all-limited line in selection.log"
 rm -f "$ACC/acct-01/.limited" "$ACC/acct-02/.limited"
 
+# The fallback applies the SAME two cuts: with every account limit-marked but still
+# serving, an account past the session gate (10w/85s) yields to one inside it (70w/20s)
+# even though its weekly headroom is far better — exactly as in ordinary selection.
+# (On the pre-gate rule this picked 10w/85s, the best strict weekly score.)
+printf '%s\nbucket=weekly_all percent=95 marked_at=x reason=limits\n' "$((now+3600))" > "$ACC/acct-01/.limited"
+printf '%s\nbucket=weekly_all percent=95 marked_at=x reason=limits\n' "$((now+3600))" > "$ACC/acct-02/.limited"
+lj 10 85 85 > "$ACC/acct-01/limits.json"
+lj 70 20 70 > "$ACC/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 12); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "the all-limited fallback applies the session gate before strict weekly (70w/20s over 10w/85s)" \
+  || t_fail "fallback session gate" "the fallback handed out the account past the session gate"
+grep -q "all-limited fallback=acct-02 weekly=70%" "$ACC/selection.log" \
+  && t_ok "the fallback line names the gated pick" || t_fail "fallback gate log" "$(tail -1 "$ACC/selection.log")"
+rm -f "$ACC/acct-01/.limited" "$ACC/acct-02/.limited"
+
 # ---- 9a2. the fallback tells "still serving" from "rejected right now" --------------
 # acct-01: weekly at 99% — worse headroom, but still answering requests.
 # acct-02: session at 100% — far better weekly (7%), but every request bounces until
@@ -512,8 +637,8 @@ check "all exhausted: the soonest reset is handed out" "CFG=acct-02" "$out"
 grep -q "all-exhausted resets_in=" "$ACC/selection.log" \
   && t_ok "the all-exhausted pick is logged with its reset" || t_fail "all-exhausted log" "no line"
 rm -f "$ACC/acct-01/.limited" "$ACC/acct-02/.limited"
-printf '{"fetched_at":%s,"max_percent":97,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
-printf '{"fetched_at":%s,"max_percent":91,"buckets":[]}' "$now" > "$ACC/acct-02/limits.json"
+lj 97 10 97 > "$ACC/acct-01/limits.json"
+lj 91 10 91 > "$ACC/acct-02/limits.json"
 
 # ---- 9a3. a token park is credential-scoped ----------------------------------------
 # A dead portable token beside a LIVE login: this session runs the account on the
@@ -717,8 +842,8 @@ rm -f "$ACC/acct-01/server.token"
 printf '%s' "$DEAD_CREDS" > "$ACC/acct-01/.credentials.json"
 printf '%s' "$HEALTHY_CREDS" > "$ACC/acct-02/.credentials.json"
 printf 'sk-ant-oat01-REVOKEDREVOKEDREVOKEDREVOKEDREVOKEDREVOKED' > "$ACC/acct-01/server.token"
-printf '{"fetched_at":%s,"max_percent":1,"buckets":[]}' "$now" > "$ACC/acct-01/limits.json"
-printf '{"fetched_at":%s,"max_percent":50,"buckets":[]}' "$now" > "$ACC/acct-02/limits.json"
+lj 1 1 1 > "$ACC/acct-01/limits.json"      # ranks first, so its preflight is what runs
+lj 50 1 50 > "$ACC/acct-02/limits.json"
 rm -f "$ACC/.last-pick" "$ACC/acct-01/.expired" "$ACC/acct-01/.server-token-verified"
 out="$(claude --resume d6ccbac0-6643-4780-a99e-3afa1683478e 2>&1)"
 check "revoked setup-token fails over before --resume" "CFG=acct-02" "$out"
@@ -1439,7 +1564,7 @@ expected="$(cat "$WORK/stdin13")"
 
 # ---- 14. selection log written ------------------------------------------------
 log_pattern='^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*acct-0[123] weekly=[0-9?]+% session=[0-9?]+%'
-log_pattern="$log_pattern band=30 band-count=[0-9]+ pwd="
+log_pattern="$log_pattern band=30 band-count=[0-9]+ session-gate=50 session-ok=[0-9]+ pwd="
 grep -qE "$log_pattern" "$ACC/selection.log" \
   && t_ok "selection.log format" || t_fail "selection.log format" "no matching lines"
 grep -qE 'sk-ant-oat|accessToken|refreshToken' "$ACC/selection.log" \
@@ -1931,10 +2056,13 @@ assert groups["weekly_scoped:Fable"] == "weekly", groups
 EOF
 [ $? -eq 0 ] && t_ok "limits records weekly_percent(55) + session_percent(88) with correct groups" \
   || t_fail "weekly/session classification" "see limits.json"
-# a session bucket at 88 must NOT poison weekly ranking: score uses weekly(55), not 88
-sc="$(python3 -c "import json;d=json.load(open('$ACC/acct-01/limits.json'));print(d['weekly_percent']*1000+d['session_percent'])")"
-[ "$sc" = "55088" ] && t_ok "ranking score weighs weekly over session (55088)" \
-  || t_fail "ranking score" "got $sc"
+# The two numbers must stay SEPARATE on disk. There is no combined score any more
+# (2026-09-03): the shim GATES on session_percent and BANDS on weekly_percent, so a
+# session bucket at 88 must never be folded into — or allowed to poison — the weekly
+# reading the band ranks on.
+sc="$(python3 -c "import json;d=json.load(open('$ACC/acct-01/limits.json'));print('%s/%s' % (d['weekly_percent'], d['session_percent']))")"
+[ "$sc" = "55/88" ] && t_ok "weekly and session are recorded as separate ranking inputs (55 weekly / 88 session)" \
+  || t_fail "weekly/session ranking inputs" "got $sc"
 rm -f "$ACC/acct-01/limits.json" "$ACC/acct-01/.limited"
 
 # ---- 16-marker. the marker names ONE bucket and carries THAT bucket's reset ----------
@@ -2410,6 +2538,9 @@ EOF
   grep -q "ranking=BLIND" "$SD/selection.log" \
     && t_ok "selection.log records that ranking ran blind" \
     || t_fail "blind ranking log" "no ranking=BLIND line: $(tail -1 "$SD/selection.log")"
+  grep -qE "ranking=BLIND telemetry-age=[0-9]+s band=30 band-count=[0-9]+ session-gate=50 session-ok=0 pwd=" "$SD/selection.log" \
+    && t_ok "the blind line carries both cuts in the standard field order" \
+    || t_fail "blind line fields" "$(tail -1 "$SD/selection.log")"
   grep -q "telemetry-age=9[0-9]\{5\}s" "$SD/selection.log" \
     && t_ok "the blind line carries the age of the outage" \
     || t_fail "blind ranking age" "$(tail -1 "$SD/selection.log")"
@@ -2431,17 +2562,20 @@ EOF
   # ...and telemetry INSIDE the window must still rank. 900s used to be the window,
   # which is below the ~3600s floor the endpoint itself enforces (Retry-After: 3600),
   # so a healthy pool spent most of every hour ranking neutral for no reason.
-  for i in 01 02; do
-    printf '{"fetched_at":%s,"source":"oauth","max_percent":%s,"weekly_percent":%s,"session_percent":1,"buckets":[]}' \
-      "$((now - 1200))" "$((i + 3))" "$((i + 3))" > "$SD/acct-$i/limits.json"
-  done
+  # acct-02 is put OUTSIDE the 30-point band (weekly 40 against acct-01's 4) on purpose:
+  # inside the band the two are peers and the pick is a coin flip, which would make this
+  # assertion about the freshness window flaky for reasons that have nothing to do with it.
+  printf '{"fetched_at":%s,"source":"oauth","max_percent":4,"weekly_percent":4,"session_percent":1,"buckets":[]}' \
+    "$((now - 1200))" > "$SD/acct-01/limits.json"
+  printf '{"fetched_at":%s,"source":"oauth","max_percent":40,"weekly_percent":40,"session_percent":1,"buckets":[]}' \
+    "$((now - 1200))" > "$SD/acct-02/limits.json"
   : > "$SD/selection.log"
   CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1
   ! grep -q "ranking=BLIND" "$SD/selection.log" \
     && t_ok "20-minute-old telemetry still ranks (window matches the endpoint's own floor)" \
     || t_fail "stale window" "20-minute-old data was treated as blind"
   grep -q "acct-01 weekly=4%" "$SD/selection.log" \
-    && t_ok "the pool ranks on real numbers and picks the account with more headroom" \
+    && t_ok "the pool ranks on real numbers and picks the account with more headroom (4% over 40%)" \
     || t_fail "headroom ranking" "$(tail -1 "$SD/selection.log")"
 
   # ---- blind does not mean neutral --------------------------------------------
@@ -2467,6 +2601,10 @@ EOF
   grep -q "ranking=DEGRADED" "$SD/selection.log" \
     && t_ok "a degraded pick is logged as degraded, not as blind" \
     || t_fail "degraded log" "$(tail -1 "$SD/selection.log")"
+  # Session is unknown in a degraded pool, so nobody clears the gate: session-ok=0.
+  grep -qE "ranking=DEGRADED telemetry-age=[0-9]+s band=30 band-count=[0-9]+ session-gate=50 session-ok=0 pwd=" "$SD/selection.log" \
+    && t_ok "the degraded line carries both cuts in the standard field order" \
+    || t_fail "degraded line fields" "$(tail -1 "$SD/selection.log")"
   grep -q "acct-02 weekly=4% .*ranking=DEGRADED" "$SD/selection.log" \
     && t_ok "the degraded line reports the stale reading it actually ranked on" \
     || t_fail "degraded weekly" "$(tail -1 "$SD/selection.log")"
@@ -2712,10 +2850,14 @@ RACER
   # threshold on its session bucket (max 91%). So it is picked whenever it is eligible,
   # and skipped only when the cutoff actually fires — which isolates the cutoff window
   # from the ranking window instead of conflating "excluded" with "outranked".
+  # BOTH sessions sit above the 50-point session gate (91 and 55) deliberately: with
+  # acct-02 inside the gate it would be the only gated candidate and win on the gate
+  # alone, and these assertions would then be measuring the gate instead of the cutoff
+  # window. Nobody clearing the gate makes it step aside, so weekly alone ranks here.
   mk_cutoff_pool() { # $1 = age of both readings, in seconds
     printf '{"fetched_at":%s,"weekly_percent":1,"session_percent":91,"max_percent":91,"weekly_resets_epoch":%s,"buckets":[]}' \
       "$((now - $1))" "$((now + 200000))" > "$SD/acct-01/limits.json"
-    printf '{"fetched_at":%s,"weekly_percent":50,"session_percent":5,"max_percent":50,"weekly_resets_epoch":%s,"buckets":[]}' \
+    printf '{"fetched_at":%s,"weekly_percent":50,"session_percent":55,"max_percent":55,"weekly_resets_epoch":%s,"buckets":[]}' \
       "$((now - $1))" "$((now + 200000))" > "$SD/acct-02/limits.json"
     : > "$SD/selection.log"
     rm -f "$SD/.last-pick"
@@ -3346,7 +3488,7 @@ check "codex: passthrough with CODEX_HOME" "CFG=other" "$out"
 out="$(CODEX_MULTIACC_DISABLE=1 codex 2>&1)"
 check "codex: passthrough when disabled" "CFG=none" "$out"
 
-# ---- C3. headroom selection --------------------------------------------------------
+# ---- C3. headroom selection: session gate first, then the WEEKLY headroom band ------
 cxlj() { printf '{"fetched_at":%s,"weekly_percent":%s,"session_percent":%s,"max_percent":%s,"buckets":[]}' "$now" "$1" "$2" "$3"; }
 cxlj 80 10 80 > "$CX/acct-01/limits.json"
 cxlj 20 10 20 > "$CX/acct-02/limits.json"
@@ -3377,15 +3519,118 @@ for _ in $(seq 1 10); do
 done
 [ "$all1" = 1 ] && t_ok "codex: headroom band 0 restores strict ranking" \
   || t_fail "codex zero headroom band" "the runner-up was selected"
-# high session must NOT beat better weekly headroom
+# THE KEY CASE, REVERSED on 2026-09-03, in parity with the claude shim (section 5):
+# the operator asked for "among accounts where high session limits it must choose
+# randomly from ones where highest weekly limits", so a nearly-spent 5h bucket is the
+# FIRST cut and the 30-point weekly band ranks only what clears the gate. acct-01:
+# session 85 (past the gate), weekly 10; acct-02: session 20, weekly 70 -> acct-02.
+cxlj 10 85 85 > "$CX/acct-01/limits.json"
+cxlj 70 20 70 > "$CX/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: a session bucket past the gate is skipped while a fresher one exists (70w/20s over 10w/85s)" \
+  || t_fail "codex session gate" "the account with its 5h bucket at 85% was still selected"
+: > "$CX/selection.log"
+codex >/dev/null 2>&1
+grep -qE 'acct-02 weekly=70% session=20% band=30 band-count=1 session-gate=50 session-ok=1 pwd=' "$CX/selection.log" \
+  && t_ok "codex: the selection log carries session-gate=50 session-ok=1 when one of two clears" \
+  || t_fail "codex session gate log" "$(tail -1 "$CX/selection.log")"
+# Both sessions inside the gate: it has nothing to say and weekly decides as before.
+cxlj 10 45 45 > "$CX/acct-01/limits.json"
+cxlj 70 20 70 > "$CX/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "codex: with both sessions inside the gate weekly headroom decides (10w/45s over 70w/20s)" \
+  || t_fail "codex session gate no-op" "the gate changed a ranking where every candidate cleared it"
+# Nobody clears it: the gate compares, it never empties the pool — it steps aside.
+cxlj 10 85 85 > "$CX/acct-01/limits.json"
+cxlj 70 60 70 > "$CX/acct-02/limits.json"
+: > "$CX/selection.log"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "codex: with nobody inside the gate it steps aside and weekly ranks (10w/85s over 70w/60s)" \
+  || t_fail "codex session gate step-aside" "an empty gate emptied the pool instead of stepping aside"
+grep -qE 'acct-01 weekly=10% session=85% band=30 band-count=1 session-gate=50 session-ok=0 pwd=' "$CX/selection.log" \
+  && t_ok "codex: the selection log carries session-ok=0 when the gate steps aside" \
+  || t_fail "codex session gate log" "$(tail -1 "$CX/selection.log")"
+# The gate is a knob, like the band: 100 turns it off; garbage falls back to 50.
 cxlj 10 85 85 > "$CX/acct-01/limits.json"
 cxlj 70 20 70 > "$CX/acct-02/limits.json"
 all1=1
+for _ in $(seq 1 15); do
+  case "$(CODEX_MULTIACC_SESSION_GATE=100 codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "codex: CODEX_MULTIACC_SESSION_GATE=100 disables the gate" \
+  || t_fail "codex session gate off" "the gate still fired at 100"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(CODEX_MULTIACC_SESSION_GATE=abc codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: a non-numeric CODEX_MULTIACC_SESSION_GATE falls back to 50" \
+  || t_fail "codex session gate validation" "a garbage gate value changed the outcome"
+# Equal weekly usage: the GATE decides, never a tiebreak — strict band or default 30.
+cxlj 40 20 40 > "$CX/acct-01/limits.json"
+cxlj 40 80 80 > "$CX/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 15); do
+  case "$(CODEX_MULTIACC_HEADROOM_BAND=0 codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = "1" ] && t_ok "codex: strict mode: the session gate decides an exact weekly tie" \
+  || t_fail "codex session gate tie" "a weekly tie was not resolved by the session gate"
+all1=1
 for _ in $(seq 1 15); do
   case "$(codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
 done
-[ "$all1" = "1" ] && t_ok "codex: high session does NOT beat better weekly headroom" \
-  || t_fail "codex weekly-over-session" "ranked the account with less weekly headroom higher"
+[ "$all1" = "1" ] && t_ok "codex: the gate (not the band) removes the session-heavy half of a weekly tie" \
+  || t_fail "codex session gate tie" "the default band let the 80-point session account back in"
+
+# Inside the gate, session is NOT a tiebreaker any more: an exact weekly tie between two
+# gate-clearing accounts is a coin flip even in strict mode (it used to go to the lower
+# session, through the old weekly*1000+session score).
+cxlj 40 20 40 > "$CX/acct-01/limits.json"
+cxlj 40 45 45 > "$CX/acct-02/limits.json"
+hits1=0; hits2=0
+for _ in $(seq 1 20); do
+  case "$(CODEX_MULTIACC_HEADROOM_BAND=0 codex 2>&1)" in
+    *CFG=acct-01*) hits1=$((hits1+1)) ;;
+    *CFG=acct-02*) hits2=$((hits2+1)) ;;
+  esac
+done
+{ [ "$hits1" -gt 0 ] && [ "$hits2" -gt 0 ]; } \
+  && t_ok "codex: strict mode: session does not break an exact weekly tie inside the gate (acct-01=$hits1 acct-02=$hits2)" \
+  || t_fail "codex: session tiebreak removed" "acct-01=$hits1 acct-02=$hits2 (want both >0)"
+
+# Clearing the gate takes BOTH readings, as in pool-selection.v2: a fresh file with a
+# session reading but no weekly one must not become the sole gate-clearer and win the
+# all-gated tie over an account with a truthful weekly reading — not even with a
+# max_percent to fall back on (the shims used to rank on that; the policy never could).
+# (No writer produces such a file; this pins parity with lib/selector_policy.py.)
+printf '{"fetched_at":%s,"max_percent":10,"session_percent":10,"buckets":[]}' "$now" > "$CX/acct-01/limits.json"
+cxlj 20 80 80 > "$CX/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: a session reading without a weekly one never clears the gate" \
+  || t_fail "codex: gate needs both readings" "an unknown-weekly account beat a truthful weekly reading"
+
+# ...and the converse: a weekly reading without a session one is not "known" either — it
+# neither clears the gate nor ranks once the gate steps aside (10w/?s vs 70w/80s -> the
+# 70w account, as in pool-selection.v2, where quota_known needs both readings).
+printf '{"fetched_at":%s,"weekly_percent":10,"max_percent":10,"buckets":[]}' "$now" > "$CX/acct-01/limits.json"
+cxlj 70 80 80 > "$CX/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 15); do
+  case "$(codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: a weekly reading without a session one is unknown to both cuts" \
+  || t_fail "codex: known needs both readings" "a session-less weekly reading ranked as known"
 # equal scores spread load
 cxlj 10 10 10 > "$CX/acct-01/limits.json"
 cxlj 10 10 10 > "$CX/acct-02/limits.json"
@@ -3652,17 +3897,65 @@ c_n="$(printf '%s' "$c_distinct" | wc -w | tr -d ' ')"
 rm -rf "$CX/acct-09"
 rm -f "$CX/.last-pick"
 
-# ---- C6. all limited -> least-utilized fallback -------------------------------------
+# ---- C6. all limited -> the still-serving accounts go through the same two cuts, strict weekly --
 printf '%s\nbucket=7d percent=95 reason=limits\n' "$((now+3600))" > "$CX/acct-01/.limited"
 printf '%s\nbucket=7d percent=99 reason=limits\n' "$((now+3600))" > "$CX/acct-02/.limited"
 cxlj 95 10 95 > "$CX/acct-01/limits.json"
 cxlj 99 10 99 > "$CX/acct-02/limits.json"
 out="$(codex 2>&1)"
-check "codex: all-limited falls back to least utilized" "CFG=acct-01" "$out"
+check "codex: all-limited falls back to the still-serving account with the most weekly headroom" "CFG=acct-01" "$out"
 grep -q "all-limited fallback=acct-01" "$CX/selection.log" \
   && t_ok "codex: all-limited fallback logged" || t_fail "codex fallback log" "no all-limited line"
 rm -f "$CX"/acct-*/.limited "$CX"/acct-*/limits.json
 
+# The fallback applies the SAME two cuts (parity with the claude shim, section 9): an
+# account past the session gate yields to one inside it even with far better weekly.
+printf '%s\nbucket=7d percent=95 reason=limits\n' "$((now+3600))" > "$CX/acct-01/.limited"
+printf '%s\nbucket=7d percent=95 reason=limits\n' "$((now+3600))" > "$CX/acct-02/.limited"
+cxlj 10 85 85 > "$CX/acct-01/limits.json"
+cxlj 70 20 70 > "$CX/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 12); do
+  case "$(codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: the all-limited fallback applies the session gate before strict weekly (70w/20s over 10w/85s)" \
+  || t_fail "codex fallback session gate" "the fallback handed out the account past the session gate"
+grep -q "all-limited fallback=acct-02 weekly=70%" "$CX/selection.log" \
+  && t_ok "codex: the fallback line names the gated pick" || t_fail "codex fallback gate log" "$(tail -1 "$CX/selection.log")"
+rm -f "$CX"/acct-*/.limited "$CX"/acct-*/limits.json
+
+# ---- C6b. the fallback tells "still serving" from "rejected right now" ----------------
+# Ported from the claude shim (2026-08-29) when the session gate reached the fallback.
+# acct-01: 7d window at 99% — worse headroom, but still answering. acct-02: 5h window at
+# 100% — far better weekly (7%), but every request bounces until the reset.
+printf '%s\nbucket=7d percent=99 marked_at=x reason=limits\n' "$((now+3600))" > "$CX/acct-01/.limited"
+printf '%s\nbucket=5h percent=100 marked_at=x reason=limits\n' "$((now+600))" > "$CX/acct-02/.limited"
+cxlj 99 10 99 > "$CX/acct-01/limits.json"
+cxlj 7 100 100 > "$CX/acct-02/limits.json"
+out="$(codex 2>&1)"
+check "codex: a still-serving limited account beats an exhausted one with more headroom" "CFG=acct-01" "$out"
+# The codex-review case (2026-09-04): the exhausted account is the only one INSIDE the
+# session gate; the gate must not resurrect it over a still-serving account outside it.
+printf '%s\nbucket=7d percent=100 marked_at=x reason=limits\n' "$((now+3600))" > "$CX/acct-01/.limited"
+printf '%s\nbucket=7d percent=95 marked_at=x reason=limits\n' "$((now+3600))" > "$CX/acct-02/.limited"
+cxlj 100 20 100 > "$CX/acct-01/limits.json"
+cxlj 95 85 95 > "$CX/acct-02/limits.json"
+out="$(codex 2>&1)"
+check "codex: an exhausted account inside the gate never beats a still-serving one outside it" "CFG=acct-02" "$out"
+# A real client rejection (a 429 the server sent) is exhausted whatever percent says.
+printf '%s\nbucket=client:5h percent=95 marked_at=x reason=client-rate-limit\n' "$((now+600))" > "$CX/acct-01/.limited"
+cxlj 95 10 95 > "$CX/acct-01/limits.json"
+out="$(codex 2>&1)"
+check "codex: a client-rejected account is not the fallback while another still serves" "CFG=acct-02" "$out"
+# Every account exhausted RIGHT NOW: hand out the one that unblocks first.
+printf '%s\nbucket=5h percent=100 marked_at=x reason=limits\n' "$((now+7200))" > "$CX/acct-01/.limited"
+printf '%s\nbucket=5h percent=100 marked_at=x reason=limits\n' "$((now+600))" > "$CX/acct-02/.limited"
+out="$(codex 2>&1)"
+check "codex: all exhausted: the soonest reset is handed out" "CFG=acct-02" "$out"
+grep -q "all-exhausted resets_in=" "$CX/selection.log" \
+  && t_ok "codex: the all-exhausted pick is logged with its reset" || t_fail "codex all-exhausted log" "no line"
+rm -f "$CX"/acct-*/.limited "$CX"/acct-*/limits.json
+
 # ---- C7. dead logins: .expired excludes, heals on newer credential ------------------
 printf '%s\nreason=refresh-denied-http-400 marked_at=t detail=x\n' "$now" > "$CX/acct-01/.expired"
 all2=1
@@ -3682,6 +3975,9 @@ mk_cx_auth "$CX/acct-01/auth.json" a@cx "$FUTURE_EXP"
 out="$(CODEX_SHIM_SELECT=random codex 2>&1)"
 [ ! -f "$CX/acct-01/.expired" ] && t_ok "codex: newer auth.json clears a credential park" \
   || t_fail "codex park heal" ".expired survived a newer credential"
+grep -qE 'band=30 band-count=[0-9]+ session-gate=off session-ok=[0-9]+ pwd=' "$CX/selection.log" \
+  && t_ok "codex: random mode logs session-gate=off instead of a cut it never made" \
+  || t_fail "codex random mode gate log" "$(tail -1 "$CX/selection.log")"
 # an org-blocked park survives a newer credential (policy, not credential)
 printf '%s\nreason=org-blocked marked_at=t detail=x\n' "$now" > "$CX/acct-01/.expired"
 sleep 1