@arhen/pi-core-subagent 1.3.40 → 1.3.42

package/package.json

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

@@ -1,5 +1,5 @@
 /**
- * Child-session tools + watchdog.
+ * Child-session tools.
  *
  * When `allowIntercom: true`, children get four talk tools:
  *   - ask_parent            blocking Q&A with the leader (parent)
@@ -107,49 +107,3 @@ export function createChildTools(taskId: string, handlers: ChildHandlers): ToolD
 		},
 	];
 }
-
-/**
- * Watchdog — a subagent is "stalled" when it produces no events for stallMs.
- * In-process AgentSessions have no process-exit signal, so we synthesize one
- * via event-heartbeat. Every relevant child event must call touch().
- */
-export interface Watchdog {
-	touch(): void;
-	readonly promise: Promise<never>;
-	dispose(): void;
-}
-
-export function createWatchdog(stallMs: number, label: string): Watchdog {
-	let lastEventAt = Date.now();
-	let disposed = false;
-	let timer: ReturnType<typeof setInterval> | undefined;
-
-	const promise = new Promise<never>((_, reject) => {
-		const interval = Math.max(1000, Math.min(5000, Math.floor(stallMs / 4)));
-		timer = setInterval(() => {
-			if (disposed) return;
-			if (Date.now() - lastEventAt > stallMs) {
-				disposed = true;
-				if (timer) clearInterval(timer);
-				timer = undefined;
-				reject(new Error(`${label} stalled: no activity for ${Math.round(stallMs / 1000)}s`));
-			}
-		}, interval);
-		timer.unref?.();
-	});
-
-	return {
-		touch() {
-			lastEventAt = Date.now();
-		},
-		promise,
-		dispose() {
-			if (disposed) return;
-			disposed = true;
-			if (timer) {
-				clearInterval(timer);
-				timer = undefined;
-			}
-		},
-	};
-}

package/src/format.ts

@@ -250,6 +250,11 @@ export function makeSummary(run: RunSnapshot): string {
 	return truncateText(lines.join("\n"));
 }
 /** Per-task notice: one task's outcome, small. Full output stays out of parent context. */
+/** Dead on arrival: failed without ever producing assistant text — model/plan/auth/agent-file
+ *  level, so every respawn with the same config fails identically. */
+export function isStartupFailure(task: TaskSnapshot, kind: string): boolean {
+	return kind === "failed" && !task.finalText?.trim();
+}
 export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: string): string {
 	const goal = truncateText(task.task, 120);
 	const detail = task.error ? task.error : truncateText(task.finalText || "(no output)", 200);
@@ -263,7 +268,9 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 	return [
 		`Task ${task.agent} (${task.id}) ${kind} in run ${run.id}: ${detail}${wt}`,
 		`Goal: ${goal}${src}`,
-		`Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
+		isStartupFailure(task, kind)
+			? "Never started — stop and diagnose before spawning anything else: a config-level error (model, plan, auth, agent file) fails identically on every respawn."
+			: `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`,
 	].join("\n");
 }
 /** Notification: 3 lines max. Full output stays out of parent context. */

package/src/index.ts

@@ -157,7 +157,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you. Set autoAwait:true when you need the result before your next step — the call parks until the run finishes and returns runId + final result in one response. allowIntercom:true lets children talk to you and each other.",
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Write agents run in an isolated git worktree: on completion the result reports the branch + changed files — review, then merge with `git merge --no-ff <branch>` (merged branches are cleaned automatically). Every run is background: the call returns a runId immediately and completion notifies you — do NOT park waiting on it. If you have no other work, end your turn; the completion notice wakes you with the results. Set autoAwait:true only when the very next step in the SAME turn consumes the result. allowIntercom:true lets children talk to you and each other.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -167,8 +167,11 @@ export default function (pi: ExtensionAPI) {
 			"End each task with a runnable check, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's claim of success is not evidence.",
 			"For write agents (write:true) in a git repo, the child works in an isolated worktree and its changes are committed to a branch — the result reports branch + changed files. Review the diff, then merge with `git merge --no-ff <branch>`; merged branches are cleaned up automatically. Never leave a worktree branch unmerged at the end of the task.",
 			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents` — project first, then home) whose `description` matches the spawn goal (name + task) takes over: its body is the system prompt, frontmatter `model`/`tools` apply and are validated against the model registry. Matching is by description, not name — name the agent whatever fits the goal.",
-			"When you need a run's result before your next step, spawn with autoAwait:true — the call returns runId + final result in one response. Otherwise spawn background and settle results (await_subagent / subagent_result) before continuing dependent work.",
-			"For long multi-task runs, don't autoAwait the whole run: spawn background, then loop await_subagent with short timeoutMs slices (e.g. 20s), processing whichever tasks completed in each slice while the rest keep running. You get incremental results instead of one big wait.",
+			"Right after a background spawn, call subagent_status(runId) ONCE before any other work — confirm each task is running (or already progressing), not stuck queued or failed at startup. A child that dies on spawn otherwise stays invisible until far later.",
+			"If that first status shows a task failed or never started, fix or respawn immediately; do not move on assuming it runs.",
+			"Never block with nothing to do: if you have no work left after spawning, end your turn. Task completion notifies you and wakes a fresh turn with the results — await_subagent/autoAwait in that situation only burns time and tokens.",
+			"autoAwait:true only when the same turn must consume the result immediately (e.g. you spawn a reviewer and then must act on its verdict before replying). Otherwise spawn background and read results from the completion notice, or subagent_result when you come back.",
+			"await_subagent is for the rare case where you have parallel work of your own and need to sync at a specific point — not the default follow-up to a spawn.",
 			"allowIntercom:true only when a child may need to ask you something.",
 		],
 		parameters: SubagentParams,
