@selesai/code 0.8.4 → 0.8.6

package/dist/extensions/undo.ts

@@ -160,6 +160,9 @@ async function restoreWrite(op: Extract<UndoOp, { type: "write" }>, cwd: string,
 	if (op.oldContentTooLarge) throw new Error(`${op.path}: old content too large; cannot restore`);
 	if (op.existed) {
 		await mkdir(path.dirname(absPath), { recursive: true });
+		// oldContent is always set when existed && !oldContentTooLarge (the
+		// too-large case throws above), so the ?? fallback is unreachable.
+		/* v8 ignore next 1 */
 		await writeFile(absPath, op.oldContent ?? "", "utf8");
 	} else {
 		if (existsSync(absPath)) await rm(absPath, { force: true });
@@ -173,6 +176,9 @@ async function restoreCheckpoint(checkpoint: Checkpoint, cwd: string, force: boo
 			if (op.type === "edit") await restoreEdit(op, cwd, force);
 			else await restoreWrite(op, cwd, force);
 		} catch (error: any) {
+			// restoreEdit/restoreWrite always throw Error instances, so the
+			// String(error) fallback is unreachable.
+			/* v8 ignore next 1 */
 			errors.push(error?.message ?? String(error));
 			if (!force) break;
 		}

package/dist/extensions/web-agent-onboarding.test.ts

@@ -0,0 +1,415 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@selesai/code", () => ({
+	getAgentDir: () => process.env.SELESAI_CODING_AGENT_DIR ?? join(require("node:os").homedir(), ".selesai", "agent"),
+	getSettingsPath: () => join(process.env.SELESAI_CODING_AGENT_DIR ?? join(require("node:os").homedir(), ".selesai", "agent"), "settings.json"),
+}));
+
+import {
+	BRAVE_KEYS_URL,
+	getBraveApiKey,
+	getWebAgentConfigPath,
+	isPlaceholderKey,
+	ONBOARDING_MARKER_NAME,
+	readSettingsJson,
+	setBraveApiKey,
+	validateBraveKey,
+	WEB_AGENT_CONFIG_SUBPATH,
+	writeSettingsJson,
+	writeWebAgentBraveBackendConfig,
+} from "./web-agent-onboarding.ts";
+import webAgentOnboardingExtension from "./web-agent-onboarding.ts";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, SessionStartEvent } from "../core/extensions/types.ts";
+
+let agentDir: string;
+
+beforeEach(() => {
+	agentDir = mkdtempSync(join(tmpdir(), "web-agent-ob-"));
+	process.env.SELESAI_CODING_AGENT_DIR = agentDir;
+});
+
+afterEach(() => {
+	rmSync(agentDir, { recursive: true, force: true });
+	delete process.env.SELESAI_CODING_AGENT_DIR;
+});
+
+describe("web-agent-onboarding helpers", () => {
+	it("isPlaceholderKey returns true for missing/empty/non-string values", () => {
+		expect(isPlaceholderKey(undefined)).toBe(true);
+		expect(isPlaceholderKey(null)).toBe(true);
+		expect(isPlaceholderKey("")).toBe(true);
+		expect(isPlaceholderKey("   ")).toBe(true);
+		expect(isPlaceholderKey(42)).toBe(true);
+		expect(isPlaceholderKey("BSA123abc")).toBe(false);
+	});
+
+	it("getBraveApiKey reads the nested value safely", () => {
+		expect(getBraveApiKey({})).toBeUndefined();
+		expect(getBraveApiKey({ webAgent: "not-an-object" })).toBeUndefined();
+		expect(getBraveApiKey({ webAgent: [] })).toBeUndefined();
+		expect(getBraveApiKey({ webAgent: { braveApiKey: "key-1" } })).toBe("key-1");
+	});
+
+	it("setBraveApiKey clones and sets the nested value", () => {
+		const original = { other: 1, webAgent: { braveApiKey: "old" } };
+		const next = setBraveApiKey(original, "new-key");
+		expect(next.webAgent).toEqual({ braveApiKey: "new-key" });
+		expect(next.other).toBe(1);
+		// original is not mutated
+		expect(original.webAgent.braveApiKey).toBe("old");
+		// missing/non-object webAgent is replaced
+		expect(setBraveApiKey({}, "k").webAgent).toEqual({ braveApiKey: "k" });
+		expect(setBraveApiKey({ webAgent: "x" }, "k").webAgent).toEqual({ braveApiKey: "k" });
+		expect(setBraveApiKey({ webAgent: [] }, "k").webAgent).toEqual({ braveApiKey: "k" });
+	});
+
+	it("validateBraveKey trims and reports errors", () => {
+		expect(validateBraveKey("  BSA-key  ")).toEqual({ key: "BSA-key" });
+		expect(validateBraveKey("")).toEqual({ error: "Key cannot be empty." });
+		expect(validateBraveKey("   ")).toEqual({ error: "Key cannot be empty." });
+		expect(validateBraveKey(undefined)).toEqual({ error: "No key entered." });
+		expect(validateBraveKey(null as unknown as string)).toEqual({ error: "No key entered." });
+	});
+
+	it("readSettingsJson parses existing file, defaults to {} for missing/corrupt", () => {
+		const settingsPath = join(agentDir, "settings.json");
+		writeFileSync(settingsPath, '{"webAgent":{"braveApiKey":"k"}}', "utf-8");
+		expect(readSettingsJson(settingsPath)).toEqual({ webAgent: { braveApiKey: "k" } });
+		expect(readSettingsJson(join(agentDir, "missing.json"))).toEqual({});
+		writeFileSync(settingsPath, "{not json", "utf-8");
+		expect(readSettingsJson(settingsPath)).toEqual({});
+	});
+
+	it("writeSettingsJson creates dirs and writes pretty JSON with trailing newline", () => {
+		const deep = join(agentDir, "nested", "dir");
+		const settingsPath = join(deep, "settings.json");
+		writeSettingsJson({ a: 1 }, settingsPath);
+		expect(readFileSync(settingsPath, "utf-8")).toBe('{\n  "a": 1\n}\n');
+	});
+
+	it("getWebAgentConfigPath joins agentDir with the config subpath", () => {
+		expect(getWebAgentConfigPath(agentDir)).toBe(join(agentDir, "extensions", "pi-web-agent", "config.json"));
+		expect(WEB_AGENT_CONFIG_SUBPATH).toBe(join("extensions", "pi-web-agent", "config.json"));
+	});
+
+	it("writeWebAgentBraveBackendConfig writes brave with duckduckgo fallback, merging existing", () => {
+		const configPath = getWebAgentConfigPath(agentDir);
+		// Pre-seed an existing config to verify merge-not-clobber.
+		mkdirSync(join(agentDir, "extensions", "pi-web-agent"), { recursive: true });
+		writeFileSync(configPath, '{"presentation":{"theme":"dark"}}', "utf-8");
+		writeWebAgentBraveBackendConfig(agentDir);
+		const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+		expect(parsed.presentation).toEqual({ theme: "dark" });
+		expect(parsed.backends.search).toEqual({ provider: "brave", fallback: "duckduckgo" });
+	});
+
+	it("writeWebAgentBraveBackendConfig tolerates missing/corrupt existing config", () => {
+		const configPath = getWebAgentConfigPath(agentDir);
+		mkdirSync(join(agentDir, "extensions", "pi-web-agent"), { recursive: true });
+		writeFileSync(configPath, "{corrupt", "utf-8");
+		writeWebAgentBraveBackendConfig(agentDir);
+		const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+		expect(parsed.backends.search).toEqual({ provider: "brave", fallback: "duckduckgo" });
+
+		// Missing file entirely -> starts fresh.
+		const freshDir = mkdtempSync(join(tmpdir(), "web-agent-fresh-"));
+		writeWebAgentBraveBackendConfig(freshDir);
+		const freshParsed = JSON.parse(readFileSync(join(freshDir, WEB_AGENT_CONFIG_SUBPATH), "utf-8"));
+		expect(freshParsed.backends.search).toEqual({ provider: "brave", fallback: "duckduckgo" });
+		rmSync(freshDir, { recursive: true, force: true });
+	});
+});
+
+describe("web-agent-onboarding constants and markers", () => {
+	it("exports the Brave keys URL and marker name", () => {
+		expect(BRAVE_KEYS_URL).toContain("brave.com");
+		expect(ONBOARDING_MARKER_NAME).toBe(".webAgentOnboardingComplete");
+	});
+});
+
+describe("web-agent-onboarding extension lifecycle", () => {
+	function makePi(overrides: Partial<ExtensionAPI> = {}): { pi: ExtensionAPI; on: ReturnType<typeof vi.fn>; registerCommand: ReturnType<typeof vi.fn> } {
+		const on = vi.fn();
+		const registerCommand = vi.fn();
+		const pi = { on, registerCommand, ...overrides } as unknown as ExtensionAPI;
+		webAgentOnboardingExtension(pi);
+		return { pi, on, registerCommand };
+	}
+
+	function sessionStartHandler(pi: ExtensionAPI): (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void> {
+		return (pi.on as ReturnType<typeof vi.fn>).mock.calls.find(([event]: [string]) => event === "session_start")![1];
+	}
+
+	it("registers session_start and setup-web-search command", () => {
+		const { on, registerCommand } = makePi();
+		expect(on).toHaveBeenCalledWith("session_start", expect.any(Function));
+		expect(registerCommand).toHaveBeenCalledWith("setup-web-search", expect.objectContaining({ description: expect.stringContaining("Brave") }));
+	});
+
+	it("session_start ignores non-startup reasons", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const ctx = { hasUI: true } as unknown as ExtensionContext;
+		await handler({ reason: "reload" } as SessionStartEvent, ctx);
+		// No marker written, no prompt: marker missing proves no completion occurred.
+		expect(existsSync(join(agentDir, ONBOARDING_MARKER_NAME))).toBe(false);
+	});
+
+	it("session_start skips when onboarding is already complete", async () => {
+		writeFileSync(join(agentDir, ONBOARDING_MARKER_NAME), "1", "utf-8");
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const input = vi.fn();
+		const ctx = { hasUI: true, ui: { input } } as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(input).not.toHaveBeenCalled();
+	});
+
+	it("session_start defers when SELESAI_SKIP_WEB_AGENT_ONBOARDING=1", async () => {
+		process.env.SELESAI_SKIP_WEB_AGENT_ONBOARDING = "1";
+		try {
+			const { pi } = makePi();
+			const handler = sessionStartHandler(pi);
+			const input = vi.fn();
+			const ctx = { hasUI: true, ui: { input } } as unknown as ExtensionContext;
+			await handler({ reason: "startup" } as SessionStartEvent, ctx);
+			expect(input).not.toHaveBeenCalled();
+		} finally {
+			delete process.env.SELESAI_SKIP_WEB_AGENT_ONBOARDING;
+		}
+	});
+
+	it("session_start skips when no UI is available", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const input = vi.fn();
+		const ctx = { hasUI: false, ui: { input } } as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(input).not.toHaveBeenCalled();
+	});
+
+	it("already-configured key defers and marks complete", async () => {
+		const settingsPath = join(agentDir, "settings.json");
+		writeFileSync(settingsPath, '{"webAgent":{"braveApiKey":"existing-key"}}', "utf-8");
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const confirm = vi.fn();
+		const ctx = { hasUI: true, ui: { confirm } } as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(confirm).not.toHaveBeenCalled();
+		expect(existsSync(join(agentDir, ONBOARDING_MARKER_NAME))).toBe(true);
+	});
+
+	it("declining Brave skips onboarding and notifies", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const notify = vi.fn();
+		const ctx = { hasUI: true, ui: { confirm: async () => false, notify } } as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(notify).toHaveBeenCalledWith(expect.stringContaining("skipped"), "info");
+		expect(existsSync(join(agentDir, ONBOARDING_MARKER_NAME))).toBe(true);
+	});
+
+	it("accepting Brave saves the key and config", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const notify = vi.fn();
+		const exec = vi.fn().mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+		const ctx = {
+			hasUI: true,
+			ui: { confirm: async () => true, input: async () => "  BSA-my-key  ", notify },
+		} as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(notify).toHaveBeenCalledWith(expect.stringContaining("saved"), "info");
+		expect(exec).not.toHaveBeenCalled(); // openBraveKeysUrl uses pi.exec — not provided here
+		const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+		expect(settings.webAgent.braveApiKey).toBe("BSA-my-key");
+		const config = JSON.parse(readFileSync(join(agentDir, WEB_AGENT_CONFIG_SUBPATH), "utf-8"));
+		expect(config.backends.search).toEqual({ provider: "brave", fallback: "duckduckgo" });
+		expect(existsSync(join(agentDir, ONBOARDING_MARKER_NAME))).toBe(true);
+	});
+
+	it("accepting Brave with browser open failure still saves", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const notify = vi.fn();
+		const exec = vi.fn().mockResolvedValue({ code: 1, stdout: "", stderr: "no browser" });
+		const ctx = {
+			hasUI: true,
+			ui: { confirm: async () => true, input: async () => "BSA-key", notify },
+		} as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(notify).toHaveBeenCalledWith(expect.stringContaining("Could not open browser"), "warning");
+		expect(notify).toHaveBeenCalledWith(expect.stringContaining("manually"), "info");
+		const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+		expect(settings.webAgent.braveApiKey).toBe("BSA-key");
+	});
+
+	describe("openBraveKeysUrl platform branches", () => {
+		it("uses win32 command and still saves on zero exit", async () => {
+			const original = process.platform;
+			const exec = vi.fn().mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+			try {
+				Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+				const { pi } = makePi({ exec } as unknown as ExtensionAPI);
+				const handler = sessionStartHandler(pi);
+				const notify = vi.fn();
+				const ctx = {
+					hasUI: true,
+					ui: { confirm: async () => true, input: async () => "BSA-win", notify },
+				} as unknown as ExtensionContext;
+				await handler({ reason: "startup" } as SessionStartEvent, ctx);
+				expect(exec).toHaveBeenCalledWith("cmd", ["/c", "start", "", BRAVE_KEYS_URL], { timeout: 10_000 });
+				expect(notify).toHaveBeenCalledWith(expect.stringContaining("Opened the Brave API key dashboard"), "info");
+			} finally {
+				Object.defineProperty(process, "platform", { value: original, configurable: true });
+			}
+		});
+
+		it("uses xdg-open on other platforms", async () => {
+			const original = process.platform;
+			const exec = vi.fn().mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+			try {
+				Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+				const { pi } = makePi({ exec } as unknown as ExtensionAPI);
+				const handler = sessionStartHandler(pi);
+				const notify = vi.fn();
+				const ctx = {
+					hasUI: true,
+					ui: { confirm: async () => true, input: async () => "BSA-lin", notify },
+				} as unknown as ExtensionContext;
+				await handler({ reason: "startup" } as SessionStartEvent, ctx);
+				expect(exec).toHaveBeenCalledWith("xdg-open", [BRAVE_KEYS_URL], { timeout: 10_000 });
+			} finally {
+				Object.defineProperty(process, "platform", { value: original, configurable: true });
+			}
+		});
+
+		it("non-zero exit warns and opens the manual URL even after a string error", async () => {
+			const original = process.platform;
+			const exec = vi.fn().mockResolvedValue({ code: 1, stdout: "", stderr: "browser failed" });
+			try {
+				Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+				const { pi } = makePi({ exec } as unknown as ExtensionAPI);
+				const handler = sessionStartHandler(pi);
+				const notify = vi.fn();
+				const ctx = {
+					hasUI: true,
+					ui: { confirm: async () => true, input: async () => "BSA-err", notify },
+				} as unknown as ExtensionContext;
+				await handler({ reason: "startup" } as SessionStartEvent, ctx);
+				expect(notify).toHaveBeenCalledWith(expect.stringContaining("Could not open browser: Failed to open"), "warning");
+				expect(notify).toHaveBeenCalledWith(expect.stringContaining("manually"), "info");
+				// Even though the browser failed, the key is still saved.
+				const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+				expect(settings.webAgent.braveApiKey).toBe("BSA-err");
+			} finally {
+				Object.defineProperty(process, "platform", { value: original, configurable: true });
+			}
+		});
+
+		it("a rejecting exec (non-Error) still warns without crashing the flow", async () => {
+			const original = process.platform;
+			const exec = vi.fn().mockRejectedValue("plain string failure");
+			try {
+				Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+				const { pi } = makePi({ exec } as unknown as ExtensionAPI);
+				const handler = sessionStartHandler(pi);
+				const notify = vi.fn();
+				const ctx = {
+					hasUI: true,
+					ui: { confirm: async () => true, input: async () => "BSA-rej", notify },
+				} as unknown as ExtensionContext;
+				await handler({ reason: "startup" } as SessionStartEvent, ctx);
+				expect(notify).toHaveBeenCalledWith(expect.stringContaining("Could not open browser: plain string failure"), "warning");
+				const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+				expect(settings.webAgent.braveApiKey).toBe("BSA-rej");
+			} finally {
+				Object.defineProperty(process, "platform", { value: original, configurable: true });
+			}
+		});
+		it("non-zero exit with both stderr and stdout empty falls back to unknown error", async () => {
+			const original = process.platform;
+			const exec = vi.fn().mockResolvedValue({ code: 1, stdout: "", stderr: "" });
+			try {
+				Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+				const { pi } = makePi({ exec } as unknown as ExtensionAPI);
+				const handler = sessionStartHandler(pi);
+				const notify = vi.fn();
+				const ctx = {
+					hasUI: true,
+					ui: { confirm: async () => true, input: async () => "BSA-un", notify },
+				} as unknown as ExtensionContext;
+				await handler({ reason: "startup" } as SessionStartEvent, ctx);
+				expect(notify).toHaveBeenCalledWith(expect.stringContaining("unknown error"), "warning");
+				const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+				expect(settings.webAgent.braveApiKey).toBe("BSA-un");
+			} finally {
+				Object.defineProperty(process, "platform", { value: original, configurable: true });
+			}
+		});
+	});
+
+	it("empty pasted key defers without saving", async () => {
+		const { pi } = makePi();
+		const handler = sessionStartHandler(pi);
+		const notify = vi.fn();
+		const ctx = {
+			hasUI: true,
+			ui: { confirm: async () => true, input: async () => "  ", notify },
+		} as unknown as ExtensionContext;
+		await handler({ reason: "startup" } as SessionStartEvent, ctx);
+		expect(notify).toHaveBeenCalledWith("Key cannot be empty.", "warning");
+		expect(existsSync(join(agentDir, ONBOARDING_MARKER_NAME))).toBe(false);
+		expect(existsSync(join(agentDir, "settings.json"))).toBe(false);
+	});
+
+	it("setup-web-search command saves and reloads extensions", async () => {
+		const exec = vi.fn().mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+		const { registerCommand } = makePi({ exec } as unknown as ExtensionAPI);
+		const { handler } = registerCommand.mock.calls.find(([name]: [string]) => name === "setup-web-search")![1] as { handler: (args: string, ctx: ExtensionCommandContext) => Promise<void> };
+		const reload = vi.fn().mockResolvedValue(undefined);
+		const notify = vi.fn();
+		const ctx = {
+			hasUI: true,
+			reload,
+			ui: { confirm: async () => true, input: async () => "BSA-key", notify },
+		} as unknown as ExtensionCommandContext;
+		await handler("", ctx);
+		expect(reload).toHaveBeenCalled();
+		expect(notify).toHaveBeenCalledWith(expect.stringContaining("reloading extensions"), "info");
+		const settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf-8"));
+		expect(settings.webAgent.braveApiKey).toBe("BSA-key");
+	});
+
+	it("setup-web-search command does not reload when skipped", async () => {
+		const { registerCommand } = makePi();
+		const { handler } = registerCommand.mock.calls.find(([name]: [string]) => name === "setup-web-search")![1] as { handler: (args: string, ctx: ExtensionCommandContext) => Promise<void> };
+		const reload = vi.fn();
+		const notify = vi.fn();
+		const ctx = {
+			hasUI: true,
+			reload,
+			ui: { confirm: async () => false, notify },
+		} as unknown as ExtensionCommandContext;
+		await handler("", ctx);
+		expect(reload).not.toHaveBeenCalled();
+	});
+
+	it("setup-web-search command defers (no reload) when key is invalid", async () => {
+		const { registerCommand } = makePi();
+		const { handler } = registerCommand.mock.calls.find(([name]: [string]) => name === "setup-web-search")![1] as { handler: (args: string, ctx: ExtensionCommandContext) => Promise<void> };
+		const reload = vi.fn();
+		const notify = vi.fn();
+		const ctx = {
+			hasUI: true,
+			reload,
+			ui: { confirm: async () => true, input: async () => "", notify },
+		} as unknown as ExtensionCommandContext;
+		await handler("", ctx);
+		expect(reload).not.toHaveBeenCalled();
+	});
+});

