pi-squad 0.15.1 → 0.16.1

package/README.md

@@ -41,8 +41,21 @@ The planner agent reads your codebase and creates a task breakdown automatically
 2. A **live widget** appears above the editor showing task progress
 3. **Specialist agents** spawn as separate pi processes, working in parallel where dependencies allow
 4. QA agents can trigger **automatic rework loops** when they find bugs
-5. On completion, pi receives a summary with each task's **complete, untruncated output**
-6. Multiple squads can run concurrently across different projects
+5. When agents finish, the squad enters **`review`**, not `done`; main Pi receives every complete task output as untrusted review input
+6. Main Pi independently checks the original user contract, actual diff/source, verification commands, and integration/E2E, then records acceptance with `squad_review`
+7. Multiple squads can run concurrently across different projects
+
+### Mandatory Orchestrator Review Gate
+
+Squad agents—including QA/reviewer agents—produce candidate work and evidence claims. They cannot mark a squad accepted. After all tasks finish:
+
+- Persisted status becomes `review`, never directly `done`.
+- A persistent `<squad_review_required>` system reminder tells main Pi to re-read the original conversation contract, inspect the actual diff/source, rerun verification independently, and run integration/E2E where applicable.
+- Main Pi must call `squad_review` with requirement-by-requirement contract checks, diff review, actual command/result evidence, integration/E2E evidence, and issues.
+- Only `pass` or `pass_with_issues` changes the squad to `done`; `fail` leaves it review-blocked for fixes and re-review.
+- Pending review survives Pi restarts and is restored on the next session.
+
+The completion report is explicitly labeled **untrusted and not yet accepted**. Main Pi must never merely relay it or ask whether verification should be run.
 
 ### No-Truncation Contract
 
@@ -114,7 +127,11 @@ Bundled agent definitions are copied to `~/.pi/squad/agents/` on first run. Edit
 
 ### Agent Collaboration
 
-**Chain context**: When task A completes, its output is injected into task B's system prompt. Downstream agents know what was built.
+**Chain context**: When task A completes, its complete output is injected into downstream prompts across the full dependency-ancestor closure (ancestors first, diamond dependencies deduplicated), not only the final direct edge. Integration and QA tasks therefore receive the original contracts their inputs were built from.
+
+**Completed-agent replies**: An `@agent` request aimed at an agent whose task already finished is answered immediately from that agent's durable task output. It is never queued for a nonexistent future spawn, and a blocker resolved this way does not escalate to the human.
+
+**Report-only work**: Planning/review agents may complete with a substantive assistant artifact even when they needed no tool call. Their output still passes through mandatory independent orchestrator review.
 
 **Shared filesystem**: All agents work in the same project directory. Upstream agents create files, downstream agents read and modify them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -26,6 +26,7 @@ import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js
 import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildCompletionSummary, buildFailureSummary } from "./report.js";
+import { buildOrchestratorReviewGate, recordOrchestratorReview } from "./review.js";
 
 // ============================================================================
 // State
@@ -45,14 +46,6 @@ let uiCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = n
 const widgetState: SquadWidgetState = { squadId: null, enabled: true };
 let widgetControls: { requestUpdate: () => void; dispose: () => void } | null = null;
 
