@siuver/omp-debug-mode 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.2 - 2026-08-20
+
+- Added an interactive round-review menu with Mark as fixed, Proceed, Add reproduction details, and Abort actions.
+- Added `/debug-review` to reopen the menu and `/debug-note <details>` to return to the editor, add user evidence, and continue the workflow.
+- Kept `/debug-done fixed|proceed` as compatible shortcuts and added interactive confirmation for zero-log completion, zero-log progression, and abort.
+
+## 0.1.1 - 2026-08-20
+
+- Replaced the localhost HTTP collector with direct JSONL file appends from instrumented runtime code.
+- The injected prompt now supplies the exact absolute log file and explicitly forbids POST, sockets, and other network transports.
+- Updated log analysis, status reporting, and session resume to read JSONL directly; active probes use a stable `current.jsonl` path while completed rounds are archived by run id.
+
 ## 0.1.0 - 2026-08-20
 
 - Initial npm release of the Cursor Debug Mode replica for OMP.

package/README.md

@@ -9,28 +9,50 @@ The plugin makes the agent form hypotheses, add temporary runtime probes, attemp
 | Command | Purpose |
 | --- | --- |
 | `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
+| `/debug-review` | Reopens the interactive action menu for the completed round. |
+| `/debug-note <details>` | Adds reproduction details from the editor and starts the next evidence-driven round. |
 | `/debug-status` | Shows the current phase, round, run, live probes, and captured log counts. |
-| `/debug-done fixed` | Confirms the fix and asks the agent to remove every probe and summarize the root cause and final change. |
-| `/debug-done proceed` | Reports that the issue remains, asks the agent to analyze the captured logs, and starts another hypothesis/instrument/fix round. |
-| `/debug-abort` | Stops debug mode and removes its logs while leaving code changes in the working tree. |
+| `/debug-done fixed` | Non-menu shortcut that confirms the fix and asks the agent to remove every probe and summarize the result. |
+| `/debug-done proceed` | Non-menu shortcut that analyzes the captured logs and starts another hypothesis/instrument/fix round. |
+| `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
+
+## Interactive Round Review
+
+When the Agent completes a debugging round, the plugin enters the reproduction gate and opens an action menu:
+
+- **Mark as fixed** - asks the Agent to clean up probes and summarize the root cause and fix. If the round captured no runtime logs, the plugin asks for confirmation first.
+- **Proceed with captured logs** - refreshes the log file at selection time, archives the completed run, and starts the next analysis and fix round. If no runtime observations exist, the plugin asks for confirmation before proceeding.
+- **Add reproduction details** - closes the menu and pre-fills the editor with `/debug-note ` so you can add symptoms, environment details, or reproduction results before continuing.
+- **Abort debug mode** - asks for confirmation, removes debug logs, and keeps applied code changes.
+
+Pressing `Esc` simply closes the menu and leaves the workflow at the reproduction gate. After reproducing the issue in another application, run `/debug-review` to reopen it. The existing `/debug-done fixed|proceed` commands remain available for non-interactive and shortcut use.
 
 ## Workflow
 
 1. Run `/debug-mode <problem description>`.
-2. The agent investigates, records hypotheses, inserts minimal probes marked with `@omp-probe <id>`, and attempts a fix.
-3. When the agent stops, reproduce the issue in the real application.
-4. Run `/debug-done fixed` if the issue is resolved, or `/debug-done proceed` to analyze evidence and continue.
-5. On success, the agent removes all probes, verifies the probe ledger is empty, and summarizes the root cause and fix.
+2. The Agent investigates, records hypotheses, inserts minimal probes marked with `@omp-probe <id>`, and attempts a fix. The injected prompt strongly requires every probe to append runtime observations directly to the exact JSONL path; console output is supplemental only.
+3. When the Agent stops, dismiss the review menu if necessary and reproduce the issue in the real application so the instrumented code writes its observations.
+4. Reopen `/debug-review` and mark the issue fixed, proceed with logs, or return to the editor to submit `/debug-note <details>`.
 
