@ferris1225/pi-subagents 4.1.8 → 4.1.11

package/src/tools.ts

@@ -1,6 +1,6 @@
 /**
  * Thread controls and lookup tools around the subagent runtime:
- * subagent_control (steer/retarget/park/resume/fork), subagent_wait (in-turn
+ * subagent_control (resume), subagent_wait (in-turn
  * result lookup), subagent_status, and destructive subagent_stop.
  */
 
@@ -10,6 +10,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { existsSync } from "node:fs";
 import { Type } from "typebox";
 import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "./config.ts";
+import { removeThreadRecord } from "./durable.ts";
 import { formatCompletionBlock, formatUsage, matchRunIds } from "./format.ts";
 import { emptyUsage } from "./rpc-run.ts";
 import {
@@ -46,15 +47,12 @@ function renderFirstLine(result: { content?: unknown }, label: string, theme: an
 
 export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	const SubagentControlParams = Type.Object({
-		action: StringEnum(["steer", "retarget", "park", "resume", "fork"] as const, {
+		action: StringEnum(["resume"] as const, {
 			description: "Control operation for the logical sub-agent thread.",
 		}),
 		id: Type.Integer({ minimum: 1, description: "Stable run id shown by subagent dispatch/status output." }),
-		instruction: Type.Optional(
-			Type.String({ description: "Instruction queued by steer after the current child tool batch." }),
-		),
 		objective: Type.Optional(
-			Type.String({ description: "Replacement objective for retarget; optional appended objective for resume/fork. Omit on resume/fork to continue the current retained objective." }),
+			Type.String({ description: "Optional appended objective for resume. Omit to continue the current retained objective." }),
 		),
 	});
 
@@ -62,21 +60,14 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 		name: "subagent_control",
 		label: "Subagent Control",
 		description: [
-			"Control an existing sub-agent thread by stable run id.",
-			"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 an existing sub-agent thread by stable run id.",
 			"resume restarts a parked, completed, or failed retained thread with the same run id and cumulative active time; omit objective to continue the current goal, or provide one to append it to retained context and make it the displayed current goal.",
-			"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; omit objective to continue the current goal, or provide one to append a new branch goal.",
+			"Threads parked or interrupted by a shutdown/reload are restorable; use subagent_stop for destructive cancellation.",
 		].join(" "),
-		promptSnippet: "Control a subagent thread: steer/retarget an active top-level child; park/stop a managed downstream stage; resume or fork retained context.",
+		promptSnippet: "Resume a parked or settled subagent thread with its retained context.",
 		promptGuidelines: [
-			"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. Resume without objective keeps the current goal; resume with objective appends that goal to retained context.",
-			"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.",
+			"Use subagent_control resume to continue a parked/settled thread on the same run id. Resume without objective keeps the current goal; resume with objective appends that goal to retained context.",
+			"Use subagent_stop only for destructive cancellation; it retires that thread's retained session.",
 		],
 		parameters: SubagentControlParams,
 
@@ -92,54 +83,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 			try {
 				switch (params.action) {
-					case "steer": {
-						const instruction = nonBlank(params.instruction);
-						if (!instruction) {
-							return { content: [{ type: "text", text: "steer requires a non-blank instruction." }], details: {} };
-						}
-						if (!(["running", "steering"] as const).includes(thread.control.getPhase() as any)) {
-							return { content: [{ type: "text", text: `Run #${thread.id} is ${thread.control.getPhase()}; only a running thread can be steered.` }], details: {} };
-						}
-						await thread.control.steer(instruction);
-						return { content: [{ type: "text", text: `Queued steering instruction for run #${thread.id} after its current tool batch.` }], details: {} };
-					}
-					case "retarget": {
-						const objective = nonBlank(params.objective);
-						if (!objective) {
-							return { content: [{ type: "text", text: "retarget requires a non-blank objective." }], details: {} };
-						}
-						const phase = thread.control.getPhase();
-						if (thread.state === "queued" && phase === "queued") {
-							thread.task = objective;
-							thread.control.retargetPending(objective);
-							monitor.setTask(thread.id, objective);
-							monitor.setContinuationKind(thread.id, "retarget");
-							return { content: [{ type: "text", text: `Updated queued run #${thread.id} to the replacement objective; no child was spawned by this control action.` }], details: {} };
-						}
-						if (!(["starting", "running", "steering", "interrupting", "retrying"] as const).includes(phase as any)) {
-							return { content: [{ type: "text", text: `Run #${thread.id} is ${thread.state}; use resume with objective to restart retained context.` }], details: {} };
-						}
-						thread.task = objective;
-						monitor.setTask(thread.id, objective);
-						monitor.setContinuationKind(thread.id, "retarget");
-						await thread.control.retarget(objective);
-						return { content: [{ type: "text", text: `Retargeted run #${thread.id} in the same session; the aborted objective will not be delivered as a completion.` }], details: {} };
-					}
-					case "park": {
-						if (thread.state === "parked") {
-							return { content: [{ type: "text", text: `Run #${thread.id} is already parked.` }], details: {} };
-						}
-						const disposition = await thread.park();
-						return disposition === "queued"
-							? {
-								content: [{ type: "text", text: `Parked queued run #${thread.id}; it never spawned a child or empty session.` }],
-								details: {},
-							}
-							: {
-								content: [{ type: "text", text: `Parked run #${thread.id} at a stable checkpoint; its session is retained and concurrency slot released.` }],
-								details: {},
-							};
-					}
 					case "resume": {
 						if (thread.retired) {
 							return { content: [{ type: "text", text: `Run #${thread.id} was retired by subagent_stop and has no resumable session.` }], details: {} };
@@ -165,24 +108,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 							: "no prior child session existed, so only the logical run and objective are continued";
 						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. Completion will arrive automatically.` }], details: {}, terminate: true };
 					}
-					case "fork": {
-						const objective = params.objective === undefined ? undefined : nonBlank(params.objective);
-						if (params.objective !== undefined && !objective) {
-							return { content: [{ type: "text", text: "fork objective must be non-blank when provided." }], details: {} };
-						}
-						const pending = await thread.fork(objective, ctx);
-						if (pending.exitCode !== -1 || pending.runId === undefined) {
-							return { content: [{ type: "text", text: getResultOutput(pending) }], details: {} };
-						}
-						return {
-							content: [{
-								type: "text",
-								text: `Forked run #${thread.id} into new run #${pending.runId}; ${objective ? `appended branch objective: ${formatTaskSummary(objective, 80, false)}` : `continuing current objective: ${formatTaskSummary(thread.task, 80, false)}`}. Retained context is copied, the source is unchanged, and child completion will arrive automatically.`,
-							}],
-							details: { sourceRunId: thread.id, childRunId: pending.runId, result: pending },
-							terminate: true,
-						};
-					}
 				}
 			} catch (error) {
 				throw new Error(`Could not ${params.action} run #${thread.id}: ${error instanceof Error ? error.message : String(error)}`);
@@ -431,8 +356,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 						: undefined;
 					const metadata = [
 						activeThread?.isolation === "worktree" ? `worktree ${active.integrationStatus ?? activeThread.worktree?.state ?? "active"}` : undefined,
-						activeThread?.forkedFromRunId !== undefined ? `forked from #${activeThread.forkedFromRunId}` : undefined,
-						(activeThread?.forkChildRunIds.length ?? 0) > 0 ? `forks ${activeThread!.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
 					].filter(Boolean).join(" · ");
 					const stageStatus = activeChild
 						? monitor.summarize(activeChild)
@@ -444,8 +367,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 								text: parked
 									? `Run #${active.id} ${owner} is parked with retained${retainedStage ? ` ${retainedStage} stage` : ""} context${metadata ? ` (${metadata})` : ""}. Use subagent_control resume to restart it, or subagent_stop to retire it.`
 									: managedDownstream
-										? `Run #${active.id} ${owner} is in a managed downstream stage (${stageStatus}${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} ${owner} 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.`,
+										? `Run #${active.id} ${owner} is in a managed downstream stage (${stageStatus}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait for its result or subagent_stop to cancel it.`
+										: `Run #${active.id} ${owner} is still active (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait to block for its result or subagent_stop to cancel it.`,
 							},
 						],
 						details: {},
@@ -462,8 +385,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const parts = [
 					`#${run.id} ${monitor.summarize(run)}`,
 					run.label,
-					thread?.forkedFromRunId !== undefined ? `forked from #${thread.forkedFromRunId}` : undefined,
-					(thread?.forkChildRunIds.length ?? 0) > 0 ? `forks ${thread!.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
 					run.activity ?? statusLabel(run.status),
 				].filter(Boolean);
 				return `- ${parts.join(" · ")}`;
@@ -475,13 +396,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const retainedStage = run?.managedWorkflow && thread.agentName !== run.agent
 					? ` · retained stage ${thread.agentName}`
 					: "";
-				const relations = [
-					thread.forkedFromRunId !== undefined ? `forked from #${thread.forkedFromRunId}` : undefined,
-					thread.forkChildRunIds.length > 0 ? `forks ${thread.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
-				].filter(Boolean);
-				const relation = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
 				const isolation = thread.isolation === "worktree" ? ` · worktree ${thread.worktree?.state ?? "active"}` : "";
-				return `- #${thread.id} ${owner} · ${run?.label ?? runLabel(thread.task)} · parked${thread.sessionDir ? " · context retained" : " · not started"}${retainedStage}${isolation}${relation}`;
+				return `- #${thread.id} ${owner} · ${run?.label ?? runLabel(thread.task)} · parked${thread.sessionDir ? " · context retained" : " · not started"}${retainedStage}${isolation}`;
 			});
 			const completed = [...runtime.settledRuns.entries()].slice(-5);
 			const completedLines = completed.map(([id, result]) => {
@@ -491,12 +407,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					? `${result.model ?? "?"} (main after ${result.modelFallbackFrom} failed)`
 					: (result.model ?? "?");
 				const isolation = result.isolation === "worktree" ? ` · worktree ${result.integrationStatus ?? "unknown"}` : "";
-				const relations = [
-					result.forkedFromRunId !== undefined ? `forked from #${result.forkedFromRunId}` : undefined,
-					(result.forkChildRunIds?.length ?? 0) > 0 ? `forks ${result.forkChildRunIds!.map((childId) => `#${childId}`).join(",")}` : undefined,
-				].filter(Boolean);
-				const relation = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
-				return `- #${id} ${result.agent}${label ? ` · ${label}` : ""} · ${isFailedResult(result) ? "failed" : "completed"} · ${model}${isolation}${relation}${usage ? ` · ${usage}` : ""}`;
+				return `- #${id} ${result.agent}${label ? ` · ${label}` : ""} · ${isFailedResult(result) ? "failed" : "completed"} · ${model}${isolation}${usage ? ` · ${usage}` : ""}`;
 			});
 
 			const sections: string[] = [];
@@ -506,7 +417,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 			sections.push(parkedLines.length > 0 ? parkedLines.join("\n") : "(none)");
 			sections.push(`### Finished this session (${runtime.settledRuns.size})`);
 			sections.push(completedLines.length > 0 ? completedLines.join("\n") : "(none)");
-			sections.push("Pass a run id to subagent_status for the full result, use subagent_control to steer/park/resume/fork, or subagent_wait for active work.");
+			sections.push("Pass a run id to subagent_status for the full result, use subagent_control to resume a settled thread, or subagent_wait for active work.");
 			return { content: [{ type: "text", text: sections.join("\n\n") }], details: {} };
 		},
 
