claude-multiacc 2.0.20 → 2.0.22

package/bin/codex-accounts

@@ -359,7 +359,15 @@ for a in doc.get('accounts', []):
             lim = json.load(open(lpath))
             age = int(now - lim.get('fetched_at', 0))
             parts = [f"{b['name']}={b['percent']}%" for b in lim.get('buckets', [])]
-            print(f"  limits      : {'  '.join(parts) or '(none)'}  [{age}s old, max {lim.get('max_percent')}%]")
+            # A no_data document (all-zero buckets with no reported reset windows —
+            # the 2026-09-04 claude incident, mirrored here for parity) carries no
+            # percent fields at all. Printing "max None%" would read like a healthy
+            # account sitting at zero, which is the misreading that handed picks to
+            # exhausted accounts; 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)'}  [{age}s old, {head}]")
         except Exception as e:
             print(f"  limits      : unreadable ({e})")
     else:
@@ -1079,6 +1087,14 @@ CLIENT_ID = os.environ.get('CODEX_MULTIACC_CLIENT_ID',
 REFRESH_MIN_EXPIRED = 300
 REFRESH_FAIL_BACKOFF = 600     # transient (network/5xx/429): retry in 10 min
 REFRESH_DENIED_BACKOFF = 21600  # 4xx = grant likely revoked: 6h; re-login needed anyway
+# A real client 429 beats an immediately-following usage response, which may be cached.
+# A later successful response under the threshold is newer first-hand evidence and must
+# release the account instead of preserving a false marker until a days-away reset.
+try:
+    CLIENT_LIMIT_CONFIRM_DELAY = max(
+        0, min(3600, int(os.environ.get('CODEX_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY', '300'))))
+except ValueError:
+    CLIENT_LIMIT_CONFIRM_DELAY = 300
 
 def say(msg):
     if not quiet:
@@ -1086,6 +1102,48 @@ def say(msg):
     with open(os.path.join(root, 'limits.log'), 'a') as f:
         f.write(time.strftime('%Y-%m-%dT%H:%M:%SZ ', time.gmtime()) + msg + '\n')
 
+def parse_iso(s):
+    if not s:
+        return None
+    try:
+        return datetime.datetime.fromisoformat(str(s).replace('Z', '+00:00')).timestamp()
+    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 the claude writer 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, and the codex
+    # client writes client:7d — a label bin/codex's client_limit_scan derives from the
+    # rollout's window_minutes (>= 1440), NOT the raw `primary`/`secondary` key names it
+    # wrote before 2026-09-04, which map to no fixed window and so were never protected
+    # here. Any future weekly* name is caught too. A legacy client:primary/secondary
+    # marker is therefore not weekly to this rule and stays clearable, exactly as it was
+    # before the guard existed; it expires at its own reset regardless.
+    b = marker_bucket(txt).lower()
+    return 'seven_day' in b or '7d' in b or 'weekly' in b
+
 def jwt_claims(token):
     try:
         payload = str(token).split('.')[1]
@@ -1395,8 +1453,15 @@ for acct in manifest.get('accounts', []):
         name = f'{scope}:{dur}' if scope else dur
         try:
             reset_epoch = int(float(win.get('reset_at')))
+            reset_known = True
         except (TypeError, ValueError):
             reset_epoch = int(now + (secs or 3600))
+            # Synthesized, not reported. Remembered because this writer FORMATS
+            # resets_at itself: unlike the claude payload, the finished bucket cannot
+            # be re-read later to tell a real window from a placeholder, and the
+            # no-data rule below turns on exactly that distinction. Stripped before
+            # the document is written so limits.json keeps its published shape.
+            reset_known = False
         return {
             'name': name,
             'kind': which,
@@ -1404,6 +1469,7 @@ for acct in manifest.get('accounts', []):
             'percent': pct,
             'resets_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(reset_epoch)),
             'resets_epoch': reset_epoch,
+            '_reset_known': reset_known,
         }
 
     def scope_buckets(scope, rl):
@@ -1425,6 +1491,9 @@ for acct in manifest.get('accounts', []):
                 'kind': 'limit_reached', 'group': 'weekly', 'percent': 100,
                 'resets_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(reset_epoch)),
                 'resets_epoch': reset_epoch,
+                # A server verdict, not a reported window: 100% is informative on its
+                # own, so the no-data rule below never depends on this flag here.
+                '_reset_known': False,
             })
         return out
 