-The extension also provides the read-only `get_debug_logs` and `list_debug_probes` tools so the agent can inspect runtime evidence and verify cleanup.
+The extension also provides the read-only `get_debug_logs` and `list_debug_probes` tools so the Agent can inspect runtime evidence and verify cleanup.
 
 ## Runtime Data
 
-During an active session, the plugin starts a local HTTP server on `127.0.0.1:7842`. Instrumentation posts `{ "probe": "...", "data": ... }` to `/log`, and the plugin appends the entries to `<project>/.omp/debug/<run>.jsonl`.
+At the start of each round, the plugin creates an absolute log path:
+
+```text
+<project>/.omp/debug/current.jsonl
+```
+
+That exact stable path is injected into the Agent prompt. The prompt requires every runtime probe to use the target environment's native file append API and write one compact JSON object plus a newline using this schema:
+
+```json
+{"probe":"player-state","ts":1787193600000,"data":{"isGrounded":false}}
+```
 
-The server only listens on localhost. Debug data may still contain values captured from your application, so review probe payloads before reproducing sensitive workflows. Finishing or aborting debug mode removes the debug log directory. Applied fixes remain in the working tree for review.
+If the log file contains zero entries, treat that as instrumentation or execution-path evidence. Check the build, path permissions, code path, and file append errors; do not ask the user to copy Unity Console output. Use `/debug-note` for reproduction details, not manual console transcription.
 
-Debug state is recorded in the OMP session so an active workflow can resume after reopening the session. Port `7842` must be available for probes to report data.
+When you proceed from the review menu, `/debug-done proceed`, or `/debug-note`, the plugin archives the completed file as `<run-id>.jsonl`, creates an empty `current.jsonl` for the next reproduction, and makes the Agent analyze the archived evidence through `get_debug_logs`. `/debug-status` shows the current absolute file path and log count.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siuver/omp-debug-mode",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "A Cursor Debug Mode replica for evidence-driven, human-in-the-loop debugging in oh-my-pi.",
   "license": "MIT",

package/src/log-files.ts

@@ -0,0 +1,46 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const ACTIVE_LOG_FILE = "current.jsonl";
+
+export function resolveRunLogFile(
+	debugDir: string | null,
+	run: string | null,
+	activeRun: string | null,
+): string | null {
+	if (!debugDir || !run) return null;
+	return path.join(debugDir, run === activeRun ? ACTIVE_LOG_FILE : `${run}.jsonl`);
+}
+
+export function readJsonlLines(file: string | null): string[] {
+	if (!file) return [];
+	try {
+		return fs
+			.readFileSync(file, "utf8")
+			.split(/\r?\n/)
+			.filter(line => line.trim().length > 0);
+	} catch {
+		return [];
+	}
+}
+
+export function prepareRunLog(debugDir: string, previousRun: string | null): string {
+	const activeFile = path.join(debugDir, ACTIVE_LOG_FILE);
+	const archivedFile = previousRun ? path.join(debugDir, `${previousRun}.jsonl`) : null;
+
+	try {
+		if (archivedFile) {
+			if (fs.existsSync(activeFile)) fs.copyFileSync(activeFile, archivedFile);
+			else fs.writeFileSync(archivedFile, "", { flag: "a" });
+		}
+		fs.writeFileSync(activeFile, "", { flag: "w" });
+		return activeFile;
+	} catch (error) {
+		if (archivedFile) {
+			try {
+				fs.rmSync(archivedFile, { force: true });
+			} catch {}
+		}
+		throw error;
+	}
+}

package/src/main.ts

@@ -5,29 +5,27 @@
  *   IDLE → /debug-mode <problem>
  *   → agent hypothesizes, adds @omp-probe instrumentation, attempts a fix
  *   → WAITING_REPRO: agent stops; user reproduces out-of-band
- *   → /debug-done fixed   → agent removes probes + summarizes → teardown (logs deleted)
- *   → /debug-done proceed → agent analyzes captured logs, re-instruments + fixes → loop
+ *   → Mark as fixed → agent removes probes + summarizes → teardown (logs deleted)
+ *   → Proceed/add details → agent analyzes logs, re-instruments + fixes → loop
  *
