@ferris1225/pi-subagents 4.1.1 → 4.1.2

package/src/fixloop.ts

@@ -1,16 +1,15 @@
 /**
- * Auto-fix loop: when a reviewer returns REVIEW_FAIL, the extension dispatches a
- * worker (briefed with the review's concrete findings) and then a reviewer
- * re-review, repeating up to maxFixRounds times before waking the main agent with
- * the full chain. The reviewer stays read-only and in its own context; the loop
- * is orchestrated by the extension layer, not by the reviewer itself, so the
- * independence guarantee (no self-confirmation bias) is preserved.
+ * Managed workflow policy and handoff formatting.
  *
- * The main agent is never woken mid-loop: the reviewer's FAIL result is intercepted
- * before delivery, the chain runs in the background, and only the final group
- * (initial review → worker fixes → re-reviews) is delivered at the end.
+ * Successful top-level writers can continue through documentation sync and an
+ * independent final review. A direct passing reviewer is also forced through
+ * documentation sync plus a fresh review when documenter is enabled. Any final
+ * gate failure may then use the established worker → optional documenter →
+ * reviewer fix rounds. Internal steps are launched by dispatch directly, so
+ * they never re-enter this top-level 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 { extractKeyFragments, formatUsageCompact, sumUsage } from "./monitor.ts";
 import type { SubagentsConfig } from "./config.ts";
@@ -31,12 +30,92 @@ export function shouldTriggerFixLoop(result: SingleResult, config: SubagentsConf
 	// child happened to emit, which could end in a stray `VERDICT: REVIEW_FAIL`.
 	// Guard explicitly in addition to isFailedResult so the intent is clear and
 	// a future change to isFailedResult can never let a crashed reviewer start a
-	// phantom auto-fix chain (and re-add a run controller id that was deleted in
-	// the catch path).
+	// phantom auto-fix chain.
 	if (result.dispatchFailed) return false;
 	return reviewVerdict(getResultOutput(result)) === "fail";
 }
 
+export interface WorkflowAgentAvailability {
+	worker: boolean;
+	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 {
+		worker: names.has("worker"),
+		cleaner: names.has("cleaner"),
+		documenter: names.has("documenter"),
+		reviewer: names.has("reviewer"),
+		writer: agents.some(isWriteCapableAgent),
+	};
+}
+
+export type ManagedWorkflowKind = "auto-fix" | "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 or maxFixRounds=0. 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. */
+export function getManagedWorkflowPlan(
+	result: SingleResult,
+	config: SubagentsConfig,
+	availability: WorkflowAgentAvailability,
+): ManagedWorkflowPlan | undefined {
+	if (result.parked || 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",
+		};
+	}
+	if (result.agent === "documenter") {
+		return availability.reviewer
+			? { kind: "post-writer", initialRelation: "documentation pass" }
+			: undefined;
+	}
+	if (result.agent !== "reviewer") return undefined;
+
+	const verdict = reviewVerdict(getResultOutput(result));
+	if (verdict === "pass" && availability.documenter && availability.reviewer) {
+		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
+	}
+	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result, config)) {
+		return { kind: "auto-fix", initialRelation: "initial review" };
+	}
+	return undefined;
+}
+
 /**
  * Build the worker task brief for one fix round from a reviewer's findings.
  * The worker gets the full review text so it can address concrete file:line
@@ -56,20 +135,83 @@ 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 documentation sync and final review.`,
 		`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 main agent will be woken with the full chain.`,
+			: `This is the last auto-fix round; optional documentation sync and a fresh reviewer still run before final delivery.`,
 	].join("\n");
 }
 
+interface DocumentationBriefOptions {
+	title: string;
+	reports: Array<{ label: string; result: SingleResult }>;
+	closing: string;
+}
+
+function buildDocumentationBrief(options: DocumentationBriefOptions): string {
+	const reportSections = options.reports.flatMap(({ label, result }) => [
+		`${label}:`,
+		`---`,
+		getResultOutput(result),
+		`---`,
+		``,
+	]);
+	return [
+		options.title,
+		``,
+		...reportSections,
+		`Inspect the actual git diff (the complete pending diff) and relevant implementation; the report is only a lead.`,
+		`Synchronize stale README/docs, examples, API comments, docstrings, and explanatory comments with the behavior that will be committed.`,
+		`Change documentation surfaces only; never alter runtime behavior or tests to make prose true.`,
+		`Make zero edits when the diff creates no documentation drift.`,
+		`Do NOT commit, push, publish, tag, or release; do not bump versions. ${options.closing}`,
+		`Report exact documentation/comment paths changed, or state explicitly that no sync was needed.`,
+	].join("\n");
+}
+
+/** Build the pre-commit documentation handoff after one auto-fix worker. */
+export function buildDocumenterTaskBrief(
+	workerResult: SingleResult,
+	round: number,
+	reviewerResult?: SingleResult,
+): string {
+	return buildDocumentationBrief({
+		title: `Documentation sync after auto-fix round ${round}.`,
+		reports: [
+			...(reviewerResult ? [{ label: "The triggering reviewer reported", result: reviewerResult }] : []),
+			{ label: "The worker reported", result: workerResult },
+		],
+		closing: "a fresh reviewer gate runs after you.",
+	});
+}
+
+/** Build the automatic documentation stage after a successful top-level writer. */
+export function buildPostWriterDocumenterBrief(writerResult: SingleResult): string {
+	return buildDocumentationBrief({
+		title: `Documentation sync after successful top-level ${writerResult.agent}.`,
+		reports: [{ label: `The ${writerResult.agent} reported`, result: writerResult }],
+		closing: "the managed workflow owns any final reviewer and delivery.",
+	});
+}
+
+/** A direct passing review cannot be the final gate while documenter is enabled:
+ * the preliminary report is context, but the actual pending diff is authoritative. */
+export function buildReviewPassDocumenterBrief(reviewerResult: SingleResult): string {
+	return buildDocumentationBrief({
+		title: "Documentation sync required before accepting a direct passing review.",
+		reports: [{ label: "The preliminary reviewer reported", result: reviewerResult }],
+		closing: "the preliminary pass is not final and a fresh reviewer gate runs after you.",
+	});
+}
+
 /**
  * One step of an auto-fix chain 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 chain ("initial review", "fix round 1",
- * "re-review round 2"). runId is undefined for steps that never spawned a run
- * (e.g. an unknown agent).
+ * "re-review round 2"). runId is optional only for synthetic steps that never
+ * spawned a child.
  */
 export interface ChainStep {
 	runId?: number;
@@ -77,6 +219,11 @@ export interface ChainStep {
 	relation: string;
 }
 
+export interface ManagedWorkflowOutcome {
+	kind: ManagedWorkflowKind;
+	steps: ChainStep[];
+}
+
 /** Max distinguishing fragments kept in a one-line chain summary. */
 export const CHAIN_SUMMARY_FRAGMENTS_MAX = 3;
 
@@ -87,58 +234,124 @@ export function chainKeyFragments(result: SingleResult): string[] {
 	return extractKeyFragments(getResultOutput(result)).slice(0, CHAIN_SUMMARY_FRAGMENTS_MAX);
 }
 
-/**
- * Condensed, readable summary of a completed auto-fix chain: one line per step
- * (run id, role, verdict / what changed) plus aggregate usage. Full per-step
- * reports stay addressable via `subagent_status <id>`; the caller appends the
- * final step's full block only when its detail is actionable (FAIL verdict or a
- * crash), so the delivered message stays short instead of stacking every
- * round's raw output.
- */
-export function formatChainSummary(steps: readonly ChainStep[]): string {
-	const rounds = steps.filter((step) => step.relation.startsWith("fix round")).length;
-	const last = steps[steps.length - 1];
-	const stepStatus = (step: ChainStep): string => {
-		const { result } = step;
-		if (result.agent === "reviewer") {
-			const verdict = reviewVerdict(getResultOutput(result));
-			if (verdict) return verdict.toUpperCase();
-		}
-		return isFailedResult(result) ? "failed" : "completed";
-	};
-	const lines = [
-		`## Auto-fix chain: ${Math.max(1, rounds)} round${rounds === 1 ? "" : "s"} — final ${stepStatus(last)}`,
-		"",
-	];
-	for (const step of steps) {
-		const fragments = chainKeyFragments(step.result);
-		const suffix =
-			fragments.length > 0
-				? step.result.agent === "worker"
-					? ` — changed: ${fragments.join(" · ")}`
-					: ` — ${fragments.join(" · ")}`
-				: "";
-		const id = step.runId !== undefined ? `#${step.runId} ` : "";
-		lines.push(`- ${id}${step.result.agent} · ${step.relation} · ${stepStatus(step)}${suffix}`);
+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 fragments = chainKeyFragments(step.result);
+	const writer = step.result.agent === "worker" || step.result.agent === "cleaner" || step.result.agent === "documenter";
+	const suffix = fragments.length > 0
+		? writer
+			? ` — changed: ${fragments.join(" · ")}`
+			: ` — ${fragments.join(" · ")}`
+		: "";
+	const id = step.runId !== undefined ? `#${step.runId} ` : "";
+	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result)}${suffix}`;
+}
+
+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(`Full per-run reports (output, usage, failed tools): subagent_status ${ids.join(" ")}`);
+}
+
+/** Condensed compatibility summary for a direct REVIEW_FAIL auto-fix chain. */
+export function formatChainSummary(
+	steps: readonly ChainStep[],
+	terminalResult: SingleResult = steps[steps.length - 1]!.result,
+): string {
+	const rounds = steps.filter((step) => step.relation.startsWith("fix round")).length;
+	const lines = [
+		`## Auto-fix chain: ${Math.max(1, rounds)} round${rounds === 1 ? "" : "s"} — final ${workflowResultStatus(terminalResult)}`,
+		"",
+		...steps.map(workflowStepLine),
+	];
+	appendWorkflowFooter(lines, steps);
+	return lines.join("\n");
+}
+
+/** One clear final delivery for all newly managed writer/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 fixRounds = steps.filter((step) => step.relation.startsWith("fix round")).length;
+	const roundNote = fixRounds > 0 ? ` · ${fixRounds} fix round${fixRounds === 1 ? "" : "s"}` : "";
+	const lines = [
+		`## Managed workflow: ${route}${roundNote} — final ${workflowResultStatus(terminalResult)}`,
+		"",
+		...steps.map(workflowStepLine),
+	];
+	appendWorkflowFooter(lines, steps);
 	return lines.join("\n");
 }
 
+/** Build the first independent final gate after a top-level writer or required
+ * post-pass documentation sync. Reports carry intent; the actual pending diff
+ * remains authoritative. */
+export function buildFinalReviewBrief(
+	initialResult: SingleResult,
+	documenterResult?: SingleResult,
+): string {
+	const documenterSection = documenterResult
+		? [
+			``,
+			`The documenter's full sync report:`,
+			`---`,
+			getResultOutput(documenterResult),
+			`---`,
+		]
+		: [];
+	return [
+		`Fresh final gate for a managed ${initialResult.agent} workflow.`,
+		``,
+		`The top-level ${initialResult.agent}'s full report:`,
+		`---`,
+		getResultOutput(initialResult),
+		`---`,
+		...documenterSection,
+		``,
+		`Run \`git status\` and \`git diff\` and inspect the actual pending code and documentation; reports are context, not proof.`,
+		`Remain read-only. Verify correctness, regressions, tests, documentation drift, and that documenter was the last writer when it ran.`,
+		`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");
+}
+
 /**
  * The re-review brief handed to the reviewer after a worker fix round. Includes
- * the prior review AND the worker's report so the reviewer can adjudicate
- * rejections instead of restating findings. The convergence contract keeps
- * rounds from ping-ponging: rule on the open findings once, add only defects
- * this round's edits introduced, never re-open a verified resolution.
+ * the prior review, worker report, and optional documenter report so the
+ * reviewer can adjudicate rejections instead of restating findings. The
+ * convergence contract keeps rounds from ping-ponging: rule on the open
+ * findings once, add only defects this round's edits introduced, never re-open
+ * a verified resolution.
  */
-export function buildReReviewBrief(reviewerResult: SingleResult, round: number, workerResult: SingleResult): string {
+export function buildReReviewBrief(
+	reviewerResult: SingleResult,
+	round: number,
+	workerResult: SingleResult,
+	documenterResult?: SingleResult,
+): string {
 	const review = getResultOutput(reviewerResult);
 	const workerReport = getResultOutput(workerResult);
+	const documenterSection = documenterResult
+		? [
+			``,
+			`The documenter's pre-commit sync report:`,
+			`---`,
+			getResultOutput(documenterResult),
+			`---`,
+		]
+		: [];
 	return [
 		`Re-review after auto-fix round ${round}.`,
 		``,
@@ -151,6 +364,7 @@ export function buildReReviewBrief(reviewerResult: SingleResult, round: number,
 		`---`,
 		workerReport,
 		`---`,
+		...documenterSection,
 		``,
 		`Rule on EVERY previous finding: resolved, or still open. A finding the worker rejected must be`,
 		`adjudicated ONCE — accept the rejection unless you can concretely refute the worker's reasoning;`,

package/src/index.ts

@@ -3,8 +3,8 @@
  *
  * Assembly point: builds the shared runtime and registers everything.
  * The heavy lifting lives in focused modules:
- *   - dispatch.ts         — the `subagent` tool contract and auto-fix chain
- *   - thread-lifecycle.ts — queued generations, resume/fork, isolation settlement
+ *   - dispatch.ts         — tool contract, managed role policy, internal steps
+ *   - thread-lifecycle.ts — stable generations, controls, final integration/delivery
  *   - tools.ts            — subagent_control / subagent_wait / status / stop
  *   - announcements.ts — session-start recovery, notices, and widget install
  *   - widget.ts        — active-only TUI run status
@@ -86,7 +86,7 @@ export default function (pi: ExtensionAPI): void {
 			enabledNames: config.enabledAgents,
 			projectTrusted: ctx.isProjectTrusted?.() === true,
 		});
-		const directive = buildDelegationDirective(agents);
+		const directive = buildDelegationDirective(agents, { maxFixRounds: config.maxFixRounds });
 		if (!directive) return undefined;
 		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
 	});

