Automation begins with a weaker claim: “candidate due”
Provider state is not a single public clock. It can be delayed, partially exposed, or unavailable from the local CLI surface. Treating a rough inference as an exact account fact would make an automation look more reliable than it is. QuotaWake instead starts with a candidate, then asks whether taking the small local action is appropriate.
That distinction is more than wording. It gives users a way to decide how much automation they want. A strict configuration can refuse to act without direct local evidence; a less strict configuration can allow a carefully labeled estimate. Neither mode should describe an estimate as an observed reset.
The local signal ladder
Swipe sideways to compare the columns.
| Confidence order | Example local evidence | What it means |
|---|---|---|
| 1. Observed local quota | Rate-limit data exposed by a local provider CLI surface. | Best available on-device evidence. |
| 2. Exact observed reset | A reset time or relative reset message parsed from bounded, sanitized CLI output. | A specific local observation, not a provider API guarantee. |
| 3. Estimated candidate | A time calculated from the last successful readiness send. | Useful context, but explicitly an estimate. |
| 4. Unknown | No suitable local signal. | No automatic send in strict mode. |
Confidence is not a cosmetic badge. It is part of the policy input. Logging the signal source alongside the outcome lets a person see why an action happened—and notice when an old assumption is no longer valid.
Five gates before a send
- Due check. Is there a local candidate that is actually due under the configured policy?
- Activity check. Does the operating system indicate that the user session is active enough for the action? If that cannot be determined safely, automatic action can fail closed.
- Pause and provider check. Has the user paused readiness, or disabled this provider?
- Idempotency and cooldown check. Has this candidate already produced a send, or was there a recent run that makes another one inappropriate?
- Process guard. Can the selected local CLI run within a bounded timeout without overlapping another provider process?
Only after those checks does QuotaWake run the configured small prompt. The model keeps an automation from becoming a blind periodic request.
Why “active-only” is a product choice
A timer knows the time but not the context. An activity gate does not make a tool omniscient; it does give the user a simple, inspectable condition: if the device is idle or in a suppressed power state, do not initiate a background readiness action. That respects the idea that this is an assistive local workflow, not unattended traffic generation.
It also matters for clarity. A person who opens their machine can understand why an action followed. A person who was away should not find an unexplained series of background requests.
What a local log should answer
A readiness log is valuable only if it answers the questions a user would ask after the fact: Which tool ran? When? Which confidence source supported the decision? What command boundary was used? Did it exit successfully? How long did it take? Was this a manual action or an automatic one?
QuotaWake documents local JSONL logs with the time, provider/tool, exit result, duration, decision source, and confidence. In practice, those fields turn a black-box background task into a reviewable operating history.
The useful outcome is transparency, not perfect prediction
A correctly designed decision cannot promise a provider state it cannot see. What it can provide is a careful local decision: evidence in, safeguards applied, action or non-action out, and a record that explains the result. That is enough for a person to decide whether the automation belongs in their workflow.
For the broader vocabulary and boundary, start with what usage-window scheduling means. For the data and process boundary that makes this decision local-first, read what stays local in session readiness.
Evidence & source material
The decision model is documented in the project and implemented in the readiness engine. These links make the confidence and guardrail claims inspectable.