Surface worker death reasons; auto-resume at limit reset; optional model fallback

[365atw]

What happened (real incident, 2026-07-12 ~00:32 America/Denver)

A 6h+ overnight gnhf run (--agent claude, model pinned via ANTHROPIC_MODEL) died with
"3 consecutive failures / claude exited with code 1:" — with an EMPTY error body — and then
sat at its "[ctrl+c to exit]" end screen until morning. The actual reason existed the whole
time, recorded in each worker's session transcript as a synthetic assistant message:

"You've hit your session limit · resets 3:40am (America/Denver)"

The run resumed cleanly in the morning with zero changes, meaning ~3.5h of potential work
time (from the 3:40am reset to morning) was lost purely to the runner not knowing why its
worker died.

Requests, in priority order

1. Relay the worker's death reason. When a claude worker exits non-zero, read the tail of
   its session transcript (~/.claude/projects//.jsonl) for a synthetic
   assistant message and surface that text in the failure banner and (ideally) a machine-readable
   run-state file. "claude exited with code 1:" with an empty body should never be the final word.
2. Auto-resume at the stated reset time. When the death reason matches a session/usage-limit
   message that names a reset time, schedule the next iteration attempt for that time instead of
   burning the remaining consecutive-failure budget immediately (3 retries in 12 minutes against
   a wall that resets hours later).
3. Optional model fallback. A flag such as --fallback-model <m> (or --on-limit rotate)
   so a run pinned to a premium model can degrade gracefully to a model with remaining headroom
   rather than dying. Default off to preserve current behavior.
4. Machine-readable end state. Write "stop condition met" / "N consecutive failures" (+ reason)
   to a sidecar file on disk when the TUI reaches its end screen, so supervisors do not have to
   scrape the terminal to learn a run has ended while the process is still alive at
   "[ctrl+c to exit]".

Environment

gnhf with --agent claude, Claude Code 2.1.207, WSL2 Ubuntu. Happy to provide the full
night-1 log and session transcripts on request.

[omkarbhale]

Would especially love resume after session reset since (presumably) most of us run with a subscription (not API costs.)

[kunchenguid]

Speaking as Kun's firstmate:

VISION.md per-rule:

1. No work is ever lost — aligned. An empty claude exited with code 1: hid a resettable session-limit death and sat at the end screen, so hours after the reset produced no commits. Surfacing the real death reason, not burning the consecutive-failure budget against a wall that resets later, and writing a machine-readable end state all keep night work from vanishing.
2. The user holds the leash — aligned with constraints. Stay-alive on a resettable usage window matches defending the night against an early abort. Permanent errors (exhausted credit) must still abort at once — main already maps low credit balance to PermanentAgentError. Auto-resume is new autonomy: it needs a user-settable wait/limit and a working interrupt. Optional --fallback-model default-off is correctly leashed.
3. Small surface, wide reach — aligned if implemented on the loop, not a new vendor scrape. VISION already requires the real error and full cause chain. Prefer the CLI stream/result events over reading ~/.claude/projects transcripts. Do not add a new native adapter. Fallback stays opt-in.
4. Nothing identifiable leaves the machine — aligned if the sidecar stays under .gnhf/runs/ and transcripts are not copied into telemetry.
5. Delight is part of the contract — aligned. A morning-legible failure banner beats an empty [ctrl+c to exit] screen.
6. Scope — aligned. This is the unattended loop staying alive and becoming reviewable in the morning, not a coding agent, CI, or merge authority.

Labeling ready-for-pr. A contributor PR that (a) surfaces the worker death reason with its cause chain, (b) waits for a resettable usage-limit window without burning consecutive failures, with interrupt plus a user-settable wait bound, (c) optional model fallback default-off, and (d) writes a machine-readable end state under .gnhf/runs/, is welcome. Related implementation already exists as PR #179 — help that if it becomes merge-shaped; I will not open a duplicate implementation PR.