@ferris1225/pi-subagents 4.1.13 → 4.1.15

package/src/thread-lifecycle.ts

@@ -42,6 +42,7 @@ import {
 	failedStartResult,
 	formatCompletionBlock,
 	modelLevelTakeoverNote,
+	reviewFailFollowUpNote,
 	queuedResult,
 } from "./format.ts";
 import {
@@ -220,16 +221,19 @@ export function ownsResumeReservation(
 	);
 }
 
-/** Fire-and-forget durable checkpoint write. The live session keeps working
- * when the manifest is unwritable; only cross-reload resume is degraded. */
+/** Fire-and-forget durable checkpoint. Parked threads stay resumable across
+ * reloads; a settled thread drops its record so the manifest only exists
+ * while unfinished work needs it. The live session keeps working when the
+ * manifest is unwritable; only cross-reload resume is degraded. */
 export function persistThreadCheckpoint(
 	runtime: SubagentRuntime,
 	thread: SubagentThread,
 	state: "parked" | "completed" | "failed",
 ): void {
-	void upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state)).catch(
-		() => undefined,
-	);
+	const write = state === "parked"
+		? upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state))
+		: removeThreadRecord(runtime.configPath, thread.id);
+	void write.catch(() => undefined);
 }
 
 const WORKTREE_ISOLATION_INSTRUCTIONS =
@@ -246,27 +250,6 @@ export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
 	return isWriteCapableAgent(agent);
 }
 
-/** A direct reviewer otherwise cannot infer enabled-role availability from its
- * isolated task. Managed internal gates receive the same contract in their
- * generated briefs. Advisory reviews still emit neither machine marker. */
-function withEnabledDocumenterReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: documenter is enabled. In gate reviews, documentation drift is non-gating: emit DOCUMENTATION: NEEDED with ## Documentation notes, or DOCUMENTATION: CLEAN when no sync is needed. Advisory reviews still emit neither VERDICT nor DOCUMENTATION markers.`.trim(),
-	};
-}
-
-/** The dispatcher explicitly requested a report-only review: forbid the gate
- * markers at the source and (in dispatch) refuse to chain on them anyway. */
-function withAdvisoryReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}
-
-Runtime workflow context: this dispatch is advisory. Report findings only; do not emit VERDICT or DOCUMENTATION markers — the runtime will not act on them.`.trim(),
-	};
-}
-
 export interface DispatchEnvironment {
 	ctx: ExtensionContext;
 	config: SubagentsConfig;
@@ -296,7 +279,6 @@ export interface StartBackgroundOptions {
 	environment?: DispatchEnvironment;
 	seed?: SessionSeed;
 	resumeReservation?: ResumeReservation;
-	advisoryReview?: boolean;
 }
 
 export type StartBackgroundInternal = (
@@ -426,15 +408,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		if (!discoveredAgent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
-		const resolvedAgent = resolveLiveAgentTools(discoveredAgent);
-		const advisoryReview = startOptions.advisoryReview ?? existingThread?.advisoryReview ?? false;
-		const agent = agentName === "reviewer"
-			? advisoryReview
-				? withAdvisoryReviewContract(resolvedAgent)
-				: runAgents.some((candidate) => candidate.name === "documenter")
-					? withEnabledDocumenterReviewContract(resolvedAgent)
-					: resolvedAgent
-			: resolvedAgent;
+		const agent = resolveLiveAgentTools(discoveredAgent);
 		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, cleaner, or documenter.`),
@@ -528,7 +502,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			thread.executionCwd = executionCwd;
 			thread.thinkingLevel = thinkingLevel;
 			thread.isolation = isolation;
-			thread.advisoryReview = advisoryReview;
 			thread.worktree = worktree;
 			thread.state = "queued";
 			thread.control = control;
@@ -552,7 +525,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				executionCwd,
 				thinkingLevel,
 				isolation,
-				advisoryReview,
 				worktree,
 				state: "queued",
 				control,
@@ -670,13 +642,13 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				if (thread.lifecycleOperation === "stop") return;
 
 				// A shutdown can win in the microtask gap after the top-level RPC
-				// settles. Do not launch an obsolete documenter/reviewer or replace the
+				// settles. Do not launch an obsolete downstream gate 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);
 				let workflowOutcome: ManagedWorkflowOutcome | undefined;
