@siuver/omp-debug-mode 0.1.1 → 0.1.3

package/src/methodology.ts

@@ -0,0 +1,140 @@
+export const PROCEED_REMINDER = "Press Proceed/Mark as fixed when done.";
+
+export const METHODOLOGY = `\
+[DEBUG MODE METHODOLOGY — follow strictly]
+This is OMP Debug Mode. Follow the steps in order. Do not skip them.
+
+1. Generate 3-5 precise hypotheses about WHY the bug occurs. Be detailed; prefer
+   more hypotheses over fewer. Mark each hypothesis pending until logs exist.
+
+2. Instrument code with runtime probes that test ALL remaining hypotheses in
+   parallel. Do not apply a product fix in this step. NEVER fix without runtime 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\` /
+     \`// #endregion\`, or the target language equivalent).
+   - Mark every probe with \`@omp-probe <id>\` so the ledger can track it.
+   - Every runtime probe MUST append exactly one compact JSON object plus a
+     newline to the exact absolute log file shown above.
+   - Schema: {"probe":"<id>","hypothesisId":"<A|B|C|...>","ts":<epoch-ms>,"location":"<file:line>","message":"<short>","data":<JSON-serializable-observation>}
+   - Include hypothesisId so each log line can confirm or reject one hypothesis.
+   - Append; never overwrite or truncate. Open, append, flush, and close promptly.
+   - Do not use HTTP, POST, localhost, sockets, or any network transport.
+   - Use the target environment's native file API. Console logging may supplement
+     the file but never replaces it. Never ask the user to copy console output.
+   - Aim for 2-6 probes; at least 1 is required; do not exceed 10.
+   - Never log secrets, tokens, passwords, API keys, or PII.
+   - The extension truncates the current log file at the start of each round.
+     Do not delete, rename, or overwrite that file yourself.
+
+3. Ask the user to reproduce. End your response with a
+   <reproduction_steps> numbered list (no header inside the tag) 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.
+   Then STOP. The user reproduces out-of-band.
+
+4. After Proceed: read logs with get_debug_logs (previous=true for the completed
+   run). Evaluate EACH hypothesis as CONFIRMED, REJECTED, or INCONCLUSIVE with
+   cited log-line evidence. Empty logs are themselves evidence (path not
+   executed, stale build, wrong path, or append failure).
+
+5. Fix only with 100% confidence and log proof. Do NOT remove instrumentation yet.
+   Keep probes active during the fix so the next reproduction can verify it.
+   A speculative fix without log proof is forbidden. If you are not 100%
+   confident, do not patch: update probes, add hypotheses if needed, and ask
+   for another reproduction.
+
+6. After a fix, ask the user to reproduce again. Compare before/after logs with
+   cited entries. Do not claim success without that log proof.
+
+7. If verification logs prove success and the user chooses Mark as fixed: 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.
+
+   If verification failed: FIRST remove any code changes from rejected hypotheses
+   (keep instrumentation and any proven fixes). THEN generate NEW hypotheses from
+   different subsystems, add more instrumentation, and reproduce again.
+
+8. After confirmed success: explain the problem and provide a concise summary
+   of the fix.`;
+
+export function buildStartMessage(problem: string, logFile: string): string {
+	return (
+		`Starting debug mode. Problem report:\n\n${problem}\n\n` +
+		`Runtime log file (absolute): ${logFile}\n` +
+		"Every probe MUST append one JSON object per line to that exact file using the target environment's native file API. " +
+		"Console logging (including Unity Debug.Log) may supplement the file but never replaces it.\n\n" +
+		"Begin round 1: generate 3-5 precise hypotheses, instrument probes that test all of them in parallel, and do NOT apply a product fix yet. " +
+		`End with <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+	);
+}
+
+export function buildProceedMessage(args: {
+	run: string;
+	logCount: number;
+	reproductionDetails?: string;
+	hypotheses?: string;
+}): string {
+	const userEvidence = args.reproductionDetails
+		? `User added reproduction details after run ${args.run}:\n\n${args.reproductionDetails}\n\nTreat these details as evidence alongside the captured logs.\n`
+		: `User chose PROCEED after reproducing (run ${args.run} captured ${args.logCount} log entries).\n`;
+	const logNote =
+		args.logCount === 0
+			? "No logs were captured: the instrumented code path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed — treat that as a signal.\n"
+			: `Run ${args.run} captured ${args.logCount} log entries (by hypothesis: ${args.hypotheses ?? "unknown"}). A hypothesis with no entries was not exercised — that is not the same as being rejected.\n`;
+	return (
+		userEvidence +
+		logNote +
+		"Read the previous run with get_debug_logs (previous=true). Evaluate each hypothesis CONFIRMED/REJECTED/INCONCLUSIVE with cited log lines. " +
+		"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. " +
+		`If a previous fix failed, first revert code changes from rejected hypotheses. End with <reproduction_steps> and "${PROCEED_REMINDER}" then STOP.`
+	);
+}
+
+/**
+ * Cleanup turns get this instead of the full methodology: hypotheses,
+ * instrumentation and reproduction are all behind us, and restating them
+ * invites the agent to start another round instead of finishing.
+ */
+export const CLEANUP_CONTRACT = `\
+[DEBUG MODE — CLEANUP]
+The user confirmed the fix. Only two things remain:
+1. Remove every debug probe listed in the ledger above, including its
+   \`#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.`;
+
+export function buildFixedMessage(probesJson: string): string {
+	return (
+		"User marked the problem FIXED.\n" +
+		"1. Remove every debug probe from the code (probe ledger below; verify with list_debug_probes after edits). Do not revert the proven fix.\n" +
+		"2. Then summarize in 1-2 lines: root cause, the fix applied, what remains in the working diff.\n" +
+		`Probe ledger: ${probesJson}`
+	);
+}
+
+export function extractAssistantText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const block of content) {
+		if (!block || typeof block !== "object") continue;
+		const item = block as { type?: unknown; text?: unknown };
+		if (item.type === "text" && typeof item.text === "string") parts.push(item.text);
+	}
+	return parts.join("\n");
+}
+
+export function extractReproductionSteps(text: string): string[] {
+	const match = /<reproduction_steps>\s*([\s\S]*?)\s*<\/reproduction_steps>/i.exec(text);
+	if (!match) return [];
+	return match[1]
+		.split(/\r?\n/)
+		.map(line => line.trim())
+		.filter(line => line.length > 0);
+}

