claude-multiacc 2.0.20 → 2.0.21

package/bin/codex

@@ -3,8 +3,10 @@
 # Every invocation runs under a randomly picked ChatGPT subscription account with limit
 # headroom. Self-contained on purpose: no sourcing, so a broken repo file can never
 # break `codex`.
-# Selection: CODEX_HOME passthrough > CODEX_ACCOUNT pin > random among limit-eligible
-# accounts in the 30-point headroom band > least-utilized fallback (degraded beats down).
+# Selection: CODEX_HOME passthrough > CODEX_ACCOUNT pin > random among the limit-eligible
+# accounts that clear the 50-point session gate and then sit in the 30-point weekly
+# headroom band > all-limited fallback: the same two cuts over the still-serving limited
+# accounts, strict weekly (degraded beats down).
 # Accounts whose login is DEAD (a `.expired` marker from a failed refresh/verify/run)
 # are never selected — not even as the all-limited fallback — because they fail every
 # call outright; `codex-accounts expired` / `relogin` fix them.
@@ -140,33 +142,101 @@ fresh_field() { # fresh_field <acct dir> <json key> -> integer if telemetry fres
   printf '%s\n' "$v"
 }
 
-# RANKING score — lower is better (more headroom). Weekly headroom dominates: a weekly
-# window only refills on its multi-day reset, while the ~5h window self-heals, so
-# session is a mild tiebreaker only (same reset asymmetry as the claude pool).
-#   score = weekly%*1000 + session%      weekly,session in [0,100]
-# Stale/unreadable telemetry ranks LAST (weekly 100, session 100), never "free".
-# Equal worst-case scores keep an entirely unknown pool selectable, but an unknown
-# account can never beat a candidate with truthful usage telemetry.
-sel_score_of() { # $1 = acct dir
-  local w s
-  w="$(fresh_field "$1" weekly_percent)" || w="$(fresh_field "$1" max_percent)" || w=100
-  s="$(fresh_field "$1" session_percent)" || s=100
-  printf '%s\n' $((w * 1000 + s))
-}
+# RANKING — TWO CUTS, in this order, then chance. The operator's ask (2026-09-03):
+# "among accounts where high session limits it must choose randomly from ones where
+# highest weekly limits."
+#   1. SESSION GATE (SESSION_GATE, default 50): a candidate clears the gate when its ~5h
+#      session usage is KNOWN and at or under the gate. When at least one candidate clears
+#      it, only those are ranked further — an account whose session bucket is nearly spent
+#      is about to be rejected whatever its weekly headroom is. When NOBODY clears it the
+#      gate steps aside and every candidate is ranked: the gate compares candidates, it
+#      never empties the pool.
+#   2. WEEKLY BAND (HEADROOM_BAND, default 30, kept at the operator's request): among the
+#      gated candidates the lowest KNOWN weekly usage leads, and every gated candidate
+#      within the band of it is a peer. Weekly dominates because a weekly window only
+#      refills on its multi-day reset while the ~5h window self-heals (same asymmetry as
+#      the claude pool) — which is exactly why session acts as the gate and is NOT a
+#      tiebreaker inside the band any more: the operator asked for a random choice among
+#      the best-weekly accounts.
+# Stale/unreadable telemetry never clears the gate and never enters the band — an unknown
+# account can never beat a candidate with truthful usage telemetry — but when NOTHING is
+# known the candidates all tie, which keeps an entirely blind pool selectable.
+# Band 0 (or the all-limited PICK_STRICT fallback) means exact weekly ties only; gate 100
+# turns the gate off.
 
 HEADROOM_BAND="${CODEX_MULTIACC_HEADROOM_BAND:-30}"
 case "$HEADROOM_BAND" in ''|*[!0-9]*|??????*) HEADROOM_BAND=30 ;; esac
 [ "$HEADROOM_BAND" -gt 100 ] && HEADROOM_BAND=100
