claude-multiacc 2.0.19 → 2.0.21

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"
 }
@@ -331,28 +331,160 @@ done
 [ "$all2" = "1" ] && t_ok "picks the highest weekly-headroom account (weekly 20 over 80)" \
   || t_fail "headroom selection" "picked the more-utilized account"
 
-# 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 default 30-point band prevents strict headroom ranking from burning one account
+# to zero while its near-peers idle. Both boundaries participate; 31 points does not.
+lj 0 10 10 > "$ACC/acct-01/limits.json"
+lj 30 10 30 > "$ACC/acct-02/limits.json"
+hits1=0; hits2=0
+for _ in $(seq 1 20); do
+  case "$(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 "30-point headroom band spreads direct Claude launches (acct-01=$hits1 acct-02=$hits2)" \
+  || t_fail "Claude headroom band spread" "acct-01=$hits1 acct-02=$hits2"
+lj 31 10 31 > "$ACC/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 10); do
+  case "$(claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = 1 ] && t_ok "an account 31 points behind stays outside the Claude band" \
+  || t_fail "Claude headroom band boundary" "the 31-point account was selected"
+lj 20 10 20 > "$ACC/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 10); do
+  case "$(CLAUDE_MULTIACC_HEADROOM_BAND=0 claude 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+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, 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 "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"
+
+# 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 "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 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 => session breaks the tie toward the account with more session headroom
+# 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: 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 "equal weekly: lower session wins the tiebreak" \
-  || t_fail "session tiebreak" "did not use session to break a weekly tie"
+[ "$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"
@@ -380,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"
@@ -449,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
@@ -483,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
@@ -688,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"
@@ -1036,7 +1190,8 @@ mkclientlimit() { # mkclientlimit <acct dir> <session id> <resetsAt> [rejection
 }
 SID1="81bf8b20-013f-4414-8878-e0289bec9ad0"
 RESET1=$(( $(date +%s) + 1800 ))
-mkclientlimit "$ACC/acct-01" "$SID1" "$RESET1"
+REJECTED1="$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"
+mkclientlimit "$ACC/acct-01" "$SID1" "$RESET1" "$REJECTED1"
 all2=1
 for _ in $(seq 1 12); do
   case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
@@ -1048,6 +1203,9 @@ first="$(head -1 "$ACC/acct-01/.limited" 2>/dev/null)"
   || t_fail "client marker reset" "want $RESET1, got '${first:-<none>}'"
 grep -q 'reason=client-rate-limit' "$ACC/acct-01/.limited" 2>/dev/null \
   && t_ok "marker is tagged client-rate-limit" || t_fail "client marker reason" "$(cat "$ACC/acct-01/.limited" 2>/dev/null)"
+grep -q "marked_at=$REJECTED1" "$ACC/acct-01/.limited" 2>/dev/null \
+  && t_ok "client marker preserves the rejection timestamp" \
+  || t_fail "client marker timestamp" "$(cat "$ACC/acct-01/.limited" 2>/dev/null)"
 out="$(CLAUDE_ACCOUNT=acct-01 claude 2>&1)"
 check "explicit pin still wins over a client-reported limit" "CFG=acct-01" "$out"
 
@@ -1055,6 +1213,25 @@ check "explicit pin still wins over a client-reported limit" "CFG=acct-01" "$out
 CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-mid.json" claude-accounts limits --quiet
 [ -f "$ACC/acct-01/.limited" ] && t_ok "client-rate-limit marker survives a clean limits refresh" \
   || t_fail "client marker vs limits" "marker was cleared while the window was still open"
+# A later successful usage read under the threshold supersedes the client marker. The
+# live pool had five accounts at 0-3% hidden behind days-old client markers, leaving one
+# nominally-empty (but actually rejected) account to receive every direct launch.
+# A fleet sync refreshes the file's mtime, so recovery must use its semantic timestamp.
+{ head -1 "$ACC/acct-01/.limited"; \
+  sed 's/marked_at=[^ ]*/marked_at=2020-01-01T00:00:00Z/' "$ACC/acct-01/.limited" | tail -1; \
+} > "$ACC/acct-01/.limited.tmp"
+mv "$ACC/acct-01/.limited.tmp" "$ACC/acct-01/.limited"
+CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-mid.json" claude-accounts limits --force --quiet
+[ ! -f "$ACC/acct-01/.limited" ] \
+  && t_ok "newer low telemetry clears an old client-rate-limit marker" \
+  || t_fail "old client marker vs limits" "marker survived confirmed recovery"
+[ -f "$ACC/acct-01/.client-limit-cleared" ] \
+  && t_ok "confirmed client-limit recovery records a transcript watermark" \
+  || t_fail "client recovery watermark" "watermark missing"
+claude >/dev/null 2>&1
+[ ! -f "$ACC/acct-01/.limited" ] \
+  && t_ok "an old transcript cannot recreate a telemetry-disproved marker" \
+  || t_fail "client recovery watermark" "old rejection recreated the marker"
 rm -f "$ACC/acct-01/.limited"
 
 # an ALREADY-ELAPSED rejection is history, not an exclusion
@@ -1386,7 +1563,9 @@ expected="$(cat "$WORK/stdin13")"
 [ "$out" = "$expected" ] && t_ok "stdin/stdout byte fidelity (-p pipe)" || t_fail "stdin fidelity" "got: $out"
 
 # ---- 14. selection log written ------------------------------------------------
-grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*acct-0[123] weekly=[0-9?]+% session=[0-9?]+% pwd=' "$ACC/selection.log" \
+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]+ 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" \
   && t_fail "selection.log has no secrets" "a token leaked into the log" \
@@ -1877,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 ----------
@@ -2356,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")"
@@ -2377,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 --------------------------------------------
@@ -2413,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")"
@@ -2658,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"
@@ -3292,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"
@@ -3302,15 +3498,139 @@ for _ in $(seq 1 15); do
 done
 [ "$all2" = "1" ] && t_ok "codex: picks the highest weekly-headroom account" \
   || t_fail "codex headroom selection" "picked the more-utilized account"
-# high session must NOT beat better weekly headroom
+# Keep direct-provider behavior aligned with pool-selection.v2: both accounts inside
+# the default 30-point band receive launches; a caller can set 0 for strict ranking.
+cxlj 0 10 10 > "$CX/acct-01/limits.json"
+cxlj 30 10 30 > "$CX/acct-02/limits.json"
+hits1=0; hits2=0
+for _ in $(seq 1 20); do
+  case "$(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: 30-point headroom band spreads launches (acct-01=$hits1 acct-02=$hits2)" \
+  || t_fail "codex headroom band spread" "acct-01=$hits1 acct-02=$hits2"
+cxlj 20 10 20 > "$CX/acct-02/limits.json"
+all1=1
+for _ in $(seq 1 10); do
+  case "$(CODEX_MULTIACC_HEADROOM_BAND=0 codex 2>&1)" in *CFG=acct-01*) ;; *) all1=0 ;; esac
+done
+[ "$all1" = 1 ] && t_ok "codex: headroom band 0 restores strict ranking" \
+  || t_fail "codex zero headroom band" "the runner-up was selected"
+# 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: 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: 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: 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"
@@ -3577,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
@@ -3607,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
@@ -3622,13 +3993,13 @@ codex >/dev/null 2>&1
   || t_fail "codex soft park" "an elapsed soft park still excluded the account"
 
 # ---- C8. exec auto-retry ------------------------------------------------------------
