@siuver/omp-debug-mode 0.1.3 → 0.1.5

package/src/debug-mode.ts

@@ -2,7 +2,8 @@ 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 { decideGate } from "./gate";
+import { describeEvidence, validateEvidenceArtifact } from "./evidence";
+import { describeOpenReason } from "./gate";
 import {
 	ACTIVE_LOG_FILE,
 	JsonlLineCounter,
@@ -11,46 +12,43 @@ import {
 	readJsonlLines,
 	summarizeHypotheses,
 } from "./log-files";
+import { type DebugEvent, type Effect, PROMPT_FIXED, PROMPT_PROCEED, PROMPT_START, reduce } from "./machine";
+import { CLEANUP_CONTRACT, METHODOLOGY, extractAssistantText } from "./methodology";
+import { type LedgerScan, describeLedger, probesInInput, scanLedger, survivingProbes } from "./probes";
 import {
-	CLEANUP_CONTRACT,
-	METHODOLOGY,
-	PROCEED_REMINDER,
-	buildFixedMessage,
-	buildProceedMessage,
-	buildStartMessage,
-	extractAssistantText,
-	extractReproductionSteps,
-} from "./methodology";
-import { describeLedger, recordProbes, syncLedger } from "./probes";
-import { REVIEW_ABORT, REVIEW_ADD_DETAILS, REVIEW_MARK_FIXED, REVIEW_PROCEED, reviewMenuOptions } from "./review-actions";
-import {
+	type DebugSession,
+	type DebugState,
 	DEBUG_CONTEXT_TYPE,
 	DEBUG_ENTRY,
-	type DebugState,
+	INACTIVE,
+	activeRunId,
 	blackboard,
 	compareRunIds,
-	freshState,
+	currentRound,
+	evidenceSummary,
+	evidenceView,
+	hasNonProbeEvidence,
 	keepLatestCustomType,
 	logFileFor,
+	pendingRequests,
+	reviveState,
 } from "./state";
 import { registerDebugTools } from "./tools";
-import { applyUi, reviewMenuTitle } from "./ui";
+import { applyUi } from "./ui";
 import { debugDirFor, excludeDebugLogsFromGit, pruneDebugRoot } from "./workspace";
 
 const COMMAND_MODE = "debug-mode";
-const COMMAND_MENU = "debug-menu";
 const COMMAND_DONE = "debug-done";
 const COMMAND_PROCEED = "debug-proceed";
-const COMMAND_NOTE = "debug-note";
+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-note": "reproduction details added — analyzing captured logs",
-	"debug-mode-fixed": "marked fixed — removing probes and summarizing",
+	[PROMPT_START]: "debug mode started — hypotheses and instrumentation",
+	[PROMPT_PROCEED]: "proceed — analyzing captured logs",
+	[PROMPT_FIXED]: "marked fixed — removing probes and summarizing",
 };
 
 interface DebugMessageDetails {
@@ -58,8 +56,7 @@ interface DebugMessageDetails {
 }
 
 export function registerDebugMode(pi: ExtensionAPI): void {
-	const state: DebugState = freshState();
-	let reviewMenuOpen = false;
+	let state: DebugState = INACTIVE;
 	let uiCtx: ExtensionContext | null = null;
 	let watchedLogFile: string | null = null;
 	const lineCounter = new JsonlLineCounter();
@@ -72,79 +69,142 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		pi.registerMessageRenderer<DebugMessageDetails>(customType, renderer);
 	}
 
-	// ============================== log files ==============================
+	// ============================== state plumbing ==============================
 
-	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;
+	/**
+	 * Cache-only events carry no effects, so they may run inside a render pass
+	 * without re-entering the UI refresh that asked for them.
+	 */
+	function absorbCache(event: Extract<DebugEvent, { t: "runs_observed" | "ledger_synced" }>): void {
+		state = reduce(state, event).state;
+	}
+
+	/** Run one event through the machine, then realise whatever it asked for. */
+	function dispatch(event: DebugEvent, ctx: ExtensionContext): string | null {
+		const transition = reduce(state, event);
+		// The reducer returns the previous object for a genuine no-op, so a turn
+		// full of tool calls does not append a state snapshot per message.
+		const changed = transition.state !== state;
+		state = transition.state;
+		if (changed) pi.appendEntry(DEBUG_ENTRY, { ...state });
+		refreshUi();
+		watchLogFile();
+		let continueContext: string | null = null;
+		for (const effect of transition.effects) {
+			const context = applyEffect(effect, ctx);
+			if (context) continueContext = context;
+		}
+		return continueContext;
+	}
+
+	function applyEffect(effect: Effect, ctx: ExtensionContext): string | null {
+		switch (effect.kind) {
+			case "notify":
+				ctx.ui.notify(effect.text, effect.level);
+				return null;
+			case "prompt":
+				pi.sendMessage(
+					{
+						customType: effect.customType,
+						content: effect.content,
+						display: true,
+						details: { summary: effect.summary } satisfies DebugMessageDetails,
+					},
+					{ triggerTurn: true },
+				);
+				return null;
+			case "continue":
+				return effect.context;
+			case "teardown": {
+				unwatchLogFile();
+				lineCounter.clear();
+				if (effect.debugDir) {
+					try {
+						fs.rmSync(effect.debugDir, { recursive: true, force: true });
+						pruneDebugRoot(ctx.cwd);
+					} catch (err) {
+						pi.logger.warn("debug-mode: failed to remove debug dir", { err });
+					}
+				}
+				const label = effect.outcome === "finished" ? "finished" : "aborted";
+				if (effect.probesLeft.length > 0) {
+					ctx.ui.notify(
+						`Debug mode ${label}, but ${effect.probesLeft.length} probe(s) remain in code: ${effect.probesLeft.map(p => p.id).join(", ")} — remove manually. Applied fixes remain in the working diff.`,
+						"warning",
+					);
+				} else {
+					ctx.ui.notify(
+						`Debug mode ${label}. Log files removed; applied fixes remain in the working diff for review.`,
+						"info",
+					);
+				}
+				return null;
+			}
 		}
 	}
 
+	function refreshUi(): void {
+		applyUi(uiCtx, state, currentLogCount);
+	}
+
+	// ============================== log files ==============================
+
 	function readRunLines(run: string): string[] {
-		return readJsonlLines(logFileFor(state, run));
+		return state.active ? readJsonlLines(logFileFor(state, run)) : [];
 	}
 
+	/** Re-count every run on disk. Pure cache maintenance — never a decision. */
 	function refreshLogCounts(): void {
-		const runs = new Set(Object.keys(state.logCounts));
-		if (state.debugDir) {
+		if (!state.active) return;
+		const session: DebugSession = state;
+		const active = activeRunId(session);
+		const runs = new Set(Object.keys(session.logCounts));
+		if (session.debugDir) {
 			try {
-				for (const file of fs.readdirSync(state.debugDir)) {
+				for (const file of fs.readdirSync(session.debugDir)) {
 					if (!file.endsWith(".jsonl")) continue;
 					if (file === ACTIVE_LOG_FILE) {
-						if (state.runId) runs.add(state.runId);
+						if (active) runs.add(active);
 					} else {
 						runs.add(file.replace(/\.jsonl$/, ""));
 					}
 				}
 			} catch {}
 		}
-		for (const run of runs) state.logCounts[run] = lineCounter.count(logFileFor(state, run));
-		adoptDiscoveredRuns(runs);
+		const logCounts: Record<string, number> = {};
+		for (const run of runs) logCounts[run] = lineCounter.count(logFileFor(session, run));
+		absorbCache({ t: "runs_observed", runHistory: orderedHistory(session, runs), logCounts });
 	}
 
 	/** 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);
+	function orderedHistory(session: DebugSession, runs: Iterable<string>): string[] {
+		const active = activeRunId(session);
+		const missing = [...runs].filter(run => run !== active && !session.runHistory.includes(run));
+		if (missing.length === 0) return session.runHistory;
+		const completed = session.runHistory.filter(run => run !== active).concat(missing);
 		completed.sort(compareRunIds);
-		state.runHistory = active ? [...completed, active] : completed;
+		return active ? [...completed, active] : completed;
 	}
 
 	function currentLogCount(): number {
 		refreshLogCounts();
-		return state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
+		if (!state.active) return 0;
+		const run = activeRunId(state);
+		return run ? (state.logCounts[run] ?? 0) : 0;
 	}
 
-	function newRun(): string | null {
-		if (!state.debugDir) return null;
-		const run = `run${state.round}-${Date.now().toString(36)}`;
+	/** Archive the active log, truncate it for the next reproduction, and name the run. */
+	function createRun(debugDir: string, round: number, previousRun: string | null): string | null {
 		try {
-			prepareRunLog(state.debugDir, state.runId);
+			prepareRunLog(debugDir, previousRun);
 		} catch (err) {
 			pi.logger.error("debug-mode: cannot initialize run log", {
-				file: path.join(state.debugDir, ACTIVE_LOG_FILE),
+				file: path.join(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);
+		return `run${round}-${Date.now().toString(36)}`;
 	}
 
 	/**
@@ -153,13 +213,13 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 	 * refresh the widget as observations land.
 	 */
 	function watchLogFile(): void {
-		const file = state.phase === "waiting" ? logFileFor(state) : null;
+		const file = state.active && state.stage === "awaiting_evidence" ? 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 (!state.active || state.stage !== "awaiting_evidence") return;
 				if (curr.mtimeMs === prev.mtimeMs && curr.size === prev.size) return;
 				try {
 					refreshUi();
@@ -185,25 +245,34 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 
 	// ============================== probe ledger ==============================
 
+	/** Rescan the recorded files so the ledger matches the code on disk. */
+	async function syncLedger(): Promise<LedgerScan> {
+		const scan = await scanLedger(state.active ? state.probes : []);
+		if (state.active) absorbCache({ t: "ledger_synced", probes: survivingProbes(scan) });
+		return scan;
+	}
+
 	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);
+		const probes = probesInInput(event.input as Record<string, unknown>, ctx.cwd, currentRound(state).index);
+		if (probes.length > 0) dispatch({ t: "probes_found", probes }, ctx);
 	});
 
 	// ============================== prompt injection ==============================
 
 	pi.on("before_agent_start", async () => {
-		if (!state.active || (state.phase !== "round" && state.phase !== "cleanup")) return;
+		if (!state.active || state.stage === "awaiting_evidence") return;
 		// The blackboard claims to be ground truth, so reconcile it with disk first.
-		await syncLedger(state);
+		await syncLedger();
+		if (!state.active) return;
 		// Cleanup has no hypotheses left to form; the full methodology would only
 		// invite another round.
-		const contract = state.phase === "cleanup" ? CLEANUP_CONTRACT : METHODOLOGY;
+		const contract = state.stage === "cleaning_up" ? CLEANUP_CONTRACT : METHODOLOGY;
 		return {
 			message: {
 				customType: DEBUG_CONTEXT_TYPE,
-				content: `${blackboard(state)}\n\n${contract}`,
+				content: `${blackboard(state, describeEvidence(evidenceView(state)))}\n\n${contract}`,
 				display: false,
 			},
 		};
@@ -217,229 +286,141 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		if (filtered.length !== event.messages.length) return { messages: filtered };
 	});
 
-	// ============================== round lifecycle ==============================
+	// ============================== turn lifecycle ==============================
 
-	pi.on("agent_start", async () => {
-		if (state.active) state.hasRoundContent = false;
+	pi.on("agent_start", async (_event, ctx) => {
+		if (state.active) dispatch({ t: "turn_started" }, ctx);
 	});
 
-	pi.on("message_end", async (event) => {
+	pi.on("message_end", async (event, ctx) => {
 		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 steps = extractReproductionSteps(extractAssistantText(msg.content));
-			if (steps.length > 0) state.reproductionSteps = steps;
-		}
+		if (msg?.role !== "assistant") return;
+		dispatch({ t: "assistant_message", text: extractAssistantText(msg.content) }, ctx);
 	});
 
 	pi.on("session_stop", async (_event, ctx) => {
-		if (!state.active) return;
-		if (state.phase === "cleanup") {
-			// Cleanup turn settled: keep fixes and remove the temporary logs.
-			if (state.cleanupReady) await teardown(ctx, "finished");
-			return;
-		}
-		if (state.phase !== "round" || !state.hasRoundContent) return;
-
-		const probesThisRound = state.probes.filter(p => p.round === state.round).length;
-		const decision = decideGate({
-			hasReproductionSteps: state.reproductionSteps.length > 0,
-			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);
+		if (!state.active || !state.turnProduced) return;
+		if (state.stage !== "investigating" && state.stage !== "cleaning_up") return;
+		// A declared runtime_probe must be backed by a marker that is really on
+		// disk, so the ledger is reconciled before the round may close.
+		await syncLedger();
+		const context = dispatch({ t: "turn_settled" }, ctx);
+		if (context) return { continue: true, additionalContext: context };
 	});
 
-	function enterGate(ctx: ExtensionContext, probesThisRound: number, missingSteps: boolean): void {
-		state.phase = "waiting";
-		pi.appendEntry(DEBUG_ENTRY, { ...state });
-		refreshUi();
-		watchLogFile();
-		scheduleReviewMenu(ctx);
-		if (probesThisRound === 0) {
+	registerDebugTools(pi, { getState: () => state, refreshLogCounts, readRunLines, syncLedger });
+
+	// ============================== command guards ==============================
+
+	function activeSession(ctx: ExtensionContext): DebugSession | null {
+		if (!state.active) {
+			ctx.ui.notify("debug-mode: not active", "error");
+			return null;
+		}
+		return state;
+	}
+
+	function ownsTurn(session: DebugSession): boolean {
+		return session.stage === "awaiting_evidence" || session.stage === "open";
+	}
+
+	/**
+	 * The debug commands belong to the user's turn. An unclosed round is still
+	 * the user's move, so it gets a confirmation rather than the flat "not
+	 * waiting for reproduction" refusal that made an open round look stuck.
+	 */
+	async function claimTurn(ctx: ExtensionContext, action: string): Promise<boolean> {
+		const session = activeSession(ctx);
+		if (!session) return false;
+		if (!ownsTurn(session)) {
 			ctx.ui.notify(
-				`Debug round ${state.round} paused, but it added no probes — this round cannot produce runtime evidence. Use /${COMMAND_MENU} and Proceed to ask for instrumentation.`,
-				"warning",
+				`debug-mode: the agent still has round ${currentRound(session).index} (stage: ${session.stage}) — wait for it to stop.`,
+				"error",
 			);
-		} else if (missingSteps) {
-			ctx.ui.notify(
-				`Debug round ${state.round} paused without reproduction steps. Exercise the instrumented path, then ${PROCEED_REMINDER}`,
-				"warning",
+			return false;
+		}
+		if (session.stage === "open" && ctx.hasUI) {
+			const confirmed = await ctx.ui.confirm(
+				`${action} an unclosed round?`,
+				`${describeOpenReason(currentRound(session).openReason ?? "awaiting_reply", currentRound(session).index)} Continue with the evidence that exists?`,
 			);
-		} else {
-			ctx.ui.notify(`Debug round ${state.round} paused. Reproduce the bug, then ${PROCEED_REMINDER}`, "info");
+			if (!confirmed) return false;
 		}
+		return true;
 	}
 
 	// ============================== round transitions ==============================
 
 	function startDebug(ctx: ExtensionContext, problem: string): void {
-		if (!initializeLogDirectory(ctx)) {
+		const debugDir = debugDirFor(ctx.cwd, ctx.sessionManager.getSessionId());
+		try {
+			fs.mkdirSync(debugDir, { recursive: true });
+			excludeDebugLogsFromGit(ctx.cwd);
+		} catch (err) {
+			pi.logger.error("debug-mode: cannot create log dir", { dir: debugDir, err });
 			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;
-		if (!newRun()) {
-			Object.assign(state, freshState());
+		const runId = createRun(debugDir, 1, null);
+		if (!runId) {
 			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 },
-		);
+		dispatch({ t: "start", problem, debugDir, runId, logFile: path.join(debugDir, ACTIVE_LOG_FILE) }, ctx);
 	}
 
-	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();
-		if (logCount === 0 && ctx.hasUI) {
+	async function advanceDebug(ctx: ExtensionContext, userDetails?: string): Promise<void> {
+		if (!(await claimTurn(ctx, "Proceed from"))) return;
+		refreshLogCounts();
+		if (!state.active) return;
+		const closingRun = activeRunId(state);
+		const logCount = closingRun ? (state.logCounts[closingRun] ?? 0) : 0;
+		if (logCount === 0 && !userDetails && !hasNonProbeEvidence(currentRound(state)) && 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?",
+				"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;
-
-		state.phase = "cleanup";
-		state.cleanupReady = false;
-		unwatchLogFile();
-		refreshUi();
-		pi.sendMessage(
-			{
-				customType: "debug-mode-fixed",
-				content: buildFixedMessage(JSON.stringify(state.probes)),
-				display: true,
-				details: { summary: `marked fixed — removing ${state.probes.length} probe(s)` } satisfies DebugMessageDetails,
-			},
-			{ triggerTurn: true },
-		);
-	}
-
-	async function advanceDebug(ctx: ExtensionContext, reproductionDetails?: string): Promise<void> {
-		if (!ensureWaiting(ctx)) return;
-		refreshLogCounts();
-		const run = state.runId ?? "(none)";
-		const logCount = state.logCounts[run] ?? 0;
-		if (logCount === 0 && !reproductionDetails && ctx.hasUI) {
+		if (!state.active) return;
+		const stillPending = pendingRequests(state);
+		if (stillPending.length > 0 && 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?",
+				"Proceed without all requested evidence?",
+				`${stillPending.length} evidence request(s) still pending (${stillPending.map(r => r.id).join(", ")}). Continue anyway?`,
 			);
 			if (!confirmed) return;
 		}
-		if (!state.active || state.phase !== "waiting") 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();
+		if (!state.active || !ownsTurn(state) || !state.debugDir) return;
+
+		// The digest must be read before the active log is archived and truncated.
+		const hypotheses = describeHypotheses(summarizeHypotheses(closingRun ? readRunLines(closingRun) : []));
+		const runId = createRun(state.debugDir, currentRound(state).index + 1, closingRun);
+		if (!runId) {
+			ctx.ui.notify("debug-mode: could not initialize the next run log file; staying on this round", "error");
 			return;
 		}
-		unwatchLogFile();
-		refreshUi();
-
-		const summary = reproductionDetails
-			? `reproduction details added — analyzing run ${run} (${logCount} entries)`
-			: `proceed — analyzing run ${run} (${logCount} entries)`;
-		pi.sendMessage(
-			{
-				customType: reproductionDetails ? "debug-mode-note" : "debug-mode-proceed",
-				content: buildProceedMessage({ run, logCount, reproductionDetails, hypotheses }),
-				display: true,
-				details: { summary } satisfies DebugMessageDetails,
-			},
-			{ triggerTurn: true },
-		);
+		dispatch({ t: "proceed", runId, logCount, hypotheses, details: userDetails, now: Date.now() }, ctx);
 	}
 
-	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 markDebugFixed(ctx: ExtensionContext): Promise<void> {
+		if (!(await claimTurn(ctx, "Mark as fixed from"))) return;
+		const logCount = currentLogCount();
+		if (!state.active) return;
+		if (logCount === 0 && !hasNonProbeEvidence(currentRound(state)) && 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 || !ownsTurn(state)) return;
+		dispatch({ t: "mark_fixed" }, ctx);
 	}
 
 	async function abortDebug(ctx: ExtensionContext): Promise<void> {
-		if (!state.active) {
-			ctx.ui.notify("debug-mode: not active", "error");
-			return;
-		}
+		if (!activeSession(ctx)) return;
 		if (ctx.hasUI) {
 			const confirmed = await ctx.ui.confirm(
 				"Abort debug mode?",
@@ -448,53 +429,59 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 			if (!confirmed) return;
 		}
 		if (!state.active) return;
-		await teardown(ctx, "aborted");
+		dispatch({ t: "abort" }, ctx);
 	}
 
 	/**
-	 * Open the action menu after `session_stop` has returned. Awaiting it
-	 * inside that handler would hold the agent-loop lock for the whole
-	 * reproduction; the microtask lets the round settle first.
+	 * Attach one user-provided evidence file to the current round. The file is
+	 * referenced in place — never copied, moved or deleted — and the action does
+	 * not advance the workflow: no model-visible message, no agent turn.
 	 */
-	function scheduleReviewMenu(ctx: ExtensionContext): void {
-		if (!ctx.hasUI) return;
-		queueMicrotask(() => {
-			openReviewMenu(ctx).catch(err => {
-				pi.logger.warn("debug-mode: review menu failed to open", { err });
-			});
-		});
-	}
-
-	async function openReviewMenu(ctx: ExtensionContext): Promise<void> {
-		if (!ensureWaiting(ctx)) return;
-		if (!ctx.hasUI) {
-			ctx.ui.notify(`/${COMMAND_MENU} requires an interactive UI; use /${COMMAND_DONE} or /${COMMAND_PROCEED} instead.`, "warning");
-			return;
+	async function attachEvidence(ctx: ExtensionContext, rawPath?: string, requestId: string | null = null): Promise<boolean> {
+		const session = activeSession(ctx);
+		if (!session) return false;
+		if (!ownsTurn(session)) {
+			ctx.ui.notify(`debug-mode: cannot attach evidence while the agent is working (stage: ${session.stage})`, "error");
+			return false;
 		}
-		if (reviewMenuOpen) {
-			ctx.ui.notify("debug-mode: review menu is already open", "info");
-			return;
+		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;
+			}
 		}
-
-		reviewMenuOpen = true;
-		try {
-			const probesThisRound = state.probes.filter(p => p.round === state.round).length;
-			const title = reviewMenuTitle(state.round, currentLogCount(), probesThisRound);
-			const choice = await ctx.ui.select(title, reviewMenuOptions());
-			if (!choice) return;
-			if (choice === REVIEW_MARK_FIXED) {
-				await markDebugFixed(ctx);
-			} else if (choice === REVIEW_PROCEED) {
-				await advanceDebug(ctx);
-			} else if (choice === REVIEW_ADD_DETAILS) {
-				ctx.ui.setEditorText("/debug-note ");
-				ctx.ui.notify("Add reproduction details in the editor, then submit /debug-note.", "info");
-			} else if (choice === REVIEW_ABORT) {
-				await abortDebug(ctx);
+		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;
 			}
-		} finally {
-			reviewMenuOpen = 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 validation = validateEvidenceArtifact(trimmed, ctx.cwd);
+		if (!validation.ok) {
+			ctx.ui.notify(`debug-mode: evidence rejected — ${validation.reason}`, "error");
+			return false;
 		}
+		if (!state.active) return false;
+		dispatch({ t: "attach_artifact", candidate: validation.artifact, requestId, now: Date.now() }, ctx);
+		return true;
 	}
 
 	// ============================== commands ==============================
@@ -504,7 +491,7 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		handler: async (args, ctx) => {
 			uiCtx = ctx;
 			if (state.active) {
-				ctx.ui.notify(`debug-mode: already active (use /${COMMAND_MENU}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT})`, "error");
+				ctx.ui.notify(`debug-mode: already active (use /${COMMAND_STATUS}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT})`, "error");
 				return;
 			}
 			const problem = args.trim();
@@ -528,31 +515,40 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand(COMMAND_PROCEED, {
-		description: "Continue with captured logs: evaluate hypotheses, fix only with evidence",
-		handler: async (_args, ctx) => {
+		description: "Continue with captured evidence and optional user details: /debug-proceed [details]",
+		handler: async (args, ctx) => {
 			uiCtx = ctx;
-			await advanceDebug(ctx);
+			const details = args.trim();
+			await advanceDebug(ctx, details || undefined);
 		},
 	});
 
-	pi.registerCommand(COMMAND_MENU, {
-		description: "Open the interactive action menu for a completed debug round",
-		handler: async (_args, ctx) => {
-			uiCtx = ctx;
-			await openReviewMenu(ctx);
-		},
-	});
+	/**
+	 * 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 =
+			state.active &&
+			pendingRequests(state).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_NOTE, {
-		description: "Add reproduction details and continue: /debug-note <details>",
+	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 details = args.trim();
-			if (!details) {
-				ctx.ui.notify("Usage: /debug-note <reproduction details>", "error");
-				return;
-			}
-			await advanceDebug(ctx, details);
+			const { requestId, rawPath } = parseEvidenceArgument(args);
+			await attachEvidence(ctx, rawPath, requestId);
 		},
 	});
 
@@ -573,23 +569,40 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 				return;
 			}
 			refreshLogCounts();
-			const scan = await syncLedger(state);
-			const tallies = state.runId ? summarizeHypotheses(readRunLines(state.runId)) : [];
+			const scan = await syncLedger();
+			if (!state.active) return;
+			const session: DebugSession = state;
+			const round = currentRound(session);
+			const run = activeRunId(session);
+			const tallies = run ? summarizeHypotheses(readRunLines(run)) : [];
+			const requests = round.plan ?? [];
+			const pending = pendingRequests(session, round);
+			const unavailable = session.artifacts.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` +
+				`debug-mode: stage=${session.stage} round=${round.index} run=${run ?? "(none)"}\n` +
+					(round.openReason ? `${describeOpenReason(round.openReason, round.index)}\n` : "") +
 					`${describeLedger(scan)}\n` +
-					`logs: ${state.runHistory.map(r => `${r}=${state.logCounts[r] ?? 0}`).join(", ") || "(none)"}\n` +
+					`logs: ${session.runHistory.map(r => `${r}=${session.logCounts[r] ?? 0}`).join(", ") || "(none)"}\n` +
 					`this run by hypothesis: ${describeHypotheses(tallies)}\n` +
-					`current log file: ${logFileFor(state) ?? "(not initialized)"}`,
+					`current log file: ${logFileFor(session) ?? "(not initialized)"}\n` +
+					`evidence requests: ${requests.map(r => `${r.id}[${r.method}] ${r.title}`).join("; ") || "(none)"}\n` +
+					`pending: ${pending.map(r => r.id).join(", ") || "(none)"}\n` +
+					`observations: ${session.observations.map(o => o.id).join(", ") || "(none)"}\n` +
+					`artifacts: ${session.artifacts.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) => {
@@ -597,18 +610,24 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		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.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);
+			.pop() as { data?: unknown } | undefined;
+		state = reviveState(last?.data);
+		if (state.active) {
+			if (!state.debugDir || !fs.existsSync(state.debugDir)) {
+				const debugDir = debugDirFor(ctx.cwd, ctx.sessionManager.getSessionId());
+				try {
+					fs.mkdirSync(debugDir, { recursive: true });
+					excludeDebugLogsFromGit(ctx.cwd);
+					state = { ...state, debugDir };
+				} catch (err) {
+					pi.logger.error("debug-mode: cannot restore log dir", { dir: debugDir, err });
+				}
+			}
 			const currentFile = logFileFor(state);
 			if (currentFile) {
 				try {
-					const legacyRunFile = state.debugDir && state.runId ? path.join(state.debugDir, `${state.runId}.jsonl`) : null;
+					const run = activeRunId(state);
+					const legacyRunFile = state.debugDir && run ? path.join(state.debugDir, `${run}.jsonl`) : null;
 					if (!fs.existsSync(currentFile) && legacyRunFile && fs.existsSync(legacyRunFile)) {
 						fs.renameSync(legacyRunFile, currentFile);
 					}
@@ -618,18 +637,15 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 				}
 			}
 			refreshLogCounts();
-			ctx.ui.notify(
-				`debug-mode resumed: phase=${state.phase} round=${state.round}, log=${currentFile ?? "unavailable"}. Use /${COMMAND_STATUS}, /${COMMAND_MENU}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT}.`,
-				"info",
-			);
+			if (state.active) {
+				ctx.ui.notify(
+					`debug-mode resumed: stage=${state.stage} round=${currentRound(state).index}, log=${currentFile ?? "unavailable"}; evidence: ${evidenceSummary(state)}. Use /${COMMAND_STATUS}, /${COMMAND_EVIDENCE}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT}.`,
+					"info",
+				);
+			}
 		}
 		refreshUi();
 		watchLogFile();
-		if (state.active && state.phase === "waiting") scheduleReviewMenu(ctx);
-	});
-
-	pi.on("turn_start", async () => {
-		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
 	});
 
 	pi.on("session_shutdown", async () => {