@arhen/pi-core-subagent 1.3.37 → 1.3.39

package/README.md

@@ -147,6 +147,12 @@ On completion the extension commits the child's changes (the child is told not t
 git merge --no-ff subagents/<run>/<task>
 ```
 
+**Branch relationships — read this before merging.** A write task that `needs` a completed write task is **stacked**: its worktree branches from the upstream's branch, so the child actually sees the files its upstream wrote (basing on main `HEAD` would hand it a tree without them, and its merge would revert the upstream). The summary says `Stacked on <branch> — merge that branch FIRST`; merge in dependency order.
+
+Same-wave write tasks are **siblings**: both branch from the same base, so they are independent, not stacked. When two siblings changed the same file the summary emits `CONFLICT RISK` naming the overlap — the second `git merge` will be a real 3-way. Siblings that touched *different* but coupled files (a schema and its consumer) merge cleanly and can still break at runtime; that one is on you.
+
+**Dependencies are shared, not isolated.** `node_modules` is symlinked to the main checkout, so dependency writes escape the worktree: children are instructed never to install, upgrade, or delete deps. A task that genuinely needs a dependency change should edit the manifest and say so.
+
 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:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.37",
+	"version": "1.3.39",
 	"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

@@ -44,24 +44,12 @@ const STOP = new Set([
 	"how",
 	"what",
 	"who",
-	// Generic connectors/verbs that carry no routing signal. Two of these shared
-	// used to be enough to bind a task to an unrelated agent file (a "release
-	// audit" landing on a PRD writer via "from" + "user").
+	// Pure connectors only. Words like create/user/work/run were stopped here to
+	// kill one false positive and took real routing signal with them (a
+	// scaffolder agent is legitimately "creates", a research agent "user") — the
+	// coverage gate handles weak matches without blinding whole categories.
 	"from",
 	"into",
-	"user",
-	"note",
-	"creat",
-	"create",
-	"make",
-	"use",
-	"work",
-	"run",
-	"new",
-	"other",
-	"single",
-	"formal",
-	"description",
 	"this",
 	"that",
 	"it",
@@ -69,6 +57,7 @@ const STOP = new Set([
 	"any",
 	"per",
 	"via",
+	"other",
 ]);
 
 /** A body becomes the child's ENTIRE system prompt — an oversized reference file
@@ -77,7 +66,7 @@ const MAX_BODY_CHARS = 64_000;
 /** A file takes over the prompt AND the model, so a weak match is expensive.
  *  Both gates must pass: distinct shared terms, and share of the description. */
 const MIN_SHARED_TERMS = 2;
-const MIN_DESC_COVERAGE = 0.2;
+const MIN_COVERAGE = 0.4;
 
 /** 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
@@ -95,8 +84,11 @@ function tokens(text: string): string[] {
 		.filter((t) => !STOP.has(t) && t.length > 1)
 		.map((t) => {
 			if (t.endsWith("ing") && t.length > 5) t = t.slice(0, -3);
-			if (t.endsWith("es") && t.length > 4) t = t.slice(0, -2);
-			else if (t.endsWith("s") && t.length > 3) t = t.slice(0, -1);
+			// Only -es after a sibilant is a two-char plural (batches, boxes). Blindly
+			// stripping "es" mangles every -e noun — services→servic vs service→service
+			// never matched, silently breaking the most common routing words.
+			if (/(?:ch|sh|ss|x|z|s)es$/.test(t) && t.length > 4) t = t.slice(0, -2);
+			else if (t.endsWith("s") && !t.endsWith("ss") && t.length > 3) t = t.slice(0, -1);
 			return t;
 		});
 }
@@ -117,8 +109,12 @@ function score(query: string[], desc: string[]): number {
 	const shared = new Set<string>();
 	for (const t of desc) if (q.has(t)) shared.add(t);
 	if (shared.size < MIN_SHARED_TERMS) return 0;
-	const uniqueDesc = new Set(desc);
-	if (shared.size / uniqueDesc.size < MIN_DESC_COVERAGE) return 0;
+	// Normalize by the SMALLER side. Dividing by the description's length alone
+	// punished well-written descriptions: a 20-token description needed 4 shared
+	// terms while a lazy 3-token one needed 2, so better docs routed worse — and
+	// a 2-word goal could never match a detailed description at all.
+	const denom = Math.min(new Set(desc).size, q.size);
+	if (denom === 0 || shared.size / denom < MIN_COVERAGE) return 0;
 	return shared.size;
 }
 

package/src/format.ts

@@ -197,13 +197,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 {
+function worktreeLine(task: TaskSnapshot, siblings?: 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.`);
+		if (task.stackedOn) parts.push(`Stacked on ${task.stackedOn} — merge that branch FIRST.`);
+		// Sibling branches are independent, not stacked: overlapping files mean the
+		// second merge is a real 3-way, and non-overlapping-but-coupled edits break
+		// silently. Both are computable from changedFiles, so say so.
+		const overlap = (siblings ?? [])
+			.filter((s) => s.id !== task.id && s.branch && !s.stackedOn && !task.stackedOn)
+			.flatMap((s) => (s.changedFiles ?? []).filter((f) => task.changedFiles?.includes(f)).map((f) => `${s.id}:${f}`));
+		if (overlap.length > 0) {
+			parts.push(`CONFLICT RISK — sibling branches touched the same file(s): ${truncateText(overlap.join(", "), 200)}`);
+		}
 	} else if (task.isolation === "in-place") {
 		parts.push(
 			`Applied IN PLACE (no branch) — ${task.isolationReason ?? "worktree unavailable"}. Review the working tree directly.`,
@@ -228,7 +238,7 @@ export function makeSummary(run: RunSnapshot): string {
 		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}${fileNote} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task)}`,
+			`\n## ${task.agent}${edge}${fileNote} ${statusIcon(task.status)}${task.error ? `\nError: ${task.error}` : `\n${truncateText(task.finalText || "(no output)")}`}${worktreeLine(task, run.tasks)}`,
 		);
 	}
 	// Ceiling on the WHOLE summary — 16 tasks × 24KB would otherwise flood the parent context.

