@siuver/omp-debug-mode 0.1.5 → 0.1.7

package/src/debug-mode.ts

@@ -1,14 +1,27 @@
 import { Text } from "@oh-my-pi/pi-coding-agent";
-import type { ExtensionAPI, ExtensionContext, MessageRenderer } from "@oh-my-pi/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	MessageRenderer,
+} from "@oh-my-pi/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { describeEvidence, validateEvidenceArtifact } from "./evidence";
-import { describeOpenReason } from "./gate";
+import {
+	type EvidenceCompletion,
+	UNLINKED_SELECTOR,
+	describeEvidence,
+	evidenceCompletions,
+	parseEvidenceArgument,
+	validateEvidenceArtifact,
+} from "./evidence";
+import { describeHandoff } from "./gate";
 import {
 	ACTIVE_LOG_FILE,
 	JsonlLineCounter,
 	describeHypotheses,
 	prepareRunLog,
+	clearActiveLog,
 	readJsonlLines,
 	summarizeHypotheses,
 } from "./log-files";
@@ -28,12 +41,12 @@ import {
 	evidenceSummary,
 	evidenceView,
 	hasNonProbeEvidence,
-	keepLatestCustomType,
 	logFileFor,
 	pendingRequests,
 	reviveState,
+	syncCustomType,
 } from "./state";
-import { registerDebugTools } from "./tools";
+import { type HandoffOutcome, type HandoffRequest, nextActiveTools, registerDebugTools } from "./tools";
 import { applyUi } from "./ui";
 import { debugDirFor, excludeDebugLogsFromGit, pruneDebugRoot } from "./workspace";
 
@@ -43,6 +56,7 @@ const COMMAND_PROCEED = "debug-proceed";
 const COMMAND_EVIDENCE = "debug-evidence";
 const COMMAND_ABORT = "debug-abort";
 const COMMAND_STATUS = "debug-status";
+const COMMAND_CLEAR = "debug-clear";
 
 /** Compact transcript lines for the prompts this extension injects. */
 const MESSAGE_SUMMARIES: Record<string, string> = {
@@ -55,6 +69,16 @@ interface DebugMessageDetails {
 	summary?: string;
 }
 
+/**
+ * Argument completion reached the host's command options after the version this
+ * package type-checks against, hence the spread instead of an inline key.
+ */
+function argumentCompletions(provide: (argumentPrefix: string) => EvidenceCompletion[] | null): {
+	getArgumentCompletions?: (argumentPrefix: string) => EvidenceCompletion[] | null;
+} {
+	return { getArgumentCompletions: provide };
+}
+
 export function registerDebugMode(pi: ExtensionAPI): void {
 	let state: DebugState = INACTIVE;
 	let uiCtx: ExtensionContext | null = null;
@@ -72,10 +96,12 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 	// ============================== state plumbing ==============================
 
 	/**
-	 * Cache-only events carry no effects, so they may run inside a render pass
-	 * without re-entering the UI refresh that asked for them.
+	 * Effect-free bookkeeping: these events carry no effects, so they may run
+	 * inside a render pass without re-entering the UI refresh that asked for
+	 * them, and they are deliberately not persisted — every one of them is
+	 * either a disk observation or live-turn state that a restore rebuilds.
 	 */
-	function absorbCache(event: Extract<DebugEvent, { t: "runs_observed" | "ledger_synced" }>): void {
+	function absorbCache(event: Extract<DebugEvent, { t: "runs_observed" | "ledger_synced" | "tool_used" }>): void {
 		state = reduce(state, event).state;
 	}
 
@@ -138,6 +164,7 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 						"info",
 					);
 				}
+				void setDebugToolsActive(false);
 				return null;
 			}
 		}
@@ -193,8 +220,27 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		return run ? (state.logCounts[run] ?? 0) : 0;
 	}
 