package/src/probes.ts

@@ -0,0 +1,97 @@
+import * as path from "node:path";
+import type { Probe } from "./state";
+
+const PROBE_MARK = /@omp-probe\s+([A-Za-z0-9_-]+)/g;
+
+/**
+ * Edit-tool fields that describe the code being replaced. Scanning them would
+ * re-register the very probes an edit is removing, so the ledger ignores them.
+ */
+const PRE_EDIT_KEYS = /^old(_?(string|str|text|content|source))?$/i;
+
+export function probeIdsIn(text: unknown): string[] {
+	if (typeof text !== "string") return [];
+	const ids: string[] = [];
+	for (const m of text.matchAll(PROBE_MARK)) ids.push(m[1]);
+	return ids;
+}
+
+/** Absolute path of the file an edit/write tool call targets. */
+export function probeFileFromInput(input: Record<string, unknown>, cwd: string): string {
+	const raw = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : null;
+	if (!raw) return "(unknown)";
+	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 {
+	const file = probeFileFromInput(input, cwd);
+	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 });
+		}
+	}
+}
+
+export interface LedgerScan {
+	/** Marker still present on disk. */
+	alive: Probe[];
+	/** File is gone or no longer contains the marker. */
+	gone: Probe[];
+	/** File exists but could not be read — never assume these were cleaned up. */
+	unknown: Probe[];
+}
+
+/** Ground truth: rescan every recorded file and classify each probe. */
+export async function scanLedger(probes: readonly Probe[]): Promise<LedgerScan> {
+	const scan: LedgerScan = { alive: [], gone: [], unknown: [] };
+	const byFile = new Map<string, Probe[]>();
+	for (const p of probes) {
+		const list = byFile.get(p.file) ?? [];
+		list.push(p);
+		byFile.set(p.file, list);
+	}
+	for (const [file, filedProbes] of byFile) {
+		const handle = Bun.file(file);
+		let text: string | null = null;
+		let readable = true;
+		if (await handle.exists()) {
+			try {
+				text = await handle.text();
+			} catch {
+				readable = false;
+			}
+		}
+		for (const p of filedProbes) {
+			if (!readable) scan.unknown.push(p);
+			else if (text?.includes(`@omp-probe ${p.id}`)) scan.alive.push(p);
+			else scan.gone.push(p);
+		}
+	}
+	return scan;
+}
+
+/**
+ * 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.
+ */
+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 describeLedger(scan: LedgerScan): string {
+	if (scan.alive.length === 0 && scan.unknown.length === 0) return "Probe ledger is EMPTY — all probes removed.";
+	const lines: string[] = [];
+	if (scan.alive.length > 0) {
+		lines.push(`Alive probes (${scan.alive.length}):`);
+		for (const p of scan.alive) lines.push(`${p.id} — ${p.file}`);
+	}
+	if (scan.unknown.length > 0) {
+		lines.push(`Unverified probes (${scan.unknown.length}) — file could not be read, check manually:`);
+		for (const p of scan.unknown) lines.push(`${p.id} — ${p.file}`);
+	}
+	return lines.join("\n");
+}

