pi-herdr-agents 0.0.4 → 0.1.1

package/README.md

@@ -78,12 +78,6 @@ pi
 
 herdr is the only supported terminal environment. The extension requires `HERDR_ENV=1` and the `herdr` CLI to be available.
 
-If your shell startup is slow and subagent commands sometimes get dropped before the prompt is ready, set `PI_SUBAGENT_SHELL_READY_DELAY_MS` to a higher value (defaults to `500`):
-
-```bash
-export PI_SUBAGENT_SHELL_READY_DELAY_MS=2500
-```
-
 ### Troubleshooting completion delivery
 
 If a child finishes but the parent returns an empty or unrelated response, first verify that the result reached the parent session:
@@ -314,7 +308,14 @@ exact IDs from your authenticated model catalog:
 `subagent({ agent: ... })`. Explicit `model` tool arguments take precedence,
 followed by agent frontmatter, per-agent config, the global default, and finally
 the parent model. Model values must be exact authenticated `provider/model-id`
-references.
+references. A value can contain an ordered comma-separated fallback list, for
+example `provider/preferred, provider/fallback`. The extension validates every
+candidate before launch, retries the preferred model normally, then launches
+later candidates only after a provider/agent request failure. A completed child
+result, including a negative task result, never switches models. Completion
+metadata and the status widget report the model actually used; an exhausted
+list reports every attempted model. Workflow metadata accepts one exact model
+only, to keep approved workflow runtimes deterministic.
 
 `config.json` is gitignored in the source tree so local overrides are not
 committed from a checkout. On an installed package root, treat it as disposable
