pi-umbra 0.3.1 → 0.4.0

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/spec.ts

@@ -1,3 +1,4 @@
+import assert from "node:assert";
 import type { RunSpec } from "./store.ts";
 
 // The one text format a run is described in. `/umb-fan` opens it in an editor, and the fan
@@ -11,8 +12,10 @@ import type { RunSpec } from "./store.ts";
 //   omp-intercept@openai/gpt-5: Check whether an extension can override it.
 //   # Design
 //   proposal: Given the Map phase, write the design.
+//   prototype [write]: Build the smallest version of it and run the tests.
 //
-// Phases run in order; every branch inside one phase runs at the same time.
+// Phases run in order; every branch inside one phase runs at the same time. A branch is
+// read-only unless its key carries `[write]`: then it works in its own git worktree.
 
 export const TEMPLATE = ["name: ", "desc: ", "# Phase one", "label: task", ""].join("\n");
 
@@ -40,8 +43,9 @@ export const parseSpec = (text: string): RunSpec | undefined => {
 			// A branch before any "#" gets an implicit first phase, so the common
 			// single-phase run needs no header at all.
 			const phase = spec.phases[spec.phases.length - 1] ?? pushPhase(spec, "Branches");
-			const [label, model] = key.split("@");
-			if (label) phase.branches.push({ label, model, task: value });
+			const write = /\s*\[write\]$/i.test(key);
+			const [label, model] = key.replace(/\s*\[write\]$/i, "").split("@");
+			if (label) phase.branches.push({ label, model, task: value, ...(write ? { write } : {}) });
 		}
 	}
 	spec.phases = spec.phases.filter((phase) => phase.branches.length > 0);
@@ -51,7 +55,7 @@ export const parseSpec = (text: string): RunSpec | undefined => {
 };
 
 const pushPhase = (spec: RunSpec, title: string) => {
-	const phase = { title, branches: [] as { label: string; model?: string; task: string }[] };
+	const phase = { title, branches: [] as RunSpec["phases"][number]["branches"] };
 	spec.phases.push(phase);
 	return phase;
 };
@@ -69,19 +73,25 @@ lone: Read tui.d.ts:68 and report.
 # Design
 plan@openai/gpt-5: Write it up.
 free@openrouter/nvidia/nemotron-3-super-120b-a12b:free: Check src/a.ts:12.