-				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability, thread.advisoryReview);
+				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability);
 					if (workflowPlan && runtime.sessionActive) {
 						// The continuation is runtime-initiated (gate review,
 						// documentation sync): release this generation's
@@ -801,6 +773,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						if (needsFullFinal) {
 							block += `\n\n${formatCompletionBlock(result, runConfig.maxResultLines, originalCwd)}`;
 						}
+						if (finalVerdict === "fail") {
+							block += `\n\n${reviewFailFollowUpNote()}`;
+						}
 						if (modelLevel) block += `\n\n${modelLevelTakeoverNote(result, { runId })}`;
 						runtime.sendCompletionGroup([{
 							agent: `managed workflow (${result.agent})`,
@@ -816,7 +791,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						agent: result.agent,
 						block: modelLevel
 							? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
-							: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
+							: result.agent === "reviewer" && reviewVerdict(getResultOutput(result)) === "fail"
+								? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${reviewFailFollowUpNote()}`
+								: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
 						triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
 						usage: result.usage,
 					};
@@ -1290,7 +1267,6 @@ function createRestoredThread(
 		executionCwd: record.executionCwd,
 		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),
 		isolation: record.isolation,
-		advisoryReview: false,
 		worktree,
 		state,
 		control: new RpcRunControl(record.task, record.generation),
@@ -1320,15 +1296,20 @@ function createRestoredThread(
 	return thread;
 }
 
-/** Rebuild parked and settled threads from the durable manifest after a reload
- * or restart. Orphaned children recorded by the previous process are killed
- * first; records whose retained session vanished drop out with their
- * artifacts. Returns the restored run ids. */
+/** Rebuild interrupted (parked) threads from the durable manifest after a
+ * reload or restart. Orphaned children recorded by the previous process are
+ * killed first; records whose retained session vanished — and settled records
+ * left by older versions, which hold no work worth resuming — drop out with
+ * their artifacts. Returns the restored run ids. */
 export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<number[]> {
 	const records = await readThreadRecords(runtime.configPath);
 	const restoredIds: number[] = [];
 	for (const record of records) {
 		if (runtime.threads.has(record.runId) || monitor.findRun(record.runId)) continue;
+		if (record.state !== "parked") {
+			await discardRestoredRecord(runtime, record);
+			continue;
+		}
 		// A child orphaned by reload/crash may still hold the retained session.
 		// The on-disk session checkpoint is what survives; kill the writer.
 		for (const pid of record.childPids) {
@@ -1348,33 +1329,29 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 		// A worktree thread whose isolated filesystem is gone cannot continue its
 		// isolation invariant; surface it as failed instead of pretending.
 		const state: ThreadState = worktree
-			? record.state
+			? "parked"
 			: record.isolation === "worktree" && record.worktree
 				? "failed"
-				: record.state;
+				: "parked";
 		const thread = createRestoredThread(runtime, record, worktree, state);
 		runtime.threads.set(record.runId, thread);
 		runtime.sessionDirs.add(record.sessionDir!);
-		if (state === "parked") {
-			monitor.restoreRun({
-				id: record.runId,
-				agent: record.agentName,
-				task: record.task,
-				status: "parked",
-				elapsedMs: record.elapsedMs,
-				isolation: record.isolation,
-				...(record.worktree
-					? {
-						integrationStatus: record.worktree.state === "active"
-							? ("pending" as const)
-							: record.worktree.state,
-						...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
-					}
-					: {}),
-			});
-		} else if (thread.lastResult) {
-			runtime.registerRunResult(record.runId, thread.lastResult);
-		}
+		monitor.restoreRun({
+			id: record.runId,
+			agent: record.agentName,
+			task: record.task,
+			status: "parked",
+			elapsedMs: record.elapsedMs,
+			isolation: record.isolation,
+			...(record.worktree
+				? {
+					integrationStatus: record.worktree.state === "active"
+						? ("pending" as const)
+						: record.worktree.state,
+					...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
+				}
+				: {}),
+		});
 		restoredIds.push(record.runId);
 	}
 	return restoredIds;

package/src/tools.ts

@@ -106,7 +106,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 						const context = hadRetainedSession
 							? "the same retained session and prior context are preserved"
 							: "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 };
+						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. It runs in the background — keep working; the result resumes you automatically.` }], details: {} };
 					}
 				}
 			} catch (error) {

package/src/workflow.ts

@@ -1,16 +1,15 @@
 /**
  * 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.
+ * Successful top-level worker/cleaner runs continue through one independent
+ * code review gate. A failing managed gate continues into the reviewer fix
+ * stage: the same retained reviewer session gets write access and applies its
+ * own fix instructions, so nobody outside the gate has to guess what satisfies
+ * it. Direct reviewer results never chain — a failing direct gate returns its
+ * findings to the main agent, which owns that fix decision. Documentation
+ * drift is an ordinary gate finding; dispatching a documenter stays the main
+ * agent's call. 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";
@@ -18,8 +17,6 @@ import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } fro
 import { formatUsageCompact, sumUsage } from "./monitor.ts";
 
 export interface WorkflowAgentAvailability {
-	cleaner: boolean;
-	documenter: boolean;
 	reviewer: boolean;
 	writer: boolean;
 }
@@ -29,131 +26,122 @@ export function workflowAgentAvailability(
 ): 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;
 }
 
+/** Fixed cap on reviewer fix → re-review rounds inside one managed workflow.
+ * The loop converges by itself when reviews pass; the cap only stops
+ * pathological burn and hands the still-failing gate back to the main agent. */
+export const MAX_REVIEW_FIX_ROUNDS = 3;
+
 /** 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. */
+ * around a complete writer workflow or a reviewer that needs a stable diff. */
 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.
+	// a managed writer's pending diff.
 	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.
+		// this review is advisory: a gate over a moving diff is unsound.
 		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. */
+/** Classify only healthy top-level writer results; everything else delivers
+ * directly, including every reviewer result — a direct reviewer dispatch never
+ * starts another child. A failing managed gate is expanded by the workflow
+ * itself into the reviewer fix stage. */
 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;
+		if (!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),
-				`---`,
-				``,
-			]
-			: []),
-	];
+/** Build the code gate that runs directly after a top-level writer. Reports
+ * carry intent; the actual pending diff remains authoritative. */
+export function buildFinalReviewBrief(initialResult: SingleResult): 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 — including documentation drift —:`,
+		`what to change, where, and how to verify the fix. A failing gate continues into your own write-enabled fix stage,`,
+		`so make every instruction executable exactly as written.`,
+		`Surface the COMPLETE finding set in this one pass — scan the full changed surface before the verdict;`,
+		`do not ration findings across later rounds.`,
+		`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");
+}
+
+/** Build the follow-up brief for the reviewer fix stage: the same retained
+ * reviewer session continues with its read-only boundary lifted and applies
+ * its own fix instructions. The workflow continues with a fresh re-review. */
+export function buildReviewerFixBrief(gateOutput: string): string {
+	return [
+		`Fix stage: your gate review returned REVIEW_FAIL. You now have full write access in this same session.`,
+		`Apply every one of your own fix instructions now — exactly the changes you specified, nothing broader.`,
+		`Then re-check the code your fixes touch, so the next scan does not open with your own regression, and run`,
+		`the narrowest decisive checks (type check, focused tests) to verify.`,
+		``,
+		`Your gate review:`,
+		`---`,
+		gateOutput,
+		`---`,
+		``,
+		`Report:`,
+		`## Fixed`,
+		`- each finding → the exact fix applied (path + what changed)`,
+		`## Verification`,
+		`- checks actually run and their results`,
+		`Do not emit another VERDICT; a fresh gate re-reviews the diff after you.`,
+	].join("\n");
+}
+
+/** Fresh gate over the updated diff after a fix round. The re-review runs in a
+ * brand-new context so it cannot inherit the previous pass's blind spots, and
+ * it must rescan the complete surface so new findings surface now, not in a
+ * later round. */
+export function buildReReviewBrief(fixResult: SingleResult, round: number): string {
 	return [
-		`Final documentation sync: the review gate settled and you are the last managed stage before delivery.`,
+		`Fresh re-review after fix round ${round}: re-scan the COMPLETE pending diff from scratch.`,
+		`Earlier reviews and fix reports are context, not proof — do not inherit their conclusions.`,
 		``,
-		...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.`,
+		`The fix stage reported:`,
+		`---`,
+		getResultOutput(fixResult),
+		`---`,
+		``,
+		`Run \`git status\` and \`git diff\` and judge the actual pending code, including side effects of the fixes.`,
+		`Surface the complete finding set in this one pass — a defect this scan should have caught must not appear later.`,
+		`Remain read-only. Attach a concrete fix instruction to EVERY finding; a failing gate continues into another`,
+		`write-enabled fix stage.`,
+		`End with exactly one standalone machine verdict line:`,
+		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
 	].join("\n");
 }
 
