@arhen/pi-core-subagent 1.3.38 → 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.38",
+	"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/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

@@ -57,7 +57,10 @@ 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;
+/** 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 —
@@ -248,9 +251,14 @@ export class SubagentManager {
 	private widgetTimers = new Map<string, ReturnType<typeof setTimeout>>(); // per-run stream throttle
 	private widgetRuns: RunSnapshot[] = [];
 	private eventSeq = 0;
-	/** Sidecar write ordering: unique tmp names + last-writer-wins by sequence. */
+	/** 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;
 
@@ -425,18 +433,22 @@ export class SubagentManager {
 			// 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 tmp = `${sidecar}.${process.pid}.${this.persistSeq++}.tmp`;
+			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);
-			const seq = this.persistSeq;
-			void writeFile(tmp, payload)
-				.then(async () => {
-					// Drop a snapshot that a newer persist already superseded, so a slow
-					// write can't rename stale data over fresh data.
-					if (seq < this.persistedSeq) return rm(tmp, { force: true });
+			// 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;
-					return rename(tmp, sidecar);
-				})
-				.catch(() => rm(tmp, { force: true }).catch(() => {})); // never leak a tmp, never throw
+				} catch {
+					await rm(tmp, { force: true }).catch(() => {}); // never leak a tmp, never throw
+				}
+			});
 		} catch {
 			/* ignore */
 		}
@@ -825,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
@@ -866,24 +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,
-				// 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,
-		);
+		// 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.
@@ -897,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,
@@ -977,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) {
@@ -1000,6 +1035,11 @@ export class SubagentManager {
 			// 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) {
@@ -1134,13 +1174,14 @@ export class SubagentManager {
 		// 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", "cwd", "maxRuntimeMs"] as const).filter(
-				(k) => params[k] !== undefined,
-			);
+			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 ? "are" : "is"} only read in single mode. Set ${stray.length > 1 ? "them" : "it"} on each item of ${hasChain ? "chain" : "tasks"} instead.`,
+					`${stray.join(", ")} ${stray.length > 1 ? "describe" : "describes"} a single agent. Set ${stray.length > 1 ? "them" : "it"} on each item of ${hasChain ? "chain" : "tasks"} instead.`,
 				);
 			}
 		}
@@ -1160,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
@@ -1184,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
@@ -1376,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;