feat(tools): add tier-advisor CLI (cnighswonger#244)

Recommends cache TTL tier upgrades/downgrades from measured session behavior rather than guesswork.

Verified locally merged onto current main: full suite 1487/0.

Closes cnighswonger#63

Author: vsits-proxy-builder[bot]

README.md

@@ -241,6 +241,10 @@ All proxy settings are controlled via environment variables. Set them before sta
 | `CACHE_FIX_DEBUG` | `0` | Enable debug logging |
 | `CACHE_FIX_HOT_RELOAD` | unset | Set to `on` to enable in-process extension hot-reload. Off by default as of v4.0.0 — see [Upgrading from v3.x](#upgrading-from-v3x) for details and the supervisor restart flow. |
 | `CACHE_FIX_READ_DEDUPE` | unset | Set to `1` to dedupe repeat `Read` tool results that re-appear unchanged across turns. Keeps the first occurrence intact; replaces later byte-identical ones (keyed on `file_path` + content + `offset` + `limit`) with a stable pointer line. Default-off; opt in per session to validate before broader rollout. See [extension impact guide](docs/extension-impact-guide.md). |
+| `CACHE_FIX_ADVISOR_PLAN` | unset | Plan override for `tools/tier-advisor.mjs` — one of `max-5x`, `max-20x`, `pro`. Bypasses heuristic plan detection. See [Tier advisor](docs/tier-advisor.md). |
+| `CACHE_FIX_ADVISOR_UPGRADE_THRESHOLD` | `80` | Projected-Q7d percent that triggers an `UPGRADE` recommendation from tier-advisor. |
+| `CACHE_FIX_ADVISOR_DOWNGRADE_THRESHOLD` | `20` | Projected-Q7d percent that triggers a `DOWNGRADE` recommendation from tier-advisor (paired with the `DOWNGRADE_WEEKS` consecutive-weeks gate). |
+| `CACHE_FIX_ADVISOR_DOWNGRADE_WEEKS` | `2` | Consecutive completed weeks under the downgrade threshold required before tier-advisor recommends downgrade. Single-week dips never trigger; single-week spikes DO trigger upgrade (cost-of-being-throttled asymmetry). |
 
 ### Corporate environments (proxies, custom CAs)
 

docs/code-reviews/pr-244-tier-advisor-impl-codex-rereview-2026-06-27.md

@@ -0,0 +1,90 @@
+# Review: PR #244 tier-advisor implementation
+
+Date: 2026-06-27
+Reviewed: PR #244 (`feature/tier-advisor-impl`) at `21a1d48e91bed2eaf55e2527fc76bcb738399587`
+Round: 2
+Label applied: changes-requested
+
+## What Is Correct
+
+The round 1 fallback blocker is fixed for the high-burn cases that failed previously. In the stale `account.json` path, the advisor now exits `1`, reports `burn_rate_source: "log"`, sets `current_q7d_pct` from the weighted log sum (`98.0392156862745` in my reproduction), projects above the upgrade threshold, and recommends `upgrade`. In the missing `account.json` path, the same high-burn fixture also exits `1`, reports `burn_rate_source: "log"`, sets `current_q7d_pct` from the log, and recommends `upgrade`.
+
+Actual round 1 reproduction rerun against this HEAD:
+
+```text
+stale account.json + high usage.jsonl:
+exit=1
+current_q7d_pct=98.0392156862745
+burn_rate_source=log
+projected_q7d_at_reset=114.37901568682078
+recommendation=upgrade
+
+missing account.json + high usage.jsonl:
+exit=1
+current_q7d_pct=98.0392156862745
+burn_rate_source=log
+projected_q7d_at_reset=99.51359014876492
+recommendation=upgrade
+```
+
+The single-source state persistence path is also fixed for fallback runs that cross a week boundary. A stale-header/log-fallback run wrote a completed `weeks[]` entry with `q7d_actual_at_reset: 98.0392156862745`, `under_downgrade: false`, and `tier_assumed: "max-5x"` rather than carrying the stale header's `5%` value into state (`tools/tier-advisor.mjs:519-528`).
+
+The round 1 attention items are addressed coherently. `parseArgs` no longer has `opts.week` or `--week` parsing (`tools/tier-advisor.mjs:57-74`), the help text only lists shipped flags (`tools/tier-advisor.mjs:661-666`), and the docs now say historical-week analysis is deferred (`docs/tier-advisor.md:49-59`). The `recentQ5hBudgetTokens()` stub is now documented honestly in code and docs (`tools/tier-advisor.mjs:310-318`, `docs/tier-advisor.md:140-147`). The stray FIRST-keeper phrase is gone from `docs/monitoring.md:23-27`.
+
+Targeted edge cases requested in this round:
+
+```text
+fallback state persistence after boundary:
+exit=1
+state.last_recommendation=tier:upgrade
+state.weeks[0].q7d_actual_at_reset=98.0392156862745
+
+missing account.json + zero-entry usage.jsonl:
+exit=0
+current_q7d_pct=0
+burn_rate_source=log
+recommendation=ok
+state.last_recommendation=tier:ok
+
+missing account.json + high usage.jsonl + CACHE_FIX_ADVISOR_PLAN=pro:
+exit=3
+recommendation=unknown
+state_exists=no
+```
+
+Verification passed:
+
+```text
+npm test
+tests 1392
+pass 1392
+fail 0
+```
+
+## Blockers
+
+1. `tier:unknown` / `pro` recommendations return before state persistence, so the documented statusline integration cannot display them.
+
+   `tools/tier-advisor.mjs:462-465` and `tools/tier-advisor.mjs:484-485` call `emitUnknown()` before the state load/persist block at `tools/tier-advisor.mjs:494-579`. That means an advisor run that exits `3` never writes `last_recommendation: "tier:unknown"`. The statusline only reads persisted state (`tools/quota-statusline.sh:238-250`), and the docs promise that it appends `tier:upgrade` / `tier:downgrade` / `tier:unknown` from `~/.claude/tier-advisor-state.json` after the advisor runs (`docs/tier-advisor.md:74-78`).
+
+   I reproduced this with missing `account.json`, high `usage.jsonl`, and `CACHE_FIX_ADVISOR_PLAN=pro`: the CLI correctly returned exit `3` with JSON `recommendation: "unknown"`, but no state file was written. The same early-return behavior also applies to `planRes.plan === "unknown"`, and the current test only checks stdout/exit for that case (`test/tier-advisor.test.mjs:569-582`), not state persistence.
+
+   Fix options: either persist `last_run` and `last_recommendation: "tier:unknown"` for exit-3 runs when `--no-state` is not set, or explicitly remove `tier:unknown` from the statusline/docs contract. Given the existing statusline allowlist includes `tier:unknown`, persisting the state is the smaller behavioral fix.
+
+## What Needs Attention
+
+None beyond the blocker above.
+
+## Bloat / Non-Functional
+
+None. The fallback fix stays local to the advisor math/state path, and the new regression coverage is targeted.
+
+## Recommendations
+
+Add regression coverage for both unknown exits: no plan override plus available inputs, and `CACHE_FIX_ADVISOR_PLAN=pro`. The assertions should cover exit `3`, JSON `recommendation: "unknown"`, and the persisted state behavior chosen by the contract. If the intended behavior is to suppress statusline `tier:unknown`, update `tools/quota-statusline.sh` and `docs/tier-advisor.md` together so the CLI and prompt contracts do not diverge.
+
+## Bottom Line
+
+REQUEST_CHANGES. The original fallback math bug is fixed and the requested tests pass, but the newly checked fallback/pro/unknown path exposes a state-persistence gap: `tier:unknown` is documented and wired into the statusline reader, yet exit-3 runs never write the state needed for the statusline to show it.
+
+— Codex review

docs/code-reviews/pr-244-tier-advisor-impl-codex-rereview-r3-2026-06-27.md

@@ -0,0 +1,73 @@
+# Review: PR #244 tier-advisor implementation
+
+Date: 2026-06-27
+Reviewed: PR #244 (`feature/tier-advisor-impl`) at `c85a3f4ac60dc97869b0d9282478940790df4627`
+Round: 3
+Label applied: approved-by-codex-agent
+
+## What Is Correct
+
+The round 2 blocker is fixed. Both exit-3 paths now call `emitUnknown(opts, writeOutput, planRes, statePath)`, so the state writer can update `last_run` and `last_recommendation: "tier:unknown"` before returning (`tools/tier-advisor.mjs:462-485`, `tools/tier-advisor.mjs:637-676`).
+
+I reran the prior reproductions against `c85a3f4`:
+
+```text
+heuristic unknown path:
+exit=3
+recommendation=unknown
+state.last_recommendation=tier:unknown
+loadAdvisorState(...).last_recommendation=tier:unknown
+
+pro plan via log fallback:
+exit=3
+recommendation=unknown
+state.last_recommendation=tier:unknown
+loadAdvisorState(...).last_recommendation=tier:unknown
+
+--no-state unknown path:
+exit=3
+recommendation=unknown
+state_exists=false
+```
+
+The new regression tests cover the important contract points: heuristic unknown persists, pro-plan log fallback persists, and `--no-state` still avoids state writes (`test/tier-advisor.test.mjs:592-645`). The state loader accepts `tier:unknown` cleanly because `loadAdvisorState()` preserves `last_recommendation` as a string and does not restrict it to upgrade/downgrade/ok (`tools/tier-advisor.mjs:199-209`). The statusline allowlist already includes `tier:unknown` (`tools/quota-statusline.sh:238-250`).
+
+Full verification passed:
+
+```text
+npm test
+tests 1395
+pass 1395
+fail 0
+```
+
+## Blockers
+
+None.
+
+## What Needs Attention
+
+The malformed-state edge is intentionally tolerant on the unknown path. I verified that if `CACHE_FIX_ADVISOR_STATE` points at malformed JSON and the advisor otherwise resolves to `tier:unknown`, the CLI exits `3`, prints the unknown recommendation, and leaves the malformed file untouched:
+
+```text
+malformed state + unknown path:
+exit=3
+recommendation=unknown
+state_still_malformed=true
+```
+
+That differs from normal recommendation paths, where malformed state still returns the hard-error exit `4` (`tools/tier-advisor.mjs:494-504`). I am not treating this as a blocker because this PR's stated round 3 behavior deliberately keeps unknown-path persistence failures non-fatal, and this case is not worse than the previous exit-3 behavior that did not read or write state at all. The next run with a known plan still hits the normal hard-error path and forces the malformed state file to be repaired.
+
+## Bloat / Non-Functional
+
+None. The fix is scoped to the existing `emitUnknown()` helper and the regression tests are targeted.
+
+## Recommendations
+
+No required changes before merge. If the team wants the docs to be exact about this edge, add a note that malformed state is exit `4` for normal analysis paths, while the plan-undetectable exit `3` path reports the plan problem first and treats state persistence as best-effort.
+
+## Bottom Line
+
+APPROVE. The round 2 state-persistence blocker is resolved, `tier:unknown` survives reload through the state schema, the `--no-state` guard is preserved, and the full test suite passes with 1395 tests.
+
+— Codex review

docs/code-reviews/pr-244-tier-advisor-impl-codex-review-2026-06-25.md

@@ -0,0 +1,58 @@
+# Review: PR #244 tier-advisor implementation
+
+Date: 2026-06-25
+Reviewed: PR #244 (`feature/tier-advisor-impl`) at `22a8175cbc67a4ec696c512c7560f790169c5d78`
+Round: 1
+Label applied: changes-requested
+
+## What Is Correct
+
+The implementation lands in the requested shape: `tools/tier-advisor.mjs` is a standalone CLI with no proxy extension, and `tools/quota-statusline.sh` only reads the persisted advisor state and appends a single `tier:` token. The statusline change preserves the existing heredoc security model: hook input is still read from `CC_INPUT` via `os.environ`, and the new tier-advisor state read is a fixed path with no shell interpolation.
+
+The modern quota path pin is correct. The advisor defaults to `~/.claude/quota-status/account.json` and does not read the preload-era `~/.claude/quota-status.json`; tests override the path with `CACHE_FIX_ADVISOR_QUOTA_STATUS`.
+
+The focused tests cover the prior directive blockers at the helper/API level: single exit-code mapping across default / `--json` / `--quiet`, bounded newest-first `weeks[]`, no duplicate same-week records, projection cap at 200%, additive overage-warning enrichment, and statusline omission for `tier:ok`. Test 30's structural comparison that ignores sub-millisecond float drift is acceptable because those fields are intentionally `now`-dependent.
+
+## Blockers
+
+1. `usage.jsonl` fallback does not produce a valid projection and can silently return `tier:ok` on high burn.
+
+   In `tools/tier-advisor.mjs:425-442`, the fallback branch computes a log-derived `burnRate` and sets `burnRateSource = "log"`, but `tools/tier-advisor.mjs:456-459` only projects when `q7dPct` came from `account.json`. If `account.json` is missing, projection becomes `0`; if `account.json` is stale, the projection combines stale header Q7d percent with log-derived burn. Both cases violate the directive's binary source rule: primary = fresh header, fallback = usage log, never blend.
+
+   Reproduction against this PR:
+
+   ```bash
+   tmp=$(mktemp -d)
+   node -e 'console.log(JSON.stringify({ts: new Date().toISOString(), usage:{input_tokens:200000000, cache_creation_input_tokens:0, cache_read_input_tokens:0}}))' > "$tmp/usage.jsonl"
+   CACHE_FIX_ADVISOR_QUOTA_STATUS="$tmp/missing-account.json" \
+   CACHE_FIX_ADVISOR_USAGE_LOG="$tmp/usage.jsonl" \
+   CACHE_FIX_ADVISOR_STATE="$tmp/state.json" \
+   CACHE_FIX_ADVISOR_PLAN=max-5x \
+   node tools/tier-advisor.mjs --json
+   ```
+
+   The output records `burn_rate_source: "log"` and `burn_rate_per_hour: 0.92...`, but `current_q7d_pct: null`, `projected_q7d_at_reset: 0`, `recommendation: "ok"`, and exit `0`. A 200M weighted-token current-week log on a 204M plan is not a hold signal. The fallback path needs to derive the current-week consumed percent from the same log token sum used for burn rate, then project from that value and persist week observations from that same source. Add a test where `account.json` is absent or stale, `usage.jsonl` alone implies an upgrade, and the recommendation/exit code are `upgrade`/`1`.
+
+## What Needs Attention
+
+- `--week` is documented as historical analysis (`tools/tier-advisor.mjs:628`) and parsed (`tools/tier-advisor.mjs:72-73`), but the parsed value is not used by `runAdvisor`. The current test only asserts parse acceptance, despite the test name saying it affects analysis. If historical analysis is still in scope, implement it; otherwise remove the behavior claim from help/docs and make the test name honest.
+
+- Runtime heuristic plan detection is currently a stub: `recentQ5hBudgetTokens()` always returns `null`, so the CLI's actual plan order is CLI override, env override, fallback unknown. That can be acceptable only if the fallback is intentionally the v1 behavior, but it does not match the directive checklist's stated heuristic step. Either wire a real heuristic from available quota/usage data or document the limitation consistently in the PR docs and tests.
+
+- `docs/monitoring.md:27` mentions a "FIRST-keeper byte-stability guarantee" that belongs to read-dedupe, not the tier-advisor state history. This is a docs copy/paste artifact and should be corrected while the PR is already open.
+
+## Bloat / Non-Functional
+
+None. The CLI is intentionally self-contained and uses Node built-ins only; the size is mostly tests and explicit formatting/state helpers, not unnecessary abstraction.
+
+## Recommendations
+
+Keep the fallback math single-source: have the usage-log path return both `currentPct` and `burnRate`, set `current_q7d_pct` from the log-derived percent, and avoid carrying stale/missing header utilization into projection or state. That will also make the `burn_rate_source` field auditably true.
+
+After the fallback fix, add a regression test for stale `account.json` plus high `usage.jsonl` to prove the stale header percent is not blended with log burn. The existing missing-both-inputs test does not exercise the fallback recommendation path.
+
+## Bottom Line
+
+REQUEST_CHANGES. The implementation is close and the statusline/security pieces look sound, but the fallback burn-rate path currently violates the load-bearing single-source contract and can suppress an upgrade recommendation exactly when `account.json` is unavailable or stale.
+
+— Codex review

docs/monitoring.md

@@ -20,6 +20,12 @@ On the first API call, the interceptor reads `~/.claude.json` and logs the curre
 
 Response headers are parsed for `anthropic-ratelimit-unified-5h-utilization` and `7d-utilization`, saved for consumption by status line hooks or other tools. Proxy mode (v3.5.0+, via `cache-telemetry` extension) splits state into `~/.claude/quota-status/account.json` (account-global facts) plus `~/.claude/quota-status/sessions/<filename>.json` (per-session cache facts), so multi-agent users no longer see cross-session contamination. Preload mode keeps the legacy single-file `~/.claude/quota-status.json` (single-session by construction).
 
+## Tier upgrade/downgrade advisor
+
+`tools/tier-advisor.mjs` is a CLI tool that consumes the proxy-written `account.json` snapshot and the per-call `usage.jsonl` log, projects this week's Q7d burn forward to the weekly reset, and emits a tier-change recommendation (`tier:upgrade` / `tier:downgrade` / `tier:ok` / `tier:unknown`). Designed to be run on a cron / shell alias; the cache-fix statusline picks up the persisted recommendation and appends a single token to the user's prompt.
+
+See [`docs/tier-advisor.md`](tier-advisor.md) for the full reference: exit codes, CLI flags, env vars (`CACHE_FIX_ADVISOR_*`), cron setup, state-file shape, and the calendar-week-scoped history semantics. Directive: [`docs/directives/proxy-tier-advisor.md`](directives/proxy-tier-advisor.md) (PR #93, issue #63).
+
 ## Peak hour detection
 
 Anthropic applies elevated quota drain rates during weekday peak hours (13:00–19:00 UTC, Mon–Fri). The interceptor detects peak windows and writes `peak_hour: true/false` to the quota-status payload (`account.json` in proxy mode, `quota-status.json` in preload mode). See `docs/peak-hours-reference.md` for sources and details.