-
+SESSION_GATE="${CODEX_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"
+# The codex shim has no DEGRADED ranking mode (the claude shim ranks on still-valid stale
+# weekly readings when nothing in its pool is fresh). The constant exists so pick_best
+# can stay byte-identical with bin/claude.
+SEL_DEGRADED=0
+
+# 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
   return 1
 }
 
+rank_session_of() { # $1 = acct dir -> fresh session use, or fail when unknown
+  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.
+limited_reset_of() { # $1 acct dir -> the marker's reset epoch, or 0 (unknown)
+  local m="$1/.limited" r=""
+  [ -f "$m" ] && { IFS= read -r r < "$m" 2>/dev/null || r=""; }
+  if num_ok "$r"; then printf '%s\n' "$r"; else printf '0\n'; fi
+}
+
+limited_percent_of() { # $1 acct dir -> the marked window's percent, or -1 (unknown)
+  local m="$1/.limited" line=""
+  [ -f "$m" ] && line="$(sed -n 2p "$m" 2>/dev/null)"
+  case "$line" in
+    *percent=*) line="${line#*percent=}"; line="${line%% *}" ;;
+    *) line="" ;;
+  esac
+  if num_ok "$line"; then printf '%s\n' "$line"; else printf '%s\n' "-1"; fi
+}
+
+# Rejected RIGHT NOW, not merely near the threshold: the marked window is exhausted
+# (100%), or the marker records a real client rejection (a 429 the server sent) or an
+# error cooldown. A window at 90-99% still answers requests — the difference the
+# all-limited fallback lives on, because "degraded service beats a hard failure" only
+# holds for an account that can actually serve. Same rule as the claude shim.
+limited_hard_blocked() { # $1 acct dir
+  local m="$1/.limited" line="" p
+  if [ -f "$m" ]; then
+    line="$(sed -n 2p "$m" 2>/dev/null)"
+    case "$line" in *reason=client-rate-limit*|*reason=error-cooldown*) return 0 ;; esac
+    p="$(limited_percent_of "$1")"
+    if [ "$p" -ge 0 ] 2>/dev/null; then
+      [ "$p" -ge 100 ]
+      return
+    fi
+    return 1
+  fi
+  # No marker (the over-threshold backstop put it in valid-but-not-eligible):
+  # fresh telemetry's peak decides; stale/unknown reads as still serving.
+  p="$(fresh_field "$1" max_percent)" || return 1
+  [ "$p" -ge 100 ]
+}
+
 # Backstop for a lost/failed marker write: fresh telemetry with ANY bucket at/over the
 # threshold excludes the account even if .limited is missing. Stale/unreadable => not
 # over (fail open — telemetry must never invent exclusions).