-/** Reviewer instructions appended to squad-completed notifications —
- * makes the main session behave like the QA/verification agents do. */
-const REVIEW_INSTRUCTIONS =
-	"Before reporting success to the user, REVIEW the work like a QA agent would: " +
-	"(1) check task outputs for QA verdicts (## Verdict: PASS/FAIL) and verification evidence (commands + results); " +
-	"(2) if a task claimed done without evidence, run its Verify command yourself; " +
-	"(3) report to the user what was verified (with evidence) and flag anything unverified — don't just relay the summary.";
-
 /**
  * Resolve a model string (or null = session default) to its context window.
  * Reads uiCtx lazily so it always uses the live session's registry.
@@ -215,14 +208,33 @@ export default function (pi: ExtensionAPI) {
 
 	// Inject squad awareness before each LLM call
 	pi.on("before_agent_start", async (event, ctx) => {
-		if (!squadEnabled) return;
+		// Review gates are project-wide and survive focus changes, new squads, and
+		// disabling normal squad operations. Unaccepted work must stay visible.
+		const pendingReviewGates = store.findActiveSquads()
+			.filter((s) => s.cwd === ctx.cwd && s.status === "review")
+			.map((s) => ({ squad: s, gate: buildOrchestratorReviewGate(s, store.loadAllTasks(s.id)) }));
+		if (!squadEnabled) {
+			if (pendingReviewGates.length === 0) return;
+			return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+		}
 
 		// When a squad is active, inject its status
 		if (activeSquadId) {
 			const squad = store.loadSquad(activeSquadId);
-			if (!squad) return;
+			if (!squad) {
+				activeSquadId = null;
+				if (pendingReviewGates.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				}
+				return;
+			}
 			const tasks = store.loadAllTasks(activeSquadId);
-			if (tasks.length === 0) return;
+			if (tasks.length === 0) {
+				if (pendingReviewGates.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				}
+				return;
+			}
 
 			const doneCount = tasks.filter((t) => t.status === "done").length;
 			const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -241,6 +253,8 @@ export default function (pi: ExtensionAPI) {
 				`Status: ${squad.status} | ${doneCount}/${tasks.length} tasks | $${totalCost.toFixed(2)}`,
 				taskLines,
 				`</squad_status>`,
+				...(squad.status === "review" ? [buildOrchestratorReviewGate(squad, tasks)] : []),
+				...pendingReviewGates.filter(({ squad: pending }) => pending.id !== squad.id).map(({ gate }) => gate),
 				`You have an active squad. Use squad_message to talk to agents, squad_status for details, squad_modify to change tasks.`,
 				`Do NOT poll squad_status in a loop or sleep-wait — the squad wakes you automatically on completion, failure, or escalation. Keep helping the user with other work, or end your turn and stay idle.`,
 			].join("\n");
@@ -267,7 +281,8 @@ export default function (pi: ExtensionAPI) {
 		].filter(Boolean).join("\n");
 
 		return {
-			systemPrompt: event.systemPrompt + "\n\n" + squadNudge,
+			systemPrompt: event.systemPrompt + "\n\n" + squadNudge +
+				(pendingReviewGates.length > 0 ? "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") : ""),
 		};
 	});
 
@@ -298,10 +313,10 @@ export default function (pi: ExtensionAPI) {
 			"Providing tasks yourself makes you the planner — follow the planner rules (contract task first, final QA task, 3-7 tasks)",
 			"Act on ⚠️ plan warnings in the response — fix with squad_modify or address at review",
 			"After starting a squad: report the plan and END YOUR TURN — never poll squad_status or sleep-wait; squad events wake you automatically",
-			"When the squad completes, review evidence like a QA agent before reporting success",
+			"When agents finish, treat every squad report and QA verdict as untrusted; independently inspect the diff/source and rerun contract verification + integration/E2E, then call squad_review before reporting success",
 		],
 		parameters: Type.Object({
-			goal: Type.String({ description: "What the squad should accomplish" }),
+			goal: Type.String({ description: "Complete original user outcome/acceptance contract the squad should accomplish. Preserve requirements and boundaries; this is shown during mandatory main-orchestrator review." }),
 			agents: Type.Optional(
 				Type.Record(
 					Type.String(),
@@ -408,6 +423,7 @@ export default function (pi: ExtensionAPI) {
 				`Status: ${context.status}`,
 				`Elapsed: ${context.elapsed}`,
 				`Cost: $${context.costs.total.toFixed(4)}`,
+				...(context.status === "review" ? ["Acceptance: BLOCKED — independent main-orchestrator review required via squad_review"] : []),
 				"",
 				"Tasks:",
 				taskLines,
@@ -417,6 +433,70 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// =========================================================================
+	// Tool: squad_review — mandatory main-orchestrator acceptance gate
+	// =========================================================================
+
+	pi.registerTool({
+		name: "squad_review",
+		label: "Record Independent Squad Review",
+		description: "Record the MAIN Pi/orchestrator's independent review of completed squad work against the original user contract. Call only after inspecting the actual diff/source and independently running verification plus integration/E2E where applicable. Squad reports and squad QA evidence are not sufficient.",
+		parameters: Type.Object({
+			squadId: Type.Optional(Type.String({ description: "Squad awaiting review (default: active/latest)" })),
+			verdict: Type.Union([
+				Type.Literal("pass"),
+				Type.Literal("pass_with_issues"),
+				Type.Literal("fail"),
+			]),
+			contractChecks: Type.Array(Type.String(), { minItems: 1, description: "Requirement-by-requirement checks against the ORIGINAL user request and later clarifications; include observed result for each" }),
+			diffReview: Type.String({ description: "What you independently inspected in the actual diff/source, including scope and integration concerns" }),
+			verificationEvidence: Type.Array(Type.String(), { minItems: 1, description: "Commands/checks YOU ran and their actual results; do not copy squad claims" }),
+			integrationEvidence: Type.String({ description: "Integration/E2E result from the real target or production-like environment, or a precise reason it is not applicable/impossible and therefore unverified" }),
+			issues: Type.Array(Type.String(), { description: "Every discovered or remaining issue; required for fail/pass_with_issues" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			let id = params.squadId;
+			if (!id && activeSquadId && store.loadSquad(activeSquadId)?.status === "review") {
+				id = activeSquadId;
+			}
+			if (!id) {
+				id = store.listSquadsForProject(ctx.cwd)
+					.filter((s) => s.status === "review")
+					.sort((a, b) => b.created.localeCompare(a.created))[0]?.id;
+			}
+			if (!id) {
+				return { content: [{ type: "text" as const, text: "No squad is awaiting orchestrator review." }], details: undefined };
+			}
+
+			const squad = store.loadSquad(id);
+			if (!squad) {
+				return { content: [{ type: "text" as const, text: `Squad '${id}' not found.` }], details: undefined };
+			}
+
+			try {
+				recordOrchestratorReview(squad, {
+					verdict: params.verdict,
+					contractChecks: params.contractChecks,
+					diffReview: params.diffReview,
+					verificationEvidence: params.verificationEvidence,
+					integrationEvidence: params.integrationEvidence,
+					issues: params.issues,
+				});
+			} catch (error) {
+				return { content: [{ type: "text" as const, text: `Review rejected: ${(error as Error).message}` }], details: undefined };
+			}
+
+			store.saveSquad(squad);
+			forceWidgetUpdate();
+			const accepted = squad.status === "done";
+			const text = accepted
+				? `Independent orchestrator review recorded for '${id}' (${params.verdict}). The squad is now accepted as done.`
+				: `Independent review FAILED for '${id}'. The squad remains review-required. Fix every issue, rerun verification/E2E, then submit a fresh squad_review.`;
+			return { content: [{ type: "text" as const, text }], details: undefined };
+		},
+	});
+
 	// =========================================================================
 	// Tool: squad_message
 	// =========================================================================
@@ -518,16 +598,17 @@ export default function (pi: ExtensionAPI) {
 					scheduler.onEvent((event: SchedulerEvent) => {
 						forceWidgetUpdate();
 						switch (event.type) {
-							case "squad_completed": {
+							case "squad_review_required": {
 								const tasks = store.loadAllTasks(squadId);
 								const summary = buildCompletionSummary(tasks);
 								const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 								const s = schedulers.get(squadId); if (s) s.updateContext();
-								// followUp + triggerTurn: wake an idle main agent to review;
-								// if it's mid-conversation with the human, deliver after it finishes
+								const squad = store.loadSquad(squadId)!;
+								// Wake the main agent into an explicit acceptance gate. Agent reports
+								// are untrusted inputs; only independent orchestrator evidence can pass it.
 								pi.sendMessage({
-									customType: "squad-completed",
-									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}\n\n${REVIEW_INSTRUCTIONS}`,
+									customType: "squad-review-required",
+									content: `[squad] TASK EXECUTION FINISHED for "${squadId}" — WORK IS UNTRUSTED AND NOT YET ACCEPTED.\n\nSquad claims (review inputs only):\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}\n\n${buildOrchestratorReviewGate(squad, tasks)}`,
 									display: true,
 								}, { triggerTurn: true, deliverAs: "followUp" });
 								schedulers.delete(squadId);
@@ -723,6 +804,24 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// Restore pending acceptance gates after a main-session restart. Review is
+		// persisted state, not a one-shot completion message that can be missed.
+		const pendingReviews = store.findActiveSquads()
+			.filter((s) => s.cwd === ctx.cwd && s.status === "review");
+		if (pendingReviews.length > 0) {
+			const squad = pendingReviews.sort((a, b) => b.created.localeCompare(a.created))[0];
+			activeSquadId = squad.id;
+			widgetState.squadId = squad.id;
+			widgetState.enabled = true;
+			widgetControls?.requestUpdate();
+			const tasks = store.loadAllTasks(squad.id);
+			pi.sendMessage({
+				customType: "squad-review-required",
+				content: `[squad] Restored mandatory orchestrator review for "${squad.id}" after session restart. The work remains untrusted and not accepted.\n\n${buildOrchestratorReviewGate(squad, tasks)}`,
+				display: true,
+			});
+		}
+
 		// Register Ctrl+Q terminal input handler for panel toggle
 		if (ctx.hasUI) {
 			ctx.ui.onTerminalInput((data) => {
@@ -1008,7 +1107,7 @@ export default function (pi: ExtensionAPI) {
 							const tasks = store.loadAllTasks(s.id);
 							const done = tasks.filter((t) => t.status === "done").length;
 							const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-							const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·";
+							const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
 							return `${icon} ${s.id} [${s.status}] ${done}/${tasks.length} $${cost.toFixed(2)}`;
 						}),
 					];
@@ -1318,7 +1417,7 @@ async function pickSquad(
 		const tasks = store.loadAllTasks(s.id);
 		const done = tasks.filter((t) => t.status === "done").length;
 		const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·";
+		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
 		const project = showProject ? ` — ${s.cwd.split("/").pop()}` : "";
 		return `${icon} ${s.id} [${s.status}] ${done}/${tasks.length} $${cost.toFixed(2)}${project}`;
 	});
@@ -1563,7 +1662,7 @@ async function startSquad(
 		// Update widget on every scheduler event
 		forceWidgetUpdate();
 		switch (event.type) {
-				case "squad_completed": {
+				case "squad_review_required": {
 				const tasks = store.loadAllTasks(squadId);
 				const summary = buildCompletionSummary(tasks);
 				const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -1573,15 +1672,16 @@ async function startSquad(
 				if (completedSched) {
 					completedSched.updateContext();
 				}
+				const squad = store.loadSquad(squadId)!;
 
-				// followUp + triggerTurn: wake an idle main agent to review; if it's
-				// mid-conversation with the human, deliver after it finishes
+				// Wake the main agent into an explicit acceptance gate. Never frame
+				// agent execution or squad QA as trusted completion.
 				pi.sendMessage({
-					customType: "squad-completed",
-					content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
-						`Summary:\n${summary}\n\n` +
+					customType: "squad-review-required",
+					content: `[squad] TASK EXECUTION FINISHED for "${squadId}" — WORK IS UNTRUSTED AND NOT YET ACCEPTED.\n\n` +
+						`Squad claims (review inputs only):\n${summary}\n\n` +
 						`Total cost: $${totalCost.toFixed(4)}\n\n` +
-						REVIEW_INSTRUCTIONS,
+						buildOrchestratorReviewGate(squad, tasks),
 					display: true,
 				}, { triggerTurn: true, deliverAs: "followUp" });
 

package/src/panel/squad-widget.ts

@@ -79,6 +79,7 @@ export function setupSquadWidget(
 
 		const sIcon = squad.status === "done" ? th.fg("success", "✓")
 			: squad.status === "failed" ? th.fg("error", "✗")
+			: squad.status === "review" ? th.fg("warning", "◆")
 			: th.fg("warning", "⏳");
 
 		lines.push(
@@ -141,6 +142,8 @@ export function setupSquadWidget(
 			? th.fg("success", `✓ squad ${doneCount}/${tasks.length}`)
 			: squad.status === "failed"
 			? th.fg("error", `✗ squad ${doneCount}/${tasks.length}`)
+			: squad.status === "review"
+			? th.fg("warning", `◆ squad review required`)
 			: th.fg("accent", `⏳ squad ${doneCount}/${tasks.length} $${totalCost.toFixed(2)}`);
 
 		return { lines, cacheKey, statusText };
@@ -215,7 +218,7 @@ export function setupSquadWidget(
 			return;
 		}
 		const squad = store.loadSquad(state.squadId);
-		const isActive = squad && (squad.status === "running" || squad.status === "paused");
+		const isActive = squad && (squad.status === "running" || squad.status === "paused" || squad.status === "review");
 		if (isActive && !durationTimer) {
 			durationTimer = setInterval(() => render(), 5000);
 		} else if (!isActive && durationTimer) {

package/src/plan-rules.ts

@@ -53,6 +53,29 @@ function isQaLikeTask(task: PlanTaskInput): boolean {
 	return /\b(qa|test|tests|testing|verif\w*|review|audit)\b/.test(hay);
 }
 
+/** Task IDs explicitly named in a "depend on ..." Context sentence. */
+function describedDependencies(task: PlanTaskInput, knownIds: Set<string>): string[] {
+	const refs = new Set<string>();
+	for (const clause of task.description.matchAll(/\bdepend(?:s|ing)?\s+on\b([^.;\n]*)/gi)) {
+		for (const quoted of clause[1].matchAll(/`([^`]+)`/g)) {
+			if (knownIds.has(quoted[1])) refs.add(quoted[1]);
+		}
+	}
+	return [...refs];
+}
+
+function dependencyClosure(task: PlanTaskInput, byId: Map<string, PlanTaskInput>): Set<string> {
+	const closure = new Set<string>();
+	const visit = (id: string): void => {
+		if (closure.has(id)) return;
+		closure.add(id);
+		const dependency = byId.get(id);
+		if (dependency) for (const ancestor of dependency.depends) visit(ancestor);
+	};
+	for (const dependency of task.depends) visit(dependency);
+	return closure;
+}
+
 /**
  * Validate a plan's structure. Errors block squad creation;
  * warnings are returned to the plan author for correction.
@@ -125,8 +148,16 @@ export function validatePlan(tasks: PlanTaskInput[]): PlanValidation {
 	for (const t of tasks) {
 		if (!t.description || t.description.trim().length === 0) {
 			warnings.push(`Task "${t.id}" has no description — the agent only gets the title.`);
-		} else if (!/verif|test|check|curl|run\b|npm |pnpm |cargo |pytest|tsc\b/i.test(t.description)) {
-			warnings.push(`Task "${t.id}" description has no Verify criterion — the agent won't know how to prove it's done.`);
+		} else {
+			if (!/verif|test|check|curl|run\b|npm |pnpm |cargo |pytest|tsc\b/i.test(t.description)) {
+				warnings.push(`Task "${t.id}" description has no Verify criterion — the agent won't know how to prove it's done.`);
+			}
+			const closure = dependencyClosure(t, byId);
+			for (const described of describedDependencies(t, ids)) {
+				if (!closure.has(described)) {
+					warnings.push(`Task "${t.id}" says it depends on "${described}", but that task is absent from its formal dependency closure.`);
+				}
+			}
 		}
 	}
 

package/src/protocol.ts

@@ -90,9 +90,10 @@ function buildChainContext(task: Task, allTasks: Task[], squadId: string): strin
 
 	const sections: string[] = [];
 
-	for (const depId of task.depends) {
-		const dep = allTasks.find((t) => t.id === depId);
-		if (!dep || dep.status !== "done") continue;
+	// A downstream integration/QA task needs the contracts its direct inputs
+	// were built from, not only the last edge in the DAG. Walk the complete
+	// ancestor closure, ancestors first, and deduplicate diamond dependencies.
+	for (const dep of completedDependencyClosure(task, allTasks)) {
 
 		let section = `## ${dep.id} (done by ${dep.agent})\n**${dep.title}**\n`;
 		if (dep.output) {
@@ -119,6 +120,24 @@ ${sections.join("\n---\n\n")}
 `;
 }
 
+function completedDependencyClosure(task: Task, allTasks: Task[]): Task[] {
+	const byId = new Map(allTasks.map((candidate) => [candidate.id, candidate]));
+	const seen = new Set<string>();
+	const ordered: Task[] = [];
+
+	const visit = (id: string): void => {
+		if (seen.has(id)) return;
+		seen.add(id);
+		const dependency = byId.get(id);
+		if (!dependency) return;
+		for (const ancestorId of dependency.depends) visit(ancestorId);
+		if (dependency.status === "done") ordered.push(dependency);
+	};
+
+	for (const dependencyId of task.depends) visit(dependencyId);
+	return ordered;
+}
+
 // ============================================================================
 // Sibling Awareness
 // ============================================================================

package/src/review.ts

@@ -0,0 +1,107 @@
+import type { Squad, Task } from "./types.js";
+
+export type OrchestratorReviewVerdict = "pass" | "pass_with_issues" | "fail";
+
+export interface OrchestratorReviewInput {
+	verdict: OrchestratorReviewVerdict;
+	contractChecks: string[];
+	diffReview: string;
+	verificationEvidence: string[];
+	integrationEvidence: string;
+	issues: string[];
+}
+
+/** Move a squad from agent execution into mandatory independent main-session review. */
+export function beginOrchestratorReview(squad: Squad): void {
+	squad.status = "review";
+	squad.review = {
+		status: "pending",
+		requestedAt: new Date().toISOString(),
+		completedAt: null,
+		verdict: null,
+		contractChecks: [],
+		diffReview: "",
+		verificationEvidence: [],
+		integrationEvidence: "",
+		issues: [],
+	};
+}
+
+/**
+ * Validate and record the orchestrator's independent review evidence.
+ * A failing review deliberately leaves the squad behind the review gate.
+ */
+export function recordOrchestratorReview(squad: Squad, input: OrchestratorReviewInput): void {
+	if (squad.status !== "review" || !squad.review) {
+		throw new Error(`Squad '${squad.id}' is not awaiting orchestrator review`);
+	}
+
+	const contractChecks = cleanList(input.contractChecks);
+	const verificationEvidence = cleanList(input.verificationEvidence);
+	const issues = cleanList(input.issues);
+	const diffReview = input.diffReview.trim();
+	const integrationEvidence = input.integrationEvidence.trim();
+
+	if (contractChecks.length === 0) {
+		throw new Error("contractChecks must map the original user requirements to observed results");
+	}
+	if (!diffReview) {
+		throw new Error("diffReview must describe the independently inspected changes and scope");
+	}
+	if (verificationEvidence.length === 0) {
+		throw new Error("verificationEvidence must include commands/checks and their actual results");
+	}
+	if (!integrationEvidence) {
+		throw new Error("integrationEvidence must include E2E/integration results or a specific reason it is not applicable");
+	}
+	if ((input.verdict === "fail" || input.verdict === "pass_with_issues") && issues.length === 0) {
+		throw new Error(`${input.verdict} must list every actionable or remaining issue`);
+	}
+
+	squad.review = {
+		status: input.verdict === "fail" ? "failed" : "passed",
+		requestedAt: squad.review.requestedAt,
+		completedAt: new Date().toISOString(),
+		verdict: input.verdict,
+		contractChecks,
+		diffReview,
+		verificationEvidence,
+		integrationEvidence,
+		issues,
+	};
+
+	// Only an independently reviewed PASS can become done. A FAIL remains gated
+	// until fixes are made and the main orchestrator records a fresh review.
+	squad.status = input.verdict === "fail" ? "review" : "done";
+}
+
+/** Persistent system-prompt contract shown until squad_review accepts the work. */
+export function buildOrchestratorReviewGate(squad: Squad, tasks: Task[]): string {
+	const delegatedPlan = tasks
+		.map((task) => `- ${task.id} (${task.agent}): ${task.title}\n  ${task.description || "(no description)"}`)
+		.join("\n");
+
+	return `<squad_review_required>
+UNTRUSTED CANDIDATE WORK — INDEPENDENT ORCHESTRATOR REVIEW IS MANDATORY.
+
+Authoritative contract: re-read the user's ORIGINAL request and all later clarifications in this main-session conversation. The squad report and delegated task descriptions are claims, not proof and not substitutes for that contract.
+Recorded squad goal (secondary reference): ${squad.goal}
+
+Delegated plan (non-authoritative):
+${delegatedPlan}
+
+Before reporting success, completion, or acceptance to the user, YOU (the main Pi/orchestrator) MUST:
+1. Reconstruct the original contract requirement-by-requirement from the conversation.
+2. Inspect the actual working-tree/commit diff and relevant source files yourself; check scope, integration points, error paths, regressions, and unintended changes.
+3. Independently run the original Verify commands and appropriate build/tests. Do not rely on pasted squad output.
+4. Run integration/E2E in the real target or production-like environment when the request affects runtime behavior. If genuinely not applicable or impossible, record the precise reason and mark it unverified.
+5. Fix discovered defects and repeat checks. Squad QA PASS does not override your findings.
+6. Call squad_review with contract checks, diff review, actual command/result evidence, integration/E2E evidence, and remaining issues.
+
+Do not ask the user whether you should verify. Do not merely summarize the squad report. Until squad_review records PASS/PASS_WITH_ISSUES, the work is not accepted.
+</squad_review_required>`;
+}
+
+function cleanList(values: string[]): string[] {
+	return values.map((value) => value.trim()).filter(Boolean);
+}

package/src/router.ts

@@ -47,12 +47,18 @@ export class Router {
 	processMessage(taskId: string, fromAgent: string, text: string): void {
 		// Parse @mentions
 		const mentions = this.parseMentions(text, fromAgent);
+		let resolvedFromDurableOutput = false;
 		for (const mention of mentions) {
-			this.routeMention(taskId, fromAgent, mention.target, mention.message);
+			const resolved = this.routeMention(taskId, fromAgent, mention.target, mention.message);
+			// Only suppress escalation when the resolved mention itself expressed
+			// the blocker; an unrelated completed-agent FYI must not hide another block.
+			resolvedFromDurableOutput =
+				(resolved && this.isBlockSignal(mention.message)) || resolvedFromDurableOutput;
 		}
 
-		// Detect block signals
-		if (this.isBlockSignal(text)) {
+		// Do not wake the human for a blocker we immediately resolved from a
+		// completed agent's durable task output.
+		if (this.isBlockSignal(text) && !resolvedFromDurableOutput) {
 			for (const listener of this.escalationListeners) {
 				listener(taskId, fromAgent, this.extractBlockReason(text));
 			}
@@ -67,7 +73,7 @@ export class Router {
 		fromAgent: string,
 		targetAgent: string,
 		message: string,
-	): void {
+	): boolean {
 		// Log the mention in the source task
 		store.appendMessage(this.squadId, sourceTaskId, {
 			ts: store.now(),
@@ -93,8 +99,41 @@ export class Router {
 				to: targetAgent,
 				text: message,
 			});
-		} else {
-			// Target not running — queue for later
+			return false;
+		}
+
+		const targetTasks = store.loadAllTasks(this.squadId).filter((task) => task.agent === targetAgent);
+		const hasFutureRun = targetTasks.some((task) =>
+			task.status === "pending" || task.status === "blocked" || task.status === "suspended" || task.status === "in_progress",
+		);
+		if (!hasFutureRun) {
+			const completed = targetTasks.filter((task) => task.status === "done" && task.output);
+			if (completed.length > 0) {
+				const durableReply = [
+					`[squad] @${targetAgent} has completed and is no longer running. Durable completed output:`,
+					...completed.map((task) => `\n## ${task.id}: ${task.title}\n${task.output}`),
+				].join("\n");
+				const reply = {
+					ts: store.now(),
+					from: targetAgent,
+					type: "reply" as const,
+					to: fromAgent,
+					text: durableReply,
+				};
+				store.appendMessage(this.squadId, sourceTaskId, reply);
+				if (this.pool.isRunning(sourceTaskId)) {
+					this.pool.steer(sourceTaskId, durableReply);
+				} else {
+					this.pool.queueMessage(fromAgent, reply);
+				}
+				return true;
+			}
+		}
+
+		// Target has future work and may spawn again — queue for that run. If the
+		// target is terminal with no output, do not create an undeliverable queue;
+		// leave the blocker unresolved so it escalates to the main orchestrator.
+		if (hasFutureRun) {
 			this.pool.queueMessage(targetAgent, {
 				ts: store.now(),
 				from: fromAgent,
@@ -103,6 +142,7 @@ export class Router {
 				text: message,
 			});
 		}
+		return false;
 	}
 
 	/**

package/src/scheduler.ts

@@ -19,6 +19,7 @@ import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
 import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
+import { beginOrchestratorReview } from "./review.js";
 
 // ============================================================================
 // Types
@@ -31,7 +32,7 @@ export type SchedulerEventType =
 	| "task_blocked"
 	| "task_unblocked"
 	| "task_rework"
-	| "squad_completed"
+	| "squad_review_required"
 	| "squad_failed"
 	| "escalation"
 	| "activity";
@@ -621,15 +622,18 @@ export class Scheduler {
 				const turnCount = event.data?.turnCount ?? 0;
 				const toolCallCount = event.data?.toolCallCount ?? 0;
 
-				// Agent must have done real work: at least 1 turn AND at least 1 tool call.
-				// An agent that exits cleanly but with 0 turns/tools did nothing —
-				// likely hit a rate limit or API error. Treat as crash, not success.
-				const hadMeaningfulWork = turnCount > 0 && toolCallCount > 0;
+				// Tool use is strong evidence of work, but planning/review tasks can
+				// legitimately deliver a substantive report without calling a tool.
+				// Accept durable assistant output; the mandatory main-orchestrator
+				// review gate still decides whether the work satisfies the contract.
+				const hasSubstantiveOutput = store.loadMessages(this.squadId, event.taskId)
+					.some((message) => message.from === event.agentName && message.type === "text" && message.text.trim().length > 0);
+				const hadMeaningfulWork = turnCount > 0 && (toolCallCount > 0 || hasSubstantiveOutput);
 				if (hadMeaningfulWork) {
 					this.handleTaskCompleted(event.taskId).then(() => this.updateContext());
 				} else {
-					// Agent exited without doing real work (0 turns or 0 tool calls).
-					// Common causes: rate limit, API error, resource pressure, crash.
+					// Agent exited without a completed turn, tool work, or substantive
+					// assistant artifact. Common causes: rate limit/API/resource failure.
 					// Retry once before failing.
 					const retryKey = `spawn-retry:${event.taskId}`;
 					if (!this.spawnRetries.has(retryKey)) {
@@ -637,7 +641,7 @@ export class Scheduler {
 						const stderr = event.data?.stderr || "";
 						const reason = turnCount === 0
 							? `exited with 0 turns (likely rate limit or API error)`
-							: `exited with ${turnCount} turns but 0 tool calls (no work done)`;
+							: `exited with ${turnCount} turns but no tool calls or substantive output`;
 						logError("squad-scheduler", `Agent ${event.agentName} ${reason}, code=${exitCode}. Retrying in 2s... stderr: ${stderr}`);
 						store.updateTaskStatus(this.squadId, event.taskId, "pending");
 						store.appendMessage(this.squadId, event.taskId, {
@@ -996,9 +1000,12 @@ export class Scheduler {
 		);
 
 		if (allDone) {
-			squad.status = "done";
+			// Agent execution is only a candidate result. It cannot become "done"
+			// until the main Pi independently reviews it against the original contract.
+			if (squad.status === "review") return;
+			beginOrchestratorReview(squad);
 			store.saveSquad(squad);
-			this.emit({ type: "squad_completed", squadId: this.squadId });
+			this.emit({ type: "squad_review_required", squadId: this.squadId });
 		} else if (anyFailed && !anyInProgress) {
 			// All remaining tasks are blocked/failed with no way forward
 			const blockedCount = tasks.filter((t) => t.status === "blocked").length;

package/src/skills/squad-supervisor/SKILL.md

@@ -152,23 +152,30 @@ Use `squad_modify` when:
 - **`pause`** / **`resume`**: Stop/restart the entire squad
 - **`cancel`**: Abort everything (user changed their mind)
 
-## After Squad Completes — Reviewing Completed Work
-
-When you receive `[squad] Squad completed`, you are the last line of review. Do NOT just relay the summary:
-1. **Check verdicts**: scan task outputs for QA verdicts (`## Verdict: PASS/FAIL/PASS WITH ISSUES`) and note any `PASS WITH ISSUES` minor issues
-2. **Check evidence**: each task's output should include verification evidence (commands + results). If a task claimed done without evidence, run its Verify command yourself (build, test, curl — whatever the task description specified)
-3. **Spot-check integration**: individual tasks passing doesn't guarantee the integrated result works — run the end-to-end check when one exists (app builds, server starts, main flow works)
-4. **Report with evidence**: tell the user what was verified (with the commands/results), and explicitly flag anything unverified or concerning
-5. Suggest next steps if applicable
-
-Example:
-> Squad finished all 4 tasks:
-> - API endpoints created at `/api/auth` and `/api/users`
-> - JWT middleware with RS256 validation
-> - 12 tests passing
-> - README updated with API docs
+## After Agents Finish — Mandatory Independent Orchestrator Review
+
+Agent execution finishing is **not completion or acceptance**. When you receive `[squad] TASK EXECUTION FINISHED` / `<squad_review_required>`, every squad output—including QA PASS—is an untrusted claim. You are the independent acceptance authority.
+
+You MUST do all of this before telling the user the work succeeded:
+1. **Re-read the original contract**: reconstruct every requirement, boundary, and later clarification from the user's main-session conversation. The squad goal/task plan is only a secondary aid and cannot narrow the original request.
+2. **Inspect reality, not reports**: read the actual working-tree/commit diff and relevant source. Check every changed line for correctness, scope, integration points, unintended changes, error paths, security, and regressions.
+3. **Independently verify**: run the original Verify commands, build, and relevant tests yourself. Do not count command output pasted by squad agents as your evidence.
+4. **Run integration/E2E**: individual task/QA passes do not prove the integrated system. Exercise the real user flow in the target or production-like environment whenever runtime behavior changed. If impossible or genuinely inapplicable, state exactly why and mark it unverified—never silently skip it.
+5. **Fix and repeat**: if you find defects, fix them (or route explicit rework), then rerun the affected checks. Squad QA does not overrule your findings.
+6. **Record the gate**: call `squad_review` with requirement-by-requirement contract checks, your diff review, actual command/result evidence, integration/E2E evidence, and all issues. Until that tool records PASS/PASS_WITH_ISSUES, the squad remains `review` rather than `done`.
+7. **Report only reviewed facts**: clearly separate what you personally verified, remaining issues, and anything unverified.
+
+Never ask “Want me to run the tests/E2E?” after agents finish. Run required acceptance checks immediately. Never merely relay or paraphrase the squad summary.
+
+Example after independent review:
+> Independent orchestrator review complete against the original 7 acceptance criteria:
+> - Inspected `git diff --stat` and the auth/router/test changes; no unrelated files changed
+> - `npm test`: 42/42 passed; `npm run build`: passed
+> - Production-like E2E: login → refresh → protected route → logout passed
+> - Found and fixed a cookie-domain defect missed by squad QA; reran unit + E2E successfully
+> - `squad_review`: PASS
 >
-> Total cost: $1.23. Want me to run the full test suite or deploy?
+> Remaining unverified: none.
 
 ## Decision Framework
 
@@ -181,5 +188,5 @@ Example:
 | User says "tell the backend agent to..." | `squad_message` to that agent |
 | User says "add a task for..." | `squad_modify` with `add_task` |
 | User says "cancel/stop" | `squad_modify` with `cancel` |
-| Squad completes | Summarize results, suggest next steps |
+| Agents finish | Independently review against original contract, inspect diff, run verification + integration/E2E, call `squad_review`; only then report acceptance |
 | Squad fails | Report what failed, offer options (retry, modify, cancel) |

package/src/store.ts

@@ -269,11 +269,11 @@ export function listSquads(): string[] {
 }
 
 export function findActiveSquads(): Squad[] {
-	// Includes "failed": failure is recoverable (resume resets failed tasks), so
-	// failed squads must stay discoverable. All callers filter by status.
+	// Includes "failed" (recoverable) and "review" (main-orchestrator gate), so
+	// neither state disappears across session restarts. All callers filter by status.
 	return listSquads()
 		.map((id) => loadSquad(id))
-		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed"));
+		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed" || s.status === "review"));
 }
 
 /** List squads filtered by project cwd. If no cwd, returns all. */

