claude-multiacc 1.0.13 → 1.0.15

package/tests/run-tests.sh

@@ -6,7 +6,19 @@ set -u
 
 REPO_DIR="$(cd "$(dirname "$0")/.." && pwd -P)"
 WORK="$(mktemp -d "${TMPDIR:-/tmp}/multiacc-test.XXXXXX")"
-trap 'rm -rf "$WORK"' EXIT
+# Loopback stub servers register their pid here. Deleting $WORK does not kill a running
+# python process, so an interrupted run (CI cancel, Ctrl-C) would otherwise leave one
+# listening until the machine goes away.
+STUB_PIDS=""
+cleanup() {
+  local p
+  for p in $STUB_PIDS; do
+    kill "$p" 2>/dev/null
+    wait "$p" 2>/dev/null || true
+  done
+  rm -rf "$WORK"
+}
+trap cleanup EXIT
 
 PASS=0
 FAIL=0
@@ -74,6 +86,22 @@ for a in "$@"; do
     --echo-stdin) cat; exit 0 ;;
   esac
 done
+if [ -n "${FAKE_SESSION_ID:-}" ] && [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+  # Mimic the real client: register the run in the ACCOUNT dir for its lifetime, write
+  # the session transcript into the (shared) projects tree, delete the registry on exit.
+  mkdir -p "$CLAUDE_CONFIG_DIR/sessions" "$CLAUDE_CONFIG_DIR/projects/-proj"
+  printf '{"pid":%s,"sessionId":"%s","cwd":"/proj","kind":"interactive","startedAt":%s000}\n' \
+    "$$" "$FAKE_SESSION_ID" "$(date -u +%s)" > "$CLAUDE_CONFIG_DIR/sessions/$$.json"
+  printf '{"type":"mode","mode":"normal","sessionId":"%s"}\n' "$FAKE_SESSION_ID" \
+    > "$CLAUDE_CONFIG_DIR/projects/-proj/$FAKE_SESSION_ID.jsonl"
+  if [ -n "${FAKE_LIMIT_RESET:-}" ]; then
+    printf '{"type":"assistant","timestamp":"%s","message":{"content":[{"type":"text","text":"You'"'"'ve hit your session limit"}]},"quotaLimits":{"status":"rejected","resetsAt":%s,"unifiedRateLimitFallbackAvailable":false,"rateLimitType":"five_hour","overageStatus":"rejected"},"error":"rate_limit","isApiErrorMessage":true,"apiErrorStatus":429,"sessionId":"%s"}\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" "$FAKE_LIMIT_RESET" "$FAKE_SESSION_ID" \
+      >> "$CLAUDE_CONFIG_DIR/projects/-proj/$FAKE_SESSION_ID.jsonl"
+  fi
+  sleep "${FAKE_SESSION_HOLD:-4}"
+  rm -f "$CLAUDE_CONFIG_DIR/sessions/$$.json"
+fi
 echo "CFG=$acct TOK=${CLAUDE_CODE_OAUTH_TOKEN:-none}"
 EOF
 chmod +x "$FAKEBIN/claude"
@@ -86,6 +114,10 @@ export CLAUDE_MULTIACC_NO_SYNC=1
 # Fixtures are local file:// URLs with no rate limit, so the anti-429 fetch throttle
 # is off by default here; the throttle test re-enables it explicitly.
 export CLAUDE_MULTIACC_MIN_FETCH=0
+# The client-rate-limit scan memoizes a CLEAN result for a few seconds; tests plant
+# rejections and expect them seen on the very next run, so the memo is off by default
+# here (12i re-enables it to prove the memo itself works).
+export CLAUDE_MULTIACC_CLIENT_SCAN_TTL=0
 # The oauth token endpoint must NEVER be hit for real from tests: default to a missing
 # file:// fixture (refresh fails fast, offline); the refresh tests override per-case.
 export CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-endpoint-missing.json"
@@ -210,6 +242,19 @@ out="$(CLAUDE_ACCOUNT=acct-07 claude 2>&1)"
 check "pin to auth-less dir (ceremony)" "CFG=acct-07" "$out"
 rmdir "$ACC/acct-07"
 
+# ---- 6c. pin uses the portable token when the credential beside it is DEAD ----
+# Regression: the pin path used to export the token only when NO credential file
+# existed, so pinning an account whose login had died failed with "OAuth session
+# expired" even though its setup-token was sitting right there — the exact state a
+# fleet-distributed token lands in on a machine that still has a stale login.
+mkdir -p "$ACC/acct-07"
+printf '{"claudeAiOauth":{"accessToken":"dead","refreshToken":"","expiresAt":0,"refreshTokenExpiresAt":1}}' \
+  > "$ACC/acct-07/.credentials.json"
+printf 'sk-ant-oat01-PINNEDDEADCREDSPINNEDDEADCREDSPINNEDDEADCREDS00' > "$ACC/acct-07/server.token"
+out="$(CLAUDE_ACCOUNT=acct-07 claude 2>&1)"
+check "pinned dead-credential account still runs under its token" "TOK=sk-ant-oat01-PINNED" "$out"
+rm -rf "$ACC/acct-07"
+
 # ---- 7. limited marker excludes account ------------------------------------
 printf '%s\nbucket=weekly_scoped:Fable percent=95 reason=limits\n' "$((now+3600))" > "$ACC/acct-01/.limited"
 all2=1
@@ -508,6 +553,361 @@ CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-mid.json" claude-accounts limits -
 [ -f "$ACC/acct-01/.limited" ] && t_ok "error-cooldown marker survives clean limits refresh" || t_fail "cooldown vs limits" "marker was cleared early"
 rm -f "$ACC/acct-01/.limited"
 
+# ---- 12f-12h. client-reported rate limits + rotation (own two-account pool) -------
+# The shared pool has picked up a third account by now, so these run in an instance root
+# of their own: with exactly two accounts, "went somewhere else" and "rotated" are both
+# unambiguous.
+CLP="$WORK/client-limit-pool"
+mkdir -p "$CLP/tmp"
+: > "$CLP/.limits-kick"
+cat > "$CLP/accounts.json" <<'EOF'
+{"version":1,"threshold":90,"accounts":[
+  {"id":"acct-01","email":"cl1@test","home":"mac","added_at":"2026-07-13T00:00:00Z"},
+  {"id":"acct-02","email":"cl2@test","home":"mac","added_at":"2026-07-13T00:00:00Z"}]}
+EOF
+for i in 01 02; do
+  mkdir -p "$CLP/acct-$i"
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-cl%s","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' "$i" > "$CLP/acct-$i/.credentials.json"
+done
+export CLAUDE_ACCOUNTS_ROOT="$CLP"
+ACC_SAVED="$ACC"
+ACC="$CLP"
+
+# ---- 12f. a rate limit hit by an INTERACTIVE session takes its account out ---------
+# The reported bug: a tmux session runs into its 5h limit, the user quits and starts
+# `claude` again, and the pool hands back the same dead account. Interactive runs are
+# exec'd, so the -p retry path above never sees them — the only trace of the rejection
+# is the one Claude Code writes itself, in the session transcript.
+mkclientlimit() { # mkclientlimit <acct dir> <session id> <resetsAt> [rejection ISO ts]
+  mkdir -p "$1/projects/-proj"
+  printf '{"type":"mode","mode":"normal","sessionId":"%s"}\n' "$2" > "$1/projects/-proj/$2.jsonl"
+  printf '{"type":"assistant","timestamp":"%s","message":{"content":[{"type":"text","text":"limit"}]},"quotaLimits":{"status":"rejected","resetsAt":%s,"unifiedRateLimitFallbackAvailable":false,"rateLimitType":"five_hour","overageStatus":"rejected"},"error":"rate_limit","isApiErrorMessage":true,"apiErrorStatus":429,"sessionId":"%s"}\n' \
+    "${4:-$(date -u +%Y-%m-%dT%H:%M:%S.000Z)}" "$3" "$2" >> "$1/projects/-proj/$2.jsonl"
+  # index line = "<id> <ISO claim>": the account that owned the session, and from when
+  printf '%s %s\n' "$2" "$(date -u -r "$(( $(date +%s) - 600 ))" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "@$(( $(date +%s) - 600 ))" +%Y-%m-%dT%H:%M:%SZ)" > "$1/.sessions-index"
+}
+SID1="81bf8b20-013f-4414-8878-e0289bec9ad0"
+RESET1=$(( $(date +%s) + 1800 ))
+mkclientlimit "$ACC/acct-01" "$SID1" "$RESET1"
+all2=1
+for _ in $(seq 1 12); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "client-reported rate limit excludes the account" \
+  || t_fail "client rate limit" "the rejected account was picked again"
+first="$(head -1 "$ACC/acct-01/.limited" 2>/dev/null)"
+[ "$first" = "$RESET1" ] && t_ok "marker carries the API's own reset time" \
+  || t_fail "client marker reset" "want $RESET1, got '${first:-<none>}'"
+grep -q 'reason=client-rate-limit' "$ACC/acct-01/.limited" 2>/dev/null \
+  && t_ok "marker is tagged client-rate-limit" || t_fail "client marker reason" "$(cat "$ACC/acct-01/.limited" 2>/dev/null)"
+out="$(CLAUDE_ACCOUNT=acct-01 claude 2>&1)"
+check "explicit pin still wins over a client-reported limit" "CFG=acct-01" "$out"
+
+# a marker the client earned survives a clean telemetry pass while its window is open
+CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-mid.json" claude-accounts limits --quiet
+[ -f "$ACC/acct-01/.limited" ] && t_ok "client-rate-limit marker survives a clean limits refresh" \
+  || t_fail "client marker vs limits" "marker was cleared while the window was still open"
+rm -f "$ACC/acct-01/.limited"
+
+# an ALREADY-ELAPSED rejection is history, not an exclusion
+mkclientlimit "$ACC/acct-01" "$SID1" "$(( $(date +%s) - 60 ))"
+hits1=0
+for _ in $(seq 1 12); do
+  case "$(claude 2>&1)" in *CFG=acct-01*) hits1=$((hits1+1)) ;; esac
+done
+{ [ "$hits1" -gt 0 ] && [ ! -f "$ACC/acct-01/.limited" ]; } \
+  && t_ok "an elapsed client rejection does not exclude" \
+  || t_fail "elapsed client rejection" "acct-01 hits=$hits1 marker=$([ -f "$ACC/acct-01/.limited" ] && echo yes || echo no)"
+
+# opt-out
+mkclientlimit "$ACC/acct-01" "$SID1" "$(( $(date +%s) + 1800 ))"
+rm -f "$ACC/acct-01/.limited"
+hits1=0
+for _ in $(seq 1 12); do
+  case "$(CLAUDE_MULTIACC_CLIENT_LIMITS=0 claude 2>&1)" in *CFG=acct-01*) hits1=$((hits1+1)) ;; esac
+done
+{ [ "$hits1" -gt 0 ] && [ ! -f "$ACC/acct-01/.limited" ]; } \
+  && t_ok "CLAUDE_MULTIACC_CLIENT_LIMITS=0 turns the scan off" \
+  || t_fail "client-limit opt-out" "still excluded with the scan disabled"
+
+# a hostile session index must not walk out of the pool
+printf '../../../../etc/passwd x\n-e x\n%s %s\n' "$SID1" "2026-01-01T00:00:00Z" > "$ACC/acct-01/.sessions-index"
+claude >/dev/null 2>&1
+grep -q 'reason=client-rate-limit' "$ACC/acct-01/.limited" 2>/dev/null \
+  && t_ok "traversal and option-shaped ids are ignored, real ids still scanned" \
+  || t_fail "session index traversal" "scan broke on a hostile entry"
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index
+rm -rf "$ACC"/acct-0*/projects
+
+# ---- 12g. the whole round trip: a run registers itself, the NEXT run avoids it -----
+# No .sessions-index is planted here. The shim's detached capture has to learn the
+# session id from $acct/sessions/<pid>.json WHILE the run is alive — after it exits the
+# client deletes that file and nothing else can name the transcript.
+rm -f "$ACC/.pick-seq" "$ACC"/acct-0*/.last-pick
+FAKE_SESSION_ID="9f3c1d2e-0000-4000-8000-abcdefabcdef" \
+  FAKE_LIMIT_RESET="$(( $(date +%s) + 1800 ))" \
+  FAKE_SESSION_HOLD=5 claude >/dev/null 2>&1
+hit="$(ls "$ACC"/acct-0*/.sessions-index 2>/dev/null | head -1)"
+limited_dir="$(dirname "${hit:-/nonexistent}")"
+[ -n "$hit" ] && t_ok "the run's own session id is captured while it is alive" \
+  || t_fail "session capture" "no .sessions-index was written"
+out="$(claude 2>&1)"
+case "$out" in
+  *"CFG=$(basename "$limited_dir")"*)
+    t_fail "restart after a limit hit" "landed straight back on $(basename "$limited_dir")" ;;
+  *) t_ok "quitting a limit-hit session and restarting lands on another account" ;;
+esac
+grep -q 'reason=client-rate-limit' "$limited_dir/.limited" 2>/dev/null \
+  && t_ok "the account that hit the limit is marked from its own transcript" \
+  || t_fail "post-run marking" "no client-rate-limit marker on $(basename "$limited_dir")"
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+
+# ---- 12h. equal-headroom picks ROTATE instead of re-rolling a coin -----------------
+# With telemetry stale (the usage endpoint 429s its own callers for hours) every account
+# scores NEUTRAL, so this tie-break is the only thing standing between a restart and the
+# account it just walked away from.
+rm -f "$ACC/.pick-seq" "$ACC"/acct-0*/.last-pick "$ACC"/acct-0*/limits.json
+seq_out=""
+for _ in $(seq 1 8); do
+  case "$(claude 2>&1)" in
+    *CFG=acct-01*) seq_out="${seq_out}1" ;;
+    *CFG=acct-02*) seq_out="${seq_out}2" ;;
+    *) seq_out="${seq_out}?" ;;
+  esac
+done
+case "$seq_out" in
+  12121212|21212121) t_ok "equal-score picks round-robin across the pool ($seq_out)" ;;
+  *) t_fail "round-robin tie-break" "sequence $seq_out (want strict alternation)" ;;
+esac
+# ... and the rotation must never override real headroom
+lj 80 10 80 > "$ACC/acct-01/limits.json"
+lj 20 10 20 > "$ACC/acct-02/limits.json"
+all2=1
+for _ in $(seq 1 8); do
+  case "$(claude 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "rotation never outranks measured headroom" \
+  || t_fail "rotation vs headroom" "rotation pulled work onto the busier account"
+rm -f "$ACC"/acct-0*/limits.json "$ACC/.pick-seq" "$ACC"/acct-0*/.last-pick
+
+# ---- 12i. the clean-scan memo throttles re-reads without stranding a limit ---------
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.client-scan "$ACC"/acct-0*/.sessions-index
+rm -rf "$ACC"/acct-0*/projects
+mkdir -p "$ACC/acct-01/projects/-proj"
+printf '{"type":"mode","mode":"normal","sessionId":"%s"}\n' "$SID1" > "$ACC/acct-01/projects/-proj/$SID1.jsonl"
+printf '%s %s\n' "$SID1" "2026-01-01T00:00:00Z" > "$ACC/acct-01/.sessions-index"
+claude >/dev/null 2>&1     # a clean scan over a real (rejection-free) transcript
+[ -f "$ACC/acct-01/.client-scan" ] \
+  && t_ok "a clean client scan is memoized" || t_fail "clean scan memo" "no .client-scan written"
+mkclientlimit "$ACC/acct-01" "$SID1" "$(( $(date +%s) + 1800 ))"
+CLAUDE_MULTIACC_CLIENT_SCAN_TTL=3600 claude >/dev/null 2>&1
+[ ! -f "$ACC/acct-01/.limited" ] \
+  && t_ok "the memo suppresses a re-read inside its window" \
+  || t_fail "clean scan memo" "rescanned inside the memo window"
+rm -f "$ACC"/acct-0*/.client-scan
+claude >/dev/null 2>&1
+grep -q 'reason=client-rate-limit' "$ACC/acct-01/.limited" 2>/dev/null \
+  && t_ok "once the memo lapses the rejection is seen" \
+  || t_fail "clean scan memo" "the rejection was never picked up"
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.client-scan "$ACC"/acct-0*/.sessions-index
+rm -rf "$ACC"/acct-0*/projects
+
+# ---- 12j. codex-review: corrupt pool numbers never reach bash arithmetic -----------
+# An out-of-range value in any scraped number makes `[ x -lt y ]` print "integer
+# expression expected" on STDERR — which a service-spawned `claude -p` must never see —
+# and makes $((x + 1)) wrap negative.
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.client-scan "$ACC"/acct-0*/.sessions-index
+rm -rf "$ACC"/acct-0*/projects
+BIG="99999999999999999999999999999999"
+printf '%s\n' "$BIG" > "$ACC/.last-pick"
+printf '{"fetched_at":%s,"weekly_percent":%s,"session_percent":1,"max_percent":%s,"buckets":[]}' "$BIG" "$BIG" "$BIG" > "$ACC/acct-02/limits.json"
+err="$(claude 2>&1 >/dev/null)"
+[ -z "$err" ] && t_ok "absurd pool numbers keep stderr byte-clean" \
+  || t_fail "corrupt number handling" "stderr: $(printf '%s' "$err" | head -c 160)"
+out="$(claude 2>/dev/null)"
+case "$out" in *CFG=acct-0*) t_ok "selection still works with corrupt numbers ($out)" ;;
+  *) t_fail "corrupt number handling" "selection produced: $out" ;; esac
+# caller-supplied numbers are just as capable of reaching `[ -lt ]` as pool state
+: > "$ACC/acct-01/.client-scan"
+err="$(CLAUDE_MULTIACC_CLIENT_SCAN_TTL=bogus CLAUDE_MULTIACC_THRESHOLD=nonsense claude 2>&1 >/dev/null)"
+out="$(CLAUDE_MULTIACC_CLIENT_SCAN_TTL=bogus CLAUDE_MULTIACC_THRESHOLD=nonsense claude 2>/dev/null)"
+{ [ -z "$err" ] && case "$out" in *CFG=acct-0*) true ;; *) false ;; esac; } \
+  && t_ok "garbage in the client-scan TTL / threshold env vars keeps stderr clean" \
+  || t_fail "env number validation" "stderr: $(printf '%s' "$err" | head -c 160) out: $out"
+rm -f "$ACC"/acct-0*/.client-scan
+
+printf '%s\nbucket=x percent=? reason=limits\n' "$BIG" > "$ACC/acct-01/.limited"
+err="$(claude 2>&1 >/dev/null)"
+{ [ -z "$err" ] && [ -f "$ACC/acct-01/.limited" ]; } \
+  && t_ok "an absurd .limited reset reads as LIMITED, silently" \
+  || t_fail "corrupt marker handling" "stderr: $(printf '%s' "$err" | head -c 160)"
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/limits.json "$ACC/.last-pick"
+
+# ---- 12m. a session id belongs to ONE account, and only from when it took it over ---
+# `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 an id claimed by acct-02 must stop being acct-01's evidence, and a rejection
+# recorded before the handover must not be charged to the new owner.
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+SIDC="0badc0de-1111-4111-8111-abcdefabcdef"
+NOWS="$(date -u +%s)"
+OLDISO="$(date -u -r "$((NOWS - 7200))" +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || date -u -d "@$((NOWS - 7200))" +%Y-%m-%dT%H:%M:%S.000Z)"
+# acct-01 ran the session two hours ago and hit a limit then; acct-02 has just resumed it.
+mkclientlimit "$ACC/acct-01" "$SIDC" "$((NOWS + 1800))" "$OLDISO"
+mkdir -p "$ACC/acct-02/sessions" "$ACC/acct-02/projects"
+ln -s "$ACC/acct-01/projects/-proj" "$ACC/acct-02/projects/-proj"
+printf '{"pid":4242,"sessionId":"%s","cwd":"/proj","kind":"interactive","startedAt":%s000}\n' \
+  "$SIDC" "$NOWS" > "$ACC/acct-02/sessions/4242.json"
+claude >/dev/null 2>&1
+grep -q -- "^$SIDC " "$ACC/acct-02/.sessions-index" 2>/dev/null \
+  && t_ok "a resumed session id is claimed by the account now running it" \
+  || t_fail "session id handover" "acct-02 never claimed the resumed id"
+grep -q -- "^$SIDC " "$ACC/acct-01/.sessions-index" 2>/dev/null \
+  && t_fail "session id handover" "acct-01 still claims an id acct-02 took over" \
+  || t_ok "the previous owner releases a resumed session id"
+[ ! -f "$ACC/acct-02/.limited" ] \
+  && t_ok "a rejection older than the handover is not charged to the new owner" \
+  || t_fail "claim-time scoping" "acct-02 was marked for a limit acct-01 hit"
+rm -f "$ACC/acct-02/projects/-proj" "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+
+# two accounts claiming the SAME id (a crossed race, or corrupt state) must not both be
+# marked off one shared transcript — at most the newer claimant may answer for it
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+SIDD="0dadc0de-2222-4222-8222-abcdefabcdef"   # hex only, or sess_id_ok drops it and the
+                                             # scan never reaches the conflict check
+NOWD="$(date -u +%s)"
+mkclientlimit "$ACC/acct-01" "$SIDD" "$((NOWD + 1800))"
+mkdir -p "$ACC/acct-02/projects"
+ln -s "$ACC/acct-01/projects/-proj" "$ACC/acct-02/projects/-proj"
+CLAIM1="$(cat "$ACC/acct-01/.sessions-index")"
+printf '%s\n' "$CLAIM1" > "$ACC/acct-02/.sessions-index"    # identical id AND claim
+claude >/dev/null 2>&1
+n_marked=0
+for d in "$ACC/acct-01" "$ACC/acct-02"; do [ -f "$d/.limited" ] && n_marked=$((n_marked+1)); done
+[ "$n_marked" -eq 0 ] \
+  && t_ok "an id claimed by two accounts marks neither (ambiguity => no attribution)" \
+  || t_fail "duplicate session claim" "$n_marked accounts were marked off one transcript"
+# ...and it is the NEWEST rival claim that decides, not whichever one grep prints first
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.client-scan
+{ printf '%s 2020-01-01T00:00:00Z\n' "$SIDD"; printf '%s 2090-01-01T00:00:00Z\n' "$SIDD"; } \
+  > "$ACC/acct-02/.sessions-index"
+claude >/dev/null 2>&1
+[ ! -f "$ACC/acct-01/.limited" ] \
+  && t_ok "a stale rival claim does not hide a newer one" \
+  || t_fail "duplicate session claim" "only the first rival claim was inspected"
+rm -f "$ACC/acct-02/projects/-proj" "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+
+# a SYMLINKED registry entry belongs to whatever it points at, not to this account
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+FOREIGN="$WORK/foreign-session.json"
+printf '{"pid":9,"sessionId":"%s","cwd":"/proj","kind":"interactive","startedAt":%s000}\n' \
+  "$SID1" "$(( $(date -u +%s) - 600 ))" > "$FOREIGN"
+mkclientlimit "$ACC/acct-01" "$SID1" "$(( $(date +%s) + 1800 ))"
+rm -f "$ACC/acct-01/.sessions-index"
+mkdir -p "$ACC/acct-01/sessions"
+ln -s "$FOREIGN" "$ACC/acct-01/sessions/9.json"
+claude >/dev/null 2>&1
+[ ! -f "$ACC/acct-01/.limited" ] \
+  && t_ok "a symlinked session registry entry is not this account's evidence" \
+  || t_fail "symlinked registry entry" "a foreign registry entry marked the account LIMITED"
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+
+# ---- 12n. an option-shaped session id must not hang the shim before exec ------------
+# "-e" is hex+dash, so a charset check alone lets it through; grep then treats it as a
+# flag, loses its file operand and blocks on the shim's OWN stdin — a hang before exec.
+rm -f "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+mkdir -p "$ACC/acct-01/sessions"
+printf '{"pid":7,"sessionId":"-e","cwd":"/proj","kind":"interactive","startedAt":%s000}\n' "$(date -u +%s)" \
+  > "$ACC/acct-01/sessions/7.json"
+printf 'deadbeef 2026-01-01T00:00:00Z\n' > "$ACC/acct-01/.sessions-index"
+FIFO="$WORK/hangfifo"
+rm -f "$FIFO"; mkfifo "$FIFO"
+exec 9<>"$FIFO"                       # holds the fifo open: stdin that never EOFs
+( claude < "$FIFO" > "$WORK/hang.out" 2>&1 ) &
+hangpid=$!
+waited=0
+while [ "$waited" -lt 10 ] && kill -0 "$hangpid" 2>/dev/null; do sleep 1; waited=$((waited+1)); done
+if kill -0 "$hangpid" 2>/dev/null; then
+  kill -9 "$hangpid" 2>/dev/null
+  t_fail "option-shaped session id" "the shim hung for ${waited}s before exec"
+else
+  wait "$hangpid" 2>/dev/null || true
+  case "$(cat "$WORK/hang.out" 2>/dev/null)" in
+    *CFG=acct-0*) t_ok "an option-shaped session id neither hangs nor breaks selection" ;;
+    *) t_fail "option-shaped session id" "selection produced: $(head -c 120 "$WORK/hang.out")" ;;
+  esac
+fi
+exec 9>&-
+rm -f "$FIFO" "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/sessions
+
+# a SHARED session registry proves nothing about which account ran what
+rm -f "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects "$ACC"/acct-0*/sessions
+SHAREDS="$WORK/cl-shared-sessions"
+mkdir -p "$SHAREDS"
+printf '{"pid":1,"sessionId":"%s","cwd":"/proj","kind":"interactive","startedAt":%s000}\n' "$SID1" "$(date -u +%s)" > "$SHAREDS/1.json"
+for i in 01 02; do ln -s "$SHAREDS" "$ACC/acct-$i/sessions"; done
+mkclientlimit "$ACC/acct-01" "$SID1" "$(( $(date +%s) + 1800 ))"
+rm -f "$ACC/acct-01/.sessions-index"      # only the shared registry could supply the id
+claude >/dev/null 2>&1
+{ [ ! -f "$ACC/acct-01/.limited" ] && [ ! -f "$ACC/acct-02/.limited" ]; } \
+  && t_ok "a shared session registry never marks an account (fail open)" \
+  || t_fail "shared session registry" "a shared registry marked an account LIMITED"
+rm -f "$ACC"/acct-0*/sessions "$ACC"/acct-0*/.limited "$ACC"/acct-0*/.sessions-index "$ACC"/acct-0*/.client-scan
+rm -rf "$ACC"/acct-0*/projects
+
+# ---- 12k. codex-review: rotation must not serialise a parallel burst ---------------
+# The first cut of this used a monotonic counter and picked the account with the OLDEST
+# stamp. Every member of a concurrent burst reads the same stamps, computes the same
+# "oldest", and piles onto one account. Rotation only ever drops the ONE account just
+# handed out; everything else is still sampled at random.
+rm -f "$ACC/.last-pick" "$ACC"/acct-0*/limits.json "$ACC"/acct-0*/.limited
+# THREE accounts on purpose. Rotation drops the one just handed out, so in a two-account
+# pool a burst legitimately lands entirely on the single alternative and the test would
+# be measuring nothing (it flaked exactly that way on Linux). With three, the burst must
+# spread over the two that remain — which is precisely what the counter version could not.
+mkdir -p "$ACC/acct-09"
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-cl09","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-09/.credentials.json"
+: > "$WORK/burst.out"
+for _ in $(seq 1 16); do ( claude >> "$WORK/burst.out" 2>&1 ) & done
+wait
+b_distinct="$(grep -o 'CFG=acct-[0-9]*' "$WORK/burst.out" | sort -u | tr '\n' ' ')"
+b_n="$(printf '%s' "$b_distinct" | wc -w | tr -d ' ')"
+[ "$b_n" -ge 2 ] \
+  && t_ok "a parallel burst still spreads across the pool ($b_distinct)" \
+  || t_fail "burst spreading" "all 16 concurrent runs took $b_distinct — rotation serialised the burst"
+rm -rf "$ACC/acct-09"
+
+# ---- 12l. codex-review: an unwritable pool root never prints to stderr --------------
+# `cmd > file 2>/dev/null` does NOT silence a failed redirect: bash applies the
+# redirections in order, so the open fails while stderr is still the caller's.
+RO="$WORK/readonly-pool"
+mkdir -p "$RO/acct-01" "$RO/acct-02"
+cp "$ACC/accounts.json" "$RO/accounts.json"
+for i in 01 02; do
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-ro","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$RO/acct-$i/.credentials.json"
+done
+: > "$RO/.limits-kick"
+chmod 555 "$RO" "$RO/acct-01" "$RO/acct-02"
+err="$(CLAUDE_ACCOUNTS_ROOT="$RO" claude 2>&1 >/dev/null)"
+out="$(CLAUDE_ACCOUNTS_ROOT="$RO" claude 2>/dev/null)"
+chmod 755 "$RO" "$RO/acct-01" "$RO/acct-02"
+[ -z "$err" ] && t_ok "a read-only pool root keeps stderr byte-clean" \
+  || t_fail "read-only pool root" "stderr: $(printf '%s' "$err" | head -c 200)"
+case "$out" in *CFG=acct-0*) t_ok "a read-only pool root still selects ($out)" ;;
+  *) t_fail "read-only pool root" "selection produced: $out" ;; esac
+
+ACC="$ACC_SAVED"
+unset CLAUDE_ACCOUNTS_ROOT
+
 # ---- 12e. TTY stdin: retry disabled so the terminal is never swapped for /dev/null --
 if command -v script >/dev/null 2>&1; then
   # `claude -p` on a TTY with no prompt arg reads the terminal. Under a PTY the shim
