fix: report pending success instead of failing when step/pause outlives grace window

[debugmcpdev]

Problem

step_over/step_into/step_out and pause_execution blocked on the stopped DAP event with a hardcoded 5s deadline and returned a spurious success:false ("Step operation did not complete within 5s") when the debuggee was simply still executing — e.g. stepping over a long-running call, or pausing a target blocked in native code. The eventual stop was then absorbed silently by the background listener, so the user was told the step failed and the session later flipped to paused with no report. This was previously observed in real use (docs/archive/MCP_DEBUGGER_COMPREHENSIVE_TEST_RESULTS.md).

These timeouts imposed a fixed requirement on debuggee runtime behavior; they existed to keep the wait finite, not because a slow step is an error.

Fix — truthful async semantics

Mirror how continue_execution already works (ack now, stop reported asynchronously):

• Keep a short grace wait (fast steps still return the new location synchronously). On expiry, return success:true, state:"running", pending:true with a message explaining the session becomes paused when the operation completes — the persistent handleStopped listener (which has no timeout) already handles that transition.
• Extract the 5000 literals into protected stepGraceMs/pauseGraceMs fields (test-shrinkable), matching the existing attach* field pattern.
• Replace ErrorMessages.stepTimeout/pauseTimeout with informational stepStillRunning/pausePending factories.
• Surface pending:true and the truthful message in the step tool response instead of an unconditional "Stepped over".
• Document the blocking contract in the step_*/continue_execution/pause_execution tool descriptions so LLM clients know a pending step is not a failure.
• Update the pattern docs (docs/patterns/error-handling.md, event-management.md) to show the grace-window pattern.

Testing

• Updated the tests that pinned the old failure behavior; added a test pinning the async completion path (late stopped → PAUSED).
• Full unit suite (2354) + integration pass; lint clean.
• Verified live end-to-end: stepping over a time.sleep(15) in a Python session returns the pending success after ~5s (previously a spurious failure), the session flips to paused at the post-sleep line when the sleep ends, and a trivial step still returns immediately with location/context.

Follow-ups filed from the same audit

• evaluate_expression can spuriously time out on long-running expressions #142 — evaluate_expression can spuriously time out on long-running expressions (uniform 35s/30s/30s request timeouts across three layers)
• Attach thread-verification window (5s) hard-fails slow targets #143 — attach thread-verification window (5s) hard-fails slow targets

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!