@siuver/omp-debug-mode 0.1.4 → 0.1.5

package/src/evidence.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { DebugState, EvidenceArtifact, EvidenceMethod, EvidenceRequest } from "./state";
+import type { EvidenceArtifact, EvidenceMethod, EvidenceRequest, EvidenceView } from "./state";
 
 /** Upper bound on accepted plan entries so one model reply cannot flood the gate. */
 export const MAX_EVIDENCE_REQUESTS = 12;
@@ -31,7 +31,7 @@ function hasOnlyUniqueValues(values: readonly string[]): boolean {
  * all-or-nothing: any malformed or invalid entry rejects the whole plan so a
  * partial plan can never silently drop a hypothesis.
  */
-export function parseEvidencePlan(text: string, round: number): EvidencePlanParseResult {
+export function parseEvidencePlan(text: string): EvidencePlanParseResult {
 	const match = /<evidence_plan>([\s\S]*?)<\/evidence_plan>/.exec(text);
 	if (!match) return { found: false, valid: false, requests: [] };
 	const fail = (error: string): EvidencePlanParseResult => ({ found: true, valid: false, requests: [], error });
@@ -80,7 +80,6 @@ export function parseEvidencePlan(text: string, round: number): EvidencePlanPars
 			rationale: record.rationale,
 			instructions: record.instructions,
 			...(record.artifactHint === undefined ? {} : { artifactHint: record.artifactHint }),
-			round,
 		});
 	}
 	return { found: true, valid: true, requests };
@@ -116,46 +115,20 @@ export function validateEvidenceArtifact(rawPath: string, cwd: string): Artifact
 	};
 }
 
-/** Record a user-supplied artifact, deduplicating by exact absolute path. */
-export function addEvidenceArtifact(
-	state: DebugState,
-	rawPath: string,
-	cwd: string,
-	requestId: string | null,
-	now = Date.now(),
-): { state: DebugState; artifact: EvidenceArtifact } | { error: string } {
-	if (requestId !== null && !state.evidenceRequests.some(request => request.id === requestId)) {
-		return { error: `unknown evidence request id ${requestId}` };
-	}
-	const validation = validateEvidenceArtifact(rawPath, cwd);
-	if (!validation.ok) return { error: validation.reason };
-	const base = validation.artifact;
-	const existing = state.evidenceArtifacts.find(artifact => artifact.path === base.path);
-	if (existing) {
-		const artifact: EvidenceArtifact = { ...existing, ...base, requestId };
-		return {
-			state: { ...state, evidenceArtifacts: state.evidenceArtifacts.map(a => (a.path === base.path ? artifact : a)) },
-			artifact,
-		};
-	}
-	const artifact: EvidenceArtifact = { id: `artifact-${now.toString(36)}`, requestId, ...base, addedAt: now };
-	return { state: { ...state, evidenceArtifacts: [...state.evidenceArtifacts, artifact] }, artifact };
-}
-
 /**
  * Human-readable evidence description for the blackboard and the model-facing
  * tool. Availability is re-checked on every call: a missing or unreadable file
  * is never treated as captured evidence.
  */
