@siuver/omp-debug-mode 0.1.2 → 0.1.3

package/src/main.ts

@@ -1,684 +1,24 @@
 /**
  * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
  *
- * State machine:
+ * State machine (matches Cursor Debug Mode):
  *   IDLE → /debug-mode <problem>
- *   → agent hypothesizes, adds @omp-probe instrumentation, attempts a fix
+ *   → agent writes 3-5 hypotheses and @omp-probe instrumentation (no product fix)
  *   → WAITING_REPRO: agent stops; user reproduces out-of-band
+ *   → Proceed/add details → agent reads logs, evaluates hypotheses, fixes only
+ *     with evidence, keeps probes, and asks for a verification reproduce → loop
  *   → Mark as fixed → agent removes probes + summarizes → teardown (logs deleted)
- *   → Proceed/add details → agent analyzes logs, re-instruments + fixes → loop
  *
- * - 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-review, /debug-note, /debug-status, /debug-done, /debug-abort
+ * - `state.ts` — persisted round state and the injected blackboard
+ * - `probes.ts` — `@omp-probe` ledger and its on-disk ground truth
+ * - `log-files.ts` — stable `<cwd>/.omp/debug/current.jsonl` and run archival
+ * - `methodology.ts` — the Cursor Debug Mode prompt contract
+ * - `debug-mode.ts` — state machine, commands, and lifecycle wiring
  */
-import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
-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;
-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;
-}
-
-
-function freshState(): DebugState {
-	return {
-		active: false,
-		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 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)
-		.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}
-
-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)"}`;
-}
-
-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. 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 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.`;
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { registerDebugMode } from "./debug-mode";
 
 export default function debugModeExtension(pi: ExtensionAPI) {
-	const z = pi.zod;
-	const state: DebugState = freshState();
-	let reviewMenuOpen = false;
-	let uiCtx: ExtensionContext | null = null;
-
-	// ============================== log files ==============================
-
-	function initializeLogDirectory(ctx: ExtensionContext): boolean {
-		const dir = path.resolve(ctx.cwd, ".omp", "debug");
-		try {
-			fs.mkdirSync(dir, { recursive: true });
-			state.debugDir = dir;
-			return true;
-		} catch (err) {
-			pi.logger.error("debug-mode: cannot create log dir", { dir, err });
-			state.debugDir = null;
-			return false;
-		}
-	}
-
-	function readRunLines(run: string): string[] {
-		return readJsonlLines(logFileFor(state, run));
-	}
-
-	function refreshLogCounts(): void {
-		const runs = new Set(Object.keys(state.logCounts));
-		if (state.debugDir) {
-			try {
-				for (const file of fs.readdirSync(state.debugDir)) {
-					if (!file.endsWith(".jsonl")) continue;
-					if (file === ACTIVE_LOG_FILE) {
-						if (state.runId) runs.add(state.runId);
-					} else {
-						runs.add(file.replace(/\.jsonl$/, ""));
-					}
-				}
-			} catch {}
-		}
-		for (const run of runs) state.logCounts[run] = readRunLines(run).length;
-	}
-
-	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;
-		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 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") {
-			refreshLogCounts();
-			const n = state.runId ? (state.logCounts[state.runId] ?? 0) : 0;
-			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);
-	}
-
-	// ============================== 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: 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. 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", {
-		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-review, /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 {
-		if (!initializeLogDirectory(ctx)) {
-			ctx.ui.notify("debug-mode: could not create the debug log directory; debug mode was not started", "error");
-			return;
-		}
-		state.active = true;
-		state.phase = "round";
-		state.problem = problem;
-		state.round = 1;
-		state.probes = [];
-		state.logCounts = {};
-		state.hasRoundContent = false;
-		if (!newRun()) {
-			Object.assign(state, freshState());
-			ctx.ui.notify("debug-mode: could not initialize the run log file; debug mode was not started", "error");
-			return;
-		}
-		refreshUi();
-		pi.sendMessage(
-			{
-				customType: "debug-mode-start",
-				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 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;
-		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?",
-			);
-			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, outcome: "finished" | "aborted"): 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 });
-			}
-		}
-		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 ${resultLabel}, but ${probesLeft.length} probe(s) remain in code: ${probesLeft.map(p => p.id).join(", ")} — remove manually. Applied fixes remain in the working diff.`,
-				"warning",
-			);
-		} else {
-			ctx.ui.notify(
-				`Debug mode ${resultLabel}. Log files removed; applied fixes remain in the working diff for review.`,
-				"info",
-			);
-		}
-	}
-
-	async function abortDebug(ctx: ExtensionContext): Promise<void> {
-		if (!state.active) {
-			ctx.ui.notify("debug-mode: not active", "error");
-			return;
-		}
-		if (ctx.hasUI) {
-			const confirmed = await ctx.ui.confirm(
-				"Abort debug mode?",
-				"Delete captured debug logs and stop the workflow? Applied code changes will remain in the working diff.",
-			);
-			if (!confirmed) return;
-		}
-		if (!state.active) return;
-		await teardown(ctx, "aborted");
-	}
-
-	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;
-		}
-	}
-
-	// ============================== 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") {
-				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;
-			}
-			await advanceDebug(ctx, details);
-		},
-	});
-
-	pi.registerCommand("debug-abort", {
-		description: "Abort debug mode: delete logs (fixes stay in the working diff)",
-		handler: async (_args, ctx) => {
-			uiCtx = ctx;
-			await abortDebug(ctx);
-		},
-	});
-
-	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;
-			}
-			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)"}` +
-					`\ncurrent log file: ${logFileFor(state) ?? "(not initialized)"}`,
-				"info",
-			);
-		},
-	});
-
-	// ============================== tools ==============================
-
-
-	pi.registerTool({
-		name: "get_debug_logs",
-		label: "Get Debug Logs",
-		description:
-			"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"),
-			previous: z.boolean().optional().describe("Use the previous (completed) run instead of the current one"),
-		}),
-		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) {
-					return {
-						content: [{ type: "text", text: "(no completed previous debug run is available)" }],
-						details: { run: null, file: null, count: 0 },
-					};
-				}
-			}
-			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 — 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, file: run ? logFileFor(state, run) : null, count: lines.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 || !fs.existsSync(state.debugDir)) initializeLogDirectory(ctx);
-			const currentFile = logFileFor(state);
-			if (currentFile) {
-				try {
-					const legacyRunFile = state.debugDir && state.runId ? path.join(state.debugDir, `${state.runId}.jsonl`) : null;
-					if (!fs.existsSync(currentFile) && legacyRunFile && fs.existsSync(legacyRunFile)) {
-						fs.renameSync(legacyRunFile, currentFile);
-					}
-					fs.writeFileSync(currentFile, "", { flag: "a" });
-				} catch (err) {
-					pi.logger.error("debug-mode: cannot restore run log", { file: currentFile, err });
-				}
-			}
-			refreshLogCounts();
-			ctx.ui.notify(
-				`debug-mode resumed: phase=${state.phase} round=${state.round}, log=${currentFile ?? "unavailable"}. Use /debug-status, /debug-review, /debug-done fixed|proceed, or /debug-abort.`,
-				"info",
-			);
-		}
-		refreshUi();
-	});
-
-	pi.on("turn_start", async () => {
-		if (state.active) pi.appendEntry(DEBUG_ENTRY, { ...state });
-	});
-
-
 	pi.setLabel("Debug Mode");
+	registerDebugMode(pi);
 }