@@ -356,7 +357,7 @@ subagent({
 | `agent`                | string  | —              | Load defaults from agent definition                                                               |
 | `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
-| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`; resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
+| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; unavailable for Claude CLI and worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
 | `thinking`             | string  | parent level   | Pi thinking level (`off` through `max`); omit to inherit the parent                                |
 | `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; overrides the body for Claude CLI agents, while named Pi agents keep their definition body |
 | `resumeSessionId`      | string  | —              | Claude CLI session ID to resume; separate from the Pi `subagent_resume` tool                       |
@@ -422,7 +423,7 @@ herdr_workflow({ action: "cancel", runId: "run-1" });
 
 - Cancel claims a process-global terminal gate. Completion, failure, interruption, and cancellation cannot each produce a terminal outcome.
 - Queued `agent()` calls resolve as cancelled; no later reviewer or synthesizer starts.
-- Active panes are queried through Herdr process-info before close so foreground process identities can be waited on.
+- New panes are queried through Herdr process-info until their interactive shell is ready before launch. Active panes are queried again before close so foreground process identities can be waited on.
 - After synchronous pane close, cancel waits for pane absence and captured process exit before disposing the reader checkout.
 - If process identity cannot be captured for an active pane, the pane remains present after close, or any captured process still lives after the bounded wait, the checkout is retained and the run ends `failed` with `cancel_termination_failed`. Successful cancellation is not reported in that case.
 - A successful cancel writes one `cancelled` terminal journal event and one result-free delivery. Repeated cancel is idempotent and returns the authoritative terminal outcome (including a prior fail-closed result).
@@ -683,7 +684,7 @@ and verify them with `/subagent list` plus a smoke launch.
 | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`        | string  | Optional explicit agent name used in `agent: "my-agent"`; defaults to the filename stem and must match it in role packs                                                                                                                                                                                            |
 | `description` | string  | Shown in `subagents_list` output                                                                                                                                                                                                                                            |
-| `model`       | string  | Optional exact authenticated Pi model default; omit to use per-agent config, global config, then the parent                                                                                                                                                                 |
+| `model`       | string  | Optional exact authenticated Pi model default or ordered comma-separated fallback list; omit to use per-agent config, global config, then the parent                                                                                                                       |
 | `cli`         | string  | Set to `claude` to launch the Claude CLI instead of Pi                                                                                                                                                                                                                       |
 | `cli-model`   | string  | Optional model name passed to a Claude CLI agent; separate from Pi model routing                                                                                                                                                                             |
 | `thinking`    | string  | Optional Pi thinking default (`off` through `max`); omit to inherit the parent. Thinking overrides are not supported for Claude CLI agents                                                                                                                                   |

package/docs/worktree-subagents.md

@@ -46,7 +46,7 @@ For a worktree launch:
 - Uncommitted and untracked files from the parent checkout are not copied. Commit anything the child must see before spawning it, or pass the needed context in the task.
 - Worktree creation does not steal terminal focus.
 
-`worktree` cannot be set in agent frontmatter and is not exposed by the `/subagent <agent> <task>` shorthand. It is selected per call to the `subagent` tool.
+`worktree` cannot be set in agent frontmatter and is not exposed by the `/subagent <agent> <task>` shorthand. It is selected per call to the `subagent` tool. Ordered model fallback lists are not supported for worktree subagents: a failed attempt retains its worktree and branch for review, so a retry cannot safely reuse the requested branch.
 
 ## Parent and worker responsibilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/herdr.ts

@@ -129,6 +129,10 @@ function getHerdrParentPaneId(): string {
   return paneId;
 }
 
+function buildCurrentPaneArgs(): string[] {
+	return ["pane", "current", "--current"];
+}
+
 function getHerdrCurrentPaneInfo(): {
   pane_id: string;
   tab_id: string;
@@ -141,7 +145,7 @@ function getHerdrCurrentPaneInfo(): {
   // Fall back to `herdr pane current` if any identity env var is missing —
   // older herdr versions may not set all three.
   if (!paneId || !tabId || !workspaceId) {
-    const output = herdrExec(["pane", "current"]);
+    const output = herdrExec(buildCurrentPaneArgs());
     const parsed = parseHerdrJson(output);
 		const pane = (parsed as { result?: { pane?: unknown } } | null)?.result
 			?.pane as
@@ -449,6 +453,46 @@ export function getHerdrPaneProcessInfo(surface: string): HerdrPaneProcessInfo {
 	);
 }
 
+async function getHerdrPaneProcessInfoAsync(
+	surface: string,
+): Promise<HerdrPaneProcessInfo> {
+	return parsePaneProcessInfo(
+		await herdrExecAsync(["pane", "process-info", "--pane", surface]),
+		surface,
+	);
+}
+
+function isHerdrShellReady(info: HerdrPaneProcessInfo): boolean {
+	return (
+		info.shellPid != null &&
+		info.foregroundProcessGroupId === info.shellPid
+	);
+}
+
+export async function waitForHerdrShellReady(
+	surface: string,
+	options: { timeoutMs?: number; intervalMs?: number; signal?: AbortSignal } = {},
+): Promise<void> {
+	const timeoutMs = options.timeoutMs ?? 10_000;
+	const intervalMs = options.intervalMs ?? 50;
+	const deadline = Date.now() + timeoutMs;
+	let lastError = "no interactive shell foreground process";
+
+	while (Date.now() <= deadline) {
+		if (options.signal?.aborted) throw new Error("Shell readiness wait cancelled.");
+		try {
+			if (isHerdrShellReady(await getHerdrPaneProcessInfoAsync(surface))) return;
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : String(error);
+		}
+		if (Date.now() >= deadline) break;
+		await new Promise((resolve) => setTimeout(resolve, intervalMs));
+	}
+	throw new Error(
+		`Timed out waiting for interactive shell in Herdr pane ${surface}: ${lastError}`,
+	);
+}
+
 export function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -529,6 +573,7 @@ export function renameHerdrWorkspace(title: string): void {
 }
 
 export const __herdrTest__ = {
+  buildCurrentPaneArgs,
   buildTabCreateArgs,
   buildWorktreeCreateArgs,
   parseHerdrJson,
@@ -538,4 +583,5 @@ export const __herdrTest__ = {
   parsePaneGetOutput,
   parsePaneGetError,
 	parsePaneProcessInfo,
+	isHerdrShellReady,
 };

package/pi-extension/subagents/index.ts

@@ -39,6 +39,7 @@ import {
 	readPaneAsync,
 	inspectPane,
 	getPaneProcessInfo,
+	waitForShellReady,
 	waitForPaneAbsence,
 	waitForProcessesExit,
 } from "./terminal.ts";
@@ -53,6 +54,7 @@ import {
 import {
 	buildAuthenticatedModelCatalog,
 	resolveRuntimePlan,
+	resolveRuntimePlans,
 	wrapPiModelRegistry,
 	THINKING_LEVELS,
 	isThinkingLevel,
@@ -202,7 +204,7 @@ const SubagentParams = Type.Object({
 	model: Type.Optional(
 		Type.String({
 			description:
-				"Exact authenticated provider/model-id. Omit to inherit the parent model. Select another model only when task capability, speed, cost, modality, or context requirements warrant it.",
+				"Exact authenticated provider/model-id, or an ordered comma-separated fallback list. Omit to inherit the parent model. Fallbacks are Pi-backed only and cannot be used with worktrees.",
 		}),
 	),
 	thinking: Type.Optional(ThinkingLevelSchema),
@@ -802,19 +804,6 @@ function formatElapsed(seconds: number): string {
 	return `${m}m ${s}s`;
 }
 
-/**
- * Wait long enough for a freshly created pane to finish shell startup.
- *
- * Some environments do extra shell-init work before the prompt is ready
- * (for example direnv/devenv), so the delay is configurable for users who hit
- * dropped commands. Keep the historical default at 500ms.
- */
-function getShellReadyDelayMs(): number {
-	const raw = process.env.PI_SUBAGENT_SHELL_READY_DELAY_MS?.trim();
-	const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
-	return Number.isFinite(parsed) && parsed >= 0 ? parsed : 500;
-}
-
 function muxUnavailableResult() {
 	return {
 		content: [
@@ -1147,6 +1136,7 @@ function resolveResultPresentation(
 		| "summary"
 		| "sessionFile"
 		| "errorMessage"
+		| "fallbackAttempts"
 		| "worktree"
 	>,
 	name: string,
@@ -1173,6 +1163,9 @@ function resolveResultPresentation(
 				: `Sub-agent "${name}" completed (${formatElapsed(result.elapsed)}).\n\n${result.summary}`;
 	}
 
+	if (result.fallbackAttempts && result.fallbackAttempts.length > 1) {
+		body += `\n\nModels attempted: ${result.fallbackAttempts.join(", ")}`;
+	}
 	if (result.worktree) body += `\n\n${formatWorktreeHandoff(result.worktree)}`;
 	const runtimeWarning = runtimeMismatch
 		? `\n\nRuntime warning: ${runtimeMismatch}`
@@ -1215,6 +1208,8 @@ interface SubagentResult {
 	error?: string;
 	/** Provider/agent error message when auto-retry exhausted (overload, rate limit, etc.). */
 	errorMessage?: string;
+	/** Ordered models launched for this run, including failed fallback attempts. */
+	fallbackAttempts?: string[];
 	ping?: { name: string; message: string };
 	worktree?: WorktreeHandoff;
 }
@@ -1977,7 +1972,6 @@ function buildWorkflowChildCommand(params: {
 
 export const __test__ = {
 	borderLine,
-	getShellReadyDelayMs,
 	renderSubagentWidgetLines,
 	loadAgentDefaults,
 	discoverAgentDefinitions,
@@ -2045,10 +2039,10 @@ async function launchSubagent(
 		};
 	},
 	parentThinking: ThinkingLevel,
-	options?: { surface?: string },
+	options?: { surface?: string; runtimePlan?: ResolvedRuntimePlan; id?: string },
 ): Promise<RunningSubagent> {
 	const startTime = Date.now();
-	const id = Math.random().toString(16).slice(2, 10);
+	const id = options?.id ?? Math.random().toString(16).slice(2, 10);
 
 	const agentDefs = params.agent
 		? loadAgentDefaults(params.agent, runtime.pi)
@@ -2064,19 +2058,21 @@ async function launchSubagent(
 	requireClaudeAdapter(agentDefs?.cli);
 	if (!ctx.model)
 		throw new Error("Subagent launch requires a resolved parent model");
-	const runtimePlan = resolveRuntimePlan(
-		{ model: params.model, thinking: params.thinking },
-		{
-			model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
-			thinking: agentDefs?.thinking,
-		},
-		{
-			provider: ctx.model.provider,
-			modelId: ctx.model.id,
-			thinking: parentThinking,
-		},
-		wrapPiModelRegistry(ctx.modelRegistry),
-	);
+	const runtimePlan =
+		options?.runtimePlan ??
+		resolveRuntimePlan(
+			{ model: params.model, thinking: params.thinking },
+			{
+				model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
+				thinking: agentDefs?.thinking,
+			},
+			{
+				provider: ctx.model.provider,
+				modelId: ctx.model.id,
+				thinking: parentThinking,
+			},
+			wrapPiModelRegistry(ctx.modelRegistry),
+		);
 	const effectiveModel = runtimePlan.model;
 	const effectiveTools = params.tools ?? agentDefs?.tools;
 	const effectiveSkills = params.skills ?? agentDefs?.skills;
@@ -2209,13 +2205,8 @@ async function launchSubagent(
 		});
 	}
 
-	// Use pre-created surface (parallel mode) or create a new one.
-	// For new surfaces, pause briefly so the shell is ready before sending the command.
-	if (!options?.surface) {
-		await new Promise<void>((resolve) =>
-			setTimeout(resolve, getShellReadyDelayMs()),
-		);
-	}
+	// `pane run` is safe only after the shell owns the foreground process group.
+	await waitForShellReady(surface);
 
 	const launchBehavior = resolveLaunchBehavior(params, agentDefs);
 
@@ -2484,6 +2475,67 @@ async function launchSubagent(
  * the summary from the session file, and closes ordinary panes. Worktree
  * workspaces are retained for parent review.
  */
+function resolveSubagentRuntimePlans(
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+): ResolvedRuntimePlan[] {
+	const agentDefs = params.agent
+		? loadAgentDefaults(params.agent, runtime.pi)
+		: null;
+	if (params.agent && !agentDefs) {
+		const diagnostic = discoverAgentCatalog(runtime.pi).diagnostics.find(
+			(candidate) => candidate.agentName === params.agent,
+		);
+		throw new Error(
+			diagnostic?.message ?? `Agent "${params.agent}" was not found.`,
+		);
+	}
+	if (!ctx.model) throw new Error("Subagent launch requires a resolved parent model");
+	const plans = resolveRuntimePlans(
+		{ model: params.model, thinking: params.thinking },
+		{
+			model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
+			thinking: agentDefs?.thinking,
+		},
+		{
+			provider: ctx.model.provider,
+			modelId: ctx.model.id,
+			thinking: parentThinking,
+		},
+		wrapPiModelRegistry(ctx.modelRegistry),
+	);
+	if (agentDefs?.cli === "claude" && plans.length > 1) {
+		throw new Error("Model fallbacks are supported only for Pi-backed subagents.");
+	}
+	if (params.worktree && plans.length > 1) {
+		throw new Error("Model fallbacks are not supported for worktree subagents.");
+	}
+	return plans;
+}
+
+async function launchSubagentWithFallbacks(
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+	plans: ResolvedRuntimePlan[],
+): Promise<{ running: RunningSubagent; index: number }> {
+	const failures: string[] = [];
+	for (const [index, plan] of plans.entries()) {
+		try {
+			return {
+				running: await launchSubagent(params, ctx, parentThinking, { runtimePlan: plan }),
+				index,
+			};
+		} catch (error) {
+			failures.push(`${plan.model}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	throw new Error(
+		`Subagent could not launch with any configured model. Attempted: ${plans.map((plan) => plan.model).join(", ")}. ${failures.join("; ")}`,
+	);
+}
+
 async function watchSubagent(
 	running: RunningSubagent,
 	signal: AbortSignal,
@@ -2676,6 +2728,64 @@ async function watchSubagent(
 	}
 }
 
+async function watchSubagentWithFallbacks(
+	initial: RunningSubagent,
+	initialPlanIndex: number,
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+	plans: ResolvedRuntimePlan[],
+	signal: AbortSignal,
+): Promise<{ running: RunningSubagent; result: SubagentResult }> {
+	let running = initial;
+	let nextPlan = initialPlanIndex + 1;
+	const attempts = [running.runtimePlan?.model].filter(
+		(model): model is string => !!model,
+	);
+
+	for (;;) {
+		const result = await watchSubagent(running, signal);
+		const shouldRetry = !!result.errorMessage && nextPlan < plans.length;
+		if (!shouldRetry) {
+			return { running, result: { ...result, fallbackAttempts: attempts } };
+		}
+
+		runningSubagents.delete(running.id);
+		updateWidget();
+		const launchErrors: string[] = [];
+		let launchedFallback = false;
+		while (nextPlan < plans.length) {
+			const plan = plans[nextPlan++];
+			attempts.push(plan.model);
+			try {
+				running = await launchSubagent(params, ctx, parentThinking, {
+					runtimePlan: plan,
+					id: initial.id,
+				});
+				running.abortController = initial.abortController;
+				launchedFallback = true;
+				startWidgetRefresh();
+				startStatusRefresh(runtime.pi!);
+				break;
+			} catch (error) {
+				launchErrors.push(
+					`${plan.model}: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+		}
+		if (!launchedFallback) {
+			return {
+				running,
+				result: {
+					...result,
+					errorMessage: `${result.errorMessage}\n\nFallback launch failures: ${launchErrors.join("; ")}`,
+					fallbackAttempts: attempts,
+				},
+			};
+		}
+	}
+}
+
 export default function subagentsExtension(pi: ExtensionAPI) {
 	runtime.pi = pi;
 	let btwChild: BtwChild | undefined;
@@ -2881,9 +2991,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			mkdirSync(dirname(sessionFile), { recursive: true });
 			surface = createSubagentPane(`${candidate.runId}: ${roleName}`);
 			owner.children.set(id, { controller: childController, surface });
-			await new Promise<void>((done) =>
-				setTimeout(done, getShellReadyDelayMs()),
-			);
+			await waitForShellReady(surface, { signal: childController.signal });
 			if (childController.signal.aborted)
 				return workflowFailure("cancelled", "Workflow cancelled.");
 			const command = buildWorkflowChildCommand({
@@ -3604,7 +3712,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 						`Unsupported parent thinking level: ${parentThinking}`,
 					);
 				}
-				const running = await launchSubagent(params, ctx, parentThinking);
+				const runtimePlans = resolveSubagentRuntimePlans(
+					params,
+					ctx,
+					parentThinking,
+				);
+				const { running, index: initialPlanIndex } = await launchSubagentWithFallbacks(
+					params,
+					ctx,
+					parentThinking,
+					runtimePlans,
+				);
 
 				// Create a separate AbortController for the watcher
 				// (the tool's signal completes when we return)
@@ -3616,16 +3734,24 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				startStatusRefresh(pi);
 
 				// Fire-and-forget: start watching in background
-				watchSubagent(running, watcherAbort.signal)
-					.then((result) => {
-						if (!shouldDeliverSubagentCompletion(running)) {
-							running.lifecycle = markDelivery(running.lifecycle, "suppressed");
-							runningSubagents.delete(running.id);
+				watchSubagentWithFallbacks(
+					running,
+					initialPlanIndex,
+					params,
+					ctx,
+					parentThinking,
+					runtimePlans,
+					watcherAbort.signal,
+				)
+					.then(({ running: completedRunning, result }) => {
+						if (!shouldDeliverSubagentCompletion(completedRunning)) {
+							completedRunning.lifecycle = markDelivery(completedRunning.lifecycle, "suppressed");
+							runningSubagents.delete(completedRunning.id);
 							updateWidget();
 							return;
 						}
-						running.lifecycle = markDelivery(running.lifecycle, "delivered");
-						runningSubagents.delete(running.id);
+						completedRunning.lifecycle = markDelivery(completedRunning.lifecycle, "delivered");
+						runningSubagents.delete(completedRunning.id);
 						updateWidget();
 						const completionApi = selectCompletionApi(pi, runtime.pi);
 
@@ -3655,26 +3781,29 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 						const presentation = resolveResultPresentation(
 							result,
-							running.name,
-							running.runtimePlan?.runtimeMismatch,
+							completedRunning.name,
+							completedRunning.runtimePlan?.runtimeMismatch,
 						);
 
 						sendSubagentResult(completionApi, presentation, {
-							name: running.name,
-							task: running.task,
-							agent: running.agent,
+							name: completedRunning.name,
+							task: completedRunning.task,
+							agent: completedRunning.agent,
 							exitCode: result.exitCode,
 							elapsed: result.elapsed,
 							sessionFile: result.sessionFile,
 							...(result.errorMessage
 								? { errorMessage: result.errorMessage }
 								: {}),
+							...(result.fallbackAttempts
+								? { fallbackAttempts: result.fallbackAttempts }
+								: {}),
 							...(result.claudeSessionId
 								? { claudeSessionId: result.claudeSessionId }
 								: {}),
 							...(result.worktree ? { worktree: result.worktree } : {}),
-							...(running.runtimePlan
-								? { runtimePlan: running.runtimePlan }
+							...(completedRunning.runtimePlan
+								? { runtimePlan: completedRunning.runtimePlan }
 								: {}),
 						});
 					})
@@ -4033,9 +4162,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				const entryCountBefore = getNewEntries(params.sessionPath, 0).length;
 
 				const surface = createSubagentPane(name);
-				await new Promise<void>((resolve) =>
-					setTimeout(resolve, getShellReadyDelayMs()),
-				);
+				await waitForShellReady(surface);
 
 				// Build pi resume command
 				const parts = ["pi", "--session", shellQuote(params.sessionPath)];
@@ -4269,9 +4396,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 				sessionFile = createBtwSessionSnapshot(parentSessionFile, leafId);
 				surface = createSubagentPane("BTW");
-				await new Promise<void>((resolve) =>
-					setTimeout(resolve, getShellReadyDelayMs()),
-				);
+				await waitForShellReady(surface);
 
 				const artifactDir = getArtifactDir(
 					ctx.sessionManager.getSessionDir(),

package/pi-extension/subagents/runtime-routing.ts

@@ -190,6 +190,16 @@ function selectField(
   return { source: "parent" };
 }
 
+export function parseModelFallbacks(reference: string): string[] {
+  const candidates = reference.split(",").map((candidate) => candidate.trim());
+  if (candidates.some((candidate) => candidate === "")) {
+    throw new RuntimeResolutionError(
+      `model fallback list ${JSON.stringify(reference)} cannot contain an empty candidate`,
+    );
+  }
+  return candidates;
+}
+
 export function resolveRuntimePlan(
   request: RuntimeRequest,
   agentDefaults: RuntimeRequest,
@@ -272,6 +282,30 @@ export function resolveRuntimePlan(
   };
 }
 
+/** Resolve every configured fallback before launching the first child. */
+export function resolveRuntimePlans(
+  request: RuntimeRequest,
+  agentDefaults: RuntimeRequest,
+  parent: ParentRuntime,
+  registry: ModelRegistryAdapter,
+): ResolvedRuntimePlan[] {
+  const selection = selectField(request.model, agentDefaults.model);
+  if (!selection.value) {
+    return [resolveRuntimePlan(request, agentDefaults, parent, registry)];
+  }
+
+  return parseModelFallbacks(selection.value).map((model) =>
+    resolveRuntimePlan(
+      selection.source === "request" ? { ...request, model } : { ...request, model: undefined },
+      selection.source === "agent"
+        ? { ...agentDefaults, model }
+        : agentDefaults,
+      parent,
+      registry,
+    ),
+  );
+}
+
 function formatTokenCount(value: number | undefined): string | undefined {
   if (!value || value <= 0) return undefined;
   if (value >= 1_000_000) return `${Number((value / 1_000_000).toFixed(1))}m`;

package/pi-extension/subagents/terminal.ts

@@ -7,6 +7,7 @@ import {
   createHerdrSurfaceSplit,
   createHerdrWorktree,
 	getHerdrPaneProcessInfo,
+	waitForHerdrShellReady,
   isHerdrAvailable,
 	isProcessAlive,
   readHerdrScreen,
@@ -152,6 +153,14 @@ export function getPaneProcessInfo(paneId: PaneId): HerdrPaneProcessInfo {
 	return getHerdrPaneProcessInfo(paneId);
 }
 
+export async function waitForShellReady(
+	paneId: PaneId,
+	options?: { timeoutMs?: number; intervalMs?: number; signal?: AbortSignal },
+): Promise<void> {
+	assertTerminalAvailable();
+	return waitForHerdrShellReady(paneId, options);
+}
+
 export async function waitForPaneAbsence(
 	paneId: PaneId,
 	options?: { timeoutMs?: number; intervalMs?: number },