@@ -1461,20 +1530,68 @@ for acct in manifest.get('accounts', []):
     # THREE selection signals, same reset asymmetry as the claude pool:
     #   max_percent    — peak of ALL buckets; drives >=90% EXCLUSION.
     #   weekly_percent — peak of the durable buckets; the PRIMARY ranking signal.
-    #   session_percent— peak of the self-healing ~5h buckets; a soft tiebreaker.
-    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
+    #   session_percent— peak of the self-healing ~5h buckets; the session GATE's input:
+    #                    the shim ranks only accounts at/under CODEX_MULTIACC_SESSION_GATE
+    #                    (default 50) while any clear it. (A soft tiebreaker until
+    #                    2026-09-03 — the operator asked for session FIRST, then weekly.)
+    # A bucket only feeds those three signals if it SAID something. An INFORMATIVE
+    # bucket has a percent above 0, or a window the payload actually reported. The
+    # claude pool learned this the hard way on 2026-09-04: its usage endpoint answered
+    # EVERY bucket `percent: 0, resets_at: null` for acct-13/acct-14 while the client
+    # was being rejected on them at their weekly limit, the writer recorded the zeros
+    # verbatim, and two provably exhausted accounts led the weekly band for 31 of the
+    # last ~60 picks. Real usage always comes with 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 leaves the real buckets ranking as today.
+    def informative(b):
+        return b['percent'] > 0 or bool(b.get('_reset_known'))
+
+    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 — same rule as the claude writer.
+    # 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 windows
+    # were all uninformative while its 5h window read 40% was recorded as 40% WEEKLY —
+    # a number no window 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
     try:
         reset_result = try_auto_redeem(d, aid, maxp, data, url, headers, say, int(now))
     except Exception as e:
         say(f'{aid}: usage reset automation failed unexpectedly ({type(e).__name__}); failing open')
         reset_result = {'status': 'error'}
-    out = {'fetched_at': int(now), 'source': 'chatgpt', 'max_percent': maxp,
-           'weekly_percent': weeklyp, 'session_percent': sessionp,
-           'plan': str(data.get('plan_type') or ''), 'buckets': buckets}
+    # Internal only (see win_bucket): limits.json keeps the bucket shape every reader
+    # — the shim, lib/report.py, app-robot — already knows.
+    for b in buckets:
+        b.pop('_reset_known', None)
+    out = {'fetched_at': int(now), 'source': 'chatgpt'}
+    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 not live:
+        # Nothing usable in the entire payload. Keep the diagnostics (fetched_at,
+        # source, plan, the raw buckets) and write NONE of the 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 claude 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['plan'] = str(data.get('plan_type') or '')
+    out['buckets'] = buckets
     if reset_result.get('status') == 'redeemed':
         # The response proves the reset succeeded, but the usage GET happened before
         # it. Make that snapshot stale immediately so it cannot re-exclude the newly
