claude-multiacc 1.0.13 → 1.0.15

package/bin/claude

@@ -12,7 +12,10 @@ set -u
 
 # ${HOME:-} guards: with HOME stripped (env -i, some cron/systemd units) the shim
 # must still fail OPEN into plain passthrough, never abort on an unbound variable.
-ACC_ROOT="${CLAUDE_ACCOUNTS_DIR:-${HOME:-/nonexistent}/.claude-accounts}"
+# CLAUDE_ACCOUNTS_ROOT scopes the pool to one app-robot instance; CLAUDE_ACCOUNTS_DIR
+# is the older spelling and still works. Same precedence as lib/common.sh, so the shim
+# and claude-accounts always look at the same pool.
+ACC_ROOT="${CLAUDE_ACCOUNTS_ROOT:-${CLAUDE_ACCOUNTS_DIR:-${HOME:-/nonexistent}/.claude-accounts}}"
 MANIFEST="$ACC_ROOT/accounts.json"
 
 canon_path() {
@@ -81,8 +84,11 @@ now="$(date +%s)"
 # sed with a safe default, never a JSON parse.
 if [ -z "${CLAUDE_MULTIACC_THRESHOLD:-}" ]; then
   CLAUDE_MULTIACC_THRESHOLD="$(sed -n 's/.*"threshold"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$MANIFEST" 2>/dev/null | head -1)"
-  case "$CLAUDE_MULTIACC_THRESHOLD" in ''|*[!0-9]*) CLAUDE_MULTIACC_THRESHOLD=90 ;; esac
+  CLAUDE_MULTIACC_THRESHOLD="$CLAUDE_MULTIACC_THRESHOLD"
 fi
+# Scraped or handed in by the caller, it has to be a number bash can compare without
+# complaining to stderr.
+case "$CLAUDE_MULTIACC_THRESHOLD" in ''|*[!0-9]*|??????*) CLAUDE_MULTIACC_THRESHOLD=90 ;; esac
 
 if [ "$(uname -s)" = "Darwin" ]; then
   file_mtime() { stat -f %m "$1" 2>/dev/null || echo 0; }
@@ -90,21 +96,28 @@ else
   file_mtime() { stat -c %Y "$1" 2>/dev/null || echo 0; }
 fi
 
+
+# A number this shim will do ARITHMETIC on: digits only, and short enough that bash
+# cannot go out of range. An over-range value makes `[ x -lt y ]` print
+# "integer expression expected" on stderr — which a service-spawned run must never see —
+# and makes $((x + 1)) wrap negative. Pool state is a file anyone can corrupt, so every
+# scraped number goes through here.
+num_ok() { case "$1" in ''|*[!0-9]*) return 1 ;; esac; [ "${#1}" -le 18 ]; }
+
 sel_log() {
-  printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" >> "$ACC_ROOT/selection.log" 2>/dev/null || true
+  printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" 2>/dev/null >> "$ACC_ROOT/selection.log" || true
 }
 
 marker_active() { # true if $1/.limited is still in force; clears cleanly-expired markers
   local m="$1/.limited" reset=""
   [ -f "$m" ] || return 1
   IFS= read -r reset < "$m" 2>/dev/null || reset=""
-  case "$reset" in
-    ''|*[!0-9]*)
-      # Empty/partial/garbled marker — e.g. read during a concurrent rewrite.
-      # Treat as ACTIVE and never delete: deleting here could destroy a marker
-      # another process is mid-write. The next limits refresh rewrites or clears it.
-      return 0 ;;
-  esac
+  if ! num_ok "$reset"; then
+    # Empty/partial/garbled/absurd marker — e.g. read during a concurrent rewrite.
+    # Treat as ACTIVE and never delete: deleting here could destroy a marker
+    # another process is mid-write. The next limits refresh rewrites or clears it.
+    return 0
+  fi
   if [ "$now" -ge "$reset" ]; then
     rm -f "$m" 2>/dev/null
     return 1
@@ -112,29 +125,105 @@ marker_active() { # true if $1/.limited is still in force; clears cleanly-expire
   return 0
 }
 
-STALE_AFTER=900
+# How old telemetry may be and still rank. 900s was below the floor the usage endpoint
+# ITSELF enforces: it answers a caller at most about once an hour (429 + Retry-After
+# 3600), so a 15-minute window declared the data stale for most of every hour even on a
+# perfectly healthy pool — and stale data ranks NEUTRAL, which is the same as not
+# ranking at all. One hour matches what the endpoint is willing to give.
+STALE_AFTER="${CLAUDE_MULTIACC_STALE_AFTER:-3600}"
+case "$STALE_AFTER" in ''|*[!0-9]*|0) STALE_AFTER=3600 ;; esac
 
