Refactor DAP attach: transport + connector strategies (replaces #10)

[waltoss]

Summary

• Replaces #10 with a design that separates transport (stdio vs TCP) from provisioning (spawn adapter vs attach to running server), eliminating the useTcpAttach boolean and the dual-mode DapClient.
• Collapses DapSession.launch and DapSession.attach into a single runHandshake() template; the debugpy-fires-initialized-during-initialize race is now fixed structurally (listener armed before the initialize request is sent) instead of via a separate _initializedPromise field.
• Adds a RED→GREEN integration test that spawns python -m debugpy --listen <port> --wait-for-client, attaches, and verifies a breakpoint hits inside the running loop.

Why reject #10 as-is

#10 is right about the bug but the fix bolted a second mode onto DapClient:

• proc: Subprocess | null + tcpSocket: net.Socket | null with if (this.tcpSocket) ... else if (this.proc) branches in the constructor, writeMessage, and disconnect.
• get pid() returns 0 for TCP (a lie — should be "no pid").
• DapSession.attach() forks into two near-duplicated attach sequences switched on config.useTcpAttach.
• The useTcpAttach boolean collapses two orthogonal concerns — transport vs provisioning — onto one axis.

Design

Two small interfaces, each with two implementations today:

DapTransport  (interface)         ← axis 1: wire
  ├── StdioTransport(subprocess)
  └── TcpTransport(socket)

DapConnector  (interface)         ← axis 2: provisioning
  ├── SpawnAdapterConnector(cmd)        → returns StdioTransport
  └── TcpAttachConnector(host, port)    → returns TcpTransport

DapRuntimeConfig
  launch(input):  DapConnectPlan
  attach?(target): DapConnectPlan       // undefined = no attach support

DapClient(transport)              ← no more nullables, no branched I/O
DapSession.runHandshake(plan, \"launch\"|\"attach\", args)   ← single handshake

debugpyConfig.attach() returns TcpAttachConnector(host, port) — exactly PR #10's behaviour, but declarative. javaConfig.attach() keeps SpawnAdapterConnector (the java adapter bridges DAP→JDWP). Adding Go (delve, TCP) or Ruby (rdbg, both) is now a config-file change.

RED → GREEN

New test: tests/integration/python/python-attach.test.ts

• RED (pre-refactor main): times out with `this test timed out after 15000ms`. Pre-refactor `DapSession.attach("64596", "debugpy")` spawned `debugpy.adapter` and sent `{ pid: 64596 }` — there's no such pid, so the adapter hangs waiting.
• GREEN (this PR): passes in ~6s (1 pass / 0 fail).

Two subtleties worth calling out

• `python -m debugpy --listen --wait-for-client` treats the first TCP connection as THE client. You can't probe-connect to check readiness — the test watches debugpy's stderr for its "waiting for client" message instead.
• `DapSession.waitUntilStopped()` doesn't fetch the stack when a waiter is set (the `stopped` handler skips the eager fetch, expecting the caller to do it). The test uses `buildState({ stack: true })` which calls `ensureStack()`.

Test plan

• `bun run typecheck` clean
• `bun run lint` clean
• `bun test tests/integration/python/` — 17 pass / 0 fail (includes the new attach test)
• `bun test` — 576 pass / 0 fail on a clean run (full suite is flaky across repeated invocations when leftover debugger processes accumulate, unrelated to this change)
• RED verified against pre-refactor main (test times out)

🤖 Generated with Claude Code