A Scheduler That Only Runs Coding Agents With Headroom to Spare

My autonomous loop shares a Claude subscription with the human who owns it. The scheduler ticks every 20 minutes and decides whether an agent run fits in the current usage windows. It broke once by reading the wrong rate-limit snapshot: 0% at 93%. Here is the policy, the math, and the bug.

My autonomous loop runs Opus-powered agent sessions that build and operate small SaaS products. It shares a Claude subscription with me, the human who also uses that subscription for everything else. That single fact shapes the whole system: the loop must be a good tenant. It should run when there is room, work small when there is a little, and stay out of the way when there is not.

The component that makes that work is the scheduler. It is the only thing launchd runs on a timer, every 20 minutes, and it never calls the model itself. Each tick it runs a local heartbeat, reads the usage numbers, reads the job queue and the run history, checks whether I am actively working elsewhere, and then decides one thing: start one agent run now, and if so, how big.

The gates

Every decision starts with two numbers: the session percentage (the rolling window) and the weekly percentage. Both come from a usage snapshot script that reads the same rate-limit data the status line sees, with a fallback to the OAuth usage endpoint when the cache is stale.

The policy distinguishes hard gates from soft gates, and the distinction is load-bearing:

GateThresholdTypeCan priority skip it?
A run is already in progressrun lock heldhardno
Usage unknowneither % unreadablehardno
No headroomsession > 88% or weekly > 96%hardno
Owner active (me, on another project, last 30 min)only when session > 60%softyes
Weekly ahead of pacepacing line, belowsoftyes
Minimum gap since last run1h full, 0.5h small, 15min urgentsizingfull-gap can be held

A full-size run additionally needs session at or under 60%, weekly at or under 93%, and at least 1.5 hours left before the session window resets (unless the session is nearly empty, 10% or less, in which case any remaining time is plenty). Below that, a small run. The reasoning: a full run is a long campaign, and starting one at session 70% means the run dies at the limit with work half-finished. Better to spend the tail of a window on small jobs that actually complete.

Two details I want to defend because they were not obvious to me at first.

The weekly budget is a pace, not a ceiling. A flat "stop at X%" rule either starves the early week or exhausts the budget by Wednesday. The pacing line is: elapsed fraction of the week times (100 minus a 5% reserve for the owner), plus a 15% slack term. The slack front-loads: windows are rolling and expire, so capacity unused by Thursday is worth nothing by Friday. Spending early is not greed, it is not wasting the allowance.

"Use it or lose it" overrides the owner gate for small runs. If the session window resets in under 1.5 hours and there is still 15+ points of headroom below the small cap, the loop runs something small even when the soft gates would normally hold. Again: that capacity is about to evaporate. The only sin is not using it.

Priority 1-2 jobs (an urgent buyer email, a critical fix) may skip the soft gates and the gap, but never the hard ones. No job ever starts with unknown usage or over the no-headroom line. Ever. That promise is the whole design, which is why the bug below stung.

The bug: 0% at 93%

On 2026-10-08 the loop launched five Codex streams straight into a 93%-used limit. The guard that should have stopped them read 0%.

The cause was in how the usage script reads Codex's history. Codex writes a rate_limits snapshot to its session log after every turn. My reader walked the newest sessions, walked each file's lines backward, and took the first line containing "rate_limits". Newest wins. That assumption had been fine until Codex started logging a second rate_limits event right after the real one: a "premium" (credits) limit whose windows are null. The first match going backward was now often that premium snapshot, with null windows that parsed to "0% used". The guard compared 0 against every threshold, passed everything, and launched five streams into a limit it could not see.

Commit 840a065 (2026-10-07) is the fix, and the diff is one line of condition:

// before: newest line with a rate_limits object wins
if (rl) found = { rl, ts: ... };
// after: a snapshot only counts if it has windows and is the real limit
if (rl && (rl.primary || rl.secondary) && (!rl.limit_id || rl.limit_id === "codex"))
  found = { rl, ts: ... };

Two lessons live in that one line. First, newest-wins on an append-only log silently assumes every record is the same kind of measurement. The moment a producer adds a second event type, a reader shaped like "take the latest" starts mixing kinds and averages a credit balance into a usage percentage. Second, and more uncomfortable: my hard gate failed open. "Usage unknown" is a hard stop, but the script did not return unknown, it returned a confident wrong number, and the gate never fired. A guard is only as good as its input, and "null parses as 0" is the classic way a missing measurement becomes a fake one. When I fixed it, the condition requires a present, non-null window before a snapshot counts. Anything else is unknown, and unknown stops the run.

A worked decision

Here is the scheduler deciding on a real-shaped tick, with the numbers it logged:

  • session 41%, weekly 66%, 3.2 hours to session reset
  • weekly elapsed: day 3 of 7, so elapsed fraction 0.43
  • pacing line: 0.43 x 95 + 15 = 55.9, weekly 66 is over it
  • owner: active 12 minutes ago on another project, session under 60%, so the owner soft gate does not apply
  • queue: empty, so the only candidate is the default cadence job

Soft gate fired: "weekly 66% is ahead of pace". Decision: no run this tick. That is the boring, correct outcome. The loop logs the whole decision (every input and reason, one JSON line per tick) so the next tick and any human audit can see why nothing happened. A scheduler you cannot interrogate after the fact is a scheduler you will re-tune on vibes.

Two days later the same queue, session 22%, weekly 31%: pacing line 55.9, weekly under it, owner idle, gap 4 hours. Full run. The pacing line did its job: spend early in the week, coast late.

What I would build differently

If I were starting over, three things would come sooner: a recorded decision log from day one (tuning thresholds before you can see past decisions is guesswork), a test fixture of synthetic rate-limit snapshots (a two-line fixture with a null-window snapshot would have caught the premium-snapshot bug the day the second event type appeared), and a rule that every guard input must distinguish "missing" from "zero" at the parse boundary, before any policy sees it.

The scheduler is about 400 lines and most of them are policy, not plumbing. That ratio feels right. The hard part was never reading a percentage; it was deciding what the loop owes the human it shares a subscription with, and encoding that as thresholds that fail closed.