package/src/review-actions.ts

@@ -0,0 +1,22 @@
+export const REVIEW_MARK_FIXED = "Mark as fixed";
+export const REVIEW_PROCEED = "Proceed";
+export const REVIEW_ADD_DETAILS = "Add reproduction details";
+export const REVIEW_ABORT = "Abort debug mode";
+
+export const REVIEW_OPTIONS = [
+	REVIEW_MARK_FIXED,
+	REVIEW_PROCEED,
+	REVIEW_ADD_DETAILS,
+	REVIEW_ABORT,
+] as const;
+
+export const REVIEW_DESCRIPTIONS: Record<string, string> = {
+	[REVIEW_MARK_FIXED]: "Remove every probe and summarize the root cause",
+	[REVIEW_PROCEED]: "Read the captured logs, judge each hypothesis, continue",
+	[REVIEW_ADD_DETAILS]: "Describe what you observed before continuing",
+	[REVIEW_ABORT]: "Stop debugging and delete the logs; code changes stay",
+};
+
+export function reviewMenuOptions(): { label: string; description: string }[] {
+	return REVIEW_OPTIONS.map(label => ({ label, description: REVIEW_DESCRIPTIONS[label] ?? "" }));
+}

package/src/state.ts

@@ -0,0 +1,147 @@
+import { resolveRunLogFile } from "./log-files";
+
+export const DEBUG_ENTRY = "com.omp.debug-mode.state";
+/** Custom message that carries the blackboard + methodology into the model. */
+export const DEBUG_CONTEXT_TYPE = "debug-mode-context";
+
+export type Phase = "idle" | "round" | "waiting" | "cleanup";
+
+export interface Probe {
+	id: string;
+	file: string;
+	round: number;
+}
+
+export interface DebugState {
+	active: boolean;
+	phase: Phase;
+	problem: string;
+	round: number;
+	runId: string | null;
+	/** Every run in creation order; the last entry is always the active run. */
+	runHistory: string[];
+	probes: Probe[];
+	debugDir: string | null;
+	logCounts: Record<string, number>;
+	hasRoundContent: boolean;
+	cleanupReady: boolean;
+	reproductionSteps: string[];
+	/** Times the current round was asked to produce its reproduction steps. */
+	gateNudges: number;
+}
+
+export function freshState(): DebugState {
+	return {
+		active: false,
+		phase: "idle",
+		problem: "",
+		round: 0,
+		runId: null,
+		runHistory: [],
+		probes: [],
+		debugDir: null,
+		logCounts: {},
+		hasRoundContent: false,
+		cleanupReady: false,
+		reproductionSteps: [],
+		gateNudges: 0,
+	};
+}
+
+/** Order run ids by round number, then by the base36 creation stamp. */
+export function compareRunIds(a: string, b: string): number {
+	const parse = (id: string): [number, string] => {
+		const m = /^run(\d+)-(.*)$/.exec(id);
+		return m ? [Number(m[1]), m[2]] : [Number.POSITIVE_INFINITY, id];
+	};
+	const [roundA, stampA] = parse(a);
+	const [roundB, stampB] = parse(b);
+	if (roundA !== roundB) return roundA - roundB;
+	return stampA < stampB ? -1 : stampA > stampB ? 1 : 0;
+}
+
+export interface RunSelection {
+	run: string | null;
+	/** Set when the resolved run is not the one the caller literally asked for. */
+	note: string | null;
+}
+
+/**
+ * Pick which run `get_debug_logs` should read. The active run is truncated at
+ * the start of every round, so an empty current run falls back to the most
+ * recent run that actually captured something rather than reporting "no logs".
+ */
+export function resolveRun(
+	params: { run?: string; previous?: boolean },
+	runHistory: readonly string[],
+	currentRun: string | null,
+	logCounts: Readonly<Record<string, number>>,
+): RunSelection {
+	if (params.run) return { run: params.run, note: null };
+
+	const currentIndex = currentRun ? runHistory.indexOf(currentRun) : -1;
+	const completed = currentIndex >= 0 ? runHistory.slice(0, currentIndex) : runHistory.filter(r => r !== currentRun);
+
+	if (params.previous) {
+		const previous = completed[completed.length - 1];
+		if (!previous) return { run: null, note: "no completed previous debug run is available" };
+		return { run: previous, note: null };
+	}
+
+	if (currentRun && (logCounts[currentRun] ?? 0) > 0) return { run: currentRun, note: null };
+
+	for (let i = completed.length - 1; i >= 0; i -= 1) {
+		const candidate = completed[i];
+		if ((logCounts[candidate] ?? 0) > 0) {
+			return {
+				run: candidate,
+				note: `the current run (${currentRun ?? "none"}) is empty; showing the last run with observations instead`,
+			};
+		}
+	}
+	return { run: currentRun, note: null };
+}
+
+export function logFileFor(s: DebugState, run = s.runId): string | null {
+	return resolveRunLogFile(s.debugDir, run, s.runId);
+}
+
+/**
+ * Keep only the newest copy of a custom-type injection. `before_agent_start`
+ * re-injects a fresh blackboard every turn; `context` runs afterwards on the
+ * combined history, so deleting every match would drop the copy that was just
+ * added and the model would never see it.
+ */
+export function keepLatestCustomType<M extends { role?: string; customType?: string }>(
+	messages: readonly M[],
+	customType: string,
+): M[] {
+	let last = -1;
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i];
+		if (message?.role === "custom" && message.customType === customType) last = i;
+	}
+	if (last < 0) return [...messages];
+	return messages.filter((message, index) => !(message.role === "custom" && message.customType === customType && index !== last));
+}
+
+export function blackboard(s: DebugState): string {
+	const probes = s.probes.map(p => `${p.id} (${p.file}, round ${p.round})`).join("\n  ") || "(none)";
+	const counts = Object.entries(s.logCounts)
+		.map(([run, n]) => `${run}: ${n}`)
+		.join(", ") || "(none yet)";
+	return `\
+[DEBUG MODE ACTIVE — round ${s.round}]
+
+Problem under investigation:
+${s.problem}
+
+Deployed probes (ground truth, maintained by the extension):
+  ${probes}
+
+Current run log file (absolute path): ${logFileFor(s) ?? "(not initialized)"}
+Runtime probes MUST append JSONL directly to that exact file using the target environment's native file APIs.
+Console output such as Unity Debug.Log may supplement diagnostics but is never the runtime evidence for this workflow. Never ask the user to transcribe console output.
+Logs by run: ${counts}
+Current run id: ${s.runId ?? "(not started)"}`;
+}