@@ -551,7 +462,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			// Start config I/O without yielding: every target below must be claimed
-			// synchronously before a resume/fork preflight can cross its next await.
+			// synchronously before a resume preflight can cross its next await.
 			const configPromise = loadConfig(runtime.configPath).catch(() => undefined);
 			const completionResults: SingleResult[] = [];
 			const candidateIds = params.all === true
@@ -560,7 +471,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					...[...runtime.threads.values()]
 						.filter((thread) =>
 							thread.lifecycleOperation !== undefined ||
-							["queued", "resuming", "running", "steering", "interrupting"].includes(thread.state),
+							["queued", "resuming", "running", "interrupting"].includes(thread.state),
 						)
 						.map((thread) => thread.id),
 				])]
@@ -607,10 +518,10 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const wasResuming = previousState === "resuming";
 				const wasActive =
 					thread.lifecycleOperation !== undefined ||
-					["queued", "resuming", "running", "steering", "interrupting"].includes(previousState);
+					["queued", "resuming", "running", "interrupting"].includes(previousState);
 				const stopVersion = ++thread.lifecycleVersion;
 				// Stop-all claims every target before the first await. This invalidates
-				// all concurrent resume/fork preflights as one synchronous operation.
+				// all concurrent resume preflights as one synchronous operation.
 				thread.lifecycleOperation = "stop";
 				thread.retired = true;
 				thread.retireOnSettle = true;