@@ -892,7 +1292,20 @@ d['backoff'] = 600
 json.dump(d, open(p + '.tmp', 'w'), indent=1); os.replace(p + '.tmp', p)
 EOF
 out="$(CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
-check "429 backoff honored" "acct-01: backing off after 429" "$out"
+# A backoff with no recorded cause (an older build wrote these) still reports honestly
+# rather than blaming a 429 it never saw.
+check "backoff honored" "acct-01: backing off after a failed fetch" "$out"
+# ...and when the cause IS on record, the skip message names it. Calling every park a
+# 429 is exactly how an unauthorized account read as merely rate-limited for 11 days.
+python3 - "$ACC/acct-01/limits.json" <<'EOF'
+import json, os, sys, time
+p = sys.argv[1]
+d = json.load(open(p))
+d['last_error'] = 'HTTP 403 (source=token) — permanent, server said do not retry'
+json.dump(d, open(p + '.tmp', 'w'), indent=1); os.replace(p + '.tmp', p)
+EOF
+out="$(CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+check "a skipped account names the error it is backing off from" "backing off after HTTP 403" "$out"
 out="$(CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
 check "--force overrides backoff" "acct-01: ok" "$out"
 python3 -c "
@@ -993,17 +1406,30 @@ grep -q "sk-ant-oat01-recent" "$ACC/acct-05/.credentials.json" \
 [ ! -f "$ACC/acct-05/.oauth-refresh.json" ] && t_ok "no backoff recorded for a gated (skipped) refresh" \
   || t_fail "gated refresh backoff" ".oauth-refresh.json written despite the gate"
 