package/src/tools.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { describeHypotheses, summarizeHypotheses } from "./log-files";
+import { describeLedger, syncLedger } from "./probes";
+import { type DebugState, logFileFor, resolveRun } from "./state";
+
+export interface DebugToolDeps {
+	state: DebugState;
+	refreshLogCounts(): void;
+	readRunLines(run: string): string[];
+}
+
+export function registerDebugTools(pi: ExtensionAPI, deps: DebugToolDeps): void {
+	const z = pi.zod;
+	const { state, refreshLogCounts, readRunLines } = deps;
+
+	pi.registerTool({
+		name: "get_debug_logs",
+		label: "Get Debug Logs",
+		description:
+			"Read JSONL observations appended directly by debug-mode runtime probes. Each entry: {probe, hypothesisId, ts, location, message, data}. Defaults to the newest run that captured observations; pass previous=true to force the last completed reproduction run.",
+		parameters: z.object({
+			run: z.string().optional().describe("Run id filter (default: the newest run with observations)"),
+			probe: z.string().optional().describe("Probe id filter"),
+			previous: z.boolean().optional().describe("Use the previous (completed) run instead of the current one"),
+		}),
+		approval: "read",
+		async execute(_toolCallId, params) {
+			refreshLogCounts();
+			const selection = resolveRun(params, state.runHistory, state.runId, state.logCounts);
+			if (!selection.run) {
+				return {
+					content: [{ type: "text", text: `(${selection.note ?? "no debug run is available"})` }],
+					details: { run: null, file: null, count: 0 },
+				};
+			}
+
+			const run = selection.run;
+			let lines = readRunLines(run);
+			if (params.probe) {
+				lines = lines.filter(line => {
+					try {
+						const entry = JSON.parse(line) as { probe?: unknown };
+						return entry.probe === params.probe;
+					} catch {
+						return false;
+					}
+				});
+			}
+
+			const tallies = summarizeHypotheses(lines);
+			const scope = selection.note ? `run ${run} — ${selection.note}` : `run ${run}`;
+			const header = `(${scope}; by hypothesis: ${describeHypotheses(tallies)})\n`;
+			const body =
+				lines.join("\n") ||
+				"(no logs captured — the instrumented path may not have executed, the build may be stale, the path may be wrong, or the file append may have failed)";
+			return {
+				content: [{ type: "text", text: header + body }],
+				details: { run, file: logFileFor(state, run), count: lines.length, hypotheses: tallies },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "list_debug_probes",
+		label: "List Debug Probes",
+		description:
+			"Ground-truth probe ledger for debug mode: rescans files for `@omp-probe <id>` markers and reports which probes are actually present in code, with their files. Use to verify cleanup is complete.",
+		parameters: z.object({}),
+		approval: "read",
+		async execute() {
+			const scan = await syncLedger(state);
+			return {
+				content: [{ type: "text", text: describeLedger(scan) }],
+				details: { alive: scan.alive, unknown: scan.unknown },
+			};
+		},
+	});
+}

package/src/ui.ts

@@ -0,0 +1,78 @@
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { PROCEED_REMINDER } from "./methodology";
+import type { DebugState } from "./state";
+
+/** `setWidget` caps string-array widgets at 10 lines. */
+export const WIDGET_MAX_LINES = 10;
+const WIDGET_MAX_STEPS = 6;
+const WIDGET_MAX_WIDTH = 90;
+
+export type WidgetTone = "accent" | "dim";
+
+export interface WidgetLine {
+	text: string;
+	tone: WidgetTone;
+}
+
+export function statusLabel(state: DebugState): string {
+	if (state.phase === "waiting") return "🐞 waiting-repro";
+	if (state.phase === "round") return `🐞 round ${state.round}`;
+	return "🐞 cleanup";
+}
+
+function clip(text: string): string {
+	return text.length > WIDGET_MAX_WIDTH ? `${text.slice(0, WIDGET_MAX_WIDTH - 1)}…` : text;
+}
+
+function plural(count: number, singular: string): string {
+	return `${count} ${singular}${count === 1 ? "" : "s"}`;
+}
+
+function logEntries(count: number): string {
+	return count === 1 ? "1 log entry" : `${count} log entries`;
+}
+
+/**
+ * Reproduction-gate widget: the call to action, an excerpt of the agent's
+ * reproduction steps, and the live evidence counter. Always within the host's
+ * line budget so nothing important is silently dropped.
+ */
+export function waitingWidgetLines(state: DebugState, logCount: number): WidgetLine[] {
+	const lines: WidgetLine[] = [{ text: PROCEED_REMINDER, tone: "accent" }];
+	const shown = state.reproductionSteps.slice(0, WIDGET_MAX_STEPS);
+	for (const step of shown) lines.push({ text: clip(step), tone: "dim" });
+	const hidden = state.reproductionSteps.length - shown.length;
+	if (hidden > 0) lines.push({ text: `… +${plural(hidden, "more step")} in the transcript`, tone: "dim" });
+	lines.push({
+		text: `/debug-menu · run ${state.runId ?? "none"} — ${logEntries(logCount)}`,
+		tone: logCount > 0 ? "accent" : "dim",
+	});
+	return lines.slice(0, WIDGET_MAX_LINES);
+}
+
+export function reviewMenuTitle(round: number, logCount: number, probeCount: number): string {
+	return `Review debug round ${round} · ${logEntries(logCount)} · ${plural(probeCount, "probe")}`;
+}
+
+/**
+ * Render the status entry and the reproduction widget. `getLogCount` is only
+ * consulted at the reproduction gate so idle phases do not touch the log files.
+ */
+export function applyUi(ctx: ExtensionContext | null, state: DebugState, getLogCount: () => number): void {
+	if (!ctx?.hasUI) return;
+	if (!state.active) {
+		ctx.ui.setStatus("debug-mode", undefined);
+		ctx.ui.setWidget("debug-mode", undefined);
+		return;
+	}
+	ctx.ui.setStatus("debug-mode", ctx.ui.theme.fg("warning", statusLabel(state)));
+	if (state.phase !== "waiting") {
+		ctx.ui.setWidget("debug-mode", undefined);
+		return;
+	}
+	const lines = waitingWidgetLines(state, getLogCount());
+	ctx.ui.setWidget(
+		"debug-mode",
+		lines.map(line => ctx.ui.theme.fg(line.tone, line.text)),
+	);
+}

package/src/workspace.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const DEBUG_ROOT = path.join(".omp", "debug");
+/** Line written to `.git/info/exclude` so probe logs stay out of `git status`. */
+export const EXCLUDE_LINE = ".omp/debug/";
+
+/**
+ * Directory name for one session's probe logs. Two omp sessions debugging the
+ * same repository must not share `current.jsonl`: each round truncates it and
+ * teardown deletes it, so a shared directory would let one session erase the
+ * other's evidence.
+ */
+export function sessionDirName(sessionId: string | null | undefined): string {
+	const safe = (sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "");
+	return safe.length > 0 ? safe.slice(0, 16) : "session";
+}
+
+export function debugDirFor(cwd: string, sessionId: string | null | undefined): string {
+	return path.resolve(cwd, DEBUG_ROOT, sessionDirName(sessionId));
+}
+
+/** Walk up from `cwd` to the enclosing `.git` directory, if there is a plain one. */
+export function findGitDir(cwd: string): string | null {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		const candidate = path.join(dir, ".git");
+		try {
+			// A `.git` file means a worktree or submodule; leave those alone.
+			if (fs.statSync(candidate).isDirectory()) return candidate;
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+export function needsExcludeLine(contents: string): boolean {
+	return !contents.split(/\r?\n/).some(line => line.trim() === EXCLUDE_LINE);
+}
+
+export function appendExcludeLine(contents: string): string {
+	if (!needsExcludeLine(contents)) return contents;
+	const separator = contents.length === 0 || contents.endsWith("\n") ? "" : "\n";
+	return `${contents}${separator}${EXCLUDE_LINE}\n`;
+}
+
+/**
+ * Keep probe logs out of the user's working diff via the repository-local
+ * exclude file, which is never committed. Best effort: a read-only or absent
+ * git directory is not a reason to fail debugging.
+ */
+export function excludeDebugLogsFromGit(cwd: string): boolean {
+	const gitDir = findGitDir(cwd);
+	if (!gitDir) return false;
+	const excludeFile = path.join(gitDir, "info", "exclude");
+	try {
+		let contents = "";
+		try {
+			contents = fs.readFileSync(excludeFile, "utf8");
+		} catch {}
+		if (!needsExcludeLine(contents)) return false;
+		fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+		fs.writeFileSync(excludeFile, appendExcludeLine(contents));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Remove the shared `.omp/debug` parent once the last session directory is gone. */
+export function pruneDebugRoot(cwd: string): void {
+	try {
+		fs.rmdirSync(path.resolve(cwd, DEBUG_ROOT));
+	} catch {}
+	try {
+		fs.rmdirSync(path.resolve(cwd, ".omp"));
+	} catch {}
+}