@siuver/omp-debug-mode 0.1.4 → 0.1.6

package/src/machine.ts

@@ -0,0 +1,421 @@
+import { parseEvidencePlan } from "./evidence";
+import { type GateFacts, MAX_HANDOFF_NUDGES, MAX_PROBE_NUDGES, decideGate, describeHandoff } from "./gate";
+import {
+	CLEANUP_NUDGE,
+	buildFixedMessage,
+	buildProceedMessage,
+	buildStartMessage,
+	extractReproductionSteps,
+} from "./methodology";
+import {
+	type DebugSession,
+	type DebugState,
+	type EvidenceArtifact,
+	type EvidenceObservation,
+	type EvidenceRequest,
+	type HandoffMode,
+	type Probe,
+	type Round,
+	INACTIVE,
+	allRequests,
+	blankRound,
+	currentRound,
+	declaresRuntimeProbe,
+	evidenceSummary,
+	freshSession,
+	liveProbeCount,
+	needsUserCapture,
+	pendingRequests,
+	roundProbeIds,
+} from "./state";
+
+export const PROMPT_START = "debug-mode-start";
+export const PROMPT_PROCEED = "debug-mode-proceed";
+export const PROMPT_FIXED = "debug-mode-fixed";
+
+/** Artifact metadata gathered by the shell; the reducer only files it. */
+export type ArtifactCandidate = Omit<EvidenceArtifact, "id" | "addedAt" | "requestId">;
+
+/** No nudges left: used when there is no agent turn to send anything back to. */
+const SPENT_NUDGES = { handoff: MAX_HANDOFF_NUDGES, probes: MAX_PROBE_NUDGES };
+
+export type DebugEvent =
+	| { t: "start"; problem: string; debugDir: string; runId: string; logFile: string }
+	| { t: "turn_started" }
+	/** A user message landed in the transcript — the only thing that ends a user turn. */
+	| { t: "user_replied" }
+	| { t: "assistant_message"; text: string }
+	/** Any tool call: the progress signal the reminder guard waits for. */
+	| { t: "tool_used" }
+	| { t: "probes_found"; probes: Probe[] }
+	| { t: "ledger_synced"; probes: Probe[] }
+	| { t: "runs_observed"; runHistory: string[]; logCounts: Record<string, number> }
+	| { t: "turn_settled" }
+	/** An explicit `hand_off_to_user` call: intent the machine can trust. */
+	| { t: "handoff"; mode: HandoffMode; steps: string[]; plan: EvidenceRequest[] | null }
+	/** The user takes the turn back from a round that never settled. */
+	| { t: "reclaim" }
+	| { t: "proceed"; runId: string; logCount: number; hypotheses: string; details?: string; now: number }
+	| { t: "mark_fixed" }
+	| { t: "attach_artifact"; candidate: ArtifactCandidate; requestId: string | null; now: number }
+	| { t: "abort" };
+
+export type Effect =
+	| { kind: "notify"; level: "info" | "warning" | "error"; text: string }
+	/** Inject a prompt and start an agent turn. */
+	| { kind: "prompt"; customType: string; content: string; summary: string }
+	/** Keep the current turn going instead of settling it. */
+	| { kind: "continue"; context: string }
+	| { kind: "teardown"; outcome: "finished" | "aborted"; probesLeft: Probe[]; debugDir: string | null };
+
+export interface Transition {
+	state: DebugState;
+	effects: Effect[];
+}
+
+/** A narrowed active state. Kept as one type so no-ops can return it verbatim. */
+type ActiveState = { active: true } & DebugSession;
+
+function unchanged(state: DebugState): Transition {
+	return { state, effects: [] };
+}
+
+function withRound(session: ActiveState, round: Round): ActiveState {
+	return { ...session, rounds: [...session.rounds.slice(0, -1), round] };
+}
+
+/**
+ * The whole state machine. Pure and total: every transition is a function of
+ * the previous state plus one event, and anything that touches the filesystem,
+ * the host UI or the model is returned as an effect for the shell to apply.
+ */
+export function reduce(state: DebugState, event: DebugEvent): Transition {
+	if (event.t === "start") {
+		if (state.active) return unchanged(state);
+		return {
+			state: { active: true, ...freshSession(event.problem, event.debugDir, event.runId) },
+			effects: [
+				{
+					kind: "prompt",
+					customType: PROMPT_START,
+					content: buildStartMessage(event.problem, event.logFile),
+					summary: "debug mode started — hypotheses and instrumentation",
+				},
+			],
+		};
+	}
+	if (!state.active) return unchanged(state);
+	const session: ActiveState = state;
+
+	switch (event.t) {
+		case "turn_started":
+			// Deliberately stage-blind. A turn can start without the user doing
+			// anything — a todo reminder, a plan nudge or any other host
+			// continuation resumes the agent loop, which starts a turn while the
+			// round is still with the user. Reading "a turn began" as "the user
+			// replied" is what let those continuations take the user's turn away.
+			return session.turnProduced ? unchanged({ ...session, turnProduced: false }) : unchanged(session);
+
+		case "user_replied":
+			// A reply at a handoff hands the round back to the agent. Keeping the
+			// user stage through the turn would make the entire turn invisible to
+			// the machine and silently discard the plan and steps it produced.
+			return unchanged(session.stage === "user_turn" ? reopenRound(session) : session);
+
+		case "assistant_message":
+			return unchanged(absorbAssistantText(session, event.text));
+
+		case "tool_used":
+			return unchanged(clearNudgeWait(session));
+
+		case "probes_found": {
+			const fresh = event.probes.filter(probe => !session.probes.some(known => known.id === probe.id));
+			if (fresh.length === 0) return unchanged(session);
+			const probes = [...session.probes, ...fresh];
+			if (session.stage !== "investigating") return unchanged({ ...session, probes });
+			const round = currentRound(session);
+			return unchanged(
+				withRound({ ...session, probes }, { ...round, probeIds: [...round.probeIds, ...fresh.map(p => p.id)] }),
+			);
+		}
+
+		case "ledger_synced": {
+			const same =
+				event.probes.length === session.probes.length &&
+				event.probes.every((probe, i) => probe.id === session.probes[i]?.id);
+			return unchanged(same ? session : { ...session, probes: event.probes });
+		}
+
+		case "runs_observed":
+			return unchanged({ ...session, runHistory: event.runHistory, logCounts: event.logCounts });
+
+		case "turn_settled":
+			return settle(session);
+
+		case "handoff":
+			return applyHandoff(session, event);
+
+		case "reclaim":
+			return reclaim(session);
+
+		case "proceed":
+			return advance(session, event);
+
+		case "mark_fixed":
+			return startCleanup(session);
+
+		case "attach_artifact":
+			return attach(session, event);
+
+		case "abort":
+			return {
+				state: INACTIVE,
+				effects: [
+					{ kind: "teardown", outcome: "aborted", probesLeft: session.probes, debugDir: session.debugDir },
+				],
+			};
+	}
+}
+
+/**
+ * Give the round back to the agent. Nudge budgets are per agent turn rather
+ * than per round: a round the user replied to must still be repairable, or one
+ * spent budget would silence every later turn in the same round.
+ */
+function reopenRound(session: ActiveState): ActiveState {
+	const round = currentRound(session);
+	return withRound(
+		{ ...session, stage: "investigating", turnProduced: false },
+		{ ...round, handoff: null, nudges: { handoff: 0, probes: 0 }, awaitingProgress: false },
+	);
+}
+
+/**
+ * Clear the reminder guard. A tool call means the agent acted on the reminder
+ * instead of restating itself, so the next settle may remind it again; a turn
+ * that only produces more prose keeps the guard set and is handed over.
+ */
+function clearNudgeWait(session: ActiveState): ActiveState {
+	if (session.stage !== "investigating") return session;
+	const round = currentRound(session);
+	if (!round.awaitingProgress) return session;
+	return withRound(session, { ...round, awaitingProgress: false });
+}
+
+/** Record the round artefacts a settled-but-not-yet-judged turn produced. */
+function absorbAssistantText(session: ActiveState, text: string): ActiveState {
+	const round = currentRound(session);
+	const steps = session.stage === "investigating" ? extractReproductionSteps(text) : [];
+	const plan = session.stage === "investigating" ? parseEvidencePlan(text) : { found: false, valid: false, requests: [] };
+	const next: Round = {
+		...round,
+		reproductionSteps: steps.length > 0 ? steps : round.reproductionSteps,
+		// A later malformed block must never erase a plan that already validated:
+		// the round would lose evidence requests the user was already shown.
+		plan: plan.valid ? plan.requests : round.plan,
+	};
+	const roundChanged = next.reproductionSteps !== round.reproductionSteps || next.plan !== round.plan;
+	if (!roundChanged) return session.turnProduced ? session : { ...session, turnProduced: true };
+	return withRound({ ...session, turnProduced: true }, next);
+}
+
+function gateFacts(session: ActiveState, round: Round): GateFacts {
+	return {
+		round: round.index,
+		hasReproductionSteps: round.reproductionSteps.length > 0,
+		hasEvidencePlan: round.plan !== null,
+		declaresRuntimeProbe: declaresRuntimeProbe(round),
+		needsUserCapture: needsUserCapture(round),
+		liveProbes: liveProbeCount(session),
+		probesAddedThisRound: roundProbeIds(session, round).length,
+		nudges: round.nudges,
+		awaitingProgress: round.awaitingProgress,
+	};
+}
+
+function settle(session: ActiveState): Transition {
+	if (session.stage === "cleaning_up") return finishCleanup(session);
+	if (session.stage !== "investigating" || !session.turnProduced) return unchanged(session);
+
+	const round = currentRound(session);
+	const decision = decideGate(gateFacts(session, round));
+
+	if (decision.kind === "nudge") {
+		const nudges =
+			decision.budget === "probes"
+				? { ...round.nudges, probes: round.nudges.probes + 1 }
+				: { ...round.nudges, handoff: round.nudges.handoff + 1 };
+		return {
+			state: withRound(session, { ...round, nudges, awaitingProgress: true }),
+			effects: [{ kind: "continue", context: decision.context }],
+		};
+	}
+
+	return handOff(session, decision.mode, decision.missingPlan);
+}
+
+/**
+ * Move the round to the user. Every settled turn ends here: the mode only
+ * changes the wording, so a mode the agent misjudged can never make a command
+ * illegal. The notify text leads with the same sentence as the widget so the
+ * transcript and the widget cannot disagree about whose move it is.
+ */
+function handOff(session: ActiveState, mode: HandoffMode, missingPlan: boolean): Transition {
+	const round = currentRound(session);
+	const next = withRound({ ...session, stage: "user_turn" }, { ...round, handoff: mode });
+	const pending = pendingRequests(next);
+	const detail = pending.length > 0 ? ` Pending: ${pending.map(request => request.id).join(", ")}.` : "";
+	return {
+		state: next,
+		effects: [
+			{
+				kind: "notify",
+				level: mode === "incomplete" || missingPlan ? "warning" : "info",
+				text: `${describeHandoff(mode, round.index, missingPlan)}${detail}`,
+			},
+		],
+	};
+}
+
+/**
+ * An explicit handoff call. The tool has already validated its arguments, so
+ * this records the declared plan and steps and hands over without consulting
+ * the gate: the agent said what it wants, and guessing from its prose is the
+ * failure mode the tool exists to remove.
+ */
+function applyHandoff(session: ActiveState, event: Extract<DebugEvent, { t: "handoff" }>): Transition {
+	if (session.stage !== "investigating") return unchanged(session);
+	const round = currentRound(session);
+	const updated: Round = {
+		...round,
+		plan: event.plan ?? round.plan,
+		reproductionSteps: event.steps.length > 0 ? event.steps : round.reproductionSteps,
+	};
+	const staged = withRound({ ...session, turnProduced: true }, updated);
+	const expectsPlan = event.mode !== "question";
+	return handOff(staged, event.mode, expectsPlan && updated.plan === null);
+}
+
+/**
+ * Classify a round whose turn never settled. An aborted turn never reaches
+ * `session_stop`, so without this the stage would stay `investigating` and
+ * every debug command would refuse for the rest of the session.
+ */
+function reclaim(session: ActiveState): Transition {
+	if (session.stage !== "investigating") return unchanged(session);
+	const round = currentRound(session);
+	// There is no turn left to continue, so no nudge is available.
+	const decision = decideGate({ ...gateFacts(session, round), nudges: SPENT_NUDGES });
+	if (decision.kind === "nudge") return handOff(session, "incomplete", round.plan === null);
+	return handOff(session, decision.mode, decision.missingPlan);
+}
+
+/** Cleanup may only finish once the ledger is actually empty. */
+function finishCleanup(session: ActiveState): Transition {
+	if (!session.turnProduced) return unchanged(session);
+	if (session.probes.length > 0 && session.cleanupNudges < 1) {
+		return {
+			state: { ...session, cleanupNudges: session.cleanupNudges + 1 },
+			effects: [{ kind: "continue", context: `${CLEANUP_NUDGE}\nRemaining probes: ${JSON.stringify(session.probes)}` }],
+		};
+	}
+	return {
+		state: INACTIVE,
+		effects: [{ kind: "teardown", outcome: "finished", probesLeft: session.probes, debugDir: session.debugDir }],
+	};
+}
+
+function advance(session: ActiveState, event: Extract<DebugEvent, { t: "proceed" }>): Transition {
+	const closing = currentRound(session);
+	const details = event.details?.trim() ?? "";
+	let withObservation: ActiveState = session;
+	if (details.length > 0) {
+		const reportIds = (closing.plan ?? [])
+			.filter(request => request.method === "user_report")
+			.map(request => request.id);
+		const observation: EvidenceObservation = {
+			id: `observation-${event.now.toString(36)}`,
+			requestIds: reportIds,
+			text: details,
+			round: closing.index,
+			addedAt: event.now,
+		};
+		withObservation = { ...session, observations: [...session.observations, observation] };
+	}
+
+	const summary = evidenceSummary(withObservation, closing);
+	const next: ActiveState = {
+		...withObservation,
+		stage: "investigating",
+		turnProduced: false,
+		rounds: [...withObservation.rounds, blankRound(closing.index + 1, event.runId)],
+		runHistory: [...withObservation.runHistory, event.runId],
+		logCounts: { ...withObservation.logCounts, [event.runId]: 0 },
+	};
+	const label = details.length > 0 ? "proceed with user details" : "proceed";
+	return {
+		state: next,
+		effects: [
+			{
+				kind: "prompt",
+				customType: PROMPT_PROCEED,
+				content: buildProceedMessage({
+					run: closing.runId ?? "(none)",
+					logCount: event.logCount,
+					userDetails: details.length > 0 ? details : undefined,
+					hypotheses: event.hypotheses,
+					evidenceSummary: summary,
+				}),
+				summary: `${label} — analyzing run ${closing.runId ?? "(none)"} (${event.logCount} entries)`,
+			},
+		],
+	};
+}
+
+function startCleanup(session: ActiveState): Transition {
+	const next: ActiveState = { ...session, stage: "cleaning_up", turnProduced: false, cleanupNudges: 0 };
+	const evidenceJson = JSON.stringify({
+		requests: allRequests(session),
+		observations: session.observations,
+		artifacts: session.artifacts,
+	});
+	return {
+		state: next,
+		effects: [
+			{
+				kind: "prompt",
+				customType: PROMPT_FIXED,
+				content: buildFixedMessage(JSON.stringify(session.probes), evidenceJson),
+				summary: `marked fixed — removing ${session.probes.length} probe(s)`,
+			},
+		],
+	};
+}
+
+function attach(session: ActiveState, event: Extract<DebugEvent, { t: "attach_artifact" }>): Transition {
+	if (event.requestId !== null && !allRequests(session).some(request => request.id === event.requestId)) {
+		return {
+			state: session,
+			effects: [
+				{ kind: "notify", level: "error", text: `debug-mode: unknown evidence request id ${event.requestId}` },
+			],
+		};
+	}
+	const existing = session.artifacts.find(artifact => artifact.path === event.candidate.path);
+	const artifact: EvidenceArtifact = existing
+		? { ...existing, ...event.candidate, requestId: event.requestId }
+		: { id: `artifact-${event.now.toString(36)}`, requestId: event.requestId, ...event.candidate, addedAt: event.now };
+	const artifacts = existing
+		? session.artifacts.map(a => (a.path === artifact.path ? artifact : a))
+		: [...session.artifacts, artifact];
+	return {
+		state: { ...session, artifacts },
+		effects: [
+			{
+				kind: "notify",
+				level: "info",
+				text: `debug-mode: attached ${artifact.id} → ${artifact.path} (${artifact.size} bytes)`,
+			},
+		],
+	};
+}

