@arhen/pi-core-subagent 1.3.30 → 1.3.32

package/README.md

@@ -147,7 +147,17 @@ On completion the extension commits the child's changes (the child is told not t
 git merge --no-ff subagents/<run>/<task>
 ```
 
-Merged branches + their worktree dirs are cleaned automatically after the run. Failed/canceled tasks keep the branch (partial work survives for manual merging) but drop the worktree dir. Crash leftovers are swept at session start — worktree dirs are removed, branches are kept. Non-git repos fall back to in-place edits.
+Isolation follows the toolset the child actually receives: explicit `tools: ["bash", "edit", "write"]` earns a worktree even without `write: true`, and an agent file that narrows the child to read-only gets no branch at all.
+
+Cleanup, in order of trust:
+
+| When | What |
+|---|---|
+| Session start | Registered worktrees can't be live yet — an interrupted child's uncommitted work is committed, the branch kept, the dir dropped. Then merged branches are reaped and dirs git no longer tracks are removed. |
+| After a run | Merged branches + their dirs, never touching a branch a live run owns (checkout state re-checked per branch). |
+| Task failed/canceled | Partial work is committed first, so the branch keeps it; the dir is dropped. |
+
+Non-git repos fall back to in-place edits.
 
 ## Graph mode — `needs`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.30",
+	"version": "1.3.32",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/index.ts

@@ -30,7 +30,7 @@ import {
 	type SubagentParamsShape,
 } from "./schemas.ts";
 import { type RunDetails, type RunSnapshot, TERMINAL } from "./types.ts";
-import { cleanupMerged, repoRoot, sweepStale } from "./worktree.ts";
+import { cleanupMerged, ownerAlive, reapDeadWorktrees, repoRoot, sweepStale } from "./worktree.ts";
 
 export default function (pi: ExtensionAPI) {
 	const manager = new SubagentManager(pi);
@@ -125,8 +125,16 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 		for (const root of roots) {
-			sweepStale(root);
-			cleanupMerged(root);
+			try {
+				// A registered subagent worktree is a crash leftover UNLESS another pi
+				// session still owns it (pid marker) — commit its work, keep the branch,
+				// drop the dir. Then reap merged branches and dirs git no longer tracks.
+				reapDeadWorktrees(root, ownerAlive);
+				cleanupMerged(root, { skipBranches: manager.liveBranches() });
+				sweepStale(root);
+			} catch {
+				/* recovery is best-effort — never block session start */
+			}
 		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -170,18 +178,29 @@ export default function (pi: ExtensionAPI) {
 				// until terminal — but surface an ask_parent: the child is waiting on the
 				// leader, so break out, reply via reply_subagent, then await again.
 				let run = details.run;
-				let intercom: ParkedMsg[] = [];
+				// Each park gets a FRESH msgs array — accumulate, or every wake but the
+				// last is lost (they were consumed by the park, never sent as followUp).
+				const intercom: ParkedMsg[] = [];
 				while (!TERMINAL.includes(run.status)) {
 					const awaited = await manager.awaitRun(details.run.id);
 					if (!awaited) break; // run gone (session shutdown) — stop, no busy-spin
 					if (awaited.run) run = awaited.run;
-					intercom = awaited.intercom;
-					if (intercom.some((m) => m.kind === "ask")) break;
+					intercom.push(...awaited.intercom);
+					if (awaited.intercom.some((m) => m.kind === "ask")) break;
 				}
 				const asked = intercom.find((m) => m.kind === "ask");
-				const text = asked
-					? `${makeSummary(run)}\n\nA child is waiting for your answer (${asked.agent}, ${asked.taskId}): ${asked.text}\nReply with reply_subagent(runId: "${run.id}", taskId: "${asked.taskId}", message: ...), then await_subagent again for the result.`
-					: makeSummary(run);
+				const heard = intercom.filter((m) => m.kind !== "ask");
+				const text = [
+					makeSummary(run),
+					heard.length > 0
+						? `\nIntercom while waiting:\n${heard.map((m) => `- [${m.kind}] ${m.agent} (${m.taskId}): ${truncateText(m.text)}`).join("\n")}`
+						: "",
+					asked
+						? `\nA child is waiting for your answer (${asked.agent}, ${asked.taskId}): ${asked.text}\nReply with reply_subagent(runId: "${run.id}", taskId: "${asked.taskId}", message: ...), then await_subagent again for the result.`
+						: "",
+				]
+					.filter(Boolean)
+					.join("\n");
 				return { content: [{ type: "text", text }], details: { run } };
 			}
 			return {

package/src/manager.ts

@@ -1,5 +1,5 @@
 /** SubagentManager: run lifecycle, child sessions, intercom, persistence, widget plumbing. */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
@@ -45,13 +45,12 @@ import {
 } from "./types.ts";
 import {
 	branchDiff,
+	claimWorktree,
 	cleanupMerged,
 	commitWorktree,
 	createWorktree,
-	removeByBranch,
 	removeWorktree,
 	repoRoot,
-	sweepStale,
 	type Worktree,
 } from "./worktree.ts";
 
@@ -60,8 +59,12 @@ export const MAX_CONCURRENCY = 8;
 /** No default wall-clock cap: a subagent runs until its task is done, it stalls, or the user aborts. */
 const DEFAULT_RUNTIME_MS = 0;
 const DEFAULT_STALL_MS = 180_000; // 3 min: long model thinking streams emit no events, but they're not stalled.
+/** Cap on a child's wait for reply_subagent — an ignored question must not pin the run open forever. */
+const PARENT_REPLY_TIMEOUT_MS = 600_000; // 10 min
 const READONLY_TOOLS = ["read", "grep", "find", "ls"];
 const WRITE_TOOLS = ["read", "grep", "find", "ls", "bash", "edit", "write"];
+/** Tools that can mutate the tree — their presence is what earns a worktree. */
+const WRITE_CAPABLE = ["bash", "edit", "write"];
 /** Task ids become git refs + filesystem paths. */
 const SAFE_TASK_ID = /^[A-Za-z0-9_-]{1,64}$/;
 const WIDGET_THROTTLE_MS = 150;
@@ -86,6 +89,14 @@ function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
 	}
 	return total;
 }
+/** realpath when possible; the raw path otherwise (cwd may not exist yet). */
+function safeRealPath(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
 function getParentSessionFile(ctx: ExtensionContext): string | undefined {
 	try {
 		return ctx.sessionManager.getSessionFile?.();
@@ -213,13 +224,19 @@ export interface ParkedMsg {
 
 export class SubagentManager {
 	private runs = new Map<string, RunSnapshot>();
-	private settlers = new Map<string, (run: RunSnapshot) => void>();
+	/** Runs that are still settleable (presence = not yet settled). */
+	private settlers = new Map<string, true>();
+	/** Everyone parked on a run — a set, so re-parking can't build a closure chain. */
+	private settleWaiters = new Map<string, Set<(run: RunSnapshot) => void>>();
 	private pendingReplies = new Map<string, PendingReply>();
 	private liveChildren = new Map<
 		string,
 		{ abort: () => void; dispose: () => void; touchWatchdog: () => void; steer: (message: string) => void }
 	>();
 	private mailboxes: Mailbox = createMailbox();
+	/** Live worktrees by `${runId}:${taskId}` — lets cancel drop dirs and keeps
+	 *  cleanup from touching a branch that a running child owns. */
+	private liveWorktrees = new Map<string, Worktree>();
 	private runControllers = new Map<string, AbortController>();
 	private widgetTimers = new Map<string, ReturnType<typeof setTimeout>>(); // per-run stream throttle
 	private widgetRuns: RunSnapshot[] = [];
@@ -285,8 +302,12 @@ export class SubagentManager {
 			child.dispose();
 		}
 		this.liveChildren.clear();
+		// Ownership markers stay on disk; the next session reaps those dirs (commit,
+		// keep branch, drop dir) once this pid is gone.
+		this.liveWorktrees.clear();
 		this.runs.clear();
 		this.settlers.clear();
+		this.settleWaiters.clear();
 		this.pendingReplies.clear();
 		this.runControllers.clear();
 		this.mailboxes = createMailbox();
@@ -497,20 +518,24 @@ export class SubagentManager {
 	private makeChildHandlers(run: RunSnapshot, task: TaskSnapshot, ctx: ExtensionContext): ChildHandlers {
 		return {
 			onAskParent: async (_taskId, question) => {
+				const key = `${run.id}:${task.id}`;
 				this.updateTask(run, task, { status: "awaiting_parent" }, ctx);
-				this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog();
-				// While the leader is parked in await_subagent, the question rides the wait
-				// instead of the steering queue — no boundary needed, no starvation.
-				if (this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
-					return "Your question was delivered to the parent (they're waiting on this run). Keep working; the answer arrives via the pending reply.";
+				this.liveChildren.get(key)?.touchWatchdog();
+				// While the leader is parked in await_subagent the question rides the wait
+				// (no steering queue, no turn boundary); otherwise it goes out as a notice.
+				// Either way the pending reply entry must exist, or reply_subagent has
+				// nowhere to land and the child waits on an answer that never comes.
+				if (!this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
+					this.notifyParent(run, "asked", { taskId: task.id, question });
 				}
-				this.notifyParent(run, "asked", { taskId: task.id, question });
-				// M3: a waiting child is not stalled — keep the watchdog fed until the reply.
-				const keepAlive = setInterval(() => this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog(), 30_000);
+				// A waiting child is not stalled — keep the watchdog fed until the reply.
+				// But the wait is BOUNDED: an unanswered question would otherwise keep the
+				// run non-terminal forever (widget never clears, run never settles).
+				const keepAlive = setInterval(() => this.liveChildren.get(key)?.touchWatchdog(), 30_000);
 				try {
-					const reply = await this.awaitParentReply(run.id, task.id);
+					const reply = await this.awaitParentReply(run.id, task.id, PARENT_REPLY_TIMEOUT_MS);
 					this.updateTask(run, task, { status: "running" }, ctx);
-					this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog();
+					this.liveChildren.get(key)?.touchWatchdog();
 					return reply;
 				} finally {
 					clearInterval(keepAlive);
@@ -518,13 +543,13 @@ export class SubagentManager {
 			},
 			onNotifyParent: (_taskId, message, level) => {
 				this.emit("subagent:intercom", { runId: run.id, taskId: task.id, kind: "notify", level, message });
+				// Parked leader gets it through the wait; otherwise queue it. `awaited` must
+				// NOT gate this — between two parks the leader is awaited but listening.
 				if (this.collectParked(run.id, { kind: "notify", taskId: task.id, agent: task.agent, text: message })) return;
-				if (!run.awaited) {
-					try {
-						this.pi.sendUserMessage(`[Subagent ${task.agent}] ${message}`, { deliverAs: "followUp" });
-					} catch {
-						/* parent mid-stream */
-					}
+				try {
+					this.pi.sendUserMessage(`[Subagent ${task.agent}] ${message}`, { deliverAs: "followUp" });
+				} catch {
+					/* parent mid-stream */
 				}
 			},
 			onSendMessage: (_taskId, to, text) => {
@@ -537,12 +562,10 @@ export class SubagentManager {
 						message: text,
 					});
 					if (this.collectParked(run.id, { kind: "notify", taskId: task.id, agent: task.agent, text })) return true;
-					if (!run.awaited) {
-						try {
-							this.pi.sendUserMessage(`[Subagent ${task.agent}] ${text}`, { deliverAs: "followUp" });
-						} catch {
-							/* parent mid-stream */
-						}
+					try {
+						this.pi.sendUserMessage(`[Subagent ${task.agent}] ${text}`, { deliverAs: "followUp" });
+					} catch {
+						/* parent mid-stream */
 					}
 					return true;
 				}
@@ -552,9 +575,24 @@ export class SubagentManager {
 			onPollMailbox: (taskId) => this.mailboxes.poll(`${run.id}:${taskId}`),
 		};
 	}
-	private awaitParentReply(runId: string, taskId: string): Promise<string> {
+	private awaitParentReply(runId: string, taskId: string, timeoutMs = 0): Promise<string> {
+		const key = `${runId}:${taskId}`;
 		return new Promise<string>((resolve) => {
-			this.pendingReplies.set(`${runId}:${taskId}`, { resolve });
+			const timer =
+				timeoutMs > 0
+					? setTimeout(() => {
+							this.pendingReplies.delete(key);
+							resolve(
+								"The parent did not answer in time. Proceed autonomously with your best judgment and state the assumption you made in your final answer.",
+							);
+						}, timeoutMs)
+					: undefined;
+			this.pendingReplies.set(key, {
+				resolve: (message) => {
+					if (timer) clearTimeout(timer);
+					resolve(message);
+				},
+			});
 		});
 	}
 	deliverReply(runId: string, taskId: string, message: string): boolean {
@@ -657,30 +695,15 @@ export class SubagentManager {
 		const fileTools = file?.tools?.filter((t) => allowedTools.includes(t));
 		const baseTools = fileTools?.length ? fileTools : (input.tools ?? allowedTools);
 		const tools = [...baseTools, ...(run.allowIntercom ? CHILD_TALK_TOOLS : [])];
-		// Worktree whenever the child can write — whether the leader said write:true
-		// or a file granted write-capable tools.
-		const canWrite = input.write || (file?.tools?.some((t) => WRITE_TOOLS.includes(t)) ?? false);
+		// Isolation follows the DELIVERED toolset, never the raw request: explicit
+		// tools: [bash] without write:true still gets a worktree, and a file that
+		// narrowed the child to read-only never gets the commit/merge ceremony.
+		const canWrite = baseTools.some((t) => WRITE_CAPABLE.includes(t));
 
 		// Write agents run in an isolated git worktree (branch subagents/<run>/<task>);
-		// non-git repos fall back to in-place. The worktree is created BEFORE session
-		// start so the child's cwd + AGENTS.md context chain are the worktree's.
-		let wt: Worktree | undefined;
-		if (canWrite) {
-			try {
-				wt = createWorktree(task.cwd, run.id, task.id);
-			} catch {
-				wt = undefined; // git failure → in-place
-			}
-		}
-		// Map a per-task cwd subpath into the worktree so relative paths stay correct.
-		let childCwd = wt?.path ?? task.cwd;
-		if (wt) {
-			const rel = relative(wt.root, task.cwd);
-			if (rel && !rel.startsWith("..") && rel !== ".") childCwd = join(wt.path, rel);
-		}
-
-		// Model + thinking resolve against the pi model registry; a bad request
-		// fails the TASK with a helpful message, not the whole run.
+		// Model + thinking resolve against the pi model registry BEFORE any worktree
+		// exists — a bad request fails the TASK with a helpful message and can't leak a
+		// checkout past this early return.
 		let model: Model<Api> | undefined;
 		try {
 			model = resolveChildModel(ctx, file?.model ?? input.model);
@@ -700,6 +723,37 @@ export class SubagentManager {
 			return;
 		}
 
+		// Write agents run in an isolated git worktree (branch subagents/<run>/<task>);
+		// non-git repos fall back to in-place. Created BEFORE session start so the
+		// child's cwd + AGENTS.md context chain are the worktree's.
+		let wt: Worktree | undefined;
+		if (canWrite) {
+			try {
+				wt = createWorktree(task.cwd, run.id, task.id);
+			} catch {
+				wt = undefined; // git failure → in-place
+			}
+		}
+		// Map a per-task cwd subpath into the worktree so relative paths stay correct.
+		// Both sides go through realpath — a symlinked root would otherwise look
+		// "outside" the repo. If the mapping can't be trusted, drop the worktree AND
+		// reset the cwd (never point the child at a dir that was just removed).
+		let childCwd = wt?.path ?? task.cwd;
+		if (wt) {
+			const rel = relative(safeRealPath(wt.root), safeRealPath(task.cwd));
+			if (rel.startsWith("..")) {
+				removeWorktree(wt);
+				wt = undefined;
+				childCwd = task.cwd;
+			} else if (rel && rel !== ".") {
+				childCwd = join(wt.path, rel);
+			}
+		}
+		if (wt) {
+			claimWorktree(wt); // pid marker: another pi session must not reap this
+			this.liveWorktrees.set(`${run.id}:${task.id}`, wt);
+		}
+
 		this.updateTask(
 			run,
 			task,
@@ -717,6 +771,9 @@ export class SubagentManager {
 			onUpdate,
 		);
 
+		// Set once the dir must outlive this call: committed work awaiting the
+		// leader's merge, or a commit failure whose work exists ONLY in the dir.
+		let keepWorktreeDir = false;
 		let child: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
 		let unsubscribe: (() => void) | undefined;
 		let timeout: ReturnType<typeof setTimeout> | undefined;
@@ -836,6 +893,7 @@ export class SubagentManager {
 					// its work: the error is reported, the status stays completed.
 					try {
 						commitWorktree(wt, `subagent ${task.agent}: ${truncateText(input.task, 60)}`);
+						keepWorktreeDir = true; // committed — dir stays until the leader merges
 						const { stat, files } = branchDiff(wt);
 						this.updateTask(
 							run,
@@ -845,12 +903,15 @@ export class SubagentManager {
 							onUpdate,
 						);
 					} catch (commitErr) {
+						// Never drop a checkout whose work isn't on the branch — it would be
+						// unreachable once the base-tip branch is reaped as "merged".
+						keepWorktreeDir = true;
 						this.updateTask(
 							run,
 							task,
 							{
 								branch: wt.branch,
-								error: `Worktree commit failed (changes remain in ${wt.path}): ${commitErr instanceof Error ? commitErr.message : String(commitErr)}`,
+								error: `Worktree commit failed (uncommitted changes remain in ${wt.path}): ${commitErr instanceof Error ? commitErr.message : String(commitErr)}`,
 							},
 							ctx,
 							onUpdate,
@@ -890,17 +951,23 @@ export class SubagentManager {
 			watchdog.dispose();
 			if (timeout) clearTimeout(timeout);
 			child?.dispose();
-			// Failed/aborted: commit whatever partial work exists FIRST (so the branch
-			// really keeps it), then drop the checkout dir.
+			// Failed/aborted: let the aborted child's last writes land (its tools may
+			// still be unwinding), commit whatever partial work exists so the branch
+			// really keeps it, then drop the checkout dir. A commit FAILURE keeps the
+			// dir — dropping it would make the work unreachable.
 			if (wt && task.status !== "completed") {
+				await new Promise((r) => setTimeout(r, 250));
 				try {
 					commitWorktree(wt, `subagent ${task.agent} (partial, ${task.status})`);
 				} catch {
-					/* nothing to commit */
+					keepWorktreeDir = true;
 				}
 				this.updateTask(run, task, { branch: wt.branch }, ctx, onUpdate);
-				removeWorktree(wt);
 			}
+			if (wt && !keepWorktreeDir) removeWorktree(wt);
+			// Released only after the dir is gone: while it exists, the branch must stay
+			// in liveBranches() so cleanup can't reap it.
+			this.liveWorktrees.delete(key);
 		}
 	}
 
@@ -988,7 +1055,7 @@ export class SubagentManager {
 		});
 		this.turnActivity = true;
 		this.runs.set(run.id, run);
-		this.settlers.set(run.id, () => {});
+		this.settlers.set(run.id, true);
 		this.runControllers.set(run.id, new AbortController());
 		for (const task of run.tasks) this.mailboxes.open(`${run.id}:${task.id}`);
 		this.emit("subagent:run-created", { run: cloneRun(run) });
@@ -1026,7 +1093,18 @@ export class SubagentManager {
 				// The scheduler passes the index into the FILTERED list — never use it
 				// against the unfiltered inputs. Look the input up by task id instead.
 				const input = inputById.get(task.id);
-				if (!input) return;
+				if (!input) {
+					// Impossible unless ids drift from inputs — fail loudly instead of
+					// leaving the task queued forever (hasActiveRun would never clear).
+					this.updateTask(
+						run,
+						task,
+						{ status: "failed", error: `No input for task ${task.id}`, endedAt: Date.now() },
+						ctx,
+						onUpdate,
+					);
+					return;
+				}
 				await this.runChild(
 					run,
 					task,
@@ -1082,14 +1160,26 @@ export class SubagentManager {
 		for (const task of run.tasks) this.mailboxes.close(`${run.id}:${task.id}`);
 		this.persist(ctx);
 		// Branches merged by the leader since the run ended: drop worktree dir + branch.
-		for (const task of run.tasks) {
-			if (task.branch) {
+		// Once per repo, never for a branch another live run owns, never fatal — a
+		// throw here would re-settle an already-finished run as failed.
+		try {
+			const roots = new Set<string>();
+			for (const task of run.tasks) {
+				if (!task.branch) continue;
 				const root = repoRoot(task.cwd);
-				if (root) cleanupMerged(root);
+				if (root) roots.add(root);
 			}
+			for (const root of roots) cleanupMerged(root, { skipBranches: this.liveBranches() });
+		} catch {
+			/* cleanup is best-effort; the run outcome must stand */
 		}
 	}
 
+	/** Branches owned by worktrees of still-running children. */
+	liveBranches(): Set<string> {
+		return new Set(Array.from(this.liveWorktrees.values(), (wt) => wt.branch));
+	}
+
 	/** Spawn a run that keeps executing after this call returns. Every run is background. */
 	startInBackground(params: SubagentParamsShape, ctx: ExtensionContext): RunDetails {
 		const { run, inputs } = this.createRun(params, ctx);
@@ -1140,6 +1230,8 @@ export class SubagentManager {
 		task.status = "aborted";
 		task.error = task.error || "Canceled from peek";
 		task.endedAt = Date.now();
+		this.pendingReplies.get(`${runId}:${taskId}`)?.resolve("(task canceled by the parent — stop work now)");
+		this.pendingReplies.delete(`${runId}:${taskId}`);
 		this.liveChildren.get(`${runId}:${taskId}`)?.abort();
 		this.mailboxes.close(`${runId}:${taskId}`);
 		if (ctx) this.flushWidget(run, ctx);
@@ -1153,6 +1245,14 @@ export class SubagentManager {
 		if (TERMINAL.includes(run.status)) return { aborted: 0 }; // never corrupt a finished run
 		let aborted = 0;
 		this.runControllers.get(runId)?.abort();
+		// Release children parked in ask_parent first — an unresolved wait would keep
+		// the child alive past the abort.
+		for (const [key, pending] of this.pendingReplies) {
+			if (key.startsWith(`${runId}:`)) {
+				this.pendingReplies.delete(key);
+				pending.resolve("(run canceled by the parent — stop work and return what you have)");
+			}
+		}
 		for (const [key, child] of this.liveChildren) {
 			if (key.startsWith(`${runId}:`)) {
 				child.abort();
@@ -1164,7 +1264,10 @@ export class SubagentManager {
 			task.error = task.error || "Canceled by subagent_cancel"; // never overwrite a real error
 			task.endedAt = Date.now();
 			aborted += 1;
-			if (task.branch) removeByBranch(task.cwd, task.branch); // dir only; branch keeps partial work
+			// The branch is recorded here so the leader can still merge partial work;
+			// runChild's finally commits + drops the dir (it owns the live worktree).
+			const wt = this.liveWorktrees.get(`${runId}:${task.id}`);
+			if (wt) task.branch = wt.branch;
 		}
 		run.status = "aborted";
 		run.endedAt = Date.now();
@@ -1175,12 +1278,15 @@ export class SubagentManager {
 		return { aborted };
 	}
 
-	/** Settle-and-delete: awaiters resolve once; no leak, no closure chain. */
+	/** Settle-and-delete: every awaiter resolves once, then the set is dropped. */
 	private settleRun(runId: string, run: RunSnapshot): void {
-		const s = this.settlers.get(runId);
-		if (!s) return;
+		if (!this.settlers.has(runId)) return;
 		this.settlers.delete(runId);
-		s(cloneRun(run));
+		const waiters = this.settleWaiters.get(runId);
+		this.settleWaiters.delete(runId);
+		if (!waiters) return;
+		const snapshot = cloneRun(run);
+		for (const waiter of waiters) waiter(snapshot);
 	}
 
 	/** Child→leader messages collected while the parent is parked in await_subagent. */
@@ -1210,16 +1316,24 @@ export class SubagentManager {
 		}
 		const msgs: ParkedMsg[] = [];
 		const settled = new Promise<RunSnapshot | undefined>((resolve) => {
-			const prev = this.settlers.get(runId);
-			this.settlers.set(runId, (r) => {
-				prev?.(r);
+			// Waiters are a SET, not a chain: the autoAwait loop re-parks on every
+			// child message, and wrapping the previous settler each time grew an
+			// unbounded closure chain (each holding a snapshot clone).
+			const waiter = (r: RunSnapshot) => {
+				this.settleWaiters.get(runId)?.delete(waiter);
 				resolve(r);
-			});
+			};
+			let waiters = this.settleWaiters.get(runId);
+			if (!waiters) {
+				waiters = new Set();
+				this.settleWaiters.set(runId, waiters);
+			}
+			waiters.add(waiter);
 			// A child→leader message while parked wakes the wait: the leader gets it
 			// IN the await result, no steering queue, no turn boundary needed.
-			this.parked.set(runId, { msgs, wake: () => resolve(cloneRun(run)) });
+			this.parked.set(runId, { msgs, wake: () => waiter(cloneRun(run)) });
 		});
-		if (timeoutMs) {
+		if (timeoutMs !== undefined && timeoutMs > 0) {
 			return Promise.race([
 				settled.then((r) => {
 					finish();

package/src/worktree.ts

@@ -2,12 +2,15 @@
  *  Worktrees live inside `<repo>/.git/subagents/<runId>/<taskId>` so the child's
  *  ancestor walk still finds the project AGENTS.md chain. node_modules is
  *  symlinked from the main tree. The extension commits the child's changes on
- *  completion; the leader reviews and merges the branch manually; merged
- *  branches are cleaned automatically, crash leftovers are swept at session
- *  start (dir removed, branch kept — the work survives). */
+ *  completion; the leader reviews and merges the branch manually.
+ *
+ *  Cleanup, in order of trust: `reapDeadWorktrees` (session start — nothing can
+ *  be live yet, so every registered worktree is a crash leftover: commit its
+ *  work, drop the dir, keep the branch), `cleanupMerged` (merged branches, never
+ *  touching a checked-out one), `sweepStale` (dirs git no longer knows about). */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 export interface Worktree {
@@ -17,6 +20,8 @@ export interface Worktree {
 	base: string; // SHA the branch was created from
 }
 
+const BRANCH_PREFIX = "subagents/";
+
 function git(root: string, args: string[]): string {
 	return execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }).trim();
 }
@@ -35,6 +40,16 @@ function gitOk(root: string, args: string[]): boolean {
 	}
 }
 
+/** Compare paths through realpath so /var vs /private/var can't diverge. */
+function samePath(a: string, b: string): boolean {
+	if (a === b) return true;
+	try {
+		return realpathSync(a) === realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
 /** Repo root for cwd, or undefined when not a git repo (or cwd doesn't exist). */
 export function repoRoot(cwd: string): string | undefined {
 	if (!existsSync(cwd)) return undefined;
@@ -49,14 +64,20 @@ export function repoRoot(cwd: string): string | undefined {
 export function createWorktree(cwd: string, runId: string, taskId: string): Worktree | undefined {
 	const root = repoRoot(cwd);
 	if (!root) return undefined;
-	const path = join(root, ".git", "subagents", runId, taskId);
-	const branch = `subagents/${runId}/${taskId}`;
+	// --git-common-dir, not "<root>/.git": inside a linked worktree or a submodule
+	// `.git` is a FILE, and joining it would make `worktree add` fail (silently
+	// dropping isolation).
+	let container: string;
 	let base: string;
 	try {
+		const common = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+		container = join(common, "subagents");
 		base = git(root, ["rev-parse", "HEAD"]); // SHA — detached HEAD stays correct
 	} catch {
 		return undefined; // broken repo — fall back to in-place
 	}
+	const path = join(container, runId, taskId);
+	const branch = `${BRANCH_PREFIX}${runId}/${taskId}`;
 	git(root, ["worktree", "add", "-b", branch, path, "HEAD"]);
 	// Deps follow the child into the worktree; anything else the task needs is
 	// project content already checked out there.
@@ -71,11 +92,23 @@ export function createWorktree(cwd: string, runId: string, taskId: string): Work
 	return { root, path, branch, base };
 }
 
-/** Commit all child changes. No-op when the worktree is already clean. */
-export function commitWorktree(wt: Worktree, message: string): void {
-	if (gitIn(wt.path, ["status", "--porcelain"]).length === 0) return;
-	gitIn(wt.path, ["add", "-A", "--", ".", ":(exclude)node_modules"]); // never stage the dep symlink
-	gitIn(wt.path, ["commit", "-m", message, "--no-verify"]);
+/**
+ * Commit the child's changes. Stages first, then commits only when something is
+ * actually staged — an untracked node_modules symlink must not fake "dirty" and
+ * turn into a failed empty commit. Returns "committed" | "empty"; a real git
+ * failure THROWS, and callers must not delete the checkout in that case (the
+ * work would become unreachable once the base-tip branch is reaped as merged).
+ */
+export function commitWorktree(wt: Worktree, message: string): "committed" | "empty" {
+	return commitIn(wt.path, message);
+}
+
+function commitIn(dir: string, message: string): "committed" | "empty" {
+	// Exclude the root dep symlink and any nested node_modules the child created.
+	gitIn(dir, ["add", "-A", "--", ".", ":(exclude)node_modules", ":(exclude,glob)**/node_modules/**"]);
+	if (gitIn(dir, ["diff", "--cached", "--name-only"]).length === 0) return "empty";
+	gitIn(dir, ["commit", "-m", message, "--no-verify"]);
+	return "committed";
 }
 
 /** Diffstat + changed files of the branch vs its base SHA. */
@@ -89,23 +122,32 @@ export function branchDiff(wt: Worktree): { stat: string; files: string[] } {
 
 /** Remove the worktree dir. The branch is KEPT (the work survives for merging). */
 export function removeWorktree(wt: Worktree): void {
-	try {
-		git(wt.root, ["worktree", "remove", "--force", wt.path]);
-	} catch {
-		/* already gone */
-	}
-	prune(wt.root);
+	dropDir(wt.root, wt.path);
 }
 
 /** Remove a worktree dir by branch name (cancel paths that didn't keep a Worktree). */
 export function removeByBranch(cwd: string, branch: string): void {
+	if (!branch.startsWith(BRANCH_PREFIX)) return;
 	const root = repoRoot(cwd);
 	if (!root) return;
-	const path = join(root, ".git", "subagents", branch.slice("subagents/".length));
+	const container = subagentsDir(root);
+	if (container) dropDir(root, join(container, branch.slice(BRANCH_PREFIX.length)));
+}
+
+/** `<git-common-dir>/subagents` — where our worktrees live for this repo. */
+function subagentsDir(root: string): string | undefined {
+	try {
+		return join(git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]), "subagents");
+	} catch {
+		return undefined;
+	}
+}
+
+function dropDir(root: string, path: string): void {
 	try {
 		git(root, ["worktree", "remove", "--force", path]);
 	} catch {
-		/* already gone */
+		if (existsSync(path)) rmSync(path, { recursive: true, force: true });
 	}
 	prune(root);
 }
@@ -119,21 +161,32 @@ function prune(root: string): void {
 	}
 }
 
+/** Is this branch checked out in some worktree right now? Checked fresh, per call. */
+function isCheckedOut(root: string, branch: string): boolean {
+	return worktreeBranches(root).includes(branch);
+}
+
 /**
  * Delete branch + worktree for branches already merged into `target`.
- * SAFETY: branches checked out in a LIVE worktree (concurrent run) are skipped —
- * their tip equals the base until the child commits, so they look "merged".
+ * SAFETY: a branch checked out in a LIVE worktree is skipped — a fresh branch's
+ * tip equals its base until the child commits, so it looks "merged". The
+ * registration is re-checked immediately before each removal (a concurrent run
+ * may have created its worktree after the first listing).
  */
-export function cleanupMerged(root: string, target = "HEAD"): number {
+export function cleanupMerged(root: string, opts: { skipBranches?: Set<string>; target?: string } = {}): number {
 	root = realpathSync(root);
+	const target = opts.target ?? "HEAD";
 	const merged = git(root, ["branch", "--merged", target])
 		.split("\n")
 		.map((b) => b.trim().replace(/^[+*]\s*/, ""));
-	const live = new Set(worktreeBranches(root));
 	let cleaned = 0;
+	const container = subagentsDir(root);
 	for (const branch of merged) {
-		if (!branch.startsWith("subagents/") || live.has(branch)) continue;
-		const path = join(root, ".git", "subagents", branch.slice("subagents/".length));
+		if (!branch.startsWith(BRANCH_PREFIX) || !container) continue;
+		if (opts.skipBranches?.has(branch)) continue; // owned by a live run
+		if (isCheckedOut(root, branch)) continue; // fresh re-check, not a stale snapshot
+		const path = join(container, branch.slice(BRANCH_PREFIX.length));
+		if (existsSync(path) && ownerAlive(path)) continue; // another session's live checkout
 		if (existsSync(path)) {
 			try {
 				git(root, ["worktree", "remove", "--force", path]);
@@ -150,51 +203,111 @@ export function cleanupMerged(root: string, target = "HEAD"): number {
 /** Branch names currently checked out in any worktree (incl. the main one). */
 function worktreeBranches(root: string): string[] {
 	try {
-		return git(root, ["worktree", "list", "--porcelain"])
-			.split("\n")
+		return git(root, ["worktree", "list", "--porcelain", "-z"])
+			.split("\0")
 			.filter((l) => l.startsWith("branch "))
-			.map((l) => l.slice("branch refs/heads/".length).trim());
+			.map((l) => l.slice("branch refs/heads/".length));
 	} catch {
 		return [];
 	}
 }
 
 /**
- * Remove worktree dirs that are NOT registered worktrees (crash leftovers).
- * A crash leaves the dir AND the branch, so branch-existence can't identify
- * leftovers — worktree registration can. Branches always survive.
+ * Session-start recovery: every registered subagent worktree is a crash leftover
+ * (nothing of ours can be live yet). Commit whatever the dead child left so the
+ * branch keeps it, then drop the dir. Branches always survive.
+ */
+export function reapDeadWorktrees(root: string, isLive: (path: string) => boolean = () => false): number {
+	root = realpathSync(root);
+	const sub = subagentsDir(root);
+	if (!sub || !existsSync(sub)) return 0;
+	let reaped = 0;
+	for (const path of worktreePaths(root)) {
+		if (!isInside(path, sub)) continue; // not ours
+		if (isLive(path)) continue; // another pi session owns it
+		try {
+			commitIn(path, "subagent (recovered after interrupted session)");
+		} catch {
+			continue; // git failed — never drop a dir whose work isn't on the branch
+		}
+		dropDir(root, path);
+		reaped += 1;
+	}
+	return reaped;
+}
+
+/**
+ * Ownership marker: a live worktree gets `<dir>/.subagent-owner` holding the
+ * owning pid. Another pi session must not reap a checkout whose owner is alive.
+ */
+export function claimWorktree(wt: Worktree): void {
+	try {
+		writeFileSync(join(wt.path, ".subagent-owner"), String(process.pid));
+	} catch {
+		/* best-effort: worst case another session reaps it after a crash */
+	}
+}
+
+/** True when the worktree dir is claimed by a process that still exists. */
+export function ownerAlive(path: string): boolean {
+	try {
+		const pid = Number.parseInt(readFileSync(join(path, ".subagent-owner"), "utf8").trim(), 10);
+		if (!Number.isFinite(pid) || pid <= 0) return false;
+		if (pid === process.pid) return true;
+		process.kill(pid, 0); // throws ESRCH when the owner is gone
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Remove worktree dirs that git no longer knows about (partial-crash leftovers).
+ * Registered worktrees are never touched here — `reapDeadWorktrees` owns those,
+ * and a live child's checkout must survive.
  */
 export function sweepStale(root: string): void {
 	root = realpathSync(root);
-	const sub = join(root, ".git", "subagents");
-	if (!existsSync(sub)) return;
-	const registered = new Set(worktreePaths(root));
+	const sub = subagentsDir(root);
+	if (!sub || !existsSync(sub)) return;
+	const registered = worktreePaths(root);
 	for (const runDir of readDirs(sub)) {
 		for (const taskDir of readDirs(join(sub, runDir))) {
 			const dir = join(sub, runDir, taskDir);
-			if (registered.has(dir)) continue; // live worktree
-			try {
-				git(root, ["worktree", "remove", "--force", dir]);
-			} catch {
-				// dir not a registered worktree (partial crash) — plain rm
-				rmSync(dir, { recursive: true, force: true });
-			}
+			if (registered.some((p) => samePath(p, dir))) continue; // live/registered worktree
+			if (ownerAlive(dir)) continue; // claimed by a running session
+			rmSync(dir, { recursive: true, force: true });
 		}
 	}
 	prune(root);
 }
 
+/** Registered worktree paths. `-z` keeps paths verbatim (no C-quoting to undo). */
 function worktreePaths(root: string): string[] {
 	try {
-		return git(root, ["worktree", "list", "--porcelain"])
-			.split("\n")
+		return git(root, ["worktree", "list", "--porcelain", "-z"])
+			.split("\0")
 			.filter((l) => l.startsWith("worktree "))
-			.map((l) => l.slice("worktree ".length).trim());
+			.map((l) => l.slice("worktree ".length));
 	} catch {
 		return [];
 	}
 }
 
+function isInside(path: string, dir: string): boolean {
+	const p = safeReal(path);
+	const d = safeReal(dir);
+	return p === d || p.startsWith(`${d}/`);
+}
+
+function safeReal(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+
 function readDirs(dir: string): string[] {
 	try {
 		return readdirSync(dir, { withFileTypes: true })