-# acct-01 gets the strictly better score so headroom selection deterministically
-# picks it FIRST; the scripted failure then forces the retry onto acct-02.
+# Strict mode makes acct-01's better score deterministic for these retry-path tests;
+# the scripted failure then forces the retry onto acct-02.
 cx_first_01() { cxlj 5 5 5 > "$CX/acct-01/limits.json"; cxlj 20 20 20 > "$CX/acct-02/limits.json"; }
 cx_first_01
 # rate limit: retry on the other account + self-expiring cooldown for the failed one
 echo "fail:acct-01" > "$FAKE_CTL2"
-out="$(codex exec "hello" < /dev/null 2>&1)"
+out="$(CODEX_MULTIACC_HEADROOM_BAND=0 codex exec "hello" < /dev/null 2>&1)"
 case "$out" in *CFG=acct-02*) t_ok "codex: exec retries a rate-limited account on another" ;;
   *) t_fail "codex retry" "did not land on acct-02: $out" ;; esac
 if [ -f "$CX/acct-01/.limited" ]; then
@@ -3642,7 +4013,7 @@ rm -f "$CX/acct-01/.limited" "$FAKE_CTL2"
 # auth failure parks (soft) instead of a cooldown
 cx_first_01
 echo "authfail:acct-01" > "$FAKE_CTL2"
-codex exec "hello" < /dev/null >/dev/null 2>&1
+CODEX_MULTIACC_HEADROOM_BAND=0 codex exec "hello" < /dev/null >/dev/null 2>&1
 if [ -f "$CX/acct-01/.expired" ]; then
   grep -q "reason=auth-error" "$CX/acct-01/.expired" && grep -q "soft_until=" "$CX/acct-01/.expired" \
     && t_ok "codex: auth failure parks the account with a soft stamp" \
@@ -3654,7 +4025,7 @@ rm -f "$CX/acct-01/.expired" "$FAKE_CTL2"
 # org-disabled failure parks as org-blocked
 cx_first_01
 echo "orgfail:acct-01" > "$FAKE_CTL2"
-codex exec "hello" < /dev/null >/dev/null 2>&1
+CODEX_MULTIACC_HEADROOM_BAND=0 codex exec "hello" < /dev/null >/dev/null 2>&1
 grep -q "reason=org-blocked" "$CX/acct-01/.expired" 2>/dev/null \
   && t_ok "codex: workspace-disabled failure parks as org-blocked" \
   || t_fail "codex org park from run" "marker: $(cat "$CX/acct-01/.expired" 2>/dev/null || echo none)"