Class PiSubagentRunner

packages/pi-plugin/src/subagent-runner.ts:360–1056

 *   the core contract.
 */
export class PiSubagentRunner implements SubagentRunner {
	readonly harness = "pi";

	/**
	 * How to invoke a Pi subagent (command + fixed leading args + shell flag).
	 * Resolved once at construction in the host process so `process.argv[1]`
	 * points at the host `cli.js`. See {@link resolvePiInvocation} for the
	 * cross-platform order; an explicit `options.piBinary` overrides it (test
	 * seam + advanced users who point at their own pi build).
	 */
	private readonly invocation: PiInvocation;
	private readonly spawnImpl: typeof childProcess.spawn;
	private readonly platform: NodeJS.Platform;

	constructor(
		options: {
			piBinary?: string;
			platform?: NodeJS.Platform;
			/** Test seam for subprocess lifecycle tests. Production uses child_process.spawn. */
			spawnImpl?: typeof childProcess.spawn;
		} = {},
	) {
		this.invocation = options.piBinary
			? { command: options.piBinary, prefixArgs: [] }
			: resolvePiInvocation();
		this.spawnImpl = options.spawnImpl ?? childProcess.spawn;
		this.platform = options.platform ?? process.platform;
	}

	async run(options: SubagentRunOptions): Promise<SubagentRunResult> {
		const models = [options.model, ...(options.fallbackModels ?? [])].filter(
			(model): model is string => typeof model === "string" && model.length > 0,
		);
		const attempts = models.length > 0 ? models : [undefined];
		let lastResult: SubagentRunResult | null = null;
		for (let index = 0; index < attempts.length; index += 1) {
			const model = attempts[index];
			const attemptOptions = {
				...options,
				model,
				fallbackModels: undefined,
			};
			const result = await this.runOnce(attemptOptions);
			if (result.ok) return result;
			lastResult = result;
			if (index >= attempts.length - 1 || !isFallbackEligible(result.reason)) {
				return result;
			}
		}
		return (
			lastResult ?? this.runOnce({ ...options, fallbackModels: undefined })
		);
	}

	private async runOnce(
		options: SubagentRunOptions,
	): Promise<SubagentRunResult> {
		const startTime = Date.now();