fix(#493): make the proxy-init timeout say what actually stalled - #509
Merged
Conversation
The 30s init-timeout message — "the debug adapter failed to start or is not properly configured; check that it is installed" — was written for the nothing-ever-connected case and was confidently wrong for every other stage. In #492's incident the adapter spawned, opened its socket, accepted the connection, and emitted a DAP event; the one missing thing was a response frame, and the one diagnostic fact that names it (which handshake request is outstanding) was known worker-side and discarded. For an agent that is worse than unhelpful: it is a directed wrong lead. The worker now reports init progress over the existing status IPC: adapter_spawned {pid} and dap_handshake_stage {transport_connected | request_pending | response_received, command} around each blocking handshake request (initialize/launch/attach). Both statuses are handled imperatively only — deliberately no dap-core case, following the adapter_capabilities convention, so nothing is double-processed and the js-debug launch barrier is untouched ('adapter_connected' keeps its unblock semantics; the new status names avoid it on purpose). ProxyManager tracks the progress and the timeout message now reflects the reached stage, keeping the first sentence invariant (tests pin it, docs quote it): connected + request outstanding names the request and the live adapter PID and says "protocol stall, not a missing install"; spawned-but-never-connected and connected-but-idle get their own wording; the install hint survives only for no-progress. The structured facts ride on the Error object and land in the failed start_debugging result's data ({initProgress, proxyLogPath}) — previously they were logged server-side where the agent reading the error can't see them. Fixes #493 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
debugmcpdev
added a commit
that referenced
this pull request
Aug 27, 2026
…#510) Self-debugging RCA writeup of the #492 Ruby launch stall: the incident log, why #470's decoder paths were ruled out, mcp-debugger stepping through its own compiled MinimalDapClient (statement breakpoints in dist/, evaluate_expression against pendingRequests, the stack of the event-delivery moment), the fake-rdbg replay with its DAP trace, the rdbg 1.11.0 source analysis (silent `if sock = @sock` drop guard, unsynchronized cleanup_reader) with the seq discriminator for the next live capture, and what #507/#509 changed. Honest about proven vs. hypothesized. Also: troubleshooting gains a section decoding the stage-aware 30s init-timeout message (post-#493), the ruby guide's troubleshooting table maps the new recovery warning to the case study, and the README documentation index links it. Co-authored-by: JF <john.franklin@gmail.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The 30s init-timeout message — "the debug adapter failed to start or is not properly configured; check that it is installed" — was written for the nothing-ever-connected case and is confidently wrong for every other stage. In #492's incident the adapter spawned, connected, and emitted a DAP event; the one diagnostic fact that mattered (which handshake request is outstanding) was known worker-side and discarded. For an agent this is a directed wrong lead: it verifies
rdbg --version, finds it healthy, and has nowhere to go.Changes
adapter_spawned {pid}after spawn, anddap_handshake_stage {stage: transport_connected | request_pending | response_received, command}around each blocking init request (initialize/launch/attach — all four flow variants). Handled imperatively only, deliberately no dap-core case (theadapter_capabilitiesconvention) so nothing is double-processed; the new names deliberately avoidadapter_connected, whose handler unblocks the js-debug queueing handshake.ErrorMessages.proxyInitTimeout(timeout, progress?)keeping the first sentence invariant (pinned by existing tests, quoted in docs):initProgress; the failedstart_debuggingresult now includesdata: { initProgress, proxyLogPath }(previously these were only server-side logs), following the existing MSVC-branchdataprecedent.Tests
error-messages.test.ts).initProgress; answered requests no longer read as pending; the existing no-progress timeout tests pass unchanged (they simulateinit_receivedprogress and pin the invariant sentence).spawned → transport_connected → initialize pending/received → launch pending/received).Pairs with #507 (#492's recovery): a fully-wedged adapter that also withholds the launch response still times out — and now the message names the launch request instead of blaming the install.
Fixes #493
🤖 Generated with Claude Code