Session Quota Forecast

The framing everyone uses is the wrong one

> "two prompts torched my entire 5h session on Opus 5"

The complaint is about how much the window costs. The more expensive failure is where it runs out. Starting a long task with 15% of a window left is not 15% of the value — running out at 80% of a refactor is frequently worth less than never starting:

• the work is left half-applied, which is a state nobody designed for
• resuming costs a fresh re-read of everything the dead session had in context, so **the restart
• is more expensive than the original start was**
• somebody has to review or revert the partial state before anything else can happen

And the window usually resets soon. Waiting twenty minutes to run a task that completes beats starting now and dying at 80% — but no tool ever suggests waiting, because tools are built to do the thing you asked.

  shouldStart(window, estimate, now);
  // { decision: "wait_for_reset", minutesToReset: 20,
  //   detail: "5000 tokens cannot cover even the expected 20000. The window resets in 20m —
  //            waiting and completing beats starting now and stopping partway, which leaves
  //            state nobody designed for" }

| decision | meaning | |---|---| | start | the pessimistic cost fits | | start_at_risk | expected fits, worst case does not — a gamble, stated as one | | wait_for_reset | will not fit, and the reset is close enough to be worth it | | split_required | too big for a whole window, so waiting changes nothing | | unknown | no usable estimate — refuses to produce a confident number |

Decided against the worst case, deliberately

An expected-case decision is a coin flip dressed as a plan, and the losing side of that flip is the expensive outcome above. start_at_risk exists so a caller who wants to gamble does it knowingly, rather than because the tool rounded in their favour.

When you supply no worstCase, a 2× overrun multiplier is applied **and the result is marked imprecise** — agent tasks overrun, and planning against expected alone is planning against the good case.

The forecast refuses to cry wolf

  forecastBurn(samples, window, now);
  // { reliable: false, exhaustedAt: null,
  //   detail: "2 sample(s) over 1m is not enough to project. A forecast built on this would be
  //            confident and wrong, and a forecast that cries wolf is ignored later when it is right" }

Two samples ninety seconds apart extrapolate to a confident, wildly wrong exhaustion time. Needs 3+ samples over 10+ minutes before it will project at all.

What it does not do

| not included | why | |---|---| | Reading your provider's quota | plans and headers differ per vendor; you supply the window | | Estimating task cost | the hard part, and it needs your own history — rebuild-cost and true-token-ledger are closer to it | | Stopping a running task | iteration-stop-conditions, spend-ceiling-limiter | | Reducing what a task costs | agent-loop-burn, context-window-packer, prompt-cache-aware-batcher |

The projection is only as good as the estimate you feed it. Everything here reports its own uncertainty rather than dressing a guess up as a forecast — which is the only honest thing to do with a number this easy to be wrong about.