cprof: auto-resume a Claude Code task stopped for lack of tokens

[dcotelo]

Problem

When a Claude Code session/task gets stopped by a rate limit (a 429 with a
"resets at HH:MM" message), there's currently no way to have it come back on
its own — you have to notice the reset happened and manually relaunch or
claude --resume <session-id> yourself. Doing this by hand (poll wall-clock
time, then relaunch) is exactly the kind of thing cprof is positioned to
absorb, since it already tracks per-profile identity and per-profile
resets_at timestamps.

Proposed behavior

Something like:

cprof resume-on-reset <session-id> [--profile <name>]

Waits for the given profile's usage window to reset (reusing the cache and
resets_at data cprof usage already fetches), then runs claude --resume <session-id> with that profile's CLAUDE_CONFIG_DIR, so the interrupted task
picks back up automatically instead of sitting stopped until a human notices.

Alternatives considered

A shell wrapper that sleeps and relaunches is possible today, but it has to
rediscover the reset time, the profile's config directory and the session id
itself — three things cprof already knows. pin/rule/default/env decide
which account a session uses, not when a session runs, so none of them
cover this.

The fallback-account feature (0.11.0) covers a different case: it swaps to
another account so work continues now, rather than waiting for this account's
window to reopen. Both can be wanted for the same session.

Additional context

Surface: CLI, and it is the one proposal here that launches Claude Code rather
than just reporting — worth deciding whether cprof should ever spawn a session,
or only print the command for a caller to run.

Needs network for the confirming fetch, and needs the session id from the
caller: cprof does not track sessions today.

Overlaps #25, which proposes the wait primitive this would build on. Whichever
lands first should expose the wait in a callable form.

Note: the original filing linked
docs/superpowers/specs/2026-09-14-per-profile-usage-design.md for the
resets_at details. That path is not in the repository — docs/superpowers/ is
deliberately untracked — so the live reference is cp_usage_resets_at and
cp_usage_window_open in scripts/lib/usage.sh, plus docs/usage.md.