Proposal: wake-up schedules — resume an agent automatically when its usage limit resets

[yuruiz]

Problem

Claude Code and Codex enforce rolling usage limits — a 5-hour window, plus weekly caps. A long-running task that hits the limit dies mid-turn, and the agent sits idle until the window resets. Today your options are:

• Watch the clock and resume manually — which defeats the point of remote monitoring.
• Create a recurring schedule that blindly sends "continue" every N hours — it fires whether or not the limit actually reset, keeps firing after the task is done, and is invisible while it waits.

The information needed to do better already exists: the daemon's quota fetcher knows the exact reset time for Claude's 5h/weekly windows and Codex's primary/secondary windows. It just never reaches the agent lifecycle.

Proposal

When a turn fails because of a usage limit, the composer offers a one-tap wake-up:

1. Detection — the daemon classifies the failed turn as rate-limited (error heuristics, cross-checked against a forced quota refresh, which also yields the authoritative reset time).

2. Banner above the composer — instead of a bare error state, the composer shows:

   ┌────────────────────────────────────────────────┐
   │ ⚠ Usage limit reached — resets at 14:32        │
   │   Resume this agent automatically?             │
   │           [ Create wake-up schedule ]          │
   ├────────────────────────────────────────────────┤
   │  [ composer …                           ⬆ ]   │
   └────────────────────────────────────────────────┘
   

3. One tap creates the schedule — a one-shot schedule targeting this agent, firing at the reset time (plus a small buffer), sending a continue prompt into the same session.

4. It stays visible while it waits — until it fires, the pending wake-up floats above the composer as a chip with a countdown, one tap to cancel:

   ┌────────────────────────────────────────────────┐
   │ ⏳ Wake-up scheduled · fires in 1h 42m     ✕   │
   ├────────────────────────────────────────────────┤
   │  [ composer …                           ⬆ ]   │
   └────────────────────────────────────────────────┘
   

Consent happens once, at the moment of failure. No setting to discover in advance, no quota burned unattended by default — and unlike a blind cron, you can always see that the agent will wake itself, and how to stop it.

Why a schedule, and not a timer inside the agent

A wake-up should survive daemon restarts, be inspectable in the schedules list, and be cancellable from the same place as every other schedule. The schedule service already is that: persisted storage, a tick loop, and an existing target type that delivers a prompt to an existing agent (ScheduleTarget type agent). The feature composes two things Paseo already has, rather than adding a third way to resume an agent.

What exists today

• Reset times — the quota fetcher retrieves resetsAt for Claude's 5h window and weekly limits, and Codex's primary/secondary windows (packages/server/src/services/quota-fetcher/). Currently feeds the quota UI only.
• Schedules — the schedule service can target an existing agent and deliver a prompt, with persisted storage.
• Session continuity — agent sessions are resumable; failed turns are already resumable, and the system-envelope mechanism (formatSystemNotificationPrompt) exists for injected "continue" prompts.

What's missing

1. Rate-limit classification — turn errors aren't classified today. The heuristic guesses from error text, then confirms with a forced quota refresh. This avoids parsing "resets 3:04pm" out of an error string and handles provider wording drift.
2. One-shot cadence — ScheduleCadence only supports every and cron. A wake-up wants "fire once at time X, then complete" — likely a third cadence variant rather than a fake cron expression.
3. The composer surfaces — the banner CTA and the persistent pending chip. The composer already reacts to per-agent pending state (e.g. pending permission prompts change send behavior), so the slot concept exists.
4. Auto-cancel — if you manually prompt the agent before the wake-up fires, the schedule should probably cancel itself (see open questions).

Open questions

• Weekly caps. When the weekly limit is what's exhausted, resetsAt may be null or days away — a wake-up doesn't help. Degrade to a plain notification ("limit reset, tap to resume") in that case?
• Shared accounts. Multiple agents on one account share the quota. Should wake-ups for the same account be staggered so three agents don't wake at once and immediately re-exhaust the window?
• What the wake-up sends. Re-send the interrupted prompt verbatim, or a system envelope ("you were interrupted by a usage limit — continue where you left off")? The envelope seems safer when the turn died mid-task.
• Buffer and verification. Fire at resetsAt + a minute or two, and re-check the quota before sending — if the window hasn't actually reset, recompute the next wake-up instead of sending into a wall.
• Notification variant. Some users won't want unattended quota burn at all. The push variant ("limit reset, tap to resume") is nearly free once detection exists — worth shipping both?

[yuruiz]

Duplicate of #4122 (accidental double post) — continuing the discussion over there.