Debugger (src/main/debug, ipc/debug.ts)

Generic over the Debug Adapter Protocol, built like LSP (lsp skill): adapters are external processes owned per workspace view, their output is untrusted and normalized at the boundary, every request has a deadline.

Modules

ipc/debug.ts is wiring only (channels, argument validation, delegation); the manager of a view lives in debug/registry.ts (debugManagerOf(wc), ensureDebugManager(wc), killAllDebug() for will-quit, debugRunCommand for the terminal source).

Rules

• Ownership: one manager per view (createViewRegistry, key debug); a view reset disposes it (short graceful stop, then kill), a folder change calls resetForFolder (stops the sessions, forgets the breakpoints), will-quit calls killAllDebug (the adapters are spawnGroup processes, so killAllSpawnedGroups also sweeps them).
• debug.adapters is user-only (it runs programs): validated by isValidDebugAdapter in shared/settings.ts (command like terminal.shell, tcp requires ${port} in args, env like claude.env). The executable is resolved with resolveExecutable on the login-shell PATH (effectivePath), env through buildChildEnv.
• Timeouts (DAP_TIMEOUTS): initialize 15 s, launch/attach 60 s, requests 10 s, evaluate 15 s, terminate/ disconnect 3 s. Never await a DAP request without one.
• The launch response is not awaited before initialized: debugpy answers launch only after configurationDone. Some adapters send initialized after the launch response: wait lateInitialized (2 s) for it before configuring.
• Breakpoints: the renderer is the source of truth (persisted in the workspace session) and sends the whole list of a file with debug.setBreakpoints (only enabled ones). The manager keeps the map, sends it in configure and to every live session on change (initializedSeen, so a change during configure is not lost). Statuses go back as the breakpoints event aligned with the request order; breakpoint events are mapped by the ids of the last response. Conditions/hit counts/log messages are dropped when the adapter did not announce support.
• Synthetic continued: adapters do not send continued for client requests, so control emits one after a successful continue/next/stepIn/stepOut (and restartInAdapter too). The renderer handles continued uniformly.
• Failure surfaces: a failure during start rejects the debug:start invoke (the adapter's spawn error or crash, with the last stderr line, wins over the generic communication error) and emits no error event; after start, an adapter crash or a broken channel emits { kind: 'error' } (translated) and the sessions vanish from the list.
• runInTerminal: the manager stores a one-shot ticket (15 s) and emits { kind: 'runInTerminal', ticket }; the renderer calls terminal.create({ debugRun: ticket }); terminal/create.ts asks the debugRun terminal source (registered by ipc/debug.ts), which takes the ticket and runs args[0] with the rest (no shell), the adapter's cwd and env; onSpawned(pid) answers the adapter with processId. The command never comes from the renderer.
• startDebugging (js-debug): only over tcp (a new socket to the same server per child); the child gets parentId, ends with its root, and stop of any session stops the whole tree (children first).
• Text sent to the adapter (reverse request refusals) is English; everything shown to the user goes through t().debug (main) or t().debugUi (renderer).
• preLaunchTask/postDebugTask are not run: a note goes to the Debug Console. ${command:…}, ${input:…} and ${config:…} throw a translated error.

Testing

• manager.test.ts uses a FakeAdapter (two PassThrough streams + createDapParser) that answers like debugpy (initialized right after launch, launch response after configurationDone); tcp: true gives a new adapter per connect for child sessions. Real adapters are not part of the suite (debugpy/js-debug are not dependencies).

Renderer

• State: types/debug.ts / state/debug.ts (scoped per folder). Actions: debugActions.ts (sessions, events from api.debug.onEvent, focused session/frame, watches, console, the inDebugMode context) and debugBreakpointActions.ts (breakpoints per path, pushed with debug.setBreakpoints and saved in the session). Pure logic in lib/debugBreakpoints.ts, lib/debugConsole.ts, lib/debugSessions.ts.
• UI: components/debug/ (DebugView + DebugSections in the sidebar, DebugToolbar floating in .main, DebugConsole as the debugConsole bottom-panel view), styles in styles/debug.css.
• Editor: components/editor/breakpointGutter.ts (gutter marks that follow edits, inline condition widget, stopped line highlight), added to both extensionsFor and createMirror; it reaches the store only through components/editor/debugHost.ts (bindDebugHost), like lspHost.ts.
• Commands act on the focused session: the one of the last stopped event, else the newest live leaf session.