@ferris1225/pi-subagents 4.1.1 → 4.1.3

package/src/spawn.ts

@@ -49,8 +49,23 @@ export type { SubagentLiveEvent, UsageStats };
 export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
 /** 0 disables the watchdog; dispatch supplies the configured timeout. */
 export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
-export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
+/** Base delays cover Pi's stale-lock window and leave headroom beyond the
+ * default four-way launch fan-out. Additive jitter below reduces the chance
+ * that contenders retry in the same lockstep waves. */
+export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500, 3000, 6000] as const;
 export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
+export const MAX_SUBAGENT_STARTUP_RETRY_JITTER_MS = 1000;
+
+function normalizeStartupRetryDelay(delayMs: number): number {
+	return Number.isFinite(delayMs) && delayMs > 0 ? delayMs : 0;
+}
+
+export function addStartupRetryJitter(delayMs: number, randomValue = Math.random()): number {
+	const baseDelay = Math.floor(normalizeStartupRetryDelay(delayMs));
+	if (baseDelay === 0) return 0;
+	const boundedRandom = Number.isFinite(randomValue) ? Math.max(0, Math.min(1, randomValue)) : 0;
+	return baseDelay + Math.floor(Math.min(baseDelay, MAX_SUBAGENT_STARTUP_RETRY_JITTER_MS) * boundedRandom);
+}
 
 export interface SingleResult extends RpcSingleResult {}
 
@@ -204,10 +219,17 @@ export function isModelLevelFailure(result: SingleResult): boolean {
 	if (result.stopReason === "aborted") return false;
 	if (result.dispatchFailed) return false;
 	if (result.rpcStartupFailed) return false;
+	// A negative RPC response proves Pi rejected the prompt before execution. It
+	// remains safe to hand off even though dispatch was attempted; local write,
+	// close, timeout, and lost-ACK failures never set this explicit flag.
+	if (result.rpcPromptRejected) return true;
+	// The prompt write completed but its ACK never arrived. With no later activity
+	// we cannot know whether Pi started the model or tools, so neither startup
+	// retry nor selected→main fallback may replay this objective.
+	if (result.rpcPromptDispatched && !result.rpcPromptAccepted && !result.rpcActivity) return false;
 	if (isRpcCommandTimeoutError(result.errorMessage)) return false;
 	if (result.integrationStatus === "retained") return false;
 	if (result.errorMessage?.includes("idle timeout")) return true;
-	if (result.rpcPromptRejected) return true;
 
 	// Classification belongs to the final assistant turn, not the whole attempt.
 	// Earlier useful text or failed tool calls are retained session history and
@@ -236,7 +258,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 	if (result.exitCode === 0) return false;
 	if (result.stopReason === "aborted") return false;
 	if (result.dispatchFailed) return false;
-	if (result.rpcPromptAccepted || result.rpcActivity) return false;
+	if (result.rpcPromptDispatched || result.rpcPromptAccepted || result.rpcActivity) return false;
 	if (result.errorMessage?.includes("idle timeout")) return false;
 	if (getFinalOutput(result.messages)) return false;
 	if (result.messages.length > 0) return false;
@@ -250,14 +272,15 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child never accepted its initial RPC prompt or produced 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.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no 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.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
-	if (delayMs <= 0) return !signal?.aborted;
+	const normalizedDelay = normalizeStartupRetryDelay(delayMs);
+	if (normalizedDelay === 0) return !signal?.aborted;
 	if (!signal) {
 		return new Promise<boolean>((resolve) => {
-			const timer = setTimeout(() => resolve(true), delayMs);
+			const timer = setTimeout(() => resolve(true), normalizedDelay);
 			if (typeof timer.unref === "function") timer.unref();
 		});
 	}
@@ -272,7 +295,7 @@ export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal)
 			resolve(shouldRetry);
 		};
 		const onAbort = (): void => finish(false);