- * Components:
- * - Local log server (Bun.serve, 127.0.0.1:7842) — probes POST {probe, data};
- *   logs append to <cwd>/.omp/debug/<run>.jsonl
+ * - Stable JSONL file at <cwd>/.omp/debug/current.jsonl — runtime probes append
+ *   observations directly with the target environment's native file APIs
  * - Probe ledger: tool_call interception on edit/write records @omp-probe ids;
  *   ground truth is rescanned from disk (checkLedger)
  * - Tools: get_debug_logs, list_debug_probes
- * - Commands: /debug-mode, /debug-status, /debug-done fixed|proceed, /debug-abort
+ * - Commands: /debug-mode, /debug-review, /debug-note, /debug-status, /debug-done, /debug-abort
  */
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
-import type { Server } from "bun";
-import type { WriteStream } from "node:fs";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { ACTIVE_LOG_FILE, prepareRunLog, readJsonlLines, resolveRunLogFile } from "./log-files";
+import { REVIEW_ABORT, REVIEW_ADD_DETAILS, REVIEW_MARK_FIXED, REVIEW_OPTIONS, REVIEW_PROCEED } from "./review-actions";
 
 const DEBUG_ENTRY = "com.omp.debug-mode.state";
 const PROBE_MARK = /@omp-probe\s+([A-Za-z0-9_-]+)/g;
-const DEFAULT_PORT = 7842;
-
 type Phase = "idle" | "round" | "waiting" | "cleanup";
 
