claude-multiacc 2.0.20 → 2.0.22

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 918 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,
-   form a **30-percentage-point weekly-headroom band** around the account with the most
-   remaining headroom (see below). The pool **rotates away from the account it just handed
+   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_HEADROOM_BAND=0` restores strict
-   best-headroom selection; `CLAUDE_SHIM_SELECT=random` uses the whole eligible pool.
-5. If every account is limit-excluded → the highest-headroom *authenticable* account
-   anyway + a warning in `selection.log` (degraded beats down: the 100% rule).
+   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,13 +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) to form the 30-point band. Accounts
-inside that band are deliberately treated as peers and spread randomly; with a zero-width
-band the self-healing session bucket is the tiebreaker. An account at 10% weekly remains
-protected from one at 70% weekly because the latter is outside the band. (`score = weekly%
-× 1000 + session%` in strict mode, 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.
 
@@ -151,6 +177,22 @@ buckets keep being tracked and the ≥90% rule keeps working. Unparseable entrie
 skipped, an all-legacy payload falls back to `five_hour`/`seven_day`, and a payload the
 code cannot read at all degrades that one account (fail open), never the run.
 
+**A 0% bucket with no reset window is no data, not an empty account.** Real usage always
+carries the window it resets in, so `percent: 0` with a null `resets_at` is the endpoint
+declining to answer — and taking it at face value put two weekly-exhausted accounts at the
+top of the ranking for 31 of ~60 picks on 2026-09-04. Only *informative* buckets (percent
+above 0, or a parseable reset time) are aggregated, **per signal**: `weekly_percent` is the
+peak over informative *weekly* buckets, `session_percent` over informative *session* ones,
+and each is simply omitted when its own group has nothing informative in it — a weekly
+figure is never borrowed from the session bucket. An account with no informative bucket at
+all gets a `limits.json` with none of `max_percent`/`weekly_percent`/`session_percent`,
+marked `"no_data": true`. Either way the account ranks **unknown** — selection needs BOTH
+readings, so a half-filled document is as unknown as an empty one: never the band leader,
+never past the session gate, never able to clear a marker, and a pool made only of them
+logs `ranking=BLIND` instead of quietly tying every account. Accounts that really are idle
+are untouched: 0% with a real reset window is informative and still ranks as empty, and one
+blank per-model bucket beside real ones leaves the real ones in charge.
+
 Telemetry failures never block work: no fresh data ⇒ account treated as available. The
 endpoint rate-limits per account, so the refresher skips accounts fetched in the last 4 min
 and backs off on **every** non-2xx, not just a 429 — honoring `Retry-After`, and parking
@@ -248,8 +290,20 @@ wrongly parked account is worse than a missed limit:
 
 The resulting marker is tagged `reason=client-rate-limit` and outlives a clean telemetry
 pass while its window is still open — first-hand evidence beats a usage payload that
-disagrees. Cost is bounded: the three newest sessions per account, a tail read rather than
-a whole transcript, and a clean result memoized for 20s
+disagrees. A **weekly** rejection is absolute: nothing — neither a shim invocation nor the
+scheduled `limits` pass — retires it before its reset epoch, since a weekly bucket cannot
+fall from a server-proven 100% back under the threshold inside that window. Claude names
+that bucket from the API's own type (`bucket=client:seven_day`); codex has no such name in
+its rollout files, only `primary`/`secondary` keys whose meaning moves, so it labels the
+marker from the window itself — `window_minutes >= 1440` ⇒ `client:7d`, a shorter window ⇒
+`client:5h`, and a window with no `window_minutes` at all stays `client:<key>` and remains
+clearable (fail open, bounded by its own reset). A five-hour marker can
+still be retired by telemetry fetched well after it
+(`CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY`, 300s), which is what keeps a fresh account
+from being stranded by an old session limit — before 2026-09-04 that carve-out also let
+fake-zero telemetry retire weekly markers, re-admitting an exhausted account six times a
+day. Cost is bounded: the three newest sessions per account, a tail read rather than a whole
+transcript, and a clean result memoized for 20s
 (`CLAUDE_MULTIACC_CLIENT_SCAN_TTL`), which on a three-account pool of large live
 transcripts is ~2 ms per run amortized.
 
@@ -286,8 +340,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 within the 30-point headroom band > 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.
@@ -274,7 +276,7 @@ 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
+  local fetched peak delay marked mk cutoff ck newer=0 bucket
   # 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
@@ -282,7 +284,28 @@ client_marker_recovered() { # $1 account dir, $2 marker
   # 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
+    # ...but a WEEKLY rejection is stronger than any telemetry until its own reset.
+    # Line 2 carries bucket=client:<type> (five_hour, seven_day, seven_day_opus, …).
+    # A seven-day window only refills on its multi-day reset, so it cannot have fallen
+    # from the server-proven 100% that wrote this marker to under the threshold while
+    # the window is still open: a reading that says otherwise is wrong by construction.
+    # 2026-09-04: acct-13/acct-14 were served fake-zero telemetry (every bucket
+    # percent 0, resets_at null), which read as 0% here and deleted their truthful
+    # client:seven_day markers ~6x/day each; an interactive session was handed both
+    # accounts in a row and was rejected by each with "You've hit your weekly limit".
+    # five_hour/session markers keep clearing exactly as before — that window self-heals
+    # within hours, which is why #22 (2026-09-03) had to clear it.
+    bucket="$(sed -n 2p "$2" 2>/dev/null)"
+    case "$bucket" in
+      *bucket=*) bucket="${bucket#*bucket=}"; bucket="${bucket%% *}" ;;
+      *) bucket="" ;;
+    esac
+    case "$(sel_lc "$bucket")" in *seven_day*|*7d*|*weekly*) return 1 ;; esac
     fetched="$(telem_fetched_at "$1" 2>/dev/null || echo 0)"
+    # Defaulting peak to 100 when the reading is missing/stale is the second half of the
+    # same rule: an UNINFORMATIVE reading must never clear a marker. It is what keeps a
+    # no_data account (2026-09-04: all-zero buckets with no reset windows write no
+    # max_percent at all) from unparking itself.
     peak="$(cutoff_field "$1" max_percent 2>/dev/null || echo 100)"
     delay="${CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY:-300}"
     num_ok "$delay" || delay=300
@@ -409,12 +432,39 @@ stale_weekly() { # $1 = acct dir
   limits_field "$1" weekly_percent
 }
 
-# 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.
+# TRUE when this account contributes nothing to ranking: no in-window telemetry, or an
+# in-window document that is not a COMPLETE reading. 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.
+# A fresh timestamp is not the same thing as a usable reading: since 2026-09-04 the
+# writer refuses to invent percentages from all-zero buckets with no reset window and
+# writes `no_data` instead, so such a document is current, well-formed, and ranks
+# nothing. Judging blindness on fetched_at alone called a pool of those "fresh" while
+# every account read as unknown and selection was in fact a coin flip.
+# BOTH fields are required, exactly as pick_best's "known" rule requires them (and
+# pool-selection.v2's quota_known): the same 2026-09-04 writer change also emits
+# one-signal documents per signal (weekly-only when no session bucket is informative,
+# and the converse), and an EITHER test called a pool of those sighted while pick_best
+# read every one of them as unknown and tied the whole pool — the coin flip again, this
+# time with no ranking=BLIND line and a status saying "fresh". The degraded path takes
+# one more guard for the same reason (assess_telemetry): a reading counts toward
+# DEGRADED only when it is genuinely OUT of the ranking window — degraded exists for an
+# outage, and a FRESH weekly-only document must not smuggle the very reading the
+# quota_known rule just refused back in as "old truth" (codex review, 2026-09-04).
+# A no_data document (no weekly_percent, no horizon) stays un-degradable either way.
+# Asked through limits_field, the SAME parser rank_weekly_of/rank_session_of use, so
+# this can never disagree with them about what "known" means. Both calls only ever run
+# for a blind-looking account (assess_telemetry stops at the first ranking one).
+# TELEM_FRESH_UNUSABLE is set as a side effect for the operator warning: the pool is
+# then blind with CURRENT data, which is a different fault (and a different fix) from
+# telemetry that merely went stale. Set here because the window test is already paid
+# for; this file is deliberately fork-frugal (see sessions_owned).
+TELEM_FRESH_UNUSABLE=0
 telem_blind() { # $1 = acct dir
-  ! within_window "$1" "$STALE_AFTER"
+  within_window "$1" "$STALE_AFTER" || return 0
+  limits_field "$1" weekly_percent >/dev/null 2>&1 || { TELEM_FRESH_UNUSABLE=1; return 0; }
+  limits_field "$1" session_percent >/dev/null 2>&1 || { TELEM_FRESH_UNUSABLE=1; return 0; }
+  return 1
 }
 
 # Human age for the warning line: seconds -> "3h" / "11d". Never fails.
@@ -425,36 +475,52 @@ 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
-  fi
-  s="$(fresh_field "$1" session_percent)" || s=100
-  printf '%s\n' $((w * 1000 + s))
-}
 
-# The direct shims use the same 30-point headroom band as pool-selection.v2. Strict
-# best-headroom selection burned one account to its limit while equally healthy
-# neighbours idled. A caller can set 0 to restore strict ranking.
+# 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)" || w="$(fresh_field "$1" max_percent)"; then
+  if w="$(fresh_field "$1" weekly_percent)"; then
     printf '%s\n' "$w"
     return 0
   fi
@@ -462,6 +528,13 @@ rank_weekly_of() { # $1 = acct dir -> comparable weekly use, or fail when unknow
   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=…
 # percent=… … reason=…"). All tolerant: an unreadable or bare marker answers
 # "unknown", never an error — these feed the all-limited fallback only.
@@ -1176,45 +1249,71 @@ 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 w avoid best="" bestv=1000000 bestw=101 ceiling=100 ties=0 i n match
-  local cand=() score=() weekly=() known=() pool=()
+  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")")
-    if w="$(rank_weekly_of "$d")"; then weekly+=("$w"); known+=(1)
-    else weekly+=(100); known+=(0); fi
+    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. (The writers DO
+    # emit one-signal documents — per-signal informative aggregation, 2026-09-04 — and
+    # such a document is exactly as unknown here as an empty one; parity with
+    # lib/selector_policy.py's quota_known.)
+    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]}"
-    [ "${known[$i]}" = 1 ] && [ "${weekly[$i]}" -lt "$bestw" ] && bestw="${weekly[$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
-  ceiling=$((bestw + HEADROOM_BAND)); [ "$ceiling" -gt 100 ] && ceiling=100
+  band="$HEADROOM_BAND"
+  [ "$PICK_STRICT" = 1 ] && band=0
+  ceiling=$((bestw + band)); [ "$ceiling" -gt 100 ] && ceiling=100
   i=0
   while [ "$i" -lt "$n" ]; do
-    match=0
-    if [ "$PICK_STRICT" = 0 ] && [ "$HEADROOM_BAND" -gt 0 ] && [ "$bestw" -le 100 ]; then
-      [ "${known[$i]}" = 1 ] && [ "${weekly[$i]}" -le "$ceiling" ] && match=1
-    else
-      [ "${score[$i]}" -eq "$bestv" ] && match=1
+    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
-    [ "$match" = 1 ] && pool+=("$i")
     i=$((i + 1))
   done
   PICK_BAND_COUNT=${#pool[@]}
-  # Reservoir-sample inside the band, skipping the account just handed out.
+  # Reservoir-sample the peers, skipping the account just handed out.
   for i in "${pool[@]}"; do
     if [ "${cand[$i]##*/}" != "$avoid" ]; then
       ties=$((ties + 1))
@@ -1228,15 +1327,15 @@ pick_best() { # args: candidate dirs
     done
   fi
   PICK_DIR="$best"
-  PICK_SCORE="$(sel_score_of "$best")"
 }
 
 # 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
@@ -1245,6 +1344,9 @@ degraded=0        # 1 = blind, but every candidate had a stale reading still wor
 assess_telemetry() { # args: the dirs actually being chosen between
   local d f n=0 stale_ok=0
   blind=1; blind_age=0; degraded=0
+  # Re-armed per assessment: the fallback path assesses a second candidate set, and a
+  # verdict from the first one must not colour the warning printed for the second.
+  TELEM_FRESH_UNUSABLE=0
   for d in "$@"; do
     n=$((n + 1))
     if ! telem_blind "$d"; then blind=0; return 0; fi
@@ -1253,13 +1355,21 @@ assess_telemetry() { # args: the dirs actually being chosen between
     # never fetched at all must not make the pool look older than it is.
     [ "$f" -gt 0 ] && { [ "$blind_age" -eq 0 ] || [ $((now - f)) -lt "$blind_age" ]; } \
       && blind_age=$((now - f))
-    stale_weekly "$d" >/dev/null && stale_ok=$((stale_ok + 1))
+    # Only a reading that is genuinely OUT of the ranking window may count toward
+    # DEGRADED: degraded exists for an outage ("nothing fresh anywhere, rank on old
+    # truths"), not for a fresh document that simply lacks a signal. A fresh
+    # weekly-only file already read as blind above (one-signal is unknown, 2026-09-04);
+    # letting its still-in-window weekly enable degraded would rank the pool on the
+    # very reading the two-cut rule just refused (codex review, 2026-09-04).
+    if ! within_window "$d" "$STALE_AFTER"; then
+      stale_weekly "$d" >/dev/null && stale_ok=$((stale_ok + 1))
+    fi
   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
 }
@@ -1273,6 +1383,8 @@ if [ "${#eligible[@]}" -gt 0 ]; then
   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
@@ -1404,10 +1516,12 @@ if [ "$blind" = 1 ]; then
   if [ "$degraded" = 1 ]; then
     sel_log "$acct weekly=$(stale_weekly "$pick" || echo '?')% session=?%" \
       "ranking=DEGRADED telemetry-age=${blind_age}s band=${HEADROOM_BAND}" \
-      "band-count=${PICK_BAND_COUNT} pwd=$PWD"
+      "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" \
-      "band=${HEADROOM_BAND} band-count=${PICK_BAND_COUNT} pwd=$PWD"
+      "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.
@@ -1417,9 +1531,21 @@ if [ "$blind" = 1 ]; then
     [ -f "$n" ] && last="$(file_mtime "$n")"
     if [ $((now - last)) -gt 3600 ]; then
       : 2>/dev/null > "$n" || true
+      # Three faults, three fixes, and telling them apart is the whole point of this
+      # line. Telemetry that went STALE is fixed by fetching again (and, if that keeps
+      # failing, by an OAuth login). Telemetry that arrived CURRENT and said nothing
+      # rankable — a 2026-09-04 no_data document, or a one-signal one — is not stale at
+      # all: refetching returns the same emptiness and a re-login fixes nothing, so
+      # advising one sends the operator down the wrong path (E4, 2026-09-04). The state
+      # is already known here: telem_blind sets TELEM_FRESH_UNUSABLE while testing the
+      # window it had to test anyway.
+      # (degraded && FRESH_UNUSABLE cannot happen: a fresh-but-unusable candidate is
+      # not counted by assess_telemetry, and degraded is all-or-nothing.)
       if [ "$degraded" = 1 ]; then
         printf 'claude-multiacc: usage telemetry is %s old — ranking on the last readings that are still valid, not on current usage. Fix: claude-accounts limits --force, then claude-accounts status\n' \
           "$(age_human "$blind_age")" >&2
+      elif [ "$TELEM_FRESH_UNUSABLE" = 1 ]; then
+        printf 'claude-multiacc: usage telemetry is CURRENT but carries no usable reading for any account (the endpoint answered with no percentages, or only half of them) — selection is running blind (random, not by headroom). Refetching and re-logging in will not change it: claude-accounts status\n' >&2
       elif [ "$blind_age" -gt 0 ]; then
         printf 'claude-multiacc: usage telemetry is %s old for EVERY account and too old to mean anything — selection is running blind (random, not by headroom). Fix: claude-accounts limits --force, then claude-accounts status\n' \
           "$(age_human "$blind_age")" >&2
@@ -1431,7 +1557,8 @@ if [ "$blind" = 1 ]; then
 else
   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} pwd=$PWD"
+    "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