package/src/monitor.ts

@@ -49,15 +49,15 @@ export interface RunView {
 	startedAt?: number;
 	/** Epoch ms when the run finished (set on "done"/"failed"). */
 	endedAt?: number;
-	/** When set, this run belongs to an auto-fix chain (e.g. worker fixing a reviewer's findings). */
+	/** When set, this is an internal managed-workflow step. */
 	groupId?: string;
 	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
 	relationLabel?: string;
-	/** Owning run for chain children: the triggering reviewer whose row represents the chain. */
+	/** Stable owning run whose row represents the whole managed workflow. */
 	parentRunId?: number;
 }
 
-/** Optional chain metadata for runs spawned by an auto-fix loop. */
+/** Optional metadata for documenter/reviewer/fix children of a stable parent run. */
 export interface RunChainMeta {
 	groupId?: string;
 	relationLabel?: string;
@@ -503,6 +503,15 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Reflect the currently owned internal stage when a managed parent is parked
+	 * or inspected between children; the stable id and original task stay intact. */
+	setAgent(id: number, agent: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.agent = agent;
+		this.notify();
+	}
+
 	/** Update the objective shown for a queued retarget or resumed generation. */
 	setTask(id: number, task: string): void {
 		const run = this.find(id);

package/src/prompt.ts

@@ -11,22 +11,42 @@ function bullets(lines: readonly string[]): string {
 	return lines.map((line) => `- ${line}`).join("\n");
 }
 
-export function buildDelegationDirective(agents: AgentConfig[]): string {
+export function buildDelegationDirective(
+	agents: AgentConfig[],
+	options: { maxFixRounds?: number } = {},
+): string {
 	if (agents.length === 0) return "";
 
 	const catalog = agents.map(formatCatalogEntry).join("\n");
 	const hasExplorer = agents.some((agent) => agent.name === "explorer");
 	const hasWorker = agents.some((agent) => agent.name === "worker");
 	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
+	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
 	const hasMultiple = agents.length > 1;
-	const worktreeTargets = hasWorker && hasCleaner
-		? "worker, cleaner, or another"
-		: hasWorker
-			? "worker or another"
-			: hasCleaner
-				? "cleaner or another"
-				: "a";
+	const autoFixEnabled = hasWorker && (options.maxFixRounds ?? 1) > 0;
+	const codeWriterNames = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+	];
+	const reviewedWriterNames = [
+		...codeWriterNames,
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const automaticWriterRoute = [
+		...(hasDocumenter ? ["documenter"] : []),
+		...(hasReviewer ? ["reviewer"] : []),
+	].join(" → ");
+	const namedWorktreeTargets = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const worktreeTargets = namedWorktreeTargets.length === 0
+		? "a"
+		: namedWorktreeTargets.length === 1
+			? `${namedWorktreeTargets[0]} or another`
+			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
 		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
@@ -40,12 +60,17 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only when the user explicitly authorizes cleanup/removal/simplification edits, including a requested maintenance pass. It gathers evidence, then applies every safe proven in-scope cut; zero edits is valid. Generic or read-only audit, inspect, report, review, code-health, plan, proposed-solution, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+			]
+			: []),
+		...(hasDocumenter
+			? [
+				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, release state, or ${hasReviewer ? "the final reviewer gate" : "direct final verification"}.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for generic/read-only assessments and as the fresh independent pre-commit gate for non-trivial diffs${hasCleaner ? ", including cleaner edits" : ""}. Advisory findings do not authorize follow-up edits; only gate verdicts can enter auto-fix.`,
+				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
 			]
 			: []),
 		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
@@ -55,7 +80,7 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
 			]
 			: []),
-		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
+		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}${hasDocumenter ? "; documenter defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
 		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
 		"Trust but verify: inspect actual changes/results before reporting completion.",
 	];
@@ -69,9 +94,19 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
+		...(automaticWriterRoute && reviewedWriterNames.length > 0
+			? [
+				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
+			]
+			: []),
 		...(hasReviewer
 			? [
-				"Send every non-trivial diff through one fresh read-only `reviewer` gate before reporting done. Resolve every finding; do not bypass the configured auto-fix/re-review cap.",
+				...(hasDocumenter
+					? [
+						`A direct REVIEW_PASS is preliminary: runtime runs documenter on the pending diff, then a fresh reviewer. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not initial docs/review." : "cannot start fixes while worker/fix rounds are disabled."}`,
+					]
+					: []),
+				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
 				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),

package/src/rpc-run.ts

@@ -66,10 +66,13 @@ export interface RpcSingleResult {
 	 * model execution. This remains main-model handoff eligible even when an
 	 * earlier, aborted objective left assistant text in the session. */
 	rpcPromptRejected?: boolean;
-	/** Handshake or initial prompt ACK never came back. This is a startup/
-	 * transport miss, not a model/provider failure. */
+	/** Startup handshake failed before the initial prompt was dispatched. This
+	 * transport miss is safe to retry and is not a model/provider failure. */
 	rpcStartupFailed?: boolean;
-	/** The child accepted a prompt; startup retries must never duplicate it. */
+	/** The parent dispatched the initial prompt command. Until its response is
+	 * observed, Pi may already be running it, so startup retries must not replay it. */
+	rpcPromptDispatched?: boolean;
+	/** The child confirmed prompt acceptance (or emitted agent activity). */
 	rpcPromptAccepted?: boolean;
 	/** Pi emitted agent/turn/model/tool activity for this attempt. */
 	rpcActivity?: boolean;
@@ -415,6 +418,13 @@ interface RpcResponse {
 	data?: unknown;
 }
 
+class RpcCommandRejectedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RpcCommandRejectedError";
+	}
+}
+
 interface PendingRequest {
 	resolve: (response: RpcResponse) => void;
 	reject: (error: Error) => void;
@@ -642,7 +652,9 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				},
 			);
 		}).then((response) => {
-			if (!response.success) throw new Error(response.error || `RPC ${response.command} failed.`);
+			if (!response.success) {
+				throw new RpcCommandRejectedError(response.error || `RPC ${response.command} failed.`);
+			}
 			return response;
 		});
 	};