package/src/index.ts

@@ -129,7 +129,10 @@ export default function (pi: ExtensionAPI) {
 				// 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);
+				// Pass real ownership: in a long-lived process (pi `/new`) the previous
+				// session's markers carry THIS pid, and trusting them made those dirs
+				// unreapable until the process exited.
+				reapDeadWorktrees(root, (p) => ownerAlive(p, manager.ownsWorktree));
 				cleanupMerged(root, { skipBranches: manager.liveBranches() });
 				sweepStale(root);
 			} catch {

package/src/manager.ts

@@ -1,7 +1,7 @@
 /** SubagentManager: run lifecycle, child sessions, intercom, persistence, widget plumbing. */
-import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
-import { rename, writeFile } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, 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 {
@@ -57,8 +57,15 @@ import {
 export const DEFAULT_CONCURRENCY = 3;
 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.
+/** Hard wall-clock ceiling per child. The stall watchdog is touched by every
+ *  event, so a child stuck in a retry/compaction livelock emits forever and is
+ *  never "stalled" — only a cap that events CANNOT reset bounds that. */
+const DEFAULT_RUNTIME_MS = 3_600_000; // 1 h
+/** Last-resort hang detector, not a latency budget. A healthy child can be
+ *  silent for minutes (big-context upload, non-streamed reasoning, provider
+ *  retry backoff), so this is deliberately far above any normal quiet window —
+ *  killing a working child is much worse than waiting out a dead one. */
+const DEFAULT_STALL_MS = 900_000; // 15 min
 /** 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. */
@@ -244,6 +251,16 @@ export class SubagentManager {
 	private widgetTimers = new Map<string, ReturnType<typeof setTimeout>>(); // per-run stream throttle
 	private widgetRuns: RunSnapshot[] = [];
 	private eventSeq = 0;
+	/** Sidecar writes are serialized on this chain — ordering the DECISION isn't
+	 *  enough, two renames in flight can still land out of order. */
+	private persistSeq = 0;
+	private persistedSeq = 0;
+	private persistChain: Promise<unknown> = Promise.resolve();
+	/** Distinguishes managers sharing a pid (tests, SDK hosts with two sessions)
+	 *  so their tmp paths can't collide. */
+	private readonly instanceNonce = Math.random().toString(36).slice(2, 8);
+	/** Set by clearRuns — blocks late persists from erasing the sidecar. */
+	private cleared = false;
 
 	/** When false, strip leader-imposed maxRuntimeMs so tasks run unlimited — toggle via `/subagents auto-limit on|off`. */
 	private autoLimit = true;
@@ -335,6 +352,7 @@ export class SubagentManager {
 		this.settleWaiters.clear();
 		this.pendingReplies.clear();
 		this.runControllers.clear();
+		this.cleared = true; // any persist after this point would write an empty sidecar
 		this.mailboxes = createMailbox();
 		this.widgetTui = null; // force re-registration on the next session
 		if (this.pulseTimer) {
@@ -348,10 +366,21 @@ export class SubagentManager {
 
 	// ── persistence (sidecar per parent session) ────────────────────────
 	async restoreFromSidecar(ctx: ExtensionContext): Promise<void> {
+		this.cleared = false; // a new session may persist again
 		const parentFile = getParentSessionFile(ctx);
 		if (!parentFile) return;
 		const sidecar = parentFile.replace(/\.jsonl$/, ".subagents.json");
 		let runs: RunSnapshot[];
+		// Sweep tmp files a crash left between write and rename (one per dead session).
+		try {
+			const dir = dirname(sidecar);
+			const prefix = `${basename(sidecar)}.`;
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith(prefix) && entry.endsWith(".tmp")) rmSync(join(dir, entry), { force: true });
+			}
+		} catch {
+			/* best-effort */
+		}
 		try {
 			if (!existsSync(sidecar)) return;
 			const raw = JSON.parse(readFileSync(sidecar, "utf-8"));
@@ -392,17 +421,34 @@ export class SubagentManager {
 		}
 	}
 	private persist(ctx: ExtensionContext): void {
+		// After clearRuns the map is empty by design; a late persist (e.g. the
+		// background rejection handler firing after session_shutdown) would write
+		// `[]` over a good sidecar and erase the session's history.
+		if (this.cleared) return;
 		try {
 			const parentFile = getParentSessionFile(ctx);
 			if (!parentFile) return;
 			const sidecar = parentFile.replace(/\.jsonl$/, ".subagents.json");
 			// 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`;
+			// ALL run history for the session on the next read. The tmp name must be
+			// UNIQUE per write — a shared one lets two concurrent persists interleave
+			// their bytes (unparseable sidecar) or rename an older snapshot last.
+			const seq = ++this.persistSeq;
+			const tmp = `${sidecar}.${process.pid}.${this.instanceNonce}.${seq}.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
+			// Serialized: each write+rename runs after the previous one finishes, so two
+			// renames can never be in flight and land out of order.
+			this.persistChain = this.persistChain.then(async () => {
+				// A newer snapshot already landed — this one is stale, don't write it.
+				if (seq < this.persistedSeq) return;
+				try {
+					await writeFile(tmp, payload);
+					await rename(tmp, sidecar);
+					this.persistedSeq = seq;
+				} catch {
+					await rm(tmp, { force: true }).catch(() => {}); // never leak a tmp, never throw
+				}
+			});
 		} catch {
 			/* ignore */
 		}
@@ -663,6 +709,11 @@ export class SubagentManager {
 		watchdog: Watchdog,
 		state: ChildEventState,
 	): void {
+		// ANY event is proof of life. The old allowlist ignored message_start,
+		// turn_start/end, compaction and auto-retry, so a child was killed during
+		// silent-but-healthy windows — context upload, a provider that doesn't
+		// stream reasoning, retry backoff — and surfaced as "Error: terminated".
+		watchdog.touch();
 		const active =
 			event.type === "message_update" ||
 			event.type === "message_end" ||
@@ -672,7 +723,6 @@ export class SubagentManager {
 			event.type === "bash_execution_update" ||
 			event.type === "agent_settled";
 		if (active) {
-			watchdog.touch();
 			this.emit("subagent:session-event", {
 				runId: run.id,
 				taskId: task.id,
@@ -724,6 +774,8 @@ export class SubagentManager {
 		run: RunSnapshot,
 		task: TaskSnapshot,
 		input: TaskInput,
+		/** The task text as WRITTEN, before upstream outputs were spliced in. */
+		routingTask: string,
 		ctx: ExtensionContext,
 		signal: AbortSignal | undefined,
 		onUpdate?: (partial: any) => void,
@@ -733,7 +785,10 @@ export class SubagentManager {
 		// Matched user agent file (`.agents/agents` etc., by description): the file
 		// 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());
+		// Route on the task as written, never on the upstream output spliced into
+		// it: a chain step would otherwise match a different file (and a different
+		// model) at runtime than the one createRun pre-flighted.
+		const file = resolveAgentFile(input.agent, routingTask, 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;
@@ -782,7 +837,15 @@ export class SubagentManager {
 		let isolationReason: string | undefined;
 		if (canWrite) {
 			try {
-				wt = createWorktree(task.cwd, run.id, task.id);
+				// Stack on the upstream write task's branch, so a chained writer actually
+				// SEES the work it was told to build on. Read-only upstreams have no
+				// branch, so those stay based on HEAD.
+				const upstream = (task.needs ?? [])
+					.map((id) => run.tasks.find((t) => t.id === id))
+					.filter((t) => t?.branch && t.status === "completed")
+					.at(-1);
+				wt = createWorktree(task.cwd, run.id, task.id, upstream?.branch);
+				if (wt && upstream?.branch) task.stackedOn = upstream.branch;
 				if (!wt) isolationReason = "not a git repository";
 			} catch (err) {
 				wt = undefined; // git failure → in-place
@@ -823,22 +886,31 @@ export class SubagentManager {
 			this.liveWorktrees.set(`${run.id}:${task.id}`, wt);
 		}
 
-		this.updateTask(
-			run,
-			task,
-			{
-				status: "starting",
-				startedAt: Date.now(),
-				// Upstream outputs were spliced in by the scheduler; the snapshot must show
-				// the prompt the child actually receives.
-				task: input.task,
-				model: input.model,
-				thinking,
-				tools,
-			},
-			ctx,
-			onUpdate,
-		);
+		// Guarded: a throwing event listener or widget failure here would escape
+		// runChild BEFORE the try/finally that releases the worktree — leaking a
+		// checkout that every reaper then skips (registered + owned by a live pid).
+		try {
+			this.updateTask(
+				run,
+				task,
+				{
+					status: "starting",
+					startedAt: Date.now(),
+					// Upstream outputs were spliced in by the scheduler; the snapshot must show
+					// the prompt the child actually receives.
+					task: input.task,
+					// RESOLVED model, not the request — an agent file's `model:` overrides it,
+					// and this patch used to clobber the resolved id recorded above.
+					model: model?.id ?? input.model,
+					thinking,
+					tools,
+				},
+				ctx,
+				onUpdate,
+			);
+		} catch {
+			/* a listener/widget failure must not strand the checkout */
+		}
 
 		// 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.
@@ -852,9 +924,15 @@ export class SubagentManager {
 
 		const key = `${run.id}:${task.id}`;
 		try {
+			// node_modules is a SHARED symlink to the leader's real tree, so dep writes
+			// escape the worktree entirely and `rm -rf node_modules/` destroys the
+			// project's deps. The child is the only thing that can avoid that.
+			const worktreeNote = wt
+				? ` You work in an isolated git worktree (branch ${wt.branch})${task.stackedOn ? `, stacked on ${task.stackedOn} (its changes are already in your tree)` : ""}. Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes. node_modules is a SHARED symlink to the main checkout: never install, upgrade, or delete dependencies (no npm/bun/yarn/pnpm install, no \`rm -rf node_modules\`) — those writes escape your worktree and damage the user's project. If the task truly needs a dependency change, edit the manifest only and say so in your answer.`
+				: "";
 			const subagentInstruction = run.allowIntercom
-				? `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${wt ? ` You work in an isolated git worktree (branch ${wt.branch}). Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes.` : ""}`
-				: `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer for the parent agent.${wt ? ` You work in an isolated git worktree (branch ${wt.branch}). Never run git commands that switch branches, create branches, or move the worktree (git switch/checkout/branch/worktree). The extension commits your changes when you finish. git status/diff are fine for inspecting your own changes.` : ""}`;
+				? `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer. You MAY use ask_parent only when truly blocked on information only the parent has; notify_parent for one-way updates; send_agent_message/poll_agent_messages to coordinate with siblings. Your mailbox address and siblings: ${task.roster ?? "(none)"}. Use the exact task ids (e.g. task_2) as send_agent_message targets. Siblings run independently and may start late or finish early — never block indefinitely on their replies: poll at most 5 times, then proceed with your best judgment. A gated sibling (marked ↳ waits in the graph) may not be running yet; do not wait for it. Stalled waits get the whole run killed. When your work is done, call notify_parent ONCE with a concise result summary — key findings, verdicts, file:line evidence — so the leader can start consuming your output before the run finishes.${worktreeNote}`
+				: `You are running as a subagent. Your bash tool already executes in the project working directory — never prefix commands with \`cd\`. Do not call subagent/delegation tools unless the parent explicitly asks. Return a concise final answer for the parent agent.${worktreeNote}`;
 
 			const loader = new DefaultResourceLoader({
 				cwd: childCwd,
@@ -932,8 +1010,10 @@ export class SubagentManager {
 					),
 			});
 
-			// auto-limit off = strip leader-imposed caps; tasks run unlimited until done.
-			const maxRuntimeMs = this.autoLimit ? (input.maxRuntimeMs ?? DEFAULT_RUNTIME_MS) : 0;
+			// auto-limit off = drop the DEFAULT ceiling, but never an explicit request:
+			// discarding the leader's own maxRuntimeMs removed the last escape from a
+			// livelocked child.
+			const maxRuntimeMs = input.maxRuntimeMs ?? (this.autoLimit ? DEFAULT_RUNTIME_MS : 0);
 			const promptPromise = child.prompt(task.task, { source: "extension" });
 			const races: Promise<unknown>[] = [promptPromise, childFailurePromise, childEndPromise, watchdog.promise];
 			if (maxRuntimeMs > 0) {
@@ -952,7 +1032,15 @@ export class SubagentManager {
 			const finalText =
 				task.finalText ||
 				truncateText((child.messages as AssistantMessage[]).map(getFirstText).filter(Boolean).at(-1) || "");
-			if (task.status !== "aborted") {
+			// TERMINAL, not just "aborted": a cancel/timeout that landed while the
+			// final text was being assembled must not be overwritten with "completed"
+			// (which would also skip the partial commit and drop the child's work).
+			// `awaiting_parent` also means the child hadn't finished talking — marking
+			// it completed would publish a truncated finalText to every dependent.
+			if (task.status === "awaiting_parent") {
+				this.pendingReplies.get(key)?.resolve("(your task is being finalized — stop work and return now)");
+			}
+			if (!TERMINAL.includes(task.status)) {
 				this.updateTask(run, task, { status: "completed", finalText, endedAt: Date.now() }, ctx, onUpdate);
 				if (wt) {
 					// Commit the child's changes, then report the branch + diff so the
@@ -1033,6 +1121,9 @@ export class SubagentManager {
 			);
 		} finally {
 			this.liveChildren.delete(key);
+			// Resolve, don't just delete: a bare delete strands the 10-minute reply
+			// timer and leaves the child's await unsettled.
+			this.pendingReplies.get(key)?.resolve("(task ended — stop work now)");
 			this.pendingReplies.delete(key);
 			abortListener?.();
 			unsubscribe?.();
@@ -1080,6 +1171,20 @@ export class SubagentManager {
 				`Provide one subagent mode: agent+task (single), tasks: [...] (parallel), or chain: [...] (sequential).`,
 			);
 		}
+		// Single-mode-only fields alongside an array mode are silently dropped
+		// otherwise: `write: true` next to tasks:[...] produced read-only children
+		// that reported they "cannot edit files", with nothing explaining why.
+		// `cwd` and `maxRuntimeMs` are meaningful run-wide (and the schema advertises
+		// maxRuntimeMs without a single-mode marker), so they FAN OUT as per-task
+		// defaults instead of being refused. The rest genuinely describe one agent.
+		if (hasChain || hasTasks) {
+			const stray = (["write", "prompt", "tools", "model", "thinking"] as const).filter((k) => params[k] !== undefined);
+			if (stray.length > 0) {
+				throw new Error(
+					`${stray.join(", ")} ${stray.length > 1 ? "describe" : "describes"} a single agent. Set ${stray.length > 1 ? "them" : "it"} on each item of ${hasChain ? "chain" : "tasks"} instead.`,
+				);
+			}
+		}
 
 		const mode: RunMode = hasChain ? "chain" : hasTasks ? "parallel" : "single";
 		const inputs: TaskInput[] = hasSingle
@@ -1096,9 +1201,12 @@ export class SubagentManager {
 						maxRuntimeMs: params.maxRuntimeMs,
 					},
 				]
-			: hasTasks
-				? params.tasks!
-				: params.chain!;
+			: (hasTasks ? params.tasks! : params.chain!).map((item) => ({
+					// Run-wide defaults; a per-task value always wins.
+					...item,
+					cwd: item.cwd ?? params.cwd,
+					maxRuntimeMs: item.maxRuntimeMs ?? params.maxRuntimeMs,
+				}));
 		if (inputs.length > MAX_TASKS) throw new Error(`Too many subagent tasks (${inputs.length}). Max is ${MAX_TASKS}.`);
 		// Task ids become git refs + filesystem paths — refuse anything unsafe.
 		// Explicit ids are checked against each other; generated ones are checked
@@ -1120,6 +1228,10 @@ export class SubagentManager {
 			}
 		}
 		const edges = resolveNeeds(inputs, mode);
+		// A new run exists, so persisting is meaningful again. Without this, a host
+		// that emits session_shutdown with no following session_start (SIGTERM, SDK
+		// reuse, tests) leaves every later persist a silent no-op.
+		this.cleared = false;
 		// Pre-flight every task's model BEFORE the run exists. A matched agent file
 		// overrides the requested model, so an unresolvable one is the leader's
 		// mistake to see NOW — not N children dying one by one on their first turn
@@ -1230,6 +1342,7 @@ export class SubagentManager {
 					run,
 					task,
 					{ ...input, task: applyUpstream(input.task, task.needs ?? [], outputs) },
+					input.task,
 					ctx,
 					signal,
 					onUpdate,
@@ -1311,6 +1424,12 @@ export class SubagentManager {
 	}
 
 	/** Branches owned by worktrees of still-running children. */
+	/** True only for checkouts THIS manager still runs — a marker carrying our own
+	 *  pid from a previous session in the same process is not proof of life. */
+	ownsWorktree = (path: string): boolean => {
+		for (const wt of this.liveWorktrees.values()) if (wt.path === path) return true;
+		return false;
+	};
 	liveBranches(): Set<string> {
 		return new Set(Array.from(this.liveWorktrees.values(), (wt) => wt.branch));
 	}

package/src/types.ts

@@ -53,6 +53,9 @@ export interface TaskSnapshot {
 	 *  changes are already in the leader's tree — always surfaced, never silent. */
 	isolation?: "worktree" | "in-place";
 	isolationReason?: string;
+	/** Upstream branch this one was built on top of. Merge that one FIRST — these
+	 *  are stacked, not independent. Absent = branched from the base tree. */
+	stackedOn?: string;
 	/** Worktree commit/diff trouble. Kept apart from `error` so a completed task
 	 *  still reports its answer. */
 	worktreeError?: string;

package/src/worktree.ts

@@ -81,8 +81,15 @@ export function repoRoot(cwd: string): string | undefined {
 	}
 }
 
-/** Create an isolated worktree for a write task. Returns undefined when not a git repo. */
-export function createWorktree(cwd: string, runId: string, taskId: string): Worktree | undefined {
+/**
+ * Create an isolated worktree for a write task. Returns undefined when not a git repo.
+ *
+ * @param baseRef Branch/SHA to start from. A chained write task MUST pass its
+ *   upstream's branch: basing on main HEAD hands the child a tree without the
+ *   upstream's edits, so it "builds on" work it cannot see and its merge reverts
+ *   the upstream.
+ */
+export function createWorktree(cwd: string, runId: string, taskId: string, baseRef?: string): Worktree | undefined {
 	const root = repoRoot(cwd);
 	if (!root) return undefined;
 	// --git-common-dir, not "<root>/.git": inside a linked worktree or a submodule
@@ -92,17 +99,30 @@ export function createWorktree(cwd: string, runId: string, taskId: string): Work
 	if (!container) return undefined;
 	let base: string;
 	try {
-		base = git(root, ["rev-parse", "HEAD"]); // SHA — detached HEAD stays correct
+		// Resolve to a SHA so a later commit on the ref can't skew the diff base.
+		base = git(root, ["rev-parse", baseRef ?? "HEAD"]);
 	} catch {
-		return undefined; // broken repo — fall back to in-place
+		if (!baseRef) return undefined; // broken repo — fall back to in-place
+		try {
+			base = git(root, ["rev-parse", "HEAD"]); // upstream branch gone — fall back to HEAD
+		} catch {
+			return undefined;
+		}
 	}
 	const path = join(container, runId, taskId);
 	const branch = `${BRANCH_PREFIX}${runId}/${taskId}`;
 	// 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.
+	// Deps follow the child into the worktree so it can build without a reinstall.
+	//
+	// ponytail: this is a SHARED symlink to the main tree's node_modules, not a
+	// copy — the cheap option, and it escapes isolation. A child that runs an
+	// install, or `rm -rf node_modules/` (trailing slash follows the link),
+	// mutates the leader's real deps outside any branch. Ceiling accepted because
+	// copying/hardlinking node_modules per worktree costs GBs per task; the
+	// upgrade path is a per-worktree install on an explicit opt-in flag.
+	// Children are warned in their system prompt (see manager.ts childPrompt).
 	const nm = join(root, "node_modules");
 	if (existsSync(nm) && !existsSync(join(path, "node_modules"))) {
 		try {
@@ -320,7 +340,7 @@ export function claimWorktree(wt: Worktree): void {
  * 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 {
+export function ownerAlive(path: string, ownedHere?: (path: string) => boolean): boolean {
 	let marker: { pid?: number; host?: string; boot?: string };
 	try {
 		marker = JSON.parse(readFileSync(ownerFile(path), "utf8"));
@@ -331,7 +351,10 @@ export function ownerAlive(path: string): boolean {
 	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;
+	// Our OWN pid is not proof: a previous session in this same long-lived process
+	// (pi `/new`) leaves markers with this pid, and trusting them made those dirs
+	// unreapable for the process lifetime. Callers pass `isLive` for real knowledge.
+	if (pid === process.pid) return ownedHere?.(path) ?? true;
 	try {
 		process.kill(pid, 0);
 		return true;