@@ -218,7 +221,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / subagent_cancel.`,
 					},
 				],
 				details,
@@ -300,8 +303,11 @@ export default function (pi: ExtensionAPI) {
 		name: "subagent_status",
 		label: "Subagent Status",
 		description:
-			"Live status of a subagent run (non-blocking): per-task state, plus each child's session file path (JSONL) so you can tail it from outside — e.g. in a terminal multiplexer pane.",
-		promptSnippet: "Check progress of a subagent run.",
+			"Live status of a subagent run (non-blocking): per-task state, plus each child's session file path (JSONL) so you can tail it from outside — e.g. in a terminal multiplexer pane. Call this once right after spawning to verify the children actually started.",
+		promptSnippet: "Check progress of a subagent run; use right after spawn as a health check.",
+		promptGuidelines: [
+			"Health-check every background spawn with one subagent_status(runId) before continuing — catch dead-on-arrival children early instead of at completion time.",
+		],
 		parameters: RunIdParam,
 		async execute(_id, params) {
 			const { runId } = params as { runId: string };
@@ -348,7 +354,10 @@ export default function (pi: ExtensionAPI) {
 		name: "await_subagent",
 		label: "Await Subagent",
 		description:
-			"Block until a run finishes (or timeoutMs elapses). While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive INSIDE the result — the await doubles as the run's intercom drain, no steering queue involved.",
+			"Block until a run finishes (or timeoutMs elapses). Use ONLY when you have work of your own to sync with; if you have nothing else to do, end your turn instead — completion notifies you and wakes a new turn with the results. While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive INSIDE the result.",
+		promptGuidelines: [
+			"Do not call await_subagent right after spawning with no other work pending — end the turn and let the completion notice wake you.",
+		],
 		parameters: AwaitParam,
 		async execute(_id, params) {
 			const { runId, timeoutMs } = params as { runId: string; timeoutMs?: number };

package/src/manager.ts

@@ -17,7 +17,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
 import { resolveAgentFile } from "./agentfile.ts";
-import { CHILD_TALK_TOOLS, type ChildHandlers, createChildTools, createWatchdog, type Watchdog } from "./child.ts";
+import { CHILD_TALK_TOOLS, type ChildHandlers, createChildTools } from "./child.ts";
 import {
 	activitySnippet,
 	describeCall,
@@ -25,6 +25,7 @@ import {
 	isTalking,
 	makeNotice,
 	makeTaskNotice,
+	isStartupFailure,
 	SubagentsWidget,
 	truncateText,
 } from "./format.ts";
@@ -56,19 +57,20 @@ 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. */
-/** 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. */
+/**
+ * Hard wall-clock ceiling per child — the ONLY liveness bound.
+ *
+ * There used to be a second one, an event-heartbeat "stall" watchdog. It was
+ * deleted: it was armed before the child session even existed, so the only
+ * window it could fire in was a slow startup (where firing is always wrong),
+ * and once events flowed it could never fire at all. Every observed firing
+ * across three releases was a false kill. A wedged child that emits events was
+ * always bounded by this cap alone; nothing else changed by removing it.
+ */
 const DEFAULT_RUNTIME_MS = 3_600_000; // 1 h
 /** "Unlimited" still has a ceiling — an unbounded child pins hasActiveRun() and
  *  its concurrency slot for the life of the session. */
 const UNLIMITED_RUNTIME_MS = 21_600_000; // 6 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,7 +246,7 @@ export class SubagentManager {
 	private pendingReplies = new Map<string, PendingReply>();
 	private liveChildren = new Map<
 		string,
-		{ abort: () => void; dispose: () => void; touchWatchdog: () => void; steer: (message: string) => void }
+		{ abort: () => void; dispose: () => void; steer: (message: string) => void }
 	>();
 	private mailboxes: Mailbox = createMailbox();
 	/** Live worktrees by `${runId}:${taskId}` — lets cancel drop dirs and keeps
@@ -461,7 +463,16 @@ export class SubagentManager {
 		this.pi.events.emit(type, { type, timestamp: Date.now(), ...payload });
 	}
 
-	/** Per-task wake-up: queued follow-up so the parent can interleave responses. */
+	/** Only startup failures are forced: they're dead-on-arrival and the leader must
+	 *  notice before it respawns the same broken config. Completed/aborted and even
+	 *  mid-run failures wait for the turn's end (followUp) — they're not urgent and
+	 *  steering every one of them would interrupt the leader mid-tool-call.
+	 *  force = deliver immediately even while streaming (steer). */
+	private deliverMode(kind: string, task: TaskSnapshot): "steer" | "followUp" {
+		return isStartupFailure(task, kind) ? "steer" : "followUp";
+	}
+
+	/** Per-task wake-up: failures steer in immediately, the rest queue as follow-up. */
 	private notifyTask(run: RunSnapshot, task: TaskSnapshot, kind: "completed" | "failed" | "aborted"): void {
 		const body = makeTaskNotice(run, task, kind);
 		// Parked leader (await_subagent) receives completions through the wait — no queue.
@@ -470,7 +481,7 @@ export class SubagentManager {
 			return;
 		}
 		try {
-			this.pi.sendUserMessage(body, { deliverAs: "followUp" });
+			this.pi.sendUserMessage(body, { deliverAs: this.deliverMode(kind, task) });
 		} catch {
 			/* parent mid-stream; consumers can poll subagent_status */
 		}
@@ -478,8 +489,8 @@ export class SubagentManager {
 	}
 
 	/** Wake the parent with a 3-line notice. Full text stays out of context.
-	 *  deliverAs followUp queues the message if the parent is mid-stream
-	 *  (e.g. inside await_subagent) instead of throwing/aborting. */
+	 *  deliverAs queues the message if the parent is mid-stream (e.g. inside
+	 *  await_subagent) instead of throwing/aborting. */
 	private notifyParent(
 		run: RunSnapshot,
 		kind: "completed" | "failed" | "aborted" | "asked",
@@ -598,7 +609,6 @@ export class SubagentManager {
 	private makeChildHandlers(run: RunSnapshot, task: TaskSnapshot, ctx: ExtensionContext): ChildHandlers {
 		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.
@@ -606,7 +616,6 @@ export class SubagentManager {
 					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
 				// (no steering queue, no turn boundary); otherwise it goes out as a notice.
 				// Either way the pending reply entry must exist, or reply_subagent has
@@ -614,24 +623,17 @@ export class SubagentManager {
 				if (!this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
 					this.notifyParent(run, "asked", { taskId: task.id, question });
 				}
-				// A waiting child is not stalled — keep the watchdog fed until the reply.
-				// But the wait is BOUNDED: an unanswered question would otherwise keep the
-				// run non-terminal forever (widget never clears, run never settles).
-				const keepAlive = setInterval(() => this.liveChildren.get(key)?.touchWatchdog(), 30_000);
-				try {
-					const reply = await this.awaitParentReply(run.id, task.id, 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;
-				} finally {
-					clearInterval(keepAlive);
+				// The wait is BOUNDED: an unanswered question would otherwise keep the run
+				// non-terminal forever (widget never clears, run never settles).
+				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);
+				return reply;
 			},
 			onNotifyParent: (_taskId, message, level) => {
 				this.emit("subagent:intercom", { runId: run.id, taskId: task.id, kind: "notify", level, message });
@@ -709,14 +711,8 @@ export class SubagentManager {
 		task: TaskSnapshot,
 		ctx: ExtensionContext,
 		onUpdate: ((partial: any) => void) | undefined,
-		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" ||
@@ -922,7 +918,6 @@ export class SubagentManager {
 		let unsubscribe: (() => void) | undefined;
 		let timeout: ReturnType<typeof setTimeout> | undefined;
 		let abortListener: (() => void) | undefined;
-		const watchdog = createWatchdog(DEFAULT_STALL_MS, `Subagent ${task.agent}`);
 		const childState: ChildEventState = {};
 
 		const key = `${run.id}:${task.id}`;
@@ -981,7 +976,7 @@ export class SubagentManager {
 			});
 
 			unsubscribe = child.subscribe((event: AgentSessionEvent) =>
-				this.onChildEvent(event, run, task, ctx, onUpdate, watchdog, childState),
+				this.onChildEvent(event, run, task, ctx, onUpdate, childState),
 			);
 
 			const abortChild = () => {
@@ -1002,8 +997,7 @@ export class SubagentManager {
 			}
 			this.liveChildren.set(key, {
 				abort: () => void child?.abort(),
-				dispose: () => watchdog.dispose(),
-				touchWatchdog: () => watchdog.touch(),
+				dispose: () => child?.dispose(),
 				// Inject a steering message mid-run; queues as steer if the child is streaming.
 				steer: (message) =>
 					void child?.prompt(message, { streamingBehavior: "steer" }).catch((err) =>
@@ -1014,12 +1008,11 @@ export class SubagentManager {
 			});
 
 			// The ceiling is the ONLY bound on a child that emits events forever (retry
-			// or tool-call livelock): the stall watchdog is touched by every event and
-			// cannot fire for one. So auto-limit off RAISES it, never removes it —
+			// or tool-call livelock). So auto-limit off RAISES it, never removes it —
 			// removing it reproduced the immortal-child hang.
 			const maxRuntimeMs = input.maxRuntimeMs ?? (this.autoLimit ? DEFAULT_RUNTIME_MS : UNLIMITED_RUNTIME_MS);
 			const promptPromise = child.prompt(task.task, { source: "extension" });
-			const races: Promise<unknown>[] = [promptPromise, childFailurePromise, childEndPromise, watchdog.promise];
+			const races: Promise<unknown>[] = [promptPromise, childFailurePromise, childEndPromise];
 			if (maxRuntimeMs > 0) {
 				races.push(
 					new Promise<never>((_, reject) => {
@@ -1140,7 +1133,6 @@ export class SubagentManager {
 			this.pendingReplies.delete(key);
 			abortListener?.();
 			unsubscribe?.();
-			watchdog.dispose();
 			if (timeout) clearTimeout(timeout);
 			child?.dispose();
 			// Failed/aborted: let the aborted child's last writes land (its tools may