fix(claude): surface nested Claude Code hangs with timeout + diagnostics

[Wirasm]

Follow-up to #1068. Addresses the silent-hang class of bug reported in #1067.

Context

#1067 reported that `archon workflow run` hangs at `dag_node_started` for 30+ minutes with no error. The RCA (in `.agents/rca/issue-1067-nested-claude-hang.md`) could not reproduce the hang on current `dev` or the v0.3.5 binary — Archon already strips `CLAUDECODE` from the subprocess env (`packages/core/src/clients/claude.ts:167-170`). The reporter's hang is likely environmental (keychain/TCC/SessionCreate state, macOS launchd, specific Claude Code CLI version, or an upstream SDK quirk we didn't trace).

Since we can't pinpoint the root cause, this PR adds defense in depth + diagnostics so the next user hitting this class of issue gets a loud, actionable failure in under 60 seconds instead of 30 minutes of silence.

Changes

1. CLAUDECODE=1 startup warning

`packages/cli/src/cli.ts` — prints a warning when `CLAUDECODE=1` is inherited from the parent env, pointing at #1067 and the `archon serve` workaround. Suppressable via `ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING=1`.

```
⚠ Detected CLAUDECODE=1 — you appear to be running `archon` from inside a Claude Code session.
If workflows hang silently at dag_node_started, this is a known class of issue.
Workaround: run `archon serve` from a regular shell and use the web UI or HTTP API.
Details: #1067
```

2. First-event timeout on the SDK query generator

`packages/core/src/clients/claude.ts` — wraps `query({ prompt, options })` in a `withFirstMessageTimeout` helper that races the first `iterator.next()` against a 60-second timeout (configurable via `ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS`).

If the SDK produces no output within the window:

1. Log `claude.first_event_timeout` at error level with a diagnostic dump:
   • Subprocess env keys (names only, no values — no secrets leaked)
   • Parent process keys matching `CLAUDECODE`, `CLAUDE_CODE_`, `ANTHROPIC_`
   • SDK model, process platform, UID, TTY state, CLAUDECODE value, CLAUDE_CODE_ENTRYPOINT
   • Last 20 stderr lines from the subprocess
