@siuver/omp-debug-mode 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-08-20
+
+- Initial npm release of the Cursor Debug Mode replica for OMP.
+- Added iterative hypothesis, instrumentation, fix, and user-reproduction rounds.
+- Added local probe logging, session resume, probe-ledger cleanup, debug commands, and evidence-reading tools.

package/README.md

@@ -0,0 +1,56 @@
+# @siuver/omp-debug-mode
+
+A Cursor Debug Mode replica for oh-my-pi. It recreates Cursor's evidence-driven, human-in-the-loop debugging workflow for OMP; it is an independent implementation and is not affiliated with Cursor.
+
+The plugin makes the agent form hypotheses, add temporary runtime probes, attempt a fix, and then pause while you reproduce the problem outside the agent loop. Your result either starts another evidence-driven round or triggers probe cleanup and a final summary.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
+| `/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. |
+
+## 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.
+
+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`.
+
+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.
+
+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.
+
+## Install
+
+```sh
+omp plugin install @siuver/omp-debug-mode
+```
+
+Restart omp after installation, then run `/debug-mode <problem>`.
+
+## Local Development
+
+From the repository root:
+
+```sh
+bun run check
+omp plugin link ./plugins/debug-mode
+```
+
+Restart omp after linking.
+
+## Changelog
+
+See `CHANGELOG.md` for release notes included in the npm package.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@siuver/omp-debug-mode",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A Cursor Debug Mode replica for evidence-driven, human-in-the-loop debugging in oh-my-pi.",
+  "license": "MIT",
+  "homepage": "https://github.com/Siuver/blackhole/tree/master/plugins/debug-mode#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Siuver/blackhole.git",
+    "directory": "plugins/debug-mode"
+  },
+  "keywords": [
+    "omp",
+    "oh-my-pi",
+    "extension",
+    "debug",
+    "cursor",
+    "human-in-the-loop"
+  ],
+  "exports": {
+    ".": "./src/main.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "omp": {
+    "name": "debug-mode",
+    "description": "Cursor-style human-in-the-loop debugging with runtime probes and reproduction gates.",
+    "extensions": [
+      "./src/main.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": "*"
+  }
+}

package/src/main.ts