package/src/types.ts

@@ -71,11 +71,24 @@ export const DEFAULT_SQUAD_SETTINGS: SquadSettings = {
 // Squad
 // ============================================================================
 
-export type SquadStatus = "planning" | "running" | "paused" | "done" | "failed";
+export type SquadStatus = "planning" | "running" | "paused" | "review" | "done" | "failed";
+
+export interface SquadReview {
+	status: "pending" | "passed" | "failed";
+	requestedAt: string;
+	completedAt: string | null;
+	verdict: "pass" | "pass_with_issues" | "fail" | null;
+	contractChecks: string[];
+	diffReview: string;
+	verificationEvidence: string[];
+	integrationEvidence: string;
+	issues: string[];
+}
 
 export interface SquadConfig {
 	maxConcurrency: number;
 	autoUnblock: boolean;
+	/** @deprecated Independent main-orchestrator review is always required. */
 	reviewOnComplete: boolean;
 	/** Max rework attempts when QA fails a task (0 = no rework, just fail) */
 	maxRetries: number;
@@ -84,7 +97,7 @@ export interface SquadConfig {
 export const DEFAULT_SQUAD_CONFIG: SquadConfig = {
 	maxConcurrency: 2,
 	autoUnblock: true,
-	reviewOnComplete: false,
+	reviewOnComplete: true,
 	maxRetries: 2,
 };
 
@@ -99,6 +112,8 @@ export interface Squad {
 	/** Agent name → overrides. Keys must exist in .pi/squad/agents/ */
 	agents: Record<string, SquadAgentEntry>;
 	config: SquadConfig;
+	/** Mandatory independent main-session review; absent on legacy/running squads. */
+	review?: SquadReview;
 }
 
 // ============================================================================