Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/loop/__tests__/contract.test.ts

Raw
import { execFileSync } from "node:child_process";
import {
	existsSync,
	mkdtempSync,
	readFileSync,
	rmSync,
	writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { DatabaseSync } from "node:sqlite";
import { fileURLToPath } from "node:url";
import {
	type FauxResponseStep,
	fauxAssistantMessage,
	fauxToolCall,
	type TranscriptContext,
} from "@earendil-works/pi-ai";
import { initTheme, SessionManager } from "@earendil-works/pi-coding-agent";
import {
	type AutocompleteItem,
	type Component,
	Input,
	rgbColor,
	type TUI,
	TuiAltScreen,
} from "@earendil-works/pi-tui";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
	createPiSession,
	type PiSession,
} from "../../../test/fixture/create-pi-session.ts";
import { stateFileUnignored } from "../src/guide.ts";
import { LoopStore } from "../src/store.ts";
import { MemoryTerminal } from "./terminal.ts";

const extensionPath = fileURLToPath(new URL("../index.ts", import.meta.url));
function alive(pid: number): boolean {
	try {
		process.kill(pid, 0);
		return true;
	} catch (error) {
		if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
		throw error;
	}
}
function killGate(pid: number): void {
	try {
		if (process.platform === "win32")
			execFileSync("taskkill", ["/pid", String(pid), "/T", "/F"], {
				stdio: "ignore",
			});
		else process.kill(-pid, "SIGKILL");
	} catch (error) {
		if (alive(pid)) throw error;
	}
}
let box: PiSession | undefined;
let owned: string | undefined;
afterEach(async () => {
	await box?.dispose();
	box = undefined;
	if (owned) rmSync(owned, { recursive: true, force: true });
	owned = undefined;
});

/** Gate that fails until it has run `passOn` times; state lives in the project cwd. */
function countingGate(passOn: number, name = "counter") {
	return {
		name,
		command: process.execPath,
		args: [
			"-e",
			`const fs=require('fs');const n=(fs.existsSync('count')?+fs.readFileSync('count','utf8'):0)+1;fs.writeFileSync('count',String(n));console.error('attempt '+n);process.exit(n>=${passOn}?0:1)`,
		],
	};
}
const fileGate = {
	name: "ready",
	command: process.execPath,
	args: ["-e", "process.exit(require('fs').existsSync('ready')?0:1)"],
};

const holdUntilAborted: FauxResponseStep = async (_context, options) => {
	await new Promise<void>((resolve) => {
		if (options?.signal?.aborted) return resolve();
		options?.signal?.addEventListener("abort", () => resolve(), { once: true });
	});
	return fauxAssistantMessage("", { stopReason: "aborted" });
};

function promptTexts(context: TranscriptContext) {
	return context.messages.flatMap((message) =>
		message.role === "user"
			? [
					typeof message.content === "string"
						? message.content
						: message.content
								.flatMap((part) => (part.type === "text" ? [part.text] : []))
								.join("\n"),
				]
			: [],
	);
}

async function start(
	options: {
		statePath?: string;
		anim?: string;
		responses?: FauxResponseStep[];
		sessionManager?: SessionManager;
	} = {},
) {
	box = await createPiSession({
		extensionPaths: [extensionPath],
		...(options.sessionManager
			? { sessionManager: options.sessionManager }
			: {}),
		env: {
			PI_LOOP_DEBUG: "0",
			PI_LOOP_STATE_PATH: options.statePath,
			PI_LOOP_ANIM: options.anim,
		},
		responses: options.responses ?? [],
	});
	expect(box.errors).toEqual([]);
	const editors: string[] = [];
	const notes: { message: string; type: string | undefined }[] = [];
	const statuses: (string | undefined)[] = [];
	await box.session.bindExtensions({
		mode: "rpc",
		uiContext: {
			...box.session.extensionRunner.getUIContext(),
			editor: async () => editors.shift(),
			confirm: async () => true,
			setStatus: (key: string, text: string | undefined) => {
				if (key === "loop") statuses.push(text);
			},
			notify: (message: string, type?: "info" | "warning" | "error") => {
				notes.push({ message, type });
			},
		},
	});
	const command = box.extensions[0]!.commands.get("loop")!;
	const session = box;
	return {
		box: session,
		editors,
		notes,
		statuses,
		command,
		run: (args: string) =>
			command.handler(
				args,
				session.session.extensionRunner.createContext() as never,
			),
	};
}

function readDb(path: string) {
	const db = new DatabaseSync(path, { readOnly: true });
	try {
		return {
			runs: db.prepare("SELECT * FROM runs").all(),
			attempts: db.prepare("SELECT * FROM gate_attempts ORDER BY id").all(),
			events: db
				.prepare("SELECT kind FROM events ORDER BY id")
				.all()
				.map((row) => row["kind"]),
		};
	} finally {
		db.close();
	}
}