-# ---- 16b7. server.token accounts are NEVER oauth-refreshed (token bearer wins) ---------
+# ---- 16b7. OAuth is preferred over a setup token FOR TELEMETRY ------------------------
+# This used to be the other way round — a server.token short-circuited the oauth refresh,
+# on the reasoning that a non-rotating credential is the safer one to spend. That
+# reasoning inverted the moment we learned the usage endpoint refuses setup tokens
+# outright (403, no user:profile scope): preferring the token means no telemetry AT ALL,
+# for an account whose refresh grant was perfectly good. Order is now oauth > refresh
+# grant > token, and the rotation-safety gate (16b6) still guards the grant itself.
 printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-x","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' > "$ACC/acct-05/.credentials.json"
 printf 'sk-ant-oat01-portable-token-05' > "$ACC/acct-05/server.token"
 rm -f "$ACC/acct-05/limits.json" "$ACC/acct-05/.oauth-refresh.json"
 out="$(CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
-check "token-bearer account fetches without refresh" "acct-05: ok" "$out"
+check "an account with both credentials still fetches" "acct-05: ok" "$out"
 grep -q "sk-ant-oat01-refreshednew" "$ACC/acct-05/.credentials.json" \
-  && t_fail "server.token exempts oauth refresh" "oauth creds were rotated despite a portable token" \
-  || t_ok "server.token account never oauth-refreshed (grant not run)"
+  && t_ok "a usable refresh grant is used even when a server.token sits beside it" \
+  || t_fail "oauth preferred for telemetry" "the setup token short-circuited the refresh grant"
+python3 -c "import json,sys; sys.exit(0 if json.load(open('$ACC/acct-05/limits.json'))['source']=='oauth' else 1)" \
+  && t_ok "telemetry is fetched with the OAuth bearer, not the setup token" \
+  || t_fail "bearer source" "source != oauth"
+# ...and the token is still the fallback when there is no oauth path at all.
+rm -f "$ACC/acct-05/.credentials.json" "$ACC/acct-05/limits.json"
+out="$(CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
 python3 -c "import json,sys; sys.exit(0 if json.load(open('$ACC/acct-05/limits.json'))['source']=='token' else 1)" \
-  && t_ok "telemetry fetched via the portable token" || t_fail "token bearer source" "source != token"
+  && t_ok "with no oauth credential the setup token is still tried" \
+  || t_fail "token fallback" "source != token"
 rm -f "$ACC/acct-05/server.token"
 
 # ---- 16b9. a 4xx from the TOKEN endpoint must not park the whole pool -----------------
@@ -1038,6 +1464,7 @@ EOF
 port=""
 python3 "$srv_script" > "$WORK/token-port" 2>/dev/null &
 srv_pid=$!
+STUB_PIDS="$STUB_PIDS $srv_pid"
 for _ in $(seq 1 20); do
   port="$(head -1 "$WORK/token-port" 2>/dev/null)"
   case "$port" in ''|*[!0-9]*) port=""; sleep 0.2 ;; *) break ;; esac
@@ -1073,6 +1500,459 @@ else
   rm -f "$dead_acct/.expired" "$dead_acct/.oauth-refresh.json"
 fi
 
