@ferris1225/pi-subagents 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.18.0",
+  "version": "0.20.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/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";
@@ -43,7 +43,20 @@ 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,
+	formatUsageCompact,
+	monitor,
+	rightAlign,
+	statusIcon,
+	statusLabel,
+	type RunChainMeta,
+} from "./monitor.ts";
 
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
@@ -136,6 +149,7 @@ function formatUsage(usage: UsageStats): string {
 	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
 	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
 	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
 	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
 	return parts.join(" ");
 }
@@ -148,7 +162,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)})`);
@@ -284,29 +301,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");
@@ -522,7 +540,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) => {
@@ -553,7 +571,7 @@ export default function (pi: ExtensionAPI): void {
 								errorMessage,
 								dispatchFailed: true,
 							};
-							// The dedicated 派发失败 notification below replaces the generic
+							// The dedicated dispatch-failure notification below replaces the generic
 							// failure toast for dispatch crashes, so finish silently here.
 							finishRun(runId, "failed", { silent: true });
 						}
@@ -578,7 +596,7 @@ export default function (pi: ExtensionAPI): void {
 						}
 						const failed = isFailedResult(result);
 						// Model-level failures and dispatch crashes get their own dedicated
-						// 派发失败 notification below, so finishRun's generic failure toast is
+						// 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;
@@ -761,20 +779,47 @@ 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;
+							// Header row stays short: icon, run id, agent name — the task summary
+							// (keys-only fragments: paths, symbols, quoted phrases) gets its own
+							// line below with a full width budget, so parallel runs of the SAME
+							// agent are still distinguishable at a glance.
+							const title = formatTaskSummary(r.task, Math.max(16, Math.floor(width * 0.65)), true);
+							const left = `${head}${icon} ${theme.fg("dim", `#${r.id}`)} ${theme.bold(name)}`;
+
+							// Right side: compact model (no provider prefix), token usage (in/out +
+							// cache read/write), 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 usage = formatUsageCompact(r.usage);
+							const tools = r.toolCount ? `${r.toolCount} tool${r.toolCount === 1 ? "" : "s"}` : "";
+							const elapsed = formatElapsed(r, now);
+							const metaParts = [model, usage, 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));
+
+							// Task summary sits one indent below the header, on its own line.
+							lines.push(rightAlign(`${head}  ${theme.fg("accent", title)}`, "", 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"). */
@@ -212,6 +234,7 @@ export function formatUsageCompact(usage: UsageStats): string {
 	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
 	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
 	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
 	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
 	return parts.join(" ");
 }
@@ -233,6 +256,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 +401,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 +412,7 @@ export class MonitorStore {
 		if (!run) return;
 		run.usage = { ...usage };
 		if (model) run.model = model;
+		run.lastActivityAt = Date.now();
 		this.notify();
 	}
 
@@ -355,6 +421,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;
@@ -61,6 +70,10 @@ export interface SingleResult {
 	 * 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 {
@@ -177,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;
@@ -253,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;
@@ -548,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 };
 }