@@ -1503,14 +1620,37 @@ for acct in manifest.get('accounts', []):
         # since any bucket over the threshold stays there until its own reset.
         worst = max(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
@@ -1522,18 +1662,62 @@ for acct in manifest.get('accounts', []):
             #                        payload that disagrees must not unpark the account
             #                        early and send work straight back into the wall.
             keep = False
+            client_recovered = False
             try:
                 txt = open(mpath).read()
                 first = txt.splitlines()[0] if txt else ''
-                if reset_result.get('status') != 'redeemed' \
-                        and ('reason=error-cooldown' in txt or 'reason=client-rate-limit' in txt) \
-                        and first.isdigit() and int(first) > now:
+                active = first.isdigit() and int(first) > now
+                # Sync and atomic copies change mtimes, so prefer the marker's own
+                # semantic timestamp; old marker formats fall back to mtime.
+                marked_at = next((part[10:] for part in txt.split()
+                                  if part.startswith('marked_at=')), '')
+                marked_epoch = parse_iso(marked_at)
+                if marked_epoch is None:
+                    marked_epoch = os.path.getmtime(mpath)
+                recent_client = now - marked_epoch < CLIENT_LIMIT_CONFIRM_DELAY
+                is_client = 'reason=client-rate-limit' in txt
+                # See weekly_marker() above: ONE rule, shared with the claude writer.
+                # 2026-09-04 changed this branch — every active client marker used to
+                # be kept unconditionally, so a 5h rejection outlived a window that
+                # refills in hours. Now it clears on an informative pass after the same
+                # confirm delay claude uses, while a 7d one sticks until its reset.
+                if reset_result.get('status') == 'redeemed':
+                    keep = False   # a confirmed reset is first-hand proof it refilled
+                elif 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:
                 os.remove(mpath)
-                say(f'{aid}: marker cleared (max {maxp}%)')
+                if client_recovered:
+                    # The rollout that reported the spent window is STILL on disk, and
+                    # the shim's client_limit_scan re-reads its tail on the very next
+                    # launch — so deleting the marker without a watermark only rewrites
+                    # it seconds later, once per 15-minute pass, forever. Stamp the clear
+                    # the way bin/claude-accounts has since #22's five-hour clearing
+                    # landed (same filename, same epoch payload); bin/codex then skips
+                    # every report at or before it. Codex gained 5h clearing on
+                    # 2026-09-04 and needed the identical brake with it.
+                    cleared = os.path.join(d, '.client-limit-cleared')
+                    with open(cleared + '.tmp', 'w') as f:
+                        f.write(f'{int(now)}\n')
+                    os.replace(cleared + '.tmp', cleared)
+                # 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}')

package/docs/ACCOUNT_OPERATIONS.md

@@ -226,12 +226,18 @@ providers (`lib/report.py`), so a consumer writes one parser:
                     "token_age_days": 39},
     "limited": false, "limit_reset_at": null, "limit_detail": null,
     "usage": {"fetched_at": "…Z", "age_seconds": 41, "source": "oauth",
+              // a null percent = that signal had no informative bucket; all three
+              // null = limits.json "no_data": true
               "max_percent": 62, "weekly_percent": 62, "session_percent": 18,
               "buckets": [{"name": "weekly_scoped:Fable", "group": "weekly",
                            "percent": 62, "resets_at": "…Z"}]}
   }],
   "summary": {"total": 3, "active": 2, "limited": 1, "needs_login": 0,
-              "portable": 3, "selectable": 2},
+              "portable": 3, "selectable": 2,
+              // pool-wide ranking verdict: fresh | degraded | blind | none.
+              // "fresh" needs ONE candidate with both percentages inside the window;
+              // "blind" = every account scores the same and selection is random.
+              "telemetry": "fresh", "ranking_blind": false},
   "warnings": []
 }
 ```
@@ -244,6 +250,21 @@ A consumer that only distinguishes *usable / parked / needs-a-human* can read
 without the limit overlay. `limited` follows the shim's marker rule exactly — a marker
 whose reset time has passed does not count, an unreadable one does.
 
+A percent field is **null** when that signal had no informative bucket to aggregate. The
+writers keep the signals separate: `weekly_percent` comes from informative weekly buckets,
+`session_percent` from informative session ones, and each is omitted on its own when its
+group has nothing informative — a payload with a real session bucket and an all-zero weekly
+one reports the session and leaves `weekly_percent` null rather than borrowing the session
+number. `"no_data": true` appears only when NOTHING in the payload is informative (every
+bucket 0% with no *parseable* reset window — the `buckets` array is kept verbatim for
+diagnostics and, on codex, may still show a synthesized epoch), and then all three
+percentages are absent together; a
+weekly-only or session-only document carries no `no_data` flag. The rule behind it: 0% with
+no window is the endpoint declining to answer rather than an idle account (2026-09-04 —
+reading it as 0% ranked two weekly-exhausted accounts first). Either way the account ranks
+*unknown*, not empty — selection needs BOTH percentages — and its `buckets` are still
+emitted for diagnostics.
+
 ### Which accounts are portable
 
 | Credential | Where it lives | Class | Can it be copied to another machine? |
@@ -333,9 +354,10 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 | `CLAUDE_CONFIG_DIR=...` | shim passes straight through (scripts can pin the old way) |
 | `CLAUDE_MULTIACC_DISABLE=1` | bypass selection entirely |
 | `CLAUDE_MULTIACC_HEADROOM_BAND=0..100` | weekly points treated as peers; default `30`, `0` is strict |
+| `CLAUDE_MULTIACC_SESSION_GATE=0..100` | max 5h-session usage that still gets ranked; default `50`, `100` disables the gate |
 | `CLAUDE_MULTIACC_CLIENT_LIMITS=0` | ignore the client's own rate-limit records |
 | `CLAUDE_MULTIACC_CLIENT_SCAN_TTL=<s>` | clean client-limit scan cache; default 20s |
-| `CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY=<s>` | low-telemetry recovery grace; default 300s |
+| `CLAUDE_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY=<s>` | five-hour recovery grace; default 300s (weekly never clears early) |
 | `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
 | `CLAUDE_ACCOUNTS_ROOT=...` | relocate the pool; legacy spelling is `CLAUDE_ACCOUNTS_DIR` |
 | `CLAUDE_MULTIACC_SYNC_TARGET=...` | sync target, overriding the manifest; `none` = local-only |