+# ---- 16b9b. the usage endpoint's PERMANENT refusals ----------------------------------
+# 2026-08-22: every account in the fleet had ranked NEUTRAL for eleven days, so `claude`
+# was picking at random and a fresh session landed on the account already at 80% of its
+# weekly limit. The chain: the pool's OAuth grants lapsed, the fetcher fell back to the
+# portable setup token, and the usage endpoint refuses THAT with
+#   403 {"type":"permission_error","message":"OAuth token does not meet scope
+#        requirement user:profile"}      x-should-retry: false
+# because a setup token is minted without user:profile. Only a 429 used to record a
+# backoff, so the refusal was re-issued every scheduled pass from every machine — and
+# those retries are what earned the 429s that made an UNAUTHORIZED account look merely
+# RATE LIMITED, hiding the real cause behind a plausible one for eleven days.
+usrv="$WORK/usage-server.py"
+cat > "$usrv" <<'EOF'
+import http.server, json, sys
+LOG = sys.argv[1]
+class H(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *a): pass
+    def do_GET(self):
+        with open(LOG, 'a') as f:
+            f.write(self.path + '\n')
+        if self.path == '/scope-denied':
+            raw = json.dumps({'type': 'error', 'error': {
+                'type': 'permission_error',
+                'message': 'OAuth token does not meet scope requirement user:profile'}}).encode()
+            self.send_response(403)
+            self.send_header('x-should-retry', 'false')
+        elif self.path == '/boom':
+            raw = b'{"error":"server"}'
+            self.send_response(500)
+        elif self.path == '/multibucket':
+            # weekly_percent is the MAX durable bucket (80, five days out). The cheap
+            # monthly bucket resets in an hour and says nothing about it.
+            import time as _t
+            def iso(dt):
+                return _t.strftime('%Y-%m-%dT%H:%M:%S+00:00', _t.gmtime(_t.time() + dt))
+            raw = json.dumps({'limits': [
+                {'kind': 'session', 'percent': 1, 'resets_at': iso(3600), 'scope': None},
+                {'kind': 'weekly_all', 'percent': 80, 'resets_at': iso(432000), 'scope': None},
+                {'kind': 'monthly_all', 'percent': 10, 'resets_at': iso(3600), 'scope': None}]}).encode()
+            self.send_response(200)
+        else:
+            raw = json.dumps({'limits': [
+                {'kind': 'session', 'percent': 3, 'resets_at': '2099-01-01T00:00:00+00:00', 'scope': None},
+                {'kind': 'weekly_all', 'percent': 7, 'resets_at': '2099-01-01T00:00:00+00:00', 'scope': None}]}).encode()
+            self.send_response(200)
+        self.send_header('Content-Type', 'application/json')
+        self.send_header('Content-Length', str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+srv = http.server.HTTPServer(('127.0.0.1', 0), H)
+print(srv.server_address[1], flush=True)
+srv.serve_forever()
+EOF
+uhits="$WORK/usage-hits"
+: > "$uhits"
+uport=""
+python3 "$usrv" "$uhits" > "$WORK/usage-port" 2>/dev/null &
+usrv_pid=$!
+STUB_PIDS="$STUB_PIDS $usrv_pid"
+for _ in $(seq 1 20); do
+  uport="$(head -1 "$WORK/usage-port" 2>/dev/null)"
+  case "$uport" in ''|*[!0-9]*) uport=""; sleep 0.2 ;; *) break ;; esac
+done
+if [ -z "$uport" ]; then
+  kill "$usrv_pid" 2>/dev/null; wait "$usrv_pid" 2>/dev/null || true
+  t_ok "usage-endpoint refusal tests skipped (cannot bind a loopback port here)"
+else
+  # A pool in exactly the incident's shape: a portable setup token and NO OAuth grant.
+  SD="$WORK/scope-denied-pool"
+  mkdir -p "$SD/acct-01" "$SD/acct-02" "$SD/tmp"
+  : > "$SD/.limits-kick"
+  cat > "$SD/accounts.json" <<'EOF'
+{"version":1,"server":"none","threshold":90,"accounts":[
+  {"id":"acct-01","email":"sd1@test","home":"mac","added_at":"2026-07-13T00:00:00Z"},
+  {"id":"acct-02","email":"sd2@test","home":"mac","added_at":"2026-07-13T00:00:00Z"}]}
+EOF
+  for i in 01 02; do
+    printf 'sk-ant-oat01-SETUPTOKEN%s\n' "$i" > "$SD/acct-$i/server.token"
+    chmod 600 "$SD/acct-$i/server.token"
+    # Telemetry frozen eleven days ago — exactly what the incident left on disk.
+    printf '{"fetched_at":%s,"source":"oauth","max_percent":2,"weekly_percent":2,"session_percent":0,"buckets":[]}' \
+      "$((now - 950000))" > "$SD/acct-$i/limits.json"
+  done
+
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits --force 2>&1)"
+  check "a scope-denied 403 names the missing scope" "user:profile" "$out"
+  check "a scope-denied 403 names the ceremony that fixes it" "claude-accounts login acct-01" "$out"
+  check "a scope-denied 403 backs off instead of retrying" "Backing off" "$out"
+  python3 - "$SD/acct-01/limits.json" "$now" <<'EOF'
+import json, sys
+lim = json.load(open(sys.argv[1]))
+now = int(sys.argv[2])
+assert lim['retry_after'] > now + 3600, lim          # parked for hours, not minutes
+assert lim['fetched_at'] == now - 950000, lim        # a FAILURE never invents freshness
+assert 'HTTP 403' in lim['last_error'], lim
+EOF
+  [ $? -eq 0 ] && t_ok "a refused fetch records a long backoff and keeps its stale fetched_at" \
+    || t_fail "403 backoff state" "see $SD/acct-01/limits.json"
+
+  # The whole point: the next scheduled pass must NOT spend another request. Before the
+  # fix this retried every five minutes, from every machine, forever.
+  before="$(wc -l < "$uhits")"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits 2>&1)"
+  after="$(wc -l < "$uhits")"
+  [ "$before" = "$after" ] && t_ok "a parked account is not re-fetched on the next pass" \
+    || t_fail "403 retry storm" "endpoint hit again ($before -> $after requests)"
+  check "the parked account says why it is waiting" "backing off after HTTP 403" "$out"
+
+  # Any other non-2xx backs off too — a 5xx retried every pass is the same storm.
+  rm -f "$SD/acct-01/limits.json"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/boom" \
+         claude-accounts limits --force 2>&1)"
+  check "a 500 backs off as well" "backing off" "$out"
+  python3 - "$SD/acct-01/limits.json" <<'EOF'
+import json, sys
+lim = json.load(open(sys.argv[1]))
+assert lim.get('retry_after', 0) > 0 and 'HTTP 500' in lim.get('last_error', ''), lim
+assert 'fetched_at' not in lim or not lim['fetched_at'], lim   # never fetched != fresh
+EOF
+  [ $? -eq 0 ] && t_ok "a 5xx records a backoff without faking a fetch" \
+    || t_fail "500 backoff state" "see $SD/acct-01/limits.json"
+
+  # ---- the blind-ranking guard -------------------------------------------------
+  # Stale telemetry scores every account the same NEUTRAL value, so pick_best sees one
+  # pool-wide tie and selection silently becomes uniform random. It must say so.
+  for i in 01 02; do
+    printf '{"fetched_at":%s,"source":"oauth","max_percent":2,"weekly_percent":2,"session_percent":0,"buckets":[]}' \
+      "$((now - 950000))" > "$SD/acct-$i/limits.json"
+  done
+  : > "$SD/selection.log"
+  CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1
+  grep -q "ranking=BLIND" "$SD/selection.log" \
+    && t_ok "selection.log records that ranking ran blind" \
+    || t_fail "blind ranking log" "no ranking=BLIND line: $(tail -1 "$SD/selection.log")"
+  grep -q "telemetry-age=9[0-9]\{5\}s" "$SD/selection.log" \
+    && t_ok "the blind line carries the age of the outage" \
+    || t_fail "blind ranking age" "$(tail -1 "$SD/selection.log")"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts status 2>&1)"
+  check "status calls a blind pool blind" "RANKING IS BLIND" "$out"
+  check "status names the scope that is missing" "user:profile" "$out"
+  check "status flags the stale reading itself" "<< STALE" "$out"
+  # A panel drives off --json, so the outage has to be a FIELD, not just prose.
+  CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts list --json > "$SD/blind.json" 2>/dev/null
+  python3 - "$SD/blind.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d['summary']['ranking_blind'] is True, d['summary']
+assert all(a['usage']['stale'] is True for a in d['accounts']), d['accounts']
+EOF
+  [ $? -eq 0 ] && t_ok "--json reports the pool-wide blindness and per-account staleness" \
+    || t_fail "json blindness" "see $SD/blind.json"
+
+  # ...and telemetry INSIDE the window must still rank. 900s used to be the window,
+  # which is below the ~3600s floor the endpoint itself enforces (Retry-After: 3600),
+  # so a healthy pool spent most of every hour ranking neutral for no reason.
+  for i in 01 02; do
+    printf '{"fetched_at":%s,"source":"oauth","max_percent":%s,"weekly_percent":%s,"session_percent":1,"buckets":[]}' \
+      "$((now - 1200))" "$((i + 3))" "$((i + 3))" > "$SD/acct-$i/limits.json"
+  done
+  : > "$SD/selection.log"
+  CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1
+  ! grep -q "ranking=BLIND" "$SD/selection.log" \
+    && t_ok "20-minute-old telemetry still ranks (window matches the endpoint's own floor)" \
+    || t_fail "stale window" "20-minute-old data was treated as blind"
+  grep -q "acct-01 weekly=4%" "$SD/selection.log" \
+    && t_ok "the pool ranks on real numbers and picks the account with more headroom" \
+    || t_fail "headroom ranking" "$(tail -1 "$SD/selection.log")"
+
+  # ---- blind does not mean neutral --------------------------------------------
+  # Ranking everything NEUTRAL when nothing is fresh throws away information that is
+  # still TRUE: a weekly bucket only rises until its reset, so before that moment an
+  # old weekly reading remains a valid lower bound. Neutral is only the right answer
+  # while some other account has fresh data to be neutral against.
+  printf '{"fetched_at":%s,"weekly_percent":81,"session_percent":0,"max_percent":81,"weekly_resets_epoch":%s,"buckets":[]}' \
+    "$((now - 950000))" "$((now + 200000))" > "$SD/acct-01/limits.json"
+  printf '{"fetched_at":%s,"weekly_percent":4,"session_percent":0,"max_percent":4,"weekly_resets_epoch":%s,"buckets":[]}' \
+    "$((now - 950000))" "$((now + 200000))" > "$SD/acct-02/limits.json"
+  : > "$SD/selection.log"
+  rm -f "$SD/.last-pick"
+  for _ in 1 2 3 4 5 6; do CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1; done
+  if grep -q "acct-01 " "$SD/selection.log"; then
+    t_fail "blind ranking still avoids a nearly-exhausted account" \
+      "the account stale-reported at 81% weekly was picked: $(grep -c 'acct-01 ' "$SD/selection.log")/6 runs"
+  else
+    t_ok "blind ranking still avoids a nearly-exhausted account"
+  fi
+  # DEGRADED, not BLIND: the pool IS still ranking, on readings that remain true. An
+  # operator told "random" would go hunting a bug that is not there.
+  grep -q "ranking=DEGRADED" "$SD/selection.log" \
+    && t_ok "a degraded pick is logged as degraded, not as blind" \
+    || t_fail "degraded log" "$(tail -1 "$SD/selection.log")"
+  grep -q "acct-02 weekly=4% .*ranking=DEGRADED" "$SD/selection.log" \
+    && t_ok "the degraded line reports the stale reading it actually ranked on" \
+    || t_fail "degraded weekly" "$(tail -1 "$SD/selection.log")"
+
+  # ...but a reading whose week has ALREADY reset describes a week that is over. It is
+  # worth nothing, and must not be mistaken for a low-usage account.
+  printf '{"fetched_at":%s,"weekly_percent":81,"session_percent":0,"max_percent":81,"weekly_resets_epoch":%s,"buckets":[]}' \
+    "$((now - 950000))" "$((now + 200000))" > "$SD/acct-01/limits.json"
+  printf '{"fetched_at":%s,"weekly_percent":4,"session_percent":0,"max_percent":4,"weekly_resets_epoch":%s,"buckets":[]}' \
+    "$((now - 950000))" "$((now - 100))" > "$SD/acct-02/limits.json"
+  : > "$SD/selection.log"
+  rm -f "$SD/.last-pick"
+  for _ in 1 2 3 4 5 6; do CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1; done
+  grep -q "acct-02 " "$SD/selection.log" \
+    && t_ok "an expired weekly reading falls back to neutral instead of reading as 4%" \
+    || t_fail "expired weekly reading" "acct-02 never picked, so 81% still outranked an unknown"
+
+  # ---- the recorded horizon belongs to the bucket weekly_percent came from -----
+  # Taking the earliest reset across ALL durable buckets would let a 10% monthly bucket
+  # resetting in an hour throw away an 80% weekly reading that is good for five days —
+  # and that account would then score neutral 50 and beat a neighbour honestly at 60%.
+  rm -f "$SD/acct-01/limits.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/multibucket" \
+    claude-accounts limits --force >/dev/null 2>&1
+  python3 - "$SD/acct-01/limits.json" <<'EOF'
+import json, sys, time
+lim = json.load(open(sys.argv[1]))
+assert lim['weekly_percent'] == 80, lim
+horizon = lim['weekly_resets_epoch'] - time.time()
+assert horizon > 86400, lim   # the 80% bucket's five days, not the monthly bucket's hour
+EOF
+  [ $? -eq 0 ] && t_ok "the stale-reading horizon tracks the bucket weekly_percent came from" \
+    || t_fail "weekly horizon" "see $SD/acct-01/limits.json"
+
+  # ---- an unknown horizon is not comparable, so nobody gets degraded ranking ----
+  # A limits.json written before weekly_resets_epoch existed scores NEUTRAL 50 — which
+  # would beat a neighbour's true-but-worse 70 and make the degraded path actively
+  # wrong. Degraded ranking is therefore all-or-nothing across the candidates.
+  printf '{"fetched_at":%s,"weekly_percent":70,"session_percent":0,"max_percent":70,"weekly_resets_epoch":%s,"buckets":[]}' \
+    "$((now - 950000))" "$((now + 200000))" > "$SD/acct-01/limits.json"
+  printf '{"fetched_at":%s,"weekly_percent":85,"session_percent":0,"max_percent":85,"buckets":[]}' \
+    "$((now - 950000))" > "$SD/acct-02/limits.json"     # legacy file: no horizon
+  : > "$SD/selection.log"
+  rm -f "$SD/.last-pick"
+  for _ in 1 2 3 4 5 6; do CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1; done
+  grep -q "ranking=BLIND" "$SD/selection.log" && ! grep -q "ranking=DEGRADED" "$SD/selection.log" \
+    && t_ok "one horizon-less candidate turns degraded ranking off for the whole pool" \
+    || t_fail "mixed degraded ranking" "$(tail -1 "$SD/selection.log")"
+  grep -q "acct-02 " "$SD/selection.log" \
+    && t_ok "with degraded ranking off, the legacy account is still reachable" \
+    || t_fail "legacy starvation" "acct-02 never picked in 6 runs"
+
+  # ---- status/--json must agree with the shim, not just with each other --------
+  # A status that says "picking at RANDOM" while the shim is ranking on valid stale
+  # readings sends an operator after a bug that is not there; a status that says
+  # "fine" while the shim is blind is how eleven days went by.
+  for i in 01 02; do
+    printf '{"fetched_at":%s,"weekly_percent":%s,"session_percent":0,"max_percent":%s,"weekly_resets_epoch":%s,"buckets":[]}' \
+      "$((now - 950000))" "$((i + 3))" "$((i + 3))" "$((now + 200000))" > "$SD/acct-$i/limits.json"
+  done
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts status 2>&1)"
+  check "status reports DEGRADED when the shim is degraded" "RANKING IS DEGRADED" "$out"
+  CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts list --json > "$SD/degraded.json" 2>/dev/null
+  python3 - "$SD/degraded.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d['summary']['telemetry'] == 'degraded', d['summary']
+assert d['summary']['ranking_blind'] is False, d['summary']
+EOF
+  [ $? -eq 0 ] && t_ok "--json reports degraded, and ranking_blind stays false" \
+    || t_fail "json degraded" "see $SD/degraded.json"
+
+  # ---- a refused setup token is never spent on this endpoint again -------------
+  # The 6h park expires; the refusal does not. Asking again can only 403 and only
+  # burns the account's ~1-per-hour budget, which is what made an authorization
+  # problem look like a rate limit.
+  rm -f "$SD/acct-02/limits.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+    claude-accounts limits --force >/dev/null 2>&1
+  python3 - "$SD/acct-01/limits.json" <<'EOF'
+import json, os, sys
+p = sys.argv[1]
+d = json.load(open(p))
+assert d.get('token_scope_denied'), d             # WHICH token was refused (digest)
+d['retry_after'] = 0                             # the park has since expired
+json.dump(d, open(p + '.tmp', 'w')); os.replace(p + '.tmp', p)
+EOF
+  before="$(wc -l < "$uhits")"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits 2>&1)"
+  after="$(wc -l < "$uhits")"
+  [ "$before" = "$after" ] && t_ok "a token already refused for scope is not offered again" \
+    || t_fail "token re-offered" "endpoint hit again ($before -> $after)"
+  check "and the message says what would fix it" "claude-accounts login acct-01" "$out"
+  # Re-minting the token is a new credential, so it earns a fresh try.
+  printf 'sk-ant-oat01-REMINTED01\n' > "$SD/acct-01/server.token"
+  before="$(wc -l < "$uhits")"
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" \
+    claude-accounts limits >/dev/null 2>&1
+  after="$(wc -l < "$uhits")"
+  [ "$before" != "$after" ] && t_ok "a newly minted token is tried again" \
+    || t_fail "remint not retried" "the new token was never offered"
+
+  # ---- a dead OAuth grant must not park an account whose TOKEN still works -----
+  # This is the whole pool's shape after the incident: a working setup token beside a
+  # lapsed grant. The shim's auth_dead() reads .expired BEFORE server.token, so parking
+  # here would take every working account out of the pool at once — over a credential
+  # the pool needs only for telemetry, never for work.
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-x","expiresAt":1000,"refreshTokenExpiresAt":1000}}' \
+    > "$SD/acct-01/.credentials.json"
+  rm -f "$SD/acct-01/limits.json" "$SD/acct-01/.expired" "$SD/acct-01/.oauth-refresh.json"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-endpoint-missing.json" \
+         claude-accounts limits --force 2>&1)"
+  [ ! -f "$SD/acct-01/.expired" ] \
+    && t_ok "a dead grant never parks an account that still has a working setup token" \
+    || t_fail "portable account parked" "$(tail -1 "$SD/acct-01/.expired")"
+  check "...and it says telemetry is what is broken, not the account" "TELEMETRY is dead" "$out"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts status 2>&1)"
+  check "status keeps it selectable" "selectable  : yes" "$out"
+  # ...but with NO token, the same dead grant DOES park it: then nothing can authenticate.
+  mv "$SD/acct-01/server.token" "$SD/acct-01/server.token.bak"
+  rm -f "$SD/acct-01/limits.json" "$SD/acct-01/.oauth-refresh.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-endpoint-missing.json" \
+    claude-accounts limits --force >/dev/null 2>&1
+  grep -q "reason=refresh-token-expired" "$SD/acct-01/.expired" 2>/dev/null \
+    && t_ok "with no token to fall back on, a dead grant still parks the account" \
+    || t_fail "dead grant not parked" "no .expired for an account with nothing that authenticates"
+  mv "$SD/acct-01/server.token.bak" "$SD/acct-01/server.token"
+  rm -f "$SD/acct-01/.expired" "$SD/acct-01/.credentials.json" "$SD/acct-01/.oauth-refresh.json"
+
+  # ---- a live refresh token recovers even from a husk credential ---------------
+  # A credential whose ACCESS token was cleared but whose REFRESH token is alive is
+  # exactly what a grant exists to recover from. Requiring the dead half to be present
+  # meant such an account could never come back — and with a setup token beside it, it
+  # went dark for telemetry permanently.
+  printf '{"claudeAiOauth":{"accessToken":"","refreshToken":"sk-ant-ort01-live","expiresAt":0,"refreshTokenExpiresAt":9999999999999}}' \
+    > "$SD/acct-01/.credentials.json"
+  rm -f "$SD/acct-01/limits.json" "$SD/acct-01/.oauth-refresh.json" "$SD/acct-01/.expired"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" \
+         CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" claude-accounts limits --force 2>&1)"
+  check "a husk credential with a live refresh token is refreshed" "refreshed via refresh-token grant" "$out"
+  python3 -c "import json,sys; sys.exit(0 if json.load(open('$SD/acct-01/limits.json'))['source']=='oauth' else 1)" \
+    && t_ok "...and telemetry comes back on the OAuth bearer" \
+    || t_fail "husk recovery" "source != oauth"
+
+  # ---- a credential rotated mid-flight by someone else is never overwritten -----
+  # The grant rotates; a live claude session refreshes the same file. Losing that race
+  # by overwriting destroys the session's newer credential and strands the account.
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-MINE","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' \
+    > "$SD/acct-01/.credentials.json"
+  rm -f "$SD/acct-01/limits.json" "$SD/acct-01/.oauth-refresh.json"
+  # token-ok.json is a file:// fixture, so the "other writer" can land while the grant
+  # is in flight simply by writing a different refresh token first.
+  cat > "$SD/racer.sh" <<'RACER'
+#!/usr/bin/env bash
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-SESSION","refreshToken":"sk-ant-ort01-THEIRS","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$1"
+RACER
+  chmod +x "$SD/racer.sh"
+  "$SD/racer.sh" "$SD/acct-01/.credentials.json.race"
+  # simulate: the grant was issued against MINE, but THEIRS is what is on disk now
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-old","refreshToken":"sk-ant-ort01-MINE","expiresAt":1000,"refreshTokenExpiresAt":9999999999999}}' \
+    > "$SD/acct-01/.credentials.json"
+  ( sleep 0.1; cp "$SD/acct-01/.credentials.json.race" "$SD/acct-01/.credentials.json" ) &
+  racer_pid=$!
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" \
+    CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" claude-accounts limits --force >/dev/null 2>&1
+  wait "$racer_pid" 2>/dev/null || true
+  grep -q "sk-ant-ort01-THEIRS" "$SD/acct-01/.credentials.json" \
+    && t_ok "a credential rotated by another writer survives our refresh" \
+    || t_ok "refresh committed before the other writer landed (race not exercised)"
+  rm -f "$SD/acct-01/.credentials.json" "$SD/acct-01/.credentials.json.race" "$SD/racer.sh" \
+        "$SD/acct-01/.oauth-refresh.json" "$SD/acct-01/.expired"
+
+  # ---- an org block is never downgraded by a weaker reason ---------------------
+  # clear_expired refuses to lift an org block, but nothing stopped mark_expired from
+  # REWRITING its reason — after which the next successful fetch lifts it happily.
+  printf '%s\nreason=org-blocked marked_at=now detail=test\n' "$now" > "$SD/acct-01/.expired"
+  printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-x","refreshToken":"sk-ant-ort01-x","expiresAt":1000,"refreshTokenExpiresAt":1000}}' \
+    > "$SD/acct-01/.credentials.json"
+  rm -f "$SD/acct-01/limits.json"
+  CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" \
+    claude-accounts limits --force >/dev/null 2>&1
+  grep -q "reason=org-blocked" "$SD/acct-01/.expired" 2>/dev/null \
+    && t_ok "a dead refresh grant never overwrites an org-blocked marker" \
+    || t_fail "org block downgraded" "marker is now: $(cat "$SD/acct-01/.expired" 2>/dev/null | tail -1)"
+  rm -f "$SD/acct-01/.expired" "$SD/acct-01/.credentials.json"
+
+  # ---- the >=90% cutoff keeps the TIGHT window --------------------------------
+  # Ranking may trust an hour-old number; declaring an account UNUSABLE may not. The
+  # cutoff window is EXCLUDE_STALE_AFTER (900s), so this is tested on both sides of it.
+  # acct-01 is deliberately the BEST-RANKING account (weekly 1%) while being over the
+  # threshold on its session bucket (max 91%). So it is picked whenever it is eligible,
+  # and skipped only when the cutoff actually fires — which isolates the cutoff window
+  # from the ranking window instead of conflating "excluded" with "outranked".
+  mk_cutoff_pool() { # $1 = age of both readings, in seconds
+    printf '{"fetched_at":%s,"weekly_percent":1,"session_percent":91,"max_percent":91,"weekly_resets_epoch":%s,"buckets":[]}' \
+      "$((now - $1))" "$((now + 200000))" > "$SD/acct-01/limits.json"
+    printf '{"fetched_at":%s,"weekly_percent":50,"session_percent":5,"max_percent":50,"weekly_resets_epoch":%s,"buckets":[]}' \
+      "$((now - $1))" "$((now + 200000))" > "$SD/acct-02/limits.json"
+    : > "$SD/selection.log"
+    rm -f "$SD/.last-pick"
+    local _i
+    for _i in 1 2 3 4; do CLAUDE_ACCOUNTS_ROOT="$SD" claude >/dev/null 2>&1; done
+  }
+  mk_cutoff_pool 800     # inside the 900s cutoff window
+  ! grep -q "acct-01 " "$SD/selection.log" \
+    && t_ok "a 91% reading inside the cutoff window excludes the account" \
+    || t_fail "threshold exclusion" "a 91% account was selected on 800s-old data"
+  mk_cutoff_pool 1000    # past the cutoff window, still inside the RANKING window
+  grep -q "acct-01 " "$SD/selection.log" \
+    && t_ok "past the cutoff window a 91% reading no longer excludes (fail open)" \
+    || t_fail "cutoff fail-open" "a 1000s-old 91% reading still excluded the account"
+  ! grep -qE "ranking=(BLIND|DEGRADED)" "$SD/selection.log" \
+    && t_ok "...but it is still fresh enough to RANK on (the two windows differ)" \
+    || t_fail "ranking window" "1000s-old data was treated as unrankable"
+  grep -q "acct-01 weekly=1%" "$SD/selection.log" \
+    && t_ok "and ranking still prefers the account with more weekly headroom" \
+    || t_fail "ranking preference" "$(tail -1 "$SD/selection.log")"
+
+  # ---- one corrupt limits.json costs exactly one account ----------------------
+  # `[]` is valid JSON. Every prev.get() in the refresher would raise on it, OUTSIDE
+  # the per-account try — starving every account after it, which is the same pool-wide
+  # telemetry blackout this whole section is about.
+  printf '[]' > "$SD/acct-01/limits.json"
+  rm -f "$SD/acct-02/limits.json"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" \
+         claude-accounts limits --force 2>&1)"
+  rc=$?
+  [ "$rc" = "0" ] && t_ok "a limits.json that is not an object exits 0" || t_fail "corrupt limits rc" "rc=$rc: $out"
+  [ -s "$SD/acct-02/limits.json" ] \
+    && t_ok "accounts after a corrupt limits.json still refresh" \
+    || t_fail "corrupt limits starves the loop" "acct-02 was never fetched"
+
+  # status must survive the same file — it is the one command that reports the outage.
+  printf '{"fetched_at":"yesterday"}' > "$SD/acct-01/limits.json"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" claude-accounts status 2>&1)"
+  rc=$?
+  [ "$rc" = "0" ] && t_ok "status survives a limits.json with a non-numeric fetched_at" \
+    || t_fail "status crash" "rc=$rc: $(printf '%s' "$out" | tail -3)"
+  check "status still reaches the accounts after the corrupt one" "acct-02" "$out"
+
+  # A successful fetch must clear the whole backoff record, or one bad hour would keep
+  # an account parked long after the endpoint came back.
+  printf '{"fetched_at":%s,"weekly_percent":2,"session_percent":0,"max_percent":2,"buckets":[]}' \
+    "$((now - 950000))" > "$SD/acct-01/limits.json"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/scope-denied" \
+         claude-accounts limits --force 2>&1)"
+  out="$(CLAUDE_ACCOUNTS_ROOT="$SD" CLAUDE_MULTIACC_USAGE_URL="http://127.0.0.1:$uport/ok" \
+         claude-accounts limits --force 2>&1)"
+  python3 - "$SD/acct-01/limits.json" <<'EOF'
+import json, sys
+lim = json.load(open(sys.argv[1]))
+assert 'retry_after' not in lim and 'last_error' not in lim, lim
+assert lim['weekly_percent'] == 7 and lim['session_percent'] == 3, lim
+EOF
+  [ $? -eq 0 ] && t_ok "a successful fetch drops every trace of the backoff" \
+    || t_fail "backoff cleared" "see $SD/acct-01/limits.json"
+  kill "$usrv_pid" 2>/dev/null; wait "$usrv_pid" 2>/dev/null || true
+fi
+
 # ---- 16b8. malformed claudeAiOauth (null) degrades that account ONLY (fail open) -------
 # {"claudeAiOauth": null} is valid JSON from an interrupted/reset credential write; it
 # must not abort the refresher — accounts AFTER it in the manifest must still be fetched.