-fresh_field() { # fresh_field <acct dir> <json key> -> integer if telemetry fresh, else fail
-  local f="$1/limits.json" fetched v
+# EXCLUSION keeps the old, tight window on purpose. Ranking and the >=90% cutoff are
+# not the same kind of judgement: ranking picks between working accounts and an hour-old
+# number is plenty, while the cutoff decides that an account is UNUSABLE — and an
+# account reading 89% an hour ago may be well past 90% now. Trusting one window for both
+# would have quietly extended a stale "89%" into 45 extra minutes of eligibility.
+EXCLUDE_STALE_AFTER=900
+[ "$EXCLUDE_STALE_AFTER" -gt "$STALE_AFTER" ] && EXCLUDE_STALE_AFTER="$STALE_AFTER"
+
+telem_fetched_at() { # $1 = acct dir -> epoch of the last successful fetch, or fail
+  local f="$1/limits.json" fetched
   [ -f "$f" ] || return 1
   fetched="$(sed -n 's/.*"fetched_at"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$f" 2>/dev/null | head -1)"
-  case "$fetched" in ''|*[!0-9]*) return 1 ;; esac
-  [ $((now - fetched)) -le "$STALE_AFTER" ] || return 1
-  v="$(sed -n "s/.*\"$2\"[^0-9]*\([0-9][0-9]*\).*/\1/p" "$f" 2>/dev/null | head -1)"
-  case "$v" in ''|*[!0-9]*) return 1 ;; esac
+  num_ok "$fetched" || return 1
+  printf '%s\n' "$fetched"
+}
+
+limits_field() { # limits_field <acct dir> <json key> -> integer, or fail
+  local v
+  v="$(sed -n "s/.*\"$2\"[^0-9]*\([0-9][0-9]*\).*/\1/p" "$1/limits.json" 2>/dev/null | head -1)"
+  num_ok "$v" || return 1
   printf '%s\n' "$v"
 }
 