@@ -343,8 +365,10 @@ derived from the pool root. Uninstalling an instance removes only that instance'
 
 The codex shim honors the same switches spelled `CODEX_*`: `CODEX_ACCOUNT`,
 `CODEX_HOME` (passthrough), `CODEX_MULTIACC_DISABLE`, `CODEX_SHIM_RETRY`,
-`CODEX_SHIM_SELECT`, `CODEX_ACCOUNTS_ROOT` (legacy `CODEX_ACCOUNTS_DIR`),
-`CODEX_MULTIACC_SYNC_TARGET`, `CODEX_MULTIACC_THRESHOLD`.
+`CODEX_SHIM_SELECT`, `CODEX_MULTIACC_HEADROOM_BAND`, `CODEX_MULTIACC_SESSION_GATE`,
+`CODEX_MULTIACC_CLIENT_LIMIT_CONFIRM_DELAY` (5h client-marker recovery grace, default
+300s — weekly markers never clear early), `CODEX_ACCOUNTS_ROOT` (legacy
+`CODEX_ACCOUNTS_DIR`), `CODEX_MULTIACC_SYNC_TARGET`, `CODEX_MULTIACC_THRESHOLD`.
 
 ## Verification
 
@@ -382,8 +406,9 @@ repointed via `CLAUDE_BIN=/usr/local/bin/claude` and restarted healthy.
   before direct, TUI, or `--resume` work sees the 401. Run `claude-accounts verify` to
   check every token immediately; `claude-accounts expired` reports token-only accounts
   as `UNVERIFIED` until that proof exists.
-- **Everything marked limited** — the shim still runs (least-utilized fallback);
-  check `selection.log` for `all-limited` lines.
+- **Everything marked limited** — the shim still runs: the still-serving limited accounts
+  go through the same two cuts (session gate, then strict best-weekly) and one is handed
+  out anyway; check `selection.log` for `all-limited fallback=` lines.
 - **Sync fails** — `tail ~/.claude-accounts/sync.log`; it's ssh/rsync to the manifest's
   `server` (BatchMode — needs key auth).
 - **A service bypasses the shim** — it spawns an absolute path. Point its env