+fix [write]: Patch src/a.ts:12.
+fast@openai/gpt-5 [write]: Patch it again.
 `);
 	if (!spec) throw new Error("parseSpec returned undefined for a valid spec");
-	console.assert(spec.name === "toolcall", "name");
-	console.assert(spec.description === "Map how pi renders tool calls", "desc");
-	console.assert(spec.phases.length === 2, `expected 2 phases, got ${spec.phases.length}`);
-	console.assert(spec.phases[0]?.title === "Branches", "implicit first phase");
-	console.assert(spec.phases[0]?.branches[0]?.task === "Read tui.d.ts:68 and report.", "colon in task");
-	console.assert(spec.phases[1]?.branches[0]?.model === "openai/gpt-5", "per-branch model");
+	assert(spec.name === "toolcall", "name");
+	assert(spec.description === "Map how pi renders tool calls", "desc");
+	assert(spec.phases.length === 2, `expected 2 phases, got ${spec.phases.length}`);
+	assert(spec.phases[0]?.title === "Branches", "implicit first phase");
+	assert(spec.phases[0]?.branches[0]?.task === "Read tui.d.ts:68 and report.", "colon in task");
+	assert(spec.phases[1]?.branches[0]?.model === "openai/gpt-5", "per-branch model");
 	const free = spec.phases[1]?.branches[1];
-	console.assert(free?.model === "openrouter/nvidia/nemotron-3-super-120b-a12b:free", "colon in model");
-	console.assert(free?.task === "Check src/a.ts:12.", "task after a model with a colon");
-	console.assert(parseSpec("name: empty") === undefined, "a spec with no branches is not a run");
-	console.assert(findBlock("blah\n```fan\nx: y\n```\nblah") === "x: y\n", "block extraction");
+	assert(free?.model === "openrouter/nvidia/nemotron-3-super-120b-a12b:free", "colon in model");
+	assert(free?.task === "Check src/a.ts:12.", "task after a model with a colon");
+	const [fix, fast] = [spec.phases[1]?.branches[2], spec.phases[1]?.branches[3]];
+	assert(fix?.label === "fix" && fix.write === true && fix.task === "Patch src/a.ts:12.", "[write]");
+	assert(fast?.label === "fast" && fast.model === "openai/gpt-5" && fast.write === true, "[write] after a model");
+	assert(spec.phases[0]?.branches[0]?.write === undefined, "read-only by default");
+	assert(parseSpec("name: empty") === undefined, "a spec with no branches is not a run");
+	assert(findBlock("blah\n```fan\nx: y\n```\nblah") === "x: y\n", "block extraction");
 	console.log("spec.ts ok");
 };
 

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/store.check.ts

@@ -8,9 +8,10 @@
 // It never starts pi: PI_BIN points at the stub, and the stub is the only thing spawned.
 
 import { strict as assert } from "node:assert";
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 const root = mkdtempSync(join(tmpdir(), "fan-check-"));
 
@@ -21,10 +22,20 @@ const stub = join(root, "fake-pi.mjs");
 writeFileSync(
     stub,
     [
-        'import { appendFileSync } from "node:fs";',
+        'import { execFileSync } from "node:child_process";',
+        'import { appendFileSync, writeFileSync } from "node:fs";',
+        'import { join } from "node:path";',
         "const task = process.argv[process.argv.length - 1];",
         'if (process.env.FAN_CHECK_ORDER) appendFileSync(process.env.FAN_CHECK_ORDER, `${task}\\n`);',
         'if (task === "hang") setInterval(() => {}, 1000);',
+        // A write branch's edits: two in its cwd, which must be the session's folder inside its
+        // worktree, one binary, and one at the worktree's root, outside that folder.
+        'else if (task === "edit") {',
+        '  writeFileSync("edited.txt", "from the branch\\n");',
+        '  writeFileSync("logo.bin", Buffer.from([0, 255, 0, 10, 13, 0]));',
+        '  const top = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();',
+        '  appendFileSync(join(top, "a.txt"), "three\\n");',
+        "}",
         'else process.stdout.write(`report for ${task}\\nSTATUS: OK\\n`);',
         "",
     ].join("\n"),
@@ -38,6 +49,18 @@ process.env.FAN_LOAD = "";
 
 const { reportOf, store } = await import("./store.ts");
 const { readRun } = await import("../skills/delegate/state.ts");
+const { mergeCommand } = await import("./worktree.ts");
+
+// A throw inside a child-process listener never reaches an assert; it is counted here instead.
+const uncaught: string[] = [];
+process.on("uncaughtException", (error) => uncaught.push(String(error)));
+// A promise chain that stalls lets the loop drain and bun exit 0 without a word.
+let completed = false;
+process.on("exit", () => {
+    if (completed) return;
+    console.error("store.check.ts did not finish");
+    process.exitCode = 1;
+});
 
 const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -99,7 +122,9 @@ await until("the run to finish", () => {
 
 const finished = store.run();
 assert.equal(finished?.done, 3, "every branch settles");
-assert.deepEqual(readFileSync(order, "utf8").trim().split("\n"), ["alpha", "beta", "gamma"], "phase two waits for phase one");
+// The two phase-one branches race each other; only gamma's place is a fact.
+const ran = readFileSync(order, "utf8").trim().split("\n");
+assert.deepEqual([...ran.slice(0, 2).sort(), ran[2]], ["alpha", "beta", "gamma"], "phase two waits for phase one");
 assert.equal(readFileSync(join(dir, "state", "map-core-render.exit"), "utf8"), "0", "a clean exit is recorded as 0");
 assert.equal(finished?.branches.every((branch) => !branch.timedOut), true, "nothing timed out");
 assert.match(reportOf(finished!), /report for alpha[\s\S]*report for gamma/, "the reports are read back in launch order");
@@ -148,5 +173,95 @@ await until(
 assert.equal(store.run()?.branches[0]?.timedOut, true, "exit code 124 is a timeout, not a crash");
 assert.equal(existsSync(join(slowCwd, ".pi-out")), true, "the run directory outlives the run");
 
+// ---------- a [write] branch edits its own worktree, and its work waits on a git branch ----------
+
+assert.throws(
+    () => store.start({ name: "nogit", description: "", phases: [{ title: "Build", branches: [{ label: "fix", task: "edit", model: "stub/one", write: true }] }] }, "stub/one", mkdtempSync(join(tmpdir(), "fan-nogit-"))),
+    /need a git repository/,
+    "a write branch outside git refuses to start",
+);
+
+const repo = mkdtempSync(join(tmpdir(), "fan-write-"));
+const git = (...args: string[]) => execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+git("init", "-q", "-b", "main");
+git("config", "user.name", "check");
+git("config", "user.email", "check@localhost");
+writeFileSync(join(repo, "a.txt"), "one\n");
+git("add", "-A");
+git("commit", "-q", "-m", "init");
+writeFileSync(join(repo, "a.txt"), "one\ntwo\n"); // the user's uncommitted work
+// What used to stop a write run before it started: an untracked nested repo, a symlink to a
+// folder, a post-checkout hook that fails. And a post-commit hook that must never run.
+execFileSync("git", ["init", "-q", join(repo, "vendor", "lib")]);
+symlinkSync("vendor", join(repo, "link"));
+writeFileSync(join(repo, ".git", "hooks", "post-checkout"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+writeFileSync(join(repo, ".git", "hooks", "post-commit"), `#!/bin/sh\ntouch '${repo}/hooked'\n`, { mode: 0o755 });
+// The session sits in a folder no commit has, so no checkout has it either.
+const session = join(repo, "newpkg");
+mkdirSync(session);
+
+const writeDir = store.start(
+    {
+        name: "write",
+        description: "",
+        phases: [
+            { title: "Build", branches: [{ label: "fix", task: "edit", model: "stub/one", write: true }, { label: "look", task: "read", model: "stub/one" }] },
+            // Dots in a label made a branch name git refuses.
+            { title: "Later", branches: [{ label: "v1..lock", task: "edit", model: "stub/one", write: true }] },
+        ],
+    },
+    "stub/one",
+    session,
+) as string;
+const worktrees = join(repo, ".git", "fan-worktrees", basename(writeDir));
+assert.ok(existsSync(join(worktrees, "later-v1-lock")), "every write branch gets its worktree at start, under .git");
+assert.equal(await store.stop("later-v1-lock"), true);
+assert.equal(existsSync(join(worktrees, "later-v1-lock")), false, "a stopped queued write branch drops its worktree");
+await until("the write run to end", () => {
+    store.refresh(session);
+    return store.run()?.live === false;
+});
+const fix = store.run()?.branches.find((branch) => branch.stem === "build-fix")?.git;
+assert.ok(fix && !fix.error, `the branch's work is committed: ${JSON.stringify(fix)}`);
+assert.equal(fix.stat, "+2 −0 · 3 files", "the branch's own change only");
+assert.equal(fix.root, repo);
+assert.equal(existsSync(join(session, "edited.txt")), false, "the user's tree is untouched");
+assert.equal(git("show", `${fix.branch}:newpkg/edited.txt`), "from the branch", "the branch worked in the session's folder");
+assert.equal(git("show", `${fix.branch}:a.txt`), "one\ntwo\nthree", "the branch started from the uncommitted work");
+assert.match(git("ls-tree", fix.base, "link"), /^120000 /, "a symlink stays a symlink");
+assert.equal(existsSync(join(repo, "hooked")), false, "no hook ran");
+assert.equal(existsSync(join(worktrees, "build-fix")), false, "a finished worktree is removed");
+assert.doesNotMatch(git("status", "--porcelain"), /pi-out|fan-worktrees/, "neither the run nor the worktrees show in git status");
+assert.equal(store.run()?.branches.find((branch) => branch.stem === "build-look")?.git, undefined, "a read-only branch has no git");
+assert.equal(git("branch", "--list", "fan/*/later-*"), "", "the stopped one leaves no branch");
+assert.ok(reportOf(store.run()!).includes(mergeCommand(fix)), "the report carries the merge command");
+
+// The merge the session is offered, run where the session's bash runs: from the subfolder, over
+// the user's own unstaged edit to the same file, with a binary file, staging nothing.
+execFileSync("bash", ["-c", mergeCommand(fix)], { cwd: session, stdio: "pipe" });
+assert.equal(readFileSync(join(repo, "a.txt"), "utf8"), "one\ntwo\nthree\n", "a change outside the subfolder lands on the user's edit");
+assert.equal(readFileSync(join(session, "edited.txt"), "utf8"), "from the branch\n");
+assert.deepEqual([...readFileSync(join(session, "logo.bin"))], [0, 255, 0, 10, 13, 0], "a binary change lands");
+assert.equal(git("diff", "--cached", "--name-only"), "", "nothing is staged");
+assert.equal(git("branch", "--list", fix.branch), "", "the merged branch is gone");
+
+// A branch whose process never starts gets "error" and "close" both; its worktree is closed once.
+process.env.PI_BIN = join(root, "missing-pi");
+// The repo root, not the session folder: a run in the same second there would sort by name.
+store.start({ name: "nospawn", description: "", phases: [{ title: "Build", branches: [{ label: "fix", task: "edit", model: "stub/one", write: true }] }] }, "stub/one", repo);
+await until("the failed spawn to settle", () => {
+    store.refresh(repo);
+    return store.run()?.live === false;
+});
+// "close" comes a tick after "error"; give it the time to do damage.
+await delay(300);
+store.refresh(repo);
+const failed = store.run()?.branches[0];
+assert.equal(failed?.exitCode, 127, "a spawn that failed reads as 127");
+assert.equal(failed?.git?.error, undefined, `a spawn that failed closes its worktree once: ${JSON.stringify(failed?.git)}`);
+assert.deepEqual(uncaught, [], "nothing threw outside a handler: in pi that ends the process");
+process.env.PI_BIN = stub;
+
 store.stopAll();
