claude-multiacc 2.0.19 → 2.0.21

package/bin/claude-accounts

@@ -1520,6 +1520,14 @@ REFRESH_DENIED_BACKOFF = 21600  # 4xx = grant likely revoked: 6h; re-login neede
 # exactly which ceremony fixes it.
 USAGE_DENIED_BACKOFF = 21600
 USAGE_FAIL_BACKOFF = 900       # anything else non-2xx: 15 min, doubling to 30
+# A real client 429 beats an immediately-following usage response, which may be cached.
+# A later successful response under the threshold is newer first-hand evidence and must
+# release the account instead of preserving a false marker until a days-away reset.
+try:
+    CLIENT_LIMIT_CONFIRM_DELAY = max(
+        0, min(3600, int(os.environ.get('CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY', '300'))))
+except ValueError:
+    CLIENT_LIMIT_CONFIRM_DELAY = 300
 
 def say(msg):
     if not quiet:
@@ -2148,7 +2156,10 @@ for acct in manifest.get('accounts', []):
     #   weekly_percent — peak of the durable (weekly/monthly) buckets; the PRIMARY
     #                    ranking signal, because weekly headroom only returns on the
     #                    account's fixed weekly reset (days away).
-    #   session_percent— peak of the self-healing 5h bucket; a soft tiebreaker only.
+    #   session_percent— peak of the self-healing 5h bucket; the session GATE's input:
+    #                    the shim ranks only accounts at/under CLAUDE_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']
@@ -2207,23 +2218,37 @@ for acct in manifest.get('accounts', []):
             # A shim-written marker outlives a clean limits pass while its own window
             # is still open:
             #   error-cooldown     — the account failed a real call moments ago.
-            #   client-rate-limit  — Claude Code itself was REJECTED on this account and
-            #                        recorded the reset the API handed it. That is
-            #                        first-hand evidence; a usage payload that disagrees
-            #                        (different bucket set, cached edge) must not unpark
-            #                        the account early and send work straight back into
-            #                        the 429.
+            #   client-rate-limit  — Claude Code itself was REJECTED on this account.
+            #                        Preserve that over a possibly-cached response during
+            #                        a short grace period. A later successful low-usage
+            #                        response disproves it; otherwise false/shared-session
+            #                        markers strand recovered accounts for days.
             keep = False
+            client_recovered = False
             try:
                 txt = open(mpath).read()
                 first = txt.splitlines()[0] if txt else ''
-                if ('reason=error-cooldown' in txt or 'reason=client-rate-limit' in txt) \
-                        and first.isdigit() and int(first) > now:
+                active = first.isdigit() and int(first) > now
+                marked_at = next((part[10:] for part in txt.split()
+                                  if part.startswith('marked_at=')), '')
+                marked_epoch = parse_iso(marked_at)
+                if marked_epoch is None:
+                    marked_epoch = os.path.getmtime(mpath)
+                recent_client = now - marked_epoch < CLIENT_LIMIT_CONFIRM_DELAY
+                client_recovered = active and 'reason=client-rate-limit' in txt \
+                    and not recent_client
+                if active and ('reason=error-cooldown' in txt
+                               or ('reason=client-rate-limit' in txt and recent_client)):
                     keep = True
             except Exception:
                 pass
             if not keep:
                 os.remove(mpath)
+                if client_recovered:
+                    cleared = os.path.join(d, '.client-limit-cleared')
+                    with open(cleared + '.tmp', 'w') as f:
+                        f.write(f'{int(now)}\n')
+                    os.replace(cleared + '.tmp', cleared)
                 say(f'{aid}: marker cleared (max {maxp}%)')
         if not quiet:
             detail = '  '.join(f"{b['name']}={b['percent']}%" for b in buckets)

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 > most-headroom among
-# limit-eligible accounts > 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,18 +142,99 @@ 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)"; 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
@@ -454,62 +537,138 @@ 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 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"
 }
 
 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_best "${valid[@]}"
-  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
@@ -538,7 +697,9 @@ if [ "$stale" = 1 ] && [ -x "$SELF_DIR/codex-accounts" ]; then
 fi
 
 acct="$(basename "$pick")"
-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"
 
 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

@@ -332,8 +332,11 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 | `CLAUDE_ACCOUNT=acct-03` | pin this invocation to one account (wins over markers) |
 | `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 |
 | `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
 | `CLAUDE_ACCOUNTS_ROOT=...` | relocate the pool; legacy spelling is `CLAUDE_ACCOUNTS_DIR` |
 | `CLAUDE_MULTIACC_SYNC_TARGET=...` | sync target, overriding the manifest; `none` = local-only |
@@ -341,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
 
@@ -380,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.