package/src/main.ts

@@ -1,24 +1,24 @@
-/**
- * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
- *
- * State machine (matches Cursor Debug Mode):
- *   IDLE → /debug-mode <problem>
- *   → 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)
- *
- * - `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 } from "@oh-my-pi/pi-coding-agent";
-import { registerDebugMode } from "./debug-mode";
-
-export default function debugModeExtension(pi: ExtensionAPI) {
-	pi.setLabel("Debug Mode");
-	registerDebugMode(pi);
-}
+/**
+ * Debug Mode Extension — Cursor-style human-in-the-loop debugging for omp.
+ *
+ * State machine (matches Cursor Debug Mode):
+ *   IDLE → /debug-mode <problem>
+ *   → agent writes 3-5 hypotheses and @omp-probe instrumentation (no product fix)
+ *   → WAITING_REPRO: agent stops; user reproduces out-of-band
+ *   → /debug-proceed [details] → agent reads logs, evaluates hypotheses, fixes only
+ *     with evidence, keeps probes, and asks for a verification reproduce → loop
+ *   → /debug-done → agent removes probes + summarizes → teardown (logs deleted)
+ *
+ * - `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 } from "@oh-my-pi/pi-coding-agent";
+import { registerDebugMode } from "./debug-mode";
+
+export default function debugModeExtension(pi: ExtensionAPI) {
+	pi.setLabel("Debug Mode");
+	registerDebugMode(pi);
+}

package/src/methodology.ts

@@ -1,7 +1,26 @@
-export const PROCEED_REMINDER = "Press Proceed/Mark as fixed when done.";
+export const PROCEED_REMINDER =
+	"When done, run /debug-proceed to analyze this round, or /debug-done if the bug is fixed.";
 
 export const EVIDENCE_PLAN_TAG = "evidence_plan";
 
+/** The Agent tool that ends an agent turn and hands the round to the user. */
+export const HANDOFF_TOOL = "hand_off_to_user";
+
+/**
+ * Stated wherever a round is closed. Prose cannot move the session: the model
+ * announcing a reproduction is not the same event as the session reaching the
+ * user, and conflating them is what leaves a round unclosed while the user has
+ * already been told to act.
+ */
+export const HANDOFF_RULE =
+	`Close every round by calling ${HANDOFF_TOOL} as your last action. Pass mode ("reproduce" when the user must run ` +
+	'the app, "capture" when they only supply a report or file, "question" when you need an answer before you can ' +
+	"plan), the evidence plan array, and the numbered steps the USER performs now. That tool call is the only thing " +
+	"that hands the session to the user, and it replies with exactly what to fix when an argument is wrong, so a " +
+	`rejected call is repaired in this turn. <${EVIDENCE_PLAN_TAG}> and <reproduction_steps> in prose are still read ` +
+	"for their contents, but they never close a round: a turn that stops without the tool call is sent straight back " +
+	"to you to make it.";
+
 /** The least-user-intervention evidence method ordering, verbatim for prompts. */
 export const MINIMIZE_USER_INTERVENTION =
 	"MINIMIZE USER INTERVENTION. Choose the cheapest reliable evidence method per hypothesis, in this exact order: " +