+completed = true;
 console.log("store.check.ts ok");

package/node_modules/pi-umbra-subagents/extensions/umbra-subagents/fan/store.ts

@@ -1,8 +1,9 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { envSettings, type FanSettings } from "./models.ts";
+import { closeWorktree, discardCommand, dropWorktree, gitRepo, mergeCommand, openWorktree, snapshot, type Worktree } from "./worktree.ts";
 import { LINGER_MS, OUT_DIR, pidLive, readRun, type BranchState, type RunState } from "../skills/delegate/state.ts";
 
 // The producer. It launches branches, keeps their run directory honest, and hands the panel
@@ -24,7 +25,7 @@ import { LINGER_MS, OUT_DIR, pidLive, readRun, type BranchState, type RunState }
 export type RunSpec = {
 	name: string;
 	description: string;
-	phases: { title: string; branches: { label: string; model?: string; task: string }[] }[];
+	phases: { title: string; branches: { label: string; model?: string; task: string; write?: boolean }[] }[];
 };
 
 // Every branch gets the same tail on its system prompt. Same contract as the delegate skill's
@@ -34,15 +35,30 @@ const CONTRACT =
 	"Your final message is the only thing the caller reads. Answer it directly in markdown, " +
 	"cite every claim as file:line, and write no preamble. End with a single line " +
 	"'STATUS: OK' when you answered fully, 'STATUS: PARTIAL' when you answered part of it, or " +