2. Call `controller.abort()` (best effort — the SDK may or may not respond)
3. Throw `Claude Code subprocess produced no output within {N}ms. See logs... Details: https://github.com/coleam00/Archon/issues/1067\`
4. Do NOT retry — a wedged subprocess will produce the same hang again

Why Promise.race instead of just abortController: the pathological case we're defending against is "SDK ignores abort" — so we need an independent unblocking mechanism. Promise.race guarantees the first-event wait resolves within the timeout regardless of SDK behavior.

The wrapper is zero-overhead on the happy path: after the first message arrives, it just forwards `iterator.next()` calls directly.

Validation

• `bun run validate` passes (type-check, lint, format, all tests)
• 3 new unit tests in `packages/core/src/clients/claude.test.ts`:
  • Normal run completes without firing the timeout
  • Stuck generator triggers the timeout within the configured window
  • Timeout error mentions 2 issues: v0.3.5: CLI workflow run silently hangs — dotenv loads .env from CWD instead of ~/.archon/.env,, + rchon serve hardcodes skipPlatformAdapters:true — Telegram/Discord/Slack adapters are unreachable #1067 for discoverability
• E2E (archon version): warning prints with CLAUDECODE=1; suppressed with `ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING=1`
• E2E (archon workflow run archon-assist): completes normally in 2.8s with CLAUDECODE=1 in parent env — the timeout doesn't fire on the fast path

Files

• `packages/cli/src/cli.ts` — CLAUDECODE warning (+15 lines)
• `packages/core/src/clients/claude.ts` — `withFirstMessageTimeout`, `getFirstEventTimeoutMs`, `buildFirstEventHangDiagnostics`, wire-in (+137 lines)
• `packages/core/src/clients/claude.test.ts` — 3 new tests (+87 lines)

Rollback

Single commit, no schema or API changes. `git revert ` cleanly reverts all three changes. The timeout is configurable via env var, so operators can set it to a very high value if they want to effectively disable it without a revert.

Not in this PR

• Allowlist → blocklist refactor (the design question raised by Add MiniMax M2 API and additional environment variables to subprocess allowlist #1070/fix(core): add AWS env vars to subprocess allowlist for Bedrock auth #1060/feat: add Qwen support to Archon #1050/feat(cli): inject codebase env vars for bash nodes #1069). That's a larger conversation and deserves its own PR/RFC. See the review comment for my take.
• Duplicate key detection in `~/.archon/.env` — separate UX improvement, file 2 issues: v0.3.5: CLI workflow run silently hangs — dotenv loads .env from CWD instead of ~/.archon/.env,, + rchon serve hardcodes skipPlatformAdapters:true — Telegram/Discord/Slack adapters are unreachable #1067 tracks it.
• Root cause fix for the reporter's specific hang — we couldn't reproduce it, so this PR makes the class of failure observable rather than chasing a ghost.

Summary by CodeRabbit

• Bug Fixes
  • Added timeout detection for Claude client when responses aren't received within expected timeframes, including improved diagnostic information in error messages.
  • Added CLI warning in specific environment configurations to help users troubleshoot setup issues.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6694a4cf-4816-47c8-9cd0-7db1f4b7299a

📥 Commits

Reviewing files that changed from the base of the PR and between 536584d and 17e47f3.

📒 Files selected for processing (3)

• packages/cli/src/cli.ts
• packages/core/src/clients/claude.test.ts
• packages/core/src/clients/claude.ts

---

📝 Walkthrough

Walkthrough

This change introduces a first-event timeout mechanism for Claude API queries (default 60 seconds, configurable) with diagnostic logging when no initial event arrives within the deadline. Additionally, a CLI startup warning detects nested Claude execution and notifies users unless explicitly suppressed.

Changes

Cohort / File(s)	Summary
CLI Startup Warning packages/cli/src/cli.ts	Detects nested Claude execution via CLAUDECODE=1 environment variable and conditionally emits a console.warn message with guidance unless ARCHON_SUPPRESS_NESTED_CLAUDE_WARNING is set.
Claude First-Event Timeout packages/core/src/clients/claude.ts, packages/core/src/clients/claude.test.ts	Implements first streamed message timeout (default 60s, configurable via ARCHON_CLAUDE_FIRST_EVENT_TIMEOUT_MS) with withFirstMessageTimeout() race logic, buildFirstEventHangDiagnostics() for diagnostic snapshots, and error-level logging on timeout. Retry logic now detects and rethrows timeout-specific errors without retry. Tests cover timeout expiration scenarios, immediate yield validation, and error message verification including issue references.

Sequence Diagram

sequenceDiagram
    participant Client as ClaudeClient
    participant Controller as AbortController
    participant SDK as Anthropic SDK
    participant Timeout as Timeout Handler
    participant Logger as Diagnostic Logger

    Client->>Timeout: withFirstMessageTimeout(iterator, timeoutMs)
    Timeout->>SDK: Race first event yield
    alt First Event Arrives in Time
        SDK->>Timeout: yield chunk
        Timeout->>Client: return chunk
    else Timeout Expires
        Timeout->>Controller: abort()
        Timeout->>Logger: buildFirstEventHangDiagnostics()
        Logger->>Logger: collect working dir, attempt, model, stderr, env vars
        Logger->>Logger: log error with diagnostics
        Timeout->>Client: throw TimeoutError with issue link
        Client->>Client: detect firstEventTimedOut, rethrow without retry
    end

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 twitches nose knowingly
A timeout waits with patient grace,
While Claude takes time to find its place,
With warnings bright for nested calls,
The diagnostics catch it all! ⏰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding timeout and diagnostics for nested Claude Code hangs, which is the core focus of the PR.
Description check	✅ Passed	The description covers all critical template sections: context/problem, specific changes with code examples, validation evidence, backward compatibility, and rollback plan. It is comprehensive and well-structured.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/claude-hang-diagnostics

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Wirasm]

Superseded by #1092 which consolidates this PR and #1068 into a single PR with docs updates.

[Wirasm]

Superseded by #1092 (now merged).