refactor: inject process handles so tests never mutate the global process (#183)

[debugmcpdev]

Fixes #183.

What

The proper fix behind the #159 CI flake: production code no longer hardwires the global process, so tests no longer have to mutate it to drive the code under test. With the offenders gone, the #184 leak guard is promoted from lenient to enforcing: CI now runs with LEAK_GUARD_STRICT=1.

New abstraction

• ProcessLike (src/interfaces/process-interfaces.ts) — minimal current-process surface (on/removeListener/listeners/rawListeners/listenerCount/exit/send?/connected/env/argv/uptime/stdin/stdout). Hand-rolled rather than Pick<NodeJS.Process, ...>: the exact Node types (tty stream intersections, never-returning exit, per-event listener overloads) make fakes unimplementable. Structurally satisfied by both the global process and the new EventEmitter-backed FakeCurrentProcess test fake (tests/test-utils/mocks/fake-current-process.ts).

Injection sites (all default to the global process — production behavior unchanged, entry files untouched)

• ProxyRunner (ProxyRunnerOptions.proc): all ~20 touchpoints — IPC mode detection, heartbeat interval, 10s init timeout, message/disconnect/error listeners, readline stdio, and the setupGlobalErrorHandlers method. The worker exit hook is threaded as (code) => this.proc.exit(code) (identical to the worker's own default in prod).
• detectExecutionMode(proc?), createProductionDependencies(proc?) (messageSender IPC/stdout channel).
• CLI commands (stdio, http, sse, error-handlers): proc?: ProcessLike in each dependencies object; signal registration, env gates, exit diagnostics, and the exitProcess default route through it. Stdin watchdog gets env from the handle.
• GenericAdapterManager: constructor-injected platform (win32 tree-kill branch, Ruby launch orphans the debuggee ruby.exe on Windows: worker destroys the DAP socket before sending disconnect, and tree-kill only fires on the slow path #156 heritage).
• Narrow seams where full ProcessLike would be ceremony: SignalFn for pid-liveness (jvm-orphan-reaper, logger stale-log cleanup); platform params on resolveExecutablePath and buildRdbgInvocation.

Deleted

• The standalone setupGlobalErrorHandlers() in dap-proxy-dependencies.ts — dead in production (only its own tests called it) and behaviorally divergent from the ProxyRunner method prod uses (it exited on unhandledRejection; the real one doesn't). Docs updated.
• The CI flake: vitest worker fork exits unexpectedly on windows-latest, failing a fully green suite #159-era test safety nets (top-level process.exit spy nets in dap-proxy-core/worker tests, listener-baseline belt-and-braces) — unreachable now that every runner/worker gets an injected handle.

Deliberate exceptions

• proxy-bootstrap.js untouched (plain-JS pre-TS orphan-prevention layer).
• environment-impl.test.ts keeps its process.cwd spy, documented as the sanctioned boundary test — ProcessEnvironment IS the process abstraction; injecting a fake there is tautological.
• packages/adapter-* platform-redefinition tests (~60 sites, cannot trip the leak guard) deferred to a follow-up issue to keep this reviewable.

Verification

• Key checkpoint: after the ProxyRunner rewrite, the unmodified old tests still passed (default = global process, byte-identical)
• LEAK_GUARD_STRICT=1 pnpm run test:ci-coverage (same command as CI, both projects) — green, 0 leak messages
• LEAK_GUARD_STRICT=1 FLAKE_RUNS=3 pnpm run test:flake — 3/3 shuffled runs green
• E2E smoke (python 5 tests, javascript 3 tests) — real proxy spawn over the default path
• Acceptance greps: no process.on = reassignment, no delete process.send/defineProperty(process, ...), no vi.spyOn(process, 'exit'|'kill'|'on') in migrated suites; dap-proxy-core.ts touches the global only in its two = process defaults
• npm run lint clean

New convenience script: pnpm run test:strict (strict guard locally; default local runs stay lenient).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.40260% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/proxy/dap-proxy-core.ts	93.75%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!