@@ -1347,7 +2227,13 @@ if command -v node >/dev/null 2>&1; then
   # self-update on a non-npm, non-git tree is a logged no-op (never errors)
   out="$(claude-accounts self-update 2>&1)"
   rc=$?
-  [ "$rc" = "0" ] && t_ok "self-update no-op exits 0 on a plain checkout" || t_fail "self-update rc" "rc=$rc"
+  # A git checkout that cannot fast-forward (feature branch, detached CI checkout) is
+  # SUPPOSED to fail loudly; what must never happen is a crash with no explanation.
+  case "$rc:$out" in
+    0:*) t_ok "self-update no-op exits 0 on a plain checkout" ;;
+    *:*"git pull FAILED"*) t_ok "self-update reports a git checkout it cannot fast-forward" ;;
+    *) t_fail "self-update rc" "rc=$rc: $out" ;;
+  esac
   case "$out" in *"update manually"*|*"already latest"*|*"git pull"*) t_ok "self-update reports its path" ;;
     *) t_fail "self-update message" "unexpected: $out" ;; esac
   # postinstall must SKIP for a non-global install and never fail
@@ -1382,6 +2268,7 @@ mkdir -p "$CX/tmp"
 unset CODEX_HOME CODEX_ACCOUNT CODEX_SHIM_ACTIVE 2>/dev/null || true
 export CODEX_MULTIACC_NO_SYNC=1
 export CODEX_MULTIACC_MIN_FETCH=0
+export CODEX_MULTIACC_CLIENT_SCAN_TTL=0
 export CODEX_MULTIACC_TOKEN_URL="file://$WORK/cx-token-endpoint-missing.json"
 # Default usage URL is an offline missing fixture: the SHIM's opportunistic
 # background `limits --quiet` kick must never reach a real endpoint from tests
@@ -1556,6 +2443,211 @@ codex >/dev/null 2>&1
 [ ! -f "$CX/acct-01/.limited" ] && t_ok "codex: expired .limited marker self-clears" \
   || t_fail "codex marker expiry" ".limited survived its reset time"
 
+# ---- C5b. client-reported rate limits (rollouts) + rotation -------------------------
+# Parity with the claude shim: never depend on the usage endpoint to notice an account
+# ran dry. The codex CLI writes the windows the server reported into every run's
+# rollout, and rollouts live inside the account dir — so no session index is needed.
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/limits.json "$CX/.pick-seq" "$CX"/acct-0*/.last-pick
+rm -rf "$CX"/acct-0*/sessions
+mkrollout() { # mkrollout <acct dir> <used_percent> <resets_at>
+  local day="$1/sessions/2026/08/20"
+  mkdir -p "$day"
+  {
+    printf '{"timestamp":"2026-08-19T22:43:21.299Z","type":"session_meta","payload":{"session_id":"01a01c31","cwd":"/proj"}}\n'
+    printf '{"timestamp":"2026-08-19T22:49:54.120Z","type":"event_msg","payload":{"type":"token_count","info":{"model_context_window":258400},"rate_limits":{"limit_id":"codex","limit_name":null,"primary":{"used_percent":%s,"window_minutes":10080,"resets_at":%s},"secondary":null,"credits":{"has_credits":false,"unlimited":false,"balance":"0"}}}}\n' "$2" "$3"
+  } > "$day/rollout-2026-08-20T01-43-21-01a01c31-7fc3-7291-a0fc-7b4e2b035f1a.jsonl"
+}
+mkrollout "$CX/acct-01" "97.4" "$((now + 3600))"
+all2=1
+for _ in $(seq 1 12); do
+  case "$(codex 2>&1)" in *CFG=acct-02*) ;; *) all2=0 ;; esac
+done
+[ "$all2" = "1" ] && t_ok "codex: a spent window in the account's own rollout excludes it" \
+  || t_fail "codex client rate limit" "the spent account was picked again"
+first="$(head -1 "$CX/acct-01/.limited" 2>/dev/null)"
+[ "$first" = "$((now + 3600))" ] && t_ok "codex: marker carries the reported reset time" \
+  || t_fail "codex client marker reset" "want $((now + 3600)), got '${first:-<none>}'"
+grep -q 'reason=client-rate-limit' "$CX/acct-01/.limited" 2>/dev/null \
+  && t_ok "codex: marker is tagged client-rate-limit" \
+  || t_fail "codex client marker reason" "$(cat "$CX/acct-01/.limited" 2>/dev/null)"
+rm -f "$CX/acct-01/.limited"
+
+# under the threshold is just usage, not an exclusion
+mkrollout "$CX/acct-01" "40.0" "$((now + 3600))"
+hits1=0
+for _ in $(seq 1 12); do
+  case "$(codex 2>&1)" in *CFG=acct-01*) hits1=$((hits1+1)) ;; esac
+done
+{ [ "$hits1" -gt 0 ] && [ ! -f "$CX/acct-01/.limited" ]; } \
+  && t_ok "codex: a sub-threshold window does not exclude" \
+  || t_fail "codex sub-threshold rollout" "acct-01 hits=$hits1"
+
+# a window that has already reset is history
+mkrollout "$CX/acct-01" "99.0" "$((now - 60))"
+hits1=0
+for _ in $(seq 1 12); do
+  case "$(codex 2>&1)" in *CFG=acct-01*) hits1=$((hits1+1)) ;; esac
+done
+{ [ "$hits1" -gt 0 ] && [ ! -f "$CX/acct-01/.limited" ]; } \
+  && t_ok "codex: an elapsed window does not exclude" \
+  || t_fail "codex elapsed rollout window" "acct-01 hits=$hits1"
+
+# opt-out
+mkrollout "$CX/acct-01" "99.0" "$((now + 3600))"
+hits1=0
+for _ in $(seq 1 12); do
+  case "$(CODEX_MULTIACC_CLIENT_LIMITS=0 codex 2>&1)" in *CFG=acct-01*) hits1=$((hits1+1)) ;; esac
+done
+{ [ "$hits1" -gt 0 ] && [ ! -f "$CX/acct-01/.limited" ]; } \
+  && t_ok "codex: CODEX_MULTIACC_CLIENT_LIMITS=0 turns the scan off" \
+  || t_fail "codex client-limit opt-out" "still excluded with the scan disabled"
+rm -rf "$CX"/acct-0*/sessions
+rm -f "$CX"/acct-0*/.limited
+
+# equal-headroom picks rotate instead of re-rolling a coin
+rm -f "$CX/.pick-seq" "$CX"/acct-0*/.last-pick "$CX"/acct-0*/limits.json
+seq_out=""
+for _ in $(seq 1 8); do
+  case "$(codex 2>&1)" in
+    *CFG=acct-01*) seq_out="${seq_out}1" ;;
+    *CFG=acct-02*) seq_out="${seq_out}2" ;;
+    *) seq_out="${seq_out}?" ;;
+  esac
+done
+case "$seq_out" in
+  12121212|21212121) t_ok "codex: equal-score picks round-robin across the pool ($seq_out)" ;;
+  *) t_fail "codex round-robin tie-break" "sequence $seq_out (want strict alternation)" ;;
+esac
+rm -f "$CX/.pick-seq" "$CX"/acct-0*/.last-pick
+
+
+# codex-review finding: the bounded rollout scan must start at the NEWEST file, or a
+# busy account whose only over-threshold report is its latest run stays eligible.
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+rm -rf "$CX"/acct-0*/sessions
+mkdir -p "$CX/acct-01/sessions/2026/08/20"
+i=1
+while [ "$i" -le 12 ]; do
+  printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":10.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+    "$((now + 3600))" > "$CX/acct-01/sessions/2026/08/20/rollout-2026-08-20T0$(printf '%01d' $((i % 10)))-0$i-old$i.jsonl"
+  i=$((i + 1))
+done
+printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":100.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+  "$((now + 3600))" > "$CX/acct-01/sessions/2026/08/20/rollout-2026-08-20T99-99-newest.jsonl"
+codex >/dev/null 2>&1
+grep -q 'reason=client-rate-limit' "$CX/acct-01/.limited" 2>/dev/null \
+  && t_ok "codex: the newest rollout is read even past the file cap" \
+  || t_fail "codex rollout scan order" "13 rollouts, only the newest over threshold — missed it"
+rm -rf "$CX"/acct-0*/sessions
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+
+# A SHARED sessions tree (the layout lib/common.sh actually installs: acct/sessions is a
+# symlink to ~/.codex/sessions so `codex resume` finds every session) proves nothing about
+# who spent the quota. One spent window there must not mark the whole pool.
+SHARED="$WORK/cx-shared-sessions"
+mkdir -p "$SHARED/2026/08/20"
+printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":100.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+  "$((now + 3600))" > "$SHARED/2026/08/20/rollout-2026-08-20T01-00-00-shared.jsonl"
+for i in 01 02; do ln -s "$SHARED" "$CX/acct-$i/sessions"; done
+codex >/dev/null 2>&1
+{ [ ! -f "$CX/acct-01/.limited" ] && [ ! -f "$CX/acct-02/.limited" ]; } \
+  && t_ok "codex: a shared sessions symlink never marks an account (fail open)" \
+  || t_fail "codex shared sessions" "a shared rollout tree marked the pool LIMITED"
+out="$(codex 2>&1)"
+case "$out" in *CFG=acct-0*) t_ok "codex: the pool still selects with a shared sessions tree" ;;
+  *) t_fail "codex shared sessions" "selection produced: $out" ;; esac
+rm -f "$CX"/acct-0*/sessions "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+
+# second codex-review pass: a NESTED symlink inside a real sessions/ dir must not smuggle
+# another tree's rollouts in, and a huge stale rollout directory must not be walked.
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+rm -rf "$CX"/acct-0*/sessions
+OUTSIDE="$WORK/cx-outside"
+mkdir -p "$OUTSIDE/08/20" "$CX/acct-01/sessions"
+printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":100.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+  "$((now + 3600))" > "$OUTSIDE/08/20/rollout-2026-08-20T01-00-00-outside.jsonl"
+ln -s "$OUTSIDE" "$CX/acct-01/sessions/2026"
+codex >/dev/null 2>&1
+[ ! -f "$CX/acct-01/.limited" ] \
+  && t_ok "codex: a nested symlink out of the account tree never marks it" \
+  || t_fail "codex nested sessions symlink" "rollouts outside the account tree marked it LIMITED"
+rm -f "$CX/acct-01/sessions/2026"
+
+# a day dir stuffed with stale rollouts must cost a bounded amount of work, and the
+# newest (over-threshold) file must still be the one that decides
+mkdir -p "$CX/acct-01/sessions/2026/08/20"
+i=1
+while [ "$i" -le 60 ]; do
+  printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":5.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+    "$((now + 3600))" > "$CX/acct-01/sessions/2026/08/20/rollout-2026-08-20T00-00-$(printf '%02d' "$i")-bulk.jsonl"
+  i=$((i + 1))
+done
+printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":100.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+  "$((now + 3600))" > "$CX/acct-01/sessions/2026/08/20/rollout-2026-08-20T23-59-59-newest.jsonl"
+codex >/dev/null 2>&1
+grep -q 'reason=client-rate-limit' "$CX/acct-01/.limited" 2>/dev/null \
+  && t_ok "codex: 61 rollouts in one day dir — the newest still decides" \
+  || t_fail "codex bulk rollout dir" "the newest rollout was not the one read"
+rm -rf "$CX"/acct-0*/sessions
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+
+# third codex-review pass: find(1) output is newline-delimited, so a pool file whose NAME
+# contains a newline arrives as two lines and its tail resolves relative to $PWD.
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+rm -rf "$CX"/acct-0*/sessions
+mkdir -p "$CX/acct-01/sessions/2026/08/20"
+ESCDIR="$WORK/cx-escape-dir"
+mkdir -p "$ESCDIR"
+printf '{"type":"event_msg","payload":{"rate_limits":{"primary":{"used_percent":100.0,"window_minutes":10080,"resets_at":%s},"secondary":null}}}\n' \
+  "$((now + 3600))" > "$ESCDIR/escape.jsonl"
+# ONE file whose name embeds a newline; find prints it as two lines, and the second
+# ("escape.jsonl") would resolve against the caller's cwd — outside the pool entirely.
+HOSTILE=$'rollout-a\nescape.jsonl'
+: > "$CX/acct-01/sessions/2026/08/20/$HOSTILE"
+[ -e "$CX/acct-01/sessions/2026/08/20/$HOSTILE" ] \
+  || t_fail "codex newline filename" "fixture not created — the guard would go unexercised"
+( cd "$ESCDIR" && codex >/dev/null 2>&1 )
+[ ! -f "$CX/acct-01/.limited" ] \
+  && t_ok "codex: a newline in a rollout name cannot pull in a file outside the pool" \
+  || t_fail "codex newline filename" "a file outside the pool marked the account LIMITED"
+rm -rf "$CX"/acct-0*/sessions
+rm -f "$CX"/acct-0*/.limited "$CX"/acct-0*/.client-scan
+
+# corrupt pool state must never reach bash arithmetic here either
+CXBIG="99999999999999999999999999999999"
+printf '%s\n' "$CXBIG" > "$CX/.last-pick"
+printf '{"fetched_at":%s,"weekly_percent":%s,"session_percent":1,"max_percent":%s,"buckets":[]}' "$CXBIG" "$CXBIG" "$CXBIG" > "$CX/acct-02/limits.json"
+err="$(codex 2>&1 >/dev/null)"
+[ -z "$err" ] && t_ok "codex: absurd pool numbers keep stderr byte-clean" \
+  || t_fail "codex corrupt number handling" "stderr: $(printf '%s' "$err" | head -c 160)"
+rm -f "$CX/.last-pick" "$CX"/acct-0*/limits.json
+: > "$CX/acct-01/.client-scan"
+err="$(CODEX_MULTIACC_CLIENT_SCAN_TTL=bogus CODEX_MULTIACC_THRESHOLD=nonsense codex 2>&1 >/dev/null)"
+out="$(CODEX_MULTIACC_CLIENT_SCAN_TTL=bogus CODEX_MULTIACC_THRESHOLD=nonsense codex 2>/dev/null)"
+{ [ -z "$err" ] && case "$out" in *CFG=acct-0*) true ;; *) false ;; esac; } \
+  && t_ok "codex: garbage in the TTL / threshold env vars keeps stderr clean" \
+  || t_fail "codex env number validation" "stderr: $(printf '%s' "$err" | head -c 160) out: $out"
+rm -f "$CX"/acct-0*/.client-scan
+
+# a parallel burst still spreads (rotation drops only the account just handed out).
+# Three accounts, for the same reason as the claude side: with two, landing entirely on
+# the single alternative is correct behaviour and the assertion would measure nothing.
+mkdir -p "$CX/acct-09"
+"$MKAUTH" > "$CX/acct-09/auth.json" 2>/dev/null || \
+  printf '{"tokens":{"access_token":"%s","account_id":"a9"},"last_refresh":"2026-08-01T00:00:00Z"}' \
+    "$(sed -n 's/.*"access_token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$CX/acct-01/auth.json" | head -1)" \
+    > "$CX/acct-09/auth.json"
+: > "$WORK/cx-burst.out"
+for _ in $(seq 1 16); do ( codex >> "$WORK/cx-burst.out" 2>&1 ) & done
+wait
+c_distinct="$(grep -o 'CFG=acct-[0-9]*' "$WORK/cx-burst.out" | sort -u | tr '\n' ' ')"
+c_n="$(printf '%s' "$c_distinct" | wc -w | tr -d ' ')"
+[ "$c_n" -ge 2 ] \
+  && t_ok "codex: a parallel burst still spreads across the pool ($c_distinct)" \
+  || t_fail "codex burst spreading" "all 16 concurrent runs took $c_distinct"
+rm -rf "$CX/acct-09"
+rm -f "$CX/.last-pick"
+
 # ---- C6. all limited -> least-utilized fallback -------------------------------------
 printf '%s\nbucket=7d percent=95 reason=limits\n' "$((now+3600))" > "$CX/acct-01/.limited"
 printf '%s\nbucket=7d percent=99 reason=limits\n' "$((now+3600))" > "$CX/acct-02/.limited"
@@ -2306,6 +3398,462 @@ else
   t_ok "codex npm-layer tests skipped (node not installed)"
 fi
 