+
 interface Probe {
 	id: string;
 	file: string;
@@ -47,17 +45,10 @@ interface DebugState {
 	cleanupReady: boolean;
 }
 
-interface LogEntry {
-	run: string;
-	probe: string;
-	ts: number;
-	data: unknown;
-}
 
 function freshState(): DebugState {
 	return {
 		active: false,
-		phase: "idle",
 		problem: "",
 		round: 0,
 		runId: null,
@@ -76,6 +67,10 @@ function probeIdsIn(text: unknown): string[] {
 	return ids;
 }
 
+function logFileFor(s: DebugState, run = s.runId): string | null {
+	return resolveRunLogFile(s.debugDir, run, s.runId);
+}
+
 function blackboard(s: DebugState): string {
 	const probes = s.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
 	const counts = Object.entries(s.logCounts)
@@ -90,8 +85,9 @@ ${s.problem}
 Deployed probes (ground truth, maintained by the extension):
   ${probes}
 
-Log endpoint for probes: POST JSON {probe, data} to http://127.0.0.1:${DEFAULT_PORT}/log
-Probe code MUST carry the marker comment \`// @omp-probe <id>\` adjacent to it.
+Current run log file (absolute path): ${logFileFor(s) ?? "(not initialized)"}
+Runtime probes MUST append JSONL directly to that exact file using the target environment's native file APIs.
+Console output such as Unity Debug.Log may supplement diagnostics but is never the runtime evidence for this workflow. Never ask the user to transcribe console output.
 Logs by run: ${counts}
 Current run id: ${s.runId ?? "(not started)"}`;
 }
@@ -101,99 +97,85 @@ const METHODOLOGY = `\
 Each round consists of, in order:
 1. Restate hypotheses (mark each: pending / ruled-out / confirmed via runtime evidence).
 2. Update instrumentation: remove probes that yielded no information, add probes that
-   discriminate between remaining hypotheses. Each probe is one minimal statement sending
-   JSON via HTTP POST to the log endpoint, with the marker comment \`// @omp-probe <id>\`
-   adjacent (language-appropriate; keep the block small and easy to remove).
+   discriminate between remaining hypotheses. Every runtime probe MUST append exactly
+   one compact JSON object plus a newline to the exact absolute log file shown above.
+   Use {"probe":"<id>","ts":<epoch-ms>,"data":<JSON-serializable-observation>}.
+   Append; never overwrite or truncate. Open, append, flush, and close promptly for each
+   observation. Do not use HTTP, POST, localhost, sockets, or any network transport.
+   Use the target environment's native file API and ensure the code path writes the file.
+   Console logging may supplement the file but never replaces it. Do not ask the user to
+   copy or summarize console output.
 3. ATTEMPT A FIX for your leading hypothesis in the same round. Instrumentation without
    a fix is an incomplete round — the loop only advances when you fix something.
 4. End the round by writing concise reproduction steps for the user (exact commands or
-   actions, what to observe). Then STOP — the user reproduces out-of-band and answers
-   with /debug-done fixed or /debug-done proceed.
+   actions, what to observe). Then STOP — the user reproduces out-of-band and uses
+   the review menu, /debug-note, or /debug-done fixed|proceed.
 When told the fix is confirmed: remove every probe, verify with the list_debug_probes
 tool that the ledger is empty, then summarize root cause and the final fix.`;
 
 export default function debugModeExtension(pi: ExtensionAPI) {
 	const z = pi.zod;
 	const state: DebugState = freshState();
-	let server: Server | null = null;
-	let logBuffer: LogEntry[] = [];
-	let pendingWrite: WriteStream | null = null;
+	let reviewMenuOpen = false;
 	let uiCtx: ExtensionContext | null = null;
 
-	// ============================== log server ==============================
+	// ============================== log files ==============================
 
-	function startServer(ctx: ExtensionContext, port: number): boolean {
-		if (server) return true;
-		const dir = path.join(ctx.cwd, ".omp", "debug");
+	function initializeLogDirectory(ctx: ExtensionContext): boolean {
+		const dir = path.resolve(ctx.cwd, ".omp", "debug");
 		try {
 			fs.mkdirSync(dir, { recursive: true });
-		} catch (err) {
-			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
-			return false;
-		}
-		state.debugDir = dir;
-		logBuffer = [];
-		try {
-			server = Bun.serve({
-				port,
-				hostname: "127.0.0.1",
-				idleTimeout: 5,
-				async fetch(req) {
-					const url = new URL(req.url);
-					if (req.method === "POST" && url.pathname === "/log") {
-						try {
-							const body = (await req.json()) as { probe?: unknown; data?: unknown };
-							if (typeof body.probe !== "string") return new Response("bad probe", { status: 400 });
-							const entry: LogEntry = {
-								run: state.runId ?? "orphan",
-								probe: body.probe,
-								ts: Date.now(),
-								data: body.data ?? null,
-							};
-							logBuffer.push(entry);
-							state.logCounts[entry.run] = (state.logCounts[entry.run] ?? 0) + 1;
-							pendingWrite?.write(JSON.stringify(entry) + "\n");
-							refreshUi();
-							return new Response("ok");
-						} catch {
-							return new Response("bad json", { status: 400 });
-						}
-					}
-					if (req.method === "GET" && url.pathname === "/health") {
-						return new Response("ok");
-					}
-					return new Response("not found", { status: 404 });
-				},
-			});
+			state.debugDir = dir;
 			return true;
 		} catch (err) {
-			pi.logger.error("debug-mode: log server failed to start", { err });
-			server = null;
+			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
+			state.debugDir = null;
 			return false;
 		}
 	}
 
-	function stopServer(): void {
-		pendingWrite?.end();
-		pendingWrite = null;
-		server?.stop(true);
-		server = null;
+	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] = readRunLines(run).length;
 	}
 
-	function newRun(): string {
-		pendingWrite?.end();
-		pendingWrite = null;
+	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.logCounts[run] = 0;
-		if (state.debugDir) {
-			pendingWrite = fs.createWriteStream(path.join(state.debugDir, `${run}.jsonl`), { flags: "a" });
-		}
 		return run;
 	}
 
+
 	// ============================== probe ledger ==============================
 
+
 	pi.on("tool_call", async (event) => {
 		if (!state.active) return;
 		if (event.toolName !== "edit" && event.toolName !== "write") return;
@@ -205,8 +187,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 				if (!state.probes.some(p => p.id === id)) state.probes.push({ id, file, round: state.round });
 			}
 		}
-		// removal detection: edit inputs alone can't prove deletion — checkLedger()
-		// rescans files for ground truth on demand.
+		// Removal detection rescans files for ground truth on demand.
 	});
 
 	/** Ground truth: which registered probes still exist in code. */
@@ -247,8 +228,9 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		ctx.ui.setStatus("debug-mode", ctx.ui.theme.fg("warning", label));
 		const lines: string[] = [];
 		if (state.phase === "waiting") {
+			refreshLogCounts();
 			const n = state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
-			lines.push(ctx.ui.theme.fg("accent", "reproduce the bug, then: /debug-done fixed | proceed"));
+			lines.push(ctx.ui.theme.fg("accent", "reproduce the bug, then: /debug-review"));
 			lines.push(ctx.ui.theme.fg("dim", `run ${state.runId} — ${n} log entries`));
 		}
 		ctx.ui.setWidget("debug-mode", lines.length ? lines : undefined);
@@ -293,17 +275,21 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 	pi.on("session_stop", async (_event, ctx) => {
 		if (!state.active) return;
 		if (state.phase === "cleanup") {
-			// cleanup turn settled → teardown (fixes kept, logs + server removed)
-			if (state.cleanupReady) await teardown(ctx, true);
+			// 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;
 		state.phase = "waiting";
+		pi.appendEntry(DEBUG_ENTRY, { ...state });
 		refreshUi();
 		ctx.ui.notify(
-			`Debug round ${state.round} paused.\nReproduce the bug now, then run:\n  /debug-done fixed   — fix confirmed, clean up & summarize\n  /debug-done proceed — analyze logs, next round`,
+			`Debug round ${state.round} paused. Reproduce the bug, then choose an action or run /debug-review.`,
 			"info",
 		);
+		if (ctx.hasUI) {
+			void openReviewMenu(ctx).catch(err => pi.logger.warn("debug-mode: review menu failed", { err }));
+		}
 	});
 
 	pi.registerCommand("debug-mode", {
@@ -311,7 +297,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			uiCtx = ctx;
 			if (state.active) {
-				ctx.ui.notify("debug-mode: already active (use /debug-done or /debug-abort)", "error");
+				ctx.ui.notify("debug-mode: already active (use /debug-review, /debug-done, or /debug-abort)", "error");
 				return;
 			}
 			const problem = args.trim();
@@ -324,6 +310,10 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 	});
 
 	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;
@@ -331,72 +321,110 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		state.probes = [];
 		state.logCounts = {};
 		state.hasRoundContent = false;
-		if (!startServer(ctx, DEFAULT_PORT)) {
-			ctx.ui.notify("debug-mode: log server failed to start; probes will have nowhere to report", "error");
+		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;
 		}
-		newRun();
 		refreshUi();
 		pi.sendMessage(
 			{
 				customType: "debug-mode-start",
-				content: `Starting debug mode. Problem report:\n\n${problem}\n\nBegin round 1: explore, hypothesize, instrument, and attempt a fix. Then give reproduction steps and stop.`,
+				content: `Starting debug mode. Problem report:\n\n${problem}\n\nBegin round 1: explore, hypothesize, instrument with direct file writes, and attempt a fix. Then give reproduction steps and stop.`,
 				display: true,
 			},
 			{ triggerTurn: true },
 		);
 	}
 
-	function finishDebug(ctx: ExtensionContext, verdict: "fixed" | "proceed"): void {
+	function ensureWaiting(ctx: ExtensionContext): boolean {
 		if (!state.active) {
 			ctx.ui.notify("debug-mode: not active", "error");
-			return;
+			return false;
 		}
 		if (state.phase !== "waiting") {
 			ctx.ui.notify(`debug-mode: not waiting for reproduction (phase: ${state.phase})`, "error");
-			return;
+			return false;
 		}
-		if (verdict === "fixed") {
-			state.phase = "cleanup";
-			state.cleanupReady = false;
-			refreshUi();
-			pi.sendMessage(
-				{
-					customType: "debug-mode-fixed",
-					content:
-						"User marked the problem FIXED.\n" +
-						"1. Remove every debug probe from the code (probe ledger below; verify with list_debug_probes after edits).\n" +
-						"2. Then summarize: root cause, the fix applied, what remains in the working diff.\n" +
-						`Probe ledger: ${JSON.stringify(state.probes)}`,
-					display: true,
-				},
-				{ triggerTurn: true },
+		return true;
+	}
+
+	async function markDebugFixed(ctx: ExtensionContext): Promise<void> {
+		if (!ensureWaiting(ctx)) return;
+		refreshLogCounts();
+		const logCount = state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
+		if (logCount === 0 && 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?",
 			);
-			// teardown happens when the cleanup turn settles (session_stop above)
-		} else {
-			const run = state.runId ?? "(none)";
-			const n = state.logCounts[run] ?? 0;
-			state.round += 1;
-			state.phase = "round";
-			state.hasRoundContent = false;
-			newRun();
-			refreshUi();
-			pi.sendMessage(
-				{
-					customType: "debug-mode-proceed",
-					content:
-						`User chose PROCEED — the fix did not resolve it (run ${run} captured ${n} log entries).\n` +
-						(n === 0
-							? "No logs were captured: the probes may not have executed (wrong code path, not rebuilt, or server unreachable) — treat that as a signal.\n"
-							: "") +
-						"Read the logs with get_debug_logs, rule out / strengthen hypotheses, re-instrument, attempt the next fix, give reproduction steps, and stop.",
-					display: true,
-				},
-				{ triggerTurn: true },
+			if (!confirmed) return;
+		}
+		if (!state.active || state.phase !== "waiting") return;
+
+		state.phase = "cleanup";
+		state.cleanupReady = false;
+		refreshUi();
+		pi.sendMessage(
+			{
+				customType: "debug-mode-fixed",
+				content:
+					"User marked the problem FIXED.\n" +
+					"1. Remove every debug probe from the code (probe ledger below; verify with list_debug_probes after edits).\n" +
+					"2. Then summarize: root cause, the fix applied, what remains in the working diff.\n" +
+					`Probe ledger: ${JSON.stringify(state.probes)}`,
+				display: true,
+			},
+			{ 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) {
+			const confirmed = await ctx.ui.confirm(
+				"Proceed without runtime logs?",
+				"No runtime observations were captured for this round. Continue to another analysis and fix round anyway?",
 			);
+			if (!confirmed) return;
+		}
+		if (!state.active || state.phase !== "waiting") return;
+
+		const previousRound = state.round;
+		state.round += 1;
+		state.phase = "round";
+		state.hasRoundContent = false;
+		if (!newRun()) {
+			state.round = previousRound;
+			state.phase = "waiting";
+			ctx.ui.notify("debug-mode: could not initialize the next run log file; staying at the reproduction gate", "error");
+			refreshUi();
+			return;
 		}
+		refreshUi();
+
+		const userEvidence = reproductionDetails
+			? `User added reproduction details after run ${run}:\n\n${reproductionDetails}\n\nTreat these details as evidence alongside the captured logs.\n`
+			: `User chose PROCEED — the fix did not resolve it (run ${run} captured ${logCount} log entries).\n`;
+		pi.sendMessage(
+			{
+				customType: reproductionDetails ? "debug-mode-note" : "debug-mode-proceed",
+				content:
+					userEvidence +
+					(logCount === 0
+						? "No logs were captured: the instrumented code path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed — treat that as a signal.\n"
+						: `Run ${run} captured ${logCount} log entries.\n`) +
+					"Read the previous run with get_debug_logs, update the hypotheses, re-instrument, attempt the next fix, give reproduction steps, and stop.",
+				display: true,
+			},
+			{ triggerTurn: true },
+		);
 	}
 
-	async function teardown(ctx: ExtensionContext, keepFixes: boolean): Promise<void> {
+	async function teardown(ctx: ExtensionContext, outcome: "finished" | "aborted"): Promise<void> {
 		if (state.debugDir) {
 			try {
 				fs.rmSync(state.debugDir, { recursive: true, force: true });
@@ -404,17 +432,67 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 				pi.logger.warn("debug-mode: failed to remove debug dir", { err });
 			}
 		}
-		stopServer();
 		const probesLeft = await checkLedger();
 		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 ended, but ${probesLeft.length} probe(s) remain in code: ${probesLeft.map(p => p.id).join(", ")} — remove manually.`,
+				`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 if (keepFixes) {
-			ctx.ui.notify("Debug mode finished. Log files removed; working diff contains the fix — review with git diff.", "info");
+		} 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");
+	}
+
+	async function openReviewMenu(ctx: ExtensionContext): Promise<void> {
+		if (!ensureWaiting(ctx)) return;
+		if (!ctx.hasUI) {
+			ctx.ui.notify("/debug-review requires an interactive UI; use /debug-done fixed|proceed instead.", "warning");
+			return;
+		}
+		if (reviewMenuOpen) {
+			ctx.ui.notify("debug-mode: review menu is already open", "info");
+			return;
+		}
+
+		reviewMenuOpen = true;
+		try {
+			const choice = await ctx.ui.select(`Review debug round ${state.round}`, [...REVIEW_OPTIONS]);
+			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);
+			}
+		} finally {
+			reviewMenuOpen = false;
 		}
 	}
 
@@ -426,11 +504,34 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			uiCtx = ctx;
 			const verdict = args.trim().toLowerCase();
-			if (verdict !== "fixed" && verdict !== "proceed") {
+			if (verdict === "fixed") {
+				await markDebugFixed(ctx);
+			} else if (verdict === "proceed") {
+				await advanceDebug(ctx);
+			} else {
 				ctx.ui.notify("Usage: /debug-done fixed|proceed", "error");
+			}
+		},
+	});
+
+	pi.registerCommand("debug-review", {
+		description: "Open the interactive action menu for a completed debug round",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			await openReviewMenu(ctx);
+		},
+	});
+
+	pi.registerCommand("debug-note", {
+		description: "Add reproduction details and continue: /debug-note <details>",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			const details = args.trim();
+			if (!details) {
+				ctx.ui.notify("Usage: /debug-note <reproduction details>", "error");
 				return;
 			}
-			finishDebug(ctx, verdict);
+			await advanceDebug(ctx, details);
 		},
 	});
 
@@ -438,20 +539,7 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		description: "Abort debug mode: delete logs (fixes stay in the working diff)",
 		handler: async (_args, ctx) => {
 			uiCtx = ctx;
-			if (!state.active) {
-				ctx.ui.notify("debug-mode: not active", "error");
-				return;
-			}
-			const ledger = await checkLedger();
-			await teardown(ctx, true);
-			if (ledger.length > 0) {
-				ctx.ui.notify(
-					`Debug mode aborted. These probes remain (remove manually or ask the agent):\n${ledger.map(p => `  ${p.id} — ${p.file}`).join("\n")}\nApplied fixes are kept in the working diff.`,
-					"warning",
-				);
-			} else {
-				ctx.ui.notify("Debug mode aborted. No probes in code; applied fixes are kept in the working diff.", "info");
-			}
+			await abortDebug(ctx);
 		},
 	});
 
