@ferris1225/pi-subagents 4.0.1 → 4.1.2

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);
@@ -368,6 +391,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 +452,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-")));
@@ -492,8 +525,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++;
 		}

package/src/thread-lifecycle.ts

@@ -1,16 +1,17 @@
 /**
  * Stable logical-thread generation lifecycle for background sub-agents.
  *
- * Dispatch owns the public tool contract and auto-fix policy; this module owns
- * one thread generation end to end: worktree setup/finalization, queue/process
- * ownership, retained-session resume/fork, and guarded terminal publication.
+ * Dispatch owns workflow policy and internal role briefs; this module owns one
+ * stable parent generation end to end: managed-repository lane use,
+ * worktree setup/finalization after downstream review, queue/process ownership,
+ * retained-session resume/fork, and guarded one-time terminal publication.
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { resolve } from "node:path";
-import { discoverAgents, type AgentConfig } from "./agents.ts";
+import { discoverAgents, isWriteCapableAgent, type AgentConfig } from "./agents.ts";
 import { completionTriggersTurn, type CompletionMessageItem } from "./completion.ts";
 import {
 	DEFAULT_THINKING_LEVEL,
@@ -25,7 +26,15 @@ import {
 	modelLevelTakeoverNote,
 	queuedResult,
 } from "./format.ts";
-import { shouldTriggerFixLoop } from "./fixloop.ts";
+import {
+	canStartManagedWorkflow,
+	formatChainSummary,
+	formatManagedWorkflowSummary,
+	getManagedWorkflowPlan,
+	workflowAgentAvailability,
+	type ManagedWorkflowOutcome,
+	type ManagedWorkflowPlan,
+} from "./fixloop.ts";
 import {
 	availableModelsInScope,
 	currentModelRef,
@@ -34,15 +43,17 @@ import {
 	resolveAgentModelRoute,
 	resolveThinkingLevel,
 } from "./models.ts";
-import { monitor } from "./monitor.ts";
+import { monitor, sumUsage } from "./monitor.ts";
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
 import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
 import { forkRetainedSession } from "./session-fork.ts";
 import {
 	buildResumePrompt,
+	getResultOutput,
 	RpcRunControl,
 	isFailedResult,
 	isModelLevelFailure,
+	reviewVerdict,
 	runSingleAgentWithMainFallback,
 	type SingleResult,
 	type SubagentDetails,
@@ -61,7 +72,7 @@ export const FORK_CONTINUATION_PROMPT =
 const WORKTREE_ISOLATION_INSTRUCTIONS =
 	"You are running in a temporary detached Git worktree. Work only in the current cwd; do not create another worktree or manually copy/apply changes to the original checkout. The parent dispatcher will integrate your tracked, deleted, and untracked changes when this thread finally settles.";
 
-function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
+export function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
 	return {
 		...agent,
 		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\n${WORKTREE_ISOLATION_INSTRUCTIONS}`.trim(),
@@ -69,10 +80,7 @@ function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
 }
 
 export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
-	if (agent.name === "explorer" || agent.name === "reviewer") return false;
-	if (agent.name === "worker") return true;
-	if (!agent.tools) return true;
-	return agent.tools.includes("edit") || agent.tools.includes("write");
+	return isWriteCapableAgent(agent);
 }
 
 interface DispatchEnvironment {
@@ -116,6 +124,23 @@ export function resolveDispatchModelRoute(
 	};
 }
 
+export interface ManagedWorkflowRequest extends DispatchEnvironment {
+	plan: ManagedWorkflowPlan;
+	initialResult: SingleResult;
+	groupId: string;
+	parentRunId: number;
+	executionCwd: string;
+	projectCwd: string;
+	isolation: IsolationMode;
+	signal: AbortSignal;
+	rememberLatest: (result: SingleResult) => void;
+}
+
+interface ManagedRepositoryLaneRunner {
+	<T>(cwd: string, task: () => Promise<T>): Promise<T>;
+	<T>(cwd: string, task: () => Promise<T>, signal: AbortSignal): Promise<T | undefined>;
+}
+
 interface BackgroundDispatcherOptions extends DispatchEnvironment {
 	runtime: SubagentRuntime;
 	finishRun: (
@@ -131,12 +156,8 @@ interface BackgroundDispatcherOptions extends DispatchEnvironment {
 		mode: "single" | "parallel",
 		background?: boolean,
 	) => (results: SingleResult[]) => SubagentDetails;
-	startFixLoop: (
-		initialReviewerResult: SingleResult,
-		parentGroupId: string,
-		parentRunId: number,
-		executionCwd: string,
-	) => void;
+	runManagedWorkflow: (request: ManagedWorkflowRequest) => Promise<ManagedWorkflowOutcome>;
+	runInManagedRepositoryLane: ManagedRepositoryLaneRunner;
 }
 
 type BackgroundStarter = (
@@ -155,7 +176,8 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		finishRun,
 		makeLiveHandler,
 		makeDetails,
-		startFixLoop,
+		runManagedWorkflow,
+		runInManagedRepositoryLane,
 	} = options;
 	interface SessionSeed {
 		sessionId?: string;
@@ -221,7 +243,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
-				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker or cleaner.`),
+				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker, cleaner, or documenter.`),
 				isolation,
 			};
 		}
@@ -365,13 +387,22 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				"error",
 			);
 		};
+		const generationWorktree = worktree;
+		let generationFinalization: Promise<WorktreeFinalization> | undefined;
 		thread.finalizeIsolation = async (
 			expectedGeneration: number,
 			result?: SingleResult,
 		): Promise<WorktreeFinalization | undefined> => {
-			if (thread.isolation !== "worktree" || !thread.worktree) return undefined;
-			if (thread.generation !== expectedGeneration) return undefined;
-			const finalization = await thread.worktree.finalize();
+			if (thread.isolation !== "worktree" || !generationWorktree) return undefined;
+			if (thread.generation !== expectedGeneration || thread.worktree !== generationWorktree) return undefined;
+			// All normal, destructive-stop, and shutdown owners converge here. Cache
+			// the lane-protected apply itself so superseding lifecycle paths can project
+			// the same finalization onto their own result without acquiring twice.
+			generationFinalization ??= runInManagedRepositoryLane(
+				generationWorktree.originalRoot,
+				() => generationWorktree.finalize(),
+			);
+			const finalization = await generationFinalization;
 			monitor.setIsolation(runId, "worktree", finalization.status);
 			if (result) {
 				result.runId = runId;
@@ -498,8 +529,8 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					runtime.backgroundQueue.cancel(controller);
 				} else {
 					await thread.control.park();
-					// Auto-fix orchestration has no live RPC attempt once its parent
-					// review settled, so cancel its queue owner explicitly.
+					// A managed downstream child does not attach to the top-level RPC
+					// control after that child settles, so cancel its queue owner explicitly.
 					if (phase === "settled") runtime.backgroundQueue.cancel(controller);
 				}
 				await completion;
@@ -835,8 +866,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		};
 
 		const onLive = makeLiveHandler(runId, generation);
-		const queueController = runtime.backgroundQueue.enqueue(
-			async (backgroundSignal) => {
+		const workflowAvailability = workflowAgentAvailability(runAgents);
+		const reserveManagedLane =
+			isolation === "shared" && canStartManagedWorkflow(agent, workflowAvailability);
+		const runGeneration = async (backgroundSignal: AbortSignal): Promise<void> => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				let result: SingleResult;
 				try {
@@ -887,8 +920,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				result.isolation = isolation;
 				result.forkedFromRunId = thread.forkedFromRunId;
 				result.forkChildRunIds = [...thread.forkChildRunIds];
-				thread.queueController = undefined;
-				runtime.runControllers.delete(runId);
 				thread.task = result.task;
 				thread.sessionId = result.sessionId;
 				thread.sessionDir = result.sessionDir;
@@ -897,6 +928,11 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				monitor.setModel(runId, result.model, result.modelFallbackFrom);
 				monitor.setThinking(runId, result.thinking);
 
+				const lifecycleInterrupted = (): boolean =>
+					thread.lifecycleOperation === "park" ||
+					thread.lifecycleOperation === "stop" ||
+					thread.state === "parked" ||
+					thread.state === "stopped";
 				// Destructive stop owns publication once it has synchronously claimed
 				// the lifecycle. Leave the partial result/session on the thread; the
 				// stop path waits for this queue task, finalizes isolation, and emits
@@ -909,17 +945,68 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					runtime.settledRuns.delete(runId);
 					return;
 				}
+				// A park/shutdown can win in the microtask gap after the top-level RPC
+				// settles. Do not launch an obsolete documenter/reviewer or replace the
+				// stable top-level session with an aborted downstream attempt.
+				if (backgroundSignal.aborted || lifecycleInterrupted() || !runtime.sessionActive) return;
 
 				if (thread.retireOnSettle) runtime.retireThreadSession(thread);
-				const wantsFixLoop = shouldTriggerFixLoop(result, runConfig);
-				if (wantsFixLoop && isolation === "shared" && runtime.sessionActive) {
+				let workflowOutcome: ManagedWorkflowOutcome | undefined;
+				const workflowPlan = getManagedWorkflowPlan(result, runConfig, workflowAvailability);
+				if (workflowPlan && runtime.sessionActive) {
 					thread.state = "running";
-					// The review being done does not mean the logical run is over:
-					// the same row now represents the chain until it resolves.
+					// The stable parent row remains active until every internal writer and
+					// reviewer settles. Internal rows are independently queryable but never
+					// enter this top-level lifecycle or publish completions.
 					monitor.setStatus(runId, "running");
-					monitor.setActivity(runId, "auto-fix chain running");
-					startFixLoop(result, `fix-${runId}`, runId, thread.executionCwd);
-					return;
+					monitor.setActivity(
+						runId,
+						workflowPlan.kind === "auto-fix" ? "auto-fix chain running" : "managed workflow running",
+					);
+					workflowOutcome = await runManagedWorkflow({
+						plan: workflowPlan,
+						initialResult: result,
+						groupId: `workflow-${runId}`,
+						parentRunId: runId,
+						executionCwd: thread.executionCwd,
+						projectCwd: originalCwd,
+						isolation,
+						signal: backgroundSignal,
+						ctx: runCtx,
+						config: runConfig,
+						agents: runAgents,
+						rememberLatest: (latest) => {
+							if (runtime.threads.get(runId) !== thread || thread.generation !== generation) return;
+							thread.lastResult = latest;
+							thread.agentName = latest.agent;
+							monitor.setAgent(runId, latest.agent);
+							thread.task = latest.task;
+							thread.sessionId = latest.sessionId;
+							thread.sessionDir = latest.sessionDir;
+							runtime.retainSession(latest);
+						},
+					});
+
+					// Park/stop/shutdown owns this generation once it cancels the queue
+					// signal. The newest internal partial is already on thread.lastResult;
+					// never replace it with the old top-level result or publish stale output.
+					if (backgroundSignal.aborted || lifecycleInterrupted() || !runtime.sessionActive) return;
+
+					const finalStep = workflowOutcome.steps[workflowOutcome.steps.length - 1]!;
+					result = {
+						...finalStep.result,
+						runId,
+						projectCwd: originalCwd,
+						isolation,
+						forkedFromRunId: thread.forkedFromRunId,
+						forkChildRunIds: [...thread.forkChildRunIds],
+					};
+					thread.lastResult = result;
+					thread.agentName = result.agent;
+					thread.task = result.task;
+					thread.sessionId = result.sessionId;
+					thread.sessionDir = result.sessionDir;
+					runtime.retainSession(result);
 				}
 				// Claim terminal settlement synchronously before the first slow await.
 				// Park therefore either wins while RPC is still active, or is rejected
@@ -934,12 +1021,20 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					thread.lifecycleOperation === "settle" &&
 					!thread.retired;
 				try {
-					// Worktree isolation is rejected for reviewers, the only role that can
-					// trigger auto-fix. Keep that invariant explicit: an isolated result is
-					// finalized once here and can never start a chain that would integrate
-					// the same worktree early.
+					// For isolated writers this is deliberately after the managed documenter
+					// and reviewer stages: every child sees the same worktree, then one
+					// lifecycle owner integrates the complete writer+docs state exactly once.
 					await thread.finalizeIsolation(generation, result);
 					if (!ownsSettlement()) return;
+					if (workflowOutcome && isolation === "worktree") {
+						for (const step of workflowOutcome.steps) {
+							step.result.integrationStatus = result.integrationStatus;
+							step.result.integrationApplied = result.integrationApplied;
+							step.result.integrationError = result.integrationError;
+							step.result.integrationWorktreePath = result.integrationWorktreePath;
+							step.result.integrationPatchPath = result.integrationPatchPath;
+						}
+					}
 
 					const failed = isFailedResult(result);
 					thread.state = failed ? "failed" : "completed";
@@ -950,8 +1045,39 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 
 					const modelLevel = failed && isModelLevelFailure(result);
 					const dispatchFailed = result.dispatchFailed === true;
-					finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
+					const ownedController = thread.queueController;
+					if (runtime.runControllers.get(runId) === ownedController) runtime.runControllers.delete(runId);
+					thread.queueController = undefined;
+					finishRun(
+						runId,
+						failed ? "failed" : "done",
+						workflowOutcome || modelLevel || dispatchFailed ? { silent: true } : undefined,
+					);
 					runtime.registerRunResult(runId, result);
+
+					if (workflowOutcome) {
+						const lastStep = workflowOutcome.steps[workflowOutcome.steps.length - 1]!;
+						let block = workflowOutcome.kind === "auto-fix"
+							? formatChainSummary(workflowOutcome.steps, result)
+							: formatManagedWorkflowSummary(workflowOutcome.steps, result);
+						const finalVerdict = lastStep.result.agent === "reviewer"
+							? reviewVerdict(getResultOutput(lastStep.result))
+							: undefined;
+						const needsFullFinal = failed || (lastStep.result.agent === "reviewer" && finalVerdict !== "pass");
+						if (needsFullFinal) {
+							block += `\n\n${formatCompletionBlock(result, runConfig.maxResultLines, originalCwd)}`;
+						}
+						if (modelLevel) block += `\n\n${modelLevelTakeoverNote(result, { runId })}`;
+						runtime.sendCompletionGroup([{
+							agent: `${workflowOutcome.kind === "auto-fix" ? "auto-fix chain" : "managed workflow"} (${result.agent})`,
+							block,
+							triggerTurn: true,
+							usage: sumUsage(workflowOutcome.steps.map((step) => step.result.usage)),
+						}]);
+						runtime.completionBatcher.flush();
+						return;
+					}
+
 					const completion: CompletionMessageItem = {
 						agent: result.agent,
 						block: modelLevel
@@ -975,7 +1101,18 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				} finally {
 					if (ownsSettlement()) thread.lifecycleOperation = undefined;
 				}
-			},
+			};
+		const queuedGeneration = reserveManagedLane
+			? async (backgroundSignal: AbortSignal): Promise<void> => {
+				await runInManagedRepositoryLane(
+					originalCwd,
+					() => runGeneration(backgroundSignal),
+					backgroundSignal,
+				);
+			}
+			: runGeneration;
+		const queueController = runtime.backgroundQueue.enqueue(
+			queuedGeneration,
 			() => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				// Queued park/stop owns publication and may still be finalizing an
@@ -1011,12 +1148,29 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					thread.lifecycleOperation === "settle" &&
 					!thread.retired;
 				try {
-					const crashed: SingleResult = {
-						...dispatchFailedResult(route.agent, control.getObjective(), error, thinkingLevel),
-						runId,
-						isolation,
-						forkedFromRunId: thread.forkedFromRunId,
-					};
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					const latest = thread.lastResult;
+					const crashed: SingleResult = latest
+						? {
+							...latest,
+							runId,
+							projectCwd: originalCwd,
+							isolation,
+							exitCode: 1,
+							stopReason: "error",
+							errorMessage: `Managed workflow dispatch failed: ${errorMessage}`,
+							dispatchFailed: true,
+							forkedFromRunId: thread.forkedFromRunId,
+						}
+						: {
+							...dispatchFailedResult(route.agent, control.getObjective(), error, thinkingLevel),
+							runId,
+							projectCwd: originalCwd,
+							isolation,
+							forkedFromRunId: thread.forkedFromRunId,
+						};
+					thread.lastResult = crashed;
+					runtime.retainSession(crashed);
 					await thread.finalizeIsolation(generation, crashed);
 					if (!ownsSettlement()) return;
 					thread.state = "failed";
@@ -1027,10 +1181,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					thread.queueController = undefined;
 					if (!runtime.sessionActive || !ownsSettlement()) return;
 					try {
-						runCtx.ui.notify(`✗ ${agent.name} dispatch failed: ${crashed.errorMessage}`, "error");
+						runCtx.ui.notify(`✗ ${crashed.agent} dispatch failed: ${crashed.errorMessage}`, "error");
 						runtime.sendCompletionGroup([
 							{
-								agent: agent.name,
+								agent: crashed.agent,
 								block: formatCompletionBlock(crashed, runConfig.maxResultLines, crashed.projectCwd ?? originalCwd),
 								triggerTurn: true,
 								usage: crashed.usage,

package/src/tools.ts

@@ -60,16 +60,17 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 		label: "Subagent Control",
 		description: [
 			"Control an existing sub-agent thread by stable run id.",
-			"steer queues an instruction after the current child tool batch.",
-			"retarget aborts the current objective to a stable checkpoint, suppresses that aborted completion, then starts the replacement objective in the same session.",
+			"steer queues an instruction after the current tool batch while the top-level RPC child is active.",
+			"retarget replaces the objective in that same active top-level child.",
+			"Managed downstream documenter/reviewer/fix stages are controlled by the parent queue rather than its settled RPC control: use park or stop there, then resume with an objective to redirect retained context.",
 			"park aborts to a stable checkpoint, terminates the child, preserves context, and releases its concurrency slot.",
 			"resume restarts a parked, completed, or failed retained thread with the same run id; objective is optional.",
 			"fork copies a parked/completed/failed retained session branch into a new logical thread and run id; an isolated checkpoint must be settled and integrated first; objective is optional.",
 		].join(" "),
-		promptSnippet: "Control a subagent thread: steer, retarget, park, resume, or fork by stable run id.",
+		promptSnippet: "Control a subagent thread: steer/retarget an active top-level child; park/stop a managed downstream stage; resume or fork retained context.",
 		promptGuidelines: [
-			"Use subagent_control steer to refine active work without restarting it; the instruction is delivered after the child's current tool batch.",
-			"Use subagent_control retarget when the active objective is obsolete; do not call subagent_stop and start a fresh thread because retarget preserves context and suppresses the abandoned completion.",
+			"Use subagent_control steer to refine an active top-level RPC child without restarting it; the instruction is delivered after its current tool batch.",
+			"Use subagent_control retarget only while that top-level child is active. During a managed downstream stage, park it and resume with a replacement objective instead.",
 			"Use subagent_control park to checkpoint useful context while releasing the process/concurrency slot, and resume to continue the same run id later.",
 			"Use subagent_control fork only on a parked or settled retained thread; isolated work must settle and integrate before it can fork. Fork creates a new run id while leaving the source untouched.",
 			"Use subagent_stop only for destructive cancellation; it retires that thread's retained session without retiring independent forks.",
@@ -409,6 +410,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				if (active) {
 					const parked = active.status === "parked";
 					const activeThread = runtime.threads.get(active.id);
+					const managedDownstream =
+						activeThread?.state === "running" && activeThread.control.getPhase() === "settled";
 					const metadata = [
 						activeThread?.isolation === "worktree" ? `worktree ${active.integrationStatus ?? activeThread.worktree?.state ?? "active"}` : undefined,
 						activeThread?.forkedFromRunId !== undefined ? `forked from #${activeThread.forkedFromRunId}` : undefined,
@@ -420,7 +423,9 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 								type: "text",
 								text: parked
 									? `Run #${active.id} ${active.agent} is parked with retained context${metadata ? ` (${metadata})` : ""}. Use subagent_control resume to restart it, or subagent_stop to retire it.`
-									: `Run #${active.id} ${active.agent} is still active (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait to block for its result, subagent_control to steer/park it, or subagent_stop to cancel it.`,
+									: managedDownstream
+										? `Run #${active.id} ${active.agent} is in a managed downstream stage (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait for its result, subagent_control park to checkpoint it, or subagent_stop to cancel it. Steer/retarget are unavailable until you park and resume the retained stage.`
+										: `Run #${active.id} ${active.agent} is still active (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait to block for its result, subagent_control to steer/park it, or subagent_stop to cancel it.`,
 							},
 						],
 						details: {},
@@ -617,9 +622,19 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				});
 			}
 
+			// Interrupt every claimed generation before awaiting any one of them.
+			// An isolated stop may need the repository lane for final integration;
+			// cancelling all holders first prevents stop-all from waiting behind a
+			// later shared workflow that this same operation has not interrupted yet.
+			const interruptionPromises = claimed.map(({ thread, stopMessage, controller }) => {
+				const stopping = thread.control.stop(stopMessage).catch(() => undefined);
+				runtime.backgroundQueue.cancel(controller);
+				return stopping;
+			});
+
 			const stopped: string[] = [];
 			const retainedIntegration: string[] = [];
-			for (const claim of claimed) {
+			for (const [claimIndex, claim] of claimed.entries()) {
 				const {
 					runId,
 					thread,
@@ -634,8 +649,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					stopVersion,
 					stopMessage,
 				} = claim;
-				await thread.control.stop(stopMessage).catch(() => undefined);
-				runtime.backgroundQueue.cancel(controller);
+				await interruptionPromises[claimIndex];
 				await completion;
 				if (runtime.runControllers.get(runId) === controller) runtime.runControllers.delete(runId);
 				if (thread.queueController === controller) thread.queueController = undefined;

package/src/widget.ts

@@ -93,8 +93,8 @@ function runActivityLine(run: RunView, theme: Theme, width: number, indent: stri
 	return [truncateToWidth(`${indent}${dim(activitySummary)}`, width, "")];
 }
 
-/** Render active runs as a tree: main-agent dispatches are roots, auto-fix chain
- * rounds nest under the triggering reviewer row that owns the chain. No run ids
+/** Render active runs as a tree: main-agent dispatches are roots and managed
+ * documenter/reviewer/fix steps nest under the stable parent row. No run ids
  * appear here — the tree and the task label say what each row is, and ids stay
  * available through subagent_status when a thread must be controlled. */
 export function formatActiveRunLines(
@@ -120,8 +120,8 @@ export function formatActiveRunLines(
 	for (const root of roots) {
 		const children = childrenOf.get(root.id) ?? [];
 		lines.push(runPrimaryLine(root, theme, width, now, ""));
-		// The parent's "auto-fix chain running" placeholder is redundant while its
-		// child rows show live progress; keep it only between rounds.
+		// The parent's managed-workflow placeholder is redundant while a child
+		// row shows live progress; keep it only between stages.
 		if (children.length === 0) lines.push(...runActivityLine(root, theme, width, "  "));
 		children.forEach((child, index) => {
 			const connector = index === children.length - 1 ? "└ " : "├ ";