@@ -734,7 +746,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				result.exitCode = 1;
 				result.stopReason = "error";
 				result.errorMessage = `Replacement prompt was rejected: ${promptError.message}`;
-				if (!isRpcCommandTimeoutError(promptError.message)) result.rpcPromptRejected = true;
+				if (promptError instanceof RpcCommandRejectedError) result.rpcPromptRejected = true;
 				finish();
 				terminate();
 				if (!closed) await processClosed.promise;
@@ -1076,7 +1088,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				result.stopReason = "error";
 				result.errorMessage = error.message;
 				if (startup) result.rpcStartupFailed = true;
-				else result.rpcPromptRejected = true;
+				else if (error instanceof RpcCommandRejectedError) result.rpcPromptRejected = true;
 				finish();
 				terminate();
 			};
@@ -1091,11 +1103,15 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				}
 			}
 			if (!finished && !initialPromptResolved && !control?.isParkRequested() && !control?.isStopRequested()) {
+				// Pi starts the agent immediately after prompt preflight, before its
+				// success response necessarily reaches stdout. From this point on, a
+				// missing ACK is ambiguous and must never be recovered by replay.
+				result.rpcPromptDispatched = true;
 				void send({ type: "prompt", message: asPlainTextRpcPrompt(options.prompt) }).then(
 					() => resolveInitialPrompt(true),
 					(error) => {
 						const promptError = error instanceof Error ? error : new Error(String(error));
-						failBeforePrompt(promptError, isRpcCommandTimeoutError(promptError.message));
+						failBeforePrompt(promptError, false);
 					},
 				);
 			}