+	function fsErrorMessage(error: unknown): string {
+		if (error instanceof Error) {
+			const code = "code" in error && typeof error.code === "string" ? error.code : "";
+			return code ? `${code}: ${error.message}` : error.message;
+		}
+		return String(error);
+	}
+
+	function runLogHint(error: string): string {
+		if (/\b(EPERM|EBUSY|EACCES|EAGAIN)\b/.test(error)) {
+			return " Close the instrumented app if it still has the log file open, then retry.";
+		}
+		return "";
+	}
+
 	/** 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 {
+	function createRun(
+		debugDir: string,
+		round: number,
+		previousRun: string | null,
+	): { runId: string } | { error: string } {
 		try {
 			prepareRunLog(debugDir, previousRun);
 		} catch (err) {
@@ -202,9 +248,9 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 				file: path.join(debugDir, ACTIVE_LOG_FILE),
 				err,
 			});
-			return null;
+			return { error: fsErrorMessage(err) };
 		}
-		return `run${round}-${Date.now().toString(36)}`;
+		return { runId: `run${round}-${Date.now().toString(36)}` };
 	}
 
 	/**
@@ -213,13 +259,13 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 	 * refresh the widget as observations land.
 	 */
 	function watchLogFile(): void {
-		const file = state.active && state.stage === "awaiting_evidence" ? logFileFor(state) : null;
+		const file = state.active && state.stage === "user_turn" ? logFileFor(state) : null;
 		if (file === watchedLogFile) return;
 		unwatchLogFile();
 		if (!file || !uiCtx?.hasUI) return;
 		try {
 			fs.watchFile(file, { interval: 1000 }, (curr, prev) => {
-				if (!state.active || state.stage !== "awaiting_evidence") return;
+				if (!state.active || state.stage !== "user_turn") return;
 				if (curr.mtimeMs === prev.mtimeMs && curr.size === prev.size) return;
 				try {
 					refreshUi();
@@ -254,6 +300,9 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (!state.active) return;
+		// Any tool call clears the reminder guard: the agent acted on the last
+		// reminder, so a further one is worth spending.
+		absorbCache({ t: "tool_used" });
 		if (event.toolName !== "edit" && event.toolName !== "write") return;
 		const probes = probesInInput(event.input as Record<string, unknown>, ctx.cwd, currentRound(state).index);
 		if (probes.length > 0) dispatch({ t: "probes_found", probes }, ctx);
@@ -261,29 +310,49 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 
 	// ============================== prompt injection ==============================
 
+	/** The blackboard plus the contract for the stage the session is in now. */
+	function injectedContext(session: DebugSession): string {
+		// Cleanup has no hypotheses left to form; the full methodology would only
+		// invite another round.
+		const contract = session.stage === "cleaning_up" ? CLEANUP_CONTRACT : METHODOLOGY;
+		return `${blackboard(session, describeEvidence(evidenceView(session)))}\n\n${contract}`;
+	}
+
+	// Injected on every prompt, including a reply on the user's turn. Skipping the
+	// injection there is what left the model with no idea which stage it was in,
+	// and a model that cannot see the state cannot be blamed for misjudging it.
+	//
+	// The attribution is explicit because the host otherwise inherits it from the
+	// prompt being answered, which stamps this extension's own blackboard as
+	// user-authored. Models read that literally and report the stage back as
+	// something the user said.
 	pi.on("before_agent_start", async () => {
-		if (!state.active || state.stage === "awaiting_evidence") return;
+		if (!state.active) return;
 		// The blackboard claims to be ground truth, so reconcile it with disk first.
 		await syncLedger();
 		if (!state.active) return;
-		// Cleanup has no hypotheses left to form; the full methodology would only
-		// invite another round.
-		const contract = state.stage === "cleaning_up" ? CLEANUP_CONTRACT : METHODOLOGY;
 		return {
 			message: {
 				customType: DEBUG_CONTEXT_TYPE,
-				content: `${blackboard(state, describeEvidence(evidenceView(state)))}\n\n${contract}`,
+				content: injectedContext(state),
 				display: false,
+				attribution: "agent",
 			},
 		};
 	});
 
-	// Drop stale blackboard copies. Keep the newest — `context` runs after
-	// `before_agent_start`, so deleting every match would hide the injection
-	// from the model.
+	// Keep exactly one, current blackboard in the request. `before_agent_start`
+	// only fires for a submitted prompt, so a turn the host resumed by itself —
+	// a todo reminder, a plan nudge, a queued-message drain — would otherwise
+	// hand the model the previous turn's stage. This hook runs on every provider
+	// request, so re-rendering here is what makes the stage unskippable.
 	pi.on("context", async (event) => {
-		const filtered = keepLatestCustomType(event.messages, DEBUG_CONTEXT_TYPE);
-		if (filtered.length !== event.messages.length) return { messages: filtered };
+		const messages = syncCustomType(
+			event.messages,
+			DEBUG_CONTEXT_TYPE,
+			state.active ? injectedContext(state) : null,
+		);
+		if (messages) return { messages };
 	});
 
 	// ============================== turn lifecycle ==============================
@@ -295,6 +364,13 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 	pi.on("message_end", async (event, ctx) => {
 		if (!state.active) return;
 		const msg = event.message as { role?: string; content?: unknown };
+		// A user message is the one thing a host continuation cannot fake: its
+		// reminders are `developer` messages. So this, not the start of a turn,
+		// is what hands a round back to the agent.
+		if (msg?.role === "user") {
+			dispatch({ t: "user_replied" }, ctx);
+			return;
+		}
 		if (msg?.role !== "assistant") return;
 		dispatch({ t: "assistant_message", text: extractAssistantText(msg.content) }, ctx);
 	});
@@ -306,10 +382,63 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		// disk, so the ledger is reconciled before the round may close.
 		await syncLedger();
 		const context = dispatch({ t: "turn_settled" }, ctx);
+		await setDebugToolsActive(state.active);
 		if (context) return { continue: true, additionalContext: context };
 	});
 
-	registerDebugTools(pi, { getState: () => state, refreshLogCounts, readRunLines, syncLedger });
+	/**
+	 * Apply an explicit handoff from the Agent tool. The machine only accepts one
+	 * while the agent actually holds the round, so a duplicated or late call is
+	 * reported back to the model instead of silently rewriting the user's turn.
+	 */
+	function applyHandoffRequest(request: HandoffRequest, ctx: ExtensionContext): HandoffOutcome {
+		if (!state.active) return { ok: false, error: "debug mode is not active." };
+		if (state.stage !== "investigating") {
+			return {
+				ok: false,
+				error: `round ${currentRound(state).index} is already with the user (stage: ${state.stage}); do not hand off twice.`,
+			};
+		}
+		const round = currentRound(state);
+		const requests = (request.plan ?? round.plan ?? []).length;
+		dispatch({ t: "handoff", mode: request.mode, steps: request.steps, plan: request.plan }, ctx);
+		if (!state.active) return { ok: false, error: "debug mode ended while handing off." };
+		return {
+			ok: true,
+			summary:
+				`Round ${round.index} is now with the user as "${request.mode}": ${request.steps.length} step(s) and ` +
+				`${requests} evidence request(s) are showing in their widget, and /debug-proceed is available. ` +
+				"Stop here — the user reproduces or replies out-of-band.",
+		};
+	}
+
+	registerDebugTools(pi, {
+		getState: () => state,
+		refreshLogCounts,
+		readRunLines,
+		syncLedger,
+		handOff: applyHandoffRequest,
+	});
+
+	/**
+	 * The four debug tools are registered at plugin load as `defaultInactive`, so
+	 * they are not in the model's schema on an ordinary session. They join the
+	 * active set when `/debug-mode` starts (or a resumed session is already in
+	 * debug mode) and leave it on teardown. `setActiveTools` replaces the whole
+	 * enabled list, so this only adds or removes our names.
+	 */
+	async function setDebugToolsActive(wanted: boolean): Promise<void> {
+		const getActive = pi.getActiveTools?.bind(pi);
+		const setActive = pi.setActiveTools?.bind(pi);
+		if (!getActive || !setActive) return;
+		const next = nextActiveTools(getActive(), wanted);
+		if (!next) return;
+		try {
+			await setActive(next);
+		} catch (err) {
+			pi.logger.warn("debug-mode: cannot update the active tool set", { err, wanted });
+		}
+	}
 
 	// ============================== command guards ==============================
 
@@ -321,38 +450,52 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		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.
+	 * Wait out any agent turn, then make sure the round really is with the user.
+	 *
+	 * The turn is claimed rather than inspected. An aborted turn never reaches
+	 * `session_stop`, so a round could sit in `investigating` for the rest of the
+	 * session with every debug command refused; waiting for idle turns "the agent
+	 * is working" into a fact instead of a guess, and anything still unsettled
+	 * afterwards is reclassified on the spot.
 	 */
-	async function claimTurn(ctx: ExtensionContext, action: string): Promise<boolean> {
-		const session = activeSession(ctx);
-		if (!session) return false;
-		if (!ownsTurn(session)) {
+	async function ownTurn(ctx: ExtensionCommandContext): Promise<DebugSession | null> {
+		if (!activeSession(ctx)) return null;
+		await ctx.waitForIdle();
+		if (!state.active) return null;
+		if (state.stage === "cleaning_up") {
 			ctx.ui.notify(
-				`debug-mode: the agent still has round ${currentRound(session).index} (stage: ${session.stage}) — wait for it to stop.`,
+				`debug-mode: cleanup is still finishing — reply to the agent, or use /${COMMAND_ABORT}.`,
 				"error",
 			);
-			return false;
+			return null;
 		}
-		if (session.stage === "open" && ctx.hasUI) {
+		if (state.stage === "investigating") dispatch({ t: "reclaim" }, ctx);
+		return state.active && state.stage === "user_turn" ? state : null;
+	}
+
+	/**
+	 * `ownTurn` plus a confirmation for the rounds where continuing is a judgment
+	 * call: the agent either asked a question or never said what to capture.
+	 */
+	async function takeTurn(ctx: ExtensionCommandContext, action: string): Promise<DebugSession | null> {
+		const session = await ownTurn(ctx);
+		if (!session) return null;
+		const round = currentRound(session);
+		const mode = round.handoff ?? "incomplete";
+		if ((mode === "incomplete" || mode === "question") && 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?`,
+				`${action} round ${round.index}?`,
+				`${describeHandoff(mode, round.index)} Continue with the evidence that already exists?`,
 			);
-			if (!confirmed) return false;
+			if (!confirmed) return null;
 		}
-		return true;
+		return state.active ? state : null;
 	}
 
 	// ============================== round transitions ==============================
 
-	function startDebug(ctx: ExtensionContext, problem: string): void {
+	async function startDebug(ctx: ExtensionContext, problem: string): Promise<void> {
 		const debugDir = debugDirFor(ctx.cwd, ctx.sessionManager.getSessionId());
 		try {
 			fs.mkdirSync(debugDir, { recursive: true });
@@ -362,23 +505,30 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 			ctx.ui.notify("debug-mode: could not create the debug log directory; debug mode was not started", "error");
 			return;
 		}
-		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");
+		const created = createRun(debugDir, 1, null);
+		if ("error" in created) {
+			ctx.ui.notify(
+				`debug-mode: could not initialize the run log file (${created.error}); debug mode was not started.${runLogHint(created.error)}`,
+				"error",
+			);
 			return;
 		}
+		const runId = created.runId;
+		// The start prompt fires a turn immediately, so the four tools must already
+		// be in the schema or round 1 cannot close with hand_off_to_user.
+		await setDebugToolsActive(true);
 		dispatch({ t: "start", problem, debugDir, runId, logFile: path.join(debugDir, ACTIVE_LOG_FILE) }, ctx);
 	}
 
-	async function advanceDebug(ctx: ExtensionContext, userDetails?: string): Promise<void> {
-		if (!(await claimTurn(ctx, "Proceed from"))) return;
+	async function advanceDebug(ctx: ExtensionCommandContext, userDetails?: string): Promise<void> {
+		if (!(await takeTurn(ctx, "/debug-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(
-				"Proceed without runtime logs?",
+				"/debug-proceed without runtime logs?",
 				"No runtime observations were captured for this round. Continue to log analysis anyway?",
 			);
 			if (!confirmed) return;
@@ -387,35 +537,41 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		const stillPending = pendingRequests(state);
 		if (stillPending.length > 0 && ctx.hasUI) {
 			const confirmed = await ctx.ui.confirm(
-				"Proceed without all requested evidence?",
+				"/debug-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 || !ownsTurn(state) || !state.debugDir) return;
+		if (!state.active || state.stage !== "user_turn" || !state.debugDir) return;
 
 		// The digest must be read before the active log is archived and truncated.
+		// Drop the poller first: on Windows a watched file can refuse CREATE_ALWAYS.
 		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");
+		unwatchLogFile();
+		const created = createRun(state.debugDir, currentRound(state).index + 1, closingRun);
+		if ("error" in created) {
+			watchLogFile();
+			ctx.ui.notify(
+				`debug-mode: could not initialize the next run log file (${created.error}); staying on this round.${runLogHint(created.error)}`,
+				"error",
+			);
 			return;
 		}
-		dispatch({ t: "proceed", runId, logCount, hypotheses, details: userDetails, now: Date.now() }, ctx);
+		dispatch({ t: "proceed", runId: created.runId, logCount, hypotheses, details: userDetails, now: Date.now() }, ctx);
 	}
 
-	async function markDebugFixed(ctx: ExtensionContext): Promise<void> {
-		if (!(await claimTurn(ctx, "Mark as fixed from"))) return;
+	async function markDebugFixed(ctx: ExtensionCommandContext): Promise<void> {
+		if (!(await takeTurn(ctx, "/debug-done 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?",
+				"/debug-done 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;
+		if (!state.active || state.stage !== "user_turn") return;
 		dispatch({ t: "mark_fixed" }, ctx);
 	}
 
@@ -430,27 +586,72 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		}
 		if (!state.active) return;
 		dispatch({ t: "abort" }, ctx);
+		await setDebugToolsActive(false);
+	}
+
+	/** Empty this round's live log without advancing. Archived runs stay. */
+	async function clearDebugLog(ctx: ExtensionCommandContext): Promise<void> {
+		if (!activeSession(ctx)) return;
+		await ctx.waitForIdle();
+		if (!state.active || !state.debugDir) return;
+		refreshLogCounts();
+		if (!state.active) return;
+		const discarded = currentLogCount();
+		unwatchLogFile();
+		try {
+			clearActiveLog(state.debugDir);
+		} catch (err) {
+			watchLogFile();
+			const error = fsErrorMessage(err);
+			pi.logger.error("debug-mode: cannot clear run log", {
+				file: path.join(state.debugDir, ACTIVE_LOG_FILE),
+				err,
+			});
+			ctx.ui.notify(
+				`debug-mode: could not clear the run log file (${error}).${runLogHint(error)}`,
+				"error",
+			);
+			return;
+		}
+		refreshLogCounts();
+		watchLogFile();
+		refreshUi();
+		ctx.ui.notify(
+			discarded === 0
+				? "debug-mode: current run log is already empty"
+				: `debug-mode: cleared ${discarded === 1 ? "1 log entry" : `${discarded} log entries`} from this round`,
+			"info",
+		);
 	}
 
 	/**
 	 * 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.
+	 *
+	 * The argument is parsed after the turn is claimed, so the link selector is
+	 * resolved against settled state rather than against whatever the session
+	 * looked like while an agent turn was still running.
 	 */
-	async function attachEvidence(ctx: ExtensionContext, rawPath?: string, requestId: string | null = null): Promise<boolean> {
-		const session = activeSession(ctx);
+	async function attachEvidence(ctx: ExtensionCommandContext, args: string): Promise<boolean> {
+		// Attaching is not a workflow decision, so it claims the turn without the
+		// "continue anyway?" confirmation the advancing commands need.
+		const session = await ownTurn(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");
+		const parsed = parseEvidenceArgument(args, session);
+		if (!parsed.ok) {
+			ctx.ui.notify(`debug-mode: ${parsed.error}`, "error");
 			return false;
 		}
-		let input = rawPath?.trim() ?? "";
+		const requestId = parsed.requestId;
+		let input = parsed.rawPath?.trim() ?? "";
 		if (!input) {
 			if (!ctx.hasUI) {
-				ctx.ui.notify(`Usage: /${COMMAND_EVIDENCE} <path>`, "error");
+				ctx.ui.notify(`Usage: /${COMMAND_EVIDENCE} <request-id|${UNLINKED_SELECTOR}> <path>`, "error");
 				return false;
 			}
-			input = (await ctx.ui.input("Path to debug evidence file", "absolute or cwd-relative path")) ?? "";
+			const target = requestId ? `evidence file for ${requestId}` : "unlinked evidence file";
+			input = (await ctx.ui.input(`Path to ${target}`, "absolute or cwd-relative path")) ?? "";
 			if (!input.trim()) {
 				ctx.ui.notify("debug-mode: no evidence file path provided", "error");
 				return false;
@@ -502,7 +703,7 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 				);
 				return;
 			}
-			startDebug(ctx, problem);
+			await startDebug(ctx, problem);
 		},
 	});
 
@@ -523,32 +724,12 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		},
 	});
 
-	/**
-	 * 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_EVIDENCE, {
-		description: "Attach one user-provided evidence file: /debug-evidence [<request-id>] <path> (no argument opens a path prompt)",
+		description: `Attach one user-provided evidence file: /${COMMAND_EVIDENCE} <request-id|${UNLINKED_SELECTOR}> <path> (selector only opens a path prompt)`,
+		...argumentCompletions(prefix => evidenceCompletions(prefix, state)),
 		handler: async (args, ctx) => {
 			uiCtx = ctx;
-			const { requestId, rawPath } = parseEvidenceArgument(args);
-			await attachEvidence(ctx, rawPath, requestId);
+			await attachEvidence(ctx, args);
 		},
 	});
 
@@ -560,6 +741,14 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand(COMMAND_CLEAR, {
+		description: "Empty the current run log so this round can record a fresh reproduction",
+		handler: async (_args, ctx) => {
+			uiCtx = ctx;
+			await clearDebugLog(ctx);
+		},
+	});
+
 	pi.registerCommand(COMMAND_STATUS, {
 		description: "Show debug mode state",
 		handler: async (_args, ctx) => {
@@ -588,7 +777,7 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 			});
 			ctx.ui.notify(
 				`debug-mode: stage=${session.stage} round=${round.index} run=${run ?? "(none)"}\n` +
-					(round.openReason ? `${describeOpenReason(round.openReason, round.index)}\n` : "") +
+					(round.handoff ? `${describeHandoff(round.handoff, round.index, round.plan === null)}\n` : "") +
 					`${describeLedger(scan)}\n` +
 					`logs: ${session.runHistory.map(r => `${r}=${session.logCounts[r] ?? 0}`).join(", ") || "(none)"}\n` +
 					`this run by hypothesis: ${describeHypotheses(tallies)}\n` +
@@ -638,12 +827,16 @@ export function registerDebugMode(pi: ExtensionAPI): void {
 			}
 			refreshLogCounts();
 			if (state.active) {
+				const round = currentRound(state);
 				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}.`,
+					`debug-mode resumed: round ${round.index}, log=${currentFile ?? "unavailable"}; evidence: ${evidenceSummary(state)}.\n` +
+						`${describeHandoff(round.handoff ?? "incomplete", round.index, round.plan === null)}\n` +
+						`Use /${COMMAND_STATUS}, /${COMMAND_EVIDENCE}, /${COMMAND_DONE}, /${COMMAND_PROCEED}, or /${COMMAND_ABORT}.`,
 					"info",
 				);
 			}
 		}
+		await setDebugToolsActive(state.active);
 		refreshUi();
 		watchLogFile();
 	});