Errors · network · long-task resilience

Clavue (iclavue) unifies API errors, request failures, network faults, and long-task silence into one mechanism: a short primary line, an expandable diagnostic card, and a clear next step. Anchored on Grok Build SamplingError/RetryState and Claude Code’s visible retries.

At most one journal receipt per fail (blockId=api-fail-turn). Essays are never misclassified as transport failures. Esc/Ctrl+C interrupt is soft — no red wall.

Diagnostic card (user-visible)

Terminal fails paint multi-line journal rows: summary on line 1; · body lines collapse by default (expand with Enter).

⚠ Network error · retry (HTTP 503)
· kind: network · HTTP 503 · shouldRetry: yes
· attempt: 3/10 · model: grok-build · provider: gateway.example.com
· timeout: silent_first_token · 180s/180s
· next: check connection/gateway · retry · or switch model
· detail: ECONNRESET socket hang up

Error taxonomy

auth — 401/403 · no retry · /login · /provider
rate_limit — 429 · backoff · ACP -32003
network / server / timeout — retryable
context_overflow — /compact
client — bad request · check /model

Retries

Foreground main thread: up to 10 attempts (Claude-class withRetry). Status shows attempt n/m — never silent Thinking. After 3×529, the fallback chain runs.

API Error (503) · Retrying in 2s · attempt 2/10

Timeouts & long tasks

Source	Default	Behavior
`silent_first_token`	180s	Force-fail if no tools yet · env CLAVUE_SILENT_FIRST_TOKEN_MS
`stream_idle`	90–300s	Stream idle · per model family · CLAVUE_STREAM_IDLE_TIMEOUT_MS
`mid_turn_stall`	2 min heartbeat	Tools running: heartbeat only (don’t kill long agents) · CLAVUE_MID_TURN_STALL_MS; optional CLAVUE_MID_TURN_ESCALATE_MS force-fail

Terminal copy must name the timeout source (e.g. timeout: silent_first_token · 180s) so kills are attributable.

Environment

# First-token force-fail (default 180000)
export CLAVUE_SILENT_FIRST_TOKEN_MS=180000

# Mid-turn heartbeat after last tool/stream activity (default 120000)
export CLAVUE_MID_TURN_STALL_MS=120000

# Optional: force-fail mid-turn after this silence (0 = off)
export CLAVUE_MID_TURN_ESCALATE_MS=0

# Stream idle (model-family defaults 90–300s)
export CLAVUE_STREAM_IDLE_TIMEOUT_MS=180000

Troubleshooting

/doctor — PATH · pager · env health
/provider · /model · /login
Expand the fail row for kind / HTTP / attempt / model / next