Fix: Workaround for process stream hanging after completion (Issue #1280)

[konard]

Summary

This PR addresses issue #1280 where the solve command using --tool claude gets stuck after successful completion, requiring manual CTRL+C to terminate.

Root Cause

The hang is caused by command-stream v0.9.4's stream() async iterator behavior:

1. stream() waits for both process exit AND stdout/stderr pipe close before ending
2. If the CLI process keeps stdout open after sending the result event, pumpReadable() hangs indefinitely
3. finish() never fires → 'end' event never emitted → for await loop never terminates
4. Additionally, stream() does NOT yield {type:'exit'} chunks, making exit code detection via chunk.type === 'exit' dead code in 6 source files

This is NOT a Claude CLI bug — the lines "Cost captured" and "Captured result summary" are printed by our code inside the for await loop after the result event arrives. The hang occurs when command-stream's stream() iterator doesn't terminate because the underlying process keeps stdout open.

Evidence from logs — 5 min 26 sec gap after result event:

Timestamp	Event
21:10:17.168Z	Result event received (success)
21:10:17.169Z	Cost captured, result summary processed
5 min 26 sec	for await loop stuck in command-stream stream()
21:15:43.123Z	User interrupted with CTRL+C (exit code 130)

Solution

Implemented a configurable timeout workaround in src/claude.lib.mjs:

1. Track when the result event is received
2. Start a timeout (default 30s, configurable via HIVE_MIND_RESULT_STREAM_CLOSE_MS)
3. If the stream doesn't close within that time:
   • Send SIGTERM to the process
   • Wait 2 seconds
   • Send SIGKILL if still running
4. Added detailed verbose logging with timestamps for debugging

Additional Changes

• Added timeouts.resultStreamCloseMs to src/config.lib.mjs (configurable via env var)
• Added comments documenting command-stream chunk.type === 'exit' dead code
• Updated case study in docs/case-studies/issue-1280/ANALYSIS.md with corrected root cause
• Updated changeset with accurate description

Upstream Bug Reports

• Filed on command-stream: stream() async iterator does not yield exit chunks and can hang if process stdout stays open link-foundation/command-stream#155
  • stream() does not yield exit chunks
  • stream() hangs if stdout stays open after process exit
• Previously filed on Claude Code: [BUG] Claude Code CLI hangs indefinitely after sending result event in stream-json mode anthropics/claude-code#25629

Files Changed

• src/claude.lib.mjs — Timeout workaround + dead code documentation
• src/config.lib.mjs — Added resultStreamCloseMs timeout config
• .changeset/issue-1280-claude-cli-hang-workaround.md — Updated changeset
• docs/case-studies/issue-1280/ANALYSIS.md — Corrected root cause analysis

Testing

• All unit tests pass
• Linting passes (eslint)
• Formatting passes (prettier)
• Syntax validation passes
• File line count under 1500 limit (1466 lines)

Issue Reference

Fixes #1280

---

This PR was created by the AI issue solver

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $15.594683
• Calculated by Anthropic: $10.381832 USD
• Difference: $-5.212851 (-33.43%)
  📎 Log file uploaded as Gist (4043KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

I don't believe it is the problem with claude command, instead I think

}
💰 Anthropic official cost captured from success result: $1.917418
📝 Captured result summary from Claude output

That indicates, that is our solve command code is hanging. Because these lines are added after claude command is executed, and if not, just make sure we don't mix the output, and do our output only after claude command is finished, so there will be clear distinction and border of responsibilities.

Please double check our recent releases. Captured result summary from Claude output was added not long ago. If we need to add more debug data in --verbose mode just do it.

Anyway we should apply workaround to successfully terminate claude command if we got final result summary, but not the result code of the command. If we are using command-stream or other function to execute claude command, double check that this library does not have the problem. Anyway if possible try to reproduce it. And add all necessary debug output as we do it in --verbose mode, and also do all nessesary workaround. And double check our latest code changes, may be we broke something there.

Ensure all changes are correct, consistent, validated, tested and fully meet all discussed requirements (check issue description and all comments in issue and in pull request). Ensure all CI/CD checks pass.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-02-13T21:51:04.900Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $9.101580
• Calculated by Anthropic: $6.904549 USD
• Difference: $-2.197031 (-24.14%)
  📎 Log file uploaded as Gist (1670KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.