-export function describeEvidence(state: DebugState, round?: number): string {
-	const requests = round === undefined ? state.evidenceRequests : state.evidenceRequests.filter(r => r.round === round);
-	if (requests.length === 0 && state.evidenceArtifacts.length === 0 && state.evidenceObservations.length === 0) {
+export function describeEvidence(view: EvidenceView): string {
+	const { requests, artifacts, observations } = view;
+	if (requests.length === 0 && artifacts.length === 0 && observations.length === 0) {
 		return "(none)";
 	}
 	const lines: string[] = [];
 	for (const request of requests) {
-		const linked = state.evidenceArtifacts.filter(artifact => artifact.requestId === request.id);
-		const reports = state.evidenceObservations.filter(observation => observation.requestIds.includes(request.id));
+		const linked = artifacts.filter(artifact => artifact.requestId === request.id);
+		const reports = observations.filter(observation => observation.requestIds.includes(request.id));
 		const hint = request.artifactHint ? `, artifactHint: ${request.artifactHint}` : "";
 		const coverage =
 			request.method === "user_artifact"
@@ -171,10 +144,10 @@ export function describeEvidence(state: DebugState, round?: number): string {
 			`- ${request.id} [${request.method}] ${request.title} (${coverage})${hint}\n  hypotheses: ${request.hypothesisIds.join(", ")}\n  rationale: ${request.rationale}\n  instructions: ${request.instructions.join(" | ")}`,
 		);
 	}
-	for (const observation of state.evidenceObservations) {
+	for (const observation of observations) {
 		lines.push(`- ${observation.id} [user observation, round ${observation.round}] ${observation.text}`);
 	}
-	for (const artifact of state.evidenceArtifacts) {
+	for (const artifact of artifacts) {
 		let stats: fs.Stats;
 		try {
 			stats = fs.statSync(artifact.path);

package/src/gate.ts

@@ -1,7 +1,9 @@
-import { MINIMIZE_USER_INTERVENTION, PROCEED_REMINDER } from "./methodology";
+import { CLOSE_ROUND_RULES, MINIMIZE_USER_INTERVENTION, PROCEED_REMINDER } from "./methodology";
+import type { OpenReason } from "./state";
 
-/** How many times a single round may be nudged to close itself properly. */
-export const MAX_GATE_NUDGES = 1;
+/** Per-reason nudge budgets: a probe nudge must not spend the closing-tag one. */
+export const MAX_TAG_NUDGES = 1;
+export const MAX_PROBE_NUDGES = 1;
 
 export const GATE_NUDGE =
 	"This round did not close properly. It must end with BOTH a <evidence_plan> JSON block " +
@@ -14,41 +16,68 @@ export const GATE_NUDGE =
 	"A user_artifact request must state the file type, path/capture instructions, how you will inspect the file, " +
 	"and why inspection/probes are inadequate. Do not start new work.";
 
+export const PROBE_NUDGE =
+	"Your evidence plan selects runtime_probe, but no @omp-probe marker for this round exists in the working tree. " +
+	"Instrument the code now with edit/write — that is required work for this round, not a product fix — and only then " +
+	`re-emit <evidence_plan> and <reproduction_steps> followed by "${PROCEED_REMINDER}". ` +
+	CLOSE_ROUND_RULES;
+
 export type GateDecision =
 	/** Hand control to the user and wait for a reproduction/capture. */
-	| { kind: "gate"; missingSteps: boolean; missingEvidencePlan: boolean }
+	| { kind: "gate"; missingPlan: boolean }
 	/** Let the agent finish the round properly before gating. */
-	| { kind: "nudge"; context: string }
-	/** Not a completed round — the agent is mid-conversation with the user. */
-	| { kind: "stay" };
+	| { kind: "nudge"; budget: "tags" | "probes"; context: string }
+	/** The round settled without closing: the ball is with the user, not the gate. */
+	| { kind: "open"; reason: OpenReason };
+
+export interface GateFacts {
+	hasReproductionSteps: boolean;
+	hasEvidencePlan: boolean;
+	/** The plan selects runtime_probe for at least one hypothesis. */
+	declaresRuntimeProbe: boolean;
+	/** Probes this round introduced that the ledger still finds on disk. */
+	liveProbes: number;
+	nudges: { tags: number; probes: number };
+}
 
 /**
- * Decide what a settled agent turn means for the reproduction gate.
+ * Decide what a settled agent turn means.
  *
- * A properly closed round carries both the `<evidence_plan>` block and the
- * `<reproduction_steps>` block. Legacy turns that only supply reproduction
- * steps with no probes still gate (old sessions never emit plans). A turn
- * with work but a missing tag gets one nudge, then gates with the missing
- * flags set so the workflow can never stall.
+ * A round may only close when its declarations are backed by observable facts:
+ * a `runtime_probe` plan needs real `@omp-probe` markers, and both closing tags
+ * must be present. Anything short of that is either one automatic nudge or an
+ * `open` round the user can talk to — never a silent stop that looks gated.
  */
-export function decideGate(args: {
-	hasReproductionSteps: boolean;
-	hasEvidencePlan: boolean;
-	probesThisRound: number;
-	nudgesUsed: number;
-}): GateDecision {
-	if (args.hasReproductionSteps && args.hasEvidencePlan) {
-		return { kind: "gate", missingSteps: false, missingEvidencePlan: false };
+export function decideGate(facts: GateFacts): GateDecision {
+	// Declared instrumentation that never reached disk: the reproduction the
+	// user is about to be asked for could not record anything.
+	if (facts.declaresRuntimeProbe && facts.liveProbes === 0) {
+		if (facts.nudges.probes < MAX_PROBE_NUDGES) return { kind: "nudge", budget: "probes", context: PROBE_NUDGE };
+		return { kind: "open", reason: "probes_missing" };
+	}
+	if (facts.hasReproductionSteps && facts.hasEvidencePlan) {
+		return { kind: "gate", missingPlan: false };
 	}
 	// Legacy/no-probe closure: reproduction steps alone still gate the turn.
-	if (args.hasReproductionSteps && !args.hasEvidencePlan && args.probesThisRound === 0) {
-		return { kind: "gate", missingSteps: false, missingEvidencePlan: true };
+	if (facts.hasReproductionSteps && !facts.hasEvidencePlan && facts.liveProbes === 0) {
+		return { kind: "gate", missingPlan: true };
+	}
+	// Nothing was declared and nothing was instrumented — the agent is talking
+	// to the user, so leave the round open instead of inventing a gate.
+	if (facts.liveProbes === 0 && !facts.hasEvidencePlan) {
+		return { kind: "open", reason: "awaiting_reply" };
+	}
+	if (facts.nudges.tags < MAX_TAG_NUDGES) return { kind: "nudge", budget: "tags", context: GATE_NUDGE };
+	return { kind: "open", reason: "unclosed" };
+}
+
+/** User-facing explanation of why a round is open, plus what to do about it. */
+export function describeOpenReason(reason: OpenReason, round: number): string {
+	if (reason === "probes_missing") {
+		return `Debug round ${round} declared runtime_probe but no probe reached the code, so there is nothing to reproduce yet. Reply to the agent to get it instrumented.`;
+	}
+	if (reason === "unclosed") {
+		return `Debug round ${round} stopped without a complete evidence plan and reproduction steps. Reply to the agent, or run /debug-proceed to close it with whatever evidence exists.`;
 	}
-	if (args.probesThisRound === 0 && !args.hasEvidencePlan) return { kind: "stay" };
-	if (args.nudgesUsed < MAX_GATE_NUDGES) return { kind: "nudge", context: GATE_NUDGE };
-	return {
-		kind: "gate",
-		missingSteps: !args.hasReproductionSteps,
-		missingEvidencePlan: !args.hasEvidencePlan,
-	};
+	return `Debug round ${round} is still open — the agent is waiting on your reply, not on a reproduction.`;
 }

package/src/machine.ts

@@ -0,0 +1,334 @@
+import { parseEvidencePlan } from "./evidence";
+import { decideGate, describeOpenReason } from "./gate";
+import {
+	CLEANUP_NUDGE,
+	buildFixedMessage,
+	buildProceedMessage,
+	buildStartMessage,
+	extractReproductionSteps,
+} from "./methodology";
+import {
+	type DebugSession,
+	type DebugState,
+	type EvidenceArtifact,
+	type EvidenceObservation,
+	type Probe,
+	type Round,
+	INACTIVE,
+	allRequests,
+	blankRound,
+	currentRound,
+	declaresRuntimeProbe,
+	evidenceSummary,
+	freshSession,
+	liveProbeIds,
+	pendingRequests,
+} 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">;
+
+export type DebugEvent =
+	| { t: "start"; problem: string; debugDir: string; runId: string; logFile: string }
+	| { t: "turn_started" }
+	| { t: "assistant_message"; text: string }
+	| { t: "probes_found"; probes: Probe[] }
+	| { t: "ledger_synced"; probes: Probe[] }
+	| { t: "runs_observed"; runHistory: string[]; logCounts: Record<string, number> }
+	| { t: "turn_settled" }
+	| { 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":
+			// A reply to an open round hands the turn back to the agent. The
+			// reproduction gate deliberately survives ordinary conversation.
+			if (session.stage !== "open" && !session.turnProduced) return unchanged(session);
+			return unchanged({
+				...session,
+				stage: session.stage === "open" ? "investigating" : session.stage,
+				turnProduced: false,
+			});
+
+		case "assistant_message":
+			return unchanged(absorbAssistantText(session, event.text));
+
+		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 "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 },
+				],
+			};
+	}
+}
+
+/** 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,
+		plan: plan.found ? (plan.valid ? plan.requests : null) : 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 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({
+		hasReproductionSteps: round.reproductionSteps.length > 0,
+		hasEvidencePlan: round.plan !== null,
+		declaresRuntimeProbe: declaresRuntimeProbe(round),
+		liveProbes: liveProbeIds(session, round).length,
+		nudges: round.nudges,
+	});
+
+	if (decision.kind === "nudge") {
+		const nudges =
+			decision.budget === "probes"
+				? { ...round.nudges, probes: round.nudges.probes + 1 }
+				: { ...round.nudges, tags: round.nudges.tags + 1 };
+		return {
+			state: withRound(session, { ...round, nudges }),
+			effects: [{ kind: "continue", context: decision.context }],
+		};
+	}
+
+	if (decision.kind === "open") {
+		return {
+			state: withRound({ ...session, stage: "open" }, { ...round, openReason: decision.reason }),
+			effects: [
+				{
+					kind: "notify",
+					level: decision.reason === "awaiting_reply" ? "info" : "warning",
+					text: describeOpenReason(decision.reason, round.index),
+				},
+			],
+		};
+	}
+
+	const gated = withRound({ ...session, stage: "awaiting_evidence" }, { ...round, openReason: null });
+	return { state: gated, effects: [{ kind: "notify", ...gateNotice(gated, decision.missingPlan) }] };
+}
+
+function gateNotice(session: ActiveState, missingPlan: boolean): { level: "info" | "warning"; text: string } {
+	const round = currentRound(session);
+	if (missingPlan) {
+		return {
+			level: "warning",
+			text: `Debug round ${round.index} paused, but it added no probes and declared no evidence plan — this round cannot produce runtime evidence. Use /debug-proceed to ask for instrumentation.`,
+		};
+	}
+	const pending = pendingRequests(session, round);
+	if (pending.length > 0) {
+		return {
+			level: "info",
+			text: `Debug round ${round.index} paused. User evidence requested (${pending.length} pending: ${pending.map(r => r.id).join(", ")}) — attach via /debug-evidence <request-id> <path>, then press Proceed.`,
+		};
+	}
+	return { level: "info", text: `Debug round ${round.index} paused. Reproduce the bug, then press Proceed.` };
+}
+
+/** 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/methodology.ts

@@ -12,6 +12,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 +39,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,7 +60,8 @@ 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
+4. Close the round only after step 3 is done for any runtime_probe plan. Emit
+   exactly one <${EVIDENCE_PLAN_TAG}> block containing a
    non-empty JSON array covering EVERY hypothesis:
    <${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"}]
@@ -58,8 +72,9 @@ This is OMP Debug Mode. Follow the steps in order. Do not skip them.
 
 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}"
+   the single combined reproduction/capture sequence the USER performs now, and
+   this exact sentence after the tag: "${PROCEED_REMINDER}"
+   ${CLOSE_ROUND_RULES}
    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.
    Then STOP. The user reproduces out-of-band.
@@ -104,9 +119,11 @@ 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 +
+		" " +
 		"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 exactly one <${EVIDENCE_PLAN_TAG}> JSON block, then <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
 	);
 }
 
@@ -137,8 +154,11 @@ 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 +
+		" " +
+		`Then end with <${EVIDENCE_PLAN_TAG}>, <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
 	);
 }
 
@@ -156,6 +176,12 @@ The user confirmed the fix. Only two things remain:
 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.`;
 
+/** 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 (
 		"User marked the problem FIXED.\n" +

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 {