subscription-quota-check

1# subscription-quota-check
2 
3## The one rule
4 
5**Read it on demand: when the human asks, or when something was actually blocked.**
6 
7This skill is not a monitor and never schedules a read of its own, apart from the single re-confirmation read after a `wait` verdict (see "When it says wait"). The Claude usage endpoint
8is itself rate limited, so a probe on a timer eventually earns a 429 and starts serving
9cached numbers — a checker that reports confidently while reading nothing. A caller such as
10rotate-agent may arm a scheduled read deliberately; that is the caller's decision, and the
11rate-limit risk is then the caller's to manage. Outside such an armed schedule, every run
12must trace to one of the two moments above.
13 
14The anti-pattern it replaces has a name: **finding out you are out of quota by making a real
15call and reading the error.** That spends quota to learn you have none, and the error does
16not say when it comes back. This reads the same state for free and tells you the reset time.
17 
18## Running it
19 
20Use the command installed by `sno setup`, with the installed `sno heartbeat`
21command for the wait branch. If a command names a missing prerequisite, install that
22tool and retry. On macOS use `bash`, `jq`, and `coreutils` for the named shell/JSON/GNU
23tools; put `coreutils/libexec/gnubin` on PATH. Windows requires WSL. Only the wait
24branch needs `sno heartbeat`, a proven background process and a reader-to-agent delivery path;
25…