Headless Claude — `claude -p` and the fallbackModel safety netCapability

When plan-day runs itself at 6:15am with no human watching, a single overloaded-model blip kills the whole run. `--fallback-model` is the one flag that turns that fatal error into an automatic retry on a cheaper model.

`claude -p "<prompt>"` is 'headless' or 'print' mode — it runs Claude with no interactive terminal, prints the result, and exits. This is the engine behind every unattended job you own: the 6:15am plan-day, the language email, the learning email. There's no human to click 'retry' when something hiccups, so every failure mode has to be handled by flags and wrapper logic instead of by you.

The most common transient failure isn't your fault: the API occasionally returns an 'overloaded' response (HTTP 529) when demand spikes. Interactively you'd just hit enter again. Headless, that response makes `claude -p` exit non-zero — and your wrapper correctly treats non-zero as 'the job failed,' fires a macOS notification, and creates the 🚨 Things task. Everything downstream worked exactly as designed; the problem is the job gave up on the first stumble.

`--fallback-model <name>` is the fix. You give it a second, usually cheaper/faster model (e.g. `sonnet`). If the primary model is overloaded or errors out, Claude automatically retries the same prompt on the fallback instead of exiting. For a planning job, a plan written by the fallback model is infinitely better than no plan and a red alert — graceful degradation beats hard failure every time for unattended work.

Worked example

Here's your actual invocation today (run_plan_day.sh, lines 116-122) and the one-line change that hardens it:

# TODAY — no fallback. One overload = dead run = 🚨 task.
run_with_timeout "$CLAUDE_TIMEOUT_S" \
    "$CLAUDE_BIN" \
        --settings '{"enabledPlugins":{}}' \
        --strict-mcp-config \
        --dangerously-skip-permissions \
        --permission-mode bypassPermissions \
        -p "/plan-day"

# HARDENED — add one line. Overload now retries on Sonnet.
run_with_timeout "$CLAUDE_TIMEOUT_S" \
    "$CLAUDE_BIN" \
        --settings '{"enabledPlugins":{}}' \
        --strict-mcp-config \
        --dangerously-skip-permissions \
        --permission-mode bypassPermissions \
        --fallback-model sonnet \
        -p "/plan-day"

• The first block is verbatim what fires at 6:15am right now — a clean, well-guarded call (timeout wrapper, no plugins, bypass permissions for headless) that nonetheless has a single point of failure: the model.
• `--fallback-model sonnet` is the only added line. It says 'if the default model can't take this request, run the exact same /plan-day on Sonnet instead of dying.'
• Flag order doesn't matter — it just has to come before the `-p` prompt. Sonnet is the natural fallback: cheaper, faster, and more than capable of writing a day plan if Opus is momentarily busy.

Gotchas

• A fallback model does NOT rescue you from a real bug in /plan-day (a missing file, a bad path). It only catches model-level failures — overload, rate limits, a model being temporarily unavailable. Genuine logic errors still surface as 🚨, which is correct.
• Don't set the fallback to another heavyweight model — the whole point is that the fallback should be more available, not equally contended. Sonnet or Haiku are the right tier.
• The watchdog (`run_with_timeout`) and the fallback solve different problems: the watchdog kills a HUNG run, the fallback retries a FAILED one. You want both — they don't overlap.