+# fresh_field/cutoff_field parse fetched_at inline rather than through
+# telem_fetched_at: they run several times per account on EVERY invocation, and the
+# difference is a fork apiece. (This file is deliberately fork-frugal — see
+# sessions_owned.) telem_fetched_at exists for the once-per-account callers.
+within_window() { # $1 = acct dir, $2 = window seconds
+  local f="$1/limits.json" fetched
+  [ -f "$f" ] || return 1
+  fetched="$(sed -n 's/.*"fetched_at"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$f" 2>/dev/null | head -1)"
+  num_ok "$fetched" || return 1
+  [ $((now - fetched)) -le "$2" ]
+}
+
+fresh_field() { # fresh_field <acct dir> <json key> -> integer if telemetry fresh, else fail
+  within_window "$1" "$STALE_AFTER" || return 1
+  limits_field "$1" "$2"
+}
+
+# Same, but for the >=90% cutoff, which gets the tighter window (see EXCLUDE_STALE_AFTER).
+cutoff_field() { # $1 = acct dir, $2 = json key
+  within_window "$1" "$EXCLUDE_STALE_AFTER" || return 1
+  limits_field "$1" "$2"
+}
+
+# LAST-RESORT ranking input, used only when NOTHING in the pool is fresh (see the blind
+# guard below). A weekly bucket only rises until its reset, so until that moment an old
+# weekly reading is still a true lower bound on today's usage — strictly more information
+# than the neutral 50 that erases every difference between accounts and turns selection
+# into a coin flip. Once the reset has passed, the number describes a week that is over
+# and is worth exactly nothing, so it is refused.
+stale_weekly() { # $1 = acct dir
+  local resets
+  resets="$(limits_field "$1" weekly_resets_epoch)" || return 1
+  [ "$resets" -gt "$now" ] || return 1
+  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.
+telem_blind() { # $1 = acct dir
+  ! within_window "$1" "$STALE_AFTER"
+}
+
+# Human age for the warning line: seconds -> "3h" / "11d". Never fails.
+age_human() { # $1 = seconds
+  local s="$1"
+  if [ "$s" -ge 86400 ]; then printf '%dd\n' $((s / 86400))
+  elif [ "$s" -ge 3600 ]; then printf '%dh\n' $((s / 3600))
+  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 NEUTRAL (weekly 50, session 50), never "free".
+# Stale/unreadable telemetry ranks NEUTRAL (weekly 50, session 50), never "free" —
+# EXCEPT in a blind pool (SEL_DEGRADED=1), where a still-valid stale weekly reading is
+# used instead. Neutral is only the right answer while some other account HAS fresh
+# data to be neutral against; when no account does, neutral is just a coin flip.
+SEL_DEGRADED=0
 sel_score_of() { # $1 = acct dir
   local w s
-  w="$(fresh_field "$1" weekly_percent)" || w="$(fresh_field "$1" max_percent)" || w=50
+  if ! w="$(fresh_field "$1" weekly_percent)" && ! w="$(fresh_field "$1" max_percent)"; then
+    if [ "$SEL_DEGRADED" = 1 ]; then w="$(stale_weekly "$1")" || w=50; else w=50; fi
+  fi
   s="$(fresh_field "$1" session_percent)" || s=50
   printf '%s\n' $((w * 1000 + s))
 }
@@ -152,10 +241,284 @@ util_of() {
 # (fail open — telemetry must never invent exclusions).
 over_threshold() { # $1 = acct dir
   local v
-  v="$(fresh_field "$1" max_percent)" || return 1
+  v="$(cutoff_field "$1" max_percent)" || return 1
   [ "$v" -ge "${CLAUDE_MULTIACC_THRESHOLD:-90}" ]
 }
 
+# ---- client-reported rate limits ---------------------------------------------
+# The usage API is not the only source of truth, and it is the one that fails exactly
+# when it matters: it rate-limits its own callers (429 + Retry-After 3600), so
+# limits.json can be hours or days stale at the very moment an account runs dry.
+# Claude Code itself records every rejection in the session transcript:
+#   {..."error":"rate_limit","apiErrorStatus":429,
+#       "quotaLimits":{"status":"rejected","resetsAt":<epoch>,"rateLimitType":"five_hour",...}}
+# That record is free, instant, offline, and carries the REAL reset time. Reading it is
+# what lets an INTERACTIVE session take its own account out of the pool: the -p retry
+# path below never sees a TUI run, so before this, a 5h limit hit in tmux left no trace
+# at all and the next `claude` could walk straight back into the same dead account.
+#
+# Transcripts are NOT account-scoped ($acct/projects is a shared symlink by design —
+# lib/common.sh), so the session -> account mapping comes from $acct/sessions/<pid>.json,
+# which the client maintains for the lifetime of every run. sess_index_refresh() harvests
+# those ids while the runs are alive; sel_capture_session() catches the run THIS
+# invocation is about to exec into, so the id outlives the session that recorded the hit.
+# ...and that registry has to be private to the account, or it says nothing about who
+# ran what: one rejection would then mark the whole pool LIMITED.
+sessions_owned() { # $1 acct dir
+  # Structural and deliberately FORK-FREE: this runs for every account on every single
+  # invocation, and a pair of canon_path calls here cost more than the whole scan.
+  # A session tree is this account's own evidence only when neither the account dir nor
+  # its sessions dir is a symlink — which is exactly how a shared layout is built
+  # (lib/common.sh seeds codex accounts with sessions -> ~/.codex/sessions, and an account
+  # dir may itself be a symlink to ~/.codex). Anything shared fails OPEN: no ownership,
+  # no exclusion, and the usage endpoint stays the only limit signal for that account.
+  [ -d "$1/sessions" ] || return 1
+  [ -L "$1/sessions" ] && return 1
+  [ -L "$1" ] && return 1
+  return 0
+}
+
+SESS_INDEX_MAX=12          # session ids remembered per account
+QUOTA_SCAN_BYTES=262144    # transcript tail read per session (records land at the end)
+QUOTA_SCAN_MAX_AGE=21600   # 6h: a 5h window plus slack. A limit older than that has
+                           # either reset, or been re-recorded by a newer session.
+QUOTA_SCAN_MAX_FILES=3     # hard cap per account: a limit still in force rejects the
+                           # newest sessions too, so older ones can only repeat the news
+
+# Hex and dashes only, and never a LEADING dash: an id like "-e" is inside that class
+# and would be handed to grep as an option, which then eats the file operand and blocks
+# on the shim's own stdin — a hang before exec, the one failure this file may never have.
+# Every grep below also gets `--` so the class is not the only thing standing in the way.
+sess_id_ok() { case "$1" in ''|-*|*[!0-9a-fA-F-]*) return 1 ;; *) return 0 ;; esac; }
+
+iso_of_epoch() { # $1 seconds -> UTC ISO8601 ('' when neither date(1) dialect works)
+  date -u -r "$1" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "@$1" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null
+}
+
+# Comparable digit string for an ISO timestamp: 2026-08-21T17:07:59.321Z -> 20260821170759.
+# Locale-proof (plain integers), and short enough that num_ok always passes.
+iso_key() { local t="${1%%.*}"; t="$(printf '%s' "$t" | LC_ALL=C tr -cd '0-9')"; printf '%s\n' "${t}"; }
+
+# Index line: "<session id> <ISO claim>". The claim is the session's OWN start time, and
+# an id belongs to exactly ONE account.
+# Why both: `claude --continue` resumes the SAME session id under whichever account the
+# pool hands out next (the client only mints a new id with --fork-session), and the
+# transcript is shared — so without a single owner one rejection would mark every account
+# that ever touched that session, and without the claim time the new owner would inherit
+# a rejection the PREVIOUS owner earned. Each rule only ever removes attribution: the
+# failure mode is a missed limit, never an invented one.
+sess_index_add() { # $1 acct dir, $2 session id, $3 start epoch (optional)
+  local idx="$1/.sessions-index" tmp oidx claim=""
+  sess_id_ok "$2" || return 0
+  # `( |$)` also matches a claim-less line from an older build, so such an entry is still
+  # deduped and can still be released when another account takes the session over.
+  [ -f "$idx" ] && LC_ALL=C grep -qE -- "^$2( |$)" "$idx" 2>/dev/null && return 0
+  num_ok "${3:-}" && claim="$(iso_of_epoch "$3")"
+  [ -n "$claim" ] || claim="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  for oidx in "$ACC_ROOT"/acct-*/.sessions-index; do
+    [ -f "$oidx" ] || continue
+    [ "$oidx" = "$idx" ] && continue
+    LC_ALL=C grep -qE -- "^$2( |$)" "$oidx" 2>/dev/null || continue
+    # `grep -v` exits 1 when it filters everything out, which is a perfectly good result
+    # here — the `true` keeps the emptied index from being thrown away.
+    if { LC_ALL=C grep -vE -- "^$2( |$)" "$oidx" 2>/dev/null; true; } 2>/dev/null > "$oidx.$$"; then
+      mv -f "$oidx.$$" "$oidx" 2>/dev/null || rm -f "$oidx.$$" 2>/dev/null
+    else
+      rm -f "$oidx.$$" 2>/dev/null
+    fi
+  done
+  tmp="$idx.$$"
+  { [ -f "$idx" ] && cat "$idx" 2>/dev/null; printf '%s %s\n' "$2" "$claim"; } \
+    | tail -n "$SESS_INDEX_MAX" 2>/dev/null > "$tmp" \
+    && mv -f "$tmp" "$idx" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+  return 0
+}
+
+sess_index_refresh() { # $1 acct dir — record every run currently live in this account
+  local f id started known="" ln
+  sessions_owned "$1" || return 0
+  # Read the index ONCE with the builtin, so the steady state (every live session already
+  # claimed) costs one sed per session and not a grep and a second sed on top.
+  if [ -f "$1/.sessions-index" ]; then
+    while IFS= read -r ln; do known="$known ${ln%% *}"; done < "$1/.sessions-index"
+  fi
+  for f in "$1"/sessions/*.json; do
+    [ -f "$f" ] || continue
+    # A symlinked registry entry would let another pool's session id in under this
+    # account's name (second-pass codex-review finding, nested-symlink variant).
+    [ -L "$f" ] && continue
+    id="$(LC_ALL=C sed -n 's/.*"sessionId"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$f" 2>/dev/null | head -1)"
+    sess_id_ok "$id" || continue
+    case "$known" in *" $id "*|*" $id") continue ;; esac
+    # startedAt is epoch MILLIseconds; using the session's real start (not "now") is what
+    # lets a session that has been running since before this shim was installed still be
+    # attributed correctly.
+    started="$(LC_ALL=C sed -n 's/.*"startedAt"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$f" 2>/dev/null | head -1)"
+    num_ok "$started" && started=$((started / 1000)) || started=""
+    sess_index_add "$1" "$id" "$started"
+    known="$known $id"
+  done
+  return 0
+}
+
+# Two accounts can first-sight the same session id at the same instant and both claim it
+# (sess_index_add releases the id from the others, but two concurrent releases can cross,
+# and neither run repairs it afterwards). Checked HERE, at the one moment it decides
+# something: if any other account holds the id with a claim at least as new as ours, that
+# account owns the session now and the rejection is not ours to answer for. An unreadable
+# rival claim counts as a conflict too — ambiguity means no attribution.
+claim_conflicted() { # $1 acct dir, $2 session id, $3 our ISO claim
+  local oidx other ok mk
+  mk="$(iso_key "${3:-}")"
+  num_ok "$mk" || return 0
+  for oidx in "$ACC_ROOT"/acct-*/.sessions-index; do
+    [ -f "$oidx" ] || continue
+    [ "$oidx" = "$1/.sessions-index" ] && continue
+    # EVERY matching line, not just the first: an index can hold the same id twice (an
+    # older claim followed by a newer one), and it is the newest rival that decides.
+    while IFS= read -r other; do
+      [ -n "$other" ] || continue
+      case "$other" in *' '*) ok="$(iso_key "${other#* }")" ;; *) return 0 ;; esac
+      num_ok "$ok" || return 0
+      [ "$ok" -ge "$mk" ] && return 0
+    done <<EOF
+$(LC_ALL=C grep -E -- "^$2( |$)" "$oidx" 2>/dev/null)
+EOF
+  done
+  return 1
+}
+
+# Sets SESS_TRANSCRIPT rather than printing it: this is called once per examined index
+# entry, and a command substitution here is a fork per entry per account per run.
+SESS_TRANSCRIPT=""
+sess_transcript() { # $1 acct dir, $2 session id
+  local p
+  SESS_TRANSCRIPT=""
+  for p in "$1"/projects/*/"$2".jsonl; do
+    [ -f "$p" ] && { SESS_TRANSCRIPT="$p"; return 0; }
+  done
+  return 1
+}
+
+# Newest still-in-force rejection this account's own sessions recorded.
+# Prints "<reset-epoch> <rateLimitType>"; fails when there is none.
+# This runs on EVERY invocation, so it is bounded on purpose: newest session first,
+# stop at the first in-force rejection, and never read more than QUOTA_SCAN_MAX_FILES
+# transcripts. Missing an older rejection costs nothing — a limit that is still in force
+# rejects the very next request too, and that lands in a newer transcript.
+client_limit_scan() { # $1 acct dir
+  local idx="$1/.sessions-index" memo="$1/.client-scan" id p line r t read_n=0 i last=""
+  local ln claim ts ck ak ttl
+  local ids=() claims=()
+  [ "${CLAUDE_MULTIACC_CLIENT_LIMITS:-1}" = "0" ] && return 1
+  [ -f "$idx" ] || return 1
+  # A CLEAN result is remembered for a few seconds: a tight loop of `claude -p` runs
+  # must not re-read the same transcript tails on every single invocation. Only the
+  # clean answer is memoized — a rejection becomes a .limited marker, and marker_active
+  # short-circuits this scan entirely from then on. Worst case, a limit hit in the last
+  # few seconds is noticed one run late.
+  if [ -f "$memo" ]; then
+    IFS= read -r last < "$memo" 2>/dev/null || last=""
+    num_ok "$last" || last=0
+    # The TTL is caller-supplied, so it goes through num_ok too: `[ x -lt bogus ]` would
+    # print "integer expression expected" on the caller's stderr before exec.
+    ttl="${CLAUDE_MULTIACC_CLIENT_SCAN_TTL:-20}"
+    num_ok "$ttl" || ttl=20
+    [ $((now - last)) -lt "$ttl" ] && return 1
+  fi
+  while IFS= read -r ln; do
+    id="${ln%% *}"
+    claim=""
+    case "$ln" in *' '*) claim="${ln#* }" ;; esac
+    sess_id_ok "$id" && { ids+=("$id"); claims+=("$claim"); }
+  done < "$idx"
+  # The budget bounds ENTRIES EXAMINED, not just transcripts read: an entry that fails the
+  # staleness test still costs a glob and a stat, so a large pool with a full index would
+  # otherwise pay for all of them on every single run and never reach a cap at all.
+  i=$(( ${#ids[@]} - 1 ))
+  while [ "$i" -ge 0 ] && [ "$read_n" -lt "$QUOTA_SCAN_MAX_FILES" ]; do
+    id="${ids[$i]}"
+    claim="${claims[$i]}"
+    i=$((i - 1))
+    read_n=$((read_n + 1))
+    sess_transcript "$1" "$id" || continue
+    p="$SESS_TRANSCRIPT"
+    [ $((now - $(file_mtime "$p"))) -le "$QUOTA_SCAN_MAX_AGE" ] || continue
+    # One grep, not three: this runs on every invocation, and the two seds below only
+    # ever run on a line that already matched. '^{"' drops the partial first line a
+    # byte-oriented tail can leave behind.
+    line="$(tail -c "$QUOTA_SCAN_BYTES" "$p" 2>/dev/null \
+      | LC_ALL=C grep -a '^{".*"error"[[:space:]]*:[[:space:]]*"rate_limit"' \
+      | tail -1)"
+    [ -n "$line" ] || continue
+    case "$line" in *'"status":"rejected"'*|*'"status": "rejected"'*) ;; *) continue ;; esac
+    # A rejection recorded BEFORE this account took the session over belongs to whoever
+    # was running it then, not to us. Undatable => not attributed (fail open).
+    if [ -n "$claim" ]; then
+      ts="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"timestamp"[[:space:]]*:[[:space:]]*"\([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[^"]*\)".*/\1/p')"
+      [ -n "$ts" ] || continue
+      ck="$(iso_key "$ts")"; ak="$(iso_key "$claim")"
+      num_ok "$ck" || continue
+      num_ok "$ak" || continue
+      [ "$ck" -lt "$ak" ] && continue
+      claim_conflicted "$1" "$id" "$claim" && continue
+    fi
+    r="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"resetsAt"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p')"
+    num_ok "$r" || continue
+    [ "$r" -gt "$now" ] || continue
+    t="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"rateLimitType"[[:space:]]*:[[:space:]]*"\([A-Za-z0-9_.-]*\)".*/\1/p')"
+    printf '%s %s\n' "$r" "${t:-unknown}"
+    return 0
+  done
+  printf '%s\n' "$now" 2>/dev/null > "$memo.$$" \
+    && mv -f "$memo.$$" "$memo" 2>/dev/null || rm -f "$memo.$$" 2>/dev/null
+  return 1
+}
+
+mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type
+  local m="$1/.limited" cur=""
+  # Never shorten a marker that already reaches further out (a weekly park must
+  # survive a 5h report), and never rewrite the same one on every invocation.
+  if [ -f "$m" ]; then
+    IFS= read -r cur < "$m" 2>/dev/null || cur=""
+    num_ok "$cur" || cur=0
+    [ "$cur" -ge "$2" ] && return 0
+  fi
+  {
+    echo "$2"
+    echo "bucket=client:$3 percent=100 marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=client-rate-limit"
+  } 2>/dev/null > "$1/.limited.$$" \
+    && mv -f "$1/.limited.$$" "$m" 2>/dev/null \
+    || rm -f "$1/.limited.$$" 2>/dev/null || true
+  sel_log "$(basename "$1") LIMITED by its own session ($3, resets $2) — client-reported"
+  return 0
+}
+
+# The run this shim is about to BECOME writes $acct/sessions/<pid>.json for its whole
+# lifetime, and exec keeps the pid — so $$ is that file's name. A detached poll records
+# it (and every other live run of the account) in the index, because by the time the
+# user quits a limit-hit session and starts a new one, the client has already deleted
+# its registry file and nothing else can name the transcript that holds the evidence.
+sel_capture_session() { # $1 acct dir
+  local d="$1" pid=$$
+  [ "${CLAUDE_MULTIACC_CLIENT_LIMITS:-1}" = "0" ] && return 0
+  (
+    # Ctrl-C / a closed terminal must not kill the capture: it is bounded (60s) and
+    # stops the moment the run it is watching is gone.
+    trap '' INT HUP TERM QUIT
+    i=0
+    while [ "$i" -lt 30 ]; do
+      kill -0 "$pid" 2>/dev/null || break
+      sess_index_refresh "$d"
+      [ -f "$d/sessions/$pid.json" ] && break
+      sleep 2
+      i=$((i + 1))
+    done
+    sess_index_refresh "$d"
+  ) >/dev/null 2>&1 </dev/null &
+  return 0
+}
+
 # An empty credentials file is NOT auth (an interrupted write must not make a
 # dead account selectable and turn a working stock run into an auth failure).
 has_auth() { [ -s "$1/.credentials.json" ] || [ -s "$1/server.token" ]; }
