@kr78/pi-coding-agent 17.2.10

package/src/dap/session.ts

@@ -0,0 +1,1841 @@
+import * as path from "node:path";
+import * as timers from "node:timers/promises";
+import { logger, ptree, untilAborted } from "@oh-my-pi/pi-utils";
+import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
+import { DapClient } from "./client";
+import type {
+	DapAttachArguments,
+	DapAttachSessionOptions,
+	DapBreakpoint,
+	DapBreakpointRecord,
+	DapCapabilities,
+	DapContinueArguments,
+	DapContinueOutcome,
+	DapContinueResponse,
+	DapDataBreakpoint,
+	DapDataBreakpointInfoArguments,
+	DapDataBreakpointInfoResponse,
+	DapDataBreakpointRecord,
+	DapDisassembleArguments,
+	DapDisassembledInstruction,
+	DapDisassembleResponse,
+	DapEvaluateArguments,
+	DapEvaluateResponse,
+	DapExitedEventBody,
+	DapFunctionBreakpoint,
+	DapFunctionBreakpointRecord,
+	DapInitializeArguments,
+	DapInstructionBreakpoint,
+	DapInstructionBreakpointRecord,
+	DapLaunchArguments,
+	DapLaunchSessionOptions,
+	DapLoadedSourcesResponse,
+	DapModule,
+	DapModulesArguments,
+	DapModulesResponse,
+	DapOutputEventBody,
+	DapPauseArguments,
+	DapReadMemoryArguments,
+	DapReadMemoryResponse,
+	DapResolvedAdapter,
+	DapRunInTerminalArguments,
+	DapRunInTerminalResponse,
+	DapScopesArguments,
+	DapScopesResponse,
+	DapSessionStatus,
+	DapSessionSummary,
+	DapSetDataBreakpointsArguments,
+	DapSetInstructionBreakpointsArguments,
+	DapSource,
+	DapSourceBreakpoint,
+	DapStackFrame,
+	DapStackTraceArguments,
+	DapStackTraceResponse,
+	DapStartDebuggingArguments,
+	DapStepArguments,
+	DapStopLocation,
+	DapStoppedEventBody,
+	DapThread,
+	DapThreadsResponse,
+	DapVariablesArguments,
+	DapVariablesResponse,
+	DapWriteMemoryArguments,
+	DapWriteMemoryResponse,
+} from "./types";
+
+interface DapSession {
+	id: string;
+	adapter: DapResolvedAdapter;
+	cwd: string;
+	program?: string;
+	client: DapClient;
+	status: DapSessionStatus;
+	launchedAt: number;
+	lastUsedAt: number;
+	breakpoints: Map<string, DapBreakpointRecord[]>;
+	functionBreakpoints: DapFunctionBreakpointRecord[];
+	instructionBreakpoints: DapInstructionBreakpoint[];
+	dataBreakpoints: DapDataBreakpoint[];
+	/** Serializes breakpoint mutations — see #serializeBreakpointMutation. */
+	breakpointMutationQueue: Promise<void>;
+	/** Recent output chunks; trimmed from the front when over MAX_OUTPUT_BYTES. */
+	outputChunks: string[];
+	/** Cumulative bytes of output ever received (reported in summaries). */
+	outputBytes: number;
+	/** Bytes currently buffered in outputChunks. */
+	outputBufferedBytes: number;
+	outputTruncated: boolean;
+	stop: DapStopLocation;
+	threads: DapThread[];
+	lastStackFrames: DapStackFrame[];
+	exitCode?: number;
+	capabilities?: DapCapabilities;
+	initializedSeen: boolean;
+	needsConfigurationDone: boolean;
+	configurationDoneSent: boolean;
+	parentSessionId?: string;
+	childSessionIds: Set<string>;
+	port?: number;
+}
+
+interface DapTreeOutcomeWaiter {
+	rootSessionId: string;
+	resolve(value: unknown): void;
+	reject(reason: unknown): void;
+}
+
+export interface DapOutputSnapshot {
+	snapshot: DapSessionSummary;
+	output: string;
+}
+
+const IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+const CLEANUP_INTERVAL_MS = 30 * 1000;
+const HEARTBEAT_INTERVAL_MS = 5 * 1000;
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const STOP_CAPTURE_TIMEOUT_MS = 5_000;
+
+function toErrorMessage(value: unknown): string {
+	if (value instanceof Error) return value.message;
+	return String(value);
+}
+
+interface DapStartRequestFailure {
+	rejected: boolean;
+	error?: unknown;
+	/**
+	 * Resolves (never rejects) when the underlying launch/attach request
+	 * settles either way. Set by {@link trackDapStartRequest} on each call,
+	 * so a single failure object must not be reused across launch attempts.
+	 * Consumed by {@link throwPreferredDapStartError} to bound how long to
+	 * wait for a delayed adapter-side rejection before falling back to the
+	 * cascade error from configurationDone.
+	 */
+	settled?: Promise<void>;
+}
+
+function trackDapStartRequest<T>(promise: Promise<T>, failure: DapStartRequestFailure): Promise<T> {
+	const tracked = promise.catch(error => {
+		failure.rejected = true;
+		failure.error = error;
+		throw error;
+	});
+	failure.settled = tracked.then(
+		() => {},
+		() => {},
+	);
+	return tracked;
+}
+
+function combineDapStartErrors(command: "launch" | "attach", startError: unknown, configurationError: unknown): Error {
+	const startMessage = toErrorMessage(startError);
+	const configurationMessage = toErrorMessage(configurationError);
+	if (startMessage === configurationMessage) {
+		return startError instanceof Error ? startError : new Error(startMessage);
+	}
+	return new Error(
+		`DAP ${command} failed: ${startMessage}\nDAP configurationDone also failed: ${configurationMessage}`,
+	);
+}
+
+async function throwPreferredDapStartError(
+	command: "launch" | "attach",
+	startFailure: DapStartRequestFailure,
+	configurationError: unknown,
+): Promise<never> {
+	await Promise.race([startFailure.settled ?? Promise.resolve(), timers.setTimeout(50)]);
+	if (startFailure.rejected) {
+		throw combineDapStartErrors(command, startFailure.error, configurationError);
+	}
+	throw configurationError;
+}
+
+const DEBUGPY_MISSING_MODULE_RE = /No module named ['"]?debugpy['"]?/;
+
+/**
+ * Map a generic adapter-side failure into the targeted `pip install debugpy`
+ * hint when the adapter is debugpy and stderr/the wrapping error mentions
+ * the missing module. Returns null when the heuristic does not apply, so the
+ * caller can rethrow the original error untouched.
+ */
+function mapDebugpyMissingModule(adapterName: string, error: unknown): Error | null {
+	if (adapterName !== "debugpy") return null;
+	if (!DEBUGPY_MISSING_MODULE_RE.test(toErrorMessage(error))) return null;
+	return new Error("adapter 'debugpy' is not available: install with 'pip install debugpy'");
+}
+
+function normalizePath(filePath: string): string {
+	return path.resolve(filePath);
+}
+
+function truncateOutput(session: DapSession, output: string): void {
+	if (!output) return;
+	const bytes = Buffer.byteLength(output, "utf-8");
+	session.outputChunks.push(output);
+	session.outputBytes += bytes;
+	session.outputBufferedBytes += bytes;
+	// Trim whole chunks from the front, but only while the remainder still
+	// holds a full MAX_OUTPUT_BYTES tail — dropping the front chunk whenever
+	// the total exceeded the cap could retain far less than the cap (e.g.
+	// [120KB, 10KB] would keep only 10KB). Recomputing one big string's byte
+	// length per 1KB trim iteration was O(n^2) inside the event dispatch loop.
+	while (session.outputChunks.length > 1) {
+		const frontBytes = Buffer.byteLength(session.outputChunks[0], "utf-8");
+		if (session.outputBufferedBytes - frontBytes < MAX_OUTPUT_BYTES) break;
+		session.outputChunks.shift();
+		session.outputBufferedBytes -= frontBytes;
+		session.outputTruncated = true;
+	}
+	if (session.outputBufferedBytes > MAX_OUTPUT_BYTES) {
+		// Byte-slice the front chunk's head so exactly the cap remains (a torn
+		// code point at the cut decodes as U+FFFD, acceptable for log output).
+		const front = session.outputChunks[0];
+		const frontBytes = Buffer.byteLength(front, "utf-8");
+		const excess = session.outputBufferedBytes - MAX_OUTPUT_BYTES;
+		const kept = Buffer.from(front, "utf-8").subarray(excess).toString("utf-8");
+		session.outputChunks[0] = kept;
+		session.outputBufferedBytes += Buffer.byteLength(kept, "utf-8") - frontBytes;
+		session.outputTruncated = true;
+	}
+}
+
+function summarizeBreakpointCount(breakpoints: Map<string, DapBreakpointRecord[]>): number {
+	let total = 0;
+	for (const entries of breakpoints.values()) {
+		total += entries.length;
+	}
+	return total;
+}
+
+function buildSummary(session: DapSession): DapSessionSummary {
+	return {
+		id: session.id,
+		adapter: session.adapter.name,
+		cwd: session.cwd,
+		program: session.program,
+		status: session.status,
+		launchedAt: new Date(session.launchedAt).toISOString(),
+		lastUsedAt: new Date(session.lastUsedAt).toISOString(),
+		threadId: session.stop.threadId,
+		frameId: session.stop.frameId,
+		stopReason: session.stop.reason,
+		stopDescription: session.stop.description ?? session.stop.text,
+		frameName: session.stop.frameName,
+		instructionPointerReference: session.stop.instructionPointerReference,
+		source: session.stop.source,
+		line: session.stop.line,
+		column: session.stop.column,
+		breakpointFiles: session.breakpoints.size,
+		breakpointCount: summarizeBreakpointCount(session.breakpoints),
+		functionBreakpointCount: session.functionBreakpoints.length,
+		outputBytes: session.outputBytes,
+		outputTruncated: session.outputTruncated,
+		exitCode: session.exitCode,
+		needsConfigurationDone: session.needsConfigurationDone && !session.configurationDoneSent,
+		parentSessionId: session.parentSessionId,
+		childSessionIds: session.childSessionIds.size > 0 ? [...session.childSessionIds] : undefined,
+	};
+}
+
+export class DapSessionManager {
+	#sessions = new Map<string, DapSession>();
+	#activeSessionId: string | null = null;
+	#cleanupLoopPromise?: Promise<void>;
+	#nextId = 0;
+	#treeOutcomeWaiters = new Set<DapTreeOutcomeWaiter>();
+
+	constructor() {
+		this.#startCleanupTimer();
+	}
+
+	getActiveSession(): DapSessionSummary | null {
+		const session = this.#getActiveSessionOrNull();
+		return session ? buildSummary(session) : null;
+	}
+
+	listSessions(): DapSessionSummary[] {
+		return Array.from(this.#sessions.values()).map(buildSummary);
+	}
+
+	getCapabilities(): DapCapabilities | null {
+		return this.#getActiveSessionOrNull()?.capabilities ?? null;
+	}
+
+	async launch(
+		options: DapLaunchSessionOptions,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<DapSessionSummary> {
+		await this.#ensureLaunchSlot();
+		const client = await DapClient.spawn({ adapter: options.adapter, cwd: options.cwd });
+		const session = this.#registerSession(client, options.adapter, options.cwd, options.program);
+		try {
+			session.capabilities = await client.initialize(
+				this.#buildInitializeArguments(options.adapter),
+				signal,
+				timeoutMs,
+			);
+			session.needsConfigurationDone = session.capabilities.supportsConfigurationDoneRequest === true;
+			const launchArguments: DapLaunchArguments = {
+				...options.adapter.launchDefaults,
+				...(options.extraLaunchArguments ?? {}),
+				program: options.program,
+				cwd: options.cwd,
+				...(options.args !== undefined ? { args: options.args } : {}),
+			};
+			// Subscribe to stop events BEFORE launching so we don't miss
+			// stopOnEntry events that arrive before we start listening.
+			const initialStopPromise = this.#prepareStopOutcome(
+				session,
+				signal,
+				Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS),
+			);
+			// DAP spec: many adapters do not respond to launch until after
+			// configurationDone. Fire launch, complete the config handshake,
+			// then await the launch response.
+			const launchFailure: DapStartRequestFailure = { rejected: false };
+			const launchPromise = trackDapStartRequest(
+				client.sendRequest("launch", launchArguments, signal, timeoutMs),
+				launchFailure,
+			);
+			// Mark handled so a fast error response doesn't become an unhandled
+			// rejection while we await the config handshake. The actual error
+			// still propagates when we await launchPromise below.
+			launchPromise.catch(() => {});
+			try {
+				await this.#completeConfigurationHandshake(session, signal, timeoutMs);
+			} catch (error) {
+				await throwPreferredDapStartError("launch", launchFailure, error);
+			}
+			await launchPromise;
+			// Try to capture initial stopped state (e.g. stopOnEntry).
+			// Timeout is acceptable — the program may simply be running.
+			let resultSession = session;
+			try {
+				await untilAborted(signal, initialStopPromise);
+				const active = this.#getActiveSessionOrNull();
+				if (active && this.#getRootSession(active).id === session.id) {
+					resultSession = active;
+				}
+				if (resultSession.status === "stopped") {
+					await this.#fetchTopFrame(resultSession, signal, Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS));
+				}
+			} catch {
+				if (session.initializedSeen && session.status === "launching") {
+					session.status = session.configurationDoneSent ? "running" : "configuring";
+				}
+			}
+			return buildSummary(resultSession);
+		} catch (error) {
+			await this.#disposeSession(session);
+			const mapped = mapDebugpyMissingModule(options.adapter.name, error);
+			if (mapped) throw mapped;
+			throw error;
+		}
+	}
+
+	async attach(
+		options: DapAttachSessionOptions,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<DapSessionSummary> {
+		await this.#ensureLaunchSlot();
+		const client = await DapClient.spawn({ adapter: options.adapter, cwd: options.cwd });
+		const session = this.#registerSession(client, options.adapter, options.cwd);
+		try {
+			session.capabilities = await client.initialize(
+				this.#buildInitializeArguments(options.adapter),
+				signal,
+				timeoutMs,
+			);
+			session.needsConfigurationDone = session.capabilities.supportsConfigurationDoneRequest === true;
+			const attachArguments: DapAttachArguments = {
+				...options.adapter.attachDefaults,
+				cwd: options.cwd,
+				...(options.pid !== undefined ? { pid: options.pid, processId: options.pid } : {}),
+				...(options.port !== undefined ? { port: options.port } : {}),
+				...(options.host ? { host: options.host } : {}),
+			};
+			const initialStopPromise = this.#prepareStopOutcome(
+				session,
+				signal,
+				Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS),
+			);
+			const attachFailure: DapStartRequestFailure = { rejected: false };
+			const attachPromise = trackDapStartRequest(
+				client.sendRequest("attach", attachArguments, signal, timeoutMs),
+				attachFailure,
+			);
+			attachPromise.catch(() => {});
+			try {
+				await this.#completeConfigurationHandshake(session, signal, timeoutMs);
+			} catch (error) {
+				await throwPreferredDapStartError("attach", attachFailure, error);
+			}
+			await attachPromise;
+			let resultSession = session;
+			try {
+				await untilAborted(signal, initialStopPromise);
+				const active = this.#getActiveSessionOrNull();
+				if (active && this.#getRootSession(active).id === session.id) {
+					resultSession = active;
+				}
+				if (resultSession.status === "stopped") {
+					await this.#fetchTopFrame(resultSession, signal, Math.min(timeoutMs, STOP_CAPTURE_TIMEOUT_MS));
+				}
+			} catch {
+				if (session.initializedSeen && session.status === "launching") {
+					session.status = session.configurationDoneSent ? "running" : "configuring";
+				}
+			}
+			return buildSummary(resultSession);
+		} catch (error) {
+			await this.#disposeSession(session);
+			const mapped = mapDebugpyMissingModule(options.adapter.name, error);
+			if (mapped) throw mapped;
+			throw error;
+		}
+	}
+
+	/**
+	 * Serialize breakpoint mutations per session: every mutator does a
+	 * read-modify-write of session state around an await, and the adapter-side
+	 * set*Breakpoints request replaces the whole list — concurrent mutations
+	 * would silently drop each other's breakpoints on both sides.
+	 */
+	#serializeBreakpointMutation<T>(session: DapSession, mutate: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+		const run = session.breakpointMutationQueue.then(() => {
+			// A mutation can sit behind several queued 30s predecessors; honor a
+			// caller abort at dequeue instead of running a request nobody awaits.
+			if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+			return mutate();
+		});
+		session.breakpointMutationQueue = run.then(
+			() => undefined,
+			() => undefined,
+		);
+		return run;
+	}
+	async #syncBreakpointTree(
+		origin: DapSession,
+		command: string,
+		args: unknown,
+		prepare: (session: DapSession) => void,
+		apply: (session: DapSession, breakpoints: DapBreakpoint[] | undefined) => void,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<void> {
+		const sessions = this.#getTreeSessions(origin).filter(
+			session => session.status !== "terminated" && session.client.isAlive(),
+		);
+		for (const session of sessions) prepare(session);
+		await this.#serializeBreakpointMutation(
+			origin,
+			async () => {
+				const response = await this.#sendRequestWithConfig<{ breakpoints?: DapBreakpoint[] }>(
+					origin,
+					command,
+					args,
+					signal,
+					timeoutMs,
+				);
+				apply(origin, response?.breakpoints);
+			},
+			signal,
+		);
+		await Promise.all(
+			sessions
+				.filter(session => session !== origin)
+				.map(async session => {
+					try {
+						await this.#serializeBreakpointMutation(
+							session,
+							async () => {
+								const response = await this.#sendRequestWithConfig<{ breakpoints?: DapBreakpoint[] }>(
+									session,
+									command,
+									args,
+									signal,
+									timeoutMs,
+								);
+								apply(session, response?.breakpoints);
+							},
+							signal,
+						);
+					} catch (error) {
+						logger.warn("Failed to synchronize breakpoint request with child debug session", {
+							sessionId: session.id,
+							command,
+							error: toErrorMessage(error),
+						});
+					}
+				}),
+		);
+	}
+
+	async setBreakpoint(
+		file: string,
+		line: number,
+		condition?: string,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	) {
+		const session = this.#touchActiveSession();
+		const sourcePath = normalizePath(file);
+		const root = this.#getRootSession(session);
+		const current = [...(root.breakpoints.get(sourcePath) ?? [])].filter(entry => entry.line !== line);
+		current.push({ verified: false, line, condition });
+		current.sort((left, right) => left.line - right.line);
+		const args = {
+			source: { path: sourcePath, name: path.basename(sourcePath) },
+			breakpoints: current.map<DapSourceBreakpoint>(entry => ({
+				line: entry.line,
+				...(entry.condition ? { condition: entry.condition } : {}),
+			})),
+		};
+		await this.#syncBreakpointTree(
+			session,
+			"setBreakpoints",
+			args,
+			target =>
+				target.breakpoints.set(
+					sourcePath,
+					current.map(entry => ({ ...entry, verified: false })),
+				),
+			(target, response) => target.breakpoints.set(sourcePath, this.#mapSourceBreakpoints(current, response)),
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: session.breakpoints.get(sourcePath) ?? [],
+			sourcePath,
+		};
+	}
+
+	async removeBreakpoint(file: string, line: number, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const sourcePath = normalizePath(file);
+		const root = this.#getRootSession(session);
+		const current = [...(root.breakpoints.get(sourcePath) ?? [])].filter(entry => entry.line !== line);
+		const args = {
+			source: { path: sourcePath, name: path.basename(sourcePath) },
+			breakpoints: current.map<DapSourceBreakpoint>(entry => ({
+				line: entry.line,
+				...(entry.condition ? { condition: entry.condition } : {}),
+			})),
+		};
+		const prepare = (target: DapSession) => {
+			if (current.length === 0) target.breakpoints.delete(sourcePath);
+			else
+				target.breakpoints.set(
+					sourcePath,
+					current.map(entry => ({ ...entry, verified: false })),
+				);
+		};
+		await this.#syncBreakpointTree(
+			session,
+			"setBreakpoints",
+			args,
+			prepare,
+			(target, response) => {
+				if (current.length === 0) target.breakpoints.delete(sourcePath);
+				else target.breakpoints.set(sourcePath, this.#mapSourceBreakpoints(current, response));
+			},
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: session.breakpoints.get(sourcePath) ?? [],
+			sourcePath,
+		};
+	}
+
+	async setFunctionBreakpoint(name: string, condition?: string, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).functionBreakpoints.filter(entry => entry.name !== name);
+		current.push({ verified: false, name, condition });
+		current.sort((left, right) => left.name.localeCompare(right.name));
+		const args = {
+			breakpoints: current.map<DapFunctionBreakpoint>(entry => ({
+				name: entry.name,
+				...(entry.condition ? { condition: entry.condition } : {}),
+			})),
+		};
+		await this.#syncBreakpointTree(
+			session,
+			"setFunctionBreakpoints",
+			args,
+			target => {
+				target.functionBreakpoints = current.map(entry => ({ ...entry, verified: false }));
+			},
+			(target, response) => {
+				target.functionBreakpoints = this.#mapFunctionBreakpoints(current, response);
+			},
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), breakpoints: session.functionBreakpoints };
+	}
+
+	async removeFunctionBreakpoint(name: string, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).functionBreakpoints.filter(entry => entry.name !== name);
+		const args = {
+			breakpoints: current.map<DapFunctionBreakpoint>(entry => ({
+				name: entry.name,
+				...(entry.condition ? { condition: entry.condition } : {}),
+			})),
+		};
+		await this.#syncBreakpointTree(
+			session,
+			"setFunctionBreakpoints",
+			args,
+			target => {
+				target.functionBreakpoints = current.map(entry => ({ ...entry, verified: false }));
+			},
+			(target, response) => {
+				target.functionBreakpoints = this.#mapFunctionBreakpoints(current, response);
+			},
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), breakpoints: session.functionBreakpoints };
+	}
+
+	async setInstructionBreakpoint(
+		instructionReference: string,
+		offset?: number,
+		condition?: string,
+		hitCondition?: string,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).instructionBreakpoints.filter(
+			entry => entry.instructionReference !== instructionReference || entry.offset !== offset,
+		);
+		current.push({ instructionReference, offset, condition, hitCondition });
+		current.sort((left, right) => {
+			const referenceOrder = left.instructionReference.localeCompare(right.instructionReference);
+			return referenceOrder !== 0 ? referenceOrder : (left.offset ?? 0) - (right.offset ?? 0);
+		});
+		const args = { breakpoints: current } satisfies DapSetInstructionBreakpointsArguments;
+		let responseBreakpoints: DapBreakpoint[] | undefined;
+		await this.#syncBreakpointTree(
+			session,
+			"setInstructionBreakpoints",
+			args,
+			target => {
+				target.instructionBreakpoints = current.map(entry => ({ ...entry }));
+			},
+			(target, response) => {
+				if (target === session) responseBreakpoints = response;
+			},
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: this.#mapInstructionBreakpoints(current, responseBreakpoints),
+		};
+	}
+
+	async removeInstructionBreakpoint(
+		instructionReference: string,
+		offset?: number,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).instructionBreakpoints.filter(entry => {
+			if (entry.instructionReference !== instructionReference) return true;
+			return offset !== undefined && entry.offset !== offset;
+		});
+		const args = { breakpoints: current } satisfies DapSetInstructionBreakpointsArguments;
+		let responseBreakpoints: DapBreakpoint[] | undefined;
+		await this.#syncBreakpointTree(
+			session,
+			"setInstructionBreakpoints",
+			args,
+			target => {
+				target.instructionBreakpoints = current.map(entry => ({ ...entry }));
+			},
+			(target, response) => {
+				if (target === session) responseBreakpoints = response;
+			},
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: this.#mapInstructionBreakpoints(current, responseBreakpoints),
+		};
+	}
+
+	async dataBreakpointInfo(
+		name: string,
+		variablesReference?: number,
+		frameId?: number,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; info: DapDataBreakpointInfoResponse }> {
+		const session = this.#touchActiveSession();
+		const info = await this.#sendRequestWithConfig<DapDataBreakpointInfoResponse>(
+			session,
+			"dataBreakpointInfo",
+			{
+				name,
+				...(variablesReference !== undefined ? { variablesReference } : {}),
+				...(frameId !== undefined ? { frameId } : {}),
+			} satisfies DapDataBreakpointInfoArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), info };
+	}
+
+	async setDataBreakpoint(
+		dataId: string,
+		accessType?: "read" | "write" | "readWrite",
+		condition?: string,
+		hitCondition?: string,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).dataBreakpoints.filter(entry => entry.dataId !== dataId);
+		current.push({ dataId, accessType, condition, hitCondition });
+		current.sort((left, right) => left.dataId.localeCompare(right.dataId));
+		const args = { breakpoints: current } satisfies DapSetDataBreakpointsArguments;
+		let responseBreakpoints: DapBreakpoint[] | undefined;
+		await this.#syncBreakpointTree(
+			session,
+			"setDataBreakpoints",
+			args,
+			target => {
+				target.dataBreakpoints = current.map(entry => ({ ...entry }));
+			},
+			(target, response) => {
+				if (target === session) responseBreakpoints = response;
+			},
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: this.#mapDataBreakpoints(current, responseBreakpoints),
+		};
+	}
+
+	async removeDataBreakpoint(dataId: string, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const current = this.#getRootSession(session).dataBreakpoints.filter(entry => entry.dataId !== dataId);
+		const args = { breakpoints: current } satisfies DapSetDataBreakpointsArguments;
+		let responseBreakpoints: DapBreakpoint[] | undefined;
+		await this.#syncBreakpointTree(
+			session,
+			"setDataBreakpoints",
+			args,
+			target => {
+				target.dataBreakpoints = current.map(entry => ({ ...entry }));
+			},
+			(target, response) => {
+				if (target === session) responseBreakpoints = response;
+			},
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			breakpoints: this.#mapDataBreakpoints(current, responseBreakpoints),
+		};
+	}
+
+	async disassemble(
+		memoryReference: string,
+		instructionCount: number,
+		offset?: number,
+		instructionOffset?: number,
+		resolveSymbols?: boolean,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; instructions: DapDisassembledInstruction[] }> {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapDisassembleResponse>(
+			session,
+			"disassemble",
+			{
+				memoryReference,
+				instructionCount,
+				...(offset !== undefined ? { offset } : {}),
+				...(instructionOffset !== undefined ? { instructionOffset } : {}),
+				...(resolveSymbols !== undefined ? { resolveSymbols } : {}),
+			} satisfies DapDisassembleArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), instructions: response?.instructions ?? [] };
+	}
+
+	async readMemory(
+		memoryReference: string,
+		count: number,
+		offset?: number,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; address: string; data?: string; unreadableBytes?: number }> {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapReadMemoryResponse>(
+			session,
+			"readMemory",
+			{
+				memoryReference,
+				count,
+				...(offset !== undefined ? { offset } : {}),
+			} satisfies DapReadMemoryArguments,
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			address: response?.address ?? memoryReference,
+			data: response?.data,
+			unreadableBytes: response?.unreadableBytes,
+		};
+	}
+
+	async writeMemory(
+		memoryReference: string,
+		data: string,
+		offset?: number,
+		allowPartial?: boolean,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; offset?: number; bytesWritten?: number }> {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapWriteMemoryResponse>(
+			session,
+			"writeMemory",
+			{
+				memoryReference,
+				data,
+				...(offset !== undefined ? { offset } : {}),
+				...(allowPartial !== undefined ? { allowPartial } : {}),
+			} satisfies DapWriteMemoryArguments,
+			signal,
+			timeoutMs,
+		);
+		return {
+			snapshot: buildSummary(session),
+			offset: response?.offset,
+			bytesWritten: response?.bytesWritten,
+		};
+	}
+
+	async modules(
+		startModule?: number,
+		moduleCount?: number,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; modules: DapModule[] }> {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapModulesResponse>(
+			session,
+			"modules",
+			{
+				...(startModule !== undefined ? { startModule } : {}),
+				...(moduleCount !== undefined ? { moduleCount } : {}),
+			} satisfies DapModulesArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), modules: response?.modules ?? [] };
+	}
+
+	async loadedSources(
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; sources: DapSource[] }> {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapLoadedSourcesResponse>(
+			session,
+			"loadedSources",
+			{},
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), sources: response?.sources ?? [] };
+	}
+
+	async customRequest(
+		command: string,
+		args?: Record<string, unknown>,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; body: unknown }> {
+		const session = this.#touchActiveSession();
+		const body = await this.#sendRequestWithConfig<unknown>(session, command, args, signal, timeoutMs);
+		return { snapshot: buildSummary(session), body };
+	}
+
+	async continue(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapContinueOutcome> {
+		const session = this.#touchActiveSession();
+		const threadId = await this.#resolveThreadId(session, signal, timeoutMs);
+		// Reset state and subscribe BEFORE sending continue to avoid missing
+		// events that arrive in the same buffer as the response.
+		session.stop = {};
+		session.lastStackFrames = [];
+		session.status = "running";
+		const outcomePromise = this.#prepareStopOutcome(session, signal, timeoutMs);
+		await this.#sendRequestWithConfig<DapContinueResponse>(
+			session,
+			"continue",
+			{ threadId } satisfies DapContinueArguments,
+			signal,
+			timeoutMs,
+		);
+		return this.#awaitStopOutcome(session, outcomePromise, signal, timeoutMs);
+	}
+
+	async pause(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapSessionSummary> {
+		const session = this.#touchActiveSession();
+		// status is mutated by the event reader between awaits; check through a
+		// closure so TS does not carry stale narrowing from the early return.
+		const isStopped = () => session.status === "stopped";
+		if (isStopped()) {
+			return buildSummary(session);
+		}
+		const threadId = await this.#resolveThreadId(session, signal, timeoutMs);
+		// Subscribe BEFORE sending pause: the stopped event can arrive in the
+		// same chunk as the response and would otherwise be dispatched before
+		// the waiter subscribes, burning the whole timeout.
+		const stoppedPromise = session.client.waitForEvent<DapStoppedEventBody>("stopped", undefined, signal, timeoutMs);
+		stoppedPromise.catch(() => {});
+		await this.#sendRequestWithConfig(session, "pause", { threadId } satisfies DapPauseArguments, signal, timeoutMs);
+		if (!isStopped()) {
+			try {
+				await untilAborted(signal, stoppedPromise);
+			} catch {
+				// Timeout or abort — report current state regardless
+			}
+		}
+		return buildSummary(session);
+	}
+
+	async stepIn(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapContinueOutcome> {
+		return this.#step("stepIn", signal, timeoutMs);
+	}
+
+	async stepOut(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapContinueOutcome> {
+		return this.#step("stepOut", signal, timeoutMs);
+	}
+
+	async stepOver(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapContinueOutcome> {
+		return this.#step("next", signal, timeoutMs);
+	}
+
+	async threads(
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; threads: DapThread[] }> {
+		const anchor = this.#touchActiveSession();
+		// A js-debug launch is a session tree: the root may be a threadless
+		// launcher while each real thread lives in a child (main script,
+		// `[worker N]`, …), and other adapters keep every thread on the root.
+		// Querying only the active session would surface just one session's
+		// threads, so aggregate across the whole live tree. No topology guess:
+		// a threadless launcher simply returns no threads (or an error we skip).
+		const targets = this.#liveTreeSessions(anchor);
+		const merged: DapThread[] = [];
+		const seen = new Set<string>();
+		for (const target of targets) {
+			let threads: DapThread[];
+			try {
+				const response = await this.#sendRequestWithConfig<DapThreadsResponse>(
+					target,
+					"threads",
+					undefined,
+					signal,
+					timeoutMs,
+				);
+				threads = response?.threads ?? [];
+			} catch (error) {
+				// Caller cancellation is not an adapter failure: propagate it instead
+				// of degrading a cancelled call into a successful partial result.
+				if (signal?.aborted) throw error;
+				logger.warn("Failed to list threads for debug session", {
+					sessionId: target.id,
+					error: toErrorMessage(error),
+				});
+				continue;
+			}
+			target.threads = threads;
+			// DAP thread IDs are scoped per client session, so identical IDs from
+			// different sessions (e.g. two identical worker scripts) are distinct
+			// live threads and MUST be preserved; only collapse an exact repeat
+			// within a single session's response.
+			for (const thread of threads) {
+				const key = `${target.id}\0${thread.id}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				merged.push(thread);
+			}
+		}
+		return { snapshot: buildSummary(anchor), threads: merged };
+	}
+
+	async stackTrace(
+		frameCount: number | undefined,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<{ snapshot: DapSessionSummary; stackFrames: DapStackFrame[]; totalFrames?: number }> {
+		const session = this.#touchActiveSession();
+		const threadId = await this.#resolveThreadId(session, signal, timeoutMs);
+		const response = await this.#sendRequestWithConfig<DapStackTraceResponse>(
+			session,
+			"stackTrace",
+			{
+				threadId,
+				...(frameCount !== undefined ? { levels: frameCount } : {}),
+			} satisfies DapStackTraceArguments,
+			signal,
+			timeoutMs,
+		);
+		session.lastStackFrames = response?.stackFrames ?? [];
+		this.#applyTopFrame(session, session.lastStackFrames[0]);
+		return {
+			snapshot: buildSummary(session),
+			stackFrames: session.lastStackFrames,
+			totalFrames: response?.totalFrames,
+		};
+	}
+
+	async scopes(frameId: number | undefined, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const resolvedFrameId = frameId ?? session.stop.frameId;
+		if (resolvedFrameId === undefined) {
+			throw new Error("No active stack frame. Run stack_trace first or supply frame_id.");
+		}
+		const response = await this.#sendRequestWithConfig<DapScopesResponse>(
+			session,
+			"scopes",
+			{ frameId: resolvedFrameId } satisfies DapScopesArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), scopes: response?.scopes ?? [] };
+	}
+
+	async variables(variableReference: number, signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const response = await this.#sendRequestWithConfig<DapVariablesResponse>(
+			session,
+			"variables",
+			{ variablesReference: variableReference } satisfies DapVariablesArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), variables: response?.variables ?? [] };
+	}
+
+	async evaluate(
+		expression: string,
+		context: DapEvaluateArguments["context"],
+		frameId: number | undefined,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	) {
+		const session = this.#touchActiveSession();
+		// Default to the top stopped frame so callers don't need to pass
+		// frame_id explicitly for the common case.
+		const effectiveFrameId = frameId ?? session.stop.frameId;
+		const response = await this.#sendRequestWithConfig<DapEvaluateResponse>(
+			session,
+			"evaluate",
+			{
+				expression,
+				context,
+				...(effectiveFrameId !== undefined ? { frameId: effectiveFrameId } : {}),
+			} satisfies DapEvaluateArguments,
+			signal,
+			timeoutMs,
+		);
+		return { snapshot: buildSummary(session), evaluation: response };
+	}
+
+	getOutput(limitBytes?: number): DapOutputSnapshot {
+		const session = this.#touchActiveSession();
+		const output = session.outputChunks.join("");
+		if (!limitBytes || limitBytes <= 0 || session.outputBufferedBytes <= limitBytes) {
+			return { snapshot: buildSummary(session), output };
+		}
+		// Byte-slice the tail once; a torn code point at the cut decodes as U+FFFD.
+		const buffer = Buffer.from(output, "utf-8");
+		if (buffer.length <= limitBytes) {
+			return { snapshot: buildSummary(session), output };
+		}
+		return { snapshot: buildSummary(session), output: buffer.subarray(buffer.length - limitBytes).toString("utf-8") };
+	}
+
+	async terminate(signal?: AbortSignal, timeoutMs: number = 30_000): Promise<DapSessionSummary | null> {
+		const session = this.#getActiveSessionOrNull();
+		if (!session) return null;
+		this.#touchSessionAndAncestors(session);
+		const root = this.#getRootSession(session);
+		const summary = buildSummary(session);
+		await this.#terminateSessionTree(root, signal, timeoutMs);
+		return summary;
+	}
+
+	async #terminateSessionTree(session: DapSession, signal?: AbortSignal, timeoutMs: number = 30_000): Promise<void> {
+		session.status = "terminated";
+		try {
+			for (const childId of [...session.childSessionIds]) {
+				const child = this.#sessions.get(childId);
+				if (child) {
+					await this.#terminateSessionTree(child, signal, timeoutMs);
+				}
+			}
+			if (session.capabilities?.supportsTerminateRequest) {
+				await session.client.sendRequest("terminate", undefined, signal, timeoutMs).catch(() => undefined);
+			}
+			await session.client
+				.sendRequest("disconnect", { terminateDebuggee: true }, signal, timeoutMs)
+				.catch(() => undefined);
+		} catch {
+			/* Disposal remains mandatory when a caller aborts best-effort DAP shutdown. */
+		} finally {
+			this.#disposeSession(session);
+		}
+	}
+
+	#startCleanupTimer(): void {
+		if (this.#cleanupLoopPromise) return;
+		this.#cleanupLoopPromise = this.#runCleanupLoop();
+	}
+
+	async #runCleanupLoop(): Promise<void> {
+		for await (const _ of timers.setInterval(CLEANUP_INTERVAL_MS, null, { ref: false })) {
+			try {
+				this.#cleanupIdleSessions();
+			} catch (error) {
+				logger.error("DAP idle session cleanup failed", { error: toErrorMessage(error) });
+			}
+		}
+	}
+
+	#cleanupIdleSessions(): void {
+		if (this.#sessions.size === 0) return;
+		const now = Date.now();
+		for (const session of this.#sessions.values()) {
+			if (
+				session.status === "terminated" ||
+				now - session.lastUsedAt > IDLE_TIMEOUT_MS ||
+				!session.client.isAlive()
+			) {
+				this.#disposeSession(session);
+			}
+		}
+	}
+
+	async #startChildSession(
+		parent: DapSession,
+		request: "launch" | "attach",
+		configuration: Record<string, unknown>,
+		timeoutMs: number = 30_000,
+	): Promise<void> {
+		if (parent.adapter.connectMode !== "tcp" || parent.port === undefined) {
+			throw new Error(`DAP adapter ${parent.adapter.name} cannot accept child session connections`);
+		}
+		const cwd = path.resolve(parent.cwd, typeof configuration.cwd === "string" ? configuration.cwd : ".");
+		const client = await DapClient.connect({
+			adapter: parent.adapter,
+			cwd,
+			host: "127.0.0.1",
+			port: parent.port,
+		});
+		const child = this.#registerSession(
+			client,
+			parent.adapter,
+			cwd,
+			typeof configuration.program === "string" ? configuration.program : undefined,
+			parent.id,
+		);
+		try {
+			child.capabilities = await client.initialize(
+				this.#buildInitializeArguments(parent.adapter),
+				undefined,
+				timeoutMs,
+			);
+			child.needsConfigurationDone = child.capabilities.supportsConfigurationDoneRequest === true;
+			const startFailure: DapStartRequestFailure = { rejected: false };
+			const startPromise = trackDapStartRequest(
+				client.sendRequest(request, { ...configuration, cwd }, undefined, timeoutMs),
+				startFailure,
+			);
+			startPromise.catch(() => {});
+			try {
+				await this.#completeConfigurationHandshake(child, undefined, timeoutMs);
+			} catch (error) {
+				await throwPreferredDapStartError(request, startFailure, error);
+			}
+			await startPromise;
+		} catch (error) {
+			await this.#disposeSession(child);
+			throw error;
+		}
+	}
+
+	async #applyRootBreakpointsToSession(
+		session: DapSession,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<void> {
+		const root = this.#getRootSession(session);
+		for (const [sourcePath, entries] of root.breakpoints) {
+			try {
+				const response = await session.client.sendRequest<{ breakpoints?: DapBreakpoint[] }>(
+					"setBreakpoints",
+					{
+						source: { path: sourcePath, name: path.basename(sourcePath) },
+						breakpoints: entries.map<DapSourceBreakpoint>(entry => ({
+							line: entry.line,
+							...(entry.condition ? { condition: entry.condition } : {}),
+						})),
+					},
+					signal,
+					timeoutMs,
+				);
+				session.breakpoints.set(sourcePath, this.#mapSourceBreakpoints(entries, response?.breakpoints));
+			} catch (error) {
+				logger.warn("Failed to bind source breakpoints in child debug session", {
+					sessionId: session.id,
+					sourcePath,
+					error: toErrorMessage(error),
+				});
+			}
+		}
+		if (root.functionBreakpoints.length > 0) {
+			try {
+				const response = await session.client.sendRequest<{ breakpoints?: DapBreakpoint[] }>(
+					"setFunctionBreakpoints",
+					{
+						breakpoints: root.functionBreakpoints.map<DapFunctionBreakpoint>(entry => ({
+							name: entry.name,
+							...(entry.condition ? { condition: entry.condition } : {}),
+						})),
+					},
+					signal,
+					timeoutMs,
+				);
+				session.functionBreakpoints = this.#mapFunctionBreakpoints(root.functionBreakpoints, response?.breakpoints);
+			} catch (error) {
+				logger.warn("Failed to bind function breakpoints in child debug session", {
+					sessionId: session.id,
+					error: toErrorMessage(error),
+				});
+			}
+		}
+		if (root.instructionBreakpoints.length > 0) {
+			try {
+				await session.client.sendRequest(
+					"setInstructionBreakpoints",
+					{ breakpoints: root.instructionBreakpoints } satisfies DapSetInstructionBreakpointsArguments,
+					signal,
+					timeoutMs,
+				);
+				session.instructionBreakpoints = root.instructionBreakpoints.map(entry => ({ ...entry }));
+			} catch (error) {
+				logger.warn("Failed to bind instruction breakpoints in child debug session", {
+					sessionId: session.id,
+					error: toErrorMessage(error),
+				});
+			}
+		}
+		if (root.dataBreakpoints.length > 0) {
+			try {
+				await session.client.sendRequest(
+					"setDataBreakpoints",
+					{ breakpoints: root.dataBreakpoints } satisfies DapSetDataBreakpointsArguments,
+					signal,
+					timeoutMs,
+				);
+				session.dataBreakpoints = root.dataBreakpoints.map(entry => ({ ...entry }));
+			} catch (error) {
+				logger.debug("Failed to bind data breakpoints in child debug session", {
+					sessionId: session.id,
+					error: toErrorMessage(error),
+				});
+			}
+		}
+	}
+
+	async #ensureLaunchSlot(): Promise<void> {
+		for (const session of [...this.#sessions.values()]) {
+			if (session.status === "terminated" || !session.client.isAlive()) {
+				this.#disposeSession(session);
+			}
+		}
+		const root = [...this.#sessions.values()].find(session => !session.parentSessionId);
+		if (!root) return;
+		throw new Error(`Debug session ${root.id} is still active. Terminate it before launching another.`);
+	}
+
+	#registerSession(
+		client: DapClient,
+		adapter: DapResolvedAdapter,
+		cwd: string,
+		program?: string,
+		parentSessionId?: string,
+	): DapSession {
+		const session: DapSession = {
+			id: `debug-${++this.#nextId}`,
+			adapter,
+			cwd,
+			program,
+			client,
+			status: "launching",
+			launchedAt: Date.now(),
+			lastUsedAt: Date.now(),
+			breakpoints: new Map(),
+			functionBreakpoints: [],
+			instructionBreakpoints: [],
+			dataBreakpoints: [],
+			breakpointMutationQueue: Promise.resolve(),
+			outputChunks: [],
+			outputBytes: 0,
+			outputBufferedBytes: 0,
+			outputTruncated: false,
+			stop: {},
+			threads: [],
+			lastStackFrames: [],
+			initializedSeen: false,
+			needsConfigurationDone: false,
+			configurationDoneSent: false,
+			parentSessionId,
+			childSessionIds: new Set(),
+			port: client.port,
+		};
+		client.onReverseRequest("runInTerminal", async rawArgs => {
+			const args = (rawArgs ?? {}) as DapRunInTerminalArguments;
+			if (!Array.isArray(args.args) || args.args.length === 0) {
+				throw new Error("runInTerminal request did not include a command");
+			}
+			const env = Object.fromEntries(
+				Object.entries(args.env ?? {}).filter((entry): entry is [string, string] => entry[1] !== null),
+			);
+			const proc = ptree.spawn(args.args, {
+				cwd: path.resolve(session.cwd, args.cwd ?? "."),
+				stdin: "pipe",
+				env: {
+					...Bun.env,
+					...NON_INTERACTIVE_ENV,
+					...env,
+				},
+				detached: true,
+			});
+			return { processId: proc.pid } satisfies DapRunInTerminalResponse;
+		});
+		client.onReverseRequest("startDebugging", async rawArgs => {
+			const startArgs = (rawArgs ?? {}) as Partial<DapStartDebuggingArguments>;
+			const request = startArgs.request === "attach" ? "attach" : "launch";
+			const configuration =
+				startArgs.configuration && typeof startArgs.configuration === "object" ? startArgs.configuration : {};
+			logger.debug("Adapter requested child debug session", {
+				adapter: session.adapter.name,
+				sessionId: session.id,
+				request,
+				name: typeof configuration.name === "string" ? configuration.name : undefined,
+			});
+			await this.#startChildSession(session, request, configuration);
+			return {};
+		});
+		client.onEvent("output", body => {
+			truncateOutput(session, (body as DapOutputEventBody | undefined)?.output ?? "");
+		});
+		client.onEvent("initialized", () => {
+			session.initializedSeen = true;
+			session.status = session.configurationDoneSent ? session.status : "configuring";
+		});
+		client.onEvent("stopped", body => {
+			this.#handleStoppedEvent(session, body as DapStoppedEventBody);
+			this.#activeSessionId = session.id;
+			this.#resolveTreeOutcome(session);
+		});
+		client.onEvent("continued", body => {
+			const continued = body as { threadId?: number } | undefined;
+			session.status = "running";
+			session.stop = { threadId: continued?.threadId };
+			session.lastStackFrames = [];
+		});
+		client.onEvent("exited", body => {
+			session.exitCode = (body as DapExitedEventBody | undefined)?.exitCode;
+			session.status = "terminated";
+			this.#reactivateAfterTermination(session);
+			this.#resolveTreeOutcome(session);
+		});
+		client.onEvent("terminated", () => {
+			session.status = "terminated";
+			this.#reactivateAfterTermination(session);
+			this.#resolveTreeOutcome(session);
+		});
+		this.#sessions.set(session.id, session);
+		if (parentSessionId) {
+			this.#sessions.get(parentSessionId)?.childSessionIds.add(session.id);
+		}
+		// Focus follows stops, not registrations: a lazily-attached child (e.g. a
+		// js-debug `[worker N]` session) must not steal focus from a sibling that
+		// is already stopped at a breakpoint / entry. Only claim focus when no
+		// live, stopped session currently holds it.
+		if (!this.#hasLiveStoppedActiveSession()) {
+			this.#activeSessionId = session.id;
+		}
+		const heartbeat = setInterval(() => {
+			if (!client.isAlive()) {
+				session.status = "terminated";
+			}
+		}, HEARTBEAT_INTERVAL_MS);
+		heartbeat.unref?.();
+		void client.proc.exited.finally(() => {
+			clearInterval(heartbeat);
+			session.status = "terminated";
+			this.#reactivateAfterTermination(session);
+			this.#resolveTreeOutcome(session);
+		});
+		return session;
+	}
+
+	#buildInitializeArguments(adapter: DapResolvedAdapter): DapInitializeArguments {
+		return {
+			clientID: "omp",
+			clientName: "Oh My Pi",
+			adapterID: adapter.name,
+			locale: "en-US",
+			linesStartAt1: true,
+			columnsStartAt1: true,
+			pathFormat: "path",
+			supportsRunInTerminalRequest: true,
+			supportsStartDebuggingRequest: true,
+			supportsMemoryReferences: true,
+			supportsVariableType: true,
+			supportsInvalidatedEvent: true,
+		};
+	}
+
+	/**
+	 * Wait for the adapter's `initialized` event (if not already received),
+	 * then send `configurationDone`. Many adapters block the `launch`/`attach`
+	 * response until this handshake completes.
+	 */
+	async #completeConfigurationHandshake(
+		session: DapSession,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<void> {
+		if (session.configurationDoneSent) return;
+		if (!session.needsConfigurationDone) {
+			if (session.parentSessionId) {
+				await this.#applyRootBreakpointsToSession(session, signal, timeoutMs);
+			}
+			return;
+		}
+		// Wait for the initialized event if we haven't seen it yet.
+		if (!session.initializedSeen) {
+			try {
+				await untilAborted(signal, session.client.waitForEvent("initialized", undefined, signal, timeoutMs));
+			} catch {
+				// Adapter may not send initialized (e.g. it already terminated).
+				// Proceed anyway — the launch/attach response will surface any real error.
+				return;
+			}
+		}
+		if (session.parentSessionId) {
+			await this.#applyRootBreakpointsToSession(session, signal, timeoutMs);
+		}
+		await session.client.sendRequest("configurationDone", {}, signal, timeoutMs);
+		session.configurationDoneSent = true;
+		if (session.status === "configuring") {
+			session.status = "running";
+		}
+	}
+
+	#handleStoppedEvent(session: DapSession, stopped: DapStoppedEventBody): void {
+		session.status = "stopped";
+		session.stop = {
+			threadId: stopped.threadId,
+			reason: stopped.reason,
+			description: stopped.description,
+			text: stopped.text,
+		};
+		session.lastStackFrames = [];
+	}
+
+	#applyTopFrame(session: DapSession, frame: DapStackFrame | undefined): void {
+		if (!frame) return;
+		session.stop.frameId = frame.id;
+		session.stop.frameName = frame.name;
+		session.stop.instructionPointerReference = frame.instructionPointerReference;
+		session.stop.source = frame.source;
+		session.stop.line = frame.line;
+		session.stop.column = frame.column;
+	}
+
+	/**
+	 * Fetch the top stack frame from the adapter and apply it to the session's
+	 * stop location. Called outside the event dispatch loop to avoid deadlocking
+	 * the message reader.
+	 */
+	async #fetchTopFrame(session: DapSession, signal?: AbortSignal, timeoutMs: number = 5_000): Promise<void> {
+		if (session.stop.threadId === undefined) return;
+		try {
+			const response = await session.client.sendRequest<DapStackTraceResponse>(
+				"stackTrace",
+				{ threadId: session.stop.threadId, levels: 1 } satisfies DapStackTraceArguments,
+				signal,
+				timeoutMs,
+			);
+			session.lastStackFrames = response?.stackFrames ?? [];
+			this.#applyTopFrame(session, session.lastStackFrames[0]);
+		} catch (error) {
+			logger.debug("Failed to capture stopped frame", {
+				sessionId: session.id,
+				error: toErrorMessage(error),
+			});
+		}
+	}
+
+	async #step(command: "stepIn" | "stepOut" | "next", signal?: AbortSignal, timeoutMs: number = 30_000) {
+		const session = this.#touchActiveSession();
+		const threadId = await this.#resolveThreadId(session, signal, timeoutMs);
+		// Reset state and subscribe BEFORE sending the step command to avoid
+		// missing events that arrive in the same buffer as the response.
+		session.stop = {};
+		session.lastStackFrames = [];
+		session.status = "running";
+		const outcomePromise = this.#prepareStopOutcome(session, signal, timeoutMs);
+		await this.#sendRequestWithConfig(session, command, { threadId } satisfies DapStepArguments, signal, timeoutMs);
+		return this.#awaitStopOutcome(session, outcomePromise, signal, timeoutMs);
+	}
+
+	/**
+	 * Create a promise that resolves when the session stops, terminates, or exits.
+	 * MUST be called before the command that triggers the event.
+	 */
+	#prepareStopOutcome(session: DapSession, signal?: AbortSignal, timeoutMs: number = 30_000): Promise<unknown> {
+		const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+		const rootSessionId = this.#getRootSession(session).id;
+		let timeout: NodeJS.Timeout | undefined;
+		let abortHandler: (() => void) | undefined;
+		const cleanup = () => {
+			clearTimeout(timeout);
+			if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
+			this.#treeOutcomeWaiters.delete(waiter);
+		};
+		const waiter: DapTreeOutcomeWaiter = {
+			rootSessionId,
+			resolve: value => {
+				cleanup();
+				resolve(value);
+			},
+			reject: reason => {
+				cleanup();
+				reject(reason);
+			},
+		};
+		this.#treeOutcomeWaiters.add(waiter);
+		timeout = setTimeout(
+			() => waiter.reject(new Error(`DAP session tree outcome timed out after ${timeoutMs}ms`)),
+			timeoutMs,
+		);
+		if (signal) {
+			abortHandler = () =>
+				waiter.reject(signal.reason instanceof Error ? signal.reason : new Error("Debug operation aborted"));
+			if (signal.aborted) abortHandler();
+			else signal.addEventListener("abort", abortHandler, { once: true });
+		}
+		promise.catch(() => {});
+		return promise;
+	}
+
+	/**
+	 * Await a pre-subscribed stop outcome, then fetch the top frame if stopped.
+	 */
+	async #awaitStopOutcome(
+		session: DapSession,
+		outcomePromise: Promise<unknown>,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<DapContinueOutcome> {
+		try {
+			await untilAborted(signal, outcomePromise);
+			const active = this.#getActiveSessionOrNull();
+			const resultSession =
+				active && this.#getRootSession(active).id === this.#getRootSession(session).id ? active : session;
+			if (resultSession.status === "stopped") {
+				await this.#fetchTopFrame(resultSession, signal, Math.min(timeoutMs, 5_000));
+			}
+			const state =
+				resultSession.status === "stopped"
+					? "stopped"
+					: resultSession.status === "terminated"
+						? "terminated"
+						: "running";
+			return { snapshot: buildSummary(resultSession), state, timedOut: false };
+		} catch (error) {
+			if (signal?.aborted) throw error;
+			const active = this.#getActiveSessionOrNull();
+			const resultSession =
+				active && this.#getRootSession(active).id === this.#getRootSession(session).id ? active : session;
+			return {
+				snapshot: buildSummary(resultSession),
+				state: "running",
+				timedOut: resultSession.status === "running",
+			};
+		}
+	}
+
+	async #resolveThreadId(session: DapSession, signal?: AbortSignal, timeoutMs: number = 30_000): Promise<number> {
+		if (session.stop.threadId !== undefined) {
+			return session.stop.threadId;
+		}
+		if (session.threads.length > 0) {
+			return session.threads[0].id;
+		}
+		const response = await session.client.sendRequest<DapThreadsResponse>("threads", undefined, signal, timeoutMs);
+		session.threads = response?.threads ?? [];
+		const threadId = session.threads[0]?.id;
+		if (threadId === undefined) {
+			throw new Error("Debugger reported no threads.");
+		}
+		return threadId;
+	}
+
+	async #sendRequestWithConfig<TBody>(
+		session: DapSession,
+		command: string,
+		args: unknown,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<TBody> {
+		await this.#ensureConfigurationDone(session, signal, timeoutMs);
+		const body = await session.client.sendRequest<TBody>(command, args, signal, timeoutMs);
+		this.#touchSessionAndAncestors(session);
+		return body;
+	}
+
+	async #ensureConfigurationDone(
+		session: DapSession,
+		signal?: AbortSignal,
+		timeoutMs: number = 30_000,
+	): Promise<void> {
+		if (!session.needsConfigurationDone || session.configurationDoneSent) {
+			return;
+		}
+		await session.client.sendRequest("configurationDone", {}, signal, timeoutMs);
+		session.configurationDoneSent = true;
+		if (session.status === "configuring") {
+			session.status = "running";
+		}
+	}
+
+	#mapSourceBreakpoints(
+		input: DapBreakpointRecord[],
+		responseBreakpoints: DapBreakpoint[] | undefined,
+	): DapBreakpointRecord[] {
+		return input.map((entry, index) => ({
+			line: entry.line,
+			condition: entry.condition,
+			id: responseBreakpoints?.[index]?.id,
+			verified: responseBreakpoints?.[index]?.verified ?? false,
+			message: responseBreakpoints?.[index]?.message,
+		}));
+	}
+
+	#mapFunctionBreakpoints(
+		input: DapFunctionBreakpointRecord[],
+		responseBreakpoints: DapBreakpoint[] | undefined,
+	): DapFunctionBreakpointRecord[] {
+		return input.map((entry, index) => ({
+			name: entry.name,
+			condition: entry.condition,
+			id: responseBreakpoints?.[index]?.id,
+			verified: responseBreakpoints?.[index]?.verified ?? false,
+			message: responseBreakpoints?.[index]?.message,
+		}));
+	}
+
+	#mapInstructionBreakpoints(
+		input: DapInstructionBreakpoint[],
+		responseBreakpoints: DapBreakpoint[] | undefined,
+	): DapInstructionBreakpointRecord[] {
+		return input.map((entry, index) => ({
+			instructionReference: responseBreakpoints?.[index]?.instructionReference ?? entry.instructionReference,
+			offset: responseBreakpoints?.[index]?.offset ?? entry.offset,
+			condition: entry.condition,
+			hitCondition: entry.hitCondition,
+			id: responseBreakpoints?.[index]?.id,
+			verified: responseBreakpoints?.[index]?.verified ?? false,
+			message: responseBreakpoints?.[index]?.message,
+		}));
+	}
+
+	#mapDataBreakpoints(
+		input: DapDataBreakpoint[],
+		responseBreakpoints: DapBreakpoint[] | undefined,
+	): DapDataBreakpointRecord[] {
+		return input.map((entry, index) => ({
+			dataId: entry.dataId,
+			accessType: entry.accessType,
+			condition: entry.condition,
+			hitCondition: entry.hitCondition,
+			id: responseBreakpoints?.[index]?.id,
+			verified: responseBreakpoints?.[index]?.verified ?? false,
+			message: responseBreakpoints?.[index]?.message,
+		}));
+	}
+
+	#touchActiveSession(): DapSession {
+		const session = this.#getActiveSessionOrThrow();
+		this.#touchSessionAndAncestors(session);
+		if (session.status !== "terminated" && !session.client.isAlive()) {
+			session.status = "terminated";
+		}
+		return session;
+	}
+
+	#getActiveSessionOrNull(): DapSession | null {
+		if (!this.#activeSessionId) {
+			return null;
+		}
+		const session = this.#sessions.get(this.#activeSessionId) ?? null;
+		if (!session) {
+			this.#activeSessionId = null;
+		}
+		return session;
+	}
+
+	/** True when the current active session is live and paused at a stop. */
+	#hasLiveStoppedActiveSession(): boolean {
+		const active = this.#getActiveSessionOrNull();
+		return active !== null && active.status === "stopped" && active.client.isAlive();
+	}
+
+	#getActiveSessionOrThrow(): DapSession {
+		const session = this.#getActiveSessionOrNull();
+		if (!session) {
+			throw new Error("No active debug session. Launch or attach first.");
+		}
+		return session;
+	}
+
+	#getRootSession(session: DapSession): DapSession {
+		let root = session;
+		while (root.parentSessionId) {
+			const parent = this.#sessions.get(root.parentSessionId);
+			if (!parent) break;
+			root = parent;
+		}
+		return root;
+	}
+
+	#getTreeSessions(session: DapSession): DapSession[] {
+		const sessions: DapSession[] = [];
+		const pending = [this.#getRootSession(session)];
+		while (pending.length > 0) {
+			const current = pending.pop();
+			if (!current) continue;
+			sessions.push(current);
+			for (const childId of current.childSessionIds) {
+				const child = this.#sessions.get(childId);
+				if (child) pending.push(child);
+			}
+		}
+		return sessions;
+	}
+
+	/**
+	 * Live (non-terminated, connected) sessions in `session`'s tree, or the
+	 * session itself when the tree has collapsed. Used to fan `threads` out
+	 * across the whole tree; a threadless session just reports no threads, so
+	 * this makes no assumption about which node owns them.
+	 */
+	#liveTreeSessions(session: DapSession): DapSession[] {
+		const live = this.#getTreeSessions(session).filter(
+			candidate => candidate.status !== "terminated" && candidate.client.isAlive(),
+		);
+		return live.length > 0 ? live : [session];
+	}
+
+	#touchSessionAndAncestors(session: DapSession): void {
+		const now = Date.now();
+		let current: DapSession | undefined = session;
+		while (current) {
+			current.lastUsedAt = now;
+			current = current.parentSessionId ? this.#sessions.get(current.parentSessionId) : undefined;
+		}
+	}
+
+	/** Point the active session at a live tree member when the active one terminates. */
+	#reactivateAfterTermination(session: DapSession): void {
+		if (this.#activeSessionId !== session.id) return;
+		const live = this.#getTreeSessions(session).filter(
+			candidate => candidate.status !== "terminated" && candidate.client.isAlive(),
+		);
+		if (live.length === 0) return;
+		const replacement =
+			live.find(candidate => candidate.status === "stopped") ??
+			live.find(candidate => candidate.parentSessionId !== undefined) ??
+			live[0];
+		this.#activeSessionId = replacement.id;
+	}
+
+	#resolveTreeOutcome(session: DapSession): void {
+		const rootId = this.#getRootSession(session).id;
+		for (const waiter of [...this.#treeOutcomeWaiters]) {
+			if (waiter.rootSessionId === rootId) {
+				waiter.resolve(undefined);
+			}
+		}
+	}
+
+	#disposeSession(session: DapSession): void {
+		if (!this.#sessions.has(session.id)) return;
+		for (const childId of [...session.childSessionIds]) {
+			const child = this.#sessions.get(childId);
+			if (child) this.#disposeSession(child);
+		}
+		this.#sessions.delete(session.id);
+		if (session.parentSessionId) {
+			this.#sessions.get(session.parentSessionId)?.childSessionIds.delete(session.id);
+		}
+		if (this.#activeSessionId === session.id) {
+			const parent = session.parentSessionId ? this.#sessions.get(session.parentSessionId) : undefined;
+			this.#activeSessionId = parent?.id ?? this.#sessions.values().next().value?.id ?? null;
+		}
+		void session.client.dispose().catch(() => {});
+	}
+}
+
+export const dapSessionManager = new DapSessionManager();