@@ -12,6 +31,18 @@ export const MINIMIZE_USER_INTERVENTION =
 	"NEVER ask the user to run a command you can run yourself. Batch all unavoidable user actions into the fewest reproductions/captures. " +
 	"Do not choose a lower-priority method merely because it is familiar.";
 
+/**
+ * Closing-tag order repeated in the methodology, start prompt, and proceed prompt.
+ * Probe edits must land before the round may close; reproduction_steps are user-only.
+ */
+export const CLOSE_ROUND_RULES =
+	"If any selected method is runtime_probe, write @omp-probe instrumentation into the working tree in THIS turn before closing — probe edits are required and are not a product fix. " +
+	`Do not emit <${EVIDENCE_PLAN_TAG}> or <reproduction_steps> for a runtime_probe round until those probes are already on disk. ` +
+	"A runtime_probe plan without @omp-probe markers is an incomplete round: keep going and instrument first. " +
+	"<reproduction_steps> lists only actions the user performs now (reproduce, capture, restart). " +
+	"Never include future agent work such as installing probes, reading logs, or analyzing results. " +
+	"agent_inspection, user_report, and user_artifact rounds may close without adding probes.";
+
 export const METHODOLOGY = `\
 [DEBUG MODE METHODOLOGY — follow strictly]
 This is OMP Debug Mode. Follow the steps in order. Do not skip them.
@@ -27,8 +58,9 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
 
    Every plan entry needs a concrete rationale. A user_report or user_artifact rationale must explicitly name why BOTH autonomous inspection AND model-added probes cannot answer the hypotheses; a generic statement such as "need more information" is invalid.
 
-3. For runtime_probe rounds, instrument code with probes that test ALL remaining
-   hypotheses in parallel. Do not apply a product fix in this step. NEVER fix without evidence first. Always rely on runtime logs plus code — never code inspection alone. Unit tests are optional and never replace a user reproduction.
+3. For runtime_probe rounds, instrument code in THIS turn with probes that test
+   ALL remaining hypotheses in parallel. ${CLOSE_ROUND_RULES}
+   Do not apply a product fix in this step. NEVER fix without evidence first. Always rely on runtime logs plus code — never code inspection alone. Unit tests are optional and never replace a user reproduction.
 
    Probe rules:
    - Wrap EACH probe in a collapsible region (\`// #region agent log\` /
@@ -47,8 +79,10 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
    - The extension truncates the current log file at the start of each round.
      Do not delete, rename, or overwrite that file yourself.
 
-4. Close the round. Emit exactly one <${EVIDENCE_PLAN_TAG}> block containing a
-   non-empty JSON array covering EVERY hypothesis:
+4. Close the round only after step 3 is done for any runtime_probe plan.
+   ${HANDOFF_RULE}
+   The plan is a non-empty JSON array covering EVERY hypothesis, in the same
+   shape accepted inside a legacy <${EVIDENCE_PLAN_TAG}> block:
    <${EVIDENCE_PLAN_TAG}>
    [{"id":"E1","hypothesisIds":["A","B"],"method":"runtime_probe","title":"...","rationale":"The disputed runtime branches are not present in existing logs; one model-added probe set can capture both without a separate user artifact.","instructions":["..."],"artifactHint":"optional"}]
    </${EVIDENCE_PLAN_TAG}>
@@ -56,17 +90,22 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
    Use artifactHint only for user_artifact (expected file kind). Give actionable
    numbered capture/report instructions in instructions.
 
-5. Ask the user to reproduce (or capture/report, per the plan). End your response
-   with a <reproduction_steps> numbered list (no header inside the tag) describing
-   the single combined reproduction/capture sequence, and this exact sentence
-   after the tag: "${PROCEED_REMINDER}"
-   Never say "click". Never ask the user to reply "done". Remind them to restart
-   the app or service if the instrumented code would otherwise be stale.
+5. Ask the user to reproduce (or capture/report, per the plan). Pass the single
+   combined reproduction/capture sequence the USER performs now as the steps
+   argument of ${HANDOFF_TOOL} — the widget the user reads is built from that
+   call, not from your prose. A <reproduction_steps> numbered list (no header
+   inside the tag) followed by "${PROCEED_REMINDER}" is read as content but
+   closes nothing, so make the call even when you also wrote the prose.
+   ${CLOSE_ROUND_RULES}
+   Never say "click" or "press Proceed": those buttons do not exist. Name
+   /debug-proceed and /debug-done by those exact commands. Never ask the user to
+   reply "done". Remind them to restart the app or service if the instrumented
+   code would otherwise be stale.
    Then STOP. The user reproduces out-of-band.
    No logs may be expected for user_report/user_artifact plans: evaluate the
    requested user evidence instead of treating absent probes as a failed round.
 
-6. After Proceed: call list_debug_evidence, then read logs with get_debug_logs
+6. After /debug-proceed: call list_debug_evidence, then read logs with get_debug_logs
    (previous=true for the completed run). Evaluate EACH hypothesis as CONFIRMED,
    REJECTED, or INCONCLUSIVE citing the selected evidence method: hypothesis ID
    plus log-line numbers, a submitted observation, or an attached artifact/report
@@ -83,7 +122,7 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
 8. After a fix, ask the user to reproduce again. Compare before/after logs with
    cited entries. Do not claim success without that proof.
 
-9. If verification proves success and the user chooses Mark as fixed: remove
+9. If verification proves success and the user runs /debug-done: remove
    every probe, verify with list_debug_probes that the ledger is empty, then
    summarize the root cause and the final fix in 1-2 lines.
 
@@ -104,9 +143,14 @@ export function buildStartMessage(problem: string, logFile: string): string {
 		MINIMIZE_USER_INTERVENTION +
 		"\n\n" +
 		"Begin round 1: generate 3-5 precise hypotheses, decide an evidence method for each, and do NOT apply a product fix yet. " +
+		CLOSE_ROUND_RULES +
+		" " +
+		HANDOFF_RULE +
+		" " +
 		"Call list_debug_evidence whenever you need the request/observation/artifact ledger. " +
 		"Cite evidence as hypothesis ID plus log-line number or attached observation/artifact/report path. " +
-		`Close with exactly one <${EVIDENCE_PLAN_TAG}> JSON block, then <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+		`Then close with ${HANDOFF_TOOL} — prose alone never closes a round, so make the call even if you also wrote ` +
+		`a <${EVIDENCE_PLAN_TAG}> block — tell the user "${PROCEED_REMINDER}" and STOP.`
 	);
 }
 
