claude-multiacc 2.0.19 → 2.0.21

package/CLAUDE_ACCS_TASK.md

@@ -128,11 +128,16 @@ MAC (source of truth)                      SERVER 138.197.36.107 (mirror)
 
 1. `CLAUDE_CONFIG_DIR` already set → pass straight through (scripts can pin).
 2. `CLAUDE_ACCOUNT=acct-03` set → use that account (even if limit-marked — explicit wins).
-3. Else pick uniformly at random among accounts with valid auth
-   (`.credentials.json` on Mac; `server.token` on server → also exports
-   `CLAUDE_CODE_OAUTH_TOKEN`) **that are not limit-marked** (no `.limited` marker).
-   If EVERY account is marked, fall back to the least-utilized account and log a warning —
-   degraded service beats a hard failure (the 100% rule).
+3. Else, among accounts with valid auth (`.credentials.json` on Mac; `server.token` on
+   server → also exports `CLAUDE_CODE_OAUTH_TOKEN`) **that are not limit-marked** (no
+   `.limited` marker), select in two cuts (operator decision, 2026-09-03): first the
+   **session gate** — only accounts whose fresh 5h usage is at most
+   `CLAUDE_MULTIACC_SESSION_GATE` (default 50) stay in, unless nobody clears it; then the
+   **30-point weekly headroom band** — accounts within `CLAUDE_MULTIACC_HEADROOM_BAND`
+   points of the lowest weekly usage are peers, sampled at random with the previous pick
+   avoided. If EVERY account is marked, the still-serving ones go through the same two cuts
+   with a strict (exact-tie) band and one is handed out with a warning — degraded service
+   beats a hard failure (the 100% rule). README.md is the authoritative description.
 4. Append `timestamp account cwd` to `selection.log` (never prompt text); print NOTHING;
    `exec` the dynamically-resolved real binary — stdin/stdout/exit codes pass through
    byte-identically → `-p` pipe-safe.

package/README.md

@@ -16,7 +16,7 @@ completely independent — separate manifests, credentials, telemetry, and logs
 either provider can be used, re-authenticated, or emptied without touching the other.
 
 Tested on: macOS (bash 3.2, zsh, Claude Code 2.1.207+, Codex CLI 0.147) and Ubuntu 24.04
-(bash 5.2). The compatibility suite currently covers 645 sandboxed cases with no
+(bash 5.2). The compatibility suite currently covers 834 sandboxed cases with no
 network/quota use; the unified selector has its own adversarial contract suite.
 
 ## Unified selector for app-robot
@@ -32,8 +32,9 @@ claude-multiacc select --request-json - --response-json -
 
 The command reads one strict UTF-8 JSON request and emits one JSON response using
 the versioned `claude-multiacc/pool-selection.v2` protocol. It ranks the caller's
-locked candidate snapshot by usable weekly/session headroom and returns one concrete
-provider/account plus canonical snapshot and selection digests. `both` is a policy,
+locked candidate snapshot with the same two cuts as the shims — a session-headroom gate,
+then a band on weekly headroom — and returns one concrete provider/account plus canonical
+snapshot and selection digests. `both` is a policy,
 never an execution engine. The caller remains responsible for durable reservations,
 database locks, retries, and launching the selected CLI.
 Successful responses also carry `eligible_count` and `eligible_alternative_count`,
@@ -72,14 +73,26 @@ repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
 4. Among the accounts that remain valid **on this machine** (an OAuth login —
    `.credentials.json`, or a macOS Keychain item this session can open — or a
    `server.token` that passes its first inference preflight) and not limit-excluded,
