@ferris1225/pi-subagents 0.17.0 → 0.19.0

package/README.md

@@ -389,6 +389,13 @@ for `idleTimeoutSec` seconds) are treated as model-level failures and do trigger
 since a stalled SSE stream is usually a provider-side issue. Results carry a `model fell back
 from …` note when it happened.
 
+If the model is unavailable or broken and the fallback retry also fails (or no fallback model
+is available), the task is **handed back to the main window**: the completion message tells
+the main agent to execute the task itself with its own tools instead of leaving a dead
+failure. A background task that crashes with an exception (spawn infra, delivery API, ...)
+is never silently swallowed either — the user gets a `✗ … 派发失败` error notification and
+the failure is delivered to the main agent, which can re-dispatch it.
+
 Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
 
 ## Agent discovery and overrides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/background.ts

@@ -3,6 +3,10 @@
  *
  * Tasks get their own AbortSignal rather than inheriting the foreground agent
  * turn's signal. The owning extension cancels all work only on session teardown.
+ *
+ * Task exceptions are never swallowed: the per-task onError callback receives
+ * them (unless the task was cancelled) so callers can surface the failure to
+ * the user and the main agent instead of it vanishing into the queue.
  */
 
 export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
@@ -11,6 +15,9 @@ interface PendingTask {
 	task: BackgroundTask;
 	controller: AbortController;
 	onCancelled?: () => void;
+	/** Invoked when the task throws and was not cancelled (cancellation is not a
+	 * failure — e.g. session shutdown races must never be reported as errors). */
+	onError?: (error: unknown) => void;
 }
 
 export class BackgroundTaskQueue {
@@ -33,15 +40,15 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
-	enqueue(task: BackgroundTask, onCancelled?: () => void): AbortController {
+	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void): AbortController {
 		const controller = new AbortController();
 		if (this.stopped) {
 			controller.abort();
-			onCancelled?.();
+			this.runCancelled(onCancelled);
 			return controller;
 		}
 
-		this.pending.push({ task, controller, onCancelled });
+		this.pending.push({ task, controller, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
@@ -53,25 +60,47 @@ export class BackgroundTaskQueue {
 
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
-			entry.onCancelled?.();
+			this.runCancelled(entry.onCancelled);
 		}
 		for (const controller of this.active) controller.abort();
 	}
 
+	/** Cancellation callbacks are user-supplied: a throw must never break the queue
+	 * (mirrors the try/catch around onError in drain). */
+	private runCancelled(callback: (() => void) | undefined): void {
+		if (!callback) return;
+		try {
+			callback();
+		} catch {
+			/* cancellation callbacks must never break the queue */
+		}
+	}
+
 	private drain(): void {
 		while (!this.stopped && this.active.size < this.concurrency) {
 			const entry = this.pending.shift();
 			if (!entry) return;
 			if (entry.controller.signal.aborted) {
-				entry.onCancelled?.();
+				this.runCancelled(entry.onCancelled);
 				continue;
 			}
 
 			this.active.add(entry.controller);
-			void entry.task(entry.controller.signal).catch(() => undefined).finally(() => {
-				this.active.delete(entry.controller);
-				this.drain();
-			});
+			void entry.task(entry.controller.signal)
+				.catch((error: unknown) => {
+					// Cancellation is not a failure: aborted work (e.g. session
+					// shutdown) must never be reported as an exception.
+					if (entry.controller.signal.aborted) return;
+					try {
+						entry.onError?.(error);
+					} catch {
+						/* error reporting must never break the queue */
+					}
+				})
+				.finally(() => {
+					this.active.delete(entry.controller);
+					this.drain();
+				});
 		}
 	}
 }

package/src/index.ts

@@ -13,7 +13,7 @@
  */
 
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { BackgroundTaskQueue } from "./background.ts";
@@ -32,6 +32,7 @@ import {
 	currentSubagentDepth,
 	getResultOutput,
 	isFailedResult,
+	isModelLevelFailure,
 	reviewVerdict,
 	runSingleAgentWithModelFallback,
 	truncateResultOutput,
@@ -42,7 +43,19 @@ import {
 	type UsageStats,
 } from "./spawn.ts";
 import { buildFixTaskBrief, buildReReviewBrief, shouldTriggerFixLoop } from "./fixloop.ts";
-import { formatTaskSummary, formatToolActivity, monitor, statusColor, statusIcon, statusLabel, type RunChainMeta } from "./monitor.ts";
+import {
+	activityStateLabel,
+	compactModelRef,
+	deriveActivityState,
+	formatElapsed,
+	formatTaskSummary,
+	formatToolActivity,
+	monitor,
+	rightAlign,
+	statusIcon,
+	statusLabel,
+	type RunChainMeta,
+} from "./monitor.ts";
 
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
@@ -92,6 +105,21 @@ function failedStartResult(agentName: string, task: string, errorMessage: string
 		stderr: errorMessage,
 		usage: emptyUsage(),
 		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+/** Failed result for a background task that crashed with an exception (spawn
+ * infra, delivery API, ...) instead of returning a normal result. */
+function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return {
+		...queuedResult(agent, task, thinking),
+		exitCode: 1,
+		stderr: errorMessage,
+		stopReason: "error",
+		errorMessage,
+		dispatchFailed: true,
 	};
 }
 
@@ -132,7 +160,10 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number, cwd
 	const fallbackNote = result.modelFallbackFrom
 		? ` (model fell back from ${result.modelFallbackFrom} to ${result.model ?? "main-window model"})`
 		: "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", text];
+	const retryNote = result.startupRetries
+		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
+		: "";
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${retryNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", text];
 	if (truncated) {
 		// The full text lives on disk so the main agent can read it on demand.
 		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, cwd)})`);
@@ -140,6 +171,14 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number, cwd
 	return lines.join("\n");
 }
 
+/** Instruction appended to a model-level failure: the sub-agent's provider never
+ * produced usable output (or the run stalled), so the task is handed back to the
+ * main window instead of being left as a dead failure. */
+function modelLevelTakeoverNote(result: SingleResult): string {
+	const retry = result.modelFallbackFrom ? ", and the retry with the main-window model also failed" : "";
+	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${retry}. Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+}
+
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
 	// Init-time decisions need the config synchronously; the full (migrating)
@@ -260,29 +299,30 @@ export default function (pi: ExtensionAPI): void {
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob. Reviewer runs started
-			// by the main agent defer finishing so the queue task can decide between
-			// delivering the review and starting an auto-fix chain: a triggered chain
-			// keeps the parent row in the widget (annotated) until it completes and
-			// suppresses the premature "done" notification.
-			const makeLiveHandler = (runId: number, deferFinish = false) => (e: SubagentLiveEvent): void => {
+			// "read src/index.ts", ...), never a raw args blob. The live handler only
+			// updates widget status; finishing (removeRun + notify) is owned by the
+			// queue task / launchInLoop. That keeps a startup retry — which fires a
+			// transient "failed" status before relaunching — from ripping the row out
+			// early, and lets the queue task decide between delivering a reviewer's
+			// result and starting an auto-fix chain (a triggered chain keeps the
+			// parent row annotated until it completes).
+			const makeLiveHandler = (runId: number) => (e: SubagentLiveEvent): void => {
 				switch (e.kind) {
 					case "status":
-						if (e.status === "done" || e.status === "failed") {
-							// Deferred runs only update the widget; the queue task finishes
-							// them once it knows whether an auto-fix chain will follow.
-							if (deferFinish) monitor.setStatus(runId, e.status);
-							else finishRun(runId, e.status);
-						} else monitor.setStatus(runId, e.status);
+						// Only update the widget status here. Finishing (removeRun + notify) is
+						// owned by the queue task / launchInLoop so that a startup retry — which
+						// fires a transient "failed" status before relaunching the child — never
+						// rips the row out from under the retry or emits a premature "✗" toast.
+						monitor.setStatus(runId, e.status);
 						break;
 					case "usage":
 						monitor.setUsage(runId, e.usage, e.model);
 						break;
 					case "tool_start":
-						monitor.setActivity(runId, formatToolActivity(e.toolName, e.args));
+						monitor.recordToolStart(runId, e.toolName, formatToolActivity(e.toolName, e.args));
 						break;
 					case "tool_end":
-						if (e.isError) monitor.setActivity(runId, `✗ ${e.toolName} failed`);
+						monitor.recordToolEnd(runId, e.toolName, e.isError);
 						break;
 					case "thinking":
 						monitor.setActivity(runId, "thinking");
@@ -393,6 +433,7 @@ export default function (pi: ExtensionAPI): void {
 						stderr: errorMessage,
 						stopReason: signal.aborted ? "aborted" : "error",
 						errorMessage,
+						dispatchFailed: true,
 					};
 				}
 			};
@@ -438,11 +479,20 @@ export default function (pi: ExtensionAPI): void {
 						// success, a stuck one needs a human).
 						monitor.removeRun(parentRunId);
 						if (!sessionActive) return;
-						const items: CompletionMessageItem[] = chain.map((r) => ({
-							agent: r.agent,
-							block: formatCompletionBlock(r, config.maxResultLines, ctx.cwd),
-							triggerTurn: true,
-						}));
+						const items: CompletionMessageItem[] = chain.map((r) => {
+							// A model-level chain run (worker or re-review whose provider never
+							// produced output) is handed to the main window like any other
+							// sub-agent run: the block carries the takeover note. Dispatch
+							// crashes (dispatchFailed) are excluded by the gate itself.
+							const modelLevel = isFailedResult(r) && isModelLevelFailure(r);
+							return {
+								agent: r.agent,
+								block: modelLevel
+									? `${formatCompletionBlock(r, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(r)}`
+									: formatCompletionBlock(r, config.maxResultLines, ctx.cwd),
+								triggerTurn: true,
+							};
+						});
 						sendCompletionGroup(items);
 						completionBatcher.flush();
 					},
@@ -451,6 +501,30 @@ export default function (pi: ExtensionAPI): void {
 						// in-flight chain run was already finished by its launchInLoop path).
 						monitor.removeRun(parentRunId);
 					},
+					(error) => {
+						// A crash inside the chain orchestration (failed runs are caught by
+						// launchInLoop and delivered as part of the chain) must not vanish:
+						// drop the retained parent row, notify, and deliver a failed result
+						// so the main agent knows the chain never completed.
+						monitor.removeRun(parentRunId);
+						if (!sessionActive) return;
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						try {
+							ctx.ui.notify(`✗ auto-fix chain 派发失败: ${errorMessage}`, "error");
+							// Keep the triggering review's findings: the chain crashed before any
+							// fix round ran, and the main agent needs the review to act on it.
+							sendCompletionGroup([
+								{
+									agent: initialReviewerResult.agent,
+									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, ctx.cwd)}\n\nAuto-fix chain crashed before completion: ${errorMessage}. The planned fix rounds did not run; the review above is the triggering reviewer's full output.`,
+									triggerTurn: true,
+								},
+							]);
+							completionBatcher.flush();
+						} catch {
+							/* a second delivery failure must not throw through the queue */
+						}
+					},
 				);
 			};
 