package/dist/extensions/workflow/extension.ts

@@ -15,12 +15,12 @@ export default function workflowModesExtension(pi: ExtensionAPI): void {
           ctx.ui.notify(`${description}\nUsage: /${name} <goal>`, "info");
           return;
         }
-        launchSlashSubagent(pi, ctx, { workflowScript: build(goal), async: true, agentScope: "both" });
+        launchSlashSubagent(pi, ctx, { workflowScript: build(goal), async: true, agentScope: "both", mission: { title: goal } });
       },
     });
 
-  register("workflow-task", "Run the task workflow (plan → reuse → handoff → auto build↔review loop) as a scripted workflow.", buildTaskScript);
+  register("workflow-task", "Run the task workflow (plan → reuse → handoff → auto build→review→fix loop) as a scripted workflow.", buildTaskScript);
   register("workflow-prototype", "Run the full prototype workflow (research → plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildPrototypeScript);
   register("workflow-quicktype", "Run the quicker prototype workflow without research (plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildQuicktypeScript);
-  register("workflow-loop", "Run a direct auto build↔review loop for an already-agreed plan as a scripted workflow.", buildLoopScript);
+  register("workflow-loop", "Run a direct auto build→review→fix loop for an already-agreed plan as a scripted workflow.", buildLoopScript);
 }

package/dist/extensions/workflow/modes.ts

@@ -1,35 +1,57 @@
 // ponytail: four workflow modes as pi-subagents workflowScript builders.
-// One-shot-and-sleep: phases run as runs.run steps and the loop auto-repeats
-// until the reviewer reports clean. A workflowScript has no checkpoints, so
-// there are no human gates.
+// One-shot-and-sleep: phases run as runs.run steps and the build → review → fix
+// round auto-repeats until the reviewer reports clean. A workflowScript has no
+// checkpoints, so there are no human gates.
 
 function js(value: string): string {
   return JSON.stringify(value);
 }
 
 const AUTO_LOOP = String.raw`
-const autoLoop = async (goal, context) => {
+const autoLoop = async (goal, context, progressFile) => {
+  emit({ phase: 'start', goal });
   let round = 1;
+  let previousReview = '';
+  let completed = 0;
   while (true) {
-    const build = await runs.run('build-' + round, {
-      agent: 'builder',
-      task: 'Implement the approved work in the workspace and run relevant checks.\n\nSource of truth (handoff/plan):\n' + context + '\n\nGoal:\n' + goal + (round > 1 ? '\n\nAddress the previous review feedback first.' : ''),
-    });
-    const review = await runs.run('review-' + round, {
-      agent: 'commentator',
-      task: 'Independently review the uncommitted diff and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nBuilder completion summary:\n' + build.output + '\n\nEnd with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
-    });
-    if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output)) {
-      return { result: 'clean', rounds: round };
+    try {
+      const build = await runs.run('build-' + round, {
+        agent: 'builder',
+        timeoutMs: 45 * 60 * 1000,
+        task: 'Implement the next bounded step of the approved work in the workspace and run relevant checks. Work on one small, self-contained slice this round; do not attempt the whole plan.\n\nSource of truth (handoff/plan):\n' + context + '\n\nGoal:\n' + goal + (round > 1 ? '\n\nPrevious review (its findings were addressed in the fix round; use its "Remaining work" notes to pick your next slice, do not re-apply findings):\n' + previousReview : '') + '\n\nRead the progress file first for prior-round context.\n\nProgress ledger: append a "## Round ' + round + '" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the work.',
+      });
+      const review = await runs.run('review-' + round, {
+        agent: 'commentator',
+        timeoutMs: 15 * 60 * 1000,
+        task: 'Independently review the builder work for this round and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nProgress file (scope your review to its latest round entry; also re-check the files from the immediately preceding fix entry if one exists; fall back to the full uncommitted diff if it is missing or empty):\n' + progressFile + '\n\nBuilder completion summary:\n' + build.output + '\n\nIf the plan is not yet complete, add a "Remaining work:" section listing the next concrete step(s). End with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
+      });
+      if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output)) {
+        return { result: 'clean', rounds: completed + 1 };
+      }
+      previousReview = review.output;
+      await runs.run('fix-' + round, {
+        agent: 'builder',
+        timeoutMs: 45 * 60 * 1000,
+        task: 'Address ONLY the findings from the review below. The "Remaining work:" section (if present) is for the next round; do not act on it.\n\nProgress ledger: append a "## Round ' + round + ' fix" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the fixes.\n\nReviewer findings:\n' + review.output,
+      });
+      completed += 1;
+      round += 1;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/Run fan-out limit reached/i.test(message)) {
+        return { result: 'budget', rounds: completed, note: 'Run fan-out budget exhausted before the goal was reached. The progress file is current.' };
+      }
+      throw error;
     }
-    round += 1;
   }
 };`;
 
+const PROGRESS_DIR = ".pi-subagents/progress/";
+
 export function buildLoopScript(goal: string): string {
   return String.raw`const goal = ${js(goal)};
 ${AUTO_LOOP}
-return await autoLoop(goal, goal);`;
+return await autoLoop(goal, goal, ${js(PROGRESS_DIR + "loop.md")});`;
 }
 
 export function buildTaskScript(goal: string): string {
@@ -38,7 +60,7 @@ const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concr
 const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Point at relevant areas and dependencies; skip cleanly if wholly new. Return inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings so fresh agents understand the goal, constraints, and acceptance criteria without re-planning.\n\nPlan:\n' + plan.output + '\n\nReuse findings:\n' + reuse.output + '\n\nReturn inline.' });
 ${AUTO_LOOP}
-return await autoLoop(goal, handoff.output);`;
+return await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "task.md")});`;
 }
 
 export function buildPrototypeScript(goal: string): string {
@@ -48,7 +70,7 @@ const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concr
 const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
 ${AUTO_LOOP}
-const loop = await autoLoop(goal, handoff.output);
+const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "prototype.md")});
 const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
 return { ...loop, audited: true };`;
 }