-   pick the one with the **most remaining
-   headroom** (see below). On equal headroom the pool **rotates away from the account it
-   just handed out** and samples the rest at random — so quitting a session and starting
-   another one moves you along the pool, while a burst of parallel `claude -p` runs still
-   spreads (a strict "oldest first" order would send every member of the burst to the same
-   account). `CLAUDE_SHIM_SELECT=random` restores plain uniform-random selection.
-5. If every account is limit-excluded → the highest-headroom *authenticable* account
-   anyway + a warning in `selection.log` (degraded beats down: the 100% rule).
+   rank in two cuts (see below). **Session gate first:** keep only the accounts whose
+   5-hour bucket is known-fresh and at most 50% used — an account about to be rejected on
+   its session does not deserve a launch whatever its weekly headroom. If *nobody* clears
+   the gate it steps aside and every candidate stays in: the gate compares, it never
+   empties the pool. **Then the weekly band:** among the accounts that cleared the gate,
+   form a **30-percentage-point weekly-headroom band** around the one with the most
+   remaining weekly headroom. The pool **rotates away from the account it just handed
+   out** and samples the other accounts in that band at random. This prevents one nominally
+   emptiest account from taking every launch while near-peers idle, while accounts more than
+   30 points behind remain protected. `CLAUDE_MULTIACC_SESSION_GATE=100` turns the gate off
+   (default `50`); `CLAUDE_MULTIACC_HEADROOM_BAND=0` restores strict best-weekly selection
+   (default `30`); `CLAUDE_SHIM_SELECT=random` uses the whole eligible pool. Every pick
+   records both cuts in `selection.log`: `band=`/`band-count=` (the band width and how many
+   peers it held) and `session-gate=`/`session-ok=` (the gate and how many candidates
+   cleared it — `session-ok=0` means nobody did and the gate stepped aside; in
+   `CLAUDE_SHIM_SELECT=random` mode the line reads `session-gate=off`, because no cut was made).
+5. If every account is limit-excluded → the still-serving limited accounts (a bucket at
+   90–99%, not an exhausted one) go through the same two cuts — session gate, then strict
+   best-weekly — and one is handed out anyway, with an `all-limited fallback=` line in
+   `selection.log` (degraded beats down: the 100% rule).
 6. If nothing is usable at all → stock passthrough, with the reason in `selection.log`
    (and, on a terminal, one line naming the accounts to fix).
 
@@ -87,12 +100,26 @@ repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
 Fable request consumes at once: the 5-hour **session** bucket, the **weekly all-models**
 bucket, and the **weekly Fable** bucket. Anthropic's docs confirm these reset on very
 different horizons — the session bucket refills every ~5 hours, but weekly buckets only
