@siuver/omp-debug-mode 0.1.4 → 0.1.6

package/src/gate.ts

@@ -1,54 +1,147 @@
-import { MINIMIZE_USER_INTERVENTION, PROCEED_REMINDER } from "./methodology";
-
-/** How many times a single round may be nudged to close itself properly. */
-export const MAX_GATE_NUDGES = 1;
-
-export const GATE_NUDGE =
-	"This round did not close properly. It must end with BOTH a <evidence_plan> JSON block " +
-	'({"id","hypothesisIds","method","title","rationale","instructions", optional "artifactHint"}; methods: ' +
-	"agent_inspection, runtime_probe, user_report, user_artifact) AND a <reproduction_steps> numbered list " +
-	`followed by the exact sentence "${PROCEED_REMINDER}", then stop. ` +
-	MINIMIZE_USER_INTERVENTION +
-	" Every entry needs a concrete rationale; a user_report/user_artifact rationale must name why BOTH " +
-	"autonomous inspection and model-added probes cannot answer its hypotheses. " +
-	"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.";
+import { CLOSE_ROUND_RULES, HANDOFF_TOOL } from "./methodology";
+import type { HandoffMode } from "./state";
 
-export type GateDecision =
-	/** Hand control to the user and wait for a reproduction/capture. */
-	| { kind: "gate"; missingSteps: boolean; missingEvidencePlan: 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" };
+/**
+ * Per-reason nudge budgets: a probe nudge must not spend the closing one. Three
+ * matches the host's own cap for this exact failure (a turn that ended without
+ * its required tool call) and stays well under the host's continuation cap. The
+ * budget is only reachable by a model that keeps making tool calls between
+ * reminders — {@link GateFacts.awaitingProgress} stops a purely conversational
+ * turn from spending more than one.
+ */
+export const MAX_HANDOFF_NUDGES = 3;
+export const MAX_PROBE_NUDGES = 1;
 
 /**
- * Decide what a settled agent turn means for the reproduction gate.
- *
- * 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.
+ * Reminders are shaped like the host's own `<system-reminder>` prompts: one
+ * instruction, numbered choices, and an explicit ban on answering in prose. The
+ * blackboard already carries the full methodology on every turn, so restating
+ * it here only buries the single action being asked for.
  */
-export function decideGate(args: {
+function reminder(body: string): string {
+	return `<system-reminder>\n${body}\n\nYou NEVER answer this reminder with plain text.\n</system-reminder>`;
+}
+
+/**
+ * Sent back into a turn that stopped without the closing tool call. `wroteProse`
+ * marks the common near-miss: the round already describes the user's work, so
+ * the reminder asks for the same values as arguments instead of new content.
+ */
+export function handoffNudge(round: number, wroteProse: boolean): string {
+	const prose = wroteProse
+		? "You already described the steps and/or the plan in prose. Prose does not close a round: pass those same " +
+			"values as the `steps` and `plan` arguments, unchanged. "
+		: "";
+	return reminder(
+		`Debug round ${round} ended without the required ${HANDOFF_TOOL} call.\n\n` +
+			`${prose}Call ${HANDOFF_TOOL} now with exactly one mode:\n` +
+			'1. mode "reproduce" — the user must run the app so the probes record. Pass steps and plan.\n' +
+			'2. mode "capture" — the user only supplies a report or a file. Pass steps and plan.\n' +
+			'3. mode "question" — you need an answer before you can plan. steps and plan are optional.\n\n' +
+			"That call is the only thing that hands the session to the user: it renders the steps in their widget and " +
+			"makes /debug-proceed available. A rejected call names exactly what to fix and the round stays yours. Do not start new work.",
+	);
+}
+
+export const PROBE_NUDGE = reminder(
+	"Your evidence plan selects runtime_probe, but the probe ledger is empty — no @omp-probe marker exists anywhere " +
+		"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 call ${HANDOFF_TOOL}.\n\n${CLOSE_ROUND_RULES}`,
+);
+
+export type GateDecision =
+	/**
+	 * Hand the turn to the user. `mode` is guidance for wording only: every mode
+	 * is the same user stage and allows the same commands, so a misjudged mode
+	 * can never make a legitimate command illegal.
+	 */
+	| { kind: "handoff"; mode: HandoffMode; missingPlan: boolean }
+	/** Let the agent finish the round properly before handing it over. */
+	| { kind: "nudge"; budget: "handoff" | "probes"; context: string };
+
+export interface GateFacts {
+	/** Round index, so a reminder can name the round it is about. */
+	round: number;
 	hasReproductionSteps: boolean;
 	hasEvidencePlan: boolean;
-	probesThisRound: number;
-	nudgesUsed: number;
-}): GateDecision {
-	if (args.hasReproductionSteps && args.hasEvidencePlan) {
-		return { kind: "gate", missingSteps: false, missingEvidencePlan: false };
+	/** The plan selects runtime_probe for at least one hypothesis. */
+	declaresRuntimeProbe: boolean;
+	/** The plan asks the user to report or capture something themselves. */
+	needsUserCapture: boolean;
+	/** Probes the ledger still finds on disk, session-wide. */
+	liveProbes: number;
+	/** Probes this round introduced that are still on disk. */
+	probesAddedThisRound: number;
+	nudges: { handoff: number; probes: number };
+	/** A reminder already went out and the agent has not used a tool since. */
+	awaitingProgress: boolean;
+}
+
+/**
+ * Decide what a settled agent turn means.
+ *
+ * The gate only ever runs on a turn that did **not** call the handoff tool: an
+ * explicit call moves the stage itself and never settles through here. So every
+ * path below is a missing tool call, and it is answered with a reminder rather
+ * than with a silent closure — accepting the prose form as equivalent is what
+ * taught the model that skipping the call costs nothing.
+ *
+ * Every outcome is still either one reminder or a handoff, so the gate can never
+ * park a round in a state the user cannot act on.
+ */
+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 handoff("incomplete", facts);
+	}
+	if (facts.nudges.handoff < MAX_HANDOFF_NUDGES && !facts.awaitingProgress) {
+		return { kind: "nudge", budget: "handoff", context: handoffNudge(facts.round, wroteProse(facts)) };
+	}
+	return handoff(proseMode(facts), facts);
+}
+
+function wroteProse(facts: GateFacts): boolean {
+	return facts.hasReproductionSteps || facts.hasEvidencePlan;
+}
+
+/**
+ * What the round meant when the tool call never came. The prose is still the
+ * best available description of the user's work: reproduction steps are a work
+ * order the user has already read, so handing over as anything but `reproduce`
+ * would leave them acting on instructions the session claims do not exist.
+ */
+function proseMode(facts: GateFacts): HandoffMode {
+	if (facts.hasReproductionSteps) {
+		return facts.needsUserCapture && !facts.declaresRuntimeProbe ? "capture" : "reproduce";
+	}
+	// A user-assisted plan describes user work even when the steps tag is absent.
+	if (facts.hasEvidencePlan && facts.needsUserCapture) return "capture";
+	// Nothing declared and nothing instrumented this round: the agent was talking
+	// to the user, which is an ordinary question rather than a broken round.
+	if (!facts.hasEvidencePlan && facts.probesAddedThisRound === 0) return "question";
+	return "incomplete";
+}
+
+function handoff(mode: HandoffMode, facts: GateFacts): GateDecision {
+	const expectsPlan = mode === "reproduce" || mode === "capture";
+	return { kind: "handoff", mode, missingPlan: expectsPlan && !facts.hasEvidencePlan };
+}
+
+/** What the user should do now, and which command clears this mode. */
+export function describeHandoff(mode: HandoffMode, round: number, missingPlan = false): string {
+	const planNote = missingPlan
+		? " The agent declared no valid evidence plan for this round, so nothing links what you capture to a hypothesis."
+		: "";
+	if (mode === "reproduce") {
+		return `Debug round ${round} is yours: reproduce the bug so the probes can record, then /debug-proceed.${planNote}`;
+	}
+	if (mode === "capture") {
+		return `Debug round ${round} is yours: supply the requested report or file, then /debug-proceed.${planNote}`;
 	}
-	// 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 (mode === "question") {
+		return `Debug round ${round} is yours: the agent is waiting on your reply, not on a reproduction. Run /debug-proceed only once you have something to analyze.`;
 	}
-	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} stopped without telling you what to reproduce or capture. Reply in the editor to get it finished, or /debug-proceed to continue with whatever evidence already exists.`;
 }

package/src/log-files.ts

@@ -1,115 +1,154 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export const ACTIVE_LOG_FILE = "current.jsonl";
-
-export function resolveRunLogFile(
-	debugDir: string | null,
-	run: string | null,
-	activeRun: string | null,
-): string | null {
-	if (!debugDir || !run) return null;
-	return path.join(debugDir, run === activeRun ? ACTIVE_LOG_FILE : `${run}.jsonl`);
-}
-
-export function readJsonlLines(file: string | null): string[] {
-	if (!file) return [];
-	try {
-		return fs
-			.readFileSync(file, "utf8")
-			.split(/\r?\n/)
-			.filter(line => line.trim().length > 0);
-	} catch {
-		return [];
-	}
-}
-
-interface CountEntry {
-	size: number;
-	mtimeMs: number;
-	count: number;
-}
-
-/**
- * Line counts keyed by file identity. The reproduction gate polls the active
- * log once a second, so re-reading every archived run each time would scale
- * with the length of the debugging session for no new information.
- */
-export class JsonlLineCounter {
-	#cache = new Map<string, CountEntry>();
-
-	count(file: string | null): number {
-		if (!file) return 0;
-		const stat = fs.statSync(file, { throwIfNoEntry: false });
-		if (!stat) {
-			this.#cache.delete(file);
-			return 0;
-		}
-		const hit = this.#cache.get(file);
-		if (hit && hit.size === stat.size && hit.mtimeMs === stat.mtimeMs) return hit.count;
-		const count = readJsonlLines(file).length;
-		this.#cache.set(file, { size: stat.size, mtimeMs: stat.mtimeMs, count });
-		return count;
-	}
-
-	clear(): void {
-		this.#cache.clear();
-	}
-}
-
-export interface HypothesisTally {
-	id: string;
-	count: number;
-}
-
-const UNATTRIBUTED = "(unattributed)";
-
-/**
- * Group observations by the hypothesis each probe was meant to settle, so the
- * user and the agent can see which hypotheses actually produced evidence
- * before anyone reads the raw log.
- */
-export function summarizeHypotheses(lines: readonly string[]): HypothesisTally[] {
-	const counts = new Map<string, number>();
-	for (const line of lines) {
-		let id = UNATTRIBUTED;
-		try {
-			const entry = JSON.parse(line) as { hypothesisId?: unknown };
-			if (typeof entry.hypothesisId === "string" && entry.hypothesisId.trim().length > 0) {
-				id = entry.hypothesisId.trim();
-			}
-		} catch {
-			continue;
-		}
-		counts.set(id, (counts.get(id) ?? 0) + 1);
-	}
-	return [...counts]
-		.map(([id, count]) => ({ id, count }))
-		.sort((a, b) => (b.count !== a.count ? b.count - a.count : a.id < b.id ? -1 : 1));
-}
-
-export function describeHypotheses(tallies: readonly HypothesisTally[]): string {
-	if (tallies.length === 0) return "no hypothesis-attributed observations";
-	return tallies.map(t => `${t.id}=${t.count}`).join(", ");
-}
-
-export function prepareRunLog(debugDir: string, previousRun: string | null): string {
-	const activeFile = path.join(debugDir, ACTIVE_LOG_FILE);
-	const archivedFile = previousRun ? path.join(debugDir, `${previousRun}.jsonl`) : null;
-
-	try {
-		if (archivedFile) {
-			if (fs.existsSync(activeFile)) fs.copyFileSync(activeFile, archivedFile);
-			else fs.writeFileSync(archivedFile, "", { flag: "a" });
-		}
-		fs.writeFileSync(activeFile, "", { flag: "w" });
-		return activeFile;
-	} catch (error) {
-		if (archivedFile) {
-			try {
-				fs.rmSync(archivedFile, { force: true });
-			} catch {}
-		}
-		throw error;
-	}
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const ACTIVE_LOG_FILE = "current.jsonl";
+
+export function resolveRunLogFile(
+	debugDir: string | null,
+	run: string | null,
+	activeRun: string | null,
+): string | null {
+	if (!debugDir || !run) return null;
+	return path.join(debugDir, run === activeRun ? ACTIVE_LOG_FILE : `${run}.jsonl`);
+}
+
+export function readJsonlLines(file: string | null): string[] {
+	if (!file) return [];
+	try {
+		return fs
+			.readFileSync(file, "utf8")
+			.split(/\r?\n/)
+			.filter(line => line.trim().length > 0);
+	} catch {
+		return [];
+	}
+}
+
+interface CountEntry {
+	size: number;
+	mtimeMs: number;
+	count: number;
+}
+
+/**
+ * Line counts keyed by file identity. The reproduction gate polls the active
+ * log once a second, so re-reading every archived run each time would scale
+ * with the length of the debugging session for no new information.
+ */
+export class JsonlLineCounter {
+	#cache = new Map<string, CountEntry>();
+
+	count(file: string | null): number {
+		if (!file) return 0;
+		const stat = fs.statSync(file, { throwIfNoEntry: false });
+		if (!stat) {
+			this.#cache.delete(file);
+			return 0;
+		}
+		const hit = this.#cache.get(file);
+		if (hit && hit.size === stat.size && hit.mtimeMs === stat.mtimeMs) return hit.count;
+		const count = readJsonlLines(file).length;
+		this.#cache.set(file, { size: stat.size, mtimeMs: stat.mtimeMs, count });
+		return count;
+	}
+
+	clear(): void {
+		this.#cache.clear();
+	}
+}
+
+export interface HypothesisTally {
+	id: string;
+	count: number;
+}
+
+const UNATTRIBUTED = "(unattributed)";
+
+/**
+ * Group observations by the hypothesis each probe was meant to settle, so the
+ * user and the agent can see which hypotheses actually produced evidence
+ * before anyone reads the raw log.
+ */
+export function summarizeHypotheses(lines: readonly string[]): HypothesisTally[] {
+	const counts = new Map<string, number>();
+	for (const line of lines) {
+		let id = UNATTRIBUTED;
+		try {
+			const entry = JSON.parse(line) as { hypothesisId?: unknown };
+			if (typeof entry.hypothesisId === "string" && entry.hypothesisId.trim().length > 0) {
+				id = entry.hypothesisId.trim();
+			}
+		} catch {
+			continue;
+		}
+		counts.set(id, (counts.get(id) ?? 0) + 1);
+	}
+	return [...counts]
+		.map(([id, count]) => ({ id, count }))
+		.sort((a, b) => (b.count !== a.count ? b.count - a.count : a.id < b.id ? -1 : 1));
+}
+
+export function describeHypotheses(tallies: readonly HypothesisTally[]): string {
+	if (tallies.length === 0) return "no hypothesis-attributed observations";
+	return tallies.map(t => `${t.id}=${t.count}`).join(", ");
+}
+
+const BUSY_CODES = new Set(["EBUSY", "EACCES", "EAGAIN"]);
+const TRUNCATE_ATTEMPTS = 6;
+const TRUNCATE_RETRY_MS = 50;
+
+function sleepSync(ms: number): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function errorCode(error: unknown): string | undefined {
+	if (error && typeof error === "object" && "code" in error && typeof error.code === "string") {
+		return error.code;
+	}
+}
+
+function isBusyError(error: unknown): boolean {
+	const code = errorCode(error);
+	return code !== undefined && BUSY_CODES.has(code);
+}
+
+/**
+ * Empty the stable probe path for the next round. Windows fails CREATE_ALWAYS
+ * while another process (or this process's own `watchFile`) still has the
+ * file open, so busy errors are retried; a successful archive is never
+ * rolled back if truncate then fails.
+ */
+function truncateActiveLog(activeFile: string): void {
+	let last: unknown;
+	for (let attempt = 0; attempt < TRUNCATE_ATTEMPTS; attempt++) {
+		if (attempt > 0) sleepSync(TRUNCATE_RETRY_MS);
+		try {
+			fs.writeFileSync(activeFile, "", { flag: "w" });
+			return;
+		} catch (error) {
+			last = error;
+			if (!isBusyError(error)) throw error;
+		}
+		try {
+			fs.truncateSync(activeFile, 0);
+			return;
+		} catch (error) {
+			last = error;
+			if (!isBusyError(error)) throw error;
+		}
+	}
+	throw last;
+}
+
+export function prepareRunLog(debugDir: string, previousRun: string | null): string {
+	fs.mkdirSync(debugDir, { recursive: true });
+	const activeFile = path.join(debugDir, ACTIVE_LOG_FILE);
+	const archivedFile = previousRun ? path.join(debugDir, `${previousRun}.jsonl`) : null;
+
+	if (archivedFile) {
+		if (fs.existsSync(activeFile)) fs.copyFileSync(activeFile, archivedFile);
+		else fs.writeFileSync(archivedFile, "", { flag: "a" });
+	}
+	truncateActiveLog(activeFile);
+	return activeFile;
+}