@@ -137,8 +181,13 @@ export function buildProceedMessage(args: {
 		"Call list_debug_evidence first, then read the previous run with get_debug_logs (previous=true). " +
 		"Evaluate each hypothesis CONFIRMED/REJECTED/INCONCLUSIVE citing hypothesis ID plus log-line number or attached observation/artifact/report path. " +
 		"Fix only if a hypothesis is confirmed with 100% confidence; keep all probes in place for a verification reproduce. " +
-		"If not confident, re-instrument without a speculative patch; after an inconclusive round, reconsider a lower-burden method instead of repeating the same user request. " +
-		`If a previous fix failed, first revert code changes from rejected hypotheses. End with <${EVIDENCE_PLAN_TAG}>, <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+		"If not confident, re-instrument in this turn without a speculative patch; after an inconclusive round, reconsider a lower-burden method instead of repeating the same user request. " +
+		"If a previous fix failed, first revert code changes from rejected hypotheses. " +
+		CLOSE_ROUND_RULES +
+		" " +
+		HANDOFF_RULE +
+		" " +
+		`Then end with ${HANDOFF_TOOL} — prose alone never closes a round — tell the user "${PROCEED_REMINDER}" and STOP.`
 	);
 }
 
@@ -154,7 +203,15 @@ The user confirmed the fix. Only two things remain:
    \`#region agent log\` wrapper, then call list_debug_probes and confirm the
    ledger is empty. Keep the proven fix; remove nothing else.
 2. Summarize in 1-2 lines: the root cause and the fix that is staying.
-Do not add probes, form new hypotheses, or ask for another reproduction.`;
+Do not add probes, form new hypotheses, or ask for another reproduction, and do
+not call ${HANDOFF_TOOL}: cleanup ends when the ledger is empty and you have
+summarized.`;
+
+/** Sent back into a cleanup turn that ended with probes still in the code. */
+export const CLEANUP_NUDGE =
+	"Cleanup is not finished: the probe ledger below is still not empty. Remove each remaining `@omp-probe` marker " +
+	"and its `#region agent log` wrapper from the code, keep the proven fix, then call list_debug_probes to confirm " +
+	"the ledger is empty before summarizing.";
 
 export function buildFixedMessage(probesJson: string, evidenceJson = "[]"): string {
 	return (

package/src/probes.ts

@@ -23,15 +23,17 @@ export function probeFileFromInput(input: Record<string, unknown>, cwd: string):
 	return path.resolve(cwd, raw);
 }
 
-/** Register every `@omp-probe <id>` marker introduced by an edit/write tool call. */
-export function recordProbes(probes: Probe[], round: number, input: Record<string, unknown>, cwd: string): void {
+/** Every `@omp-probe <id>` marker an edit/write tool call introduces, deduplicated by id. */
+export function probesInInput(input: Record<string, unknown>, cwd: string, round: number): Probe[] {
 	const file = probeFileFromInput(input, cwd);
+	const found: Probe[] = [];
 	for (const [key, value] of Object.entries(input)) {
 		if (PRE_EDIT_KEYS.test(key)) continue;
 		for (const id of probeIdsIn(value)) {
-			if (!probes.some(p => p.id === id)) probes.push({ id, file, round });
+			if (!found.some(p => p.id === id)) found.push({ id, file, round });
 		}
 	}
+	return found;
 }
 
 export interface LedgerScan {
@@ -73,13 +75,11 @@ export async function scanLedger(probes: readonly Probe[]): Promise<LedgerScan>
 }
 
 /**
- * Rescan and prune the ledger so it mirrors the code on disk. Unreadable files
- * keep their probes so a transient read error cannot fake a clean teardown.
+ * The ledger as it should be after a rescan. Unreadable files keep their probes
+ * so a transient read error cannot fake a clean teardown.
  */
-export async function syncLedger(state: { probes: Probe[] }): Promise<LedgerScan> {
-	const scan = await scanLedger(state.probes);
-	state.probes = [...scan.alive, ...scan.unknown];
-	return scan;
+export function survivingProbes(scan: LedgerScan): Probe[] {
+	return [...scan.alive, ...scan.unknown];
 }
 
 export function describeLedger(scan: LedgerScan): string {