# 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.

By Ki Moon · 2026-11-16 · failure · current
Canonical: https://kihmoon.com/bench-notes/p/usage-limit-arrives-as-text/

**Symptom:** A 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.

## Check your setup (read-only)

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 if:** Every run whose log holds that text also shows a failure status or a recorded stop reason.

**Access needed:** scheduler, agent-transcripts

## If it fails (changes to make later, not part of the check)

1. Search every scheduled job's log for the text 'hit your' followed by 'limit'.
2. Match each hit with the run's exit code.
3. List the jobs that keep CLI output outside the main log.
4. Make each job print the limit line and record a stop reason.
5. Keep the full line so the time the limit lifts survives.

**Applies if:** You schedule headless claude -p jobs and judge a run by its exit code or by the last line of its log.

**Skip if:** Every job already records a stop reason from the CLI output text, and a run with no real work counts as a failure.

Tags: tooling, claude-code, headless, scheduler
