@ferris1225/pi-subagents 4.1.1 → 4.1.2

package/src/runtime.ts

@@ -58,9 +58,9 @@ export interface SubagentThread {
 	state: ThreadState;
 	control: RpcRunControl;
 	queueController?: AbortController;
-	/** Resolves only after the current generation's queue work has fully
-	 * quiesced and released its concurrency slot. Auto-fix orchestration is part
-	 * of the parent generation and replaces/extends this promise. */
+	/** Resolves only after the current generation's top-level child, downstream
+	 * managed workflow, and queue work have fully quiesced and released their
+	 * concurrency slot. */
 	generationCompletion: Promise<void>;
 	/** Synchronous CAS used by lifecycle controls across their async preflight. */
 	lifecycleVersion: number;
@@ -81,7 +81,8 @@ export interface SubagentThread {
 	fork: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
 	forkedFromRunId?: number;
 	forkChildRunIds: number[];
-	/** Dispatch-owned, generation-guarded worktree settlement hook. */
+	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
+	 * runs under the canonical original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;
 	/** Best-effort shutdown notification for retained integration artifacts. */
 	notifyIsolationFailure?: (finalization: WorktreeFinalization) => void;
@@ -110,7 +111,7 @@ export interface SubagentRuntime {
 	 * next generation. Shutdown invalidates these claims and waits for cleanup. */
 	preflightOperations: Set<Promise<void>>;
 	/** Every session directory retained for this parent session, including
-	 * auto-fix internals that are not directly controllable. */
+	 * managed-workflow internals that are not directly controllable. */
 	sessionDirs: Set<string>;
 	retainSession: (result: Pick<SingleResult, "sessionDir">) => void;
 	retireThreadSession: (thread: SubagentThread) => void;
@@ -134,8 +135,8 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			// Computing this at delivery (emit) time — not when the item was
 			// pushed — reflects the current monitor state, since finishing runs
 			// are removed from the monitor before their completion is pushed.
-			// Auto-fix parents are flipped back to "running" while their chain
-			// owns the logical run, so they are included without a special case.
+			// Managed-workflow parents remain "running" through documenter,
+			// reviewer, and any fix rounds, so they are included without a special case.
 			const active = monitor
 				.getRuns()
 				.filter((run) => isRunActiveStatus(run.status))

package/src/setup.ts

@@ -14,6 +14,7 @@ import {
 	AGENT_SCOPE_VALUES,
 	BUILTIN_AGENT_NAMES,
 	CLEANER_DEFAULTED_FEATURE,
+	DOCUMENTER_DEFAULTED_FEATURE,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
 	DEFAULT_IDLE_TIMEOUT_SEC,
@@ -61,7 +62,8 @@ function actualAgentThinkingDefault(
 const MODULE_HINTS: Record<string, string> = {
 	explorer: "read-only codebase recon (fast model)",
 	worker: "implement / fix / refactor / test (full tools)",
-	cleaner: "prove and apply safe cleanup cuts (full tools)",
+	cleaner: "apply proven cleanup and deduplicate code (full tools)",
+	documenter: "sync diff or whole-codebase comments/docs (full tools)",
 	reviewer: "read-only audits and pre-commit gates",
 };
 
@@ -303,7 +305,7 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	if (maxConcurrency === undefined) return notifyCancelled(ctx);
 	const maxFixRounds = await pickCount(
 		ctx,
-		"Reviewer auto-fix rounds? (0 = main agent handles fixes)",
+		"Reviewer worker-fix rounds? (0 = no automatic fixes)",
 		FIX_ROUNDS_STEPS,
 		base.maxFixRounds,
 		DEFAULT_MAX_FIX_ROUNDS,
@@ -330,9 +332,13 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		maxConcurrency,
 		maxFixRounds,
 		idleTimeoutSec,
-		// Full setup is an explicit decision point: mark the cleaner
-		// default-enable upgrade as processed so the saved list is kept as-is.
-		announcedFeatures: [...new Set([...base.announcedFeatures, CLEANER_DEFAULTED_FEATURE])],
+		// Full setup is an explicit decision point: mark role-enable migrations as
+		// processed so the user's saved selection is kept as-is.
+		announcedFeatures: [...new Set([
+			...base.announcedFeatures,
+			CLEANER_DEFAULTED_FEATURE,
+			DOCUMENTER_DEFAULTED_FEATURE,
+		])],
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured with Auto thinking. Saved to ${configPath}`, "info");
@@ -346,7 +352,7 @@ async function updateRuntimeSetting(
 		"Proactive injection",
 		"Agent scope",
 		"Max concurrency",
-		"Reviewer auto-fix rounds",
+		"Reviewer worker-fix rounds",
 		"Idle timeout",
 	]);
 	if (choice === undefined) return undefined;
@@ -364,7 +370,7 @@ async function updateRuntimeSetting(
 		if (value === undefined) return undefined;
 		next.maxConcurrency = value;
 	} else if (choice.startsWith("Reviewer")) {
-		const value = await pickCount(ctx, "Reviewer auto-fix rounds?", FIX_ROUNDS_STEPS, config.maxFixRounds, DEFAULT_MAX_FIX_ROUNDS);
+		const value = await pickCount(ctx, "Reviewer worker-fix rounds?", FIX_ROUNDS_STEPS, config.maxFixRounds, DEFAULT_MAX_FIX_ROUNDS);
 		if (value === undefined) return undefined;
 		next.maxFixRounds = value;
 	} else {
@@ -405,6 +411,17 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 				next.agentThinkingLevels.cleaner = config.agentThinkingLevels.reviewer;
 			}
 		}
+		// Documenter intentionally follows the faster explorer route. Fresh
+		// installs leave it unselected; enabling it later inherits any explorer
+		// overrides instead of silently choosing a stronger model.
+		if (!config.enabledAgents.includes("documenter") && enabled.includes("documenter")) {
+			if (!next.agentModels.documenter && config.agentModels.explorer) {
+				next.agentModels.documenter = config.agentModels.explorer;
+			}
+			if (!next.agentThinkingLevels.documenter && config.agentThinkingLevels.explorer) {
+				next.agentThinkingLevels.documenter = config.agentThinkingLevels.explorer;
+			}
+		}
 		next.agentModels = keepAgentEntries(next.agentModels, enabled);
 		next.agentThinkingLevels = keepAgentEntries(next.agentThinkingLevels, enabled);
 	} else if (choice.startsWith("Configure")) {

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,