Guard against claude -p hanging when auth is expired

[macroclaw-bot]

Problem

When Claude Code's OAuth session expires and claude -p is invoked, it hangs indefinitely retrying authentication instead of failing fast. This blocks macroclaw completely — the user gets no response and no error.

Proposed solution

Run claude auth status as a parallel guard alongside each claude -p invocation:

1. Start both in parallel: spawn claude -p <prompt> and claude auth status concurrently
2. If auth status fails (non-zero exit), kill the claude -p process and report to the user immediately (e.g. "Claude auth expired — run /login to re-authenticate")
3. If auth status succeeds, let claude -p continue normally (discard the auth check result)

This avoids the overhead of a blocking pre-check on every request while still catching expired auth quickly. The auth check is fast (~1-2s) so it will resolve well before a hanging claude -p would time out.

Alternatives considered

• Pre-check before every request: adds latency to every invocation even when auth is fine
• Timeout then check: slower to detect the issue — user waits for the timeout before getting feedback
• ANTHROPIC_API_KEY env var: bypasses OAuth entirely but requires managing API keys separately

Additional context

• claude -p hanging on expired auth has no built-in CLI fix (no --no-retry flag exists)
• The subprocess stdin hanging bug was fixed in v2.1.79, but auth retry hanging is a separate issue

[macrosak]

It will probably not work:

$ claude auth status
{
  "loggedIn": true,
  "authMethod": "claude.ai",
  "apiProvider": "firstParty",
  "email": "...",
  "orgId": "...",
  "orgName": "....",
  "subscriptionType": "max"
}

$ echo $?
0

$ claude
❯ test                                                                                                              
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth 
     token has expired. Please obtain a new token or refresh your existing                                          
     token."},"request_id":"req_011CZDBj5jw6j72JrDp53Sao"}  

[macrosak]

The next time it happens, we should test the verbose output.

[macroclaw-bot]

New findings (2026-04-30)

Reproduction in the wild. Auth token expired sometime around 2026-04-30 03:18 local. Symptoms across all crons (heartbeat, morning-brief, nightly-commit, self-update, even main session user messages):

ERROR: QueryValidationError: Claude output did not match the expected schema
  caused by: ZodError: [{ "expected": "object", "code": "invalid_type", "path": [], "message": "Invalid input: expected object, received undefined" }]
  at #parseResult (src/claude.ts:181:19)

Failure mechanism

In src/claude.ts #parseResult, the result envelope arrives but envelope.structured_output is undefined. The schema parse on undefined throws. Confirmed by reading the code — there's no upstream check for is_error/subtype === "error" before structured-output validation, so any error envelope falls into this path.

Crucially, QueryValidationError only captures raw and cause — but the catch site doesn't log raw. So we got the Zod error, not the envelope. That's the first thing to fix.

Healthy envelope (captured now, post-relogin)

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "api_error_status": null,
  "duration_ms": 9434,
  "num_turns": 5,
  "result": "",
  "stop_reason": "end_turn",
  "structured_output": { "action": "silent", "actionReason": "..." }
}

Timing fingerprint

Time	Cron	Model	Duration	Outcome
02:17	heartbeat	sonnet	~12s	success
03:00	memory-consolidate	opus	37s	success
03:17	heartbeat	sonnet	62s	fail (first)
04:17	heartbeat	sonnet	4s	fail
05:17	heartbeat	sonnet	4s	fail
...	...	...	3–4s	fail
08:17	heartbeat	sonnet	4s	fail

The first failure took 62s — almost certainly internal SDK retries on the 401. After that, the SDK fast-fails in 3–4s, which is a strong detection signal.

claude auth status is unreliable (confirmed)

Per the issue body: claude auth status returns loggedIn: true with exit 0 even when the OAuth token has expired. Cannot use for liveness probe.

Recommended changes (in order)

1. 🔴 Log the raw envelope on QueryValidationError. One-line change in src/claude.ts — log parsed (or at least its keys + is_error + subtype + api_error_status + truncated result) before throwing. Without this we're flying blind on the next occurrence.

2. 🔴 Detect auth errors before schema validation. In #parseResult, before reading structured_output, check envelope.is_error === true or typeof envelope.api_error_status === "number". Throw a distinct QueryAuthError (or similar) so the orchestrator can route it differently.

3. 🟡 Out-of-band alert path. When QueryAuthError fires, the orchestrator can't use Claude to message the user — it needs a direct Telegram Bot API call (curl https://api.telegram.org/bot$TOKEN/sendMessage). Optionally a watchdog process.

4. 🟢 Liveness probe alternative. Since claude auth status lies, a real probe = trivial structured-output query with low max_tokens (~$0.001/call). Run on macroclaw startup + every few hours. Same Bot API alert path.

I'll wire up the log-watcher in the workspace as immediate mitigation. Suggesting #1 + #2 as a minimal PR for the proper fix.