@siuver/omp-debug-mode 0.1.3 → 0.1.5

package/src/evidence.ts

@@ -0,0 +1,169 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+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;
+
+const METHODS: readonly EvidenceMethod[] = ["agent_inspection", "runtime_probe", "user_report", "user_artifact"];
+
+export interface EvidencePlanParseResult {
+	found: boolean;
+	valid: boolean;
+	requests: EvidenceRequest[];
+	error?: string;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+function hasOnlyUniqueValues(values: readonly string[]): boolean {
+	return new Set(values).size === values.length;
+}
+
+/**
+ * Parse the `<evidence_plan>` block from a model reply. Validation is
+ * 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): 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 });
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(match[1].trim());
+	} catch (error) {
+		return fail(`malformed JSON in <evidence_plan>: ${(error as Error).message}`);
+	}
+	if (!Array.isArray(parsed)) return fail("<evidence_plan> must contain a JSON array");
+	if (parsed.length === 0) return fail("<evidence_plan> array must not be empty");
+	if (parsed.length > MAX_EVIDENCE_REQUESTS) {
+		return fail(`<evidence_plan> has ${parsed.length} entries; at most ${MAX_EVIDENCE_REQUESTS} are allowed`);
+	}
+
+	const requests: EvidenceRequest[] = [];
+	const seenIds = new Set<string>();
+	for (const entry of parsed) {
+		if (typeof entry !== "object" || entry === null) return fail("every evidence plan entry must be an object");
+		const record = entry as Record<string, unknown>;
+		if (!isNonEmptyString(record.id)) return fail("every evidence plan entry needs a non-empty id");
+		if (seenIds.has(record.id)) return fail(`duplicate evidence request id ${record.id}`);
+		seenIds.add(record.id);
+		if (!isNonEmptyStringArray(record.hypothesisIds) || !hasOnlyUniqueValues(record.hypothesisIds)) {
+			return fail(`request ${record.id} needs one or more unique non-empty hypothesisIds`);
+		}
+		if (!METHODS.includes(record.method as EvidenceMethod)) {
+			return fail(`request ${record.id} has unknown method ${JSON.stringify(record.method)}`);
+		}
+		if (!isNonEmptyString(record.title)) return fail(`request ${record.id} needs a non-empty title`);
+		if (!isNonEmptyString(record.rationale)) {
+			return fail(`request ${record.id} needs a non-empty rationale explaining why this method is decisive`);
+		}
+		if (!isNonEmptyStringArray(record.instructions)) {
+			return fail(`request ${record.id} needs one or more non-empty instructions`);
+		}
+		if (record.artifactHint !== undefined && !isNonEmptyString(record.artifactHint)) {
+			return fail(`request ${record.id} has an empty artifactHint`);
+		}
+		requests.push({
+			id: record.id,
+			hypothesisIds: record.hypothesisIds,
+			method: record.method as EvidenceMethod,
+			title: record.title,
+			rationale: record.rationale,
+			instructions: record.instructions,
+			...(record.artifactHint === undefined ? {} : { artifactHint: record.artifactHint }),
+		});
+	}
+	return { found: true, valid: true, requests };
+}
+
+export type ArtifactValidation =
+	| { ok: true; artifact: Omit<EvidenceArtifact, "id" | "addedAt" | "requestId"> }
+	| { ok: false; reason: string };
+
+/**
+ * Resolve a user-supplied path and capture filesystem metadata only. The file
+ * is referenced in place: its contents are never read, copied or deleted here.
+ */
+export function validateEvidenceArtifact(rawPath: string, cwd: string): ArtifactValidation {
+	const trimmed = rawPath.trim();
+	if (trimmed.length === 0) return { ok: false, reason: "no evidence file path provided" };
+	const absolute = path.resolve(cwd, trimmed);
+	let stats: fs.Stats;
+	try {
+		stats = fs.statSync(absolute);
+	} catch (error) {
+		return { ok: false, reason: `cannot stat ${absolute}: ${(error as Error).message}` };
+	}
+	if (!stats.isFile()) return { ok: false, reason: `${absolute} is not a regular file` };
+	try {
+		fs.accessSync(absolute, fs.constants.R_OK);
+	} catch {
+		return { ok: false, reason: `${absolute} is not readable` };
+	}
+	return {
+		ok: true,
+		artifact: { path: absolute, name: path.basename(absolute), size: stats.size, mtimeMs: stats.mtimeMs },
+	};
+}
+
+/**
+ * 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(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 = 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"
+				? linked.length > 0
+					? "artifact attached"
+					: "PENDING artifact"
+				: request.method === "user_report"
+					? reports.length > 0
+						? "report submitted"
+						: "PENDING report"
+					: "agent-collected";
+		lines.push(
+			`- ${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 observations) {
+		lines.push(`- ${observation.id} [user observation, round ${observation.round}] ${observation.text}`);
+	}
+	for (const artifact of artifacts) {
+		let stats: fs.Stats;
+		try {
+			stats = fs.statSync(artifact.path);
+			fs.accessSync(artifact.path, fs.constants.R_OK);
+		} catch {
+			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (file missing or unreadable)`);
+			continue;
+		}
+		if (!stats.isFile()) {
+			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (no longer a regular file)`);
+			continue;
+		}
+		const linked = artifact.requestId ? `, request ${artifact.requestId}` : ", unlinked";
+		lines.push(
+			`- ${artifact.id} [artifact] ${artifact.path} — available${linked}, ${stats.size} bytes, mtime ${new Date(stats.mtimeMs).toISOString()}`,
+		);
+	}
+	return lines.join("\n");
+}

package/src/gate.ts

@@ -1,36 +1,83 @@
-import { 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 produce reproduction steps. */
-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 =
-	"You instrumented this round but did not end with a <reproduction_steps> block. " +
-	"List the numbered steps the user must perform to exercise the instrumented path, " +
-	`follow them with "${PROCEED_REMINDER}", and then stop. Do not start new work.`;
+	"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.";
+
+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. */
-	| { kind: "gate"; missingSteps: boolean }
+	/** Hand control to the user and wait for a reproduction/capture. */
+	| { 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.
  *
- * Cursor gates on the `<reproduction_steps>` block, so a turn without one is
- * either a clarifying question (leave the user talking to the agent) or an
- * instrumented round that forgot to close itself (nudge once, then gate anyway
- * 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;
-	probesThisRound: number;
-	nudgesUsed: number;
-}): GateDecision {
-	if (args.hasReproductionSteps) return { kind: "gate", missingSteps: false };
-	if (args.probesThisRound === 0) return { kind: "stay" };
-	if (args.nudgesUsed < MAX_GATE_NUDGES) return { kind: "nudge", context: GATE_NUDGE };
-	return { kind: "gate", missingSteps: true };
+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 (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.`;
+	}
+	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)`,
+			},
+		],
+	};
+}