@@ -467,44 +537,67 @@ 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 codex arguments.
+# Two cuts, then chance: the session gate first, the weekly headroom band second, and a
+# random peer with the account just handed out avoided. Sets PICK_DIR / PICK_BAND_COUNT /
+# PICK_GATE_COUNT as globals — it must never touch "$@", which holds the user's codex
+# 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. (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]}"
-    [ "${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 the peers, skipping the account just handed out.
   for i in "${pool[@]}"; do
     if [ "${cand[$i]##*/}" != "$avoid" ]; then
       ties=$((ties + 1))
@@ -518,22 +611,64 @@ pick_best() { # args: candidate dirs
     done
   fi
   PICK_DIR="$best"
-  PICK_SCORE="$(sel_score_of "$best")"
 }
 
 if [ "${#eligible[@]}" -gt 0 ]; then
   if [ "${CODEX_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
 else
-  # Every account is limit-marked: degraded service beats a hard failure (100% rule).
-  PICK_STRICT=1
-  pick_best "${valid[@]}"
-  PICK_STRICT=0
-  sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(fresh_field "$PICK_DIR" weekly_percent || echo '?')%"
+  # Every account is limit-marked: degraded service beats a hard failure (100% rule) —
+  # but not every limited account is equally dead. A window at 90-99% still answers;
+  # one at 100% (or a real client 429) rejects every request until its reset. The claude
+  # shim learned this on 2026-08-29; the codex shim ranked the whole valid set on weekly
+  # headroom until the session gate reached the fallback, where an exhausted account
+  # that happened to clear the gate would beat a still-serving one that did not
+  # (codex review, 2026-09-04).
+  soft=()
+  hard=()
+  for d in "${valid[@]}"; do
+    if limited_hard_blocked "$d"; then hard+=("$d"); else soft+=("$d"); fi
+  done
+  if [ "${#soft[@]}" -gt 0 ]; then
+    PICK_STRICT=1
+    pick_best "${soft[@]}"
+    PICK_STRICT=0
+    sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(fresh_field "$PICK_DIR" weekly_percent || echo '?')%"
+  else
+    # Every account is exhausted RIGHT NOW: nothing serves, so hand out the one that
+    # unblocks first — its rejection window is the shortest.
+    PICK_DIR=""
+    best_reset=0
+    for d in "${hard[@]}"; do
+      r="$(limited_reset_of "$d")"
+      if [ -z "$PICK_DIR" ]; then
+        PICK_DIR="$d"; best_reset="$r"; continue
+      fi
+      if [ "$r" -gt 0 ] && { [ "$best_reset" -eq 0 ] || [ "$r" -lt "$best_reset" ]; }; then
+        PICK_DIR="$d"; best_reset="$r"
+      fi
+    done
+    sel_log "all-limited fallback=$(basename "$PICK_DIR") all-exhausted resets_in=$((best_reset > now ? best_reset - now : 0))s"
+    # Every candidate rejects right now, so this pick WILL fail: say so on a terminal
+    # instead of letting the operator read the client's bare limit error as a bad
+    # choice by the pool. Throttled, and never on a service's stderr.
+    if [ -t 2 ]; then
+      exn="$ACC_ROOT/.exhausted-notice"
+      exlast=0
+      [ -f "$exn" ] && exlast="$(file_mtime "$exn")"
+      if [ $((now - exlast)) -gt 600 ]; then
+        : 2>/dev/null > "$exn" || true
+        printf 'codex-multiacc: every usable account is at a limit right now; %s frees up in %ds and was chosen for that.\n' \
+          "$(basename "$PICK_DIR")" "$((best_reset > now ? best_reset - now : 0))" >&2
+      fi
+    fi
+  fi
 fi
 pick="$PICK_DIR"
 # Remember the pick so the NEXT run does not hand back the same account. An explicit
@@ -564,7 +699,7 @@ fi
 acct="$(basename "$pick")"
 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"
 
 export CODEX_SHIM_ACTIVE=1
 

package/bin/codex-accounts

@@ -1461,7 +1461,10 @@ for acct in manifest.get('accounts', []):
     # THREE selection signals, same reset asymmetry as the claude pool:
     #   max_percent    — peak of ALL buckets; drives >=90% EXCLUSION.
     #   weekly_percent — peak of the durable buckets; the PRIMARY ranking signal.
-    #   session_percent— peak of the self-healing ~5h buckets; a soft tiebreaker.
+    #   session_percent— peak of the self-healing ~5h buckets; the session GATE's input:
+    #                    the shim ranks only accounts at/under CODEX_MULTIACC_SESSION_GATE
+    #                    (default 50) while any clear it. (A soft tiebreaker until
+    #                    2026-09-03 — the operator asked for session FIRST, then weekly.)
     maxp = max([b['percent'] for b in buckets] or [0])
     weekly = [b['percent'] for b in buckets if b['group'] != 'session']
     session = [b['percent'] for b in buckets if b['group'] == 'session']

package/docs/ACCOUNT_OPERATIONS.md

@@ -333,6 +333,7 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 | `CLAUDE_CONFIG_DIR=...` | shim passes straight through (scripts can pin the old way) |
 | `CLAUDE_MULTIACC_DISABLE=1` | bypass selection entirely |
 | `CLAUDE_MULTIACC_HEADROOM_BAND=0..100` | weekly points treated as peers; default `30`, `0` is strict |
+| `CLAUDE_MULTIACC_SESSION_GATE=0..100` | max 5h-session usage that still gets ranked; default `50`, `100` disables the gate |
 | `CLAUDE_MULTIACC_CLIENT_LIMITS=0` | ignore the client's own rate-limit records |
 | `CLAUDE_MULTIACC_CLIENT_SCAN_TTL=<s>` | clean client-limit scan cache; default 20s |
 | `CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY=<s>` | low-telemetry recovery grace; default 300s |
@@ -343,8 +344,9 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 
 The codex shim honors the same switches spelled `CODEX_*`: `CODEX_ACCOUNT`,
 `CODEX_HOME` (passthrough), `CODEX_MULTIACC_DISABLE`, `CODEX_SHIM_RETRY`,
-`CODEX_SHIM_SELECT`, `CODEX_ACCOUNTS_ROOT` (legacy `CODEX_ACCOUNTS_DIR`),
-`CODEX_MULTIACC_SYNC_TARGET`, `CODEX_MULTIACC_THRESHOLD`.
+`CODEX_SHIM_SELECT`, `CODEX_MULTIACC_HEADROOM_BAND`, `CODEX_MULTIACC_SESSION_GATE`,
+`CODEX_ACCOUNTS_ROOT` (legacy `CODEX_ACCOUNTS_DIR`), `CODEX_MULTIACC_SYNC_TARGET`,
+`CODEX_MULTIACC_THRESHOLD`.
 
 ## Verification
 
@@ -382,8 +384,9 @@ repointed via `CLAUDE_BIN=/usr/local/bin/claude` and restarted healthy.
   before direct, TUI, or `--resume` work sees the 401. Run `claude-accounts verify` to
   check every token immediately; `claude-accounts expired` reports token-only accounts
   as `UNVERIFIED` until that proof exists.
-- **Everything marked limited** — the shim still runs (least-utilized fallback);
-  check `selection.log` for `all-limited` lines.
+- **Everything marked limited** — the shim still runs: the still-serving limited accounts
+  go through the same two cuts (session gate, then strict best-weekly) and one is handed
+  out anyway; check `selection.log` for `all-limited fallback=` lines.
 - **Sync fails** — `tail ~/.claude-accounts/sync.log`; it's ssh/rsync to the manifest's
   `server` (BatchMode — needs key auth).
 - **A service bypasses the shim** — it spawns an absolute path. Point its env

package/docs/TRACK_PROMPT.md

@@ -0,0 +1,76 @@
+# App-Robot Delivery Tracking Prompt
+
+Replace `<TASK_URL>` with the delivery URL, then paste the full prompt into Claude Code.
+
+```text
+Track app-robot delivery task <TASK_URL> to completion and actively repair anything
+that prevents forward progress.
+
+Operating rules:
+
+1. Start with a read-only timeline audit: current task/step/run, step age, last changed
+   evidence, worker/execution ownership, retry count, external operations, blockers,
+   and production build SHA.
+
+2. Treat 15 minutes without changed durable evidence as a stall. Do not accept log
+   activity, repeated probes, heartbeats, or newly minted attempts as progress.
+
+3. Never repeat the same failed action more than once. On the second identical failure,
+   stop retrying, identify the shared root cause, add a focused regression test, open a
+   fix PR, pass exact-head CI, merge/deploy it, verify production, then resume the task.
+
+4. Use app-robot's supported operations only. Preserve at-most-once semantics for store
+   submissions and other external mutations. Never bypass an operator-disabled store lane.
+
+5. Check that every supervising turn has a claimable execution, bounded retry and launch
+   budgets, expiring reservations, and a periodic reconciler. Repair the platform if not.
+
+6. Parallelize independent diagnosis and fixes, but serialize overlapping PRs. Batch
+   related fixes where safe. Merge overlapping PRs once in dependency order instead of
+   rebasing each after every squash.
+
+7. Run focused impacted tests during development. If local test admission waits over two
+   minutes, diagnose the admission and database lifecycle and use CI as the merge gate.
+   Do not wait indefinitely or start duplicate suites.
+
+8. Perform one bounded adversarial review of each original root-cause area, using at most
+   three reviewers. Aggregate confirmed findings into at most one follow-up PR per
+   subsystem. Do not review review-generated follow-ups unless they introduce a genuinely
+   new subsystem. Launch no recursive review fan-out.
+
+9. Cap each review workflow at 20 minutes. At the deadline, aggregate completed evidence
+   and stop incomplete or redundant workers. Cap each implementation agent at 20 minutes
+   to produce a pushed commit or test result; otherwise stop it and narrow or reassign the
+   task. A stalled agent is not progress.
+
+10. Do not wait for manual cleanup that is not on the delivery critical path. Convert the
+    cause into a bounded code fix and regression test, then let exact-head CI verify it.
+
+11. Every 10 minutes report: current step, age, last real progress, active blocker, exact
+    remediation, queue/CI/deploy status, remaining critical path, and any wall-clock budget
+    deviation.
+
+12. Persist a restart-safe checkpoint before context or account exhaustion: task/run IDs,
+    operation IDs, PR queue, production build, monitors, and exact next commands.
+
+13. Target four hours for a new delivery task and two hours for a repair-only critical
+    path, excluding unavoidable external store review. Use these sub-budgets:
+    - initial audit: 10 minutes
+    - root-cause diagnosis: 20 minutes per independent failure
+    - implementation agent: 20 minutes to a pushed artifact
+    - review workflow: 20 minutes, maximum three reviewers
+    - unchanged CI or deploy: investigate after 15 minutes
+    Report a budget miss immediately; do not silently extend it.
+
+14. Completion means: all enabled lanes have accepted outcomes; policy-disabled lanes are
+    recorded as notified person waits; all confirmed root-cause fixes are merged, deployed,
+    and production-verified; the repair queue is empty; bounded reviews are finished.
+    Then mark /goal complete.
+
+First response: give me the evidence-based critical path and the maximum wall-clock budget
+for each remaining step. Then begin; do not merely propose a plan.
+```
+
+The limits prevent an open-ended review-of-review loop. External store review can outlast
+the target, but the task must reach a durable submitted or policy-blocked state before the
+tracking goal is considered complete.

package/docs/UNIFIED_SELECTOR.md

@@ -20,19 +20,52 @@ The request schema is `claude-multiacc/pool-selection.v2` and contains:
 - the policy (`default_claude`, `default_codex`, `default_both`, `explicit`,
   `producer_retry`, or `reviewer`);
 - any required provider, producer identity and explicit exclusions;
-- the runner generation's candidate telemetry plus exact reservation history.
+- the runner generation's candidate telemetry plus exact reservation history;
+- optionally `headroom_band` and `session_gate`, the two ranking knobs below.
+
+Both knobs are optional so a caller pinned to an older panel build keeps working: each
+is a decimal clamped to 0–100, and a value that is not a plain decimal (a bool, a list,
+`null`, `1e5`) is refused as `invalid_request` naming that field rather than silently
+widening selection. `headroom_band` defaults to `30`, `session_gate` to `50`.
 
 Candidates must be active, fresh, provider-capable, not currently limited, and not
 covered by a live reservation. Percentages are finite decimals clamped to 0–100.
 Canonical account IDs are NFC-normalized and trimmed with case preserved; an
 NFC/case-folded key rejects case-only duplicate identities before ranking.
-Known quota ranks ahead of unknown quota; higher minimum weekly/session headroom
-wins; equal capacity goes to the least-recently-selected account, then a stable
-Claude-before-Codex/account-id tie order.
 
-Success returns the concrete engine/account/runner generation, normalized score basis,
-an RFC 8785/SHA-256 candidate-snapshot digest and a selection digest. Stable failures
-are `invalid_request`, `unsupported_schema`, `duplicate_candidate_identity`, and
+## Ranking: the session gate, then the weekly band
+
+The eligible set is ranked in two cuts (operator's decision, 2026-09-03: "among
+accounts where high session limits it must choose randomly from ones where highest
+weekly limits").
+
+1. **Session gate.** An account clears the gate when its quota is known and its session
+   (5h) usage is at most `session_gate` points. If any account clears it, only those are
+   ranked further — a nearly spent 5h bucket is about to reject the launch whatever the
+   weekly headroom says. If nobody clears it the gate steps aside and every known
+   account is ranked: the gate compares, it never empties the pool. Unknown quota never
+   clears it. `session_gate: 100` disables the gate.
+2. **Weekly band.** Among the gated accounts, the largest weekly remaining is the
+   leader and `band_floor` is that minus `headroom_band`; every gated account at or
+   above the floor is a peer. The band is measured on WEEKLY remaining, not on
+   `min(weekly, session)` — session headroom already had its say in the gate.
+   `headroom_band: 0` restores strict best-weekly ranking.
+3. **Inside the band.** The least-recently-selected peer wins, then a spread digest over
+   (reservation key, identity), then a stable Claude-before-Codex/account-id order. This
+   is what makes a burst of parallel launches fan out instead of stacking on one
+   account, and it is deterministic: the same request always yields the same winner.
+
+With no usable quota anywhere the band cannot apply (`band_floor` is `null`) and the
+plain ordering stands: known quota ahead of unknown, then highest effective headroom,
+then least-recently-selected.
+
+Success returns the concrete engine/account/runner generation, normalized score basis
+(which still reports `effective_headroom` = min(weekly, session) for observability),
+`headroom_band` / `band_floor` / `band_count`, `session_gate` / `session_ok_count` (how
+many accounts cleared the gate; `0` means nobody did and the gate stepped aside), an
+RFC 8785/SHA-256 candidate-snapshot digest and a selection digest. Both knobs are inputs
+to the selection digest, because both can change which account wins. Stable failures are
+`invalid_request`, `unsupported_schema`, `duplicate_candidate_identity`, and
 `no_candidate`. A reviewer stays on the producer's provider and avoids its account when
 another eligible account exists.
 

package/lib/selector_policy.py

@@ -7,6 +7,7 @@ from decimal import Decimal, localcontext
 
 from selector_primitives import (
     DEFAULT_HEADROOM_BAND,
+    DEFAULT_SESSION_GATE,
     SCHEMA,
     SELECTOR_VERSION,
     canonical_sha256,
@@ -126,17 +127,39 @@ def _winner_key(row: dict) -> tuple:
         row["engine"], row["account_id"], row["runner_id"], row["runner_generation"])
 
 
+def _session_gate(rows: list[dict], gate: Decimal | None) -> list[dict]:
+    """The FIRST cut: accounts whose 5h session bucket still has room.
+
+    The operator (2026-09-03): "among accounts where high session limits it must
+    choose randomly from ones where highest weekly limits." A nearly-spent session
+    bucket is about to reject the launch whatever the weekly headroom says, so it
+    disqualifies the account outright instead of merely nudging a tie-break. The
+    gate COMPARES, it never empties the pool: when nobody clears it the caller
+    falls back to every known row. Unknown quota never clears it — a missing
+    reading is not evidence of room.
+    """
+    if gate is None:
+        return []
+    return [row for row in rows if Decimal(row["session_pct"]) <= gate]
+
+
 def _band_floor(rows: list[dict], band: Decimal) -> Decimal | None:
-    """The lowest headroom still counted as "as good as the best" this round.
+    """The lowest WEEKLY remaining still counted as "as good as the best" this round.
 
     Ranking strictly by headroom hands every task to whichever account is on top,
     which is precisely how one account's limit gets burned to zero while three
     others idle: the runner-up only ever wins after the leader has been spent
     below it. Accounts within ``band`` points of the leader are treated as equally
     good, and the tie-break below spreads work across them.
+
+    The band is measured on weekly remaining, not on min(weekly, session): session
+    headroom already had its say in ``_session_gate`` above, and letting it back in
+    here both pushed the best weekly account out of the band over a half-spent 5h
+    bucket and let a fully spent one stay in. Rows reaching here are the gated set,
+    so every one of them has a known reading.
     """
-    known = [Decimal(row["effective_headroom"]) for row in rows
-             if row["quota_known"] and row["effective_headroom"] is not None]
+    known = [Decimal(row["weekly_remaining"]) for row in rows
+             if row["quota_known"] and row["weekly_remaining"] is not None]
     return max(known) - band if known else None
 
 
@@ -197,15 +220,21 @@ def select(request: object) -> dict:
     if not eligible:
         return _error("no_candidate", {"eligible_count": 0})
     band, band_text = decimal_value(request.get("headroom_band", DEFAULT_HEADROOM_BAND))
-    floor = _band_floor(eligible, band) if band is not None else None
+    gate, gate_text = decimal_value(request.get("session_gate", DEFAULT_SESSION_GATE))
+    # Two cuts, in this order (operator's 2026-09-03 decision): the session gate says
+    # WHO may be considered, the weekly band says which of those count as equally
+    # good. "healthy or known" is the gate stepping aside when nobody clears it.
+    known = [row for row in eligible if row["quota_known"]]
+    healthy = _session_gate(known, gate)
+    ranked = healthy or known
+    floor = _band_floor(ranked, band) if band is not None else None
     if floor is None:
         # No usable quota anywhere: nothing to band, so keep the plain ordering
         # (which already ranks unknown-quota rows last and rotates on ties).
         banded = eligible
         winner = min(banded, key=_winner_key)
     else:
-        banded = [row for row in eligible if row["quota_known"]
-                  and Decimal(row["effective_headroom"]) >= floor]
+        banded = [row for row in ranked if Decimal(row["weekly_remaining"]) >= floor]
         winner = min(banded, key=_band_key(request["reservation_key"]))
     rows.sort(key=_snapshot_key)
     snapshot = canonical_sha256(rows)
@@ -214,8 +243,10 @@ def select(request: object) -> dict:
         "schema": SCHEMA, "selector_version": SELECTOR_VERSION,
         "database_now": canonical_now, "policy": request["policy"],
         "required_engine": request.get("required_engine"), "reservation_key": request["reservation_key"],
-        # The band changes which account wins, so it belongs in the proof.
+        # The band and the gate both change which account wins, so both belong in
+        # the proof. (This is why the golden digests moved on 2026-09-03.)
         "headroom_band": band_text,
+        "session_gate": gate_text,
         "candidate_snapshot_digest": snapshot, "selected_identity": chosen}
     score_fields = ("quota_known", "weekly_pct", "session_pct", "weekly_remaining",
                     "session_remaining", "effective_headroom", "last_selected_at")
@@ -228,6 +259,10 @@ def select(request: object) -> dict:
                 "headroom_band": band_text,
                 "band_floor": format(floor, "f") if floor is not None else None,
                 "band_count": len(banded),
+                # ...and how many accounts the session gate let through at all
+                # (0 means nobody cleared it and the gate stepped aside).
+                "session_gate": gate_text,
+                "session_ok_count": len(healthy),
                 "candidate_snapshot_digest": snapshot,
                 "selection_digest": canonical_sha256(digest_input)}
     if request["policy"] == "reviewer" and not alternatives and _row_identity(winner) == producer: