claude-multiacc 2.0.21 → 2.0.22

package/README.md

@@ -16,7 +16,7 @@ completely independent — separate manifests, credentials, telemetry, and logs
 either provider can be used, re-authenticated, or emptied without touching the other.
 
 Tested on: macOS (bash 3.2, zsh, Claude Code 2.1.207+, Codex CLI 0.147) and Ubuntu 24.04
-(bash 5.2). The compatibility suite currently covers 834 sandboxed cases with no
+(bash 5.2). The compatibility suite currently covers 918 sandboxed cases with no
 network/quota use; the unified selector has its own adversarial contract suite.
 
 ## Unified selector for app-robot
@@ -177,6 +177,22 @@ buckets keep being tracked and the ≥90% rule keeps working. Unparseable entrie
 skipped, an all-legacy payload falls back to `five_hour`/`seven_day`, and a payload the
 code cannot read at all degrades that one account (fail open), never the run.
 
+**A 0% bucket with no reset window is no data, not an empty account.** Real usage always
+carries the window it resets in, so `percent: 0` with a null `resets_at` is the endpoint
+declining to answer — and taking it at face value put two weekly-exhausted accounts at the
+top of the ranking for 31 of ~60 picks on 2026-09-04. Only *informative* buckets (percent
+above 0, or a parseable reset time) are aggregated, **per signal**: `weekly_percent` is the
+peak over informative *weekly* buckets, `session_percent` over informative *session* ones,
+and each is simply omitted when its own group has nothing informative in it — a weekly
+figure is never borrowed from the session bucket. An account with no informative bucket at
+all gets a `limits.json` with none of `max_percent`/`weekly_percent`/`session_percent`,
+marked `"no_data": true`. Either way the account ranks **unknown** — selection needs BOTH
+readings, so a half-filled document is as unknown as an empty one: never the band leader,
+never past the session gate, never able to clear a marker, and a pool made only of them
+logs `ranking=BLIND` instead of quietly tying every account. Accounts that really are idle
+are untouched: 0% with a real reset window is informative and still ranks as empty, and one
+blank per-model bucket beside real ones leaves the real ones in charge.
+
 Telemetry failures never block work: no fresh data ⇒ account treated as available. The
 endpoint rate-limits per account, so the refresher skips accounts fetched in the last 4 min
 and backs off on **every** non-2xx, not just a 429 — honoring `Retry-After`, and parking
@@ -274,8 +290,20 @@ wrongly parked account is worse than a missed limit:
 
 The resulting marker is tagged `reason=client-rate-limit` and outlives a clean telemetry
 pass while its window is still open — first-hand evidence beats a usage payload that
-disagrees. Cost is bounded: the three newest sessions per account, a tail read rather than
-a whole transcript, and a clean result memoized for 20s
+disagrees. A **weekly** rejection is absolute: nothing — neither a shim invocation nor the
+scheduled `limits` pass — retires it before its reset epoch, since a weekly bucket cannot
+fall from a server-proven 100% back under the threshold inside that window. Claude names
+that bucket from the API's own type (`bucket=client:seven_day`); codex has no such name in
+its rollout files, only `primary`/`secondary` keys whose meaning moves, so it labels the
+marker from the window itself — `window_minutes >= 1440` ⇒ `client:7d`, a shorter window ⇒
+`client:5h`, and a window with no `window_minutes` at all stays `client:<key>` and remains
+clearable (fail open, bounded by its own reset). A five-hour marker can
+still be retired by telemetry fetched well after it
+(`CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY`, 300s), which is what keeps a fresh account
+from being stranded by an old session limit — before 2026-09-04 that carve-out also let
+fake-zero telemetry retire weekly markers, re-admitting an exhausted account six times a
+day. Cost is bounded: the three newest sessions per account, a tail read rather than a whole
+transcript, and a clean result memoized for 20s
 (`CLAUDE_MULTIACC_CLIENT_SCAN_TTL`), which on a three-account pool of large live
 transcripts is ~2 ms per run amortized.
 

package/bin/claude

@@ -276,7 +276,7 @@ scoped_over_tok() { # $1 = acct dir
 CLIENT_RECOVERY_FETCHED=0
 CLIENT_RECOVERY_PEAK=100
 client_marker_recovered() { # $1 account dir, $2 marker
-  local fetched peak delay marked mk cutoff ck newer=0
+  local fetched peak delay marked mk cutoff ck newer=0 bucket
   # A client rejection is stronger than an immediately-following usage read: that
   # endpoint can lag or serve a cached bucket. It is not stronger forever. Once a
   # successful, below-threshold reading was fetched at least five minutes after the
@@ -284,7 +284,28 @@ client_marker_recovered() { # $1 account dir, $2 marker
   # old/shared transcript was attributed incorrectly). Keeping such a marker until its
   # claimed reset stranded five 0%-usage accounts in the live pool on 2026-09-03.
   if grep -q 'reason=client-rate-limit' "$2" 2>/dev/null; then
+    # ...but a WEEKLY rejection is stronger than any telemetry until its own reset.
+    # Line 2 carries bucket=client:<type> (five_hour, seven_day, seven_day_opus, …).
+    # A seven-day window only refills on its multi-day reset, so it cannot have fallen
+    # from the server-proven 100% that wrote this marker to under the threshold while
+    # the window is still open: a reading that says otherwise is wrong by construction.
+    # 2026-09-04: acct-13/acct-14 were served fake-zero telemetry (every bucket
+    # percent 0, resets_at null), which read as 0% here and deleted their truthful
+    # client:seven_day markers ~6x/day each; an interactive session was handed both
+    # accounts in a row and was rejected by each with "You've hit your weekly limit".
+    # five_hour/session markers keep clearing exactly as before — that window self-heals
+    # within hours, which is why #22 (2026-09-03) had to clear it.
+    bucket="$(sed -n 2p "$2" 2>/dev/null)"
+    case "$bucket" in
+      *bucket=*) bucket="${bucket#*bucket=}"; bucket="${bucket%% *}" ;;
+      *) bucket="" ;;
+    esac
+    case "$(sel_lc "$bucket")" in *seven_day*|*7d*|*weekly*) return 1 ;; esac
     fetched="$(telem_fetched_at "$1" 2>/dev/null || echo 0)"
+    # Defaulting peak to 100 when the reading is missing/stale is the second half of the
+    # same rule: an UNINFORMATIVE reading must never clear a marker. It is what keeps a
+    # no_data account (2026-09-04: all-zero buckets with no reset windows write no
+    # max_percent at all) from unparking itself.
     peak="$(cutoff_field "$1" max_percent 2>/dev/null || echo 100)"
     delay="${CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY:-300}"
     num_ok "$delay" || delay=300
@@ -411,12 +432,39 @@ stale_weekly() { # $1 = acct dir
   limits_field "$1" weekly_percent
 }
 
-# TRUE when this account contributes nothing to ranking: no in-window telemetry at all.
-# When every candidate is blind, no candidate has a known reading, pick_best sees one
-# enormous tie, and selection quietly becomes uniform random — the failure this whole
-# file exists to prevent.
+# TRUE when this account contributes nothing to ranking: no in-window telemetry, or an
+# in-window document that is not a COMPLETE reading. When every candidate is blind,
+# no candidate has a known reading, pick_best sees one enormous tie, and selection
+# quietly becomes uniform random — the failure this whole file exists to prevent.
+# A fresh timestamp is not the same thing as a usable reading: since 2026-09-04 the
+# writer refuses to invent percentages from all-zero buckets with no reset window and
+# writes `no_data` instead, so such a document is current, well-formed, and ranks
+# nothing. Judging blindness on fetched_at alone called a pool of those "fresh" while
+# every account read as unknown and selection was in fact a coin flip.
+# BOTH fields are required, exactly as pick_best's "known" rule requires them (and
+# pool-selection.v2's quota_known): the same 2026-09-04 writer change also emits
+# one-signal documents per signal (weekly-only when no session bucket is informative,
+# and the converse), and an EITHER test called a pool of those sighted while pick_best
+# read every one of them as unknown and tied the whole pool — the coin flip again, this
+# time with no ranking=BLIND line and a status saying "fresh". The degraded path takes
+# one more guard for the same reason (assess_telemetry): a reading counts toward
+# DEGRADED only when it is genuinely OUT of the ranking window — degraded exists for an
+# outage, and a FRESH weekly-only document must not smuggle the very reading the
+# quota_known rule just refused back in as "old truth" (codex review, 2026-09-04).
+# A no_data document (no weekly_percent, no horizon) stays un-degradable either way.
+# Asked through limits_field, the SAME parser rank_weekly_of/rank_session_of use, so
+# this can never disagree with them about what "known" means. Both calls only ever run
+# for a blind-looking account (assess_telemetry stops at the first ranking one).
+# TELEM_FRESH_UNUSABLE is set as a side effect for the operator warning: the pool is
+# then blind with CURRENT data, which is a different fault (and a different fix) from
+# telemetry that merely went stale. Set here because the window test is already paid
+# for; this file is deliberately fork-frugal (see sessions_owned).
+TELEM_FRESH_UNUSABLE=0
 telem_blind() { # $1 = acct dir
-  ! within_window "$1" "$STALE_AFTER"
+  within_window "$1" "$STALE_AFTER" || return 0
+  limits_field "$1" weekly_percent >/dev/null 2>&1 || { TELEM_FRESH_UNUSABLE=1; return 0; }
+  limits_field "$1" session_percent >/dev/null 2>&1 || { TELEM_FRESH_UNUSABLE=1; return 0; }
+  return 1
 }
 
 # Human age for the warning line: seconds -> "3h" / "11d". Never fails.
@@ -1225,8 +1273,10 @@ pick_best() { # args: candidate dirs
     # otherwise be the sole gate-clearer and win the all-gated tie over an account whose
     # truthful weekly reading merely failed the gate. The one exception is a DEGRADED pool
     # (SEL_DEGRADED=1): nothing is fresh anywhere, the gate has necessarily stepped aside,
-    # and a still-valid stale weekly reading is the only truth there is. (Neither writer
-    # emits one field without the other; this is parity with lib/selector_policy.py.)
+    # and a still-valid stale weekly reading is the only truth there is. (The writers DO
+    # emit one-signal documents — per-signal informative aggregation, 2026-09-04 — and
+    # such a document is exactly as unknown here as an empty one; parity with
+    # lib/selector_policy.py's quota_known.)
     if [ "$k" = 1 ] && { [ "$sk" = 1 ] || [ "$SEL_DEGRADED" = 1 ]; }; then
       weekly+=("$w"); known+=(1)
     else
@@ -1294,6 +1344,9 @@ degraded=0        # 1 = blind, but every candidate had a stale reading still wor
 assess_telemetry() { # args: the dirs actually being chosen between
   local d f n=0 stale_ok=0
   blind=1; blind_age=0; degraded=0
+  # Re-armed per assessment: the fallback path assesses a second candidate set, and a
+  # verdict from the first one must not colour the warning printed for the second.
+  TELEM_FRESH_UNUSABLE=0
   for d in "$@"; do
     n=$((n + 1))
     if ! telem_blind "$d"; then blind=0; return 0; fi
@@ -1302,7 +1355,15 @@ assess_telemetry() { # args: the dirs actually being chosen between
     # never fetched at all must not make the pool look older than it is.
     [ "$f" -gt 0 ] && { [ "$blind_age" -eq 0 ] || [ $((now - f)) -lt "$blind_age" ]; } \
       && blind_age=$((now - f))
-    stale_weekly "$d" >/dev/null && stale_ok=$((stale_ok + 1))
+    # Only a reading that is genuinely OUT of the ranking window may count toward
+    # DEGRADED: degraded exists for an outage ("nothing fresh anywhere, rank on old
+    # truths"), not for a fresh document that simply lacks a signal. A fresh
+    # weekly-only file already read as blind above (one-signal is unknown, 2026-09-04);
+    # letting its still-in-window weekly enable degraded would rank the pool on the
+    # very reading the two-cut rule just refused (codex review, 2026-09-04).
+    if ! within_window "$d" "$STALE_AFTER"; then
+      stale_weekly "$d" >/dev/null && stale_ok=$((stale_ok + 1))
+    fi
   done
   # All or nothing. A candidate whose reading has no horizon — a limits.json written
   # before this field existed, or one whose week has already turned — stays UNKNOWN even
@@ -1470,9 +1531,21 @@ if [ "$blind" = 1 ]; then
     [ -f "$n" ] && last="$(file_mtime "$n")"
     if [ $((now - last)) -gt 3600 ]; then
       : 2>/dev/null > "$n" || true
+      # Three faults, three fixes, and telling them apart is the whole point of this
+      # line. Telemetry that went STALE is fixed by fetching again (and, if that keeps
+      # failing, by an OAuth login). Telemetry that arrived CURRENT and said nothing
+      # rankable — a 2026-09-04 no_data document, or a one-signal one — is not stale at
+      # all: refetching returns the same emptiness and a re-login fixes nothing, so
+      # advising one sends the operator down the wrong path (E4, 2026-09-04). The state
+      # is already known here: telem_blind sets TELEM_FRESH_UNUSABLE while testing the
+      # window it had to test anyway.
+      # (degraded && FRESH_UNUSABLE cannot happen: a fresh-but-unusable candidate is
+      # not counted by assess_telemetry, and degraded is all-or-nothing.)
       if [ "$degraded" = 1 ]; then
         printf 'claude-multiacc: usage telemetry is %s old — ranking on the last readings that are still valid, not on current usage. Fix: claude-accounts limits --force, then claude-accounts status\n' \
           "$(age_human "$blind_age")" >&2
+      elif [ "$TELEM_FRESH_UNUSABLE" = 1 ]; then
+        printf 'claude-multiacc: usage telemetry is CURRENT but carries no usable reading for any account (the endpoint answered with no percentages, or only half of them) — selection is running blind (random, not by headroom). Refetching and re-logging in will not change it: claude-accounts status\n' >&2
       elif [ "$blind_age" -gt 0 ]; then
         printf 'claude-multiacc: usage telemetry is %s old for EVERY account and too old to mean anything — selection is running blind (random, not by headroom). Fix: claude-accounts limits --force, then claude-accounts status\n' \
           "$(age_human "$blind_age")" >&2

package/bin/claude-accounts

@@ -379,7 +379,14 @@ for a in doc.get('accounts', []):
             # entirely and picks at random, so the reading below is decoration.
             stale = age is None or age > STALE_AFTER
             flag = '  << STALE — NOT USED FOR RANKING' if stale else ''
-            print(f"  limits      : {'  '.join(parts) or '(none)'}  [{shown}, max {lim.get('max_percent')}%]{flag}")
+            # A no_data document (all-zero buckets with no reset windows, 2026-09-04)
+            # carries no percent fields at all. Printing "max None%" would read like a
+            # healthy account sitting at zero — the exact misreading that handed 31 of
+            # ~60 picks to two exhausted accounts — so name the state instead.
+            peak = lim.get('max_percent')
+            usable = isinstance(peak, (int, float)) and not isinstance(peak, bool)
+            head = f'max {peak}%' if usable else 'NO USABLE TELEMETRY — ranks as unknown'
+            print(f"  limits      : {'  '.join(parts) or '(none)'}  [{shown}, {head}]{flag}")
             err = lim.get('last_error')
             if isinstance(err, str) and err:
                 when = lim.get('last_error_at')
@@ -428,14 +435,46 @@ if verdict == 'unknown':
     print(f"RANKING STATE UNKNOWN: could not compute the pool-wide telemetry verdict "
           f"({verdict_err}). Check the per-account ages above by hand.")
 elif verdict == 'blind':
-    print("RANKING IS BLIND: no account has usage telemetry inside the "
-          f"{STALE_AFTER}s window, and the last readings are too old to mean anything, "
-          "so every account scores the same and `claude` picks at RANDOM — including "
-          "accounts that are nearly out of weekly headroom.")
-    print("  why : see the 'telemetry' lines above (a setup token cannot read the usage "
-          "endpoint — it has no user:profile scope; only an OAuth login on this machine can)")
-    print("  fix : claude-accounts limits --force   # then, if it still fails:")
-    print("        claude-accounts login <acct-NN>  # per account, on THIS machine")
+    # Two ways to be blind, and they take OPPOSITE advice. STALE: the fetches stopped,
+    # so fetch again and, if that keeps failing, log in — the eleven-day 2026-08 outage.
+    # CURRENT-BUT-UNUSABLE: the endpoint answered inside the window and said nothing
+    # rankable (a no_data document — all-zero buckets with no reset window, 2026-09-04 —
+    # or a reading carrying only one of the two percentages). There the credential is
+    # working perfectly; telling the operator to re-login sends them after a fault that
+    # does not exist, and --force just re-asks for the same emptiness. The candidate
+    # rule below is telemetry_state's own, so this text can never name a state the
+    # verdict did not come from.
+    usable_rows = [a for a in doc_rows if a.get('status') in ('active', 'limited')]
+    cands = [a for a in usable_rows if a.get('status') == 'active'] or usable_rows
+    current = [a for a in cands if (a.get('usage') or {})
+               and not (a.get('usage') or {}).get('stale')]
+    nodata = [a['id'] for a in current if (a.get('usage') or {}).get('no_data')]
+    if current:
+        print("RANKING IS BLIND: usage telemetry is INSIDE the "
+              f"{STALE_AFTER}s window but carries no reading the shim can rank on, so "
+              "every account scores the same and `claude` picks at RANDOM — including "
+              "accounts that are nearly out of weekly headroom.")
+        if nodata:
+            print("  why : the usage endpoint returned no usable data for "
+                  f"{', '.join(nodata)} — all-zero buckets with no reset window, which "
+                  'the writer records as "no_data": true rather than as 0% usage. '
+                  "Those fetches authenticated; a re-login does NOT fix this.")
+        else:
+            print("  why : the readings are incomplete — ranking needs BOTH a weekly and "
+                  "a session percentage (see the 'limits' lines above); an account with "
+                  "only one of them is unknown to selection, exactly as if it had none.")
+        print("  fix : nothing local to repair — the endpoint has to answer with real "
+              "buckets again. `claude-accounts limits --force` re-asks; while it keeps "
+              "answering this way, selection stays random.")
+    else:
+        print("RANKING IS BLIND: no account has usage telemetry inside the "
+              f"{STALE_AFTER}s window, and the last readings are too old to mean anything, "
+              "so every account scores the same and `claude` picks at RANDOM — including "
+              "accounts that are nearly out of weekly headroom.")
+        print("  why : see the 'telemetry' lines above (a setup token cannot read the usage "
+              "endpoint — it has no user:profile scope; only an OAuth login on this machine can)")
+        print("  fix : claude-accounts limits --force   # then, if it still fails:")
+        print("        claude-accounts login <acct-NN>  # per account, on THIS machine")
 elif verdict == 'degraded':
     print("RANKING IS DEGRADED: no account has telemetry inside the "
           f"{STALE_AFTER}s window, so `claude` is ranking on the last readings whose "
@@ -1402,7 +1441,22 @@ limits_distribute() {
 limits_distribute_now() {
   local lock="$ACC_ROOT/tmp/limits-push.lock"
   mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || return 0
-  mkdir "$lock" 2>/dev/null || return 0
+  if ! mkdir "$lock" 2>/dev/null; then
+    # A DETACHED push that is killed (logout, reboot, pkill) never runs its EXIT trap,
+    # and mkdir can never take a lock dir nobody will remove: one stranded lock
+    # silently stopped ALL telemetry distribution on the live pool from 2026-09-03
+    # 00:29 until it was deleted by hand on 2026-09-04 — 32 hours in which every peer
+    # ranked on whatever limits.json it happened to already have, which is the exact
+    # blindness this push exists to prevent, and nothing anywhere said so. A push is
+    # seconds of rsync under hard timeouts (--timeout=20, ConnectTimeout=10), so a
+    # lock older than ten minutes belongs to a process that is gone: break it and
+    # retake it. If the retake still fails, a live pusher owns it and this pass skips,
+    # exactly as before.
+    [ $(( $(epoch_now) - $(file_mtime "$lock") )) -gt 600 ] || return 0
+    rm -rf "$lock" 2>/dev/null
+    mkdir "$lock" 2>/dev/null || return 0
+    log_to sync.log "stale limits-push lock broken (older than 600s); distributing"
+  fi
   trap 'rmdir "$lock" 2>/dev/null || true' EXIT
   local server sroot list id d
   list="$ACC_ROOT/tmp/limits-push.$$"
@@ -1544,6 +1598,34 @@ def parse_iso(s):
     except Exception:
         return None
 
+# The ONE rule for deleting a `.limited` marker on a clean pass. It is the writer half
+# of the shim's client_marker_recovered and has to be the SAME rule: the scheduled
+# limits pass runs every 15 minutes, so a writer that clears more freely than the shim
+# just undoes the shim's fix on its own timer. Before 2026-09-04 it did exactly that —
+# a truthful client:seven_day marker was deleted 300s after it was written, on a pass
+# whose every bucket said `percent 0, resets_at null`, i.e. on nothing at all.
+#   * a pass with NO informative bucket proves nothing, so it clears nothing;
+#   * a client rejection naming a WEEKLY window outlives every reading until its own
+#     reset — a weekly bucket cannot fall from the server-proven 100% that wrote the
+#     marker to under the threshold while that window is still open, so a reading
+#     that says it did is wrong by construction;
+#   * a client rejection naming a session/5h window still clears once the pass is
+#     informative and at least CLIENT_LIMIT_CONFIRM_DELAY newer than the marker (#22,
+#     2026-09-03: 5h markers stranded accounts sitting at 0% usage for days);
+#   * error-cooldown is untouched: it keeps its own window out, exactly as before.
+def marker_bucket(txt):
+    for part in txt.split():
+        if part.startswith('bucket='):
+            return part[7:]
+    return ''
+
+def weekly_marker(txt):
+    # Matched the way both shims match it (bin/claude ~303, same token list): the
+    # claude client writes client:seven_day / client:seven_day_opus, the codex client
+    # writes client:7d, and any future weekly* name is caught too.
+    b = marker_bucket(txt).lower()
+    return 'seven_day' in b or '7d' in b or 'weekly' in b
+
 # `.expired` — the persistent "this account cannot authenticate" marker the shim
 # honors. Written only for a PROVEN dead grant (expired/absent refresh token, or a
 # 4xx from the refresh endpoint), never for a transient network/5xx/429 hiccup.
@@ -2160,11 +2242,37 @@ for acct in manifest.get('accounts', []):
     #                    the shim ranks only accounts at/under CLAUDE_MULTIACC_SESSION_GATE
     #                    (default 50) while any clear it. (A soft tiebreaker until
     #                    2026-09-03 — the operator asked for session FIRST, then weekly.)
-    maxp = max([b['percent'] for b in buckets] or [0])
-    weekly = [b['percent'] for b in buckets if b['group'] != 'session']
-    session = [b['percent'] for b in buckets if b['group'] == 'session']
-    weeklyp = max(weekly) if weekly else maxp
-    sessionp = max(session) if session else 0
+    # A bucket only feeds those three signals if it SAID something. An INFORMATIVE
+    # bucket has a percent above 0, or a parseable reset window. 2026-09-04: for
+    # acct-13/acct-14 the usage endpoint answered EVERY bucket `percent: 0,
+    # resets_at: null` while Claude Code was being rejected on those same accounts
+    # with "You've hit your weekly limit · resets Sep 8"; this writer recorded the
+    # zeros verbatim, which made two provably exhausted accounts the leaders of the
+    # weekly band and handed them 31 of the last ~60 picks. A truthful bucket ALWAYS
+    # carries the window it resets in, so 0% with no window is NO DATA, not an empty
+    # account. 0% WITH a real window stays informative — a genuinely fresh account
+    # must still rank as empty — and one uninformative bucket beside real ones (the
+    # acct-16 shape: `weekly_scoped:Fable` 0/null next to a real session and
+    # weekly_all) leaves the real buckets ranking exactly as they do today.
+    def informative(b):
+        return b['percent'] > 0 or parse_iso(b.get('resets_at')) is not None
+
+    live = [b for b in buckets if informative(b)]
+    weekly = [b['percent'] for b in live if b['group'] != 'session']
+    session = [b['percent'] for b in live if b['group'] == 'session']
+    # PER SIGNAL, never borrowed from another one. Each of the three answers a
+    # different question, so each is written only when a bucket of ITS OWN kind said
+    # something. Until 2026-09-04 weekly_percent fell back to the overall peak and
+    # session_percent to 0: an account whose weekly buckets were all uninformative
+    # while its 5h bucket read 40% was recorded as 40% WEEKLY — a number no bucket
+    # ever reported, and the signal the band ranks on — and the mirror image
+    # (informative weekly, silent session) was recorded as session 0%, which walks
+    # straight through the session gate. A signal nobody reported must be ABSENT so
+    # the shim reads it as unknown; inventing one is the same mistake as recording a
+    # fake zero, one layer up.
+    maxp = max([b['percent'] for b in live] or [0])
+    weeklyp = max(weekly) if weekly else None
+    sessionp = max(session) if session else None
     # How long weekly_percent keeps meaning something. A weekly bucket only ever RISES
     # until its reset, so before that moment a stale percent is still a valid lower
     # bound and the shim can rank on it when nothing fresher exists; after it, the
@@ -2173,13 +2281,32 @@ for acct in manifest.get('accounts', []):
     # It must come from the bucket weekly_percent actually CAME FROM: a low monthly
     # bucket resetting in an hour says nothing about an 80% weekly one that resets in
     # five days, and taking the minimum over all of them would throw the 80% away.
-    wresets = [int(b['resets_epoch']) for b in buckets
+    wresets = [int(b['resets_epoch']) for b in live
                if b['group'] != 'session' and b['percent'] == weeklyp
                and isinstance(b.get('resets_epoch'), int)]
-    out = {'fetched_at': int(now), 'source': source, 'max_percent': maxp,
-           'weekly_percent': weeklyp, 'session_percent': sessionp,
-           'weekly_resets_epoch': min(wresets) if wresets else 0,
-           'buckets': buckets}
+    out = {'fetched_at': int(now), 'source': source}
+    if live:
+        out['max_percent'] = maxp
+    if weeklyp is not None:
+        out['weekly_percent'] = weeklyp
+    if sessionp is not None:
+        out['session_percent'] = sessionp
+    if weeklyp is not None:
+        # Written with weekly_percent or not at all: the horizon describes THAT
+        # reading, and the shim's degraded path needs both or neither.
+        out['weekly_resets_epoch'] = min(wresets) if wresets else 0
+    if not live:
+        # Nothing usable in the entire payload. Keep the diagnostics (fetched_at,
+        # source, the raw buckets) and write NONE of the three percent signals: a
+        # missing field makes the shim's fresh_field/cutoff_field reads fail, so the
+        # account is UNKNOWN to both selection cuts — never the weekly band's leader,
+        # never inside the session gate, and never able to clear a client-rate-limit
+        # marker. Unknown is the honest reading; "0%" is what re-admitted two provably
+        # exhausted accounts on 2026-09-04 (see informative() above).
+        out['no_data'] = True
+        say(f'{aid}: usage endpoint returned all-zero buckets with no reset windows — '
+            f'no usable telemetry (account ranks as unknown, not as empty)')
+    out['buckets'] = buckets
     tmp = lpath + '.tmp'
     with open(tmp, 'w') as f:
         json.dump(out, f, indent=1)
@@ -2205,14 +2332,37 @@ for acct in manifest.get('accounts', []):
         worst = max(account_level or offenders,
                     key=lambda b: (int(b['resets_epoch']), b['percent']))
         reset_epoch = int(worst['resets_epoch'])
-        # Atomic: a concurrent shim must never read a half-written marker.
-        with open(mpath + '.tmp', 'w') as f:
-            f.write(f'{reset_epoch}\n')
-            f.write(f"bucket={worst['name']} percent={worst['percent']} "
-                    f"marked_at={time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} "
-                    f"reason=limits resets_at={worst['resets_at']}\n")
-        os.replace(mpath + '.tmp', mpath)
-        say(f"{aid}: LIMITED {worst['name']} at {worst['percent']}% (resets {worst['resets_at']})")
+        # Never SHORTEN an active client-rate-limit marker. A client rejection is
+        # first-hand server evidence with its own reset; this pass's worst offender
+        # can be a mere session bucket an hour from resetting, and overwriting the
+        # marker with that shorter horizon re-admits a provably exhausted account
+        # early (codex review, 2026-09-04: a client:seven_day four days out replaced
+        # by a 95% session bucket +1h). A LATER reset may still extend the exclusion.
+        keep_client = False
+        try:
+            cur = open(mpath).read()
+            first = cur.splitlines()[0] if cur else ''
+            # The shims' own validity rule (num_ok: digits only, bounded length): a
+            # signed/padded/absurd first line is a GARBLED marker to them, and a
+            # garbled marker must be rewritten here, not preserved.
+            if first.isdigit() and len(first) <= 18:
+                cur_reset = int(first)
+                keep_client = ('reason=client-rate-limit' in cur
+                               and cur_reset > now and cur_reset >= reset_epoch)
+        except Exception:
+            pass
+        if keep_client:
+            say(f"{aid}: keeping the client-reported marker (its reset reaches further "
+                f"than this pass's worst offender)")
+        else:
+            # Atomic: a concurrent shim must never read a half-written marker.
+            with open(mpath + '.tmp', 'w') as f:
+                f.write(f'{reset_epoch}\n')
+                f.write(f"bucket={worst['name']} percent={worst['percent']} "
+                        f"marked_at={time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())} "
+                        f"reason=limits resets_at={worst['resets_at']}\n")
+            os.replace(mpath + '.tmp', mpath)
+            say(f"{aid}: LIMITED {worst['name']} at {worst['percent']}% (resets {worst['resets_at']})")
     else:
         if os.path.exists(mpath):
             # A shim-written marker outlives a clean limits pass while its own window
@@ -2235,11 +2385,17 @@ for acct in manifest.get('accounts', []):
                 if marked_epoch is None:
                     marked_epoch = os.path.getmtime(mpath)
                 recent_client = now - marked_epoch < CLIENT_LIMIT_CONFIRM_DELAY
-                client_recovered = active and 'reason=client-rate-limit' in txt \
-                    and not recent_client
-                if active and ('reason=error-cooldown' in txt
-                               or ('reason=client-rate-limit' in txt and recent_client)):
+                is_client = 'reason=client-rate-limit' in txt
+                # See weekly_marker() above for why these three come first and in
+                # this order; the shim applies the identical test per invocation.
+                if active and not live:
+                    keep = True
+                elif active and is_client and weekly_marker(txt):
+                    keep = True
+                elif active and ('reason=error-cooldown' in txt
+                                 or (is_client and recent_client)):
                     keep = True
+                client_recovered = active and is_client and not keep
             except Exception:
                 pass
             if not keep:
@@ -2249,7 +2405,16 @@ for acct in manifest.get('accounts', []):
                     with open(cleared + '.tmp', 'w') as f:
                         f.write(f'{int(now)}\n')
                     os.replace(cleared + '.tmp', cleared)
-                say(f'{aid}: marker cleared (max {maxp}%)')
+                # On a no-data pass `live` is empty and maxp is 0 only because
+                # nothing was reported (see informative() above). Log that, instead
+                # of a "0%" that reads like a proven-empty account — the exact
+                # misreading behind the 2026-09-04 incident.
+                seen = f'max {maxp}%' if live else 'no usable telemetry'
+                say(f'{aid}: marker cleared ({seen})')
+            elif not live:
+                # One line per account, so a no-data pass is legible in limits.log:
+                # the marker was not re-confirmed here, it was merely not disproved.
+                say(f'{aid}: marker kept (no usable telemetry)')
         if not quiet:
             detail = '  '.join(f"{b['name']}={b['percent']}%" for b in buckets)
             print(f'{aid}: ok  {detail}')