@@ -692,7 +603,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					stoppedResult = prior
 						? {
 							...prior,
-							parked: undefined,
 							exitCode: 1,
 							stopReason: "aborted",
 							errorMessage: stopMessage,
@@ -756,6 +666,9 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				if (stoppedResult) completionResults.push(stoppedResult);
 				monitor.removeRun(runId);
 				runtime.retireThreadSession(thread);
+				// The destructive retire removes the durable record with the session;
+				// an id never resurrects after subagent_stop.
+				await removeThreadRecord(runtime.configPath, runId).catch(() => undefined);
 				if (thread.lifecycleVersion === stopVersion && thread.lifecycleOperation === "stop") {
 					thread.lifecycleOperation = undefined;
 				}

package/src/widget.ts

@@ -98,7 +98,7 @@ function runPrimaryLine(
 	// A chain child shows its role in the chain plus a task-derived label; the
 	// templated fix brief itself would only repeat the parent review's content.
 	const continuation = run.parentRunId === undefined
-		? continuationLabel(run.continuationKind, run.forkedFromRunId)
+		? continuationLabel(run.continuationKind)
 		: undefined;
 	const taskSource = run.parentRunId !== undefined
 		? [run.relationLabel, run.label].filter((part): part is string => Boolean(part)).join(" · ")
@@ -215,8 +215,8 @@ function runActivityLine(run: RunView, theme: Theme, width: number, indent: stri
 
 /** Render active runs as compact workflow-aware trees. Stable managed parents
  * retain their stage timeline while the current internal child supplies exact
- * model/thinking/activity telemetry. Fork labels include their source id; other
- * control ids remain available through status. */
+ * model/thinking/activity telemetry. Control ids remain available through
+ * status. */
 export function formatActiveRunLines(
 	runs: readonly RunView[],
 	theme: Theme,

package/src/workflow.ts

@@ -0,0 +1,248 @@
+/**
+ * Managed workflow policy and handoff formatting.
+ *
+ * Successful top-level worker/cleaner runs continue through an independent
+ * code review gate. A passing gate may run one conditional documentation
+ * sync; a failing gate is delivered to the main agent, which owns the fix
+ * decision — the runtime never edits code on a reviewer's behalf. 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 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";
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { formatUsageCompact, sumUsage } from "./monitor.ts";
+
+export interface WorkflowAgentAvailability {
+	cleaner: boolean;
+	documenter: boolean;
+	reviewer: boolean;
+	writer: boolean;
+}
+
+export function workflowAgentAvailability(
+	agents: readonly Pick<AgentConfig, "name" | "tools">[],
+): WorkflowAgentAvailability {
+	const names = new Set(agents.map((agent) => agent.name));
+	return {
+		cleaner: names.has("cleaner"),
+		documenter: names.has("documenter"),
+		reviewer: names.has("reviewer"),
+		writer: agents.some(isWriteCapableAgent),
+	};
+}
+
+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 = "post-writer" | "review-pass-sync";
+
+export interface ManagedWorkflowPlan {
+	kind: ManagedWorkflowKind;
+	initialRelation: string;
+}
+
+/** Conservative pre-run check used to reserve one shared-repository lane
+ * around a complete writer workflow or a reviewer that needs a stable diff.
+ * The actual result is classified again by getManagedWorkflowPlan before a
+ * downstream child starts. */
+export function canStartManagedWorkflow(
+	agent: Pick<AgentConfig, "name" | "tools">,
+	availability: WorkflowAgentAvailability,
+): boolean {
+	// Every shared write-capable role—including custom agents—owns the repository
+	// lane even when no downstream role is enabled. Otherwise its edits can race
+	// a managed writer's documentation snapshot.
+	if (isWriteCapableAgent(agent)) return true;
+	if (agent.name === "reviewer") {
+		// Hold a stable diff snapshot against every discoverable writer even when
+		// this review is advisory. Classification happens only after the read-only
+		// child returns, too late to acquire the lane safely.
+		return availability.writer;
+	}
+	return false;
+}
+
+/** Classify only healthy top-level results. In particular, a reviewer without a
+ * machine verdict is advisory and cannot start any write-capable child; a
+ * failing gate is not a workflow at all — its findings are delivered to the
+ * main agent, which decides the fixes. */
+export function getManagedWorkflowPlan(
+	result: SingleResult,
+	availability: WorkflowAgentAvailability,
+	advisoryReview = false,
+): ManagedWorkflowPlan | undefined {
+	if (result.dispatchFailed || isFailedResult(result)) return undefined;
+	if (result.agent === "worker" || result.agent === "cleaner") {
+		if (!availability.documenter && !availability.reviewer) return undefined;
+		return {
+			kind: "post-writer",
+			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
+		};
+	}
+	// 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;
+	// An advisory dispatch never chains: the caller asked for a report, so even
+	// a stray gate verdict must be delivered rather than acted on.
+	if (advisoryReview) return undefined;
+
+	const output = getResultOutput(result);
+	// 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 (
+		reviewVerdict(output) === "pass" &&
+		availability.documenter &&
+		documentationDisposition(output) !== "clean"
+	) {
+		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
+	}
+	return undefined;
+}
+
+/** Build the single documentation handoff selected after the review gate
+ * settles or as the reviewer-disabled fallback. The top-level writer's report
+ * 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,
+): string {
+	const reportSections = [
+		...(lastWriterResult
+			? [
+				`The last writer (${lastWriterResult.agent}) reported:`,
+				`---`,
+				getResultOutput(lastWriterResult),
+				`---`,
+				``,
+			]
+			: []),
+		...(finalReviewResult
+			? [
+				`The final gate review reported:`,
+				`---`,
+				getResultOutput(finalReviewResult),
+				`---`,
+				``,
+			]
+			: []),
+	];
+	return [
+		`Final documentation sync: the review gate settled and you are the last managed stage before delivery.`,
+		``,
+		...reportSections,
+		`Inspect the actual git diff and relevant implementation; the reports are only leads.`,
+		`Apply every documentation note the reviews recorded, then synchronize stale README/docs, examples, API comments, docstrings,`,
+		`and explanatory comments with the behavior that will be committed.`,
+		`Change documentation surfaces only; make zero edits when the diff creates no documentation drift.`,
+		`The workflow delivers directly after you; no fresh reviewer runs.`,
+		`Report exact documentation/comment paths changed, or state explicitly that no sync was needed.`,
+	].join("\n");
+}
+
+/**
+ * One step of a managed workflow as delivered: the run id (so the condensed
+ * summary can point at per-run detail via subagent_status), the result, and
+ * the human-readable role within the workflow ("initial implementation",
+ * "final review", "final documentation sync"). runId is optional only for
+ * synthetic steps that never spawned a child.
+ */
+export interface ChainStep {
+	runId?: number;
+	result: SingleResult;
+	relation: string;
+}
+
+export interface ManagedWorkflowOutcome {
+	kind: ManagedWorkflowKind;
+	steps: ChainStep[];
+}
+
+function workflowResultStatus(result: SingleResult): string {
+	if (isFailedResult(result)) return "failed";
+	if (result.agent === "reviewer") {
+		const verdict = reviewVerdict(getResultOutput(result));
+		return verdict ? verdict.toUpperCase() : "NO_VERDICT";
+	}
+	return "completed";
+}
+
+function workflowStepLine(step: ChainStep): string {
+	const id = step.runId !== undefined ? `#${step.runId} ` : "";
+	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result)}`;
+}
+
+function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): void {
+	const total = sumUsage(steps.map((step) => step.result.usage));
+	const usage = formatUsageCompact(total);
+	lines.push("", `Totals: ${steps.length} run${steps.length === 1 ? "" : "s"}${usage ? ` · ${usage}` : ""}`);
+	const ids = steps.filter((step) => step.runId !== undefined).map((step) => `#${step.runId}`);
+	lines.push(`Per-run details: subagent_status ${ids.join(" ")}`);
+}
+
+/** 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,
+): string {
+	const route = steps.map((step) => step.result.agent).join(" → ");
+	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult)}`, "", ...steps.map(workflowStepLine)];
+	appendWorkflowFooter(lines, steps);
+	return lines.join("\n");
+}
+
+export interface GateBriefOptions {
+	/** 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;
+}
+
+/** Build the code gate that runs directly after a top-level writer, before any
+ * documentation. Reports carry intent; the actual pending diff remains
+ * authoritative. */
+export function buildFinalReviewBrief(
+	initialResult: SingleResult,
+	options: GateBriefOptions,
+): string {
+	return [
+		`Fresh code gate for a managed ${initialResult.agent} workflow.`,
+		``,
+		`The top-level ${initialResult.agent}'s full report:`,
+		`---`,
+		getResultOutput(initialResult),
+		`---`,
+		``,
+		`Run \`git status\` and \`git diff\` and inspect the actual pending code; the report is context, not proof.`,
+		`Remain read-only. Attach a concrete fix instruction to EVERY gate finding: what to change, where, and how to verify the fix`,
+		`— the report returns to the main agent, which uses your instructions to drive the fix.`,
+		...(options.documenterPending
+			? [
+				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding:`,
+				`record it under "## Documentation notes" and emit the standalone line DOCUMENTATION: NEEDED,`,
+				`or DOCUMENTATION: CLEAN when no documentation update is needed.`,
+			]
+			: [
+				`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");
+}