-	"'STATUS: NEED_STRONGER' when the task needs a stronger model. When a decision only the " +
-	"caller can make blocks you, stop at once and end with 'STATUS: ASKING', then 'QUESTION: <one " +
-	"question>' and 'OPTIONS: <choices separated by \" | \", recommended first>'; your session is " +
-	"kept and the answer arrives as your next message.";
+	"'STATUS: NEED_STRONGER' when the task needs a stronger model.";
+// Read-only branches only: a write branch's worktree closes when it ends, so it cannot be continued.
+const ASKING =
+	"When a decision only the caller can make blocks you, stop at once and end with 'STATUS: ASKING', " +
+	"then 'QUESTION: <one question>' and 'OPTIONS: <choices separated by \" | \", recommended first>'; " +
+	"your session is kept and the answer arrives as your next message.";
 
 // Read-only by default: a branch that can run bash can start branches of its own, and nothing
 // here caps the depth. Reference 3's `└` nesting needs exactly that, so it is a knob rather
 // than a constant — set FAN_TOOLS="read,grep,find,ls,bash" to allow it, and watch the panel.
 const READ_ONLY_TOOLS = process.env.FAN_TOOLS || "read,grep,find,ls";
+// A `[write]` branch edits and runs tests, so it gets the full set, and its own worktree to do
+// it in. bash reaches past the worktree, so the rules below are the fence; pi has no sandbox.
+const WRITE_TOOLS = "read,grep,find,ls,edit,write,bash";
+const writeRules = (worktree: Worktree) =>
+	`You work in your own git worktree at ${worktree.path}, on branch ${worktree.branch}, and you may ` +
+	"edit files and run commands there. Never touch files outside it, never push, publish, deploy " +
+	"or delete branches, and do not commit: your changes are committed for you when you finish, " +
+	"and the user decides whether they are merged. Say in your answer what you changed and how " +
+	"you checked it. When a decision blocks you, take the recommended option and say which. " +
+	// The brief and the task were written about the user's tree, and edit and write go wherever
+	// a path points: an absolute path into the repo would land in the user's files.
+	`Every path under ${worktree.root} in your task or the brief means the same file under ${worktree.path}: ` +
+	`edit ${worktree.path}/<rest>, never ${worktree.root}/<rest>.`;
 // `--no-extensions` drops provider extensions too, so a branch on a model that only exists
 // because of one cannot start without it loaded back: that list ($LOAD) and the time limit come
 // in with each run as FanSettings (models.ts), read from the same delegate.env run.sh reads.