@@ -161,8 +149,8 @@ export function buildFinalDocumenterBrief(
  * 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.
+ * "final review"). runId is optional only for synthetic steps that never
+ * spawned a child.
  */
 export interface ChainStep {
 	runId?: number;
@@ -171,12 +159,14 @@ export interface ChainStep {
 }
 
 export interface ManagedWorkflowOutcome {
-	kind: ManagedWorkflowKind;
 	steps: ChainStep[];
 }
 
-function workflowResultStatus(result: SingleResult): string {
+function workflowResultStatus(result: SingleResult, relation?: string): string {
 	if (isFailedResult(result)) return "failed";
+	// The fix stage is reviewer-named writer work: judge it by outcome, not by
+	// the verdict contract its review stage was held to.
+	if (relation === "review fix") return "completed";
 	if (result.agent === "reviewer") {
 		const verdict = reviewVerdict(getResultOutput(result));
 		return verdict ? verdict.toUpperCase() : "NO_VERDICT";
@@ -186,7 +176,7 @@ function workflowResultStatus(result: SingleResult): string {
 
 function workflowStepLine(step: ChainStep): string {
 	const id = step.runId !== undefined ? `#${step.runId} ` : "";
-	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result)}`;
+	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result, step.relation)}`;
 }
 
 function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): void {
@@ -197,52 +187,14 @@ function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): voi
 	lines.push(`Per-run details: subagent_status ${ids.join(" ")}`);
 }
 
-/** One clear final delivery for post-writer and direct reviewer → documenter workflows. */
+/** One clear final delivery for managed writer → gate workflows. */
 export function formatManagedWorkflowSummary(
 	steps: readonly ChainStep[],
 	terminalResult: SingleResult = steps[steps.length - 1]!.result,
+	terminalRelation: string = steps[steps.length - 1]!.relation,
 ): string {
 	const route = steps.map((step) => step.result.agent).join(" → ");
-	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult)}`, "", ...steps.map(workflowStepLine)];
+	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult, terminalRelation)}`, "", ...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");
-}