@@ -231,6 +594,14 @@ auth_dead() { # $1 = acct dir
   creds_dead "$1"
 }
 
+acct_token() { # $1 = acct dir; prints token if the dir must authenticate by token
+  # Token-auth dirs (no local creds), and dirs whose OAuth credential is dead but which
+  # still carry a portable setup-token — the token is the only thing that can work there.
+  if [ -s "$1/server.token" ] && { [ ! -f "$1/.credentials.json" ] || creds_dead "$1"; }; then
+    tr -d '[:space:]' < "$1/server.token"
+  fi
+}
+
 # Explicit pin wins over everything — markers, and even missing auth: the
 # add/login ceremony pins to a dir that has no credentials yet, and the login
 # must land exactly there, never in a randomly selected account's dir.
@@ -240,10 +611,13 @@ if [ -n "${CLAUDE_ACCOUNT:-}" ]; then
     sel_log "$CLAUDE_ACCOUNT pinned pwd=$PWD"
     export CLAUDE_CONFIG_DIR="$d"
     export CLAUDE_SHIM_ACTIVE=1
-    if [ ! -f "$d/.credentials.json" ] && [ -s "$d/server.token" ]; then
-      CLAUDE_CODE_OAUTH_TOKEN="$(tr -d '[:space:]' < "$d/server.token")"
-      export CLAUDE_CODE_OAUTH_TOKEN
-    fi
+    # Same rule as every other path (acct_token): a DEAD credential beside a portable
+    # token must not shadow the token. Testing only for the credential's absence made a
+    # pinned account with a stale login fail outright ("OAuth session expired") while
+    # the very same account worked unpinned.
+    tok="$(acct_token "$d")"
+    [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+    sel_capture_session "$d"
     exec "$REAL" "$@"
   fi
   sel_log "pin-invalid account=$CLAUDE_ACCOUNT (no such dir; random fallback)"
@@ -263,7 +637,18 @@ for d in "$ACC_ROOT"/acct-*; do
     continue
   fi
   valid+=("$d")
+  sess_index_refresh "$d"
   marker_active "$d" && continue
+  # The account's own records are consulted BEFORE telemetry: what the server told a real
+  # call is first-hand and carries the real reset, while limits.json can be days stale —
+  # the usage endpoint rate-limits its own callers. Marking here (rather than lazily, on
+  # whichever account happens to be picked) is what makes the marker visible to
+  # `claude-accounts status`, to a concurrent run in another terminal, and to sync.
+  # The cost is bounded by the scan's own file budget and its clean-result memo.
+  if lim="$(client_limit_scan "$d")"; then
+    mark_client_limit "$d" "${lim%% *}" "${lim##* }"
+    continue
+  fi
   over_threshold "$d" && continue
   eligible+=("$d")
 done
@@ -279,7 +664,7 @@ if [ "${#expired[@]}" -gt 0 ]; then
     last=0
     [ -f "$n" ] && last="$(file_mtime "$n")"
     if [ $((now - last)) -gt 3600 ]; then
-      : > "$n" 2>/dev/null || true
+      : 2>/dev/null > "$n" || true
       printf 'claude-multiacc: %s account(s) unusable (%s) — see: claude-accounts expired\n' \
         "${#expired[@]}" "${ids# }" >&2
     fi
@@ -300,6 +685,30 @@ if [ "${#valid[@]}" -eq 0 ]; then
   exec "$REAL" "$@"
 fi
 
+# ---- rotation ----------------------------------------------------------------
+# Deliberately NOT a full least-recently-used order: just "do not hand back the account
+# you were on a moment ago". That is the whole of the bug (quit a session that ran into
+# its limit, start another, land straight back on it), and it is the only part that can
+# be done without serialising selection. Among equally-ranked candidates the most recent
+# pick is dropped and the REST ARE SAMPLED RANDOMLY — so a burst of parallel `claude -p` runs
+# still spreads across the pool instead of every one of them computing the same "oldest"
+# account and piling onto it.
+# The state is one id in one file. A pool root that cannot be written just leaves a stale
+# id there, which costs one avoided account and nothing else — it can never starve one.
+last_pick_id() { # -> id this pool last handed out, or empty
+  local v=""
+  [ -f "$ACC_ROOT/.last-pick" ] && { IFS= read -r v < "$ACC_ROOT/.last-pick" 2>/dev/null || v=""; }
+  case "$v" in acct-[0-9][0-9]) printf '%s\n' "$v" ;; esac
+}
+
+remember_pick() { # $1 acct dir — best effort. stderr is silenced BEFORE the redirect, or
+                  # a read-only pool root prints "Permission denied" on every single run.
+  local f="$ACC_ROOT/.last-pick" id="${1##*/}"
+  printf '%s\n' "$id" 2>/dev/null > "$f.$$" \
+    && mv -f "$f.$$" "$f" 2>/dev/null || rm -f "$f.$$" 2>/dev/null
+  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
@@ -307,21 +716,84 @@ fi
 PICK_DIR=""
 PICK_SCORE=""
 pick_best() { # args: candidate dirs
-  local d v best="" bestv=1000000 ties=1
+  local d avoid best="" bestv=1000000 ties=0 i n
+  local cand=() score=()
+  avoid="$(last_pick_id)"
   for d in "$@"; do
-    v="$(sel_score_of "$d")"
-    if [ "$v" -lt "$bestv" ]; then
-      bestv="$v"; best="$d"; ties=1
-    elif [ "$v" -eq "$bestv" ]; then
+    cand+=("$d")
+    score+=("$(sel_score_of "$d")")
+  done
+  n=${#cand[@]}
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    [ "${score[$i]}" -lt "$bestv" ] && bestv="${score[$i]}"
+    i=$((i + 1))
+  done
+  # Reservoir-sample among the equally-best, skipping the account just handed out.
+  i=0
+  while [ "$i" -lt "$n" ]; do
+    if [ "${score[$i]}" -eq "$bestv" ] && [ "${cand[$i]##*/}" != "$avoid" ]; then
       ties=$((ties + 1))
-      [ $((RANDOM % ties)) -eq 0 ] && best="$d"   # reservoir-sample among equals
+      [ $((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))
+    done
+  fi
   PICK_DIR="$best"
   PICK_SCORE="$bestv"
 }
 
+# Telemetry going stale is not a per-run detail, it is a pool-wide outage: with no
+# in-window data ANYWHERE every account scores the identical NEUTRAL value, the tie
+# spans the whole pool, and "pick the account with the most headroom" silently becomes
+# "pick any account at all". That is how a fresh session lands on the one account
+# already at 80% of its weekly limit while `claude-accounts status` still shows a
+# reassuring 2% from eleven days ago. It cost eleven days of blind picks once.
+# 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
+blind_age=0       # newest stale reading among the candidates; 0 = never fetched at all
+degraded=0        # 1 = blind, but every candidate had a stale reading still worth using
+assess_telemetry() { # args: the dirs actually being chosen between
+  local d f n=0 stale_ok=0
+  blind=1; blind_age=0; degraded=0
+  for d in "$@"; do
+    n=$((n + 1))
+    if ! telem_blind "$d"; then blind=0; return 0; fi
+    f="$(telem_fetched_at "$d" || echo 0)"
+    # The NEWEST stale reading is the honest age of the outage; an account that was
+    # 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))
+  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.
+  [ "$n" -gt 0 ] && [ "$stale_ok" -eq "$n" ] && degraded=1
+  return 0
+}
+
 if [ "${#eligible[@]}" -gt 0 ]; then
+  # Blindness is judged over the accounts actually being chosen between, not over every
+  # valid one: a FRESH account sitting behind a .limited marker is not a candidate, and
+  # letting it clear the flag would leave the real candidates ranking neutral.
+  assess_telemetry "${eligible[@]}"
+  [ "$degraded" = 1 ] && SEL_DEGRADED=1
   if [ "${CLAUDE_SHIM_SELECT:-headroom}" = "random" ]; then
     PICK_DIR="${eligible[$((RANDOM % ${#eligible[@]}))]}"
   else
@@ -329,37 +801,78 @@ if [ "${#eligible[@]}" -gt 0 ]; then
   fi
 else
   # Every account is limit-marked: degraded service beats a hard failure (100% rule).
+  assess_telemetry "${valid[@]}"
+  [ "$degraded" = 1 ] && SEL_DEGRADED=1
   pick_best "${valid[@]}"
-  sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(fresh_field "$PICK_DIR" weekly_percent || echo '?')%"
+  # Report the number this fallback ACTUALLY ranked on. Asking fresh_field here printed
+  # `weekly=?%` even when the pick was made on a perfectly good stale reading, so anyone
+  # reading only this event concluded the choice had no usage input at all.
+  if [ "$degraded" = 1 ]; then
+    sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(stale_weekly "$PICK_DIR" || echo '?')% ranking=DEGRADED"
+  elif [ "$blind" = 1 ]; then
+    sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=?% ranking=BLIND"
+  else
+    sel_log "all-limited fallback=$(basename "$PICK_DIR") weekly=$(fresh_field "$PICK_DIR" weekly_percent || echo '?')%"
+  fi
 fi
 pick="$PICK_DIR"
+# Remember the pick so the NEXT run does not hand back the same account. An explicit
+# CLAUDE_ACCOUNT pin deliberately does not: a pin is a caller overriding selection,
+# not a turn in the rotation.
+remember_pick "$pick"
 
-# Opportunistic limits refresh: non-blocking, throttled, backgrounded.
+# Opportunistic limits refresh: non-blocking, throttled, backgrounded. The windows are
+# deliberately wide (10m, matching the 5m scheduled pass): the usage endpoint rate-limits
+# its OWN callers, and a fleet of machines polling one account too eagerly earns a 429
+# with Retry-After 3600 — telemetry then goes stale for an hour at a time, which is
+# exactly how every account ends up scoring NEUTRAL.
 kick="$ACC_ROOT/.limits-kick"
 stale=0
 for d in "${valid[@]}"; do
   f="$d/limits.json"
-  if [ ! -f "$f" ] || [ $((now - $(file_mtime "$f"))) -gt 180 ]; then stale=1; break; fi
+  if [ ! -f "$f" ] || [ $((now - $(file_mtime "$f"))) -gt 600 ]; then stale=1; break; fi
 done
 if [ "$stale" = 1 ] && [ -x "$SELF_DIR/claude-accounts" ]; then
   last=0
   [ -f "$kick" ] && last="$(file_mtime "$kick")"
-  if [ $((now - last)) -gt 120 ]; then
-    : > "$kick" 2>/dev/null || true
+  if [ $((now - last)) -gt 600 ]; then
+    : 2>/dev/null > "$kick" || true
     ( "$SELF_DIR/claude-accounts" limits --quiet >/dev/null 2>&1 & ) >/dev/null 2>&1
   fi
 fi
 
 acct="$(basename "$pick")"
-sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')% session=$(fresh_field "$pick" session_percent || echo '?')% pwd=$PWD"
-
-acct_token() { # $1 = acct dir; prints token if the dir must authenticate by token
-  # Token-auth dirs (no local creds), and dirs whose OAuth credential is dead but which
-  # still carry a portable setup-token — the token is the only thing that can work there.
-  if [ -s "$1/server.token" ] && { [ ! -f "$1/.credentials.json" ] || creds_dead "$1"; }; then
-    tr -d '[:space:]' < "$1/server.token"
+if [ "$blind" = 1 ]; then
+  # Two genuinely different states, and an operator debugging this needs to know which:
+  # DEGRADED still ranks, on old readings that remain true; BLIND cannot rank at all and
+  # is a coin flip. Calling both of them "random" would send someone hunting the wrong bug.
+  if [ "$degraded" = 1 ]; then
+    sel_log "$acct weekly=$(stale_weekly "$pick" || echo '?')% session=?% ranking=DEGRADED telemetry-age=${blind_age}s pwd=$PWD"
+  else
+    sel_log "$acct weekly=?% session=?% ranking=BLIND telemetry-age=${blind_age}s 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.
+  if [ -t 2 ]; then
+    n="$ACC_ROOT/.stale-notice"
+    last=0
+    [ -f "$n" ] && last="$(file_mtime "$n")"
+    if [ $((now - last)) -gt 3600 ]; then
+      : 2>/dev/null > "$n" || true
+      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 [ "$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
+      else
+        printf 'claude-multiacc: no usage telemetry for ANY account — selection is running blind (random, not by headroom). Fix: claude-accounts limits --force, then claude-accounts status\n' >&2
+      fi
+    fi
+  fi
+else
+  sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')% session=$(fresh_field "$pick" session_percent || echo '?')% pwd=$PWD"
+fi
 
 export CLAUDE_SHIM_ACTIVE=1
 
@@ -392,6 +905,7 @@ if [ "$wants_retry" = "0" ]; then
   export CLAUDE_CONFIG_DIR="$pick"
   tok="$(acct_token "$pick")"
   [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+  sel_capture_session "$pick"
   exec "$REAL" "$@"
 fi
 
@@ -401,6 +915,7 @@ tmpd="$(mktemp -d "$ACC_ROOT/tmp/shim.XXXXXX" 2>/dev/null)" || {
   export CLAUDE_CONFIG_DIR="$pick"
   tok="$(acct_token "$pick")"
   [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+  sel_capture_session "$pick"
   exec "$REAL" "$@"
 }
 trap 'rm -rf "$tmpd"' EXIT
@@ -412,6 +927,7 @@ if ! : > "$tmpd/out" 2>/dev/null || ! : > "$tmpd/err" 2>/dev/null; then
   export CLAUDE_CONFIG_DIR="$pick"
   tok="$(acct_token "$pick")"
   [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+  sel_capture_session "$pick"
   exec "$REAL" "$@"
 fi
 
@@ -476,7 +992,7 @@ while :; do
       {
         echo "$now"
         echo "reason=$park_reason soft_until=$park_soft marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) detail=$park_detail"
-      } > "$cur/.expired.$$" 2>/dev/null \
+      } 2>/dev/null > "$cur/.expired.$$" \
         && mv -f "$cur/.expired.$$" "$cur/.expired" 2>/dev/null \
         || rm -f "$cur/.expired.$$" 2>/dev/null || true
       sel_log "$(basename "$cur") parked ($park_reason until $park_soft) — see: claude-accounts expired"
@@ -484,7 +1000,7 @@ while :; do
       {
         echo $((now + 600))
         echo "bucket=error-cooldown percent=? marked_at=$(date -u +%Y-%m-%dT%H:%M:%SZ) reason=error-cooldown"
-      } > "$cur/.limited.$$" 2>/dev/null \
+      } 2>/dev/null > "$cur/.limited.$$" \
         && mv -f "$cur/.limited.$$" "$cur/.limited" 2>/dev/null \
         || rm -f "$cur/.limited.$$" 2>/dev/null || true
     fi
@@ -500,6 +1016,9 @@ while :; do
     if [ -n "$next" ]; then
       sel_log "retry from=$(basename "$cur") to=$(basename "$next") rc=$rc"
       cur="$next"
+      # The account that actually serves the work is the one the next run should rotate
+      # away from — not the one that bounced.
+      remember_pick "$cur"
       attempt=2
       continue
     fi