pi-squad 0.16.7 → 0.17.1

package/src/index.ts

@@ -14,7 +14,7 @@ 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, SuspendedStallAttention } 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, formatSuspendedStallAttention, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
 import { runPlanner } from "./planner.js";
@@ -22,17 +22,25 @@ import { validatePlan, PLAN_STRUCTURE_RULES } from "./plan-rules.js";
 import { ADVISOR_SYSTEM_PROMPT, buildAdvisorConsultText, type AdvisorConsultInput } from "./advisor.js";
 import { completeSimple, type Message, type TextContent } from "@earendil-works/pi-ai";
 import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
-import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js";
+import { setupSquadWidget, type SquadWidgetControls, 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";
 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 */
@@ -45,7 +53,15 @@ let overlayOpen = false;
 let uiCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = null;
 /** Component-based widget state + controls */
 const widgetState: SquadWidgetState = { squadId: null, enabled: true };
-let widgetControls: { requestUpdate: () => void; dispose: () => void } | null = null;
+let widgetControls: SquadWidgetControls | null = null;
+
+/** Keep main-session focus, compact widget, and detail panel targeting identical. */
+function focusSquad(squadId: string | null): void {
+	activeSquadId = squadId;
+	widgetState.squadId = squadId;
+	if (squadId) widgetState.enabled = true;
+	widgetControls?.refreshNow();
+}
 
 /** Format completion against active work while retaining cancelled history. */
 function formatTaskProgress(tasks: Task[]): string {
@@ -189,11 +205,10 @@ function getActiveScheduler(): Scheduler | 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();
+	const nextFocus = activeSquadId === cancelledId || (activeSquadId !== null && !store.loadSquad(activeSquadId))
+		? null
+		: activeSquadId;
+	focusSquad(nextFocus);
 }
 
 function activeSuspendedAttentionForProject(cwd: string): Array<{ squadId: string; attention: SuspendedStallAttention }> {
@@ -210,10 +225,7 @@ function ensureScheduler(pi: ExtensionAPI, squadId: string, skillPaths: string[]
 		schedulers.set(squadId, scheduler);
 		wireSchedulerEvents(pi, scheduler, squadId);
 	}
-	activeSquadId = squadId;
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	focusSquad(squadId);
 	return scheduler;
 }
 
@@ -240,8 +252,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 = () => {
@@ -301,8 +313,7 @@ export default function (pi: ExtensionAPI) {
 		if (activeSquadId) {
 			const squad = store.loadSquad(activeSquadId);
 			if (!squad) {
-				activeSquadId = null;
-				widgetState.squadId = null;
+				focusSquad(null);
 				if (durablePrompts.length > 0) {
 					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
@@ -327,9 +338,12 @@ export default function (pi: ExtensionAPI) {
 			}).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,
@@ -388,16 +402,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(
@@ -427,7 +443,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 };
@@ -442,13 +463,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);
 		},
 	});
 
@@ -562,6 +587,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, {
@@ -727,7 +759,7 @@ export default function (pi: ExtensionAPI) {
 			if (!activeScheduler) {
 				return { content: [{ type: "text" as const, text: `Squad '${squadId}' has no active scheduler. Use resume, add_task, or resume_task to reconstruct it.` }], details: undefined };
 			}
-			activeSquadId = squadId;
+			focusSquad(squadId);
 
 			switch (params.action) {
 				case "add_task": {
@@ -735,7 +767,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 };
@@ -758,6 +794,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,
@@ -824,7 +861,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);
@@ -848,6 +885,13 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		uiCtx = ctx;
 
+		// A session replacement may not deliver shutdown first. Never carry a
+		// focused squad across projects, and never seed a new widget from stale state.
+		widgetControls?.dispose();
+		widgetControls = null;
+		const focused = activeSquadId ? store.loadSquad(activeSquadId) : null;
+		focusSquad(focused?.cwd === ctx.cwd ? activeSquadId : null);
+
 		// Install component-based widget
 		if (ctx.hasUI) {
 			widgetControls = setupSquadWidget(ctx, widgetState);
@@ -874,6 +918,15 @@ 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.
@@ -905,12 +958,7 @@ export default function (pi: ExtensionAPI) {
 			}
 			await scheduler.start();
 		}
-		if (pendingMailSquads.length > 0) {
-			activeSquadId = pendingMailSquads[0].id;
-			widgetState.squadId = activeSquadId;
-			widgetState.enabled = true;
-			widgetControls?.requestUpdate();
-		}
+		if (pendingMailSquads.length > 0) focusSquad(pendingMailSquads[0].id);
 
 		// Notify about paused squads only if they have real completed work
 		const paused = store.findActiveSquads()
@@ -923,7 +971,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,
 				});
@@ -936,10 +984,7 @@ export default function (pi: ExtensionAPI) {
 			.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();
+			focusSquad(squad.id);
 			const tasks = store.loadAllTasks(squad.id);
 			pi.sendMessage({
 				customType: "squad-review-required",
@@ -978,13 +1023,13 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async () => {
+		focusSquad(null);
 		widgetControls?.dispose();
 		widgetControls = null;
 		for (const [id, sched] of schedulers) {
 			await sched.stop();
 		}
 		schedulers.clear();
-		activeSquadId = null;
 		uiCtx = null;
 	});
 
@@ -1209,8 +1254,7 @@ export default function (pi: ExtensionAPI) {
 
 				case "clear": {
 					if (activeSquadId) schedulers.delete(activeSquadId);
-					activeSquadId = null;
-					widgetState.squadId = null;
+					focusSquad(null);
 					widgetControls?.dispose();
 					ctx.ui.notify("Squad view cleared", "info");
 					return;
@@ -1231,9 +1275,7 @@ export default function (pi: ExtensionAPI) {
 							await sched.stop();
 						}
 						schedulers.clear();
-						activeSquadId = null;
-						widgetState.squadId = null;
-						widgetControls?.requestUpdate();
+						focusSquad(null);
 
 						let count = 0;
 						for (const id of allSquadIds) {
@@ -1269,9 +1311,7 @@ export default function (pi: ExtensionAPI) {
 							await sched.stop();
 						}
 						schedulers.clear();
-						activeSquadId = null;
-						widgetState.squadId = null;
-						widgetControls?.requestUpdate();
+						focusSquad(null);
 						let count = 0;
 						for (const id of allSquadIds) {
 							fs.rmSync(store.getSquadDir(id), { recursive: true, force: true });
@@ -1289,11 +1329,7 @@ export default function (pi: ExtensionAPI) {
 								await sched.stop();
 								schedulers.delete(squad.id);
 							}
-							if (activeSquadId === squad.id) {
-								activeSquadId = null;
-								widgetState.squadId = null;
-								widgetControls?.requestUpdate();
-							}
+							if (activeSquadId === squad.id) focusSquad(null);
 							fs.rmSync(store.getSquadDir(squad.id), { recursive: true, force: true });
 							ctx.ui.notify(`Deleted: ${squad.id}`, "info");
 						}
@@ -1315,10 +1351,8 @@ export default function (pi: ExtensionAPI) {
 						await sched.stop();
 					}
 					schedulers.clear();
-					activeSquadId = null;
-					widgetState.squadId = null;
 					widgetState.enabled = false;
-					widgetControls?.requestUpdate();
+					focusSquad(null);
 					ctx.ui.notify("pi-squad disabled — all tools, widget, and system prompt injection stopped", "info");
 					return;
 				}
@@ -1590,13 +1624,9 @@ function activateSquadView(squadId: string, ctx: import("@earendil-works/pi-codi
 		return;
 	}
 
-	activeSquadId = squadId;
-
-	// Update widget to show the new squad. The widget reads squadId on each
-	// render, so just updating the state and requesting a render is enough.
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	// Selection is one atomic focus operation: panel, widget, status, and tools
+	// must all target this exact squad before control returns to the caller.
+	focusSquad(squadId);
 
 	// Compact notification — widget already shows full task details.
 	// Avoid large multi-line notifications that can break TUI layout.
@@ -1700,6 +1730,9 @@ function openPanel(
 	squadId: string,
 ): void {
 	if (overlayOpen) return;
+	// Opening details also establishes authoritative focus. This covers callers
+	// that reconstructed or targeted a scheduler without going through selector UI.
+	focusSquad(squadId);
 	overlayOpen = true;
 
 	// The promise resolves when the panel calls done()
@@ -1757,23 +1790,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;
 
@@ -1791,7 +1813,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}`;
@@ -1809,7 +1832,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 };
@@ -1829,6 +1852,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 = {
@@ -1840,12 +1865,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,
@@ -1861,21 +1892,20 @@ 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
 	const scheduler = new Scheduler(squadId, skillPaths, schedulerSpawnContext);
 	schedulers.set(squadId, scheduler);
-	activeSquadId = squadId;
-
-	// Activate widget for this squad
-	widgetState.squadId = squadId;
-	widgetState.enabled = true;
-	widgetControls?.requestUpdate();
+	// Activate panel/widget/tool focus as one invariant.
+	focusSquad(squadId);
 
 	// Wire up completion/escalation notifications to main agent.
 	wireSchedulerEvents(pi, scheduler, squadId);
@@ -1888,13 +1918,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

@@ -43,6 +43,12 @@ export interface SquadWidgetState {
 	enabled: boolean;
 }
 
+export interface SquadWidgetControls {
+	requestUpdate: () => void;
+	refreshNow: () => void;
+	dispose: () => void;
+}
+
 /**
  * Set up the squad widget. Returns control functions.
  *
@@ -53,11 +59,8 @@ export interface SquadWidgetState {
 export function setupSquadWidget(
 	ctx: { ui: { setWidget: Function; setStatus: Function; [key: string]: any }; hasUI?: boolean },
 	state: SquadWidgetState,
-): {
-	requestUpdate: () => void;
-	dispose: () => void;
-} {
-	if (!ctx.hasUI) return { requestUpdate: () => {}, dispose: () => {} };
+): SquadWidgetControls {
+	if (!ctx.hasUI) return { requestUpdate: () => {}, refreshNow: () => {}, dispose: () => {} };
 
 	let durationTimer: ReturnType<typeof setInterval> | null = null;
 	let renderTimer: ReturnType<typeof setTimeout> | null = null;
@@ -269,9 +272,14 @@ export function setupSquadWidget(
 		}
 	}
 
+	function refreshNow(): void {
+		if (renderTimer) { clearTimeout(renderTimer); renderTimer = null; }
+		render();
+		manageDurationTimer();
+	}
+
 	// Initial render
-	render();
-	manageDurationTimer();
+	refreshNow();
 
 	return {
 		requestUpdate(): void {
@@ -279,14 +287,17 @@ export function setupSquadWidget(
 			if (renderTimer) return;
 			renderTimer = setTimeout(() => {
 				renderTimer = null;
-				render();
-				manageDurationTimer();
+				refreshNow();
 			}, 50);
 		},
+		refreshNow,
 		dispose(): void {
 			if (durationTimer) { clearInterval(durationTimer); durationTimer = null; }
 			if (renderTimer) { clearTimeout(renderTimer); renderTimer = null; }
 			lastCacheKey = "";
+			currentLines = [];
+			widgetInstalled = false;
+			widgetComponent = null;
 			ctx.ui.setWidget("squad-tasks", undefined);
 			ctx.ui.setStatus("squad", undefined);
 		},

package/src/protocol.ts

@@ -311,6 +311,27 @@ export function buildAgentSystemPrompt(options: ProtocolBuildOptions): string {
 	const { squadId, squad, task, agentDef, modifiedFiles, queuedMessages } = options;
 	const allTasks = loadAllTasks(squadId);
 
+	if (squad.spec) {
+		const manifest = [
+			"# File-spec squad bootstrap",
+			`Squad ID: ${squad.id}`,
+			`Task ID: ${task.id}`,
+			`Spec SHA-256: ${squad.spec.sha256}`,
+			`Spec bytes: ${squad.spec.bytes}`,
+			`Chunk count: ${squad.spec.chunkCount}`,
+			"Read every canonical chunk with squad_spec_read before using normal tools or completing the task.",
+		].join("\n");
+		const fileSections = [
+			manifest,
+			buildAgentIdentity(agentDef),
+			...(task.fileSpecDelta ? [buildTaskSection(task), buildReworkContext(task, squadId)] : []),
+			buildChainContext(task, allTasks, squadId),
+			buildKnowledgeSection(squadId),
+			buildQueuedMessages(queuedMessages),
+		].filter((section) => section.length > 0);
+		return fileSections.join("\n---\n\n");
+	}
+
 	const sections = [
 		buildSquadProtocol(task.agent, agentDef, squad),
 		buildAgentIdentity(agentDef),

package/src/review.ts

@@ -1,3 +1,4 @@
+import * as path from "node:path";
 import type { Squad, Task } from "./types.js";
 
 export type OrchestratorReviewVerdict = "pass" | "pass_with_issues" | "fail";
@@ -99,15 +100,18 @@ export function buildOrchestratorReviewGate(squad: Squad, tasks: Task[]): string
 	const reviewAction = failed
 		? `This candidate was rejected. Do not submit another verdict yet. Start concrete rework in this same exact squad with squad_modify and squadId: "${squad.id}"; the failed evidence remains immutable history. After rework settles, a fresh REVIEW PENDING gate will require a new independent review.`
 		: `This candidate is awaiting its first verdict. Complete the checks below, then call squad_review for squadId: "${squad.id}".`;
-	const delegatedPlan = tasks
-		.map((task) => `- ${task.id} (${task.agent}): ${task.title}\n  ${task.description || "(no description)"}`)
-		.join("\n");
+	const goalReference = squad.spec
+		? `Canonical file spec at ${squad.spec.path} (sha256=${squad.spec.sha256}, bytes=${squad.spec.bytes}). Read and hash the exact file during review; its contract is intentionally not duplicated into this prompt.`
+		: squad.goal;
+	const delegatedPlan = squad.spec
+		? tasks.map((task) => `- ${task.id} (${task.agent}) [${task.status}] — task state: ${path.join(path.dirname(path.dirname(squad.spec!.path)), task.id, "task.json")}`).join("\n")
+		: 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}
+Recorded squad goal (secondary reference): ${goalReference}
 Acceptance: ${reviewLabel}
 ${reviewAction}