@@ -463,12 +551,14 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 				ctx.ui.notify("debug-mode: idle", "info");
 				return;
 			}
+			refreshLogCounts();
 			const alive = await checkLedger();
 			ctx.ui.notify(
 				`debug-mode: phase=${state.phase} round=${state.round} run=${state.runId}\n` +
 					`probes (ledger ${state.probes.length}, alive ${alive.length}):\n` +
 					(alive.map(p => `  ${p.id} — ${p.file}`).join("\n") || "  (none)") +
-					`\nlogs: ${Object.entries(state.logCounts).map(([r, n]) => `${r}=${n}`).join(", ") || "(none)"}`,
+					`\nlogs: ${Object.entries(state.logCounts).map(([r, n]) => `${r}=${n}`).join(", ") || "(none)"}` +
+					`\ncurrent log file: ${logFileFor(state) ?? "(not initialized)"}`,
 				"info",
 			);
 		},
@@ -476,11 +566,12 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 
 	// ============================== tools ==============================
 
+
 	pi.registerTool({
 		name: "get_debug_logs",
 		label: "Get Debug Logs",
 		description:
-			"Read logs captured by debug-mode probes. Each entry: {run, probe, ts, data}. Returns JSONL text. Call with previous=true to analyze the last completed reproduction run.",
+			"Read JSONL observations appended directly by debug-mode runtime probes. Each entry: {probe, ts, data}. Call with previous=true to analyze the last completed reproduction run.",
 		parameters: z.object({
 			run: z.string().optional().describe("Run id filter (default: current run)"),
 			probe: z.string().optional().describe("Probe id filter"),
@@ -488,33 +579,42 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		}),
 		approval: "read",
 		async execute(_toolCallId, params) {
+			refreshLogCounts();
 			const runs = Object.keys(state.logCounts);
 			let run = params.run;
-			if (!run && params.previous) run = runs[runs.length - 2];
-			if (!run) run = state.runId ?? undefined;
-			// disk is authoritative (survives resume); memory buffer is fallback
-			let text = "";
-			if (state.debugDir && run) {
-				try {
-					text = await Bun.file(path.join(state.debugDir, `${run}.jsonl`)).text();
-				} catch {
-					text = "";
+			if (!run && params.previous) {
+				run = runs[runs.length - 2];
+				if (!run) {
+					return {
+						content: [{ type: "text", text: "(no completed previous debug run is available)" }],
+						details: { run: null, file: null, count: 0 },
+					};
 				}
 			}
-			if (!text) {
-				text = logBuffer
-					.filter(e => (!run || e.run === run) && (!params.probe || e.probe === params.probe))
-					.map(e => JSON.stringify(e))
-					.join("\n");
+			if (!run) run = state.runId ?? undefined;
+
+			let lines = run ? readRunLines(run) : [];
+			if (params.probe) {
+				lines = lines.filter(line => {
+					try {
+						const entry = JSON.parse(line) as { probe?: unknown };
+						return entry.probe === params.probe;
+					} catch {
+						return false;
+					}
+				});
 			}
+			const text = lines.join("\n");
 			return {
 				content: [
 					{
 						type: "text",
-						text: text || "(no logs captured — probes did not report; wrong code path, stale build, or server unreachable)",
+						text:
+							text ||
+							"(no logs captured — the instrumented path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed)",
 					},
 				],
-				details: { run: run ?? null, count: text.split("\n").filter(Boolean).length },
+				details: { run: run ?? null, file: run ? logFileFor(state, run) : null, count: lines.length },
 			};
 		},
 	});
@@ -553,29 +653,22 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 			.pop() as { data?: DebugState } | undefined;
 		if (last?.data?.active) {
 			Object.assign(state, last.data);
-			if (state.debugDir && startServer(ctx, DEFAULT_PORT)) {
-				// replay disk logs for analysis continuity across resume
-				if (fs.existsSync(state.debugDir)) {
-					for (const f of fs.readdirSync(state.debugDir)) {
-						if (!f.endsWith(".jsonl")) continue;
-						const run = f.replace(/\.jsonl$/, "");
-						try {
-							const lines = (await Bun.file(path.join(state.debugDir!, f)).text()).split("\n").filter(Boolean);
-							state.logCounts[run] = lines.length;
-							for (const l of lines) {
-								try {
-									logBuffer.push(JSON.parse(l) as LogEntry);
-								} catch {}
-							}
-						} catch {}
+			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);
 					}
-				}
-				if (state.runId) {
-					pendingWrite = fs.createWriteStream(path.join(state.debugDir, `${state.runId}.jsonl`), { flags: "a" });
+					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}. Use /debug-status, /debug-done fixed|proceed, or /debug-abort.`,
+				`debug-mode resumed: phase=${state.phase} round=${state.round}, log=${currentFile ?? "unavailable"}. Use /debug-status, /debug-review, /debug-done fixed|proceed, or /debug-abort.`,
 				"info",
 			);
 		}
@@ -586,9 +679,6 @@ export default function debugModeExtension(pi: ExtensionAPI) {
 		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
 	});
 
-	pi.on("session_shutdown", async () => {
-		stopServer();
-	});
 
 	pi.setLabel("Debug Mode");
 }

package/src/review-actions.ts

@@ -0,0 +1,11 @@
+export const REVIEW_MARK_FIXED = "Mark as fixed";
+export const REVIEW_PROCEED = "Proceed with captured logs";
+export const REVIEW_ADD_DETAILS = "Add reproduction details";
+export const REVIEW_ABORT = "Abort debug mode";
+
+export const REVIEW_OPTIONS = [
+	REVIEW_MARK_FIXED,
+	REVIEW_PROCEED,
+	REVIEW_ADD_DETAILS,
+	REVIEW_ABORT,
+] as const;