pi-squad 0.16.6 → 0.17.0

package/src/index.ts

@@ -14,9 +14,9 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Squad, Task, SquadConfig, PlannerOutput } from "./types.js";
+import type { Squad, Task, SquadConfig, SquadAgentEntry, PlannerOutput, SuspendedStallAttention } from "./types.js";
 import { DEFAULT_SQUAD_CONFIG, THINKING_LEVELS } from "./types.js";
-import { Scheduler, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
+import { Scheduler, formatSuspendedStallAttention, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
 import { runPlanner } from "./planner.js";
 import { validatePlan, PLAN_STRUCTURE_RULES } from "./plan-rules.js";
 import { ADVISOR_SYSTEM_PROMPT, buildAdvisorConsultText, type AdvisorConsultInput } from "./advisor.js";
@@ -27,11 +27,20 @@ import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildCompletionSummary, buildFailureSummary } from "./report.js";
 import { buildOrchestratorReviewGate, recordOrchestratorReview } from "./review.js";
+import { formatSuspendedAttention, getReviewPresentation } from "./presentation.js";
+import { prepareSpec, chunkRanges, isFileSpecTaskId, registerChildSpecReader, type PreparedSpec } from "./file-spec.js";
 
 // ============================================================================
 // State
 // ============================================================================
 
+interface InlineSquadStart {
+	goal: string;
+	agents?: Record<string, SquadAgentEntry>;
+	tasks?: Array<{ id: string; title: string; description?: string; agent: string; depends?: string[]; inheritContext?: boolean }>;
+	config?: { maxConcurrency?: number; autoUnblock?: boolean; maxRetries?: number };
+}
+
 /** Master switch — when false, all squad tools, hooks, and widget are disabled */
 let squadEnabled = true;
 /** Registry of all running schedulers — supports multiple concurrent squads */
@@ -186,6 +195,21 @@ function getActiveScheduler(): Scheduler | null {
 	return schedulers.get(activeSquadId) || null;
 }
 
+/** Restore the single focus/widget invariant after destructive exact cancellation. */
+function repairFocusAfterCancellation(cancelledId: string): void {
+	if (activeSquadId === cancelledId || (activeSquadId !== null && !store.loadSquad(activeSquadId))) {
+		activeSquadId = null;
+	}
+	widgetState.squadId = activeSquadId;
+	widgetControls?.requestUpdate();
+}
+
+function activeSuspendedAttentionForProject(cwd: string): Array<{ squadId: string; attention: SuspendedStallAttention }> {
+	return store.listSquadsForProject(cwd)
+		.filter((squad) => Boolean(squad.suspendedStallAttention))
+		.map((squad) => ({ squadId: squad.id, attention: squad.suspendedStallAttention! }));
+}
+
 /** Reconstruct and focus one exact persisted squad without creating/linking another. */
 function ensureScheduler(pi: ExtensionAPI, squadId: string, skillPaths: string[]): Scheduler {
 	let scheduler = schedulers.get(squadId);
@@ -224,8 +248,8 @@ function resolveResumeSquad(cwd: string, explicitId?: string): Squad | null {
 // ============================================================================
 
 export default function (pi: ExtensionAPI) {
-	// Don't load in child agent processes (prevent recursive squad-in-squad)
-	if (process.env.PI_SQUAD_CHILD === "1") return;
+	// File-spec children load only the non-recursive reader and fail-closed guard.
+	if (process.env.PI_SQUAD_CHILD === "1") { registerChildSpecReader(pi); return; }
 
 	// Wire main-session thinking lookup (needs `pi`, guarded against stale API)
 	getMainSessionThinking = () => {
@@ -244,6 +268,24 @@ export default function (pi: ExtensionAPI) {
 	const skillsDir = path.join(path.dirname(new URL(import.meta.url).pathname), "skills");
 	const squadSkillPaths = getSquadSkillPaths(skillsDir);
 
+	/** Cancel one persisted exact squad without ever inferring or changing focus. */
+	const cancelExactSquad = async (squadId: string): Promise<boolean> => {
+		const squad = store.loadSquad(squadId);
+		if (!squad) return false;
+		const live = schedulers.get(squadId);
+		if (live) await live.stop();
+		else await new Scheduler(squadId, squadSkillPaths, schedulerSpawnContext).stop();
+		const fresh = store.loadSquad(squadId);
+		if (fresh) {
+			fresh.status = "failed";
+			delete fresh.suspendedStallAttention;
+			store.saveSquad(fresh);
+		}
+		schedulers.delete(squadId);
+		repairFocusAfterCancellation(squadId);
+		return true;
+	};
+
 	// =========================================================================
 	// Context Injection — give main agent awareness of squad state
 	// =========================================================================
@@ -255,9 +297,12 @@ export default function (pi: ExtensionAPI) {
 		const pendingReviewGates = store.findActiveSquads()
 			.filter((s) => s.cwd === ctx.cwd && s.status === "review")
 			.map((s) => ({ squad: s, gate: buildOrchestratorReviewGate(s, store.loadAllTasks(s.id)) }));
+		const suspendedAttention = activeSuspendedAttentionForProject(ctx.cwd)
+			.map(({ squadId, attention }) => formatSuspendedStallAttention(squadId, attention));
+		const durablePrompts = [...pendingReviewGates.map(({ gate }) => gate), ...suspendedAttention];
 		if (!squadEnabled) {
-			if (pendingReviewGates.length === 0) return;
-			return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+			if (durablePrompts.length === 0) return;
+			return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 		}
 
 		// When a squad is active, inject its status
@@ -265,15 +310,16 @@ export default function (pi: ExtensionAPI) {
 			const squad = store.loadSquad(activeSquadId);
 			if (!squad) {
 				activeSquadId = null;
-				if (pendingReviewGates.length > 0) {
-					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				widgetState.squadId = null;
+				if (durablePrompts.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
 				return;
 			}
 			const tasks = store.loadAllTasks(activeSquadId);
 			if (tasks.length === 0) {
-				if (pendingReviewGates.length > 0) {
-					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				if (durablePrompts.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
 				return;
 			}
@@ -281,21 +327,27 @@ export default function (pi: ExtensionAPI) {
 			const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 
 			const taskLines = tasks.map((t) => {
-				const icon = t.status === "done" ? "✓" : t.status === "in_progress" ? "⏳" : t.status === "failed" ? "✗" : t.status === "blocked" ? "◻" : t.status === "cancelled" ? "⊘" : "·";
+				const icon = t.status === "done" ? "✓" : t.status === "in_progress" ? "⏳" : t.status === "failed" ? "✗" : t.status === "blocked" ? "◻" : t.status === "suspended" ? "⏸" : t.status === "cancelled" ? "⊘" : "·";
 				let line = `  ${icon} ${t.id} (${t.agent}) [${t.status}]`;
 				if (t.output) line += ` — ${t.output}`;
 				if (t.error) line += ` ERROR: ${t.error}`;
 				return line;
 			}).join("\n");
 
+			const reviewPresentation = getReviewPresentation(squad);
+			const squadReference = squad.spec
+				? `file spec sha256=${squad.spec.sha256} bytes=${squad.spec.bytes} path=${squad.spec.path}`
+				: squad.goal;
 			const squadContext = [
 				`<squad_status>`,
-				`Squad: ${squad.id} — ${squad.goal}`,
+				`Squad: ${squad.id} — ${squadReference}`,
 				`Status: ${squad.status} | ${formatTaskProgress(tasks)} | $${totalCost.toFixed(2)}`,
+				...(reviewPresentation ? [`Acceptance: ${reviewPresentation.label}`] : []),
 				taskLines,
 				`</squad_status>`,
 				...(squad.status === "review" ? [buildOrchestratorReviewGate(squad, tasks)] : []),
 				...pendingReviewGates.filter(({ squad: pending }) => pending.id !== squad.id).map(({ gate }) => gate),
+				...suspendedAttention,
 				`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");
@@ -323,7 +375,7 @@ export default function (pi: ExtensionAPI) {
 
 		return {
 			systemPrompt: event.systemPrompt + "\n\n" + squadNudge +
-				(pendingReviewGates.length > 0 ? "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") : ""),
+				(durablePrompts.length > 0 ? "\n\n" + durablePrompts.join("\n\n") : ""),
 		};
 	});
 
@@ -347,16 +399,18 @@ export default function (pi: ExtensionAPI) {
 			PLAN_STRUCTURE_RULES.replace(/\n- /g, " ").replace(/^- /, ""),
 			"Plans are validated on submission — structural errors are rejected, rule violations come back as warnings.",
 		].join(" "),
-		promptSnippet: "squad({ goal, tasks?, agents? }): decompose complex work into parallel specialist agents → non-blocking, monitor via squad_status",
+		promptSnippet: "squad({ goal, tasks?, agents? } | { specFile, specSha256 }): start inline or canonical file-based squad → non-blocking",
 		promptGuidelines: [
 			"Use squad when work spans 2+ concerns (backend+frontend+tests+docs) or has natural parallelism",
+			"For large contracts, use only specFile + exact lowercase specSha256; never inline the same contract or large artifacts",
 			"Skip squad for single-file changes, quick fixes, or anything one agent finishes in minutes",
 			"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 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({
+		parameters: Type.Union([
+		Type.Object({
 			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(
@@ -386,7 +440,12 @@ export default function (pi: ExtensionAPI) {
 					maxConcurrency: Type.Optional(Type.Number({ description: "Max parallel agents (default: 2)" })),
 				}),
 			),
-		}),
+		}, { additionalProperties: false }),
+		Type.Object({
+			specFile: Type.String({ minLength: 1, description: "Path to a strict v1 squad specification JSON file" }),
+			specSha256: Type.String({ pattern: "^[a-f0-9]{64}$", description: "SHA-256 of the exact source bytes" }),
+		}, { additionalProperties: false }),
+		]),
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (!squadEnabled) return { content: [{ type: "text" as const, text: "Squad is disabled. Use /squad enable to re-enable." }], details: undefined };
@@ -401,13 +460,17 @@ export default function (pi: ExtensionAPI) {
 			// cwd may differ (e.g. when a relative --session-dir was used).
 			const rawSessionFile = ctx.sessionManager.getSessionFile();
 			const sessionFile = rawSessionFile ? path.resolve(rawSessionFile) : null;
-			const squadId = store.makeTaskId(params.goal);
-			if (store.squadExists(squadId)) {
-				const uniqueId = `${squadId}-${Date.now().toString(36)}`;
-				return await startSquad(uniqueId, params, ctx.cwd, squadSkillPaths, pi, sessionFile);
+			let prepared: PreparedSpec | undefined;
+			let effective: InlineSquadStart;
+			if ("specFile" in params) {
+				prepared = prepareSpec(params.specFile, params.specSha256, ctx.cwd);
+				effective = { goal: prepared.spec.goal, agents: prepared.spec.agents, tasks: prepared.spec.tasks, config: prepared.spec.config };
+			} else {
+				effective = params;
 			}
-
-			return await startSquad(squadId, params, ctx.cwd, squadSkillPaths, pi, sessionFile);
+			const baseId = store.makeTaskId(effective.goal) || `squad-${prepared?.sha256.slice(0, 12)}`;
+			const squadId = store.squadExists(baseId) ? `${baseId}-${Date.now().toString(36)}` : baseId;
+			return await startSquad(squadId, effective, ctx.cwd, squadSkillPaths, pi, sessionFile, prepared);
 		},
 	});
 
@@ -452,6 +515,7 @@ export default function (pi: ExtensionAPI) {
 						task.status === "in_progress" ? "⏳" :
 						task.status === "blocked" ? "◻" :
 						task.status === "failed" ? "✗" :
+						task.status === "suspended" ? "⏸" :
 						task.status === "cancelled" ? "⊘" :
 						"·";
 					let line = `${icon} ${taskId} (${task.agent}) — ${task.title} [${task.status}]`;
@@ -461,13 +525,16 @@ export default function (pi: ExtensionAPI) {
 				.join("\n");
 
 			const durableTasks = store.loadAllTasks(id!);
+			const squad = store.loadSquad(id!);
+			const review = squad ? getReviewPresentation(squad) : null;
 			const summary = [
 				`Squad: ${id}`,
 				`Status: ${context.status}`,
 				`Progress: ${formatTaskProgress(durableTasks)}`,
 				`Elapsed: ${context.elapsed}`,
 				`Cost: $${context.costs.total.toFixed(4)}`,
-				...(context.status === "review" ? ["Acceptance: BLOCKED — independent main-orchestrator review required via squad_review"] : []),
+				...(review ? [`Acceptance: ${review.label}`] : []),
+				...(squad ? formatSuspendedAttention(squad) : []),
 				"",
 				"Tasks:",
 				taskLines,
@@ -517,6 +584,13 @@ export default function (pi: ExtensionAPI) {
 			if (!squad) {
 				return { content: [{ type: "text" as const, text: `Squad '${id}' not found.` }], details: undefined };
 			}
+			const attestationScheduler = schedulers.get(id) ?? new Scheduler(id, squadSkillPaths, schedulerSpawnContext);
+			if (!schedulers.has(id)) { schedulers.set(id, attestationScheduler); wireSchedulerEvents(pi, attestationScheduler, id); }
+			const invalidAttestations = await attestationScheduler.auditSpecAttestations();
+			if (invalidAttestations.length > 0) {
+				void attestationScheduler.start();
+				return { content: [{ type: "text" as const, text: `Review rejected: invalid canonical spec attestation for task(s): ${invalidAttestations.join(", ")}. Work was reopened.` }], details: undefined };
+			}
 
 			try {
 				recordOrchestratorReview(squad, {
@@ -604,9 +678,9 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_modify",
 		label: "Squad Modify",
-		description: "Modify one exact squad: add_task, set_dependencies (top-level depends), cancel_task, complete_task (mark done + schedule dependents), pause, resume_task, resume (including failed-review rework), cancel. Task actions reconstruct the persisted scheduler after restart when needed.",
+		description: "Modify a squad. The destructive cancel action requires an exact squadId and never infers focus; task actions reconstruct the persisted scheduler after restart when needed.",
 		parameters: Type.Object({
-			squadId: Type.Optional(Type.String({ description: "Exact squad to modify (recommended for failed-review rework; default: focused/recoverable project squad)" })),
+			squadId: Type.Optional(Type.String({ description: "Exact squad to modify; required for cancel (other actions may use the focused/recoverable project squad)" })),
 			action: Type.Union(
 				[
 					Type.Literal("add_task"),
@@ -637,6 +711,22 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (params.action === "cancel") {
+				if (!params.squadId?.trim()) {
+					return { content: [{ type: "text" as const, text: "cancel requires exact squadId; no squad was changed." }], details: undefined };
+				}
+				const squadId = params.squadId.trim();
+				if (!store.loadSquad(squadId)) {
+					return { content: [{ type: "text" as const, text: `Squad '${squadId}' not found; no squad was changed.` }], details: undefined };
+				}
+				try {
+					await cancelExactSquad(squadId);
+				} catch (error) {
+					return { content: [{ type: "text" as const, text: `Cancel failed for squad '${squadId}': ${(error as Error).message}` }], details: undefined };
+				}
+				return { content: [{ type: "text" as const, text: `Squad '${squadId}' cancelled.` }], details: undefined };
+			}
+
 			if (params.action === "resume") {
 				const squad = resolveResumeSquad(ctx.cwd, params.squadId);
 				if (!squad) {
@@ -674,7 +764,11 @@ export default function (pi: ExtensionAPI) {
 						return { content: [{ type: "text" as const, text: "Provide a task definition for add_task." }], details: undefined };
 					}
 					// Validate against the live squad: deps must exist, agent must exist
-					const existing = store.loadAllTasks(activeSquadId);
+					const targetSquad = store.loadSquad(squadId)!;
+					if (targetSquad.spec && !isFileSpecTaskId(params.task.id)) {
+						return { content: [{ type: "text" as const, text: `Invalid file-spec task id '${params.task.id}'. Use 1..64 lowercase letters/digits with internal hyphens.` }], details: undefined };
+					}
+					const existing = store.loadAllTasks(squadId);
 					const existingIds = new Set(existing.map((t) => t.id));
 					if (existingIds.has(params.task.id)) {
 						return { content: [{ type: "text" as const, text: `Task id '${params.task.id}' already exists in this squad.` }], details: undefined };
@@ -697,6 +791,7 @@ export default function (pi: ExtensionAPI) {
 						status: dependencies.every((dependency) => existing.find((candidate) => candidate.id === dependency)?.status === "done") ? "pending" : "blocked",
 						depends: dependencies,
 						...(params.task.inheritContext ? { inheritContext: true } : {}),
+						...(targetSquad.spec ? { fileSpecDelta: true } : {}),
 						created: store.now(),
 						started: null,
 						completed: null,
@@ -742,9 +837,12 @@ export default function (pi: ExtensionAPI) {
 				case "resume_task": {
 					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
 					try {
-						await activeScheduler.resumeTask(params.taskId);
+						const result = await activeScheduler.resumeTask(params.taskId);
+						if (result === "already_running") {
+							return { content: [{ type: "text" as const, text: `Task '${params.taskId}' is already running in squad '${squadId}'; no duplicate resume was started.` }], details: undefined };
+						}
 					} catch (err) {
-						return { content: [{ type: "text" as const, text: `resume_task failed: ${(err as Error).message}` }], details: undefined };
+						return { content: [{ type: "text" as const, text: `resume_task failed for task '${params.taskId}' in squad '${squadId}': ${(err as Error).message}` }], details: undefined };
 					}
 					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed in squad '${squadId}'.` }], details: undefined };
 				}
@@ -760,7 +858,7 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				case "pause": {
-					const squad = store.loadSquad(activeSquadId);
+					const squad = store.loadSquad(squadId);
 					if (squad) {
 						squad.status = "paused";
 						store.saveSquad(squad);
@@ -769,19 +867,7 @@ export default function (pi: ExtensionAPI) {
 					return { content: [{ type: "text" as const, text: "Squad paused. Use squad_modify with action 'resume' to continue." }], details: undefined };
 				}
 
-				// Note: "resume" is handled above, before the activeScheduler guard.
-
-				case "cancel": {
-					await activeScheduler.stop();
-					const squad = store.loadSquad(activeSquadId);
-					if (squad) {
-						squad.status = "failed";
-						store.saveSquad(squad);
-					}
-					schedulers.delete(activeSquadId);
-					activeSquadId = null;
-					return { content: [{ type: "text" as const, text: "Squad cancelled." }], details: undefined };
-				}
+				// Note: "resume" and exact-ID "cancel" are handled above.
 
 				default:
 					return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }], details: undefined };
@@ -822,6 +908,30 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// Audit file-spec evidence on restart. Review/running/failed work is reopened;
+		// an explicitly paused squad remains paused and suspended/cancelled tasks stay untouched.
+		for (const squad of store.listSquadsForProject(ctx.cwd).filter((candidate) => candidate.spec && ["running", "failed", "paused", "review"].includes(candidate.status))) {
+			let scheduler = schedulers.get(squad.id);
+			if (!scheduler) { scheduler = new Scheduler(squad.id, squadSkillPaths, schedulerSpawnContext); schedulers.set(squad.id, scheduler); wireSchedulerEvents(pi, scheduler, squad.id); }
+			const invalid = await scheduler.auditSpecAttestations();
+			if (invalid.length > 0 && squad.status !== "paused") await scheduler.start();
+		}
+
+		// Reconstruct schedulers for explicit-suspension stalls without resuming any
+		// task. Reconcile derives/persists a missing outbox record and emits only a
+		// pending fingerprint; delivered attention remains durable and silent.
+		const suspensionCandidates = store.listSquadsForProject(ctx.cwd)
+			.filter((squad) => Boolean(squad.suspendedStallAttention) || store.loadAllTasks(squad.id).some((task) => task.status === "suspended"));
+		for (const squad of suspensionCandidates) {
+			let scheduler = schedulers.get(squad.id);
+			if (!scheduler) {
+				scheduler = new Scheduler(squad.id, squadSkillPaths, schedulerSpawnContext);
+				schedulers.set(squad.id, scheduler);
+				wireSchedulerEvents(pi, scheduler, squad.id);
+			}
+			await scheduler.start();
+		}
+
 		// Mailbox recovery is automatic after extension/main-process restart. Scan
 		// every project squad (including accepted done squads) because a crash can
 		// occur after the mailbox-first write but before the squad/task is reopened.
@@ -856,7 +966,7 @@ export default function (pi: ExtensionAPI) {
 			if (done > 0) {
 				pi.sendMessage({
 					customType: "squad-paused",
-					content: `[squad] Found paused squad "${squad.id}" (${squad.goal}) — ${formatTaskProgress(tasks)}. ` +
+					content: `[squad] Found paused squad "${squad.id}" (${squad.spec ? `file spec sha256=${squad.spec.sha256}` : squad.goal}) — ${formatTaskProgress(tasks)}. ` +
 						`Use squad_modify with action "resume" to continue, or start a new squad.`,
 					display: true,
 				});
@@ -1130,17 +1240,13 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				case "cancel": {
-					const cancelSched = getActiveScheduler();
-					if (!cancelSched) {
-						ctx.ui.notify("No running squad to cancel", "info");
+					const cancelledId = activeSquadId;
+					if (!cancelledId) {
+						ctx.ui.notify("No focused squad to cancel", "info");
 						return;
 					}
-					await cancelSched.stop();
-					const squad = store.loadSquad(activeSquadId!);
-					if (squad) { squad.status = "failed"; store.saveSquad(squad); }
-					if (activeSquadId) schedulers.delete(activeSquadId);
-					forceWidgetUpdate();
-					ctx.ui.notify("Squad cancelled", "info");
+					await cancelExactSquad(cancelledId);
+					ctx.ui.notify(`Squad '${cancelledId}' cancelled`, "info");
 					return;
 				}
 
@@ -1501,9 +1607,11 @@ async function pickSquad(
 	const options = squads.map((s) => {
 		const tasks = store.loadAllTasks(s.id);
 		const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
+		const review = getReviewPresentation(s);
+		const icon = review?.icon ?? (s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·");
+		const acceptance = review ? ` ${review.label}` : ` [${s.status}]`;
 		const project = showProject ? ` — ${s.cwd.split("/").pop()}` : "";
-		return `${icon} ${s.id} [${s.status}] ${formatTaskProgress(tasks)} $${cost.toFixed(2)}${project}`;
+		return `${icon} ${s.id}${acceptance} · ${formatTaskProgress(tasks)} $${cost.toFixed(2)}${project}`;
 	});
 
 	const choice = await ctx.ui.select("Select a squad", options);
@@ -1573,6 +1681,20 @@ function wireSchedulerEvents(pi: ExtensionAPI, scheduler: Scheduler, squadId: st
 				// can reopen the task immediately on its bound durable Pi session.
 				break;
 			}
+			case "suspended_stall": {
+				try {
+					const attention = event.data as SuspendedStallAttention;
+					pi.sendMessage({
+						customType: `squad-suspended-stall:${squadId}:${attention.fingerprint}`,
+						content: formatSuspendedStallAttention(squadId, attention),
+						display: true,
+					}, { triggerTurn: true, deliverAs: "followUp" });
+					scheduler.acknowledgeSuspendedStall(attention.fingerprint);
+				} catch (error) {
+					logError("squad-scheduler", `suspended-stall delivery failed for ${squadId}: ${(error as Error).message}`);
+				}
+				break;
+			}
 			case "squad_failed": {
 				const tasks = store.loadAllTasks(squadId);
 				const failed = tasks.filter((task) => task.status === "failed");
@@ -1678,23 +1800,12 @@ function openPanel(
 
 async function startSquad(
 	squadId: string,
-	params: {
-		goal: string;
-		agents?: Record<string, { model?: string; thinking?: string }>;
-		tasks?: Array<{
-			id: string;
-			title: string;
-			description?: string;
-			agent: string;
-			depends?: string[];
-			inheritContext?: boolean;
-		}>;
-		config?: { maxConcurrency?: number };
-	},
+	params: InlineSquadStart,
 	cwd: string,
 	skillPaths: string[],
 	pi: ExtensionAPI,
 	sessionFile: string | null = null,
+	preparedSpec?: PreparedSpec,
 ) {
 	let plan: PlannerOutput;
 
@@ -1712,7 +1823,8 @@ async function startSquad(
 		// Validate agent names — remap unknown agents to fullstack
 		for (const task of plan.tasks) {
 			const agentDef = store.loadAgentDef(task.agent, cwd);
-			if (!agentDef) {
+			if (!agentDef || agentDef.disabled) {
+				if (preparedSpec) throw new Error(`SPEC_MALFORMED: assigned agent '${task.agent}' is missing or disabled`);
 				const original = task.agent;
 				task.agent = "fullstack";
 				task.description = `[Note: agent "${original}" not found, remapped to fullstack]\n\n${task.description}`;
@@ -1730,7 +1842,7 @@ async function startSquad(
 	}
 
 	// Merge agent roster
-	const agents: Record<string, { model?: string; thinking?: string }> = { ...plan.agents };
+	const agents: Record<string, SquadAgentEntry> = { ...plan.agents };
 	if (params.agents) {
 		for (const [name, entry] of Object.entries(params.agents)) {
 			agents[name] = { ...agents[name], ...entry };
@@ -1750,6 +1862,8 @@ async function startSquad(
 	const config: SquadConfig = {
 		...DEFAULT_SQUAD_CONFIG,
 		...(params.config?.maxConcurrency ? { maxConcurrency: params.config.maxConcurrency } : {}),
+		...(typeof params.config?.autoUnblock === "boolean" ? { autoUnblock: params.config.autoUnblock } : {}),
+		...(typeof params.config?.maxRetries === "number" ? { maxRetries: params.config.maxRetries } : {}),
 	};
 
 	const squad: Squad = {
@@ -1761,12 +1875,18 @@ async function startSquad(
 		sessionFile,
 		agents,
 		config,
+		...(preparedSpec ? { spec: {
+			schemaVersion: 1 as const,
+			sha256: preparedSpec.sha256,
+			bytes: preparedSpec.raw.length,
+			path: path.join(store.getSquadDir(squadId), "spec", "spec.v1.json"),
+			chunkBytes: 32768 as const,
+			chunkCount: chunkRanges(preparedSpec.raw).length,
+		} } : {}),
 	};
 
-	store.saveSquad(squad);
-
-	// Create task files
-	for (const taskDef of plan.tasks) {
+	// Materialize task state in memory so file squads can publish spec+squad+tasks atomically.
+	const initialTasks: Task[] = plan.tasks.map((taskDef) => {
 		const task: Task = {
 			id: taskDef.id,
 			title: taskDef.title,
@@ -1782,10 +1902,13 @@ async function startSquad(
 			error: null,
 			usage: { inputTokens: 0, outputTokens: 0, cost: 0, turns: 0 },
 		};
-		// Note: unknown dependency references are hard validation errors above,
-		// so blocked tasks here always have resolvable deps.
+		return task;
+	});
 
-		store.createTask(squadId, task);
+	if (preparedSpec) store.publishFileSquad(squad, initialTasks, preparedSpec.raw);
+	else {
+		store.saveSquad(squad);
+		for (const task of initialTasks) store.createTask(squadId, task);
 	}
 
 	// Start scheduler
@@ -1809,13 +1932,16 @@ async function startSquad(
 		logError("squad", `Scheduler start error: ${(err as Error).message}`);
 	});
 
-	// Build response
-	const taskSummary = plan.tasks
-		.map((t) => {
-			const deps = t.depends.length > 0 ? ` (depends: ${t.depends.join(", ")})` : "";
-			return `${t.id} → ${t.agent}: ${t.title}${deps}`;
-		})
-		.join("\n");
+	// Build response. File mode returns only the bounded descriptor; the canonical
+	// contract is never reflected back into the main model's transport.
+	const taskSummary = preparedSpec
+		? `Canonical spec: ${squad.spec!.path}\nSHA-256: ${squad.spec!.sha256}\nBytes: ${squad.spec!.bytes}\nTasks: ${plan.tasks.length}`
+		: plan.tasks
+			.map((t) => {
+				const deps = t.depends.length > 0 ? ` (depends: ${t.depends.join(", ")})` : "";
+				return `${t.id} → ${t.agent}: ${t.title}${deps}`;
+			})
+			.join("\n");
 
 	return {
 		content: [

package/src/panel/squad-widget.ts

@@ -14,6 +14,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { TaskMessage, TaskStatus } from "../types.js";
+import { getReviewPresentation, getSuspendedAttention, SUSPENDED_ATTENTION_LABEL } from "../presentation.js";
 import * as store from "../store.js";
 
 function statusIcon(status: TaskStatus, th: Theme): string {
@@ -99,21 +100,25 @@ export function setupSquadWidget(
 			if (recentOrchestrator) recentOrchestratorByTask.set(task.id, recentOrchestrator);
 		}
 
-		const sIcon = squad.status === "done" ? th.fg("success", "✓")
+		const review = getReviewPresentation(squad);
+		const attention = getSuspendedAttention(squad);
+		const sIcon = review ? th.fg(review.tone, review.icon)
+			: squad.status === "done" ? th.fg("success", "✓")
 			: squad.status === "failed" ? th.fg("error", "✗")
-			: squad.status === "review" ? th.fg("warning", "◆")
 			: th.fg("warning", "⏳");
 
 		const orchestratorSignal = recentOrchestratorByTask.size > 0
 			? ` ${th.fg("accent", `✉ ${recentOrchestratorByTask.size > 1 ? recentOrchestratorByTask.size + " " : ""}ORCH`)}`
 			: "";
+		const acceptanceText = review ? ` · ${th.fg(review.tone, review.label)}` : "";
 		lines.push(
 			`${sIcon} ${th.fg("accent", "squad")}${orchestratorSignal} ${th.fg("dim", squad.goal.slice(0, 35))} ` +
-			`${th.fg("muted", progressText)} ` +
+			`${th.fg("muted", progressText)}${acceptanceText} ` +
 			`${th.fg("dim", `$${totalCost.toFixed(2)}`)} ` +
 			`${th.fg("dim", formatElapsed(elapsed))} ` +
 			`${th.fg("dim", "^q detail · /squad msg")}`
 		);
+		if (attention) lines.push(`  ${th.fg("warning", SUSPENDED_ATTENTION_LABEL)} ${th.fg("dim", "· ^q detail")}`);
 
 		// Cap visible tasks based on total count
 		const maxVisible = tasks.length > 6 ? 4 : tasks.length;
@@ -169,14 +174,16 @@ export function setupSquadWidget(
 			lines.push(`  ${th.fg("dim", `  +${tasks.length - maxVisible} more · ^q detail`)}`);
 		}
 
-		const cacheKey = `${squad.status}:${tasks.map(t => `${t.id}=${t.status}:${t.usage.turns}`).join(",")}:${recentMessageKeys.join(",")}`;
+		const cacheKey = `${state.squadId}:${squad.status}:${squad.review?.status ?? "none"}:${attention?.fingerprint ?? "no-attention"}:${tasks.map(t => `${t.id}=${t.status}:${t.usage.turns}`).join(",")}:${recentMessageKeys.join(",")}`;
 
-		const statusText = squad.status === "done"
+		const statusText = review
+			? th.fg(review.tone, `${review.label} · ${progressText}`)
+			: attention
+			? th.fg("warning", `${SUSPENDED_ATTENTION_LABEL} · ${progressText}`)
+			: squad.status === "done"
 			? th.fg("success", `✓ squad ${progressText}`)
 			: squad.status === "failed"
 			? th.fg("error", `✗ squad ${progressText}`)
-			: squad.status === "review"
-			? th.fg("warning", `◆ squad review required`)
 			: th.fg("accent", `⏳ squad ${progressText} $${totalCost.toFixed(2)}`);
 
 		return { lines, cacheKey, statusText };
@@ -216,6 +223,8 @@ export function setupSquadWidget(
 			ctx.ui.setWidget("squad-tasks", undefined);
 			ctx.ui.setStatus("squad", undefined);
 			widgetInstalled = false;
+			widgetComponent = null;
+			lastCacheKey = "";
 			return;
 		}