@@ -0,0 +1,594 @@
+/**
+ * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
+ *
+ * State machine:
+ *   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
+ *
+ * Components:
+ * - Local log server (Bun.serve, 127.0.0.1:7842) — probes POST {probe, data};
+ *   logs append to <cwd>/.omp/debug/<run>.jsonl
+ * - 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
+ */
+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";
+
+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;
+	round: number;
+}
+
+interface DebugState {
+	active: boolean;
+	phase: Phase;
+	problem: string;
+	round: number;
+	runId: string | null;
+	probes: Probe[];
+	debugDir: string | null;
+	logCounts: Record<string, number>;
+	hasRoundContent: boolean;
+	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,
+		probes: [],
+		debugDir: null,
+		logCounts: {},
+		hasRoundContent: false,
+		cleanupReady: false,
+	};
+}
+
+function probeIdsIn(text: unknown): string[] {
+	if (typeof text !== "string") return [];
+	const ids: string[] = [];
+	for (const m of text.matchAll(PROBE_MARK)) ids.push(m[1]);
+	return ids;
+}
+
+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)
+		.map(([run, n]) => `${run}: ${n}`)
+		.join(", ") || "(none yet)";
+	return `\
+[DEBUG MODE ACTIVE — round ${s.round}]
+
+Problem under investigation:
+${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.
+Logs by run: ${counts}
+Current run id: ${s.runId ?? "(not started)"}`;
+}
+
+const METHODOLOGY = `\
+[DEBUG MODE METHODOLOGY — follow strictly]
+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).
+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.
+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 uiCtx: ExtensionContext | null = null;
+
+	// ============================== log server ==============================
+
+	function startServer(ctx: ExtensionContext, port: number): boolean {
+		if (server) return true;
+		const dir = path.join(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 });
+				},
+			});
+			return true;
+		} catch (err) {
+			pi.logger.error("debug-mode: log server failed to start", { err });
+			server = null;
+			return false;
+		}
+	}
+
+	function stopServer(): void {
+		pendingWrite?.end();
+		pendingWrite = null;
+		server?.stop(true);
+		server = null;
+	}
+
+	function newRun(): string {
+		pendingWrite?.end();
+		pendingWrite = null;
+		const run = `run${state.round}-${Date.now().toString(36)}`;
+		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;
+		const input = event.input as Record<string, unknown>;
+		const file =
+			typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : "(unknown)";
+		for (const v of Object.values(input)) {
+			for (const id of probeIdsIn(v)) {
+				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.
+	});
+
+	/** Ground truth: which registered probes still exist in code. */
+	async function checkLedger(): Promise<Probe[]> {
+		const alive: Probe[] = [];
+		const byFile = new Map<string, Probe[]>();
+		for (const p of state.probes) {
+			const list = byFile.get(p.file) ?? [];
+			list.push(p);
+			byFile.set(p.file, list);
+		}
+		for (const [file, probes] of byFile) {
+			let text: string;
+			try {
+				text = await Bun.file(file).text();
+			} catch {
+				continue; // file gone → probe gone
+			}
+			for (const p of probes) {
+				if (text.includes(`@omp-probe ${p.id}`)) alive.push(p);
+			}
+		}
+		return alive;
+	}
+
+	// ============================== UI ==============================
+
+	function refreshUi(): void {
+		const ctx = uiCtx;
+		if (!ctx?.hasUI) return;
+		if (!state.active) {
+			ctx.ui.setStatus("debug-mode", undefined);
+			ctx.ui.setWidget("debug-mode", undefined);
+			return;
+		}
+		const label =
+			state.phase === "waiting" ? "🐞 waiting-repro" : state.phase === "round" ? `🐞 round ${state.round}` : "🐞 cleanup";
+		ctx.ui.setStatus("debug-mode", ctx.ui.theme.fg("warning", label));
+		const lines: string[] = [];
+		if (state.phase === "waiting") {
+			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("dim", `run ${state.runId} — ${n} log entries`));
+		}
+		ctx.ui.setWidget("debug-mode", lines.length ? lines : undefined);
+	}
+
+	// ============================== prompt injection ==============================
+
+	pi.on("before_agent_start", async () => {
+		if (!state.active || (state.phase !== "round" && state.phase !== "cleanup")) return;
+		return {
+			message: {
+				customType: "debug-mode-context",
+				content: `${blackboard(state)}\n\n${METHODOLOGY}`,
+				display: false,
+			},
+		};
+	});
+
+	// Drop stale blackboard messages; the freshest is re-injected each round.
+	pi.on("context", async (event) => {
+		const filtered = event.messages.filter(
+			m => !(m.role === "custom" && (m as { customType?: string }).customType === "debug-mode-context"),
+		);
+		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 };
+		if (msg?.role === "assistant") {
+			if (state.phase === "cleanup") state.cleanupReady = true;
+			state.hasRoundContent = true;
+		}
+	});
+
+	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);
+			return;
+		}
+		if (state.phase !== "round" || !state.hasRoundContent) return;
+		state.phase = "waiting";
+		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`,
+			"info",
+		);
+	});
+
+	pi.registerCommand("debug-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 /debug-done or /debug-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);
+		},
+	});
+
+	function startDebug(ctx: ExtensionContext, problem: string): void {
+		state.active = true;
+		state.phase = "round";
+		state.problem = problem;
+		state.round = 1;
+		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");
+		}
+		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.`,
+				display: true,
+			},
+			{ triggerTurn: true },
+		);
+	}
+
+	function finishDebug(ctx: ExtensionContext, verdict: "fixed" | "proceed"): void {
+		if (!state.active) {
+			ctx.ui.notify("debug-mode: not active", "error");
+			return;
+		}
+		if (state.phase !== "waiting") {
+			ctx.ui.notify(`debug-mode: not waiting for reproduction (phase: ${state.phase})`, "error");
+			return;
+		}
+		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 },
+			);
+			// 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 },
+			);
+		}
+	}
+
+	async function teardown(ctx: ExtensionContext, keepFixes: boolean): Promise<void> {
+		if (state.debugDir) {
+			try {
+				fs.rmSync(state.debugDir, { recursive: true, force: true });
+			} catch (err) {
+				pi.logger.warn("debug-mode: failed to remove debug dir", { err });
+			}
+		}
+		stopServer();
+		const probesLeft = await checkLedger();
+		Object.assign(state, freshState());
+		refreshUi();
+		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.`,
+				"warning",
+			);
+		} else if (keepFixes) {
+			ctx.ui.notify("Debug mode finished. Log files removed; working diff contains the fix — review with git diff.", "info");
+		}
+	}
+
+	// ============================== commands ==============================
+
+
+	pi.registerCommand("debug-done", {
+		description: "Answer the reproduction gate: /debug-done fixed|proceed",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			const verdict = args.trim().toLowerCase();
+			if (verdict !== "fixed" && verdict !== "proceed") {
+				ctx.ui.notify("Usage: /debug-done fixed|proceed", "error");
+				return;
+			}
+			finishDebug(ctx, verdict);
+		},
+	});
+
+	pi.registerCommand("debug-abort", {
+		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");
+			}
+		},
+	});
+
+	pi.registerCommand("debug-status", {
+		description: "Show debug mode state",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			if (!state.active) {
+				ctx.ui.notify("debug-mode: idle", "info");
+				return;
+			}
+			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)"}`,
+				"info",
+			);
+		},
+	});
+
+	// ============================== 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.",
+		parameters: z.object({
+			run: z.string().optional().describe("Run id filter (default: current run)"),
+			probe: z.string().optional().describe("Probe id filter"),
+			previous: z.boolean().optional().describe("Use the previous (completed) run instead of the current one"),
+		}),
+		approval: "read",
+		async execute(_toolCallId, params) {
+			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 (!text) {
+				text = logBuffer
+					.filter(e => (!run || e.run === run) && (!params.probe || e.probe === params.probe))
+					.map(e => JSON.stringify(e))
+					.join("\n");
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: text || "(no logs captured — probes did not report; wrong code path, stale build, or server unreachable)",
+					},
+				],
+				details: { run: run ?? null, count: text.split("\n").filter(Boolean).length },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "list_debug_probes",
+		label: "List Debug Probes",
+		description:
+			"Ground-truth probe ledger for debug mode: rescans files for `@omp-probe <id>` markers and reports which probes are actually present in code, with their files. Use to verify cleanup is complete.",
+		parameters: z.object({}),
+		approval: "read",
+		async execute() {
+			const alive = await checkLedger();
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							alive.length === 0
+								? "Probe ledger is EMPTY — all probes removed."
+								: `Alive probes (${alive.length}):\n` + alive.map(p => `${p.id} — ${p.file}`).join("\n"),
+					},
+				],
+				details: { alive },
+			};
+		},
+	});
+
+	// ============================== 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 (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.runId) {
+					pendingWrite = fs.createWriteStream(path.join(state.debugDir, `${state.runId}.jsonl`), { flags: "a" });
+				}
+			}
+			ctx.ui.notify(
+				`debug-mode resumed: phase=${state.phase} round=${state.round}. Use /debug-status, /debug-done fixed|proceed, or /debug-abort.`,
+				"info",
+			);
+		}
+		refreshUi();
+	});
+
+	pi.on("turn_start", async () => {
+		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
+	});
+
+	pi.on("session_shutdown", async () => {
+		stopServer();
+	});
+
+	pi.setLabel("Debug Mode");
+}