SSE streaming hangs indefinitely (no timeout) + ESC cannot fully cancel (queue auto-restart) — root cause analysis with fix proposals

[kolkov]

Summary

These two bugs have been plaguing users for months (see #26224 — 28 comments, #6836 — 150+ reports), with no root cause analysis from the team. After yet another day of babysitting Claude Code and pressing ESC every few minutes to revive a hung agent, we decided to conduct our own deep investigation — reverse-engineering cli.js across 12 npm package versions and analyzing 1,571 session JSONL files containing 148,444 tool calls.

Here are the exact root causes and proposed fixes.

Claude Code hangs indefinitely when an SSE streaming connection silently dies. There is no client-side timeout or heartbeat detection, so the process waits forever for events that will never arrive. ESC partially works around this by aborting the dead connection, but the queue auto-restart mechanism (queue.length > 0 → n()) immediately starts the next queued prompt instead of returning control to the user.

Root cause identified in source code — two separate issues in cli.js:

1. No streaming timeout: The messages.stream() call has no timeout. If the SSE connection dies silently (TCP half-open), the client waits forever.
2. Queue auto-restart after abort: After ESC aborts a hung request, if (queue.length > 0) { n(); return; } immediately starts the next queued prompt. The user cannot fully cancel.

Environment

• Claude Code: 2.1.74 (also confirmed on 2.1.50–2.1.73)
• OS: Windows 10, Git Bash
• Model: Opus 4.6
• API: Anthropic direct (not Bedrock/Vertex)

Reproduction

1. Start a Claude Code session
2. Submit a prompt → agent starts processing
3. Wait for a hang (0 tokens, timer running, no progress) — happens ~10-15% of prompts
4. Submit another prompt while hung → goes to queue
5. Press ESC
6. Expected: Cancel everything, return to ❯
7. Actual: Cancels the hung prompt, immediately starts the queued one

Frequency

Measured across 1,571 sessions using a custom JSONL analyzer tool:

Period	Versions	Orphan rate (lost tool calls)
Dec 2025	2.0.72–2.1.2	6–14%
Jan 2026	2.1.5–2.1.23	5–10%
Feb 2026	2.1.29–2.1.56	3–8%
Mar 2026	2.1.69–2.1.74	2.4–4%

The hang frequency has been increasing over time: rare in fall 2025, now ~10-15% of prompts per hour.

Source Code Analysis

Analyzed cli.js extracted from npm pack @anthropic-ai/claude-code across versions 2.0.72 through 2.1.74.

Issue 1: No streaming timeout

The API call at approximately offset 2,553,870 in cli.js (v2.1.74):

client.beta.messages.stream({...params}, options)

There is no timeout parameter, no keepalive check, and no heartbeat detection. The Anthropic SSE API sends periodic :ping comments, but the client does not monitor for their absence.

When the TCP connection silently dies (common on Windows, WiFi, VPN, or after laptop sleep), the Node.js HTTP client has no way to know the connection is dead. The AbortController signal is never triggered because no error event fires.

Evidence: Packet inspection by other reporters confirms the client is stuck waiting for SSE events that never arrive. Token count stays at 0. ESC + re-submit creates a new connection that works immediately.

Issue 2: Queue auto-restart prevents full cancellation

The main processing loop (offset ~11,400,559 in v2.1.74):

n = async () => {
  if (M) return;       // running guard
  M = true;
  // ... prepare input, call API, process response ...
}

After completion or abort — in the finally block (offset ~11,406,174):

finally {
  M = false;           // clear running guard
  W6.start();          // restart idle timer
}
if (c36()) {           // c36() = yY.length > 0 = queue not empty?
  n();                 // YES → immediately restart with queued message!
  return;              // without returning control to user!
}

Historical analysis of npm packages confirms this pattern exists since v2.1.50 (as queue.length > 0) and was refactored to c36() in v2.1.74.

Issue 3: JSONL writer race condition (related)

The session writer class LZq (offset ~10,549,000) has a non-atomic insertMessageChain() that writes assistant (tool_use) and user (tool_result) messages one at a time in a loop:

async insertMessageChain(A, q, K, Y, z) {
  return this.trackWrite(async () => {
    for (let H of A) {
      await this.appendEntry(M);  // each message separately!
    }
  });
}

If the process is interrupted between writing tool_use and tool_result, the tool_use becomes orphaned. This is the root cause of issue #6836.

Proposed Fixes

Fix 1: Streaming timeout (critical)

Add a client-side timeout that aborts and retries if no SSE events are received within N seconds:

// Pseudocode
const STREAM_IDLE_TIMEOUT_MS = 30_000;
let lastEventTime = Date.now();

stream.on('event', () => { lastEventTime = Date.now(); });

const watchdog = setInterval(() => {
  if (Date.now() - lastEventTime > STREAM_IDLE_TIMEOUT_MS) {
    clearInterval(watchdog);
    abortController.abort();
    // retry with new connection
  }
}, 5_000);

The Anthropic API sends :ping SSE comments periodically. Monitoring for these would detect stale connections without false positives.

Fix 2: ESC should clear the queue

When the user presses ESC during a hang, the queue should be cleared (or the user should be asked):

// After abort, before checking queue:
if (userInitiatedAbort && c36()) {
  // Option A: Clear queue entirely
  clearQueue();
  return; // back to prompt

  // Option B: Ask user
  // "You have N queued messages. Clear queue? (y/n)"
}

Fix 3: Atomic message chain writes

insertMessageChain() should serialize the entire chain as a single appendToFile() call:

async insertMessageChain(messages) {
  const serialized = messages.map(m => JSON.stringify(m)).join('\n') + '\n';
  await this.appendToFile(sessionFile, serialized);
}

Note: history.jsonl already uses proper-lockfile for file locking — the same approach should be applied to session JSONL files when multiple agents write concurrently.

Related Issues

• [Meta] tool_use/tool_result block mismatch causing bad conversation state (150+ reports) #6836 — Orphaned tool_use/tool_result pairs (150+ reports)
• [BUG] [URGENT!!!] Claude Code is hanging / freezing / stuck on heaps of prompts for 5-20minutes or more. #26224 — Agent hangs 5-20 minutes, 0 tokens
• Session becomes unresumable after JSONL writer drops assistant entry during parallel tool calls #31328 — JSONL writer drops assistant entry during parallel tool calls
• [BUG] Phantom 'Generating...' state - UI stuck after task completion, 0 tokens consumed #20171 — Phantom "Generating..." state after task completion
• Claude Code freezes during API call ("Befuddling" spinner), terminal becomes completely unresponsive #24688 — Freeze during API call, terminal unresponsive
• [Bug] The .claude.json elephant in the room: Is this "vibe coding" in production? #7243 — .claude.json architectural issues (non-atomic writes, no separation of concerns)
• Fear of updating: When 'vibe coding' meets production stability #14642 — Systemic stability problems driving users to build their own tools

Methodology

Analysis performed using:

• ccdiag: Custom Go CLI tool that parses JSONL session files, detects orphaned tool calls, analyzes timing, and scans multiple sessions
• Source analysis: cli.js extracted from npm packages across 12 versions (2.0.72 through 2.1.74), searched for queue/abort/streaming patterns
• Session data: 1,571 sessions, 148,444 tool calls, 8,007 orphaned

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude Code hangs indefinitely when API streaming connection stalls (no read timeout) #25979
2. [BUG] Claude Code hangs indefinitely on SSE stream with multiple simultaneous sessions #27841
3. API Streaming Stalls Causing 59-138 Second Delays and Timeouts #18028

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[kolkov]

This is not a duplicate of any of those issues. Here's why:

Issue	What it has	What it lacks
#25979	Symptom description (hang on stall)	No source code analysis, no fix proposals
#27841	Symptom description (hang with multiple sessions)	No root cause, no code references
#18028	Timing measurements (59-138s delays)	No source analysis, no fix proposals
This issue	Root cause in source code + 3 fix proposals + 12-version npm archaeology + 1,571 session dataset	—

Those issues describe what happens. This issue explains why it happens and how to fix it — with exact code offsets in cli.js, pseudocode fixes, and statistical evidence from 148,444 tool calls.

Specifically, this issue identifies:

1. The exact messages.stream() call with no timeout (offset ~2,553,870 in v2.1.74)
2. The queue auto-restart pattern if(c36()){n();return} that prevents ESC from fully cancelling (offset ~11,406,174)
3. The non-atomic insertMessageChain() race condition causing orphaned tool_use (offset ~10,555,400)

None of the "duplicate" issues contain any of this analysis.

[kolkov]

⚠️ Updated April 1, 2026: The source map leak in v2.1.88 gave us access to the full TypeScript source. We've posted updated prompts with exact file paths and line numbers — no more reverse engineering of minified code: Updated prompts →

Also see our full write-up: We Reverse-Engineered 12 Versions of Claude Code. Then It Leaked Its Own Source Code.

---

Since 100% of Claude Code is now written by Claude Code itself — "I have not edited a single line by hand since November" (Boris Cherny, creator of Claude Code) — here are ready-to-use prompts for @bcherny to copy-paste directly into Claude Code and fix these issues. No reverse engineering skills required — we already did that part.

But first — the prompts alone won't help if the development process itself is broken. So let's start there.

Important note on testing: We suspect Anthropic internally uses a private API endpoint or prioritized infrastructure that doesn't experience the same latency, timeouts, and stale connections that paying customers face on the public API. This would explain why these bugs go unnoticed internally — if your SSE stream never stalls on a private backbone, you'll never hit the missing timeout. Meanwhile, your paying customers — on real networks, with real latency, WiFi drops, VPN reconnects, and laptop sleep/wake cycles — hit it multiple times per hour and pay for every wasted token and every minute of babysitting a hung agent. All testing for these fixes MUST be done against the public API, on real consumer hardware, with simulated network instability. Not on Anthropic's internal infrastructure where everything "just works."

---

Prompt 0: Set up a proper development workflow

Read the project's CLAUDE.md. If it doesn't exist, create it. This is the most
important file in the project — it defines how YOU (Claude Code) should work
on this codebase. Add the following sections:

## Release Checklist (MANDATORY before every release)

Before shipping ANY release, verify:

1. [ ] Core workflow test: submit prompt → stream response → execute tool
       → return result. Does it complete without hanging? Test 20 times.
2. [ ] ESC test: Start a prompt, press ESC mid-stream. Does it return to
       the prompt immediately? No queued messages auto-starting?
3. [ ] Network failure test: Disconnect WiFi mid-stream. Does the client
       detect the dead connection within 30s and recover?
4. [ ] Concurrent write test: Run 2 agents writing to the same session.
       Are all tool_use/tool_result pairs intact in the JSONL?
5. [ ] Long session test: Run a 2-hour session with 100+ tool calls.
       Count orphaned tool_use entries. Must be 0.
6. [ ] Disk pressure test: Run with <1GB free disk space. Does it degrade
       gracefully or corrupt settings files?

If ANY check fails — DO NOT RELEASE. Fix it first.

## Priority Rules

- Bug fixes for core workflow ALWAYS take priority over new features
- Every network call MUST have a timeout — no exceptions
- Every multi-step file write MUST be atomic
- ESC means STOP EVERYTHING — never auto-restart after user abort

## Known Debt (must fix before adding features)

- #6836 — orphaned tool_use/tool_result (150+ reports, 6+ months open)
- #26224 — streaming hangs indefinitely (30+ comments, 0 team responses)
- #20171 — phantom "Generating..." state (17 comments)
- #33949 — root cause analysis with exact code locations and fix proposals

## Pre-commit Checks

Before committing, always run:
- All existing tests pass
- No new network calls without timeout
- No new file writes without atomic pattern
- No queue auto-restart after abort paths

## Session Memory

After each work session, update STATUS.md with:
- What was changed and why
- What tests were added
- What known issues remain
- What regressions to watch for

This is how agentic engineering works — you give the AI agent clear rules,
priorities, and checklists BEFORE it starts coding. Not after. Not "vibes".

For more on this approach, see: From Vibe Coding to Agentic Engineering: What Karpathy Got Right and What's Missing

---

Now the actual fixes:

Prompt 1: Fix streaming timeout (Issue #33949, Root Cause #1)

Read the streaming API call in the codebase where client.beta.messages.stream()
is called. There is no timeout or heartbeat detection — if the SSE connection
silently dies (TCP half-open), the client waits forever. This is the #1 cause
of "agent hangs, timer running, 0 tokens" reports.

Fix: Add a watchdog timer that monitors incoming SSE events. The Anthropic API
sends periodic :ping SSE comments. If no events are received for 30 seconds,
abort the connection via AbortController and retry with a new connection.
Implement exponential backoff for retries (max 3 attempts).

Create a todo list before starting. Write tests for:
- Normal streaming (no timeout)
- Stale connection (no events for 30s → abort + retry)
- Max retries exceeded → surface error to user

Prompt 2: Fix ESC not fully cancelling (Issue #33949, Root Cause #2)

Find the main processing loop function (the async function that checks a
running guard, processes user input, calls the API, and handles responses).
After the finally block that clears the running guard, there is a check:
if the queue is not empty, it immediately calls the processing function
again and returns — without giving the user control back.

This means when a user presses ESC during a hang, the queued message
auto-starts instead of returning to the prompt.

Fix: When the abort was user-initiated (ESC), clear the queue entirely
before checking it. Do NOT auto-restart queued messages after user abort.
The queue auto-restart should only happen after successful completion,
not after abort.

Create a todo list before starting. Write tests for:
- ESC during normal processing → returns to prompt, queue cleared
- ESC during hang → same behavior
- Successful completion with queued messages → auto-restart OK

Prompt 3: Fix JSONL writer race condition (Issue #6836 root cause)

Find the session JSONL writer class that has an insertMessageChain() method.
It currently writes messages one at a time in a for loop — each message is
a separate appendEntry() call. If the process is interrupted between writing
tool_use and tool_result, the tool_use becomes orphaned.

Fix: Serialize the entire message chain into a single string
(messages.map(JSON.stringify).join('\n') + '\n') and write it in one
appendToFile() call. This makes the write atomic at the OS level.

Also check if proper-lockfile (already used for history.jsonl) should be
applied to session JSONL files for concurrent agent writes.

Create a todo list before starting. Write tests for:
- Single message write (baseline)
- Chain write (tool_use + tool_result) — verify both present in file
- Simulated interruption mid-chain — verify no partial writes
- Concurrent writes from 2 agents — verify no corruption

Prompt 4: Audit the entire codebase for the same classes of bugs

You just fixed 3 specific bugs: missing streaming timeout, queue auto-restart
after ESC, and non-atomic JSONL writes. Now audit the ENTIRE codebase for
the same patterns — these bugs are symptoms of systemic problems, not one-offs.

Search and fix ALL instances of:

1. NETWORK CALLS WITHOUT TIMEOUT: Find every HTTP request, SSE stream,
   WebSocket connection, and fetch() call. Every single one must have:
   - A client-side timeout (30s for streams, 10s for REST calls)
   - An AbortController signal
   - Error recovery (retry with backoff or surface error to user)
   List every call you find and its current timeout status.

2. NON-ATOMIC FILE WRITES: Find every place where multiple related records
   are written to a file sequentially (for loops writing to JSONL, multiple
   appendFile calls for related data). Each must be converted to a single
   write operation. Also check for write-then-rename atomic patterns —
   config files (.claude.json, settings.json) should use write-to-tmp +
   rename, not direct overwrite.

3. USER ABORT NOT FULLY HONORED: Find every AbortController/abort() handler
   and every catch block that handles AbortError. Verify that after abort:
   - No background work continues
   - No queued tasks auto-restart
   - All resources (connections, file handles, timers) are cleaned up
   - Control returns to the user prompt

4. CONCURRENT ACCESS WITHOUT LOCKING: Find every file that can be written
   by multiple processes simultaneously (session files, config files,
   history). Each must have proper file locking (proper-lockfile or OS-level).

Create a todo list of every instance found. Fix each one. This is not
optional — these are the root causes of 150+ bug reports.

Prompt 5: Write enterprise-grade regression tests for core workflow

The core workflow (submit → stream → tools → result → cancel) is the #1
priority. It must NEVER regress. Write a comprehensive test suite that
runs on every CI build and blocks releases if any test fails.

## Test Suite: Core Workflow Reliability

### 1. Streaming Tests
- test_stream_completes_normally
- test_stream_timeout_triggers_after_30s_silence
- test_stream_timeout_retries_with_backoff
- test_stream_max_retries_surfaces_error
- test_stream_recovers_after_network_reconnect
- test_stream_abort_cleans_up_all_resources
- test_stream_handles_malformed_sse_events
- test_stream_handles_partial_json_chunks
- test_concurrent_streams_independent (multiple agents)

### 2. ESC / Abort Tests
- test_esc_during_streaming_returns_to_prompt
- test_esc_during_tool_execution_returns_to_prompt
- test_esc_clears_message_queue
- test_esc_does_not_auto_restart_queued_messages
- test_esc_aborts_all_pending_network_calls
- test_esc_closes_all_file_handles
- test_esc_stops_all_timers
- test_double_esc_is_safe (no double-free, no crash)
- test_esc_during_file_write_does_not_corrupt

### 3. Data Integrity Tests
- test_tool_use_always_paired_with_tool_result
- test_message_chain_write_is_atomic
- test_interrupted_chain_write_no_partial_data
- test_concurrent_session_writes_no_corruption
- test_config_write_is_atomic (write-tmp-rename pattern)
- test_session_file_valid_jsonl_after_abort
- test_session_file_valid_jsonl_after_crash (kill -9)
- test_no_orphaned_tool_use_after_100_rapid_esc_presses

### 4. Resource Cleanup Tests
- test_no_leaked_file_handles_after_session
- test_no_leaked_timers_after_abort
- test_no_leaked_connections_after_timeout
- test_no_temp_files_left_after_session (.node leak)
- test_disk_full_graceful_degradation
- test_disk_full_no_config_corruption

### 5. Regression Guards (one test per historical bug)
- test_regression_6836_no_orphaned_tool_results
- test_regression_26224_no_indefinite_hang
- test_regression_20171_no_phantom_generating
- test_regression_24688_no_frozen_terminal
- test_regression_25979_no_stale_connection_hang
- test_regression_33949_esc_fully_cancels

Each test must have a clear description of WHAT it tests and WHY (link to
the original issue). Tests must be fast (mock network where needed) and
deterministic. No flaky tests allowed — if it's flaky, the underlying
code is buggy.

Add a CI gate: if ANY of these tests fail, the release is blocked.
No exceptions. No "we'll fix it next sprint."

Prompt 6: Deep codebase health audit and professional report

Conduct a thorough, systematic audit of the entire Claude Code codebase.
You are acting as a senior staff engineer performing a code health review
before a critical production release. Do not rush. Be methodical.

## Phase 1: Architecture Review

Map the full architecture:
- Entry point → CLI parser → prompt handler → API client → streaming →
  tool execution → response rendering → session persistence
- Draw the data flow diagram (in Mermaid or ASCII)
- Identify all shared mutable state (globals, singletons, module-level vars)
- Identify all concurrency patterns (async/await, parallel tool calls,
  multiple agent instances, background tasks)
- List every external dependency and its purpose

## Phase 2: Reliability Audit

For each component in the data flow, answer:
1. What happens if it hangs? Is there a timeout?
2. What happens if it throws? Is the error caught and handled?
3. What happens if ESC is pressed mid-operation? Are resources cleaned up?
4. What happens if disk is full? Does it degrade or corrupt?
5. What happens if 2 instances run simultaneously? Is there locking?
6. What happens if the network drops mid-operation? Detection? Recovery?

Score each component: GREEN (solid), YELLOW (risks), RED (known broken).

## Phase 3: Error Handling Review

- Find every try/catch block. Is the error logged? Re-thrown? Swallowed?
- Find every .catch() on promises. Are rejections handled or silenced?
- Find every fire-and-forget async call (no await, no .catch). List them all.
- Check: can an unhandled rejection crash the process silently?

## Phase 4: State Management Review

- Map all files written during a session (.claude.json, session JSONL,
  history.jsonl, settings.json, debug logs)
- For each: write pattern (atomic?), locking (concurrent safe?),
  corruption recovery (what if file is half-written?)
- Check: what happens if .claude.json is corrupted on startup?
- Check: what happens if session JSONL has invalid JSON on a line?

## Phase 5: Generate Professional Report

Write a report to docs/CODE_HEALTH_REPORT.md with:

### Executive Summary
- Overall health score (RED / YELLOW / GREEN)
- Top 5 critical risks ranked by user impact
- Estimated effort to fix each

### Component Health Matrix
| Component | Timeout | Error Handling | Abort Safety | Concurrency | Disk Safety | Score |
|-----------|---------|---------------|--------------|-------------|-------------|-------|
| Streaming |   ...   |      ...      |     ...      |     ...     |     ...     |  ...  |
| ...       |   ...   |      ...      |     ...      |     ...     |     ...     |  ...  |

### Critical Findings (RED)
For each: description, code location, user impact, fix proposal, effort estimate

### Warnings (YELLOW)
Same format

### Recommended Fix Order
Numbered checklist with dependencies:
- [ ] 1. Fix X (blocks #2, #3)
- [ ] 2. Fix Y (depends on #1)
- [ ] 3. ...

### Regression Prevention Plan
- What CI checks to add
- What monitoring to add
- What CLAUDE.md rules to add

This report becomes the roadmap. No new features until all RED items
are fixed and tested.

---

Total estimated time: ~6 hours of Claude Code work. These bugs have been open for 6+ months with 150+ community reports.

We've done the hard part — reverse-engineered the minified cli.js across 12 npm versions, analyzed 1,571 sessions with 148,444 tool calls, and identified exact code locations. The prompts above are based on that analysis (full details in #33949).

If Claude Code writes 100% of itself and Boris hasn't "edited a single line by hand since November" — then surely these prompts are all that's needed. Just copy, paste, and ship it — properly this time.

[jviotti]

@kolkov Did you find any workaround while this gets fixed? The hangs get more common and are extremely disruptive...

[kolkov]

@jviotti The only workaround we have:

1. Watch the timer — if you see 0 tokens and 15+ seconds of silence, it's hung. Don't wait, press ESC immediately
2. Don't type new prompts while it's hung — they go into the queue and auto-start after ESC (that's root cause I want to use openrouter #2)
3. ESC → re-submit — this creates a new SSE connection which usually works right away

Basically, you have to babysit it. That's why we reverse-engineered the source and posted the fix proposals — there's no real solution until they add a streaming timeout.

Meanwhile, v2.1.75 just dropped — you can try it, but don't get your hopes up. The changelog has a new prompt bar color command, session name display, and memory file timestamps... but zero fixes for streaming hangs, ESC queue auto-restart, or orphaned tool calls. Priorities.

[bperry0xff]

I've been excessively experiencing this exact issue today. I am on v2.1.75.