describe("loop guide safety", () => {
	it("checks Git ignore status without relying on Pi 1.5 exec limits", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-ignore-"));
		execFileSync("git", ["init", "-q", owned]);
		const statePath = join(owned, ".pi", "loop", "state.db");
		expect(await stateFileUnignored(owned, statePath)).toBe(true);
		writeFileSync(join(owned, ".gitignore"), ".pi/\n");
		expect(await stateFileUnignored(owned, statePath)).toBe(false);
		expect(await stateFileUnignored(owned, join(tmpdir(), "outside.db"))).toBe(
			false,
		);
	});
});

describe("loop extension contract", () => {
	it("loops until every gate exits 0 and persists the run in the project", async () => {
		const contexts: string[][] = [];
		const step: FauxResponseStep = (context) => {
			contexts.push(promptTexts(context));
			return fauxAssistantMessage("Tests passed, trust me.");
		};
		const loop = await start({ responses: [step, step, step, step] });
		loop.editors.push(
			"Make the counter gate pass",
			JSON.stringify([
				{ name: "noop", command: process.execPath, args: ["-e", ""] },
				countingGate(3),
			]),
		);
		await loop.run("start");
		await vi.waitFor(
			() =>
				expect(loop.notes.map((note) => note.message).join("\n")).toMatch(
					/succeeded/u,
				),
			{ timeout: 10_000 },
		);
		await loop.box.session.waitForIdle();

		const db = readDb(join(loop.box.cwd, ".pi", "loop", "state.db"));
		expect(db.runs).toHaveLength(1);
		expect(db.runs[0]).toMatchObject({
			status: "succeeded",
			attempts: 3,
			turns: 2,
		});
		// Each attempt runs the gates in order and stops at the first failure.
		expect(
			db.attempts.map((row) => [
				row["attempt_no"],
				row["gate_index"],
				row["exit_code"],
			]),
		).toEqual([
			[1, 0, 0],
			[1, 1, 1],
			[2, 0, 0],
			[2, 1, 1],
			[3, 0, 0],
			[3, 1, 0],
		]);
		expect(db.events).toEqual(
			expect.arrayContaining(["start", "gate_result", "continue", "success"]),
		);
		// The model's claim of success never completed the run; the gate did.
		expect(loop.box.providerState.callCount).toBe(2);
		// The newest prompt carries bounded gate output; older prompts shrink to stubs.
		const second = contexts[1]!;
		const loopPrompts = second.filter((text) => text.startsWith("Loop run"));
		expect(loopPrompts).toHaveLength(2);
		expect(loopPrompts[0]).toMatch(/Superseded by a later loop prompt\.$/u);
		expect(loopPrompts[1]).toContain('gate 2/2 "counter" failed (exit 1)');
		expect(loopPrompts[1]).toContain('stderr tail: "attempt 2\\n"');
		expect(loopPrompts[1]).toMatch(
			/Do not edit, skip, weaken, or redefine the gates/u,
		);
		expect(loopPrompts[1]!.split("\n\n")[0]).toBe(
			contexts[0]![0]!.split("\n\n")[0],
		);
	});

	it("succeeds on a passing baseline without any model request", async () => {
		const loop = await start();
		loop.editors.push("Already done", JSON.stringify([countingGate(1)]));
		await loop.run("start");
		await vi.waitFor(() =>
			expect(loop.notes.at(-1)?.message).toMatch(/succeeded/u),
		);
		expect(loop.box.providerState.callCount).toBe(0);
	});

	it("pauses when the attempt budget is exhausted", async () => {
		const loop = await start();
		loop.editors.push("Never passes", JSON.stringify([fileGate]));
		await loop.run("start none none 1");
		await vi.waitFor(() =>
			expect(loop.notes.at(-1)?.message).toContain("Attempt budget exhausted"),
		);
		expect(loop.statuses.filter(Boolean)).toEqual([]);
		expect(loop.notes.at(-1)).toMatchObject({
			type: "warning",
			message: expect.stringMatching(/paused: Attempt budget exhausted/u),
		});
		expect(loop.box.providerState.callCount).toBe(0);
	});

	it("pauses when the turn budget is exhausted", async () => {
		const loop = await start({ responses: [fauxAssistantMessage("working")] });
		loop.editors.push("Never passes", JSON.stringify([fileGate]));
		await loop.run("start none 1");
		await vi.waitFor(() =>
			expect(loop.notes.at(-1)?.message).toMatch(
				/paused: Turn budget exhausted/u,
			),
		);
		await loop.box.session.waitForIdle();
		expect(loop.box.providerState.callCount).toBe(1);
	});

	it("rejects invalid budgets and gates before running anything", async () => {
		const loop = await start();
		await expect(loop.run("start 0")).rejects.toThrow(
			/Invalid minutes budget/u,
		);
		await expect(loop.run("start none -2")).rejects.toThrow(
			/Invalid turns budget/u,
		);
		loop.editors.push("Goal", '[{"command":"x","shell":true}]');
		await expect(loop.run("start")).rejects.toThrow(/unknown field shell/u);
		expect(existsSync(join(loop.box.cwd, "count"))).toBe(false);
	});

	it("pauses on user stop input and resumes across sessions with consumed budgets", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-contract-"));
		const statePath = join(owned, "state.db");
		const first = await start({ statePath, responses: [holdUntilAborted] });
		first.editors.push(
			"Create the ready file",
			JSON.stringify([{ ...fileGate, cwd: owned }]),
		);
		await first.run("start none 5 4");
		await vi.waitFor(() => expect(first.box.providerState.callCount).toBe(1));
		await first.box.session.extensionRunner.emitInput(
			"stop",
			undefined,
			"interactive",
			"steer",
		);
		await first.box.session.waitForIdle();
		expect(first.notes.map((note) => note.message).join("\n")).toMatch(
			/paused: User stop/u,
		);
		await first.box.dispose();
		box = undefined;

		const before = readDb(statePath).runs[0]!;
		expect(before).toMatchObject({ status: "paused", attempts: 1, turns: 1 });

		const second = await start({ statePath });
		const items = (await second.command.getArgumentCompletions?.(
			"resume ",
		)) as AutocompleteItem[];
		expect(items.map((item) => item.label)).toEqual([
			"latest",
			String(before["id"]).slice(0, 8),
		]);
		writeFileSync(join(owned, "ready"), "");
		await second.run(`resume ${String(before["id"]).slice(0, 8)}`);
		await vi.waitFor(() =>
			expect(second.notes.at(-1)?.message).toMatch(/succeeded/u),
		);
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "succeeded",
			attempts: 2,
			turns: 1,
		});
		await expect(second.run("resume latest")).rejects.toThrow(/No paused run/u);
	});

	it.each(["abort", "switch", "shutdown"])(
		"pauses the active run on %s and never resumes it",
		async (how) => {
			owned = mkdtempSync(join(tmpdir(), "loop-contract-"));
			const statePath = join(owned, "state.db");
			const loop = await start({ statePath, responses: [holdUntilAborted] });
			loop.editors.push("Never passes", JSON.stringify([fileGate]));
			await loop.run("start");
			await vi.waitFor(() => expect(loop.box.providerState.callCount).toBe(1));
			if (how === "abort") await loop.box.session.abort();
			if (how === "switch")
				await loop.box.session.extensionRunner.emit({
					type: "session_before_switch",
					reason: "new",
				} as never);
			// Pi aborts the old session's agent itself during a real switch.
			await loop.box.session.abort();
			if (how === "shutdown") {
				await loop.box.dispose();
				box = undefined;
			} else await loop.box.session.waitForIdle();
			// Longer than the watchdog interval: nothing may kick the paused run.
			await new Promise((resolve) => setTimeout(resolve, 2_500));
			const [run] = readDb(statePath).runs;
			expect(run).toMatchObject({
				status: "paused",
				reason: {
					abort: "Agent aborted",
					switch: "Session changed; never auto-resumed",
					// Disposal may abort the in-flight turn before shutdown handlers run.
					shutdown: expect.stringMatching(/^(Agent aborted|Session shutdown)/u),
				}[how],
			});
			expect(loop.box.providerState.callCount).toBe(1);
		},
		10_000,
	);

	it("pauses on Escape during the baseline pass", async () => {
		const loop = await start();
		let terminal: ((data: string) => unknown) | undefined;
		await loop.box.session.bindExtensions({
			mode: "tui",
			uiContext: {
				...loop.box.session.extensionRunner.getUIContext(),
				editor: async () => loop.editors.shift(),
				notify: (message: string, type?: "info" | "warning" | "error") => {
					loop.notes.push({ message, type });
				},
				onTerminalInput: (handler) => {
					terminal = handler as never;
					return () => {
						terminal = undefined;
					};
				},
			},
		});
		loop.editors.push(
			"Slow gate",
			JSON.stringify([
				{
					command: process.execPath,
					args: ["-e", "setTimeout(() => {}, 20000)"],
				},
			]),
		);
		const started = loop.run("start");
		await vi.waitFor(() => expect(terminal).toBeDefined());
		const pressEscape = terminal!;
		expect(pressEscape("\x1b")).toEqual({ consume: true });
		expect(pressEscape("\x1b")).toBeUndefined();
		await started;
		expect(loop.notes.at(-1)?.message).toMatch(
			/paused: Escape pressed during baseline/u,
		);
		await vi.waitFor(() => expect(terminal).toBeUndefined());
		expect(loop.box.providerState.callCount).toBe(0);
	});

	it("renders baseline feedback in Pi through silent waiting, cancellation and shutdown", async () => {
		initTheme("dark", false);
		const loop = await start();
		let widget: (Component & { dispose?: () => void }) | undefined;
		let removed = false;
		await loop.box.session.bindExtensions({
			mode: "tui",
			uiContext: {
				...loop.box.session.extensionRunner.getUIContext(),
				editor: async () => loop.editors.shift(),
				onTerminalInput: () => () => {},
				setWidget(key, content, options) {
					if (key !== "loop-progress") return;
					expect(options?.placement).toBe("aboveEditor");
					if (typeof content === "function")
						widget = content(
							{
								requestRender() {},
								terminal: { rows: 24, columns: 40 },
							} as TUI,
							loop.box.session.extensionRunner.getUIContext().theme,
						);
					else if (!content) {
						widget?.dispose?.();
						removed = true;
					}
				},
			},
		});
		loop.editors.push(
			"Silent gate",
			JSON.stringify([
				{
					name: "silent",
					command: process.execPath,
					args: ["-e", "setInterval(()=>{},1000)"],
				},
			]),
		);
		const rendered = () =>
			widget
				?.render(100)
				.join("\n")
				.replace(/\x1b\[[0-9;]*m/gu, "") ?? "";
		try {
			await loop.run("start");
			await vi.waitFor(() =>
				expect(rendered()).toContain("Baseline · silent [1/1]"),
			);
			expect(rendered()).toContain("no output yet");
			await vi.waitFor(() => expect(rendered()).toContain("00:01 elapsed"), {
				timeout: 3000,
			});
			await loop.run("pause");
			await vi.waitFor(() => expect(rendered()).toContain("Loop paused"));
			expect(loop.box.providerState.callCount).toBe(0);
			await loop.box.session.extensionRunner.emit({
				type: "session_shutdown",
				reason: "reload",
			});
			expect(removed).toBe(true);
		} finally {
			widget?.dispose?.();
		}
	});

	it.each([undefined, "", "0", "false", "arbitrary"])(
		"toggles the actual corner-overlay TUI factory without gates or model work (PI_LOOP_ANIM=%s)",
		async (anim) => {
			initTheme("dark", false);
			const loop = await start(anim === undefined ? {} : { anim });
			let widget: (Component & { dispose?: () => void }) | undefined;
			const terminal = new MemoryTerminal();
			const host = new TuiAltScreen(terminal);
			const portraits: string[][] = [];
			const showOverlay = host.showOverlay.bind(host);
			host.showOverlay = (component, options) => {
				if (options?.nonCapturing) {
					const paint = component.render.bind(component);
					component.render = (width) => {
						const frame = paint(width);
						portraits.push(frame);
						return frame;
					};
				}
				return showOverlay(component, options);
			};
			const editor = new Input();
			host.addChild(editor);
			host.setFocus(editor);
			host.start();
			const keys: string[] = [];
			const statuses: (string | undefined)[] = [];
			await loop.box.session.bindExtensions({
				mode: "tui",
				uiContext: {
					...loop.box.session.extensionRunner.getUIContext(),
					editor: async () => loop.editors.shift(),
					notify: () => {},
					onTerminalInput: () => () => {},
					setStatus: (_key, text) => statuses.push(text),
					setWidget(key, content, options) {
						keys.push(key);
						expect(options?.placement ?? "aboveEditor").toBe("aboveEditor");
						widget?.dispose?.();
						if (widget) host.removeChild(widget);
						widget =
							typeof content === "function"
								? content(
										host,
										loop.box.session.extensionRunner.getUIContext().theme,
									)
								: undefined;
						if (widget) host.addChild(widget);
					},
				},
			});
			try {
				await loop.run("vixen off");
				expect(existsSync(join(loop.box.cwd, ".pi", "loop"))).toBe(false);
				loop.editors.push("Never passes", JSON.stringify([fileGate]));
				await loop.run("start none none 1");
				await vi.waitFor(() =>
					expect(widget?.render(120).join("")).toContain("paused"),
				);
				const before = readDb(join(loop.box.cwd, ".pi", "loop", "state.db"));
				expect(widget?.render(120).join("")).not.toMatch(/[▀▄]/u);
				const inline = widget?.render(120);
				await loop.run("vixen on");
				host.renderNow();
				expect(widget?.render(120)).toEqual(inline);
				expect(host.getScreenLines().join("")).toMatch(/[▀▄]/u);
				terminal.input("a");
				expect(editor.getValue()).toBe("a");
				const dialog = new Input();
				const foreign = host.showOverlay(dialog, { width: 20 });
				await loop.run("vixen");
				host.renderNow();
				expect(widget?.render(120)).toEqual(inline);
				expect(foreign.isFocused()).toBe(true);
				terminal.input("b");
				expect(dialog.getValue()).toBe("b");
				foreign.hide();
				expect(host.hasOverlay()).toBe(false);
				expect(readDb(join(loop.box.cwd, ".pi", "loop", "state.db"))).toEqual(
					before,
				);
				expect(loop.box.providerState.callCount).toBe(0);
				expect(new Set(keys)).toEqual(new Set(["loop-progress"]));
				expect(statuses.filter(Boolean)).toEqual([]);
				await expect(loop.run("vixen maybe")).rejects.toThrow("Usage:");
				await loop.run("stop");
				expect(widget?.render(120).join("")).toContain("stopped");
				host.renderNow();
				expect(host.hasOverlay()).toBe(false);
				loop.editors.push("Another run", JSON.stringify([fileGate]));
				await loop.run("vixen on");
				await loop.run("start none none 1");
				await vi.waitFor(() =>
					expect(widget?.render(120).join("")).toContain("paused"),
				);
				host.renderNow();
				expect(host.hasOverlay()).toBe(true);
				// Exercise a genuinely resumable pending run, not an exhausted-budget rejection.
				await loop.run("stop");
				loop.editors.push(
					"Resume animation",
					JSON.stringify([
						{
							command: process.execPath,
							args: ["-e", "setInterval(() => {}, 1000)"],
						},
					]),
				);
				await loop.run("start none none none");
				host.renderNow();
				await loop.run("pause");
				await vi.waitFor(async () => {
					await loop.run("resume latest");
				});
				host.renderNow();
				expect(host.hasOverlay()).toBe(true);
				await loop.run("pause");
				const reloadDialog = new Input();
				const reloadOverlay = host.showOverlay(reloadDialog, { width: 20 });
				await loop.box.session.extensionRunner.emit({
					type: "session_shutdown",
					reason: "reload",
				});
				host.renderNow();
				expect(reloadOverlay.isFocused()).toBe(true);
				terminal.input("c");
				expect(reloadDialog.getValue()).toBe("c");
				reloadOverlay.hide();
				expect(host.hasOverlay()).toBe(false);
				// Fresh session_start resolves again before constructing the restored portrait.
				await loop.box.session.extensionRunner.emit({
					type: "session_start",
					reason: "reload",
				});
				host.renderNow();
				expect(host.hasOverlay()).toBe(true);
				const theme = loop.box.session.extensionRunner.getUIContext().theme;
				const cream = theme.style("▀", {
					fg: rgbColor(255, 228, 183),
					bg: rgbColor(255, 228, 183),
				});
				expect(portraits.length).toBeGreaterThan(0);
				// Every painted frame, not merely the final screen, must use the selected art.
				for (const frame of portraits)
					expect(frame.join("").includes(cream)).toBe(anim !== undefined);
			} finally {
				widget?.dispose?.();
				host.stop();
			}
		},
	);

	it("stops a paused persisted run and lists it", async () => {
		const loop = await start();
		loop.editors.push("Never passes", JSON.stringify([fileGate]));
		await loop.run("start none none 1");
		await vi.waitFor(() =>
			expect(loop.notes.at(-1)?.message).toMatch(/paused/u),
		);
		await loop.run("stop latest");
		await loop.run("list");
		expect(loop.notes.at(-1)?.message).toMatch(
			/^[0-9a-f]{8} stopped · attempts 1\/1 · turns 0 · Never passes$/u,
		);
	});

	it("guides goal and gate setup, then loop_begin starts the run", async () => {
		const seen: string[] = [];
		const begin: FauxResponseStep = (context) => {
			seen.push(...promptTexts(context));
			return fauxAssistantMessage(
				fauxToolCall("loop_begin", {
					goal: "Counter reaches two",
					gates: [countingGate(2)],
				}),
				{ stopReason: "toolUse" },
			);
		};
		const loop = await start({
			responses: [begin, fauxAssistantMessage("Working on it.")],
		});
		execFileSync("git", ["init", "-q"], { cwd: loop.box.cwd });
		await loop.run("guide none none 3");
		await vi.waitFor(
			() =>
				expect(loop.notes.map((note) => note.message).join("\n")).toMatch(
					/succeeded/u,
				),
			{ timeout: 10_000 },
		);
		await loop.box.session.waitForIdle();
		const guide = seen.find((text) => text.startsWith("Loop guide:"));
		expect(guide).toMatch(/Interview the user/u);
		expect(guide).toMatch(
			/\.pi[/\\]loop[/\\]state\.db, which Git does not ignore/u,
		);
		const result = loop.box.session.messages.find(
			(message) =>
				message.role === "toolResult" && message.toolName === "loop_begin",
		);
		expect(result).toMatchObject({ isError: false });
		expect(JSON.stringify(result)).toContain(
			'Baseline attempt 1: gate \\"counter\\" failed (exit 1)',
		);
		const db = readDb(join(loop.box.cwd, ".pi", "loop", "state.db"));
		expect(db.runs[0]).toMatchObject({ status: "succeeded", attempts: 2 });
		// Arming is single-use.
		await expect(
			loop.box.extensions[0]!.tools.get("loop_begin")!.definition.execute(
				"again",
				{ goal: "Again", gates: [countingGate(1)] },
				undefined,
				undefined,
				loop.box.session.extensionRunner.createToolContext("again", undefined),
			),
		).rejects.toThrow(/only available after the user runs \/loop guide/u);
	});

	it("lets a blocked agent pause, talk normally, and resume the loop", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-contract-"));
		const statePath = join(owned, "state.db");
		const control = (args: Record<string, string>) =>
			fauxAssistantMessage(fauxToolCall("loop_control", args), {
				stopReason: "toolUse",
			});
		const loop = await start({
			statePath,
			responses: [
				control({ action: "pause", reason: "need the ready file" }),
				fauxAssistantMessage("Please create the ready file."),
				fauxAssistantMessage("It must exist in the project root."),
				control({ action: "resume" }),
				fauxAssistantMessage("Gates pass."),
			],
		});
		loop.editors.push(
			"Create the ready file",
			JSON.stringify([{ ...fileGate, cwd: owned }]),
		);
		await loop.run("start");
		await vi.waitFor(() => expect(loop.box.providerState.callCount).toBe(2));
		await loop.box.session.waitForIdle();
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "paused",
			reason: "Agent paused: need the ready file",
		});
		// Longer than the watchdog: a paused run never prompts on its own.
		await new Promise((resolve) => setTimeout(resolve, 2_500));
		expect(loop.box.providerState.callCount).toBe(2);

		// While paused the human talks with the agent without spending loop budget.
		await loop.box.session.prompt("Where should the file go?");
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "paused",
			turns: 1,
		});

		writeFileSync(join(owned, "ready"), "");
		await loop.box.session.prompt("Created it, carry on.");
		await loop.box.session.waitForIdle();
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "succeeded",
			attempts: 2,
		});
		const results = loop.box.session.messages.filter(
			(message) =>
				message.role === "toolResult" && message.toolName === "loop_control",
		);
		expect(results.map((message) => JSON.stringify(message))).toEqual([
			expect.stringContaining("paused"),
			expect.stringContaining("succeeded"),
		]);
	});

	it("declares loop tools model-only so scripts cannot drive the loop", async () => {
		const loop = await start();
		for (const name of ["loop_begin", "loop_control"])
			expect(loop.box.extensions[0]?.tools.get(name)?.definition.exposure).toBe(
				"model-only",
			);
	});

	it("rejects loop_control pause without an active run", async () => {
		const loop = await start();
		await expect(
			loop.box.extensions[0]?.tools
				.get("loop_control")
				?.definition.execute(
					"pause",
					{ action: "pause", reason: "x" },
					undefined,
					undefined,
					loop.box.session.extensionRunner.createToolContext(
						"pause",
						undefined,
					),
				),
		).rejects.toThrow(/No active loop run/u);
	});

	it("rejects loop_begin without an armed guide", async () => {
		const loop = await start({
			responses: [
				fauxAssistantMessage(
					fauxToolCall("loop_begin", {
						goal: "Sneaky",
						gates: [countingGate(1)],
					}),
					{ stopReason: "toolUse" },
				),
				fauxAssistantMessage("Understood."),
			],
		});
		await loop.box.session.prompt("Start a loop yourself.");
		const result = loop.box.session.messages.find(
			(message) =>
				message.role === "toolResult" && message.toolName === "loop_begin",
		);
		expect(result).toMatchObject({ isError: true });
		expect(existsSync(join(loop.box.cwd, ".pi", "loop"))).toBe(false);
	});

	it("serves the site URL from /loop view and closes it with the session", async () => {
		const loop = await start();
		loop.editors.push("Never passes", JSON.stringify([fileGate]));
		await loop.run("start none none 1");
		await vi.waitFor(() =>
			expect(loop.notes.at(-1)?.message).toMatch(/paused/u),
		);
		await loop.run("view");
		const url = /Loop site: (\S+)/u.exec(loop.notes.at(-1)?.message ?? "")?.[1];
		if (!url) throw new Error("missing site URL");
		const { origin, hash } = new URL(url);
		const snapshot = await (
			await fetch(`${origin}/api/snapshot?token=${hash.slice(1)}`)
		).json();
		expect(snapshot.run).toMatchObject({
			goal: "Never passes",
			status: "paused",
		});
		await loop.box.dispose();
		box = undefined;
		await vi.waitFor(async () => expect(fetch(`${origin}/`)).rejects.toThrow());
	});

	it("cancels a background gate on reload and fences it from a replacement run", async () => {
		const loop = await start();
		loop.editors.push(
			"Old gate",
			JSON.stringify([
				{
					command: process.execPath,
					args: [
						"-e",
						"require('fs').writeFileSync('old-pid',String(process.pid));setInterval(()=>console.log('old output'),100)",
					],
				},
			]),
		);
		await loop.run("start");
		await vi.waitFor(async () => {
			await loop.run("status");
			expect(loop.notes.at(-1)?.message).toContain("old output");
		});
		const pid = Number(readFileSync(join(loop.box.cwd, "old-pid"), "utf8"));
		try {
			await loop.box.session.reload();
			await vi.waitFor(() => expect(alive(pid)).toBe(false));
			const command = loop.box.session.extensionRunner.getCommand("loop")!;
			const run = (args: string) =>
				command.handler(
					args,
					loop.box.session.extensionRunner.createContext() as never,
				);
			await run("status");
			expect(loop.notes.at(-1)?.message).toContain("paused");
			loop.editors.push("Replacement", JSON.stringify([countingGate(1)]));
			await run("start");
			await vi.waitFor(() =>
				expect(loop.notes.at(-1)?.message).toContain("succeeded"),
			);
			const db = readDb(join(loop.box.cwd, ".pi", "loop", "state.db"));
			expect(db.runs.map((row) => row["status"])).toEqual([
				"paused",
				"succeeded",
			]);
			expect(db.attempts).toHaveLength(1);
			expect(loop.box.providerState.callCount).toBe(0);
		} finally {
			if (alive(pid)) killGate(pid);
		}
	});

	it("keeps command dispatch, live observation and pause responsive during a slow baseline", async () => {
		const loop = await start();
		loop.editors.push(
			"Slow output",
			JSON.stringify([
				{
					name: "slow",
					command: process.execPath,
					args: [
						"-e",
						"console.log('x'.repeat(10000));setInterval(()=>console.log('still working'),200)",
					],
				},
			]),
		);
		await loop.run("start");
		await vi.waitFor(async () => {
			await loop.run("status");
			expect(loop.notes.at(-1)?.message).toContain("still working");
		});
		expect(loop.notes.at(-1)?.message).toContain("Running gate 1: slow");
		await loop.run("view");
		const url = new URL(
			/Loop site: (\S+)/u.exec(loop.notes.at(-1)!.message)![1]!,
		);
		const snapshot = await (
			await fetch(`${url.origin}/api/snapshot?token=${url.hash.slice(1)}`)
		).json();
		expect(snapshot.run).toMatchObject({
			status: "active",
			pending: true,
			runningGate: 0,
		});
		expect(snapshot.run.liveOutput.stdout.length).toBeLessThanOrEqual(4096);
		expect(snapshot.run.liveOutput.truncated).toBe(true);
		await loop.run("pause");
		await loop.run("status");
		expect(loop.notes.at(-1)?.message).toContain("paused");
		expect(loop.box.providerState.callCount).toBe(0);
	});

	it("restores a crashed owned run only in its session, preserving diagnostics and budgets", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-crash-"));
		const statePath = join(owned, "state.db");
		const manager = SessionManager.inMemory(owned);
		const controllerUrl = new URL("../src/controller.ts", import.meta.url).href;
		const storeUrl = new URL("../src/store.ts", import.meta.url).href;
		execFileSync(
			process.execPath,
			[
				"--no-warnings",
				"--input-type=module",
				"-e",
				`
			import {LoopStore} from ${JSON.stringify(storeUrl)};
			import {LoopController} from ${JSON.stringify(controllerUrl)};
			const store=await LoopStore.open(${JSON.stringify(statePath)});
			const loop=new LoopController(store,Date.now,()=>new Promise(()=>{}),${JSON.stringify(manager.getSessionId())});
			loop.start({goal:'Survive crash',gates:[{name:'interrupted',command:process.execPath}],cwd:${JSON.stringify(owned)}},{minutes:5,turns:3,attempts:4});
			loop.turn();void loop.checkGates();process.exit(0);
		`,
			],
			{ env: { ...process.env, PI_LOOP_DEBUG: "0" }, timeout: 10_000 },
		);
		const before = readDb(statePath).runs[0]!;
		const different = await start({ statePath });
		expect(different.notes.at(-1)?.message).toContain("not attached");
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "active",
			attempts: 1,
			turns: 1,
		});
		await different.box.dispose();
		box = undefined;
		const same = await start({ statePath, sessionManager: manager });
		expect(same.notes.at(-1)?.message).toContain(String(before["id"]));
		expect(same.notes.at(-1)?.message).toContain("gate interrupted");
		expect(same.notes.at(-1)?.message).toContain("Last activity:");
		for (const action of ["resume", "stop", "status", "view"])
			expect(same.notes.at(-1)?.message).toContain(`/loop ${action}`);
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "paused",
			goal: "Survive crash",
			attempts: 1,
			turns: 1,
			budgets: before["budgets"],
			gates: before["gates"],
		});
		expect(same.box.providerState.callCount).toBe(0);
		await same.run("stop");
	});

	it("rejects resume when a persisted orphan gate survives its owner process", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-orphan-"));
		const statePath = join(owned, "state.db");
		const controllerUrl = new URL("../src/controller.ts", import.meta.url).href;
		const storeUrl = new URL("../src/store.ts", import.meta.url).href;
		execFileSync(
			process.execPath,
			[
				"--no-warnings",
				"--input-type=module",
				"-e",
				`
			import {LoopStore} from ${JSON.stringify(storeUrl)};
			import {LoopController} from ${JSON.stringify(controllerUrl)};
			const store=await LoopStore.open(${JSON.stringify(statePath)});
			const {spawn}=await import('node:child_process');
			// Force survival on Windows too: the test runner's job can otherwise reap descendants.
			const runner=(gate,cwd,signal,onOutput,onProcess)=>{
				const child=spawn(gate.command,gate.args,{cwd,detached:true,stdio:'ignore'});
				onProcess(child.pid);child.unref();return new Promise(()=>{});
			};
			const loop=new LoopController(store,Date.now,runner);
			loop.start({goal:'Orphan',gates:[{command:process.execPath,args:['-e',${JSON.stringify("require('fs').writeFileSync('orphan-ready',String(process.pid));setInterval(()=>{},1000)")}]}],cwd:${JSON.stringify(owned)}});
			void loop.checkGates();
			const {existsSync}=await import('node:fs');
			setInterval(()=>{if(existsSync(${JSON.stringify(join(owned, "orphan-ready"))}))process.exit(0)},10);
			setTimeout(()=>process.exit(2),5000);
		`,
			],
			{ env: { ...process.env, PI_LOOP_DEBUG: "0" }, timeout: 10_000 },
		);
		const db = new DatabaseSync(statePath, { readOnly: true });
		const pid = Number(
			db.prepare("SELECT pid FROM gate_processes").get()!["pid"],
		);
		db.close();
		try {
			expect(alive(pid)).toBe(true);
			const probe = await LoopStore.open(statePath);
			try {
				expect(() =>
					probe.assertGateStopped(String(readDb(statePath).runs[0]!["id"])),
				).toThrow(/Previous gate process/u);
			} finally {
				probe.close();
			}
			const loop = await start({ statePath });
			expect(alive(pid)).toBe(true);
			await expect(loop.run("resume latest")).rejects.toThrow(
				/Previous gate process.*still be running/u,
			);
			expect(readDb(statePath).runs[0]).toMatchObject({
				attempts: 1,
				turns: 0,
			});
			expect(loop.box.providerState.callCount).toBe(0);
		} finally {
			killGate(pid);
		}
	});

	it("restores exhausted runs without auto execution and rejects resume clearly", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-exhausted-"));
		const statePath = join(owned, "state.db");
		const manager = SessionManager.inMemory(owned);
		const first = await start({ statePath, sessionManager: manager });
		first.editors.push("No budget left", JSON.stringify([fileGate]));
		await first.run("start none none 1");
		await vi.waitFor(() =>
			expect(first.notes.at(-1)?.message).toContain("Attempt budget exhausted"),
		);
		await first.box.dispose();
		box = undefined;
		const restored = await start({ statePath, sessionManager: manager });
		expect(restored.notes.map((note) => note.message).join("\n")).toContain(
			"paused",
		);
		expect(restored.statuses.filter(Boolean)).toEqual([]);
		await expect(restored.run("resume latest")).rejects.toThrow(
			/exhausted.*budget/u,
		);
		expect(readDb(statePath).attempts).toHaveLength(1);
		expect(restored.box.providerState.callCount).toBe(0);
	});

	it("requires confirmed offline migration for legacy runs and reruns gates on explicit resume", async () => {
		owned = mkdtempSync(join(tmpdir(), "loop-legacy-"));
		const statePath = join(owned, "state.db");
		const store = await LoopStore.open(statePath);
		store.saveRun({
			id: "legacy",
			goal: "Legacy goal",
			gates: [{ command: process.execPath, args: ["-e", ""] }],
			cwd: owned,
			budgets: { minutes: null, turns: null, attempts: null },
			status: "active",
			reason: "old",
			attempts: 2,
			turns: 1,
			createdAt: 1,
			updatedAt: 2,
		});
		store.close();
		const loop = await start({ statePath });
		await expect(loop.run("resume legacy")).rejects.toThrow(
			/ownership unknown/u,
		);
		await loop.run("recover legacy");
		expect(readDb(statePath).runs[0]).toMatchObject({
			status: "paused",
			attempts: 2,
			turns: 1,
		});
		expect(readDb(statePath).attempts).toHaveLength(0);
		await loop.run("resume legacy");
		await vi.waitFor(() =>
			expect(readDb(statePath).runs[0]).toMatchObject({
				status: "succeeded",
				attempts: 3,
				turns: 1,
			}),
		);
	});

	it("completes subcommands and budget placeholders", async () => {
		const loop = await start();
		const complete = async (prefix: string) =>
			((await loop.command.getArgumentCompletions?.(prefix)) ?? []).map(
				(item) => item.value,
			);
		expect(await complete("")).toEqual([
			"start",
			"guide",
			"resume",
			"pause",
			"stop",
			"status",
			"view",
			"vixen",
			"list",
			"recover",
		]);
		expect(await complete("st")).toEqual(["start", "stop", "status"]);
		expect(await complete("start 10 ")).toEqual(["start 10 none"]);
		expect(await complete("guide n")).toEqual(["guide none"]);
		expect(await complete("vixen ")).toEqual(["vixen on", "vixen off"]);
		// Completion never creates the state database.
		expect(await complete("resume ")).toEqual(["resume latest"]);
		expect(existsSync(join(loop.box.cwd, ".pi", "loop"))).toBe(false);
	});
});