@arhen/pi-core-subagent 1.3.32 → 1.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.32",
+	"version": "1.3.34",
 	"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/agentfile.ts

@@ -13,6 +13,8 @@ export interface AgentFileInfo {
 	model?: string;
 	tools?: string[];
 	description?: string;
+	/** The matched file path — surfaced so the leader can audit which file won. */
+	path?: string;
 }
 
 const AGENT_DIRS = [".agents/agents", ".claude/agents", ".pi/agents"] as const;
@@ -41,10 +43,23 @@ const STOP = new Set([
 	"as",
 	"how",
 	"what",
-	"when",
 	"who",
 ]);
 
+/** A body becomes the child's ENTIRE system prompt — an oversized reference file
+ *  would blow the context window and kill the session with a cryptic error. */
+const MAX_BODY_CHARS = 64_000;
+
+/** Per-cwd memo of the ancestor walk (project dirs then home), since the files
+ *  can't meaningfully change within one run and the walk costs 3 sync stats per
+ *  ancestor dir per task otherwise. Keyed per (agentDir + cwd). */
+const walkCache = new Map<string, AgentFileInfo[]>();
+
+/** Test/diagnostic hook: flush the walk cache (files changed mid-session). */
+export function clearAgentFileCache(): void {
+	walkCache.clear();
+}
+
 /** Lowercase, split, drop stopwords, strip plural -s/-es. */
 function tokens(text: string): string[] {
 	return (text.toLowerCase().match(/[a-z0-9]+/g) ?? [])
@@ -68,65 +83,67 @@ function readAgentFile(dir: string): AgentFileInfo[] {
 	const out: AgentFileInfo[] = [];
 	for (const entry of readdirSync(dir)) {
 		if (!entry.endsWith(".md")) continue;
-		const { frontmatter, body } = parseFrontmatter(readFileSync(join(dir, entry), "utf8"));
+		const path = join(dir, entry);
+		const { frontmatter, body } = parseFrontmatter(readFileSync(path, "utf8"));
+		let trimmed = body;
+		if (trimmed.length > MAX_BODY_CHARS) {
+			trimmed = `${trimmed.slice(0, MAX_BODY_CHARS)}\n\n[truncated: agent file exceeded ${MAX_BODY_CHARS} chars — slim it down]`;
+		}
+		const toolsF = frontmatter.tools;
 		const tools =
-			typeof frontmatter.tools === "string"
-				? frontmatter.tools
+			typeof toolsF === "string"
+				? toolsF
 						.split(",")
 						.map((t) => t.trim())
 						.filter(Boolean)
-				: Array.isArray(frontmatter.tools)
-					? frontmatter.tools.map(String)
+				: Array.isArray(toolsF)
+					? toolsF.map(String)
 					: undefined;
 		out.push({
-			body,
+			body: trimmed,
 			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 			tools: tools?.length ? tools : undefined,
 			description: typeof frontmatter.description === "string" ? frontmatter.description : undefined,
+			path,
 		});
 	}
 	return out;
 }
 
-/**
- * Best agent-file match for a spawn goal. Order: `.agents/agents` (single
- * source) → `.claude/agents` → `.pi/agents` per cwd ancestor (nearest first),
- * then home (`~/.agents` → `~/.claude` → `~/.pi`). Within a dir, highest
- * description-overlap score wins; the first dir with a match is returned.
- * `agentDir` is the pi agent dir (`~/.pi/agent`); home is derived from it.
- */
-export function resolveAgentFile(name: string, task: string, cwd: string, agentDir: string): AgentFileInfo | undefined {
-	const query = tokens(`${name} ${task}`);
+/** Walk cwd's ancestors, then home, returning files in priority order (nearest
+ *  first, each dir's 3 subdirs in AGENT_DIRS order). */
+function allAgentFiles(cwd: string, agentDir: string): AgentFileInfo[] {
+	const out: AgentFileInfo[] = [];
 	let dir = cwd;
 	while (true) {
-		for (const sub of AGENT_DIRS) {
-			let best: AgentFileInfo | undefined;
-			let bestScore = 0;
-			for (const file of readAgentFile(join(dir, sub))) {
-				const s = score(query, tokens(file.description ?? ""));
-				if (s > bestScore) {
-					best = file;
-					bestScore = s;
-				}
-			}
-			if (best) return best; // first dir with any match wins (priority over score)
-		}
+		for (const sub of AGENT_DIRS) out.push(...readAgentFile(join(dir, sub)));
 		const parent = dirname(dir);
 		if (parent === dir) break;
 		dir = parent;
 	}
 	const home = dirname(dirname(agentDir)); // ~/.pi/agent → ~
-	for (const sub of AGENT_DIRS) {
-		let best: AgentFileInfo | undefined;
-		let bestScore = 0;
-		for (const file of readAgentFile(join(home, sub))) {
-			const s = score(query, tokens(file.description ?? ""));
-			if (s > bestScore) {
-				best = file;
-				bestScore = s;
-			}
+	for (const sub of AGENT_DIRS) out.push(...readAgentFile(join(home, sub)));
+	return out;
+}
+
+/** Best agent-file match for a spawn goal. Caches per (agentDir, cwd). */
+export function resolveAgentFile(name: string, task: string, cwd: string, agentDir: string): AgentFileInfo | undefined {
+	const query = tokens(`${name} ${task}`);
+	const cacheKey = `${agentDir}${cwd}`;
+	let files = walkCache.get(cacheKey);
+	if (!files) {
+		files = allAgentFiles(cwd, agentDir);
+		if (walkCache.size >= 512) walkCache.clear();
+		walkCache.set(cacheKey, files);
+	}
+	let best: AgentFileInfo | undefined;
+	let bestScore = 0;
+	for (const file of files) {
+		const s = score(query, tokens(file.description ?? ""));
+		if (s > 0 && s > bestScore) {
+			best = file;
+			bestScore = s;
 		}
-		if (best) return best;
 	}
-	return undefined;
+	return best;
 }

package/src/format.ts

@@ -196,6 +196,23 @@ export class SubagentsWidget implements Component {
 	}
 }
 /** Blocking-call summary: full text, because the model asked for it. */
+/** Where a write child's edits went: a branch to merge, or straight into the tree. */
+function worktreeLine(task: TaskSnapshot): string {
+	const parts: string[] = [];
+	if (task.branch) {
+		const files = task.changedFiles?.length
+			? ` (${task.changedFiles.length} file(s): ${truncateText(task.changedFiles.join(", "), 160)})`
+			: "";
+		parts.push(`Branch: ${task.branch}${files} — merge with \`git merge --no-ff ${task.branch}\` after review.`);
+	} else if (task.isolation === "in-place") {
+		parts.push(
+			`Applied IN PLACE (no branch) — ${task.isolationReason ?? "worktree unavailable"}. Review the working tree directly.`,
+		);
+	}
+	if (task.worktreeError) parts.push(`Worktree: ${task.worktreeError}`);
+	return parts.length ? `\n${parts.join("\n")}` : "";
+}
+
 export function makeSummary(run: RunSnapshot): string {
 	const succeeded = run.tasks.filter((t) => t.status === "completed").length;
 	const failed = run.tasks.filter((t) => t.status === "failed").length;
@@ -209,8 +226,9 @@ export function makeSummary(run: RunSnapshot): string {
 	for (const task of run.tasks) {
 		// Edges are named so the leader can compare what it delegated against what came back.
 		const edge = task.needs?.length ? ` (${task.id}, needs ${task.needs.join(", ")})` : ` (${task.id})`;
+		const fileNote = task.agentFile ? ` [${task.agentFile}]` : "";
 		lines.push(
-			`\n## ${task.agent}${edge} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${task.branch ? `\nBranch: ${task.branch}${task.changedFiles?.length ? ` (${task.changedFiles.length} file(s): ${truncateText(task.changedFiles.join(", "), 160)})` : ""} — merge with \`git merge --no-ff ${task.branch}\` after review.` : ""}`,
+			`\n## ${task.agent}${edge}${fileNote} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task)}`,
 		);
 	}
 	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.

package/src/index.ts

@@ -188,15 +188,23 @@ export default function (pi: ExtensionAPI) {
 					intercom.push(...awaited.intercom);
 					if (awaited.intercom.some((m) => m.kind === "ask")) break;
 				}
-				const asked = intercom.find((m) => m.kind === "ask");
+				// EVERY ask must surface: siblings that asked in the same wake got no
+				// followUp notice (the park swallowed it), so showing only the first
+				// leaves the rest blocked until their 10-minute timeout.
+				const asks = intercom.filter((m) => m.kind === "ask");
 				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.`
+					asks.length > 0
+						? `\n${asks.length} child(ren) waiting for your answer:\n${asks
+								.map(
+									(a) =>
+										`- ${a.agent} (${a.taskId}): ${a.text}\n  reply_subagent(runId: "${run.id}", taskId: "${a.taskId}", message: ...)`,
+								)
+								.join("\n")}\nAnswer each, then await_subagent again for the result.`
 						: "",
 				]
 					.filter(Boolean)
@@ -321,9 +329,12 @@ export default function (pi: ExtensionAPI) {
 				`Run ${run.id} — ${run.status}`,
 				...tasks.map((t) => {
 					const wt = t.branch
-						? `\nBranch: ${t.branch}\n${t.diffStat || "(no changes committed)"}\nMerge after review: \`git merge --no-ff ${t.branch}\``
-						: "";
-					return `\n## ${t.agent} ${statusIcon(t.status)}\nGoal: ${truncateText(t.task, 300)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}${wt}\n${formatUsage(t.usage)}`;
+						? `\nBranch: ${t.branch}\n${t.diffStat || "(no diff available)"}\nMerge after review: \`git merge --no-ff ${t.branch}\``
+						: t.isolation === "in-place"
+							? `\nApplied IN PLACE (no branch) — ${t.isolationReason ?? "worktree unavailable"}. The changes are already in your working tree.`
+							: "";
+					const wtErr = t.worktreeError ? `\nWorktree: ${t.worktreeError}` : "";
+					return `\n## ${t.agent} ${statusIcon(t.status)}\nGoal: ${truncateText(t.task, 300)}\n${t.error ? `Error: ${t.error}` : t.finalText || "(no output yet)"}${wt}${wtErr}\n${formatUsage(t.usage)}`;
 				}),
 			].join("\n");
 			return { content: [{ type: "text", text: truncateText(text) }], details: { run: cloneRun(run) } };

package/src/manager.ts

@@ -1,7 +1,7 @@
 /** SubagentManager: run lifecycle, child sessions, intercom, persistence, widget plumbing. */
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
@@ -61,6 +61,8 @@ 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
+/** Intercom messages buffered per park before the followUp path takes over. */
+const PARKED_MSG_CAP = 24;
 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. */
@@ -302,6 +304,28 @@ export class SubagentManager {
 			child.dispose();
 		}
 		this.liveChildren.clear();
+		// Mark every non-terminal task aborted BEFORE resolving pendingReplies: the
+		// resumed onAskParent closure re-checks status, and a still-awaiting task
+		// would flip back to "running" and re-insert the run after the maps clear —
+		// a ghost run that widgets re-arm on and persist forever.
+		for (const run of this.runs.values()) {
+			for (const task of run.tasks) {
+				if (!TERMINAL.includes(task.status)) {
+					task.status = "aborted";
+					task.error = task.error ?? "(session ended)";
+				}
+			}
+		}
+		// Release anyone parked on a run before the maps go — dropping waiters would
+		// leave their promises pending forever (autoAwait / await_subagent hang).
+		for (const [runId, waiters] of this.settleWaiters) {
+			const run = this.runs.get(runId);
+			for (const waiter of waiters) waiter(run ? cloneRun(run) : ({ id: runId, status: "aborted" } as RunSnapshot));
+		}
+		for (const pending of this.pendingReplies.values()) {
+			pending.resolve("(session ended — stop work immediately)");
+		}
+		this.parked.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();
@@ -371,7 +395,13 @@ export class SubagentManager {
 			const parentFile = getParentSessionFile(ctx);
 			if (!parentFile) return;
 			const sidecar = parentFile.replace(/\.jsonl$/, ".subagents.json");
-			void writeFile(sidecar, JSON.stringify(this.listRuns().slice(0, 50).map(cloneRun), null, 2)).catch(() => {}); // never surface as an unhandled rejection
+			// Write-then-rename: a plain writeFile can tear on crash and silently drop
+			// ALL run history for the session on the next read.
+			const tmp = `${sidecar}.tmp`;
+			const payload = JSON.stringify(this.listRuns().slice(0, 50).map(cloneRun), null, 2);
+			void writeFile(tmp, payload)
+				.then(() => rename(tmp, sidecar))
+				.catch(() => {}); // never surface as an unhandled rejection
 		} catch {
 			/* ignore */
 		}
@@ -519,6 +549,12 @@ export class SubagentManager {
 		return {
 			onAskParent: async (_taskId, question) => {
 				const key = `${run.id}:${task.id}`;
+				// A tool call already in flight can reach here AFTER the task ended
+				// (abort/timeout/cancel). Reviving it would leave a "running" task in a
+				// finished run — hasActiveRun() then never clears.
+				if (TERMINAL.includes(task.status)) {
+					return "(your task has already ended — stop work and return immediately)";
+				}
 				this.updateTask(run, task, { status: "awaiting_parent" }, ctx);
 				this.liveChildren.get(key)?.touchWatchdog();
 				// While the leader is parked in await_subagent the question rides the wait
@@ -534,6 +570,12 @@ export class SubagentManager {
 				const keepAlive = setInterval(() => this.liveChildren.get(key)?.touchWatchdog(), 30_000);
 				try {
 					const reply = await this.awaitParentReply(run.id, task.id, PARENT_REPLY_TIMEOUT_MS);
+					// Cancel wins over a reply that arrived in the same tick: never move a
+					// terminal task back to "running" (that would let a canceled task be
+					// reported as completed).
+					if (TERMINAL.includes(task.status)) {
+						return "(your task was canceled while you waited — stop work and return immediately)";
+					}
 					this.updateTask(run, task, { status: "running" }, ctx);
 					this.liveChildren.get(key)?.touchWatchdog();
 					return reply;
@@ -578,28 +620,32 @@ export class SubagentManager {
 	private awaitParentReply(runId: string, taskId: string, timeoutMs = 0): Promise<string> {
 		const key = `${runId}:${taskId}`;
 		return new Promise<string>((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, {
+			// Identity-tagged: two asks from one child must not delete each other's
+			// entry (the loser would hang until its own timer).
+			const entry: PendingReply = {
 				resolve: (message) => {
 					if (timer) clearTimeout(timer);
+					if (this.pendingReplies.get(key) === entry) this.pendingReplies.delete(key);
 					resolve(message);
 				},
-			});
+			};
+			const timer =
+				timeoutMs > 0
+					? setTimeout(
+							() =>
+								entry.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, entry);
 		});
 	}
 	deliverReply(runId: string, taskId: string, message: string): boolean {
 		const pending = this.pendingReplies.get(`${runId}:${taskId}`);
 		if (!pending) return false;
-		this.pendingReplies.delete(`${runId}:${taskId}`);
-		pending.resolve(message);
+		pending.resolve(message); // clears its own entry + timer
 		return true;
 	}
 
@@ -687,6 +733,7 @@ export class SubagentManager {
 		// is authoritative — body = system prompt, frontmatter model/tools win over
 		// inline. No match → inline on-demand definition as usual.
 		const file = resolveAgentFile(input.agent, input.task, task.cwd, getAgentDir());
+		if (file?.path) task.agentFile = file.path; // recorded for audit — which file won
 		const prompt = file?.body ?? input.prompt?.trim();
 		const thinking = input.thinking;
 		// Trust boundary: a file can NARROW the toolset (intersect with the leader's
@@ -727,11 +774,14 @@ export class SubagentManager {
 		// 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;
+		let isolationReason: string | undefined;
 		if (canWrite) {
 			try {
 				wt = createWorktree(task.cwd, run.id, task.id);
-			} catch {
+				if (!wt) isolationReason = "not a git repository";
+			} catch (err) {
 				wt = undefined; // git failure → in-place
+				isolationReason = `git worktree add failed: ${err instanceof Error ? err.message : String(err)}`;
 			}
 		}
 		// Map a per-task cwd subpath into the worktree so relative paths stay correct.
@@ -741,14 +791,28 @@ export class SubagentManager {
 		let childCwd = wt?.path ?? task.cwd;
 		if (wt) {
 			const rel = relative(safeRealPath(wt.root), safeRealPath(task.cwd));
-			if (rel.startsWith("..")) {
+			if (rel === ".." || rel.startsWith(`..${sep}`)) {
 				removeWorktree(wt);
 				wt = undefined;
 				childCwd = task.cwd;
+				isolationReason = "task cwd is outside the repository";
 			} else if (rel && rel !== ".") {
 				childCwd = join(wt.path, rel);
+				// The subpath may be gitignored/untracked, so it won't exist in a fresh
+				// checkout — create it rather than fail session start.
+				try {
+					mkdirSync(childCwd, { recursive: true });
+				} catch {
+					childCwd = wt.path;
+				}
 			}
 		}
+		if (canWrite) {
+			// Never let isolation lapse quietly: the leader must know its edits landed
+			// straight in the working tree with no branch to review.
+			task.isolation = wt ? "worktree" : "in-place";
+			task.isolationReason = wt ? undefined : (isolationReason ?? "worktree unavailable");
+		}
 		if (wt) {
 			claimWorktree(wt); // pid marker: another pi session must not reap this
 			this.liveWorktrees.set(`${run.id}:${task.id}`, wt);
@@ -891,17 +955,12 @@ export class SubagentManager {
 					// until the branch is merged — cleanupMerged removes both then.
 					// Commit/diff failures must NOT downgrade a completed task or destroy
 					// its work: the error is reported, the status stays completed.
+					let committed: "committed" | "empty" | undefined;
 					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,
-							task,
-							{ branch: wt.branch, diffStat: stat || undefined, changedFiles: files.length ? files : undefined },
-							ctx,
-							onUpdate,
-						);
+						committed = commitWorktree(wt, `subagent ${task.agent}: ${truncateText(input.task, 60)}`);
+						// Only a real commit is worth a branch: an empty one would send the
+						// leader off to review and merge nothing.
+						keepWorktreeDir = committed === "committed";
 					} 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".
@@ -911,12 +970,36 @@ export class SubagentManager {
 							task,
 							{
 								branch: wt.branch,
-								error: `Worktree commit failed (uncommitted changes remain in ${wt.path}): ${commitErr instanceof Error ? commitErr.message : String(commitErr)}`,
+								worktreeError: `commit failed (uncommitted changes remain in ${wt.path}): ${commitErr instanceof Error ? commitErr.message : String(commitErr)}`,
 							},
 							ctx,
 							onUpdate,
 						);
 					}
+					// Diff separately: a diff failure must not be reported as a lost commit.
+					if (committed === "committed") {
+						try {
+							const { stat, files } = branchDiff(wt);
+							this.updateTask(
+								run,
+								task,
+								{ branch: wt.branch, diffStat: stat || undefined, changedFiles: files.length ? files : undefined },
+								ctx,
+								onUpdate,
+							);
+						} catch (diffErr) {
+							this.updateTask(
+								run,
+								task,
+								{
+									branch: wt.branch,
+									worktreeError: `committed, but the diff could not be read: ${diffErr instanceof Error ? diffErr.message : String(diffErr)}`,
+								},
+								ctx,
+								onUpdate,
+							);
+						}
+					}
 				}
 			}
 		} catch (err) {
@@ -957,12 +1040,16 @@ export class SubagentManager {
 			// dir — dropping it would make the work unreachable.
 			if (wt && task.status !== "completed") {
 				await new Promise((r) => setTimeout(r, 250));
+				let partial: "committed" | "empty" | undefined;
 				try {
-					commitWorktree(wt, `subagent ${task.agent} (partial, ${task.status})`);
+					partial = commitWorktree(wt, `subagent ${task.agent} (partial, ${task.status})`);
 				} catch {
-					keepWorktreeDir = true;
+					keepWorktreeDir = true; // work exists only in the dir — keep it
+				}
+				// A branch is only worth reporting when it actually carries something.
+				if (partial === "committed" || keepWorktreeDir) {
+					this.updateTask(run, task, { branch: wt.branch }, ctx, onUpdate);
 				}
-				this.updateTask(run, task, { branch: wt.branch }, ctx, onUpdate);
 			}
 			if (wt && !keepWorktreeDir) removeWorktree(wt);
 			// Released only after the dir is gone: while it exists, the branch must stay
@@ -1122,13 +1209,14 @@ export class SubagentManager {
 		// Broken-upstream tasks are detected by the scheduler; mark them after the wave.
 		for (const s of skipped) {
 			const task = run.tasks.find((t) => t.id === s.id);
-			if (task) {
+			if (task && !TERMINAL.includes(task.status)) {
 				this.updateTask(
 					run,
 					task,
 					{
 						status: "aborted",
-						error: `Skipped: upstream task(s) did not complete: ${s.needs.join(", ")}`,
+						// Don't overwrite a real reason (e.g. "Canceled by subagent_cancel").
+						error: task.error || `Skipped: upstream task(s) did not complete: ${s.needs.join(", ")}`,
 						endedAt: Date.now(),
 					},
 					ctx,
@@ -1136,6 +1224,19 @@ export class SubagentManager {
 				);
 			}
 		}
+		// Belt and braces: the wave loop breaks out when no frontier is ready, which
+		// would otherwise leave tasks queued inside a terminal run — hasActiveRun()
+		// then never clears and the widget stays pinned.
+		for (const task of run.tasks) {
+			if (TERMINAL.includes(task.status)) continue;
+			this.updateTask(
+				run,
+				task,
+				{ status: "aborted", error: task.error || "Never ran: no runnable wave", endedAt: Date.now() },
+				ctx,
+				onUpdate,
+			);
+		}
 
 		const failed = run.tasks.some((t) => t.status === "failed");
 		const aborted = run.tasks.some((t) => t.status === "aborted") || Boolean(signal?.aborted);
@@ -1290,15 +1391,37 @@ export class SubagentManager {
 	}
 
 	/** Child→leader messages collected while the parent is parked in await_subagent. */
-	private parked = new Map<string, { msgs: ParkedMsg[]; wake: () => void }>();
+	/** Every awaiter parked on a run — a SET, so two concurrent awaits can't
+	 *  overwrite each other's buffer and silently swallow one side's intercom. */
+	private parked = new Map<string, Set<{ msgs: ParkedMsg[]; wake: () => void }>>();
 
 	/** While the parent is parked on this run, deliver the message through the wait instead of the steering queue. */
 	private collectParked(runId: string, msg: ParkedMsg): boolean {
-		const p = this.parked.get(runId);
-		if (!p) return false;
-		if (p.msgs.length < 24) p.msgs.push(msg);
-		p.wake(); // resolve the parked await early — the leader breathes on every message
-		return true;
+		const parked = this.parked.get(runId);
+		if (!parked || parked.size === 0) return false;
+		let delivered = false;
+		for (const p of parked) {
+			if (p.msgs.length < PARKED_MSG_CAP) {
+				p.msgs.push(msg);
+				delivered = true;
+			} else if (msg.kind === "ask") {
+				// An unanswered ask blocks a child for 10 minutes — it must never be the
+				// message that gets dropped by the cap. Evict the oldest NON-ask first
+				// (asks already block children; displacing one hangs the earlier asker).
+				const drop = p.msgs.findIndex((m) => m.kind !== "ask");
+				if (drop !== -1) {
+					p.msgs.splice(drop, 1);
+					p.msgs.push(msg);
+				} else {
+					p.msgs[p.msgs.length - 1] = msg; // all asks — overwrite the oldest ask
+				}
+				delivered = true;
+			}
+			p.wake(); // resolve the parked await early — the leader breathes on every message
+		}
+		// Not buffered anywhere → report undelivered so the caller falls back to a
+		// followUp notice instead of assuming the leader saw it.
+		return delivered;
 	}
 
 	awaitRun(
@@ -1307,8 +1430,12 @@ export class SubagentManager {
 	): Promise<{ run: RunSnapshot | undefined; intercom: ParkedMsg[] } | undefined> {
 		const run = this.runs.get(runId);
 		if (!run) return Promise.resolve(undefined);
+		let entry: { msgs: ParkedMsg[]; wake: () => void } | undefined;
 		const finish = (): void => {
-			this.parked.delete(runId);
+			const parked = this.parked.get(runId);
+			if (!parked || !entry) return;
+			parked.delete(entry); // only our own park — a sibling await keeps receiving
+			if (parked.size === 0) this.parked.delete(runId);
 		};
 		if (TERMINAL.includes(run.status)) {
 			run.awaited = true;
@@ -1331,17 +1458,28 @@ export class SubagentManager {
 			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: () => waiter(cloneRun(run)) });
+			entry = { msgs, wake: () => waiter(cloneRun(run)) };
+			let parked = this.parked.get(runId);
+			if (!parked) {
+				parked = new Set();
+				this.parked.set(runId, parked);
+			}
+			parked.add(entry);
 		});
 		if (timeoutMs !== undefined && timeoutMs > 0) {
+			let timedOut = false;
 			return Promise.race([
 				settled.then((r) => {
 					finish();
-					run.awaited = true;
+					// Only mark awaited when this call actually hands the run back to the
+					// leader. A slice that already timed out is abandoned — setting it here
+					// would suppress the run's completion notice the leader still needs.
+					if (!timedOut) run.awaited = true;
 					return { run: r, intercom: msgs };
 				}),
 				new Promise<{ run: RunSnapshot | undefined; intercom: ParkedMsg[] } | undefined>((resolve) => {
 					const timer = setTimeout(() => {
+						timedOut = true;
 						finish();
 						resolve(this.runs.get(runId) ? { run: cloneRun(this.runs.get(runId)!), intercom: msgs } : undefined);
 					}, timeoutMs);

package/src/types.ts

@@ -41,10 +41,21 @@ export interface TaskSnapshot {
 	usage: UsageStats;
 	/** Sibling addresses for intercom tools (send_agent_message targets). */
 	roster?: string;
+	/** Path of the agent file that drove this child (inline definition otherwise).
+	 *  Surfaced so the leader can audit which file took over — a description-only
+	 *  match must never be invisible. */
+	agentFile?: string;
 	/** Git worktree isolation (write agents): branch + diff of the child's changes. */
 	branch?: string;
 	diffStat?: string;
 	changedFiles?: string[];
+	/** How a write child's edits were applied. "in-place" means NO branch: the
+	 *  changes are already in the leader's tree — always surfaced, never silent. */
+	isolation?: "worktree" | "in-place";
+	isolationReason?: string;
+	/** Worktree commit/diff trouble. Kept apart from `error` so a completed task
+	 *  still reports its answer. */
+	worktreeError?: string;
 }
 
 export interface RunSnapshot {

package/src/worktree.ts

@@ -11,7 +11,8 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { hostname, uptime } from "node:os";
+import { join, resolve } from "node:path";
 
 export interface Worktree {
 	root: string; // repo root (main tree)
@@ -22,13 +23,33 @@ export interface Worktree {
 
 const BRANCH_PREFIX = "subagents/";
 
+/** Identity + signing fallbacks: a machine without user.email (CI, fresh box) or
+ *  with commit.gpgsign set must not fail — or worse, block on a passphrase prompt. */
+const COMMIT_CONFIG = ["-c", "commit.gpgsign=false", "-c", "user.name=pi subagent", "-c", "user.email=subagent@local"];
+const GIT_TIMEOUT_MS = 120_000;
+const GIT_MAX_BUFFER = 32 * 1024 * 1024;
+
 function git(root: string, args: string[]): string {
-	return execFileSync("git", ["-C", root, ...args], { encoding: "utf8" }).trim();
+	return gitRaw(root, args).trim();
+}
+
+/** Untrimmed git output — required for -z parsing, where a path may end in a space. */
+function gitRaw(root: string, args: string[]): string {
+	return execFileSync("git", ["-C", root, ...args], {
+		encoding: "utf8",
+		timeout: GIT_TIMEOUT_MS,
+		maxBuffer: GIT_MAX_BUFFER,
+	});
 }
 
 /** Run git directly inside a directory (worktree ops). */
 function gitIn(dir: string, args: string[]): string {
-	return execFileSync("git", [...args], { cwd: dir, encoding: "utf8" }).trim();
+	return execFileSync("git", [...args], {
+		cwd: dir,
+		encoding: "utf8",
+		timeout: GIT_TIMEOUT_MS,
+		maxBuffer: GIT_MAX_BUFFER,
+	}).trim();
 }
 
 function gitOk(root: string, args: string[]): boolean {
@@ -67,18 +88,19 @@ export function createWorktree(cwd: string, runId: string, taskId: string): Work
 	// --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;
+	const container = subagentsDir(root);
+	if (!container) return undefined;
 	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"]);
+	// Branch from the recorded SHA, not "HEAD" — a concurrent commit in the main
+	// tree between the two would otherwise skew every later diff against base.
+	git(root, ["worktree", "add", "-b", branch, path, base]);
 	// Deps follow the child into the worktree; anything else the task needs is
 	// project content already checked out there.
 	const nm = join(root, "node_modules");
@@ -100,14 +122,27 @@ export function createWorktree(cwd: string, runId: string, taskId: string): Work
  * 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);
+	return commitIn(wt.path, message, wt.branch);
 }
 
-function commitIn(dir: string, message: string): "committed" | "empty" {
+function commitIn(dir: string, message: string, expectBranch?: string): "committed" | "empty" {
+	// A child that detached HEAD or switched branches would commit somewhere the
+	// leader is never told about — refuse rather than report a branch without the work.
+	if (expectBranch) {
+		// `symbolic-ref` EXITS NON-ZERO on a detached HEAD — catch it rather than
+		// letting the raw git failure masquerade as a commit error.
+		let head = "detached";
+		try {
+			head = gitIn(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]) || "detached";
+		} catch {
+			head = "detached";
+		}
+		if (head !== expectBranch) throw new Error(`worktree HEAD is "${head}", expected ${expectBranch}`);
+	}
 	// 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"]);
+	gitIn(dir, [...COMMIT_CONFIG, "commit", "-m", message, "--no-verify"]);
 	return "committed";
 }
 
@@ -134,21 +169,33 @@ export function removeByBranch(cwd: string, branch: string): void {
 	if (container) dropDir(root, join(container, branch.slice(BRANCH_PREFIX.length)));
 }
 
-/** `<git-common-dir>/subagents` — where our worktrees live for this repo. */
+/** `<git-common-dir>/subagents` — where our worktrees live for this repo.
+ *  `--path-format` needs git ≥ 2.31; fall back to resolving the relative form. */
 function subagentsDir(root: string): string | undefined {
 	try {
 		return join(git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]), "subagents");
 	} catch {
-		return undefined;
+		try {
+			return join(resolve(root, git(root, ["rev-parse", "--git-common-dir"])), "subagents");
+		} catch {
+			return undefined;
+		}
 	}
 }
 
+/** Marker path lives BESIDE the checkout, never inside it — a file in the worktree
+ *  would be staged by `add -A`, committed into the branch, and merged into main. */
+function ownerFile(path: string): string {
+	return `${path}.owner`;
+}
+
 function dropDir(root: string, path: string): void {
 	try {
 		git(root, ["worktree", "remove", "--force", path]);
 	} catch {
 		if (existsSync(path)) rmSync(path, { recursive: true, force: true });
 	}
+	rmSync(ownerFile(path), { force: true }); // marker lives beside the dir
 	prune(root);
 }
 
@@ -161,9 +208,10 @@ function prune(root: string): void {
 	}
 }
 
-/** Is this branch checked out in some worktree right now? Checked fresh, per call. */
+/** Is this branch checked out right now? "Unknown" counts as YES (never delete blind). */
 function isCheckedOut(root: string, branch: string): boolean {
-	return worktreeBranches(root).includes(branch);
+	const branches = worktreeBranches(root);
+	return branches === undefined || branches.includes(branch);
 }
 
 /**
@@ -187,29 +235,29 @@ export function cleanupMerged(root: string, opts: { skipBranches?: Set<string>;
 		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
+		// Branch FIRST: `-d` refuses anything not truly merged, so a stale "merged"
+		// listing can no longer cost us a checkout that still holds work.
+		if (!gitOk(root, ["branch", "-d", branch])) continue;
 		if (existsSync(path)) {
 			try {
 				git(root, ["worktree", "remove", "--force", path]);
 			} catch {
-				continue;
+				/* branch is gone; a leftover dir is swept later */
 			}
 		}
-		if (gitOk(root, ["branch", "-d", branch])) cleaned += 1;
+		rmSync(ownerFile(path), { force: true });
+		cleaned += 1;
 	}
 	prune(root);
 	return cleaned;
 }
 
-/** Branch names currently checked out in any worktree (incl. the main one). */
-function worktreeBranches(root: string): string[] {
-	try {
-		return git(root, ["worktree", "list", "--porcelain", "-z"])
-			.split("\0")
-			.filter((l) => l.startsWith("branch "))
-			.map((l) => l.slice("branch refs/heads/".length));
-	} catch {
-		return [];
-	}
+/** Branch names currently checked out in any worktree, or undefined when git
+ *  couldn't be asked — callers MUST treat undefined as "unknown", never as "none",
+ *  or they will happily delete live checkouts. */
+function worktreeBranches(root: string): string[] | undefined {
+	const listing = worktreeListing(root);
+	return listing?.filter((l) => l.startsWith("branch ")).map((l) => l.slice("branch refs/heads/".length));
 }
 
 /**
@@ -221,14 +269,30 @@ export function reapDeadWorktrees(root: string, isLive: (path: string) => boolea
 	root = realpathSync(root);
 	const sub = subagentsDir(root);
 	if (!sub || !existsSync(sub)) return 0;
+	const registered = worktreePaths(root);
+	if (!registered) return 0; // listing failed — touch nothing
 	let reaped = 0;
-	for (const path of worktreePaths(root)) {
+	for (const path of registered) {
 		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
+			// A dir git refuses to read (half-created by a timed-out worktree add,
+			// or corrupted) holds no recoverable work — drop it instead of retrying
+			// forever. The "never drop uncommitted work" rule protects readable dirs.
+			try {
+				execFileSync("git", ["-C", path, "rev-parse", "--git-dir"], {
+					encoding: "utf8",
+					timeout: GIT_TIMEOUT_MS,
+					maxBuffer: GIT_MAX_BUFFER,
+				});
+				continue; // git still reads it — legitimate work, keep
+			} catch {
+				dropDir(root, path);
+				reaped += 1;
+			}
+			continue;
 		}
 		dropDir(root, path);
 		reaped += 1;
@@ -242,23 +306,46 @@ export function reapDeadWorktrees(root: string, isLive: (path: string) => boolea
  */
 export function claimWorktree(wt: Worktree): void {
 	try {
-		writeFileSync(join(wt.path, ".subagent-owner"), String(process.pid));
+		writeFileSync(
+			ownerFile(wt.path),
+			JSON.stringify({ pid: process.pid, host: hostname(), boot: bootId(), at: Date.now() }),
+		);
 	} 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. */
+/**
+ * True when the worktree is claimed by a process that still exists HERE.
+ * Guards against pid reuse across reboots (boot id) and other hosts (hostname);
+ * EPERM means the pid exists under another user — alive, not reapable.
+ */
 export function ownerAlive(path: string): boolean {
+	let marker: { pid?: number; host?: string; boot?: string };
 	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;
+		marker = JSON.parse(readFileSync(ownerFile(path), "utf8"));
 	} catch {
-		return false;
+		return false; // no marker (or unreadable) → nobody claims it
 	}
+	const pid = marker.pid;
+	if (!pid || !Number.isFinite(pid) || pid <= 0) return false;
+	if (marker.host !== hostname()) return true; // another machine's checkout — never ours to reap
+	if (marker.boot !== bootId()) return false; // pre-reboot pid: reuse is near-certain
+	if (pid === process.pid) return true;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException)?.code === "EPERM"; // exists, other user
+	}
+}
+
+/** Stable per-boot id, so a recycled pid from before a reboot can't look alive.
+ *  Compute ONE floor on the expressed seconds, not two — separate floors of
+ *  walltime and uptime flip by ±1 around integer boundaries and would read a
+ *  live marker as dead on a cross-second read. */
+function bootId(): string {
+	return String(Math.floor((Date.now() - uptime() * 1000) / 1000));
 }
 
 /**
@@ -271,26 +358,49 @@ export function sweepStale(root: string): void {
 	const sub = subagentsDir(root);
 	if (!sub || !existsSync(sub)) return;
 	const registered = worktreePaths(root);
+	// Unknown registration = every dir might be live. Deleting here would be the
+	// single most destructive thing this module can do; bail instead.
+	if (!registered) return;
+	// Empty run dirs are litter — a run dir holds nothing but its task dirs.
+	for (const runDir of readdirSync(sub, { withFileTypes: true })) {
+		if (!runDir.isDirectory()) continue;
+		const runPath = join(sub, runDir.name);
+		try {
+			if (readdirSync(runPath).length === 0) rmSync(runPath, { recursive: true, force: true });
+		} catch {
+			/* skip */
+		}
+	}
 	for (const runDir of readDirs(sub)) {
 		for (const taskDir of readDirs(join(sub, runDir))) {
 			const dir = join(sub, runDir, taskDir);
 			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 });
+			rmSync(ownerFile(dir), { force: true });
 		}
 	}
 	prune(root);
 }
 
-/** Registered worktree paths. `-z` keeps paths verbatim (no C-quoting to undo). */
-function worktreePaths(root: string): string[] {
+/** Registered worktree paths, or undefined when the listing failed (see above). */
+function worktreePaths(root: string): string[] | undefined {
+	const listing = worktreeListing(root);
+	return listing?.filter((l) => l.startsWith("worktree ")).map((l) => l.slice("worktree ".length));
+}
+
+/** `worktree list --porcelain -z`; `-z` needs git ≥ 2.36, so fall back to the
+ *  newline form (which C-quotes exotic paths — those simply won't match, and a
+ *  non-match is safe: it only ever means "treat as live"). */
+function worktreeListing(root: string): string[] | undefined {
 	try {
-		return git(root, ["worktree", "list", "--porcelain", "-z"])
-			.split("\0")
-			.filter((l) => l.startsWith("worktree "))
-			.map((l) => l.slice("worktree ".length));
+		return gitRaw(root, ["worktree", "list", "--porcelain", "-z"]).split("\0").filter(Boolean);
 	} catch {
-		return [];
+		try {
+			return git(root, ["worktree", "list", "--porcelain"]).split("\n").filter(Boolean);
+		} catch {
+			return undefined; // unknown — callers must bail out
+		}
 	}
 }