A usage limit reaches a headless agent as plain text instead of an error
When a scheduled claude -p run hits the plan's usage limit, the message arrives as ordinary output, and a job can still end with exit code 0.
SymptomA scheduled agent job shows success, but its output is one line about a usage limit and none of its real work.
I expected a usage limit to fail a headless run loudly, yet the CLI printed one line, 'You've hit your … limit', as normal output. Several jobs wrote that line into their own dated logs and finished with exit code 0, so a status check saw success even though the work had not happened.
My first detector read exit codes, so it saw nothing. The second scanned the output for the limit line, but loose matching caught ticket titles and a search vendor's own 'usage limit reached' text. The line needs an anchor on its exact shape, and the plan limit and the spend cap need separate checks, because both lines can name a time the limit lifts.
One digest job echoed the message cut at 100 characters. The time the limit lifts was in the cut part, so the retry used a default wait and ran too early. Jobs that keep CLI output in a per-run folder were invisible to a scan of the main log. Those jobs have to print the limit line themselves and record a stop reason.
The fix is the same for every job. Read the output as well as the exit code, anchor on the message shape, and record a stop reason when the limit text appears. Then a limit is a known stop with a retry time rather than a silent success.
Search each scheduled job's log for the text 'hit your' followed by 'limit'. Compare each match with the recorded status of the same run.
Passes ifEvery run whose log holds that text also shows a failure status or a recorded stop reason.
Access needed:scheduleragent-transcripts
- 01Search every scheduled job's log for the text 'hit your' followed by 'limit'.
- 02Match each hit with the run's exit code.
- 03List the jobs that keep CLI output outside the main log.
- 04Make each job print the limit line and record a stop reason.
- 05Keep the full line so the time the limit lifts survives.