@@ -59,7 +81,7 @@ const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concr
 const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
 ${AUTO_LOOP}
-const loop = await autoLoop(goal, handoff.output);
+const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "quicktype.md")});
 const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
 return { ...loop, audited: true };`;
 }

package/dist/modes/interactive/interactive-mode.d.ts

@@ -398,6 +398,7 @@ export declare class InteractiveMode {
     private notifyAuthDialog;
     private loginProvider;
     private showLoginDialog;
+    private handleSettingsFactoryReset;
     private handleReloadCommand;
     private handleExportCommand;
     private getPathCommandArgument;

package/dist/modes/interactive/interactive-mode.js

@@ -9,7 +9,7 @@ import * as TuiLayouts from "@earendil-works/pi-tui";
 import { CombinedAutocompleteProvider, Container, fuzzyFilter, Markdown, matchesKey, ProcessTerminal, Spacer, setKeybindings, Text, TruncatedText, TuiAltScreen, TuiMainScreen, visibleWidth, } from "@earendil-works/pi-tui";
 import chalk from "chalk";
 import { spawn, spawnSync } from "child_process";
-import { APP_NAME, APP_TITLE, CONFIG_DIR_NAME, getAgentDir, getAuthPath, getDebugLogPath, getDocsPath, getShareViewerUrl, getUpdateInstruction, PACKAGE_NAME, VERSION, } from "../../config.js";
+import { APP_NAME, APP_TITLE, CONFIG_DIR_NAME, getAgentDir, getAuthPath, getBundledDefaultsDir, getDebugLogPath, getDocsPath, getShareViewerUrl, getUpdateInstruction, PACKAGE_NAME, VERSION, } from "../../config.js";
 import { parseSkillBlocks } from "../../core/agent-session.js";
 import { SessionImportFileNotFoundError } from "../../core/agent-session-runtime.js";
 import { CACHE_TTL_MS, collectCacheMisses, computeCacheWaste, detectCacheMiss, } from "../../core/cache-stats.js";
@@ -2319,6 +2319,11 @@ export class InteractiveMode {
                 this.editor.setText("");
                 return;
             }
+            if (text === "/settings-factory-reset") {
+                this.editor.setText("");
+                await this.handleSettingsFactoryReset();
+                return;
+            }
             if (text === "/scoped-models") {
                 this.editor.setText("");
                 await this.showModelsSelector();
@@ -4649,6 +4654,48 @@ export class InteractiveMode {
     // =========================================================================
     // Command handlers
     // =========================================================================
+    async handleSettingsFactoryReset() {
+        if (this.session.isStreaming) {
+            this.showWarning("Wait for the current response to finish before resetting settings.");
+            return;
+        }
+        if (this.session.isCompacting) {
+            this.showWarning("Wait for compaction to finish before resetting settings.");
+            return;
+        }
+        const settingsPath = path.join(getAgentDir(), "settings.json");
+        const confirmed = await this.showExtensionConfirm("Factory reset settings", `This replaces ${settingsPath} with the bundled factory defaults.\n\n`
+            + "Your credentials (auth.json), sessions, extensions, skills, and themes are NOT touched.\n"
+            + "A backup is saved next to the file before resetting.\n\n"
+            + "Continue?");
+        if (!confirmed) {
+            this.showStatus("Settings factory reset cancelled.");
+            return;
+        }
+        const bundledDefaultsDir = getBundledDefaultsDir();
+        const bundledPath = path.join(bundledDefaultsDir, "settings.json");
+        if (!fs.existsSync(bundledPath)) {
+            this.showError(`Bundled defaults not found at ${bundledPath}`);
+            return;
+        }
+        try {
+            if (fs.existsSync(settingsPath)) {
+                fs.copyFileSync(settingsPath, `${settingsPath}.bak`);
+            }
+            fs.copyFileSync(bundledPath, settingsPath);
+            try {
+                fs.chmodSync(settingsPath, 0o600);
+            }
+            catch {
+                // chmod is best-effort (no-op on platforms that don't support it).
+            }
+            await this.session.reload();
+            this.showStatus(`Settings reset to factory defaults (backup: ${settingsPath}.bak)`);
+        }
+        catch (error) {
+            this.showError(`Settings factory reset failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async handleReloadCommand() {
         if (this.session.isStreaming) {
             this.showWarning("Wait for the current response to finish before reloading.");

package/dist/skills/pi-subagents/references/execution-controls.md

@@ -55,7 +55,7 @@ its resolved launch context as `[fresh]` or `[fork]`. Aggregate headers show
 
 `workflowScript` is the scripted orchestration surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Scripts are ordinary JavaScript statement bodies, so use an explicit return such as `workflowScript: "return runs.run('main', { agent: 'worker', task: '...' })"` for a useful one-child result. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, worker then monitor setup, cross-repo prep lanes, or a fanout that the parent will consume together; use the declarative `chain` / `tasks` modes when the shape is known up front.
 
-**Workflow modes as `workflowScript` auto-loops.** The bundled `workflow` extension ships its four mode shapes (task, prototype, quicktype, loop) as `workflowScript` auto-loops launched via `/workflow-*`. Each mode runs its phases as `runs.run` steps and loops the build↔review round until the commentator reports clean. There are no checkpoints (one-shot-and-sleep); durable state is the auto-created mission per launch; recover via `mission.list`/`status`.
+**Workflow modes as `workflowScript` auto-loops.** The bundled `workflow` extension ships its four mode shapes (task, prototype, quicktype, loop) as `workflowScript` auto-loops launched via `/workflow-*`. Each mode runs its phases as `runs.run` steps and loops the build → review → fix round (a blocking review triggers a fix round that addresses only the findings) until the commentator reports clean. There are no checkpoints (one-shot-and-sleep); durable state is the auto-created mission per launch; recover via `mission.list`/`status`.
 
 ```js
 subagent({

package/docs/plans/workflow-autoloop-reference.md

@@ -1,7 +1,6 @@
 # Workflow auto-loop reference (implement exactly)
 
-> **Superseded:** the 3-round cap was later removed — the loop now runs until
-> clean. See `src/extensions/workflow/modes.ts` for the final implementation.
+> **Superseded:** the 3-round cap was later removed and a per-round fix step was added — the loop now runs build → review → fix until clean. See `src/extensions/workflow/modes.ts` for the final implementation.
 
 Convert the four `/workflow-*` modes from static chains to pi-subagents
 `workflowScript` auto-loops. One-shot-and-sleep: the phases run as `runs.run`