-refill on the account's fixed weekly reset (days away). So the picker ranks primarily on
-**weekly headroom** (the peak of the durable buckets) and uses the self-healing session
-bucket only as a tiebreaker. An account sitting at 85% session / 10% weekly outranks one
-at 20% session / 70% weekly: the first only needs a few hours to recover, the second is
-burning headroom that's gone until next week. (`score = weekly% × 1000 + session%`,
-lowest wins.) **Exclusion** still fires on *any* bucket ≥ 90% — a full session bucket
+refill on the account's fixed weekly reset (days away). The two buckets therefore answer
+two different questions, and the picker asks them in that order (operator's decision,
+2026-09-03: *"among accounts where high session limits it must choose randomly from ones
+where highest weekly limits"*).
+
+- **Session is a gate, not a tiebreaker.** A candidate clears the gate when its 5-hour
+  usage is *known* (fresh telemetry) and at most `CLAUDE_MULTIACC_SESSION_GATE` points
+  spent — default `50`, `100` disables the gate. Unknown session usage never clears it.
+  An account that is 85% through its session is minutes from a rejection, so it waits
+  while anyone fresher is available; if nobody clears the gate, everybody is ranked.
+- **Weekly headroom picks the winner.** Among the accounts that cleared the gate, the
+  picker ranks on **weekly headroom** (the peak of the durable buckets) and treats
+  everything within `CLAUDE_MULTIACC_HEADROOM_BAND` points of the leader — default `30`,
+  `0` is strict best-weekly-only — as a peer, spreading launches over that band at
+  random. Session usage is **not** a tiebreaker inside the band: it acts only through
+  the gate. So an account at 10% weekly stays protected from one at 70% weekly, but
+  10% weekly with an 85%-spent session loses to 70% weekly with a 20% one, because the
+  first never reaches the band.
+
+**Exclusion** still fires on *any* bucket ≥ 90% — a full session bucket
 really does block right now — but that marker expires when the session resets, not days
 later.
 
@@ -285,8 +312,9 @@ above about the claude pool holds for the codex pool with these translations:
 | Anthropic OAuth usage and Fable buckets | Codex usage endpoint and per-model buckets |
 | `CLAUDE_*` pool controls | equivalent `CODEX_*` controls |
 
-Same selection rule (weekly headroom primary, session tiebreak, ≥90% any-bucket
-exclusion, equal scores rotate), same marker semantics (`.limited` cooldowns, `.expired` parks with
+Same selection rule (session gate first — `CODEX_MULTIACC_SESSION_GATE`, default 50 —
+then the 30-point weekly-headroom band with random spread, ≥90% any-bucket
+exclusion, peers rotate), same marker semantics (`.limited` cooldowns, `.expired` parks with
 credential/policy scoping and soft expiry), same fail-open guarantees, same sync
 safety guards. The `codex` shim engages the buffered auto-retry only for
 `codex exec` runs with finite stdin, exactly like `-p` on the claude side.

package/bin/claude

@@ -3,7 +3,9 @@
 # Every invocation runs under a randomly picked subscription account with limit headroom.
 # Self-contained on purpose: no sourcing, so a broken repo file can never break `claude`.
 # Selection: CLAUDE_CONFIG_DIR/CLAUDE_CODE_OAUTH_TOKEN passthrough > CLAUDE_ACCOUNT pin >
-# random among limit-eligible accounts > least-utilized fallback (degraded beats down).
+# two cuts — the 50-point session gate, then random within the 30-point weekly headroom
+# band (previous pick avoided) > all-limited fallback: the same two cuts over the
+# still-serving limited accounts, strict weekly (degraded beats down).
 # Accounts whose login is DEAD (expired refresh token, or a `.expired` marker from a
 # failed auth) are never selected — not even as the all-limited fallback — because they
 # fail every call outright; `claude-accounts expired` / `relogin` fix them.
@@ -271,6 +273,47 @@ scoped_over_tok() { # $1 = acct dir
   '
 }
 
+CLIENT_RECOVERY_FETCHED=0
+CLIENT_RECOVERY_PEAK=100
+client_marker_recovered() { # $1 account dir, $2 marker
+  local fetched peak delay marked mk cutoff ck newer=0
+  # A client rejection is stronger than an immediately-following usage read: that
+  # endpoint can lag or serve a cached bucket. It is not stronger forever. Once a
+  # successful, below-threshold reading was fetched at least five minutes after the
+  # marker, it is newer first-hand evidence that the account recovered (or that an
+  # old/shared transcript was attributed incorrectly). Keeping such a marker until its
+  # claimed reset stranded five 0%-usage accounts in the live pool on 2026-09-03.
+  if grep -q 'reason=client-rate-limit' "$2" 2>/dev/null; then
+    fetched="$(telem_fetched_at "$1" 2>/dev/null || echo 0)"
+    peak="$(cutoff_field "$1" max_percent 2>/dev/null || echo 100)"
+    delay="${CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY:-300}"
+    num_ok "$delay" || delay=300
+    [ "$delay" -gt 3600 ] && delay=3600
+    marked="$(LC_ALL=C sed -n 's/.*marked_at=\([^ ]*\).*/\1/p' "$2" 2>/dev/null | head -1)"
+    mk="$(iso_key "$marked")"
+    cutoff=0
+    if num_ok "$fetched" && [ "$fetched" -ge "$delay" ]; then
+      cutoff=$((fetched - delay))
+    fi
+    ck="$(iso_key "$(iso_of_epoch "$cutoff")")"
+    # Sync and atomic copies change mtimes, so prefer the marker's semantic timestamp.
+    # Old marker formats fall back to mtime until the next writer upgrades them.
+    if num_ok "$mk" && [ "${#mk}" -eq 14 ] && num_ok "$ck"; then
+      [ "$mk" -le "$ck" ] && newer=1
+    elif num_ok "$fetched" \
+      && [ "$(file_mtime "$2")" -le "$((fetched - delay))" ]; then
+      newer=1
+    fi
+    if [ "$newer" = 1 ] && num_ok "$peak" \
+      && [ "$peak" -lt "${CLAUDE_MULTIACC_THRESHOLD:-90}" ]; then
+      CLIENT_RECOVERY_FETCHED="$fetched"
+      CLIENT_RECOVERY_PEAK="$peak"
+      return 0
+    fi
+  fi
+  return 1
+}
+
 marker_active() { # true if $1/.limited is still in force; clears cleanly-expired markers
   local m="$1/.limited" reset="" tok
   [ -f "$m" ] || return 1
@@ -285,6 +328,14 @@ marker_active() { # true if $1/.limited is still in force; clears cleanly-expire
     rm -f "$m" 2>/dev/null
     return 1
   fi
+  if client_marker_recovered "$1" "$m"; then
+    printf '%s\n' "$CLIENT_RECOVERY_FETCHED" > "$1/.client-limit-cleared.$$" 2>/dev/null \
+      && mv -f "$1/.client-limit-cleared.$$" "$1/.client-limit-cleared" 2>/dev/null \
+      || rm -f "$1/.client-limit-cleared.$$" 2>/dev/null
+    rm -f "$m" 2>/dev/null
+    sel_log "$(basename "$1") client limit cleared by newer telemetry (${CLIENT_RECOVERY_PEAK}%)"
+    return 1
+  fi
   # A park scoped to ONE model does not stop a run that will use another one.
   tok="$(scoped_tok_of_marker "$1")"
   if [ -n "$tok" ] && ! scoped_blocks_run "$tok"; then
@@ -361,9 +412,9 @@ stale_weekly() { # $1 = acct dir
 }
 
 # TRUE when this account contributes nothing to ranking: no in-window telemetry at all.
-# When every candidate is blind, every score is the same neutral constant, pick_best
-# sees one enormous tie, and selection quietly becomes uniform random — the failure
-# this whole file exists to prevent.
+# When every candidate is blind, no candidate has a known reading, pick_best sees one
+# enormous tie, and selection quietly becomes uniform random — the failure this whole
+# file exists to prevent.
 telem_blind() { # $1 = acct dir
   ! within_window "$1" "$STALE_AFTER"
 }
@@ -376,24 +427,64 @@ age_human() { # $1 = seconds
   else printf '%dm\n' $((s / 60)); fi
 }
 
-# RANKING score — lower is better (more headroom). Weekly headroom dominates: a weekly
-# bucket only refills on the account's fixed weekly reset (days away), while the 5h
-# session bucket self-heals, so session is a mild tiebreaker only. (Anthropic's docs
-# confirm this reset asymmetry — an account whose only near-full bucket is the cheap
-# session one must NOT rank behind one burning durable weekly headroom.)
-#   score = weekly%*1000 + session%      weekly,session in [0,100]
-# Stale/unreadable telemetry ranks LAST (weekly 100, session 100), never "free" —
-# EXCEPT in a blind pool (SEL_DEGRADED=1), where a still-valid stale weekly reading is
-# used instead. Unknown data must never beat a truthful usage reading; when every
-# candidate is unknown, the equal worst-case scores still preserve fail-open selection.
+# RANKING — two cuts, no score, no tiebreaker (operator's ask, 2026-09-03: "among
+# accounts where high session limits it must choose randomly from ones where highest
+# weekly limits"). Session used to be a mild tiebreaker inside the score, which meant an
+# account whose 5h bucket was nearly spent — about to be rejected whatever its weekly
+# headroom — ranked exactly like a fresh one. It is now the FIRST cut instead:
+#   1. SESSION GATE  — candidates with a KNOWN session reading <= SESSION_GATE are the
+#      only ones ranked further. Unknown session never clears it. If NOBODY clears it the
+#      gate steps aside and everyone is ranked: the gate compares, it never empties the
+#      pool.
+#   2. WEEKLY BAND   — among those, the lowest KNOWN weekly usage leads and everything
+#      within HEADROOM_BAND points of it is a peer; peers are sampled at random with the
+#      previous pick skipped. Weekly still dominates because a weekly bucket only refills
+#      on the account's fixed weekly reset (days away) while the 5h session bucket
+#      self-heals — the gate is about "will this run be rejected now", not about headroom.
+# Stale/unreadable telemetry ranks LAST (unknown weekly, and unknown never clears the
+# gate), never "free" — EXCEPT in a blind pool (SEL_DEGRADED=1), where a still-valid stale
+# weekly reading is used instead. Unknown data must never beat a truthful usage reading;
+# when every candidate is unknown they tie, which preserves fail-open selection.
 SEL_DEGRADED=0
-sel_score_of() { # $1 = acct dir
-  local w s
-  if ! w="$(fresh_field "$1" weekly_percent)" && ! w="$(fresh_field "$1" max_percent)"; then
-    if [ "$SEL_DEGRADED" = 1 ]; then w="$(stale_weekly "$1")" || w=100; else w=100; fi
+
+# The direct shims use the same 30-point headroom band as pool-selection.v2, on WEEKLY
+# usage. Strict best-headroom selection burned one account to its limit while equally
+# healthy neighbours idled. A caller can set 0 to restore strict ranking (exact weekly
+# ties only). The operator confirmed on 2026-09-03 that the 30-point band stays.
+HEADROOM_BAND="${CLAUDE_MULTIACC_HEADROOM_BAND:-30}"
+case "$HEADROOM_BAND" in ''|*[!0-9]*|??????*) HEADROOM_BAND=30 ;; esac
+[ "$HEADROOM_BAND" -gt 100 ] && HEADROOM_BAND=100
+
+# The session gate: a candidate is "healthy enough to run now" when its KNOWN 5h usage is
+# at or under this many points. It runs BEFORE the weekly band, so a nearly-spent session
+# bucket takes an account out of contention however good its weekly headroom is. 100
+# disables the gate (every known-session account clears it).
+SESSION_GATE="${CLAUDE_MULTIACC_SESSION_GATE:-50}"
+case "$SESSION_GATE" in ''|*[!0-9]*|??????*) SESSION_GATE=50 ;; esac
+[ "$SESSION_GATE" -gt 100 ] && SESSION_GATE=100
+# What the selection log prints for the gate: "off" in random mode, where no gate ran —
+# the log must never claim a cut that was not made.
+SESSION_GATE_LOG="$SESSION_GATE"
+
+# weekly_percent ONLY. A reading without it is unknown here, exactly as it is unknown to
+# pool-selection.v2 (which never sees max_percent). The old max_percent fallback let a
+# weekly-less file rank — and, once the session gate existed, CLEAR the gate — on a number
+# that may well be the session bucket's own peak (codex review, 2026-09-04).
+rank_weekly_of() { # $1 = acct dir -> comparable weekly use, or fail when unknown
+  local w
+  if w="$(fresh_field "$1" weekly_percent)"; then
+    printf '%s\n' "$w"
+    return 0
   fi
-  s="$(fresh_field "$1" session_percent)" || s=100
-  printf '%s\n' $((w * 1000 + s))
+  [ "$SEL_DEGRADED" = 1 ] || return 1
+  stale_weekly "$1"
+}
+
+rank_session_of() { # $1 = acct dir -> fresh session use, or fail when unknown
+  # Deliberately fresh-only, with no stale/degraded fallback: an old 5h reading says
+  # nothing about a bucket that self-heals every five hours, and an unknown session must
+  # not clear the gate.
+  fresh_field "$1" session_percent
 }
 
 # The .limited marker's own fields (line 1: reset epoch; line 2: "bucket=…
@@ -621,14 +712,14 @@ sess_transcript() { # $1 acct dir, $2 session id
 }
 
 # Newest still-in-force rejection this account's own sessions recorded.
-# Prints "<reset-epoch> <rateLimitType>"; fails when there is none.
+# Prints "<reset-epoch> <rateLimitType> <rejection-ISO>"; fails when there is none.
 # This runs on EVERY invocation, so it is bounded on purpose: newest session first,
 # stop at the first in-force rejection, and never read more than QUOTA_SCAN_MAX_FILES
 # transcripts. Missing an older rejection costs nothing — a limit that is still in force
 # rejects the very next request too, and that lands in a newer transcript.
 client_limit_scan() { # $1 acct dir
   local idx="$1/.sessions-index" memo="$1/.client-scan" id p line r t read_n=0 i last=""
-  local ln claim ts ck ak ttl
+  local ln claim ts ck ak ttl cleared sk
   local ids=() claims=()
   [ "${CLAUDE_MULTIACC_CLIENT_LIMITS:-1}" = "0" ] && return 1
   [ -f "$idx" ] || return 1
@@ -672,12 +763,28 @@ client_limit_scan() { # $1 acct dir
       | tail -1)"
     [ -n "$line" ] || continue
     case "$line" in *'"status":"rejected"'*|*'"status": "rejected"'*) ;; *) continue ;; esac
+    # A later successful usage read below the threshold supersedes an older rejection.
+    # Without this watermark, clearing its marker achieved nothing: the next launch
+    # scanned the same transcript and recreated the same days-long park.
+    ts="$(printf '%s' "$line" | LC_ALL=C sed -n \
+      's/.*"timestamp"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+    ck="$(iso_key "$ts")"
+    cleared=""
+    [ -f "$1/.client-limit-cleared" ] \
+      && { IFS= read -r cleared < "$1/.client-limit-cleared" 2>/dev/null || cleared=""; }
+    if num_ok "$cleared"; then
+      sk="$(iso_key "$(iso_of_epoch "$cleared")")"
+      if num_ok "$ck" && num_ok "$sk"; then
+        [ "$ck" -le "$sk" ] && continue
+      elif [ "$(file_mtime "$p")" -le "$cleared" ]; then
+        continue
+      fi
+    fi
     # A rejection recorded BEFORE this account took the session over belongs to whoever
     # was running it then, not to us. Undatable => not attributed (fail open).
     if [ -n "$claim" ]; then
-      ts="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"timestamp"[[:space:]]*:[[:space:]]*"\([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[^"]*\)".*/\1/p')"
       [ -n "$ts" ] || continue
-      ck="$(iso_key "$ts")"; ak="$(iso_key "$claim")"
+      ak="$(iso_key "$claim")"
       num_ok "$ck" || continue
       num_ok "$ak" || continue
       [ "$ck" -lt "$ak" ] && continue
@@ -687,7 +794,7 @@ client_limit_scan() { # $1 acct dir
     num_ok "$r" || continue
     [ "$r" -gt "$now" ] || continue
     t="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"rateLimitType"[[:space:]]*:[[:space:]]*"\([A-Za-z0-9_.-]*\)".*/\1/p')"
-    printf '%s %s\n' "$r" "${t:-unknown}"
+    printf '%s %s %s\n' "$r" "${t:-unknown}" "${ts:--}"
     return 0
   done
   printf '%s\n' "$now" 2>/dev/null > "$memo.$$" \
@@ -749,8 +856,8 @@ mark_client_auth_dead() { # $1 acct dir
   fi
 }
 
-mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type
-  local m="$1/.limited" cur=""
+mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type, $4 rejection ISO
+  local m="$1/.limited" cur="" marked="$4" mk
   # Never shorten a marker that already reaches further out (a weekly park must
   # survive a 5h report), and never rewrite the same one on every invocation.
   if [ -f "$m" ]; then
@@ -758,9 +865,13 @@ mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type
     num_ok "$cur" || cur=0
     [ "$cur" -ge "$2" ] && return 0
   fi
+  mk="$(iso_key "$marked")"
+  if ! num_ok "$mk" || [ "${#mk}" -ne 14 ]; then
+    marked="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  fi
   {
     echo "$2"
-    echo "bucket=client:$3 percent=100 marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=client-rate-limit"
+    echo "bucket=client:$3 percent=100 marked_at=$marked reason=client-rate-limit"
   } 2>/dev/null > "$1/.limited.$$" \
     && mv -f "$1/.limited.$$" "$m" 2>/dev/null \
     || rm -f "$1/.limited.$$" 2>/dev/null || true
@@ -1023,7 +1134,11 @@ for d in "$ACC_ROOT"/acct-*; do
   # `claude-accounts status`, to a concurrent run in another terminal, and to sync.
   # The cost is bounded by the scan's own file budget and its clean-result memo.
   if lim="$(client_limit_scan "$d")"; then
-    mark_client_limit "$d" "${lim%% *}" "${lim##* }"
+    lim_reset="${lim%% *}"
+    lim_rest="${lim#* }"
+    lim_type="${lim_rest%% *}"
+    lim_marked="${lim_rest#* }"
+    mark_client_limit "$d" "$lim_reset" "$lim_type" "$lim_marked"
     continue
   fi
   over_threshold "$d" && continue
@@ -1086,58 +1201,91 @@ remember_pick() { # $1 acct dir — best effort. stderr is silenced BEFORE the r
   return 0
 }
 
-# Pick the account with the MOST headroom (lowest ranking score = most weekly headroom,
-# session as tiebreaker). Ties break randomly so equally-idle accounts still spread load.
-# Sets PICK_DIR/PICK_SCORE as globals — it must never touch "$@", which holds the
-# user's claude arguments.
+# Pick an account by the two-cut rule above: the session gate first, then random among
+# the peers inside the 30-point WEEKLY band, with the account handed out last time
+# skipped. No score and no tiebreaker — the operator asked for a random choice among the
+# best-weekly accounts (2026-09-03), so session only ever acts through the gate.
+# Sets PICK_DIR/PICK_BAND_COUNT/PICK_GATE_COUNT as globals — it must never touch "$@",
+# which holds the user's claude arguments.
 PICK_DIR=""
-PICK_SCORE=""
+PICK_BAND_COUNT=0
+PICK_GATE_COUNT=0
+PICK_STRICT=0
 pick_best() { # args: candidate dirs
-  local d avoid best="" bestv=1000000 ties=0 i n
-  local cand=() score=()
+  local d w s k sk avoid best="" bestw=101 band ceiling ties=0 i n
+  local cand=() weekly=() known=() gated=() pool=()
   avoid="$(last_pick_id)"
+  PICK_GATE_COUNT=0
   for d in "$@"; do
     cand+=("$d")
-    score+=("$(sel_score_of "$d")")
+    w="$(rank_weekly_of "$d")" && k=1 || k=0
+    s="$(rank_session_of "$d")" && sk=1 || sk=0
+    # "Known" takes BOTH readings — pool-selection.v2's quota_known rule. A weekly figure
+    # on its own neither ranks nor clears the gate, and a session figure on its own could
+    # otherwise be the sole gate-clearer and win the all-gated tie over an account whose
+    # truthful weekly reading merely failed the gate. The one exception is a DEGRADED pool
+    # (SEL_DEGRADED=1): nothing is fresh anywhere, the gate has necessarily stepped aside,
+    # and a still-valid stale weekly reading is the only truth there is. (Neither writer
+    # emits one field without the other; this is parity with lib/selector_policy.py.)
+    if [ "$k" = 1 ] && { [ "$sk" = 1 ] || [ "$SEL_DEGRADED" = 1 ]; }; then
+      weekly+=("$w"); known+=(1)
+    else
+      weekly+=(100); known+=(0)
+    fi
+    if [ "$k" = 1 ] && [ "$sk" = 1 ] && [ "$s" -le "$SESSION_GATE" ]; then
+      gated+=(1); PICK_GATE_COUNT=$((PICK_GATE_COUNT + 1))
+    else
+      gated+=(0)
+    fi
   done
   n=${#cand[@]}
   i=0
   while [ "$i" -lt "$n" ]; do
-    [ "${score[$i]}" -lt "$bestv" ] && bestv="${score[$i]}"
+    # Nobody clears the gate => everybody does: the gate compares, it never empties the pool.
+    [ "$PICK_GATE_COUNT" -eq 0 ] && gated[$i]=1
+    if [ "${gated[$i]}" = 1 ] && [ "${known[$i]}" = 1 ] && [ "${weekly[$i]}" -lt "$bestw" ]; then
+      bestw="${weekly[$i]}"
+    fi
     i=$((i + 1))
   done
-  # Reservoir-sample among the equally-best, skipping the account just handed out.
+  band="$HEADROOM_BAND"
+  [ "$PICK_STRICT" = 1 ] && band=0
+  ceiling=$((bestw + band)); [ "$ceiling" -gt 100 ] && ceiling=100
   i=0
   while [ "$i" -lt "$n" ]; do
-    if [ "${score[$i]}" -eq "$bestv" ] && [ "${cand[$i]##*/}" != "$avoid" ]; then
+    if [ "${gated[$i]}" = 1 ]; then
+      if [ "$bestw" -gt 100 ]; then
+        pool+=("$i")                       # no weekly reading anywhere: all gated tie
+      elif [ "${known[$i]}" = 1 ] && [ "${weekly[$i]}" -le "$ceiling" ]; then
+        pool+=("$i")
+      fi
+    fi
+    i=$((i + 1))
+  done
+  PICK_BAND_COUNT=${#pool[@]}
+  # Reservoir-sample the peers, skipping the account just handed out.
+  for i in "${pool[@]}"; do
+    if [ "${cand[$i]##*/}" != "$avoid" ]; then
       ties=$((ties + 1))
       [ $((RANDOM % ties)) -eq 0 ] && best="${cand[$i]}"
     fi
-    i=$((i + 1))
   done
   if [ -z "$best" ]; then
-    # The only account at the best score IS the one just used — degraded rotation beats
-    # refusing to pick (and in a two-account pool this is the other half of the
-    # alternation).
-    i=0
-    while [ "$i" -lt "$n" ]; do
-      if [ "${score[$i]}" -eq "$bestv" ]; then
-        ties=$((ties + 1))
-        [ $((RANDOM % ties)) -eq 0 ] && best="${cand[$i]}"
-      fi
-      i=$((i + 1))
+    for i in "${pool[@]}"; do
+      ties=$((ties + 1))
+      [ $((RANDOM % ties)) -eq 0 ] && best="${cand[$i]}"
     done
   fi
   PICK_DIR="$best"
-  PICK_SCORE="$bestv"
 }
 
 # Telemetry going stale is not a per-run detail, it is a pool-wide outage: with no
-# in-window data ANYWHERE every account scores the identical NEUTRAL value, the tie
-# spans the whole pool, and "pick the account with the most headroom" silently becomes
-# "pick any account at all". That is how a fresh session lands on the one account
-# already at 80% of its weekly limit while `claude-accounts status` still shows a
-# reassuring 2% from eleven days ago. It cost eleven days of blind picks once.
+# in-window data ANYWHERE every account reads as UNKNOWN — no weekly, and nothing that
+# can clear the session gate — so the tie spans the whole pool and "pick the account with
+# the most headroom" silently becomes "pick any account at all". That is how a fresh
+# session lands on the one account already at 80% of its weekly limit while
+# `claude-accounts status` still shows a reassuring 2% from eleven days ago. It cost
+# eleven days of blind picks once.
 # Two answers, and the order matters: rank on whatever old readings are still true
 # BEFORE picking, and say out loud which of the two happened.
 blind=1           # 1 = no candidate has in-window telemetry
@@ -1157,10 +1305,10 @@ assess_telemetry() { # args: the dirs actually being chosen between
     stale_weekly "$d" >/dev/null && stale_ok=$((stale_ok + 1))
   done
   # All or nothing. A candidate whose reading has no horizon — a limits.json written
-  # before this field existed, or one whose week has already turned — scores neutral
-  # 50, and 50 would beat a NEIGHBOUR's true-but-worse 70. Mixing the two makes the
-  # degraded ranking actively wrong, so it is only used when every candidate can be
-  # compared on the same footing.
+  # before this field existed, or one whose week has already turned — stays UNKNOWN even
+  # in degraded mode, so it would drop out of the band entirely while its neighbours rank
+  # on stale numbers. Mixing the two makes the degraded ranking actively wrong, so it is
+  # only used when every candidate can be compared on the same footing.
   [ "$n" -gt 0 ] && [ "$stale_ok" -eq "$n" ] && degraded=1
   return 0
 }
@@ -1173,6 +1321,9 @@ if [ "${#eligible[@]}" -gt 0 ]; then
   [ "$degraded" = 1 ] && SEL_DEGRADED=1
   if [ "${CLAUDE_SHIM_SELECT:-headroom}" = "random" ]; then
     PICK_DIR="${eligible[$((RANDOM % ${#eligible[@]}))]}"
+    PICK_BAND_COUNT=${#eligible[@]}
+    PICK_GATE_COUNT=${#eligible[@]}
+    SESSION_GATE_LOG=off
   else
     pick_best "${eligible[@]}"
   fi
@@ -1191,7 +1342,9 @@ else
   if [ "${#soft[@]}" -gt 0 ]; then
     assess_telemetry "${soft[@]}"
     [ "$degraded" = 1 ] && SEL_DEGRADED=1
+    PICK_STRICT=1
     pick_best "${soft[@]}"
+    PICK_STRICT=0
   else
     # Every account is exhausted RIGHT NOW: nothing serves, so hand out the one
     # that unblocks first — its rejection window is the shortest.
@@ -1300,9 +1453,14 @@ if [ "$blind" = 1 ]; then
   # DEGRADED still ranks, on old readings that remain true; BLIND cannot rank at all and
   # is a coin flip. Calling both of them "random" would send someone hunting the wrong bug.
   if [ "$degraded" = 1 ]; then
-    sel_log "$acct weekly=$(stale_weekly "$pick" || echo '?')% session=?% ranking=DEGRADED telemetry-age=${blind_age}s pwd=$PWD"
+    sel_log "$acct weekly=$(stale_weekly "$pick" || echo '?')% session=?%" \
+      "ranking=DEGRADED telemetry-age=${blind_age}s band=${HEADROOM_BAND}" \
+      "band-count=${PICK_BAND_COUNT} session-gate=${SESSION_GATE_LOG}" \
+      "session-ok=${PICK_GATE_COUNT} pwd=$PWD"
   else
-    sel_log "$acct weekly=?% session=?% ranking=BLIND telemetry-age=${blind_age}s pwd=$PWD"
+    sel_log "$acct weekly=?% session=?% ranking=BLIND telemetry-age=${blind_age}s" \
+      "band=${HEADROOM_BAND} band-count=${PICK_BAND_COUNT}" \
+      "session-gate=${SESSION_GATE_LOG} session-ok=${PICK_GATE_COUNT} pwd=$PWD"
   fi
   # Terminal only, at most hourly — a service-spawned `claude -p` must keep its stderr
   # byte-clean, and this is advice, never a failure.
@@ -1324,7 +1482,10 @@ if [ "$blind" = 1 ]; then
     fi
   fi
 else
-  sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')% session=$(fresh_field "$pick" session_percent || echo '?')% pwd=$PWD"
+  sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')%" \
+    "session=$(fresh_field "$pick" session_percent || echo '?')%" \
+    "band=${HEADROOM_BAND} band-count=${PICK_BAND_COUNT}" \
+    "session-gate=${SESSION_GATE_LOG} session-ok=${PICK_GATE_COUNT} pwd=$PWD"
 fi
 
 export CLAUDE_SHIM_ACTIVE=1