@@ -77,12 +93,22 @@ export const piCommand = (): string[] => {
 // because a branch is started from the session cwd and this extension lives elsewhere.
 const BEACON = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "delegate", "beacon.ts");
 
-/** Filenames, so `^[a-z0-9][a-z0-9._-]*$` and nothing else: a stem is an NTFS filename. */
-const slug = (text: string) => text.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "") || "x";
+/** `^[a-z0-9][a-z0-9_-]*$` and nothing else: a stem is an NTFS filename and part of a git
+ *  branch name, and a dot is what git refuses there (`..`, `.lock`, a trailing dot). */
+const slug = (text: string) => text.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "x";
 
 const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-type Launch = { stem: string; phase: string; name: string; model: string; task: string; timeoutMs: number; load: string[] };
+type Launch = {
+	stem: string;
+	phase: string;
+	name: string;
+	model: string;
+	task: string;
+	timeoutMs: number;
+	load: string[];
+	worktree?: Worktree;
+};
 
 let current: RunState | undefined;
 let sessionCwd = "";
@@ -247,21 +273,29 @@ const launch = (branch: Launch) => {
 		"-e",
 		BEACON,
 		"--tools",
-		READ_ONLY_TOOLS,
+		branch.worktree ? WRITE_TOOLS : READ_ONLY_TOOLS,
 		"--model",
 		branch.model,
 		"--append-system-prompt",
 		// The path rides in the system prompt rather than in the task, so it is written once per
 		// branch instead of being pasted into every task line, and a branch that was given a
 		// one-line task still knows where the rest of the thought is.
-		briefPath ? `${CONTRACT} The full brief this task was cut from is at ${briefPath}; read it when the task alone leaves something open.` : CONTRACT,
+		[
+			CONTRACT,
+			branch.worktree ? "" : ASKING,
+			briefPath ? `The full brief this task was cut from is at ${briefPath}; read it when the task alone leaves something open.` : "",
+			branch.worktree ? writeRules(branch.worktree) : "",
+		]
+			.filter(Boolean)
+			.join(" "),
 		// A task that begins with "-" would otherwise be read as an unknown flag
 		// (cli/args.js:217). After "--" every remaining word is the message.
 		"--",
 		branch.task,
 	];
 	const child = spawn(command as string, args, {
-		cwd: sessionCwd,
+		// The same folder inside the worktree that the session sits in inside the repo.
+		cwd: branch.worktree?.cwd ?? sessionCwd,
 		windowsHide: true,
 		// A process group off Windows, so a stop reaches the branch's own tool processes.
 		detached: process.platform !== "win32",
@@ -289,16 +323,25 @@ const launch = (branch: Launch) => {
 	timer.unref?.();
 	timers.set(branch.stem, timer);
 
+	// "error" and "close" both fire when the spawn itself fails; the second must not close the
+	// worktree again and overwrite what the first one recorded.
+	let settled = false;
 	const settle = (code: number | null) => {
+		if (settled) return;
+		settled = true;
 		clearTimeout(timers.get(branch.stem));
 		timers.delete(branch.stem);
 		children.delete(branch.stem);
-		try {
-			closeSync(out);
-			closeSync(err);
-		} catch {
-			// Already closed: "error" and "close" can both fire for one child.
-		}
+		closeSync(out);
+		closeSync(err);
+		// What a write branch did is committed even when it was stopped or timed out: it is the
+		// user's to keep or throw away, not this file's. Written before the exit, so the row
+		// never settles without it.
+		if (branch.worktree)
+			writeFileSync(
+				join(stateDir, `${branch.stem}.git`),
+				JSON.stringify(closeWorktree(branch.worktree, `${branch.name}: ${branch.task.split("\n")[0]?.slice(0, 72)}`)),
+			);
 		// The one signal that survives a branch dying before its extensions ever bound, and the
 		// only place a timeout can be told apart from a crash. 124 is what `timeout(1)` reports,
 		// which is what the delegate skill's branches write, so one reader covers both.
@@ -337,7 +380,14 @@ export const reportOf = (run: RunState): string =>
 				// Killed before pi wrote anything, or a spawn that never started.
 			}
 			const note = branch.timedOut ? ", timed out" : "";
-			return `## ${branch.label} (${branch.status}${note})\n\n${text || branch.error || "no output"}`;
+			const { git } = branch;
+			const changes = git?.error
+				? `\n\nIts changes could not be committed (${git.error}); they are still in its worktree on ${git.branch}.`
+				: git?.stat
+					? `\n\nIts changes are on git branch ${git.branch} (${git.stat}). Nothing is merged. ` +
+						`To merge: \`${mergeCommand(git)}\`. To discard: \`${discardCommand(git)}\`.`
+					: "";
+			return `## ${branch.label} (${branch.status}${note})\n\n${text || branch.error || "no output"}${changes}`;
 		})
 		.join("\n\n");
 
@@ -356,6 +406,11 @@ export const store = {
 	 *  started in bash and has already read for itself. */
 	start(spec: RunSpec, defaultModel: string, cwd: string, brief?: string, settings: FanSettings = envSettings()): string | undefined {
 		if (running()) return undefined;
+		// Checked before anything is written: a run that cannot give its write branches a
+		// worktree does not start at all, rather than starting without them.
+		const writes = spec.phases.some((phase) => phase.branches.some((branch) => branch.write));
+		const repo = writes ? gitRepo(cwd) : undefined;
+		if (writes && !repo) throw new Error(`[write] branches need a git repository, and ${cwd} is not in one`);
 		sessionCwd = cwd;
 		// LOCAL time, because the reader picks the newest run by NAME and the delegate skill
 		// stamps its directories with `date +%Y%m%d-%H%M%S`. A UTC name here would sort a fresh
@@ -365,6 +420,9 @@ export const store = {
 		runDir = join(cwd, OUT_DIR, `${stamp}-${slug(spec.name)}`);
 		const stateDir = join(runDir, "state");
 		mkdirSync(stateDir, { recursive: true });
+		// Scratch: reports and sessions stay out of git status and out of a write run's snapshot.
+		const ignore = join(cwd, OUT_DIR, ".gitignore");
+		if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
 
 		// The brief goes to disk byte-for-byte, with no model between the user's words and the
 		// file. Every branch is then pointed at the path rather than at a paraphrase of it: a
@@ -379,45 +437,61 @@ export const store = {
 		const phases: string[] = [];
 		let index = 0;
 		pending = [];
-		for (const phase of spec.phases) {
-			const phaseName = slug(phase.title);
-			phases.push(phaseName);
-			const launches: Launch[] = [];
-			for (const branch of phase.branches) {
-				// Two branches sharing a stem would share a state file, and a file with two
-				// writers is the one corruption this design cannot detect. The caller here is
-				// the model, so a collision is renamed rather than refused: a run that starts
-				// with "explore-2" beats a run that does not start.
-				const base = slug(branch.label);
-				let name = base;
-				for (let n = 2; taken.has(`${phaseName}-${name}`); n++) name = `${base}-${n}`;
-				const stem = `${phaseName}-${name}`;
-				taken.add(stem);
-				const model = branch.model || defaultModel;
-				index += 1;
-				// Every field is populated at seed time, so no column appears for the first time
-				// three seconds in and reflows the row.
-				const state: BranchState = {
-					phase: phaseName,
-					name,
-					// Set when this pi is itself a branch, which is how a nested run keeps its
-					// place in the tree.
-					parent: process.env.PI_BRANCH_PARENT ?? null,
-					index,
-					model: prettyModel(model),
-					pid: null,
-					status: "starting",
-					activity: "Starting",
-					tokens: null,
-					startedAt: now,
-					updatedAt: now,
-					report: null,
-					error: null,
-				};
-				writeFileSync(join(stateDir, `${stem}.json`), JSON.stringify(state));
-				launches.push({ stem, phase: phaseName, name, model, task: branch.task, ...settings });
+		// One snapshot of the user's tree for every write branch, taken after the .gitignore above so
+		// the run directory is never part of it.
+		const from = repo ? snapshot(repo) : "";
+		try {
+			for (const phase of spec.phases) {
+				const phaseName = slug(phase.title);
+				phases.push(phaseName);
+				// Queued before it is filled, so a worktree that fails halfway undoes the ones before it.
+				const launches: Launch[] = [];
+				pending.push(launches);
+				for (const branch of phase.branches) {
+					// Two branches sharing a stem would share a state file, and a file with two
+					// writers is the one corruption this design cannot detect. The caller here is
+					// the model, so a collision is renamed rather than refused: a run that starts
+					// with "explore-2" beats a run that does not start.
+					const base = slug(branch.label);
+					let name = base;
+					for (let n = 2; taken.has(`${phaseName}-${name}`); n++) name = `${base}-${n}`;
+					const stem = `${phaseName}-${name}`;
+					taken.add(stem);
+					const model = branch.model || defaultModel;
+					index += 1;
+					// Every field is populated at seed time, so no column appears for the first time
+					// three seconds in and reflows the row.
+					const state: BranchState = {
+						phase: phaseName,
+						name,
+						// Set when this pi is itself a branch, which is how a nested run keeps its
+						// place in the tree.
+						parent: process.env.PI_BRANCH_PARENT ?? null,
+						index,
+						model: prettyModel(model),
+						pid: null,
+						status: "starting",
+						activity: "Starting",
+						tokens: null,
+						startedAt: now,
+						updatedAt: now,
+						report: null,
+						error: null,
+					};
+					writeFileSync(join(stateDir, `${stem}.json`), JSON.stringify(state));
+					const worktree =
+						branch.write && repo
+							? openWorktree(repo, from, join(repo.common, "fan-worktrees", basename(runDir), stem), `fan/${basename(runDir)}/${stem}`)
+							: undefined;
+					launches.push({ stem, phase: phaseName, name, model, task: branch.task, ...settings, worktree });
+				}
 			}
-			pending.push(launches);
+		} catch (error) {
+			// No run.json yet, so the reader never sees this directory as a run; only the
+			// worktrees already made need undoing.
+			for (const launch of pending.flat()) if (launch.worktree) dropWorktree(launch.worktree);
+			pending = [];
+			throw error;
 		}
 
 		// run.json LAST, after every seed exists: the reader treats its absence as "not a run",
@@ -442,8 +516,10 @@ export const store = {
 		const ours = current?.dir === runDir;
 		// A branch of a later phase has no process yet. Taken out of the queue, or the next phase
 		// would start it anyway, and given the exit a killed branch gets, so it reads as stopped.
-		if (ours && pending.some((phase) => phase.some((launch) => launch.stem === stem))) {
+		const queued = ours ? pending.flat().find((launch) => launch.stem === stem) : undefined;
+		if (queued) {
 			pending = pending.map((phase) => phase.filter((launch) => launch.stem !== stem)).filter((phase) => phase.length > 0);
+			if (queued.worktree) dropWorktree(queued.worktree);
 			writeFileSync(join(runDir, "state", `${stem}.exit`), "130");
 			refresh();
 			return true;
@@ -467,6 +543,10 @@ export const store = {
 		}
 		children.clear();
 		timers.clear();
+		// Queued write branches never ran, so their worktrees go. A killed one keeps its worktree:
+		// its close never runs once pi is gone, and what it wrote stays on disk for the user.
+		// ponytail: `git worktree list` shows such leftovers; add a cleanup command if they pile up.
+		for (const launch of pending.flat()) if (launch.worktree) dropWorktree(launch.worktree);
 		pending = [];
 		stopTick();
 	},