pi-squad 0.16.7 → 0.17.0

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";
@@ -28,11 +28,19 @@ 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 */
@@ -240,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 = () => {
@@ -327,9 +335,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 +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(
@@ -427,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 };
@@ -442,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);
 		},
 	});
 
@@ -562,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, {
@@ -735,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 };
@@ -758,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,
@@ -824,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);
@@ -874,6 +908,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.
@@ -923,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,
 				});
@@ -1757,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;
 
@@ -1791,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}`;
@@ -1809,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 };
@@ -1829,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 = {
@@ -1840,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,
@@ -1861,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
@@ -1888,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/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}
 

package/src/scheduler.ts

@@ -16,6 +16,7 @@ import { AgentPool, type AgentEvent } from "./agent-pool.js";
 import { Monitor } from "./monitor.js";
 import { Router } from "./router.js";
 import * as store from "./store.js";
+import { isFileSpecTaskId, validateCanonicalSpec, validateTaskSpecAttestation } from "./file-spec.js";
 import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
 import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
@@ -211,6 +212,29 @@ export class Scheduler {
 		}
 	}
 
+	/** Revalidate durable file-spec completion evidence after parent restart/review recovery. */
+	async auditSpecAttestations(): Promise<string[]> {
+		const squad = store.loadSquad(this.squadId); if (!squad?.spec) return [];
+		const tasks = store.loadAllTasks(this.squadId);
+		if (!validateCanonicalSpec(squad)) {
+			const quarantined = tasks.filter((task) => task.status !== "cancelled");
+			for (const task of quarantined) {
+				if (task.status === "done") await this.invalidateDescendants(task.id);
+				if (task.status === "in_progress" || task.status === "done") store.updateTaskStatus(this.squadId, task.id, "pending", { completed: null, output: null, error: "Canonical spec integrity failure" });
+				else store.updateTaskStatus(this.squadId, task.id, task.status, { error: "Canonical spec integrity failure" });
+			}
+			return quarantined.map((task) => task.id);
+		}
+		const invalid = tasks.filter((task) => task.status === "done" && !validateTaskSpecAttestation(squad, task));
+		for (const task of invalid) {
+			store.updateTaskStatus(this.squadId, task.id, "pending", { completed: null, output: null, error: "Missing or invalid canonical spec read attestation" });
+			store.appendMessage(this.squadId, task.id, { ts: store.now(), from: "system", type: "status", text: "Completion invalidated after attestation audit" });
+			await this.invalidateDescendants(task.id);
+		}
+		if (invalid.length > 0 && squad.status === "review") { squad.status = "running"; delete squad.review; store.saveSquad(squad); }
+		return invalid.map((task) => task.id);
+	}
+
 	/** Get references for external use */
 	getPool(): AgentPool {
 		return this.pool;
@@ -308,6 +332,12 @@ export class Scheduler {
 		if (!this.running) return;
 		const squad = store.loadSquad(this.squadId);
 		if (!squad) return;
+		// Canonical integrity is a scheduling precondition, not merely a completion check.
+		if (squad.spec && !validateCanonicalSpec(squad)) {
+			await this.auditSpecAttestations();
+			debug("squad-scheduler", "reconcile: canonical spec integrity failure — scheduling quarantined");
+			return;
+		}
 
 		const tasks = store.loadAllTasks(this.squadId);
 
@@ -387,8 +417,8 @@ export class Scheduler {
 		}
 
 		const squad = store.loadSquad(this.squadId);
-		if (!squad || squad.status !== "running") {
-			debug("squad-scheduler", `scheduleReadyTasks: squad status=${squad?.status}, skipping`);
+		if (!squad || squad.status !== "running" || (squad.spec && !validateCanonicalSpec(squad))) {
+			debug("squad-scheduler", `scheduleReadyTasks: squad unavailable, inactive, or canonical integrity invalid; status=${squad?.status}`);
 			return;
 		}
 
@@ -536,6 +566,7 @@ export class Scheduler {
 				},
 				cwd: squad.cwd,
 				skillPaths: this.skillPaths,
+				...(squad.spec ? { spec: { squadId: squad.id, path: squad.spec.path, sha256: squad.spec.sha256, bytes: squad.spec.bytes, chunkBytes: squad.spec.chunkBytes } } : {}),
 				...(resumeSession
 					? { resumeSession }
 					: forkSessionFile
@@ -684,16 +715,25 @@ export class Scheduler {
 		entries: TaskMailboxEntry[],
 		legacySeed?: { messages: TaskMessage[]; output: string | null },
 	): string {
-		const lines = resumed
+		const fileSpec = store.loadSquad(this.squadId)?.spec;
+		const lines = fileSpec
 			? [
-					`Resume your existing task: ${task.title}`,
-					"Continue from the durable Pi session context. Do not restart the task from scratch.",
+					`${resumed ? "Resume" : "Start"} file-spec squad task ${task.id}.`,
+					`Canonical spec: sha256=${fileSpec.sha256} bytes=${fileSpec.bytes} chunks=${fileSpec.chunkCount}.`,
+					"Use squad_spec_read to receive every canonical chunk before normal tools or completion.",
+					...(task.fileSpecDelta ? ["", `Dynamic task delta: ${task.title}`, task.description] : []),
+					...(resumed ? ["Continue from this task's durable Pi session and existing read coverage."] : []),
 				]
-			: [
-					`Your task: ${task.title}`,
-					"",
-					task.description || "",
-				];
+			: resumed
+				? [
+						`Resume your existing task: ${task.title}`,
+						"Continue from the durable Pi session context. Do not restart the task from scratch.",
+					]
+				: [
+						`Your task: ${task.title}`,
+						"",
+						task.description || "",
+					];
 
 		if (legacySeed) {
 			const pendingIds = new Set(entries.map((entry) => entry.id));
@@ -854,8 +894,17 @@ export class Scheduler {
 			}
 
 			case "agent_settled": {
-				const status = store.loadTask(this.squadId, event.taskId)?.status;
+				const settledTask = store.loadTask(this.squadId, event.taskId);
+				const status = settledTask?.status;
 				if (status === "cancelled" || status === "suspended") return;
+				const settledSquad = store.loadSquad(this.squadId);
+				if (settledTask && settledSquad && !validateTaskSpecAttestation(settledSquad, settledTask)) {
+					store.updateTaskStatus(this.squadId, event.taskId, "pending", { completed: null, output: null, error: "Canonical squad spec was not fully delivered; read all chunks with squad_spec_read" });
+					store.appendMessage(this.squadId, event.taskId, { ts: store.now(), from: "system", type: "status", text: "Completion rejected: missing or invalid spec-read-attestation; reopening same task session" });
+					if (this.running) void this.reconcile();
+					this.updateContext();
+					return;
+				}
 				// A mailbox entry not acknowledged by Pi outranks this run's candidate
 				// completion. Reopen the same session so accepted-at-least-once delivery
 				// occurs before the task can become done.
@@ -913,7 +962,12 @@ export class Scheduler {
 
 		// Extract output from last messages
 		const messages = store.loadMessages(this.squadId, taskId);
+		const squad = store.loadSquad(this.squadId);
+		const rejectedAt = squad?.spec
+			? messages.reduce((last, message, index) => message.from === "system" && message.type === "status" && message.text.startsWith("Completion rejected: missing or invalid spec-read-attestation") ? index : last, -1)
+			: -1;
 		const agentMessages = messages
+			.slice(rejectedAt + 1)
 			.filter((m) => m.from === task.agent && (m.type === "text" || m.type === "done"));
 		const output = agentMessages.map((m) => m.text).join("\n");
 
@@ -1117,6 +1171,11 @@ export class Scheduler {
 
 			// Create rework task for the original agent
 			const reworkId = `${originalId}-fix-${fixN}`;
+			const retestId = `${task.id}-retest-${fixN}`;
+			if (squad.spec && (!isFileSpecTaskId(reworkId) || !isFileSpecTaskId(retestId))) {
+				this.handleTaskFailed(task.id, `Generated file-spec rework IDs exceed the safe task-ID contract: ${reworkId}, ${retestId}`);
+				return true;
+			}
 			const reworkTask: Task = {
 				id: reworkId,
 				title: `Fix: ${implTask.title} (attempt ${fixN})`,
@@ -1125,6 +1184,7 @@ export class Scheduler {
 				status: "pending",
 				depends: [],
 				...(implTask.inheritContext ? { inheritContext: true } : {}),
+				...(squad.spec ? { fileSpecDelta: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,
@@ -1138,7 +1198,6 @@ export class Scheduler {
 			store.createTask(this.squadId, reworkTask);
 
 			// Create retest task for QA
-			const retestId = `${task.id}-retest-${fixN}`;
 			const retestTask: Task = {
 				id: retestId,
 				title: `Re-test: ${implTask.title} (after fix ${fixN})`,
@@ -1146,6 +1205,7 @@ export class Scheduler {
 				agent: task.agent,
 				status: "blocked",
 				depends: [reworkId],
+				...(squad.spec ? { fileSpecDelta: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,
@@ -1227,6 +1287,18 @@ export class Scheduler {
 	private checkSquadCompletion(tasks: Task[], squad: Squad): void {
 		if (tasks.length === 0) return;
 
+		const invalidDone = tasks.filter((task) => task.status === "done" && !validateTaskSpecAttestation(squad, task));
+		if (invalidDone.length > 0) {
+			for (const task of invalidDone) {
+				store.updateTaskStatus(this.squadId, task.id, "pending", { completed: null, output: null, error: "Missing or invalid canonical spec read attestation" });
+				store.appendMessage(this.squadId, task.id, { ts: store.now(), from: "system", type: "status", text: "Completion invalidated: canonical spec attestation is missing or invalid" });
+				void this.invalidateDescendants(task.id);
+			}
+			if (squad.status === "review") { squad.status = "running"; delete squad.review; store.saveSquad(squad); }
+			if (this.running) void this.reconcile();
+			return;
+		}
+
 		const relevant = tasks.filter((task) => task.status !== "cancelled");
 		const allDone = relevant.every((task) => task.status === "done");
 		const anyFailed = relevant.some((task) => task.status === "failed");
@@ -1617,6 +1689,8 @@ export class Scheduler {
 		if (!task) throw new Error(`Task not found: ${taskId}`);
 		if (task.status === "done") return;
 		if (task.status === "cancelled") throw new Error(`Task '${taskId}' is cancelled; resume it before marking it done.`);
+		const squad = store.loadSquad(this.squadId);
+		if (squad && !validateTaskSpecAttestation(squad, task)) throw new Error(`Task '${taskId}' cannot complete: missing or invalid canonical spec read attestation.`);
 
 		if (this.pool.isRunning(taskId)) {
 			await this.pool.kill(taskId);

package/src/store.ts

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import type {
 	AgentDef,
 	KnowledgeEntry,
@@ -314,13 +314,50 @@ export function saveSquad(squad: Squad): void {
 	writeJsonAtomic(getSquadFilePath(squad.id), squad);
 }
 
+/** Atomically publish a new file-spec squad, canonical bytes and initial tasks as one directory rename. */
+export function publishFileSquad(squad: Squad, tasks: Task[], canonicalBytes: Buffer): void {
+	if (!squad.spec) throw new Error("PUBLISH_FAILED: file squad is missing spec metadata");
+	const root = path.resolve(getSquadRoot()); ensureDir(root);
+	if (!/^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/.test(squad.id)) throw new Error(`PUBLISH_FAILED: unsafe squad id ${squad.id}`);
+	const finalDir = path.resolve(getSquadDir(squad.id));
+	if (path.dirname(finalDir) !== root) throw new Error(`PUBLISH_FAILED: squad destination escapes root`);
+	const expectedSpecPath = path.join(finalDir, "spec", "spec.v1.json");
+	if (path.resolve(squad.spec.path) !== expectedSpecPath || canonicalBytes.length !== squad.spec.bytes || createHash("sha256").update(canonicalBytes).digest("hex") !== squad.spec.sha256) throw new Error("PUBLISH_FAILED: canonical bytes or destination do not match spec metadata");
+	const taskIds = new Set<string>();
+	for (const task of tasks) {
+		if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(task.id) || taskIds.has(task.id)) throw new Error(`PUBLISH_FAILED: unsafe or duplicate task id ${task.id}`);
+		taskIds.add(task.id);
+	}
+	if (fs.existsSync(finalDir)) throw new Error(`PUBLISH_FAILED: squad ${squad.id} already exists`);
+	const stagingDir = path.join(root, `${squad.id}.creating.${randomUUID()}`);
+	fs.mkdirSync(stagingDir, { mode: 0o700 });
+	try {
+		const writeDurable = (filePath: string, content: string): void => { const fd = fs.openSync(filePath, "wx", 0o600); try { fs.writeFileSync(fd, content); fs.fsyncSync(fd); } finally { fs.closeSync(fd); } };
+		const specDir = path.join(stagingDir, "spec"); fs.mkdirSync(specDir, { mode: 0o700 });
+		const specPath = path.join(specDir, "spec.v1.json"); const specFd = fs.openSync(specPath, "wx", 0o600);
+		try { fs.writeFileSync(specFd, canonicalBytes); fs.fsyncSync(specFd); } finally { fs.closeSync(specFd); }
+		try { fs.chmodSync(specPath, 0o400); } catch { /* Windows/best effort */ }
+		for (const task of tasks) {
+			const taskDir = path.join(stagingDir, task.id); fs.mkdirSync(taskDir, { mode: 0o700 });
+			writeDurable(path.join(taskDir, "task.json"), JSON.stringify(task, null, 2) + "\n");
+		}
+		writeDurable(path.join(stagingDir, "squad.json"), JSON.stringify(squad, null, 2) + "\n");
+		for (const dir of [specDir, stagingDir]) { try { const fd = fs.openSync(dir, fs.constants.O_RDONLY); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } } catch { /* directory fsync unavailable */ } }
+		fs.renameSync(stagingDir, finalDir);
+		try { const fd = fs.openSync(root, fs.constants.O_RDONLY); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } } catch { /* directory fsync unavailable */ }
+	} catch (error) {
+		try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch { /* preserve original failure */ }
+		throw new Error(`PUBLISH_FAILED: ${(error as Error).message}`);
+	}
+}
+
 export function listSquads(): string[] {
 	const root = getSquadRoot();
 	if (!fs.existsSync(root)) return [];
 	return fs
 		.readdirSync(root)
 		.filter((entry) => {
-			if (entry === "agents" || entry === "memory.jsonl") return false;
+			if (entry === "agents" || entry === "memory.jsonl" || entry.includes(".creating.")) return false;
 			const squadFile = path.join(root, entry, "squad.json");
 			return fs.existsSync(squadFile);
 		});

package/src/types.ts

@@ -123,6 +123,8 @@ export interface Squad {
 	/** Agent name → overrides. Keys must exist in .pi/squad/agents/ */
 	agents: Record<string, SquadAgentEntry>;
 	config: SquadConfig;
+	/** Immutable canonical contract for file-based squads; absent for legacy inline squads. */
+	spec?: { schemaVersion: 1; sha256: string; bytes: number; path: string; chunkBytes: 32768; chunkCount: number };
 	/** Mandatory independent main-session review; absent while rework is running. */
 	review?: SquadReview;
 	/** Completed prior review attempts retained as same-squad audit evidence. */
@@ -170,6 +172,8 @@ export interface Task {
 	usage: TaskUsage;
 	/** Durable Pi context for this task. Absent until its first process creates a session. */
 	session?: TaskSession;
+	/** Dynamic task delta created after immutable file-spec publication. */
+	fileSpecDelta?: boolean;
 	/** If this is a rework task, the original task ID it's fixing */
 	retryOf?: string;
 	/** How many times this task chain has been retried */
@@ -298,7 +302,7 @@ export interface SupervisorResult {
 // ============================================================================
 
 export interface PlannerOutput {
-	agents: Record<string, { model?: string; thinking?: string }>;
+	agents: Record<string, SquadAgentEntry>;
 	tasks: Array<{
 		id: string;
 		title: string;