+# ---- 20. panel pools: --json, credential transfer, instance roots, local sync -------
+# Everything here runs against pools under $WORK/panel, addressed with the NEW
+# CLAUDE_ACCOUNTS_ROOT/CODEX_ACCOUNTS_ROOT env — while CLAUDE_ACCOUNTS_DIR (the legacy
+# spelling) still points at the suite's own pool, which is exactly the precedence a
+# second app-robot instance on a shared machine depends on.
+PP="$WORK/panel"
+JP="$PP/claude-a"
+JP2="$PP/claude-b"
+PTOKEN="sk-ant-oat01-PANELPOOLTOKENPANELPOOLTOKENPANELPOOLTOKENPANELPOOL"
+mkdir -p "$JP/acct-01" "$JP/acct-02" "$JP/acct-03" "$JP2"
+# home must be THIS machine's kind: a credential-less home=mac account audits as
+# 'remote' (its grant lives elsewhere) rather than 'missing' when the suite runs on
+# Linux — which is what the publish CI runs on. Same rule as the relogin-redirect
+# fixture (ddb3015).
+PMK=mac; [ "$(uname -s)" = "Darwin" ] || PMK=linux
+cat > "$JP/accounts.json" <<EOF
+{
+  "version": 1,
+  "server": "root@203.0.113.7",
+  "server_root": "/root/.claude-accounts",
+  "server_repo": "/root/claude-multiacc",
+  "threshold": 90,
+  "accounts": [
+    {"id": "acct-01", "email": "portable@test", "home": "$PMK", "added_at": "2026-01-02T03:04:05Z"},
+    {"id": "acct-02", "email": "local@test", "home": "$PMK", "added_at": "2026-02-02T03:04:05Z"},
+    {"id": "acct-03", "email": "nocred@test", "home": "$PMK", "added_at": "2026-03-02T03:04:05Z"}
+  ]
+}
+EOF
+printf '%s' "$PTOKEN" > "$JP/acct-01/server.token"
+chmod 600 "$JP/acct-01/server.token"
+printf '{"claudeAiOauth":{"accessToken":"a","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' \
+  > "$JP/acct-02/.credentials.json"
+printf '{"version":1,"server":"none","server_root":"/root/.claude-accounts","server_repo":"/root/claude-multiacc","threshold":90,"accounts":[]}\n' \
+  > "$JP2/accounts.json"
+: > "$JP/.limits-kick"
+: > "$JP2/.limits-kick"
+
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts list --json > "$PP/list.json" 2>"$PP/list.err"
+python3 - "$PP/list.json" "$JP" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d["schema"] == "claude-multiacc/pool.v1", d["schema"]
+assert d["provider"] == "claude" and d["kind"] == "list", d
+assert d["pool"]["root"] == sys.argv[2], d["pool"]["root"]   # _ROOT beats legacy _DIR
+by = {a["id"]: a for a in d["accounts"]}
+assert by["acct-01"]["status"] == "active", by["acct-01"]
+assert by["acct-01"]["credential_class"] == "portable" and by["acct-01"]["portable"], by["acct-01"]
+assert by["acct-02"]["credential_class"] == "machine-local", by["acct-02"]
+assert by["acct-02"]["portable"] is False, by["acct-02"]
+assert by["acct-03"]["status"] == "missing" and by["acct-03"]["credential_class"] == "none", by["acct-03"]
+assert by["acct-01"]["home_dir"].endswith("/acct-01"), by["acct-01"]
+assert by["acct-01"]["email"] == "portable@test", by["acct-01"]
+assert d["summary"] == {"total": 3, "active": 2, "limited": 0, "needs_login": 1,
+                        "portable": 1, "selectable": 2,
+                        # how the shim is CURRENTLY ranking: fresh | degraded | blind.
+                        # This fixture has no telemetry at all, so: blind.
+                        "telemetry": "blind",
+                        "ranking_blind": True}, d["summary"]
+assert d["pool"]["sync"]["mode"] == "server", d["pool"]["sync"]
+EOF
+[ $? -eq 0 ] && t_ok "list --json: stable schema, status/class per account, instance root" \
+  || t_fail "list --json" "see $PP/list.json"
+[ ! -s "$PP/list.err" ] && t_ok "list --json writes nothing to stderr" \
+  || t_fail "list --json stderr" "$(head -c 120 "$PP/list.err")"
+
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts status --json > "$PP/status.json"
+python3 - "$PP/status.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d["kind"] == "status", d["kind"]
+a = {x["id"]: x for x in d["accounts"]}["acct-01"]
+assert "last_picked" in a and "expired_marker" in a, a
+assert a["credentials"]["token"] is True and a["credentials"]["oauth"] is False, a["credentials"]
+assert a["credentials"]["token_age_days"] == 0, a["credentials"]
+b = {x["id"]: x for x in d["accounts"]}["acct-02"]
+assert b["credentials"]["oauth_refresh_expires_at"], b["credentials"]
+EOF
+[ $? -eq 0 ] && t_ok "status --json: adds last_picked + credential detail" \
+  || t_fail "status --json" "see $PP/status.json"
+
+cat > "$WORK/usage-panel.json" <<'EOF'
+{"limits":[
+  {"kind":"session","percent":12,"resets_at":"2099-01-01T00:00:00+00:00","scope":null},
+  {"kind":"weekly_all","percent":93,"resets_at":"2099-01-03T00:00:00+00:00","scope":null}
+]}
+EOF
+CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-panel.json" \
+  claude-accounts limits --json > "$PP/limits.json" 2>/dev/null
+python3 - "$PP/limits.json" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d["kind"] == "limits", d["kind"]
+a = {x["id"]: x for x in d["accounts"]}["acct-01"]
+assert a["usage"]["max_percent"] == 93, a["usage"]
+assert a["usage"]["source"] == "token", a["usage"]
+assert a["status"] == "limited" and a["limited"] is True, a
+assert a["limit_reset_at"], a
+assert a["selectable"] is False, a
+# acct-02 has a live oauth credential, so it fetched the same fixture and parked too
+assert d["summary"]["limited"] == 2, d["summary"]
+EOF
+[ $? -eq 0 ] && t_ok "limits --json: refreshes, then reports usage + limited state" \
+  || t_fail "limits --json" "see $PP/limits.json"
+rm -f "$JP/acct-01/.limited" "$JP/acct-02/.limited"
+
+# ---- 20a. export-credential: portable only, exit codes a daemon can branch on -------
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-01 > "$PP/blob.json" 2>"$PP/blob.err"
+rc=$?
+[ "$rc" = "0" ] && t_ok "export-credential exits 0 for a portable account" \
+  || t_fail "export rc" "rc=$rc $(head -c 120 "$PP/blob.err")"
+python3 - "$PP/blob.json" "$PTOKEN" "$PMK" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+assert b["format"] == "claude-multiacc/credential" and b["version"] == 1, b
+assert b["provider"] == "claude" and b["class"] == "portable", b
+assert b["account"] == {"id": "acct-01", "email": "portable@test", "home": sys.argv[3],
+                        "added_at": "2026-01-02T03:04:05Z"}, b["account"]
+assert b["credential"] == {"type": "setup-token", "value": sys.argv[2]}, "credential mismatch"
+assert b["exported_from"]["pool_root"].endswith("claude-a"), b["exported_from"]
+EOF
+[ $? -eq 0 ] && t_ok "export blob: self-contained credential + identity metadata" \
+  || t_fail "export blob shape" "see $PP/blob.json"
+
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-02 2>&1)"
+rc=$?
+check "export refuses a machine-local credential" "MACHINE-LOCAL" "$out"
+check "export says how to make it portable" "claude-accounts mint acct-02" "$out"
+[ "$rc" = "3" ] && t_ok "machine-local export exits 3" || t_fail "machine-local exit code" "rc=$rc"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-03 2>&1)"
+rc=$?
+check "export reports an account with no credential" "no credential material" "$out"
+[ "$rc" = "4" ] && t_ok "credential-less export exits 4" || t_fail "no-credential exit code" "rc=$rc"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-77 2>&1)"
+[ $? != 0 ] && t_ok "export of an unregistered id fails" || t_fail "unknown id export" "exited 0"
+
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-02 --identity-only --out "$PP/ident.json" >/dev/null
+rc=$?
+python3 - "$PP/ident.json" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+assert b["class"] == "identity", b
+assert "credential" not in b, "identity blob must carry no credential material"
+assert b["account"]["email"] == "local@test", b
+EOF
+[ $? -eq 0 ] && [ "$rc" = "0" ] \
+  && t_ok "export --identity-only works for a machine-local account (registry only)" \
+  || t_fail "identity-only export" "rc=$rc, see $PP/ident.json"
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-01 --out "$PP/blob-out.json" >/dev/null
+case "$(ls -l "$PP/blob-out.json" | cut -c1-10)" in
+  -rw-------) t_ok "export --out writes the blob 0600" ;;
+  *) t_fail "export --out perms" "$(ls -l "$PP/blob-out.json" | cut -c1-10)" ;;
+esac
+
+# ---- 20b. import-credential: faithful, idempotent, and picky ------------------------
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential < "$PP/blob.json" 2>&1)"
+rc=$?
+check "import-credential installs a portable credential" "Imported acct-01 (portable@test" "$out"
+[ "$rc" = "0" ] && t_ok "import-credential exits 0" || t_fail "import rc" "rc=$rc"
+python3 - "$JP2/accounts.json" "$JP2/acct-01/server.token" "$PTOKEN" "$PMK" <<'EOF'
+import json, sys
+accs = json.load(open(sys.argv[1]))["accounts"]
+assert len(accs) == 1, accs
+a = accs[0]
+# byte-faithful metadata: the account reads identically on the second machine
+assert a == {"id": "acct-01", "email": "portable@test", "home": sys.argv[4],
+             "added_at": "2026-01-02T03:04:05Z"}, a
+assert open(sys.argv[2]).read() == sys.argv[3], "token content changed in transfer"
+EOF
+[ $? -eq 0 ] && t_ok "imported account + credential round-trip unchanged" \
+  || t_fail "import fidelity" "see $JP2"
+case "$(ls -l "$JP2/acct-01/server.token" | cut -c1-10)" in
+  -rw-------) t_ok "imported credential is 0600" ;;
+  *) t_fail "imported credential perms" "$(ls -l "$JP2/acct-01/server.token" | cut -c1-10)" ;;
+esac
+# The write goes through a temp file in the account dir; none of it may survive.
+[ -z "$(ls -a "$JP2/acct-01" | grep '^\.cred\.')" ] \
+  && t_ok "no temp credential file is left behind by an import" \
+  || t_fail "import leftovers" "$(ls -a "$JP2/acct-01" | grep '^\.cred\.')"
+[ -z "$(ls -a "$JP2/tmp" 2>/dev/null | grep 'import-cred')" ] \
+  && t_ok "no staged blob is left behind by an import" \
+  || t_fail "staged blob leftovers" "$(ls -a "$JP2/tmp" | grep 'import-cred')"
+CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential --in "$PP/blob.json" >/dev/null 2>&1
+n="$(python3 -c "import json;print(len(json.load(open('$JP2/accounts.json'))['accounts']))")"
+[ "$n" = "1" ] && t_ok "re-importing the same account refreshes it, never duplicates" \
+  || t_fail "import idempotence" "$n accounts after a second import"
+
+python3 - "$PP/blob.json" "$PP/blob-apikey.json" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+b["credential"]["value"] = "sk-ant-api03-" + "A" * 60      # an API key, not a setup-token
+json.dump(b, open(sys.argv[2], "w"))
+EOF
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential --in "$PP/blob-apikey.json" 2>&1)"
+rc=$?
+check "import refuses an API key" "not a subscription setup-token" "$out"
+[ "$rc" != "0" ] && t_ok "API-key import exits nonzero" || t_fail "api key import" "exited 0"
+
+out="$(CODEX_ACCOUNTS_ROOT="$PP/codex-b" codex-accounts import-credential --in "$PP/blob.json" 2>&1)"
+[ $? != 0 ] && t_ok "a claude blob cannot be imported into the codex pool" \
+  || t_fail "cross-provider import" "exited 0"
+
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential --in "$PP/ident.json" 2>&1)"
+check "identity-only import registers the account" "identity only, no credential" "$out"
+check "identity-only import says what it still needs" "claude-accounts login" "$out"
+[ ! -f "$JP2/acct-02/server.token" ] && t_ok "identity-only import installs no credential" \
+  || t_fail "identity-only import" "wrote a credential file"
+
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential acct-02 --in "$PP/blob.json" 2>&1)"
+rc=$?
+check "import refuses to land the same email in a second slot" "already registered as acct-01" "$out"
+[ "$rc" != "0" ] && t_ok "conflicting-id import exits nonzero" || t_fail "conflicting id" "exited 0"
+
+# ---- 20c. instance isolation: the shim resolves the same root as the CLI ------------
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude 2>&1)"
+check "shim honors CLAUDE_ACCOUNTS_ROOT (instance pool)" "CFG=acct-01" "$out"
+[ -f "$JP2/selection.log" ] && t_ok "instance pool records its own selection log" \
+  || t_fail "instance selection log" "missing at $JP2/selection.log"
+grep -q "acct-01" "$ACC/selection.log" && ! grep -q "portable@test" "$ACC/accounts.json" \
+  && t_ok "the default pool was untouched by the instance run" \
+  || t_fail "pool isolation" "the instance run leaked into $ACC"
+
+# ---- 20d. sync target: overridable, and a local-only mode that pushes nowhere -------
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_NO_SYNC=0 claude-accounts sync --no-server 2>&1)"
+rc=$?
+check "sync --no-server stays local" "local-only" "$out"
+[ "$rc" = "0" ] && t_ok "sync --no-server exits 0" || t_fail "sync --no-server rc" "rc=$rc"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_SYNC_TARGET=none CLAUDE_MULTIACC_NO_SYNC=0 \
+       claude-accounts sync 2>&1)"
+check "SYNC_TARGET=none makes sync local-only" "nothing pushed" "$out"
+CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_SYNC_TARGET="ops@panel.example" \
+  claude-accounts list --json > "$PP/list-target.json"
+python3 - "$PP/list-target.json" <<'EOF'
+import json, sys
+s = json.load(open(sys.argv[1]))["pool"]["sync"]
+assert s["mode"] == "server" and s["target"] == "ops@panel.example", s
+EOF
+[ $? -eq 0 ] && t_ok "SYNC_TARGET env overrides the manifest server" \
+  || t_fail "sync target override" "see $PP/list-target.json"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" CLAUDE_MULTIACC_NO_SYNC=0 \
+       claude-accounts import-credential --in "$PP/blob.json" 2>&1)"
+case "$out" in
+  *"sync failed"*) t_fail "local-only auto_sync" "a local-only pool warned about a server push: $out" ;;
+  *) t_ok "local-only pool: mutations never warn about a missing server" ;;
+esac
+# A replica pool must NEVER push — and pointing it at a local-only target must not
+# become a way around that. Local mode narrows the rule (nothing pushes at all); the
+# marker is still honored and still reported.
+printf 'replica\n' > "$JP/sync-role"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_SYNC_TARGET=none CLAUDE_MULTIACC_NO_SYNC=0 \
+       claude-accounts sync 2>&1)"
+rc=$?
+check "a replica in local-only mode still says it is a replica" "sync replica" "$out"
+check "a replica in local-only mode pushes nothing" "nothing pushed either way" "$out"
+[ "$rc" = "0" ] && t_ok "replica + local-only exits 0" || t_fail "replica local-only rc" "rc=$rc"
+# `sync` refuses outright off the Mac ("sync runs on the Mac, not the server"), so the
+# replica and target-injection rules can only be observed there. Stated as a skip rather
+# than quietly asserting the wrong message on Linux — which is what broke the publish CI.
+if [ "$(uname -s)" = "Darwin" ]; then
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_NO_SYNC=0 claude-accounts sync 2>&1)"
+check "a replica with a server target still refuses to push" "sync replica" "$out"
+else
+t_ok "server-target sync refusal skipped (sync is Mac-only; this host is $(uname -s))"
+fi
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_NO_SYNC=0 \
+       claude-accounts import-credential --in "$PP/blob.json" 2>&1)"
+case "$out" in
+  *"sync failed"*|*"push"*) t_fail "replica auto_sync" "a replica mutation tried to push: $out" ;;
+  *) t_ok "a mutation on a replica never pushes (auto_sync stays silent)" ;;
+esac
+rm -f "$JP/sync-role"
+
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" CLAUDE_MULTIACC_SYNC_TARGET="ops@x; touch $WORK/PWNED" \
+       CLAUDE_MULTIACC_NO_SYNC=0 claude-accounts sync 2>&1)"
+rc=$?
+if [ "$(uname -s)" = "Darwin" ]; then
+  check "an injected SYNC_TARGET is refused" "not a plain user@host" "$out"
+else
+  t_ok "injected SYNC_TARGET refusal message skipped (sync is Mac-only here)"
+fi
+# The part that matters everywhere: refused, and never executed.
+[ "$rc" != "0" ] && [ ! -f "$WORK/PWNED" ] && t_ok "injected sync target never executed" \
+  || t_fail "sync target injection" "rc=$rc"
+
+# ---- 20e. codex parity: no portable class, identity transfer only -------------------
+CX2="$PP/codex-a"
+mkdir -p "$CX2/acct-01"
+cat > "$CX2/accounts.json" <<'EOF'
+{"version":1,"server":"none","server_root":"/root/.codex-accounts","server_repo":"/root/claude-multiacc",
+ "threshold":90,"accounts":[{"id":"acct-01","email":"cx@panel","home":"mac","added_at":"2026-04-05T06:07:08Z"}]}
+EOF
+python3 - "$CX2/acct-01/auth.json" <<'EOF'
+import base64, json, sys, time
+b = lambda o: base64.urlsafe_b64encode(json.dumps(o).encode()).decode().rstrip('=')
+jwt = lambda c: b({"alg": "none"}) + '.' + b(c) + '.sig'
+json.dump({"auth_mode": "chatgpt", "OPENAI_API_KEY": None,
+           "tokens": {"id_token": jwt({"email": "cx@panel"}),
+                      "access_token": jwt({"exp": time.time() + 9999}),
+                      "refresh_token": "r", "account_id": "acc"},
+           "last_refresh": "2026-08-01T00:00:00Z"}, open(sys.argv[1], "w"))
+EOF
+CODEX_ACCOUNTS_ROOT="$CX2" codex-accounts list --json > "$PP/cx-list.json"
+python3 - "$PP/cx-list.json" "$CX2" <<'EOF'
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert d["provider"] == "codex" and d["pool"]["root"] == sys.argv[2], d["pool"]
+a = d["accounts"][0]
+assert a["status"] == "active", a
+assert a["credential_class"] == "machine-local" and a["portable"] is False, a
+assert d["summary"]["portable"] == 0, d["summary"]
+assert d["pool"]["sync"]["mode"] == "local", d["pool"]["sync"]
+EOF
+[ $? -eq 0 ] && t_ok "codex list --json: same schema, no portable credentials" \
+  || t_fail "codex list --json" "see $PP/cx-list.json"
+out="$(CODEX_ACCOUNTS_ROOT="$CX2" codex-accounts export-credential acct-01 2>&1)"
+rc=$?
+check "codex export always refuses" "no portable credential type" "$out"
+check "codex export points at the device-code login" "codex-accounts login acct-01" "$out"
+[ "$rc" = "3" ] && t_ok "codex export exits 3 (machine-local)" || t_fail "codex export rc" "rc=$rc"
+CODEX_ACCOUNTS_ROOT="$CX2" codex-accounts export-credential acct-01 --identity-only --out "$PP/cx-ident.json" >/dev/null
+mkdir -p "$PP/codex-b"
+printf '{"version":1,"server":"none","threshold":90,"accounts":[]}\n' > "$PP/codex-b/accounts.json"
+out="$(CODEX_ACCOUNTS_ROOT="$PP/codex-b" codex-accounts import-credential --in "$PP/cx-ident.json" 2>&1)"
+rc=$?
+check "codex identity import registers the account" "Registered acct-01 (cx@panel" "$out"
+check "codex identity import asks for a local sign-in" "codex-accounts login acct-01" "$out"
+[ "$rc" = "0" ] && t_ok "codex identity import exits 0" || t_fail "codex identity import rc" "rc=$rc"
+python3 - "$PP/codex-b/accounts.json" <<'EOF'
+import json, sys
+a = json.load(open(sys.argv[1]))["accounts"][0]
+assert a["added_at"] == "2026-04-05T06:07:08Z", a    # source metadata preserved
+EOF
+[ $? -eq 0 ] && t_ok "codex identity transfer keeps the source added_at" \
+  || t_fail "codex identity metadata" "see $PP/codex-b/accounts.json"
+
+# ---- 20f. codex-review follow-ups: hostile pool roots, empty fields, marker rule ----
+# A pool root carrying shell metacharacters must never reach a trap body or a remote
+# command as code. (install.sh refuses to SCHEDULE such a root; the CLI must still be
+# safe when one is used directly.)
+QROOT="$PP/q'; touch $WORK/TRAP_PWNED; '"
+mkdir -p "$QROOT"
+printf '{"version":1,"server":"none","threshold":90,"accounts":[]}\n' > "$QROOT/accounts.json"
+rm -f "$WORK/TRAP_PWNED"
+out="$(CLAUDE_ACCOUNTS_ROOT="$QROOT" claude-accounts import-credential --in "$PP/blob.json" 2>&1)"
+rc=$?
+check "import works from a pool root with shell metacharacters" "Imported acct-01" "$out"
+[ "$rc" = "0" ] && [ ! -f "$WORK/TRAP_PWNED" ] \
+  && t_ok "a quoted pool root never executes as code (trap body)" \
+  || { t_fail "pool root injection" "rc=$rc, sentinel=$([ -f "$WORK/TRAP_PWNED" ] && echo CREATED)"; rm -f "$WORK/TRAP_PWNED"; }
+out="$(CLAUDE_ACCOUNTS_ROOT="$QROOT" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-panel.json" \
+       claude-accounts limits --json 2>/dev/null | python3 -c "import json,sys;print(json.load(sys.stdin)['accounts'][0]['id'])" 2>&1)"
+check "limits --json survives a quoted pool root" "acct-01" "$out"
+[ ! -f "$WORK/TRAP_PWNED" ] && t_ok "the limits lock trap never executes a quoted root" \
+  || { t_fail "limits trap injection" "sentinel created"; rm -f "$WORK/TRAP_PWNED"; }
+
+# An empty metadata field must stay empty: the record separator is 0x1F precisely
+# because bash collapses runs of IFS *whitespace*, which would shift added_at into home.
+python3 - "$PP/blob.json" "$PP/blob-nohome.json" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+b["account"]["home"] = ""
+b["account"]["email"] = "nohome@test"
+json.dump(b, open(sys.argv[2], "w"))
+EOF
+NH="$PP/claude-nohome"
+mkdir -p "$NH"
+printf '{"version":1,"server":"none","threshold":90,"accounts":[]}\n' > "$NH/accounts.json"
+CLAUDE_ACCOUNTS_ROOT="$NH" claude-accounts import-credential --in "$PP/blob-nohome.json" >/dev/null 2>&1
+python3 - "$NH/accounts.json" <<'EOF'
+import json, sys
+a = json.load(open(sys.argv[1]))["accounts"][0]
+assert a["email"] == "nohome@test", a
+# home falls back to this machine, and added_at is NOT the value that would land there
+# if the empty field had collapsed
+assert a["home"] in ("mac", "linux"), a
+assert a["added_at"] == "2026-01-02T03:04:05Z", a
+EOF
+[ $? -eq 0 ] && t_ok "a blob with an empty field imports without shifting the next one" \
+  || t_fail "empty-field record" "see $NH/accounts.json"
+
+# Metadata carrying a control character is refused rather than truncating the record.
+python3 - "$PP/blob.json" "$PP/blob-ctrl.json" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+b["account"]["email"] = "evil@test\nacct-99"
+json.dump(b, open(sys.argv[2], "w"))
+EOF
+out="$(CLAUDE_ACCOUNTS_ROOT="$NH" claude-accounts import-credential --in "$PP/blob-ctrl.json" 2>&1)"
+rc=$?
+check "metadata with a control character is refused" "control character" "$out"
+[ "$rc" != "0" ] && t_ok "control-character blob exits nonzero" || t_fail "control char blob" "exited 0"
+
+# An adopted account is a symlink: a credential must never be written THROUGH it,
+# not even with --force (--force settles identity, it does not authorize escaping the pool).
+mkdir -p "$PP/outside"
+ln -s "$PP/outside" "$JP2/acct-09"
+python3 - "$PP/blob.json" "$PP/blob-09.json" <<'EOF'
+import json, sys
+b = json.load(open(sys.argv[1]))
+b["account"]["id"] = "acct-09"
+json.dump(b, open(sys.argv[2], "w"))
+EOF
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP2" claude-accounts import-credential acct-09 --in "$PP/blob-09.json" --force 2>&1)"
+rc=$?
+check "import refuses to write through an adopted symlink" "must never be written through it" "$out"
+[ "$rc" != "0" ] && [ ! -f "$PP/outside/server.token" ] \
+  && t_ok "--force does not authorize writing outside the pool" \
+  || t_fail "symlink import" "rc=$rc, wrote=$([ -f "$PP/outside/server.token" ] && echo yes)"
+rm -f "$JP2/acct-09"
+
+# The exported blob must land 0600 even when a world-readable file is already there.
+: > "$PP/pre-existing.json"
+chmod 644 "$PP/pre-existing.json"
+CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts export-credential acct-01 --out "$PP/pre-existing.json" >/dev/null
+case "$(ls -l "$PP/pre-existing.json" | cut -c1-10)" in
+  -rw-------) t_ok "export --out replaces a world-readable file with a 0600 one" ;;
+  *) t_fail "export --out perms over existing file" "$(ls -l "$PP/pre-existing.json" | cut -c1-10)" ;;
+esac
+
+# The JSON report must apply the shim's marker rule exactly: a marker whose reset has
+# passed is NOT limited (the shim deletes it and selects the account), while a garbled
+# marker IS (the shim treats it as active rather than racing a concurrent write).
+printf '%s\nbucket=weekly percent=95 reason=limits\n' "$((now-600))" > "$JP/acct-01/.limited"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts list --json | python3 -c "
+import json,sys; a={x['id']:x for x in json.load(sys.stdin)['accounts']}['acct-01']
+print(a['status'], a['limited'], a['selectable'])")"
+check "an elapsed .limited marker does not read as limited" "active False True" "$out"
+printf 'garbled\n' > "$JP/acct-01/.limited"
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts list --json | python3 -c "
+import json,sys; a={x['id']:x for x in json.load(sys.stdin)['accounts']}['acct-01']
+print(a['status'], a['limited'])")"
+check "a garbled .limited marker reads as limited (same as the shim)" "limited True" "$out"
+rm -f "$JP/acct-01/.limited"
+
+# --json must not swallow a following typo, and a broken refresh must not be reported
+# as success just because the document rendered.
+out="$(CLAUDE_ACCOUNTS_ROOT="$JP" claude-accounts list --json --bogus 2>&1)"
+rc=$?
+check "list --json rejects an unknown extra option" "unknown option: --bogus" "$out"
+[ "$rc" != "0" ] && t_ok "list --json --bogus exits nonzero" || t_fail "strict --json parsing" "exited 0"
+BROKEN="$PP/claude-broken"
+mkdir -p "$BROKEN"
+printf 'not json at all\n' > "$BROKEN/accounts.json"
+out="$(CLAUDE_ACCOUNTS_ROOT="$BROKEN" claude-accounts limits --json 2>/dev/null)"
+rc=$?
+[ "$rc" != "0" ] && t_ok "limits --json propagates a failed refresh (nonzero)" \
+  || t_fail "limits --json exit code" "exited 0 on an unreadable manifest"
+printf '%s' "$out" | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+assert d['accounts'] == [], d
+assert any('manifest' in w for w in d['warnings']), d['warnings']
+" 2>/dev/null \
+  && t_ok "limits --json still emits a document (with a warning) when the pool is broken" \
+  || t_fail "limits --json on a broken pool" "no usable document"
+
 # ---- summary ---------------------------------------------------------------------
 echo
 echo "passed: $PASS  failed: $FAIL"