@@ -464,7 +538,7 @@ export default function (pi: ExtensionAPI): void {
 				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel);
 				// Only a main-agent-dispatched reviewer can trigger an auto-fix chain, so
 				// only its finish is deferred to the queue task (see startFixLoop).
-				const onLive = makeLiveHandler(runId, agent.name === "reviewer");
+				const onLive = makeLiveHandler(runId);
 
 				backgroundQueue.enqueue(
 					async (backgroundSignal) => {
@@ -493,8 +567,11 @@ export default function (pi: ExtensionAPI): void {
 								stderr: errorMessage,
 								stopReason: backgroundSignal.aborted ? "aborted" : "error",
 								errorMessage,
+								dispatchFailed: true,
 							};
-							finishRun(runId, "failed");
+							// The dedicated dispatch-failure notification below replaces the generic
+							// failure toast for dispatch crashes, so finish silently here.
+							finishRun(runId, "failed", { silent: true });
 						}
 
 						if (!sessionActive) return;
@@ -516,13 +593,31 @@ export default function (pi: ExtensionAPI): void {
 							return;
 						}
 						const failed = isFailedResult(result);
-						finishRun(runId, failed ? "failed" : "done");
+						// Model-level failures and dispatch crashes get their own dedicated
+						// dispatch-failure notification below, so finishRun's generic failure toast is
+						// silenced for them (computed before finishRun for that reason).
+						const modelLevel = failed && isModelLevelFailure(result);
+						const dispatchFailed = result.dispatchFailed === true;
+						finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
 						if (!sessionActive) return;
+						// Model-level failure: the configured model is unavailable or broke
+						// and the retry with the main-window model (when distinct) also
+						// failed. Instead of leaving a dead failure, hand the task to the
+						// main window — the main agent executes it itself with its own tools.
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
-							block: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
+							block: modelLevel
+								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result)}`
+								: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
 							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
 						};
+						if (modelLevel) {
+							ctx.ui.notify(`✗ ${result.agent} 派发失败: 模型不可用或出错，任务已交由主窗口执行`, "error");
+						} else if (dispatchFailed) {
+							// An exception inside the dispatch layer (spawn infra, temp-file/fs
+							// errors, ...): the main agent must know so it can re-dispatch.
+							ctx.ui.notify(`✗ ${result.agent} 派发失败: ${result.errorMessage ?? "dispatch crashed"}`, "error");
+						}
 						if (failed) {
 							// Failures never wait and never hide behind a success turn: deliver
 							// first so the wake-up leads with the failure; held successes follow.
@@ -533,6 +628,28 @@ export default function (pi: ExtensionAPI): void {
 						}
 					},
 					() => finishRun(runId, "failed"),
+					(error) => {
+						// The task body converts sub-agent failures into delivered results; an
+						// exception escaping it (spawn infra, delivery API, ...) must not
+						// vanish: notify the user and deliver a failed result so the main
+						// agent knows the dispatch failed and can re-dispatch.
+						const crashed = dispatchFailedResult(agent, task, error, thinkingLevel);
+						finishRun(runId, "failed", { silent: true });
+						if (!sessionActive) return;
+						try {
+							ctx.ui.notify(`✗ ${agent.name} 派发失败: ${crashed.errorMessage}`, "error");
+							sendCompletionGroup([
+								{
+									agent: agent.name,
+									block: formatCompletionBlock(crashed, config.maxResultLines, ctx.cwd),
+									triggerTurn: true,
+								},
+							]);
+							completionBatcher.flush();
+						} catch {
+							/* a second delivery failure must not throw through the queue */
+						}
+					},
 				);
 
 				return pending;
@@ -660,20 +777,41 @@ export default function (pi: ExtensionAPI): void {
 					render(width: number): string[] {
 						const runs = monitor.getRuns();
 						if (runs.length === 0) return [];
+						const now = Date.now();
 						const lines: string[] = [];
 						for (const r of runs) {
 							const icon = statusIcon(r.status, theme);
-							const label = theme.fg(statusColor(r.status), statusLabel(r.status));
-							// Chain-internal runs (auto-fix worker/reviewer) indent under their
-							// parent reviewer; summarize() already carries the relationLabel.
+							// Chain-internal runs (auto-fix worker/reviewer) indent under their parent
+							// reviewer. For those, the relationLabel ("fix round 1") is more
+							// distinguishing than the repeated worker/reviewer name.
 							const head = r.groupId ? theme.fg("dim", "  ↳ ") : " ";
-							const note = r.annotation ? theme.fg("dim", ` · ${r.annotation}`) : "";
-							lines.push(truncateToWidth(`${head}${icon} #${r.id} ${monitor.summarize(r)} · ${label}${note}`, width, ""));
-							if (r.status === "queued" || r.status === "running") {
-								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task, Math.max(20, width - 11))}`), width, ""));
+							const name = r.groupId ? (r.relationLabel ?? r.agent) : r.agent;
+							// Inline the task's distinguishing key fragments (paths, symbols, quoted
+							// phrases) right after the agent name, so parallel runs of the SAME agent
+							// are distinguishable at a glance instead of only on a second line.
+							const title = formatTaskSummary(r.task, Math.max(16, Math.floor(width * 0.45)), true);
+							const left = `${head}${icon} ${theme.fg("dim", `#${r.id}`)} ${theme.bold(name)} ${theme.fg("dim", "›")} ${theme.fg("accent", title)}`;
+
+							// Right side: compact model (no provider prefix), tool count, elapsed,
+							// and the soft activity-state annotation (idle / long-running). Always
+							// visible — rightAlign clips the title on overflow, never this.
+							const model = compactModelRef(r.model);
+							const tools = r.toolCount ? `${r.toolCount} tool${r.toolCount === 1 ? "" : "s"}` : "";
+							const elapsed = formatElapsed(r, now);
+							const metaParts = [model, tools, elapsed].filter(Boolean);
+							// Running is conveyed by the icon + elapsed; spell out the label only for
+							// the other states (ready / done / stopped) so they are unambiguous.
+							if (r.status !== "running") metaParts.push(statusLabel(r.status));
+							const state = deriveActivityState(r, now);
+							const stateNote = state ? ` · ${activityStateLabel(state)}` : "";
+							const note = r.annotation ? ` · ${r.annotation}` : "";
+							const right = theme.fg("dim", `${metaParts.join(" · ")}${stateNote}${note}`);
+							lines.push(rightAlign(left, right, width));
+
+							// Current activity sits one indent below, only while the run is active.
+							if (r.activity && (r.status === "running" || r.status === "queued")) {
+								lines.push(rightAlign(`${head}  ${theme.fg("dim", r.activity)}`, "", width));
 							}
-							// Activity sits one indent level below the agent name.
-							if (r.activity) lines.push(truncateToWidth(theme.fg("dim", `     ${r.activity}`), width, ""));
 						}
 						return lines;
 					},

package/src/monitor.ts

@@ -12,7 +12,7 @@
 
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { UsageStats } from "./spawn.ts";
 
 // ---------------------------------------------------------------------------
@@ -21,6 +21,20 @@ import type { UsageStats } from "./spawn.ts";
 
 export type RunStatus = "queued" | "running" | "done" | "failed";
 
+/** Soft state-awareness signals, complementary to the hard idle-kill: a run may
+ * be alive (stdout streaming) yet "stuck thinking" (no tool running for a while),
+ * or simply taking a long time. Both are surfaced as widget annotations so the
+ * user can tell a healthy busy run from one that needs a nudge. */
+export type ActivityState = "needs_attention" | "active_long_running";
+
+/** A run with no tool running and no activity for this long is "needs attention"
+ * (the model may be stuck between turns). Below the idle-kill threshold so the
+ * soft signal always fires before the hard kill. */
+export const NEEDS_ATTENTION_AFTER_MS = 60_000;
+/** A run whose total elapsed time exceeds this is "long-running": still active
+ * but worth flagging so the user can decide whether to wait or steer. */
+export const ACTIVE_LONG_RUNNING_AFTER_MS = 240_000;
+
 export interface RunView {
 	id: number;
 	agent: string;
@@ -32,6 +46,14 @@ export interface RunView {
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
 	activity?: string;
+	/** Total tool calls started by the run so far (a progress signal). */
+	toolCount?: number;
+	/** Tool currently executing (set on tool_start, cleared on tool_end). When set,
+	 * the run is NOT idle for needs-attention purposes. */
+	currentTool?: string;
+	/** Epoch ms of the last live activity (tool, usage, status). Used to derive
+	 * the needs-attention state: no tool running AND now - lastActivityAt > threshold. */
+	lastActivityAt?: number;
 	/** Epoch ms when the run started executing (set on first "running" status). */
 	startedAt?: number;
 	/** Epoch ms when the run finished (set on "done"/"failed"). */
@@ -233,6 +255,47 @@ export function formatElapsed(run: RunView, now: number = Date.now()): string {
 	return formatDuration(end - run.startedAt);
 }
 
+/** Strip the provider prefix from a "provider/model-id" reference for compact
+ * widget display ("anthropic/claude-sonnet-4" → "claude-sonnet-4"). A bare id is
+ * left unchanged. */
+export function compactModelRef(model: string | undefined): string {
+	if (!model) return "";
+	const slash = model.lastIndexOf("/");
+	return slash >= 0 ? model.slice(slash + 1) : model;
+}
+
+/** Human-readable label for a soft activity-state annotation. */
+export function activityStateLabel(state: ActivityState): string {
+	return state === "needs_attention" ? "idle" : "long-running";
+}
+
+/** Derive the soft activity state of a run at render time: needs_attention
+ * (no tool running, idle past the threshold) takes priority over
+ * active_long_running (total elapsed past its threshold). Both are suppressed
+ * for non-running runs. */
+export function deriveActivityState(run: RunView, now: number = Date.now()): ActivityState | undefined {
+	if (run.status !== "running") return undefined;
+	if (!run.currentTool) {
+		const since = run.lastActivityAt ?? run.startedAt ?? now;
+		if (now - since >= NEEDS_ATTENTION_AFTER_MS) return "needs_attention";
+	}
+	if (run.startedAt !== undefined && now - run.startedAt >= ACTIVE_LONG_RUNNING_AFTER_MS) {
+		return "active_long_running";
+	}
+	return undefined;
+}
+
+/** Left/right split a widget line so the right side (status, elapsed) is always
+ * visible and the left side (title) clips on overflow instead of pushing it off.
+ * `left`/`right` may carry ANSI styling; widths are measured display-column-wise. */
+export function rightAlign(left: string, right: string, width: number): string {
+	const rightWidth = visibleWidth(right);
+	const leftMax = Math.max(0, width - rightWidth - 1);
+	const leftClipped = truncateToWidth(left, leftMax);
+	const gap = Math.max(1, width - visibleWidth(leftClipped) - rightWidth);
+	return truncateToWidth(`${leftClipped}${" ".repeat(gap)}${right}`, width);
+}
+
 /** Max length of the argument target inside a formatted activity line. */
 export const ACTIVITY_TARGET_MAX = 60;
 
@@ -337,6 +400,7 @@ export class MonitorStore {
 			// A model-fallback retry after a failed attempt restarts the clock; a
 			// stale endedAt would freeze the elapsed display at the first attempt.
 			if (run.endedAt !== undefined) run.endedAt = undefined;
+			run.lastActivityAt = Date.now();
 		} else if ((status === "done" || status === "failed") && run.endedAt === undefined) {
 			run.endedAt = Date.now();
 		}
@@ -347,6 +411,7 @@ export class MonitorStore {
 		if (!run) return;
 		run.usage = { ...usage };
 		if (model) run.model = model;
+		run.lastActivityAt = Date.now();
 		this.notify();
 	}
 
@@ -355,6 +420,31 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.activity = text;
+		run.lastActivityAt = Date.now();
+		this.notify();
+	}
+
+	/** Record a tool starting: counts it, marks it current, and updates activity.
+	 * A running tool means the run is NOT idle, so needs-attention is suppressed
+	 * while it stays current. */
+	recordToolStart(id: number, toolName: string, activity: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.toolCount = (run.toolCount ?? 0) + 1;
+		run.currentTool = toolName;
+		run.activity = activity;
+		run.lastActivityAt = Date.now();
+		this.notify();
+	}
+
+	/** Record a tool ending: clears the current-tool marker (so the run becomes
+	 * eligible for needs-attention again) and notes the failure in activity. */
+	recordToolEnd(id: number, toolName: string, isError: boolean): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.currentTool = undefined;
+		run.lastActivityAt = Date.now();
+		if (isError) run.activity = `✗ ${toolName} failed`;
 		this.notify();
 	}
 

package/src/spawn.ts

@@ -32,6 +32,15 @@ export const SUBAGENT_KILL_GRACE_MS = 5_000;
  * (idleTimeoutSec); this constant is only a fallback for tests. */
 export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
 
+/** Backoff schedule for retrying a child that exited before any model or tool
+ * activity — the signature of a concurrent pi startup race, where several
+ * sub-agents contending for pi's startup lock lose and exit with nothing on
+ * stdout. Bounded and short so persistent launch failures are not amplified
+ * while the startup lock clears. */
+export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
+/** A genuine startup race fails well before a model request can complete. */
+export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
+
 export interface UsageStats {
 	input: number;
 	output: number;
@@ -57,6 +66,14 @@ export interface SingleResult {
 	errorMessage?: string;
 	/** Model the run degraded from: set when a failed run was retried with the main-window model. */
 	modelFallbackFrom?: string;
+	/** True when the result was synthesized from a thrown exception (spawn infra,
+	 * temp-file/fs errors, delivery bugs) instead of being produced by the agent
+	 * process. A dispatch failure is never a model-level failure. */
+	dispatchFailed?: boolean;
+	/** How many times the run was relaunched after a silent, zero-activity startup
+	 * exit (a concurrent pi startup race) before it produced a result. Set only when
+	 * the run actually recovered after retrying, so callers can surface it. */
+	startupRetries?: number;
 }
 
 export interface SubagentDetails {
@@ -158,6 +175,10 @@ export function isFailedResult(result: SingleResult): boolean {
 export function isModelLevelFailure(result: SingleResult): boolean {
 	if (!isFailedResult(result)) return false;
 	if (result.stopReason === "aborted") return false;
+	// A result synthesized from a thrown exception (spawn infra, fs, delivery
+	// bugs) never came from the provider: it is a dispatch failure, not a
+	// model-level one, and must not be handed back as a model problem.
+	if (result.dispatchFailed) return false;
 	// An idle timeout (stdout went silent) signals a stalled provider connection,
 	// not a task-level failure: allow model fallback even if the model produced
 	// partial output before going quiet.
@@ -169,6 +190,73 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 	return result.messages.length > 0 || result.stderr.trim().length > 0;
 }
 
+/**
+ * True when a failed run produced NO model, tool, output, or usage activity
+ * within the startup window — the signature of a concurrent pi startup race,
+ * where the child lost pi's startup lock and exited before doing anything.
+ * Such a run is safe to relaunch: nothing was mutated and no provider call
+ * completed, so retrying cannot duplicate work.
+ *
+ * Fails closed: any final output, assistant message, usage, stderr, structured
+ * error message, idle-timeout, abort, dispatch crash, or run that outlived the
+ * startup window disqualifies the run from retry (it either did real work or
+ * carries a real error that belongs to model fallback / normal failure
+ * delivery instead). Only a clean, SILENT, fast, zero-activity exit retries.
+ */
+export function isRetryableStartupFailure(result: SingleResult, durationMs: number): boolean {
+	if (result.exitCode === 0) return false;
+	if (result.stopReason === "aborted") return false;
+	if (result.dispatchFailed) return false;
+	if (result.errorMessage?.includes("idle timeout")) return false;
+	if (getFinalOutput(result.messages)) return false;
+	if (result.messages.length > 0) return false;
+	const usage = result.usage;
+	if (usage.turns || usage.input || usage.output || usage.cacheRead || usage.cacheWrite || usage.cost) return false;
+	if (durationMs > MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS) return false;
+	// Any stderr or structured error could be a real provider/config error (auth,
+	// bad model id, quota, ...) that must not be amplified by retry. A silent
+	// zero-activity exit — no stdout, no stderr, no error message — is the race.
+	if (result.stderr.trim().length > 0) return false;
+	if (result.errorMessage && result.errorMessage.trim().length > 0) return false;
+	return true;
+}
+
+/** Error surfaced when every startup-retry attempt still exited with no
+ * activity. Tells the main agent the dispatch never reached a model and what to
+ * do (retry, or lower maxConcurrency). */
+export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child exited before any model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
+}
+
+/** Wait out a startup-retry backoff. Resolves false immediately (do not retry)
+ * when the signal is or becomes aborted during the wait, so cancellation never
+ * delays delivering the last result. The timer is unref'd so it cannot keep the
+ * event loop alive on shutdown. */
+export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
+	if (delayMs <= 0) return !signal?.aborted;
+	if (!signal) {
+		return new Promise<boolean>((resolve) => {
+			const timer = setTimeout(() => resolve(true), delayMs);
+			if (typeof timer.unref === "function") timer.unref();
+		});
+	}
+	if (signal.aborted) return false;
+	return new Promise<boolean>((resolve) => {
+		let settled = false;
+		const finish = (shouldRetry: boolean): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			resolve(shouldRetry);
+		};
+		const onAbort = (): void => finish(false);
+		const timer = setTimeout(() => finish(true), delayMs);
+		if (typeof timer.unref === "function") timer.unref();
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
 export function getResultOutput(result: SingleResult): string {
 	if (isFailedResult(result)) {
 		const error = result.errorMessage || result.stderr;
@@ -245,6 +333,10 @@ export interface RunSingleOptions {
 	/** Idle timeout in ms: terminate the child if its stdout produces no activity
 	 * for this duration. 0 (the default) disables the idle watchdog. */
 	idleTimeoutMs?: number;
+	/** Startup-retry backoff schedule (ms) for silent, zero-activity child exits
+	 * (a concurrent pi startup race). Defaults to SUBAGENT_STARTUP_RETRY_DELAYS_MS;
+	 * pass a shorter array in tests to keep them fast. */
+	startupRetryDelaysMs?: readonly number[];
 	signal?: AbortSignal;
 	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
@@ -540,22 +632,68 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 }
 
 /**
- * Run one agent; when the configured model fails at the provider level before
- * producing any output (see isModelLevelFailure), retry once with the main
- * window's current model. The retried result is returned with `modelFallbackFrom`
- * set so callers can surface the degradation. The fallback is per-run only and
- * never persisted: a transient provider hiccup must not silently downgrade the
- * configured agent model.
+ * Run one agent with two layers of resilience against transient dispatch failures:
+ *
+ * 1. Startup retry (inner loop): a concurrent pi startup race can make the child
+ *    exit before any model/tool activity. Relaunch with backoff so the startup
+ *    lock clears. The SAME model is retried — the race is in the host, not the
+ *    model — and only a clean, silent, zero-activity exit qualifies (see
+ *    isRetryableStartupFailure), so retrying can never duplicate real work.
+ * 2. Model fallback (outer): when the provider rejects the configured model
+ *    before producing output (see isModelLevelFailure), retry once with the main
+ *    window's current model. The fallback gets its own startup-retry loop, since
+ *    a startup race can hit any relaunch regardless of model.
+ *
+ * The fallback is per-run only and never persisted: a transient provider hiccup
+ * must not silently downgrade the configured agent model.
  */
 export async function runSingleAgentWithModelFallback(
 	options: RunSingleOptions,
 	fallbackModelRef?: string,
 ): Promise<SingleResult> {
-	const result = await runSingleAgent(options);
 	const agent = options.agent;
 	const launchedRef = agent?.model;
+	const delays = options.startupRetryDelaysMs ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
+
+	const runWithStartupRetry = async (opts: RunSingleOptions): Promise<SingleResult> => {
+		let lastResult: SingleResult;
+		let retries = 0;
+		for (let attempt = 0; ; attempt++) {
+			const start = Date.now();
+			lastResult = await runSingleAgent(opts);
+			const durationMs = Date.now() - start;
+			if (!isRetryableStartupFailure(lastResult, durationMs)) {
+				if (retries > 0 && !isFailedResult(lastResult)) lastResult.startupRetries = retries;
+				return lastResult;
+			}
+			const delay = delays[attempt];
+			if (delay === undefined) {
+				// Exhausted: the agent never reached a model. Surface the concurrency-race
+				// cause as a dispatch-level failure (no model was ever reached, so this
+				// must NOT trigger model fallback) so the main agent can retry or lower
+				// maxConcurrency.
+				lastResult.errorMessage = formatStartupRetryExhaustedError(
+					lastResult.model ?? opts.agent?.model ?? "default",
+					attempt + 1,
+				);
+				lastResult.stopReason ??= "error";
+				lastResult.dispatchFailed = true;
+				return lastResult;
+			}
+			// Flip the live status back to running so the widget does not flash a
+			// false "failed" while we wait out the backoff and relaunch the child.
+			try {
+				opts.onLive?.({ kind: "status", status: "running" });
+			} catch { /* never throw from event handling */ }
+			const shouldRetry = await waitForStartupRetry(delay, opts.signal);
+			if (!shouldRetry) return lastResult;
+			retries++;
+		}
+	};
+
+	const result = await runWithStartupRetry(options);
 	if (!agent || !launchedRef || !fallbackModelRef || launchedRef === fallbackModelRef) return result;
 	if (!isModelLevelFailure(result)) return result;
-	const retried = await runSingleAgent({ ...options, agent: { ...agent, model: fallbackModelRef } });
+	const retried = await runWithStartupRetry({ ...options, agent: { ...agent, model: fallbackModelRef } });
 	return { ...retried, modelFallbackFrom: launchedRef };
 }