-		const timer = setTimeout(() => finish(true), delayMs);
+		const timer = setTimeout(() => finish(true), normalizedDelay);
 		if (typeof timer.unref === "function") timer.unref();
 		signal.addEventListener("abort", onAbort, { once: true });
 	});
@@ -283,7 +306,7 @@ async function waitForControlledRetry(
 	signal: AbortSignal | undefined,
 	control: RpcRunControl | undefined,
 ): Promise<boolean> {
-	let remaining = delayMs;
+	let remaining = normalizeStartupRetryDelay(delayMs);
 	while (remaining > 0) {
 		if (control?.isParkRequested() || control?.isStopRequested()) return false;
 		const slice = Math.min(remaining, 50);
@@ -304,7 +327,7 @@ export function getResultOutput(result: SingleResult): string {
 }
 
 export function buildResumePrompt(task: string, reason: string): string {
-	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Original task: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
+	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Current objective: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
 }
 
 export function buildFallbackResumeReason(fromModel?: string): string {
@@ -328,6 +351,9 @@ export interface RunSingleOptions {
 	sessionId?: string;
 	/** Initial RPC prompt. Kept under the old name to limit caller churn. */
 	stdinText?: string;
+	/** Refresh parent-derived tools immediately before every startup retry and
+	 * selected-to-main fallback process is spawned. */
+	resolveAgentForAttempt?: (agent: AgentConfig) => AgentConfig;
 	signal?: AbortSignal;
 	onLive?: (event: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
@@ -368,6 +394,15 @@ function controlledDisposition(options: RunSingleOptions, base?: SingleResult):
 	return result;
 }
 
+function signalAbortDisposition(options: RunSingleOptions, base: SingleResult): SingleResult | undefined {
+	if (!options.signal?.aborted) return undefined;
+	base.parked = undefined;
+	base.exitCode = 1;
+	base.stopReason = "aborted";
+	base.errorMessage = "Subagent was aborted";
+	return base;
+}
+
 /** Spawn one RPC attempt and wait for stable settlement. */
 export async function runSingleAgent(options: RunSingleOptions): Promise<SingleResult> {
 	const {
@@ -420,7 +455,8 @@ export async function runSingleAgentWithMainFallback(
 ): Promise<SingleResult> {
 	const agent = options.agent;
 	const launchedRef = agent?.model;
-	const startupDelays = options.startupRetryDelaysMs ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
+	const customStartupDelays = options.startupRetryDelaysMs;
+	const startupDelays = customStartupDelays ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
 
 	const sessionId = options.sessionId ?? randomUUID();
 	const sessionDir = options.sessionDir ?? (await mkdtemp(join(tmpdir(), "pi-subagent-session-")));
@@ -463,7 +499,10 @@ export async function runSingleAgentWithMainFallback(
 			}
 			const start = Date.now();
 			try {
-				lastResult = await runSingleAgent(opts);
+				const attemptOptions = opts.resolveAgentForAttempt
+					? { ...opts, agent: opts.resolveAgentForAttempt(opts.agent) }
+					: opts;
+				lastResult = await runSingleAgent(attemptOptions);
 			} catch (error) {
 				const failed = await dispatchFailure(error);
 				return controlledDisposition(opts, failed) ?? failed;
@@ -492,8 +531,9 @@ export async function runSingleAgentWithMainFallback(
 			} catch {
 				/* never throw from event handling */
 			}
-			if (!(await waitForControlledRetry(delay, opts.signal, opts.control))) {
-				return controlledDisposition(opts, lastResult) ?? lastResult;
+			const retryDelay = customStartupDelays ? delay : addStartupRetryJitter(delay);
+			if (!(await waitForControlledRetry(retryDelay, opts.signal, opts.control))) {
+				return controlledDisposition(opts, lastResult) ?? signalAbortDisposition(opts, lastResult) ?? lastResult;
 			}
 			retries++;
 		}