@ferris1225/pi-subagents 4.1.4 → 4.1.6

package/src/dispatch.ts

@@ -1,8 +1,9 @@
 /**
  * The `subagent` tool: dispatches explorer/worker/cleaner/documenter/reviewer agents as isolated pi
  * child processes, single or parallel. Owns the public dispatch contract,
- * per-run status tracking, managed writer → reviewer → documenter workflows,
- * bounded worker/reviewer fix rounds, and internal step launching. Stable
+ * per-run status tracking, managed worker/cleaner → reviewer workflows with a
+ * conditional documenter, bounded worker/reviewer fix rounds, and internal
+ * step launching. Stable
  * thread generations, final integration, and completion ownership live in
  * thread-lifecycle.ts.
  */
@@ -21,6 +22,7 @@ import {
 	buildFinalReviewBrief,
 	buildFixTaskBrief,
 	buildReReviewBrief,
+	documentationDisposition,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./fixloop.ts";
@@ -30,6 +32,8 @@ import {
 	monitor,
 	statusIcon,
 	type RunChainMeta,
+	type WorkflowStage,
+	type WorkflowStageStatus,
 } from "./monitor.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import {
@@ -85,6 +89,14 @@ export function defaultIsolationMode(mode: "single" | "parallel", agentName: str
 	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
+function workflowStageStatus(result: SingleResult): WorkflowStageStatus {
+	if (isFailedResult(result)) return "failed";
+	if (result.agent !== "reviewer") return "done";
+	const verdict = reviewVerdict(getResultOutput(result));
+	if (verdict === "fail") return "changes";
+	return verdict === "pass" ? "done" : "failed";
+}
+
 const managedRepositoryRootTails = new Map<string, Promise<void>>();
 
 async function canonicalManagedRepositoryRoot(cwd: string): Promise<string> {
@@ -167,15 +179,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		name: "subagent",
 		label: "Subagent",
 		description: [
-			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel.",
-			"Built-ins: explorer for broad read-only reconnaissance; worker for implementation; cleaner for explicitly authorized cleanup, removal, simplification, and duplicate-code consolidation; documenter for pre-commit diff sync or explicitly requested whole-codebase comment/README/docs maintenance; reviewer for generic read-only assessments and final gates.",
-			"Work starts in the background; successful top-level writers automatically continue through enabled documenter/reviewer stages and return one final completion. Results resume the main agent and are already shown to the user, so do not poll, duplicate downstream roles, or restate them. Give each child a self-contained brief because it has no conversation memory.",
+			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel; keep small known-target work in the main thread with direct tools.",
+			"Built-ins: explorer for broad read-only reconnaissance (a retrieval index, never a gate); worker for implementation; cleaner as a separate explicitly authorized cleanup/removal/simplification/deduplication entry; documenter for explicit docs/comments work or conditional final diff sync; reviewer for generic read-only assessments and independent code gates.",
+			"Work starts in the background. Successful worker/cleaner runs keep one enabled reviewer gate and bounded fix loop; documenter runs afterward only when REVIEW_PASS reports DOCUMENTATION: NEEDED or omits the marker, with a reviewer-disabled fallback. A top-level documenter delivers directly. Results resume the main agent and are already shown, so do not poll, duplicate downstream roles, or restate them.",
 			"Single tasks default to shared; parallel workers default to detached Git worktrees. Only write-capable agents can use worktree isolation, and failures never fall back silently to shared.",
 			"A selected-model or provider failure continues the retained session on the current main model; ordinary tool/task failures do not.",
 			"Use subagent_control to steer/retarget an active top-level child, park/stop a managed downstream stage, or resume/fork retained context by stable run id.",
 		].join(" "),
 		promptSnippet:
-			"Dispatch isolated background agents: explorer (recon), worker (implementation), cleaner (authorized cleanup/deduplication), documenter (docs sync), reviewer (read-only assessment/gate); enabled post-writer stages run automatically, results resume automatically, and the workflow delivers once. Use direct tools for trivial work.",
+			"Dispatch isolated background agents for broad recon, self-contained implementation, authorized cleanup, explicit docs, or independent review; keep small known-target work on direct tools. Worker/cleaner gates and only needed/conservative docs sync run automatically, results resume automatically, and each workflow delivers once.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -196,7 +208,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				if (!run) return; // already finished — stay idempotent
 				if (opts?.silent || !runtime.sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
-				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
+				ctx.ui.notify(`${icon} #${run.id} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
@@ -303,7 +315,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 					resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
 				const agent = resolveLiveAgentTools(discoveredAgent);
-				const resolvedRoute = resolveDispatchModelRoute(agent, request.config, request.ctx);
+				// Workflow policy (fix-round caps, agents) stays fixed for the chain,
+				// but model/thinking routes are re-read per stage so config edits
+				// apply to stages that have not launched yet.
+				const stageConfig = await loadConfig(runtime.configPath).catch(() => request.config);
+				const resolvedRoute = resolveDispatchModelRoute(agent, stageConfig, request.ctx);
 				const route = request.isolation === "worktree"
 					? { ...resolvedRoute, agent: withWorktreeSystemPrompt(resolvedRoute.agent) }
 					: resolvedRoute;
@@ -311,6 +327,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
 					...meta,
 					isolation: request.isolation,
+					...(request.worktreeId ? { worktreeId: request.worktreeId } : {}),
 				});
 				const onLive = makeLiveHandler(runId);
 				try {
@@ -327,7 +344,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							signal: request.signal,
 							onLive,
 							makeDetails: makeDetails("single", true),
-							idleTimeoutMs: request.config.idleTimeoutSec * 1000,
+							idleTimeoutMs: stageConfig.idleTimeoutSec * 1000,
 						},
 						route.mainFallbackRef,
 					);
@@ -387,27 +404,90 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const enabled = (name: string): boolean =>
 					request.agents.some((candidate) => candidate.name === name);
 				const canContinue = (): boolean => runtime.sessionActive && !request.signal.aborted;
+
+				// Keep a live parent-owned projection because settled internal rows are
+				// intentionally removed. Only real/currently planned stages enter it.
+				const initialStageRelation = initialStepResult.agent === "worker"
+					? "implement"
+					: initialStepResult.agent === "cleaner"
+						? "cleanup"
+						: "review";
+				const workflowStages: WorkflowStage[] = [{
+					agent: initialStepResult.agent,
+					relation: initialStageRelation,
+					status: workflowStageStatus(initialStepResult),
+				}];
+				let reviewStage: WorkflowStage | undefined;
+				if (request.plan.kind === "post-writer" && enabled("reviewer")) {
+					reviewStage = { agent: "reviewer", relation: "review", status: "pending" };
+					workflowStages.push(reviewStage);
+				}
+				let documentationStage: WorkflowStage | undefined;
+				if (enabled("documenter")) {
+					documentationStage = { agent: "documenter", relation: "docs", status: "pending" };
+					workflowStages.push(documentationStage);
+				}
+				const publishWorkflowStages = (): void => {
+					monitor.setWorkflowStages(request.parentRunId, workflowStages);
+				};
+				const insertBeforeDocumentation = (stage: WorkflowStage): void => {
+					const documentationIndex = documentationStage
+						? workflowStages.indexOf(documentationStage)
+						: -1;
+					if (documentationIndex === -1) workflowStages.push(stage);
+					else workflowStages.splice(documentationIndex, 0, stage);
+				};
+				const removeDocumentationStage = (): void => {
+					if (!documentationStage) return;
+					const index = workflowStages.indexOf(documentationStage);
+					if (index !== -1) workflowStages.splice(index, 1);
+					documentationStage = undefined;
+					publishWorkflowStages();
+				};
+				publishWorkflowStages();
+
 				const launchStep = async (
 					agentName: string,
 					task: string,
 					relation: string,
+					projection: {
+						stage?: WorkflowStage;
+						timelineRelation?: string;
+						childRelation?: string;
+					} = {},
 				): Promise<SingleResult> => {
 					if (!enabled(agentName)) {
 						throw new Error(`Managed workflow cannot launch disabled or missing agent "${agentName}".`);
 					}
-					const step = await launchInWorkflow(request, agentName, task, {
-						groupId: request.groupId,
-						relationLabel: relation,
-						parentRunId: request.parentRunId,
-					});
-					request.rememberLatest(step.result);
-					steps.push({ ...step, relation });
-					return step.result;
+					const stage: WorkflowStage = projection.stage ?? {
+						agent: agentName,
+						relation: projection.timelineRelation ?? relation,
+						status: "pending",
+					};
+					if (!projection.stage) insertBeforeDocumentation(stage);
+					stage.status = "active";
+					publishWorkflowStages();
+					try {
+						const step = await launchInWorkflow(request, agentName, task, {
+							groupId: request.groupId,
+							relationLabel: projection.childRelation ?? relation,
+							parentRunId: request.parentRunId,
+						});
+						stage.status = workflowStageStatus(step.result);
+						publishWorkflowStages();
+						request.rememberLatest(step.result);
+						steps.push({ ...step, relation });
+						return step.result;
+					} catch (error) {
+						stage.status = "failed";
+						publishWorkflowStages();
+						throw error;
+					}
 				};
 
-				/** Bounded worker → reviewer fix rounds. Documentation sync deliberately
-				 * stays out of the rounds: code fixes would invalidate it, and one final
-				 * documenter covers the settled diff once. */
+				/** Bounded worker → reviewer fix rounds. A conditional documentation sync
+				 * deliberately stays out of the rounds: code fixes would invalidate it,
+				 * and the terminal review classifies whether the settled diff needs one. */
 				const runFixRounds = async (
 					triggeringReviewer: SingleResult,
 				): Promise<{ lastReview?: SingleResult; lastWorker?: SingleResult }> => {
@@ -415,20 +495,24 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					const outcome: { lastReview?: SingleResult; lastWorker?: SingleResult } = {};
 					for (let round = 1; round <= request.config.maxFixRounds; round++) {
 						if (!canContinue()) break;
+						const fixRelation = `fix ${round}/${request.config.maxFixRounds}`;
 						const workerResult = await launchStep(
 							"worker",
 							buildFixTaskBrief(lastReviewer, round, request.config.maxFixRounds),
 							`fix round ${round}`,
+							{ timelineRelation: fixRelation, childRelation: fixRelation },
 						);
 						if (isFailedResult(workerResult) || !canContinue()) break;
 						outcome.lastWorker = workerResult;
 
+						const reReviewRelation = `re-review ${round}/${request.config.maxFixRounds}`;
 						const reviewResult = await launchStep(
 							"reviewer",
 							buildReReviewBrief(lastReviewer, round, workerResult, {
 								documenterPending: enabled("documenter"),
 							}),
 							`re-review round ${round}`,
+							{ timelineRelation: reReviewRelation, childRelation: reReviewRelation },
 						);
 						if (isFailedResult(reviewResult) || !canContinue()) break;
 						outcome.lastReview = reviewResult;
@@ -441,24 +525,40 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					return outcome;
 				};
 
-				/** One final documentation sync after the gate settles. It is skipped
-				 * when documenter is disabled, the last writer already was a
-				 * documenter with no code fixes after it, or the chain ended on a
-				 * failing/crashed gate (docs for rejected code would be rework). */
+				/** Run the low-cost final documentation sync only when the terminal REVIEW_PASS
+				 * reports drift or omits the new marker. A failed process, missing verdict, or
+				 * REVIEW_FAIL never writes docs. With no reviewer, retain the conservative
+				 * writer → documenter fallback. */
 				const runFinalDocumentation = async (
 					lastWriterResult: SingleResult | undefined,
 					finalReviewResult: SingleResult | undefined,
 				): Promise<void> => {
 					if (!canContinue() || !enabled("documenter")) return;
-					if (lastWriterResult?.agent === "documenter") return;
+					if (lastWriterResult?.agent === "documenter") {
+						removeDocumentationStage();
+						return;
+					}
 					if (finalReviewResult) {
-						if (isFailedResult(finalReviewResult)) return;
-						if (reviewVerdict(getResultOutput(finalReviewResult)) === "fail") return;
+						if (isFailedResult(finalReviewResult)) {
+							removeDocumentationStage();
+							return;
+						}
+						const reviewOutput = getResultOutput(finalReviewResult);
+						if (
+							reviewVerdict(reviewOutput) !== "pass" ||
+							documentationDisposition(reviewOutput) === "clean"
+						) {
+							removeDocumentationStage();
+							return;
+						}
 					}
+					documentationStage ??= { agent: "documenter", relation: "docs", status: "pending" };
+					if (!workflowStages.includes(documentationStage)) workflowStages.push(documentationStage);
 					await launchStep(
 						"documenter",
 						buildFinalDocumenterBrief(lastWriterResult, finalReviewResult),
 						"final documentation sync",
+						{ stage: documentationStage },
 					);
 				};
 
@@ -471,30 +571,30 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						const fixOutcome = await runFixRounds(initialStepResult);
 						await runFinalDocumentation(fixOutcome.lastWorker, fixOutcome.lastReview ?? initialStepResult);
 					} else if (request.plan.kind === "review-pass-sync") {
-						// The direct passing review already gated the pending code; sync
-						// docs once and deliver without a second gate.
+						// The direct passing review already gated the pending code. Its
+						// disposition requested (or conservatively defaulted to) one docs sync.
 						await runFinalDocumentation(undefined, initialStepResult);
 					} else if (enabled("reviewer")) {
 						const gateReview = await launchStep(
 							"reviewer",
 							buildFinalReviewBrief(initialStepResult, { documenterPending: enabled("documenter") }),
 							"final review",
+							{ stage: reviewStage },
 						);
-						if (!isFailedResult(gateReview)) {
-							let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
-							if (
-								canContinue() &&
-								reviewVerdict(getResultOutput(gateReview)) === "fail" &&
-								enabled("worker") &&
-								request.config.maxFixRounds > 0
-							) {
-								fixOutcome = await runFixRounds(gateReview);
-							}
-							await runFinalDocumentation(
-								fixOutcome.lastWorker ?? initialStepResult,
-								fixOutcome.lastReview ?? gateReview,
-							);
+						let fixOutcome: Awaited<ReturnType<typeof runFixRounds>> = {};
+						if (
+							!isFailedResult(gateReview) &&
+							canContinue() &&
+							reviewVerdict(getResultOutput(gateReview)) === "fail" &&
+							enabled("worker") &&
+							request.config.maxFixRounds > 0
+						) {
+							fixOutcome = await runFixRounds(gateReview);
 						}
+						await runFinalDocumentation(
+							fixOutcome.lastWorker ?? initialStepResult,
+							fixOutcome.lastReview ?? gateReview,
+						);
 					} else {
 						// No gate configured: the documenter is the only downstream stage.
 						await runFinalDocumentation(initialStepResult, undefined);

package/src/fixloop.ts

@@ -1,14 +1,14 @@
 /**
  * Managed workflow policy and handoff formatting.
  *
- * Successful top-level writers continue through an independent code review
- * gate; bounded worker → reviewer fix rounds close its findings; one final
- * documentation sync runs after the gate settles, so code fixes never
- * invalidate an earlier docs pass and reviewers stay focused on code. A direct
- * passing reviewer gets that same single final documentation sync instead of a
- * second gate; a direct failing reviewer uses the same fix rounds plus the
- * final sync. Internal steps are launched by dispatch directly, so they never
- * re-enter this top-level policy or wake the main agent mid-chain.
+ * Successful top-level worker/cleaner runs continue through an independent
+ * code review gate; bounded worker → reviewer fix rounds close its findings.
+ * Reviewers classify documentation drift explicitly, so the low-cost final
+ * documenter runs only when needed (or conservatively when an older/custom
+ * reviewer omits the marker). Direct passing/failing gates use the same policy.
+ * Top-level documenters are explicit standalone writing tasks. Internal steps
+ * are launched by dispatch directly, so they never re-enter this policy or wake
+ * the main agent mid-chain.
  */
 
 import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
@@ -58,6 +58,20 @@ export function workflowAgentAvailability(
 	};
 }
 
+export type DocumentationDisposition = "clean" | "needed";
+
+/** Only the last standalone documentation disposition line counts. Inline
+ * examples and prose are ignored so a prompt echo cannot suppress a needed
+ * conservative sync. */
+export function documentationDisposition(output: string): DocumentationDisposition | undefined {
+	const lines = output.split("\n");
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const match = /^\s*DOCUMENTATION:\s*(CLEAN|NEEDED)\s*$/i.exec(lines[index]);
+		if (match) return match[1].toUpperCase() === "CLEAN" ? "clean" : "needed";
+	}
+	return undefined;
+}
+
 export type ManagedWorkflowKind = "auto-fix" | "post-writer" | "review-pass-sync";
 
 export interface ManagedWorkflowPlan {
@@ -101,17 +115,20 @@ export function getManagedWorkflowPlan(
 			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
 		};
 	}
-	if (result.agent === "documenter") {
-		return availability.reviewer
-			? { kind: "post-writer", initialRelation: "documentation pass" }
-			: undefined;
-	}
+	// A top-level documenter is already an explicit docs/comments write task. It
+	// owns the writer lane but delivers directly without an automatic code gate.
+	if (result.agent === "documenter") return undefined;
 	if (result.agent !== "reviewer") return undefined;
 
-	const verdict = reviewVerdict(getResultOutput(result));
-	// The pass stands as the code gate; documenter then syncs docs once and the
-	// workflow delivers without a second gate.
-	if (verdict === "pass" && availability.documenter) {
+	const output = getResultOutput(result);
+	const verdict = reviewVerdict(output);
+	// The pass stands as the code gate. Run the conditional documenter only for
+	// explicit drift or when an older/custom reviewer omitted the marker.
+	if (
+		verdict === "pass" &&
+		availability.documenter &&
+		documentationDisposition(output) !== "clean"
+	) {
 		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
 	}
 	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result, config)) {
@@ -139,19 +156,21 @@ export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, m
 		`Fix EVERY finding in the reviewer's findings list — there is no severity triage; all of them get fixed.`,
 		`If a finding is factually wrong or clearly out of scope, say so explicitly instead of fixing it.`,
 		`Do NOT refactor unrelated code beyond what the findings require.`,
-		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and the final documentation sync.`,
+		`Synchronize any existing README/docs/examples/comments directly affected by your fixes; do not broaden into standalone documentation maintenance.`,
+		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and any conditional final documentation sync.`,
 		`After editing, run the project's format/build/tests when they exist and report`,
 		`exactly what you changed (paths + short rationale) so a reviewer can verify.`,
 		remaining > 0
 			? `A reviewer will re-review your changes automatically after you finish.`
-			: `This is the last auto-fix round; the workflow runs any enabled final documentation sync and then delivers.`,
+			: `This is the last auto-fix round; the workflow conditionally runs any needed final documentation sync and then delivers.`,
 	].join("\n");
 }
 
-/** Build the single documentation handoff that runs after the review gate
- * settles. The last writer's report (top-level writer or final fix-round
- * worker) and the terminal gate review are leads; the pending diff stays
- * authoritative. At most one of the two is undefined in every managed flow. */
+/** Build the single documentation handoff selected after the review gate
+ * settles or as the reviewer-disabled fallback. The last writer's report
+ * (top-level writer or final fix-round worker) and the terminal gate review are
+ * leads; the pending diff stays authoritative. At most one of the two is
+ * undefined in every managed flow. */
 export function buildFinalDocumenterBrief(
 	lastWriterResult?: SingleResult,
 	finalReviewResult?: SingleResult,
@@ -247,7 +266,7 @@ export function formatChainSummary(
 	);
 }
 
-/** One clear final delivery for all newly managed writer/documenter workflows. */
+/** One clear final delivery for post-writer and direct reviewer → documenter workflows. */
 export function formatManagedWorkflowSummary(
 	steps: readonly ChainStep[],
 	terminalResult: SingleResult = steps[steps.length - 1]!.result,
@@ -262,8 +281,9 @@ export function formatManagedWorkflowSummary(
 }
 
 export interface GateBriefOptions {
-	/** A final documenter runs after the gate settles. Documentation drift is
-	 * then routed to it as non-gating notes instead of failing the gate. */
+	/** A conditional final documenter is available after the gate settles.
+	 * Documentation drift is then routed to it as non-gating notes instead of
+	 * failing the code gate. */
 	documenterPending: boolean;
 }
 
@@ -286,11 +306,14 @@ export function buildFinalReviewBrief(
 		`Remain read-only. Verify correctness, regressions, and tests.`,
 		...(options.documenterPending
 			? [
-				`Documentation sync runs AFTER this gate, so documentation drift is not a gate finding: record needed`,
-				`documentation updates as a separate short "## Documentation notes" list for the final documenter,`,
-				`and fail the gate only for code or test findings.`,
+				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding.`,
+				`If documentation is stale, add a separate short "## Documentation notes" list and emit the standalone line`,
+				`DOCUMENTATION: NEEDED. If no documentation update is needed, emit DOCUMENTATION: CLEAN instead.`,
+				`Always emit exactly one of those standalone documentation lines; fail the gate only for code or test findings.`,
 			]
-			: []),
+			: [
+				`No documenter is pending, so documentation drift is an ordinary gate finding.`,
+			]),
 		`This is an acceptance gate, not an advisory audit. End with exactly one standalone machine verdict line:`,
 		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
 	].join("\n");
@@ -332,9 +355,12 @@ export function buildReReviewBrief(
 		`Do NOT re-open a finding you verified as resolved.`,
 		...(options.documenterPending
 			? [
-				`Carry any unresolved "## Documentation notes" forward verbatim; the final documenter applies them after the chain settles.`,
+				`Carry unresolved "## Documentation notes" forward and add any newly exposed drift there; documentation drift is not a code-gate finding.`,
+				`Emit exactly one standalone documentation disposition line: DOCUMENTATION: NEEDED when that notes section is required, otherwise DOCUMENTATION: CLEAN.`,
 			]
-			: []),
+			: [
+				`No documenter is pending, so unresolved documentation drift remains an ordinary gate finding.`,
+			]),
 		`REQUEST_CHANGES only while an open finding remains; otherwise APPROVE.`,
 		`End with your machine-readable verdict line as usual (VERDICT: REVIEW_PASS / REVIEW_FAIL).`,
 	].join("\n");

package/src/monitor.ts

@@ -20,18 +20,32 @@ import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 export type RunStatus = "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed";
 export type ContinuationKind = "resume-retained" | "resume-appended" | "fork-retained" | "fork-appended" | "retarget";
+export type WorkflowStageStatus = "done" | "active" | "pending" | "changes" | "failed";
+
+/** Ephemeral projection of one real or currently planned managed stage. It is
+ * live monitor state only; durable results remain the per-run chain records. */
+export interface WorkflowStage {
+	agent: string;
+	relation: string;
+	status: WorkflowStageStatus;
+}
 
 export function isRunActiveStatus(status: RunStatus): boolean {
 	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
 }
 
+/** Durable integration projection of a worktree-isolated run: pending before
+ * settlement, finalizing while the patch is applied/cleaned up, then the
+ * terminal WorktreeFinalizationStatus. */
+export type RunIntegrationStatus = "pending" | "finalizing" | WorktreeFinalizationStatus;
+
 export interface RunView {
 	id: number;
 	agent: string;
 	task: string;
 	/** Short content label derived from the task (paths/symbols), shown next to
 	 * the agent name so concurrent same-agent runs are told apart by what they
-	 * are doing, not just their run id. */
+	 * are doing, not just by their run id. */
 	label?: string;
 	model?: string;
 	/** Selected model ref when the run handed off to current main. */
@@ -39,7 +53,10 @@ export interface RunView {
 	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
 	thinking?: string;
 	isolation?: IsolationMode;
-	integrationStatus?: "pending" | WorktreeFinalizationStatus;
+	integrationStatus?: RunIntegrationStatus;
+	/** Short worktree-group identity (mkdtemp suffix) shared by every run inside
+	 * one isolated worktree; changes when a continuation worktree is created. */
+	worktreeId?: string;
 	forkedFromRunId?: number;
 	forkChildRunIds?: number[];
 	status: RunStatus;
@@ -65,6 +82,9 @@ export interface RunView {
 	/** This stable top-level row currently owns a multi-stage managed workflow.
 	 * Its elapsed time is workflow-wide; active child rows own stage telemetry. */
 	managedWorkflow?: boolean;
+	/** Live-only stage timeline retained on the parent while completed internal
+	 * child rows leave the monitor. */
+	workflowStages?: WorkflowStage[];
 }
 
 /** Optional metadata for documenter/reviewer/fix children of a stable parent run. */
@@ -73,6 +93,7 @@ export interface RunChainMeta {
 	relationLabel?: string;
 	parentRunId?: number;
 	isolation?: IsolationMode;
+	worktreeId?: string;
 	forkedFromRunId?: number;
 	continuationKind?: ContinuationKind;
 }
@@ -446,7 +467,7 @@ export class MonitorStore {
 			...(meta?.groupId ? { groupId: meta.groupId } : {}),
 			...(meta?.relationLabel ? { relationLabel: meta.relationLabel } : {}),
 			...(meta?.parentRunId !== undefined ? { parentRunId: meta.parentRunId } : {}),
-			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined } : {}),
+			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined, ...(meta.worktreeId ? { worktreeId: meta.worktreeId } : {}) } : {}),
 			...(meta?.forkedFromRunId !== undefined ? { forkedFromRunId: meta.forkedFromRunId } : {}),
 			...(meta?.continuationKind ? { continuationKind: meta.continuationKind } : {}),
 		});
@@ -481,6 +502,18 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.managedWorkflow = active || undefined;
+		if (!active) run.workflowStages = undefined;
+		this.notify();
+	}
+
+	/** Replace the live workflow projection atomically so renderers never observe
+	 * a half-updated fix/re-review plan. */
+	setWorkflowStages(id: number, stages: readonly WorkflowStage[]): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.workflowStages = stages.length > 0
+			? stages.map((stage) => ({ ...stage }))
+			: undefined;
 		this.notify();
 	}
 
@@ -535,11 +568,17 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	setIsolation(id: number, isolation: IsolationMode, integrationStatus?: "pending" | WorktreeFinalizationStatus): void {
+	setIsolation(
+		id: number,
+		isolation: IsolationMode,
+		integrationStatus?: RunIntegrationStatus,
+		worktreeId?: string,
+	): void {
 		const run = this.find(id);
 		if (!run) return;
 		run.isolation = isolation;
 		run.integrationStatus = integrationStatus;
+		if (worktreeId) run.worktreeId = worktreeId;
 		this.notify();
 	}
 
@@ -584,7 +623,7 @@ export class MonitorStore {
 		model?: string,
 		thinking?: string,
 		isolation?: IsolationMode,
-		meta?: { elapsedMs?: number; continuationKind?: ContinuationKind },
+		meta?: { elapsedMs?: number; continuationKind?: ContinuationKind; worktreeId?: string },
 	): void {
 		const run = this.find(id);
 		if (!run) {
@@ -595,7 +634,13 @@ export class MonitorStore {
 				label: runLabel(task),
 				model,
 				thinking,
-				...(isolation ? { isolation, integrationStatus: isolation === "worktree" ? "pending" as const : undefined } : {}),
+				...(isolation
+					? {
+						isolation,
+						integrationStatus: isolation === "worktree" ? "pending" as const : undefined,
+						...(isolation === "worktree" && meta?.worktreeId ? { worktreeId: meta.worktreeId } : {}),
+					}
+					: {}),
 				status: "queued",
 				usage: emptyUsage(),
 				elapsedMs: meta?.elapsedMs ?? 0,
@@ -611,10 +656,13 @@ export class MonitorStore {
 		run.thinking = thinking;
 		if (isolation) run.isolation = isolation;
 		run.integrationStatus = isolation === "worktree" ? "pending" : undefined;
+		if (isolation === "worktree" && meta?.worktreeId) run.worktreeId = meta.worktreeId;
+		else if (isolation !== "worktree") run.worktreeId = undefined;
 		run.status = "queued";
 		run.usage = emptyUsage();
 		run.activity = undefined;
 		run.managedWorkflow = undefined;
+		run.workflowStages = undefined;
 		run.activeSince = undefined;
 		run.endedAt = undefined;
 		run.elapsedMs = Math.max(run.elapsedMs, meta?.elapsedMs ?? 0);