Fallback model chains + watchdogs — surviving an overloaded headless runCapability

Claude Code can fall back to a second model when the primary is overloaded, and a wall-clock watchdog kills a hung headless run before it eats your morning. Today's lesson closes the loop you accepted on 06-09 but never wired in — and it's the direct cause of the 🚨 pile in your Inbox.

When you run a job headless (`claude -p ...` from a LaunchAgent), the model can come back 'overloaded' or 'unavailable' — a 529/503 from the server. With one model named, that's the end of the run: it errors, the LaunchAgent logs a non-zero exit, and you get a 🚨 task (if you're lucky) or silence (if you're not). `--fallback-model` lets you name a backup that's tried automatically when the primary fails over — you can chain up to three.

But a fallback only solves 'the server said no.' It does NOT solve 'the run hung for 34 minutes' — which actually happened to plan-day on 5/30. That's a different failure, and the fix is a wall-clock watchdog: wrap the whole command in `timeout` so it's killed at a hard ceiling. Your own CLAUDE.md automation-hygiene rule is blunt about this: 'every long job has a watchdog you've proved kills,' and 'an unverified watchdog is decorative.'

Both belong on the same jobs: `run_plan_day.sh`, `run_weekly_review.sh`, and the `language_lesson.py` / `learning_lesson.py` LaunchAgents. The 🚨 backlog is the symptom of neither being wired — a perfect case study for the day you're about to leave the system unattended for two weeks.

Worked example

The two-line hardening — a fallback chain plus a timeout watchdog around a headless run:

# BEFORE — one model, no ceiling. Overload or hang = failure.
claude -p "$(cat plan_day_prompt.txt)"

# AFTER — fallback chain + 25-min wall-clock watchdog
timeout --signal=TERM --kill-after=30s 25m \
  claude -p "$(cat plan_day_prompt.txt)" \
    --model claude-opus-4-8 \
    --fallback-model claude-sonnet-4-6 \
  || /usr/bin/python3 ~/Claude/PDB/scripts/notify_fail.py "plan-day"

• `timeout --signal=TERM --kill-after=30s 25m` — the watchdog. If the run isn't done in 25 minutes it gets a TERM; if it ignores that, a KILL lands 30s later. This is the 'watchdog you've proved kills' your CLAUDE.md demands.
• `--model` sets the primary; `--fallback-model` is tried automatically when the primary returns an overload/unavailable error. Pass it more than once to chain up to three models.
• `|| notify_fail.py` — the OR fires only if the whole thing exits non-zero (the watchdog fired OR every model failed). It creates the 🚨 Things task so the failure surfaces where you read it, instead of dying silently in a log.

Gotchas

• A fallback model only catches server-side overload/unavailability. A bad prompt or a missing input file still fails on every model — garbage in, garbage out, three times over.
• `timeout` sends TERM by default, which a stubborn process can ignore. Always add `--kill-after=30s` so a follow-up KILL lands. And actually force a hang once to confirm it fires — an untested watchdog is decorative.
• Fallback adds latency: the primary has to fail first (often a 30–60s server timeout) before the backup starts. Don't set the watchdog so tight that the fallback never gets its turn.