package/docs/TRACK_PROMPT.md

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

package/docs/UNIFIED_SELECTOR.md

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

package/lib/report.py

@@ -255,6 +255,14 @@ def _usage(d, stale_after):
     # the reading cannot be used for degraded ranking.
     if lim.get('weekly_resets_epoch'):
         out['weekly_resets_epoch'] = lim['weekly_resets_epoch']
+    # The writer found no INFORMATIVE bucket (every percentage 0 with no reset window)
+    # and refused to invent numbers from it, so the ranking fields above are all None
+    # here and the account ranks as unknown rather than as empty — the 2026-09-04
+    # incident, where fake-zero telemetry made two exhausted accounts the band leaders.
+    # Emitted only when set, and always as a plain true, so a consumer that has never
+    # seen the flag reads exactly the shape it always did.
+    if lim.get('no_data'):
+        out['no_data'] = True
     if lim.get('last_error'):
         out['last_error'] = lim['last_error']
         if lim.get('last_error_at'):
@@ -281,12 +289,34 @@ def _last_pick(root, aid):
 
 
 
+def _rankable(u):
+    """True when this reading can still rank its account in the shim: inside the
+    ranking window AND carrying BOTH of the fields selection reads (bin/claude
+    rank_weekly_of / rank_session_of, gated by pick_best's "known" rule and by
+    telem_blind, which uses exactly this rule). A no_data document — all-zero buckets
+    with no reset window, 2026-09-04 — is current and well-formed but carries neither,
+    so a pool full of them is BLIND, not fresh; reporting it as fresh is how an outage
+    hides behind a recent timestamp. BOTH, not either: the same writer change omits
+    fields per signal, and a one-signal document (weekly-only or session-only) is
+    unknown to pick_best just as completely — an either-test called such a pool fresh
+    while the shim was tying every account and picking at random. bool is an int in
+    Python but not a number to the shim's digit parser, so `weekly_percent: true` must
+    read as unusable here too."""
+    if not u or u.get('stale'):
+        return False
+    return all(isinstance(u.get(k), (int, float)) and not isinstance(u.get(k), bool)
+               for k in ('weekly_percent', 'session_percent'))
+
+
 def telemetry_state(accounts, now=None):
     """Three-state verdict on how the shim is CURRENTLY ranking this pool, over the
     same candidate set bin/claude uses: the eligible accounts, or — when every one of
     them is limit-marked — the valid ones it falls back to.
 
-      'fresh'    at least one candidate has telemetry inside the ranking window
+      'fresh'    at least one candidate has telemetry inside the ranking window that
+                 the shim can actually rank on — a COMPLETE reading, weekly and session
+                 both (see _rankable: a no_data document, or a one-signal one, is
+                 in-window and ranks nothing, so it does not make a pool fresh)
       'degraded' none do, but EVERY candidate still has a weekly reading whose bucket
                  has not reset yet, so the shim ranks on those (all-or-nothing: one
                  unusable reading and the comparison is not apples-to-apples)
@@ -302,10 +332,16 @@ def telemetry_state(accounts, now=None):
     cands = [a for a in usable if a.get('status') == 'active'] or usable
     if not cands:
         return 'none'
-    if any(a.get('usage') and not a['usage'].get('stale') for a in cands):
+    if any(_rankable(a.get('usage')) for a in cands):
         return 'fresh'
     for a in cands:
         u = a.get('usage') or {}
+        # DEGRADED means "everything is old, rank on old truths". A reading INSIDE the
+        # window that is merely unrankable (no_data, or one-signal) blocks degraded in
+        # the shim too (bin/claude assess_telemetry, codex review 2026-09-04): fresh
+        # emptiness is not an outage of age, and re-fetching will not improve it.
+        if not u.get('stale'):
+            return 'blind'
         horizon = u.get('weekly_resets_epoch') or 0
         pct = u.get('weekly_percent')
         # bool is an int in Python but not a number to the shim's digit parser, so a