@siuver/omp-debug-mode 0.1.2 → 0.1.4

package/src/debug-mode.ts

@@ -0,0 +1,748 @@
+import { Text } from "@oh-my-pi/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, MessageRenderer } from "@oh-my-pi/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { addEvidenceArtifact, describeEvidence, parseEvidencePlan } from "./evidence";
+import { decideGate } from "./gate";
+import {
+	ACTIVE_LOG_FILE,
+	JsonlLineCounter,
+	describeHypotheses,
+	prepareRunLog,
+	readJsonlLines,
+	summarizeHypotheses,
+} from "./log-files";
+import { describeLedger, recordProbes, syncLedger } from "./probes";
+import {
+	CLEANUP_CONTRACT,
+	METHODOLOGY,
+	PROCEED_REMINDER,
+	buildFixedMessage,
+	buildProceedMessage,
+	buildStartMessage,
+	extractAssistantText,
+	extractReproductionSteps,
+} from "./methodology";
+import {
+	DEBUG_CONTEXT_TYPE,
+	DEBUG_ENTRY,
+	type DebugState,
+	type EvidenceObservation,
+	blackboard,
+	compareRunIds,
+	evidenceSummary,
+	freshState,
+	keepLatestCustomType,
+	logFileFor,
+	pendingEvidenceRequests,
+	replaceRoundEvidenceRequests,
+} from "./state";
+import { registerDebugTools } from "./tools";
+import { applyUi } from "./ui";
+import { debugDirFor, excludeDebugLogsFromGit, pruneDebugRoot } from "./workspace";
+
+const COMMAND_MODE = "debug-mode";
+const COMMAND_DONE = "debug-done";
+const COMMAND_PROCEED = "debug-proceed";
+const COMMAND_EVIDENCE = "debug-evidence";
+const COMMAND_ABORT = "debug-abort";
+const COMMAND_STATUS = "debug-status";
+
+/** Compact transcript lines for the prompts this extension injects. */
+const MESSAGE_SUMMARIES: Record<string, string> = {
+	"debug-mode-start": "debug mode started — hypotheses and instrumentation",
+	"debug-mode-proceed": "proceed — analyzing captured logs",
+	"debug-mode-fixed": "marked fixed — removing probes and summarizing",
+};
+
+interface DebugMessageDetails {
+	summary?: string;
+}
+
+export function registerDebugMode(pi: ExtensionAPI): void {
+	const state: DebugState = freshState();
+	let uiCtx: ExtensionContext | null = null;
+	let watchedLogFile: string | null = null;
+	const lineCounter = new JsonlLineCounter();
+
+	for (const [customType, summary] of Object.entries(MESSAGE_SUMMARIES)) {
+		const renderer: MessageRenderer<DebugMessageDetails> = (message, _options, theme) => {
+			const text = typeof message.details?.summary === "string" ? message.details.summary : summary;
+			return new Text(theme.fg("dim", `🐞 ${text}`), 1, 0);
+		};
+		pi.registerMessageRenderer<DebugMessageDetails>(customType, renderer);
+	}
+
+	// ============================== log files ==============================
+
+	function initializeLogDirectory(ctx: ExtensionContext): boolean {
+		const dir = debugDirFor(ctx.cwd, ctx.sessionManager.getSessionId());
+		try {
+			fs.mkdirSync(dir, { recursive: true });
+			state.debugDir = dir;
+			excludeDebugLogsFromGit(ctx.cwd);
+			return true;
+		} catch (err) {
+			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
+			state.debugDir = null;
+			return false;
+		}
+	}
+
+	function readRunLines(run: string): string[] {
+		return readJsonlLines(logFileFor(state, run));
+	}
+
+	function refreshLogCounts(): void {
+		const runs = new Set(Object.keys(state.logCounts));
+		if (state.debugDir) {
+			try {
+				for (const file of fs.readdirSync(state.debugDir)) {
+					if (!file.endsWith(".jsonl")) continue;
+					if (file === ACTIVE_LOG_FILE) {
+						if (state.runId) runs.add(state.runId);
+					} else {
+						runs.add(file.replace(/\.jsonl$/, ""));
+					}
+				}
+			} catch {}
+		}
+		for (const run of runs) state.logCounts[run] = lineCounter.count(logFileFor(state, run));
+		adoptDiscoveredRuns(runs);
+	}
+
+	/** Keep the ordered history complete when runs are discovered from disk. */
+	function adoptDiscoveredRuns(runs: Iterable<string>): void {
+		const missing = [...runs].filter(run => run !== state.runId && !state.runHistory.includes(run));
+		if (missing.length === 0) return;
+		const active = state.runId && state.runHistory.includes(state.runId) ? state.runId : null;
+		const completed = state.runHistory.filter(run => run !== active).concat(missing);
+		completed.sort(compareRunIds);
+		state.runHistory = active ? [...completed, active] : completed;
+	}
+
+	function currentLogCount(): number {
+		refreshLogCounts();
+		return state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
+	}
+
+	function newRun(): string | null {
+		if (!state.debugDir) return null;
+		const run = `run${state.round}-${Date.now().toString(36)}`;
+		try {
+			prepareRunLog(state.debugDir, state.runId);
+		} catch (err) {
+			pi.logger.error("debug-mode: cannot initialize run log", {
+				file: path.join(state.debugDir, ACTIVE_LOG_FILE),
+				err,
+			});
+			return null;
+		}
+		state.runId = run;
+		state.runHistory.push(run);
+		state.logCounts[run] = 0;
+		return run;
+	}
+
+	function refreshUi(): void {
+		applyUi(uiCtx, state, currentLogCount);
+	}
+
+	/**
+	 * While the user reproduces out-of-band nothing in the session fires, so the
+	 * evidence counter would sit at zero. Poll the active log for appends and
+	 * refresh the widget as observations land.
+	 */
+	function watchLogFile(): void {
+		const file = state.phase === "waiting" ? logFileFor(state) : null;
+		if (file === watchedLogFile) return;
+		unwatchLogFile();
+		if (!file || !uiCtx?.hasUI) return;
+		try {
+			fs.watchFile(file, { interval: 1000 }, (curr, prev) => {
+				if (state.phase !== "waiting") return;
+				if (curr.mtimeMs === prev.mtimeMs && curr.size === prev.size) return;
+				try {
+					refreshUi();
+				} catch (err) {
+					pi.logger.warn("debug-mode: log watch refresh failed", { err });
+				}
+			});
+			watchedLogFile = file;
+		} catch (err) {
+			pi.logger.warn("debug-mode: cannot watch the run log", { file, err });
+		}
+	}
+
+	function unwatchLogFile(): void {
+		if (!watchedLogFile) return;
+		try {
+			fs.unwatchFile(watchedLogFile);
+		} catch (err) {
+			pi.logger.warn("debug-mode: cannot stop watching the run log", { file: watchedLogFile, err });
+		}
+		watchedLogFile = null;
+	}
+
+	// ============================== probe ledger ==============================
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!state.active) return;
+		if (event.toolName !== "edit" && event.toolName !== "write") return;
+		recordProbes(state.probes, state.round, event.input as Record<string, unknown>, ctx.cwd);
+	});
+
+	// ============================== prompt injection ==============================
+
+	pi.on("before_agent_start", async () => {
+		if (!state.active || (state.phase !== "round" && state.phase !== "cleanup")) return;
+		// The blackboard claims to be ground truth, so reconcile it with disk first.
+		await syncLedger(state);
+		// Cleanup has no hypotheses left to form; the full methodology would only
+		// invite another round.
+		const contract = state.phase === "cleanup" ? CLEANUP_CONTRACT : METHODOLOGY;
+		return {
+			message: {
+				customType: DEBUG_CONTEXT_TYPE,
+				content: `${blackboard(state, describeEvidence(state))}\n\n${contract}`,
+                display: false,
+			},
+		};
+	});
+
+	// Drop stale blackboard copies. Keep the newest — `context` runs after
+	// `before_agent_start`, so deleting every match would hide the injection
+	// from the model.
+	pi.on("context", async (event) => {
+		const filtered = keepLatestCustomType(event.messages, DEBUG_CONTEXT_TYPE);
+		if (filtered.length !== event.messages.length) return { messages: filtered };
+	});
+
+	// ============================== round lifecycle ==============================
+
+	pi.on("agent_start", async () => {
+		if (state.active) state.hasRoundContent = false;
+	});
+
+	pi.on("message_end", async (event) => {
+		if (!state.active) return;
+		const msg = event.message as { role?: string; content?: unknown };
+		if (msg?.role === "assistant") {
+			if (state.phase === "cleanup") state.cleanupReady = true;
+			state.hasRoundContent = true;
+			const text = extractAssistantText(msg.content);
+			const steps = extractReproductionSteps(text);
+			if (steps.length > 0) state.reproductionSteps = steps;
+			if (state.phase === "round") {
+				const plan = parseEvidencePlan(text, state.round);
+				if (plan.found) {
+					replaceRoundEvidenceRequests(state, state.round, plan.valid ? plan.requests : []);
+					pi.appendEntry(DEBUG_ENTRY, { ...state });
+				}
+			}
+		}
+	});
+
+	pi.on("session_stop", async (_event, ctx) => {
+		if (!state.active) return;
+		if (state.phase === "cleanup") {
+			if (state.cleanupReady) await teardown(ctx, "finished");
+			return;
+		}
+		// Ordinary editor messages while waiting are conversational only. Only an
+		// explicit debug command advances the run or leaves the gate.
+		if (state.phase !== "round" || !state.hasRoundContent) return;
+		const probesThisRound = state.probes.filter(p => p.round === state.round).length;
+		const hasEvidencePlan = state.evidenceRequests.some(request => request.round === state.round);
+		const decision = decideGate({
+			hasReproductionSteps: state.reproductionSteps.length > 0,
+			hasEvidencePlan,
+			probesThisRound,
+			nudgesUsed: state.gateNudges,
+		});
+		if (decision.kind === "stay") return;
+		if (decision.kind === "nudge") {
+			state.gateNudges += 1;
+			return { continue: true, additionalContext: decision.context };
+		}
+		enterGate(ctx, probesThisRound, decision.missingSteps, decision.missingEvidencePlan);
+	});
+
+function enterGate(
+	ctx: ExtensionContext,
+	probesThisRound: number,
+	missingSteps: boolean,
+	missingEvidencePlan: boolean,
+): void {
+	state.phase = "waiting";
+	pi.appendEntry(DEBUG_ENTRY, { ...state });
+	refreshUi();
+	watchLogFile();
+	// Commands are the only interaction at the gate: the widget lists them,
+	// the user picks one. No menu is opened automatically.
+	const pending = pendingEvidenceRequests(state, state.round);
+	const hasValidPlan = state.evidenceRequests.some(request => request.round === state.round);
+	if (probesThisRound === 0 && !hasValidPlan) {
+		ctx.ui.notify(
+			`Debug round ${state.round} paused, but it added no probes and declared no evidence plan — this round cannot produce runtime evidence. Use /${COMMAND_PROCEED} to ask for instrumentation.`,
+			"warning",
+		);
+	} else if (missingSteps) {
+		ctx.ui.notify(
+			`Debug round ${state.round} paused without reproduction steps. Exercise the instrumented path, then ${PROCEED_REMINDER}`,
+			"warning",
+		);
+	} else if (pending.length > 0) {
+		ctx.ui.notify(
+			`Debug round ${state.round} paused. User evidence requested (${pending.length} pending: ${pending.map(r => r.id).join(", ")}) — attach via /${COMMAND_EVIDENCE} <request-id> <path>, then ${PROCEED_REMINDER}`,
+			"info",
+		);
+	} else if (missingEvidencePlan) {
+		ctx.ui.notify(
+			`Debug round ${state.round} paused. The gate is usable, but the next Proceed will ask the model to declare an evidence method.`,
+			"info",
+		);
+	} else {
+		ctx.ui.notify(`Debug round ${state.round} paused. Reproduce the bug, then ${PROCEED_REMINDER}`, "info");
+	}
+}
+
+	// ============================== round transitions ==============================
+
+	function startDebug(ctx: ExtensionContext, problem: string): void {
+		if (!initializeLogDirectory(ctx)) {
+			ctx.ui.notify("debug-mode: could not create the debug log directory; debug mode was not started", "error");
+			return;
+		}
+		state.active = true;
+		state.phase = "round";
+		state.problem = problem;
+		state.round = 1;
+		state.probes = [];
+		state.runHistory = [];
+		state.logCounts = {};
+		state.hasRoundContent = false;
+		state.cleanupReady = false;
+		state.reproductionSteps = [];
+		state.gateNudges = 0;
+		state.evidenceRequests = [];
+		state.evidenceArtifacts = [];
+		state.evidenceObservations = [];
+		if (!newRun()) {
+			Object.assign(state, freshState());
+			ctx.ui.notify("debug-mode: could not initialize the run log file; debug mode was not started", "error");
+			return;
+		}
+		refreshUi();
+		const logFile = logFileFor(state);
+		if (!logFile) {
+			Object.assign(state, freshState());
+			ctx.ui.notify("debug-mode: could not resolve the run log file; debug mode was not started", "error");
+			return;
+		}
+		pi.sendMessage(
+			{
+				customType: "debug-mode-start",
+				content: buildStartMessage(problem, logFile),
+				display: true,
+				details: { summary: "debug mode started — hypotheses and instrumentation" } satisfies DebugMessageDetails,
+			},
+			{ triggerTurn: true },
+		);
+	}
+
+	function ensureWaiting(ctx: ExtensionContext): boolean {
+		if (!state.active) {
+			ctx.ui.notify("debug-mode: not active", "error");
+			return false;
+		}
+		if (state.phase !== "waiting") {
+			ctx.ui.notify(`debug-mode: not waiting for reproduction (phase: ${state.phase})`, "error");
+			return false;
+		}
+		return true;
+	}
+
+    async function markDebugFixed(ctx: ExtensionContext): Promise<void> {
+		if (!ensureWaiting(ctx)) return;
+		const logCount = currentLogCount();
+		const hasNonProbeEvidence = state.evidenceRequests.some(
+			request => request.round === state.round && request.method !== "runtime_probe",
+		);
+		if (logCount === 0 && !hasNonProbeEvidence && ctx.hasUI) {
+			const confirmed = await ctx.ui.confirm(
+				"Mark as fixed without runtime logs?",
+				"No runtime observations were captured for this round. Mark the problem as fixed anyway?",
+			);
+			if (!confirmed) return;
+		}
+		if (!state.active || state.phase !== "waiting") return;
+
+		state.phase = "cleanup";
+		state.cleanupReady = false;
+		unwatchLogFile();
+		refreshUi();
+		const evidenceJson = JSON.stringify({
+			requests: state.evidenceRequests,
+			observations: state.evidenceObservations,
+			artifacts: state.evidenceArtifacts,
+		});
+		pi.sendMessage(
+			{
+				customType: "debug-mode-fixed",
+				content: buildFixedMessage(JSON.stringify(state.probes), evidenceJson),
+				details: { summary: `marked fixed — removing ${state.probes.length} probe(s)` } satisfies DebugMessageDetails,
+			},
+			{ triggerTurn: true },
+		);
+    }
+
+	async function advanceDebug(ctx: ExtensionContext, userDetails?: string): Promise<void> {
+		if (!ensureWaiting(ctx)) return;
+		refreshLogCounts();
+		const run = state.runId ?? "(none)";
+		const logCount = state.logCounts[run] ?? 0;
+		const hasNonProbeEvidence = state.evidenceRequests.some(
+			request => request.round === state.round && request.method !== "runtime_probe",
+		);
+		if (logCount === 0 && !userDetails && !hasNonProbeEvidence && ctx.hasUI) {
+			const confirmed = await ctx.ui.confirm(
+				"Proceed without runtime logs?",
+				"No runtime observations were captured for this round. Continue to log analysis anyway?",
+			);
+			if (!confirmed) return;
+		}
+		if (!state.active || state.phase !== "waiting") return;
+
+		// Persist optional /debug-proceed details as a batched user observation
+		// tied to every current-round user_report request.
+		if (userDetails && userDetails.trim().length > 0) {
+			const reportIds = state.evidenceRequests
+				.filter(request => request.round === state.round && request.method === "user_report")
+				.map(request => request.id);
+			const observation: EvidenceObservation = {
+				id: `observation-${Date.now().toString(36)}`,
+				requestIds: reportIds,
+				text: userDetails.trim(),
+				round: state.round,
+				addedAt: Date.now(),
+			};
+			state.evidenceObservations = [...state.evidenceObservations, observation];
+		}
+		const stillPending = pendingEvidenceRequests(state, state.round);
+		if (stillPending.length > 0 && ctx.hasUI) {
+			const confirmed = await ctx.ui.confirm(
+				"Proceed without all requested evidence?",
+				`${stillPending.length} evidence request(s) still pending (${stillPending.map(r => r.id).join(", ")}). Continue anyway?`,
+			);
+			if (!confirmed) {
+				pi.appendEntry(DEBUG_ENTRY, { ...state });
+				refreshUi();
+				return;
+			}
+		}
+
+		const hypotheses = describeHypotheses(summarizeHypotheses(readRunLines(run)));
+		const previousRound = state.round;
+		const previousSteps = state.reproductionSteps;
+		state.round += 1;
+		state.phase = "round";
+		state.hasRoundContent = false;
+		state.reproductionSteps = [];
+		state.gateNudges = 0;
+		if (!newRun()) {
+			state.round = previousRound;
+			state.phase = "waiting";
+			state.reproductionSteps = previousSteps;
+			ctx.ui.notify("debug-mode: could not initialize the next run log file; staying at the reproduction gate", "error");
+			refreshUi();
+			return;
+		}
+		unwatchLogFile();
+		refreshUi();
+
+		const summary = userDetails
+			? `proceed with user details — analyzing run ${run} (${logCount} entries)`
+			: `proceed — analyzing run ${run} (${logCount} entries)`;
+		pi.sendMessage(
+			{
+				customType: "debug-mode-proceed",
+				content: buildProceedMessage({
+					run,
+					logCount,
+					userDetails,
+					hypotheses,
+					evidenceSummary: evidenceSummary(state, previousRound),
+				}),
+				display: true,
+				details: { summary } satisfies DebugMessageDetails,
+			},
+			{ triggerTurn: true },
+		);
+	}
+
+	async function teardown(ctx: ExtensionContext, outcome: "finished" | "aborted"): Promise<void> {
+		unwatchLogFile();
+		lineCounter.clear();
+		if (state.debugDir) {
+			try {
+				fs.rmSync(state.debugDir, { recursive: true, force: true });
+				pruneDebugRoot(ctx.cwd);
+			} catch (err) {
+				pi.logger.warn("debug-mode: failed to remove debug dir", { err });
+			}
+		}
+		const scan = await syncLedger(state);
+		const probesLeft = [...scan.alive, ...scan.unknown];
+		Object.assign(state, freshState());
+		pi.appendEntry(DEBUG_ENTRY, { ...state });
+		refreshUi();
+		const resultLabel = outcome === "finished" ? "finished" : "aborted";
+		if (probesLeft.length > 0) {
+			ctx.ui.notify(
+				`Debug mode ${resultLabel}, but ${probesLeft.length} probe(s) remain in code: ${probesLeft.map(p => p.id).join(", ")} — remove manually. Applied fixes remain in the working diff.`,
+				"warning",
+			);
+		} else {
+			ctx.ui.notify(
+				`Debug mode ${resultLabel}. Log files removed; applied fixes remain in the working diff for review.`,
+				"info",
+			);
+		}
+	}
+
+	async function abortDebug(ctx: ExtensionContext): Promise<void> {
+		if (!state.active) {
+			ctx.ui.notify("debug-mode: not active", "error");
+			return;
+		}
+		if (ctx.hasUI) {
+			const confirmed = await ctx.ui.confirm(
+				"Abort debug mode?",
+				"Delete captured debug logs and stop the workflow? Applied code changes will remain in the working diff.",
+			);
+			if (!confirmed) return;
+		}
+		if (!state.active) return;
+		await teardown(ctx, "aborted");
+	}
+
+	/**
+	 * Attach one user-provided evidence file to the current waiting round. The
+	 * file is referenced in place — never copied, moved or deleted — and the
+	 * action stays at the gate: no model-visible message, no agent turn.
+	 */
+	async function attachEvidence(ctx: ExtensionContext, rawPath?: string, requestId: string | null = null): Promise<boolean> {
+		if (!ensureWaiting(ctx)) return false;
+		let input = rawPath?.trim() ?? "";
+		if (!input) {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(`Usage: /${COMMAND_EVIDENCE} <path>`, "error");
+				return false;
+			}
+			input = (await ctx.ui.input("Path to debug evidence file", "absolute or cwd-relative path")) ?? "";
+			if (!input.trim()) {
+				ctx.ui.notify("debug-mode: no evidence file path provided", "error");
+				return false;
+			}
+		}
+		const trimmed = input.trim();
+		const cwdRoot = path.resolve(ctx.cwd);
+		const resolved = path.resolve(cwdRoot, trimmed);
+		const outsideCwd = resolved !== cwdRoot && !resolved.startsWith(`${cwdRoot}${path.sep}`);
+		if (outsideCwd) {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(
+					`debug-mode: ${resolved} is outside the session working directory and cannot be confirmed without a UI`,
+					"error",
+				);
+				return false;
+			}
+			const confirmed = await ctx.ui.confirm(
+				"Attach evidence outside the working directory?",
+				`Record ${resolved} as debug evidence? The file is referenced in place and never modified.`,
+			);
+			if (!confirmed) return false;
+		}
+		const result = addEvidenceArtifact(state, trimmed, ctx.cwd, requestId);
+		if ("error" in result) {
+			ctx.ui.notify(`debug-mode: evidence rejected — ${result.error}`, "error");
+			return false;
+		}
+		Object.assign(state, result.state);
+		pi.appendEntry(DEBUG_ENTRY, { ...state });
+		refreshUi();
+		ctx.ui.notify(
+			`debug-mode: attached ${result.artifact.id} → ${result.artifact.path} (${result.artifact.size} bytes)`,
+			"info",
+		);
+		return true;
+}
+
+	// ============================== commands ==============================
+
+	pi.registerCommand(COMMAND_MODE, {
+		description: "Start debug mode: /debug-mode <problem description>",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			if (state.active) {
+				ctx.ui.notify(`debug-mode: already active (use /${COMMAND_STATUS}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT})`, "error");
+				return;
+			}
+			const problem = args.trim();
+			if (!problem) {
+				ctx.ui.notify(
+					"Usage: /debug-mode <problem description — symptoms, expected vs actual, how to reproduce>",
+					"error",
+				);
+				return;
+			}
+			startDebug(ctx, problem);
+		},
+	});
+
+	pi.registerCommand(COMMAND_DONE, {
+		description: "Mark the problem fixed: remove probes and summarize",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			await markDebugFixed(ctx);
+		},
+	});
+
+	pi.registerCommand(COMMAND_PROCEED, {
+		description: "Continue with captured evidence and optional user details: /debug-proceed [details]",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			const details = args.trim();
+			await advanceDebug(ctx, details || undefined);
+		},
+	});
+
+	/**
+	 * Parse `/debug-evidence [<request-id>] <path>`: when the first
+	 * whitespace-delimited token names a pending current-round user_artifact
+	 * request, link to it and treat the remainder (spaces intact) as the path;
+	 * otherwise the whole argument is an unlinked path.
+	 */
+	function parseEvidenceArgument(args: string): { requestId: string | null; rawPath: string | undefined } {
+		const trimmed = args.trim();
+		if (!trimmed) return { requestId: null, rawPath: undefined };
+		const firstToken = trimmed.split(/\s+/, 1)[0];
+		const isPending = pendingEvidenceRequests(state, state.round).some(
+			request => request.method === "user_artifact" && request.id === firstToken,
+		);
+		if (isPending) {
+			const rest = trimmed.slice(firstToken.length).trim();
+			return rest ? { requestId: firstToken, rawPath: rest } : { requestId: firstToken, rawPath: undefined };
+		}
+		return { requestId: null, rawPath: trimmed };
+	}
+
+	pi.registerCommand(COMMAND_EVIDENCE, {
+		description: "Attach one user-provided evidence file: /debug-evidence [<request-id>] <path> (no argument opens a path prompt)",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			const { requestId, rawPath } = parseEvidenceArgument(args);
+			await attachEvidence(ctx, rawPath, requestId);
+		},
+	});
+
+
+	pi.registerCommand(COMMAND_ABORT, {
+		description: "Abort debug mode: delete logs (fixes stay in the working diff)",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			await abortDebug(ctx);
+		},
+	});
+
+	pi.registerCommand(COMMAND_STATUS, {
+		description: "Show debug mode state",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			if (!state.active) {
+				ctx.ui.notify("debug-mode: idle", "info");
+				return;
+			}
+			refreshLogCounts();
+			const scan = await syncLedger(state);
+			const tallies = state.runId ? summarizeHypotheses(readRunLines(state.runId)) : [];
+			const roundRequests = state.evidenceRequests.filter(request => request.round === state.round);
+			const pending = pendingEvidenceRequests(state, state.round);
+			const unavailable = state.evidenceArtifacts.filter(artifact => {
+				try {
+					const stats = fs.statSync(artifact.path);
+					fs.accessSync(artifact.path, fs.constants.R_OK);
+					return !stats.isFile();
+				} catch {
+					return true;
+				}
+			});
+			ctx.ui.notify(
+				`debug-mode: phase=${state.phase} round=${state.round} run=${state.runId}\n` +
+					`${describeLedger(scan)}\n` +
+					`logs: ${state.runHistory.map(r => `${r}=${state.logCounts[r] ?? 0}`).join(", ") || "(none)"}\n` +
+					`this run by hypothesis: ${describeHypotheses(tallies)}\n` +
+					`current log file: ${logFileFor(state) ?? "(not initialized)"}\n` +
+					`evidence requests: ${roundRequests.map(r => `${r.id}[${r.method}] ${r.title}`).join("; ") || "(none)"}\n` +
+					`pending: ${pending.map(r => r.id).join(", ") || "(none)"}\n` +
+					`observations: ${state.evidenceObservations.map(o => o.id).join(", ") || "(none)"}\n` +
+					`artifacts: ${state.evidenceArtifacts.map(a => a.id).join(", ") || "(none)"}` +
+					(unavailable.length > 0 ? `\nunavailable artifacts: ${unavailable.map(a => `${a.id} ${a.path}`).join(", ")}` : ""),
+				"info",
+			);
+		},
+	});
+
+	// ============================== tools ==============================
+
+	registerDebugTools(pi, { state, refreshLogCounts, readRunLines });
+
+	// ============================== lifecycle ==============================
+
+	pi.on("session_start", async (_event, ctx) => {
+		uiCtx = ctx;
+		const entries = ctx.sessionManager.getEntries();
+		const last = entries
+			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === DEBUG_ENTRY)
+			.pop() as { data?: DebugState } | undefined;
+		if (last?.data?.active) {
+			Object.assign(state, last.data);
+			if (!Array.isArray(state.reproductionSteps)) state.reproductionSteps = [];
+			if (!Array.isArray(state.evidenceRequests)) state.evidenceRequests = [];
+			if (!Array.isArray(state.evidenceArtifacts)) state.evidenceArtifacts = [];
+			if (!Array.isArray(state.evidenceObservations)) state.evidenceObservations = [];
+			if (!Array.isArray(state.runHistory)) state.runHistory = state.runId ? [state.runId] : [];
+			if (typeof state.gateNudges !== "number") state.gateNudges = 0;
+			if (!state.phase) state.phase = "waiting";
+			if (!state.debugDir || !fs.existsSync(state.debugDir)) initializeLogDirectory(ctx);
+			const currentFile = logFileFor(state);
+			if (currentFile) {
+				try {
+					const legacyRunFile = state.debugDir && state.runId ? path.join(state.debugDir, `${state.runId}.jsonl`) : null;
+					if (!fs.existsSync(currentFile) && legacyRunFile && fs.existsSync(legacyRunFile)) {
+						fs.renameSync(legacyRunFile, currentFile);
+					}
+					fs.writeFileSync(currentFile, "", { flag: "a" });
+				} catch (err) {
+					pi.logger.error("debug-mode: cannot restore run log", { file: currentFile, err });
+				}
+			}
+			refreshLogCounts();
+			ctx.ui.notify(
+				`debug-mode resumed: phase=${state.phase} round=${state.round}, log=${currentFile ?? "unavailable"}; evidence: ${evidenceSummary(state, state.round)}. Use /${COMMAND_STATUS}, /${COMMAND_EVIDENCE}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT}.`,
+				"info",
+			);
+		}
+		refreshUi();
+		watchLogFile();
+	});
+
+	pi.on("turn_start", async () => {
+		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
+	});
+
+	pi.on("session_shutdown", async () => {
+		unwatchLogFile();
+	});
+}