pi-squad 0.16.6 → 0.17.0

package/src/panel/task-list.ts

@@ -6,6 +6,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { Task, TaskStatus } from "../types.js";
 import type { Scheduler } from "../scheduler.js";
+import { formatSuspendedAttention, getReviewPresentation } from "../presentation.js";
 import * as store from "../store.js";
 
 // ============================================================================
@@ -90,6 +91,15 @@ export class TaskListView {
 		bottomLines.push("");
 		bottomLines.push(truncateToWidth(th.fg("border", " " + "─".repeat(width - 2)), width, ""));
 
+		const squad = store.loadSquad(this.squadId);
+		const review = squad ? getReviewPresentation(squad) : null;
+		if (review) bottomLines.push(truncateToWidth(` ${th.fg(review.tone, review.label)}`, width, ""));
+		if (squad) {
+			for (const line of formatSuspendedAttention(squad)) {
+				bottomLines.push(truncateToWidth(` ${th.fg("warning", line)}`, width, ""));
+			}
+		}
+
 		const runningTask = tasks.find((t) => t.status === "in_progress");
 		if (runningTask) {
 			bottomLines.push(...this.renderLiveActivity(runningTask, width, scheduler));

package/src/presentation.ts

@@ -0,0 +1,38 @@
+import type { Squad, SuspendedStallAttention } from "./types.js";
+
+export const REVIEW_PENDING_LABEL = "◆ REVIEW PENDING · independent review required";
+export const REVIEW_FAILED_LABEL = "✗ REVIEW FAILED · awaiting same-squad rework";
+export const SUSPENDED_ATTENTION_LABEL = "⚠ SUSPENDED — explicit resume required";
+
+export interface ReviewPresentation {
+	kind: "pending" | "failed";
+	icon: "◆" | "✗";
+	label: string;
+	tone: "warning" | "error";
+}
+
+/** Keep execution progress separate from the independent acceptance gate. */
+export function getReviewPresentation(squad: Squad): ReviewPresentation | null {
+	if (squad.status !== "review") return null;
+	if (squad.review?.status === "failed") {
+		return { kind: "failed", icon: "✗", label: REVIEW_FAILED_LABEL, tone: "error" };
+	}
+	return { kind: "pending", icon: "◆", label: REVIEW_PENDING_LABEL, tone: "warning" };
+}
+
+export function getSuspendedAttention(squad: Squad): SuspendedStallAttention | null {
+	return squad.suspendedStallAttention?.kind === "suspended_stall" ? squad.suspendedStallAttention : null;
+}
+
+/** Full-fidelity operator output. Terminal components may clip only while rendering. */
+export function formatSuspendedAttention(squad: Squad): string[] {
+	const attention = getSuspendedAttention(squad);
+	if (!attention) return [];
+	return [
+		`Attention: ${SUSPENDED_ATTENTION_LABEL}`,
+		`Suspended task IDs: ${attention.suspendedTaskIds.join(", ")}`,
+		`Blocked by suspended work: ${attention.blockedTaskIds.length > 0 ? attention.blockedTaskIds.join(", ") : "none"}`,
+		`No task was resumed automatically.`,
+		`Resume intentionally with squad_modify { action: "resume_task", squadId: "${squad.id}", taskId: "<exact-task-id>" } for each task you choose.`,
+	];
+}

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";
@@ -92,15 +93,27 @@ export function recordOrchestratorReview(squad: Squad, input: OrchestratorReview
 
 /** Persistent system-prompt contract shown until squad_review accepts the work. */
 export function buildOrchestratorReviewGate(squad: Squad, tasks: Task[]): string {
-	const delegatedPlan = tasks
-		.map((task) => `- ${task.id} (${task.agent}): ${task.title}\n  ${task.description || "(no description)"}`)
-		.join("\n");
+	const failed = squad.review?.status === "failed";
+	const reviewLabel = failed
+		? "✗ REVIEW FAILED · awaiting same-squad rework"
+		: "◆ REVIEW PENDING · independent review required";
+	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 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}
 
 Delegated plan (non-authoritative):
 ${delegatedPlan}
@@ -111,9 +124,9 @@ Before reporting success, completion, or acceptance to the user, YOU (the main P
 3. Independently run the original Verify commands and appropriate build/tests. Do not rely on pasted squad output.
 4. Run integration/E2E in the real target or production-like environment when the request affects runtime behavior. If genuinely not applicable or impossible, record the precise reason and mark it unverified.
 5. Fix discovered defects and repeat checks. Squad QA PASS does not override your findings.
-6. Call squad_review with contract checks, diff review, actual command/result evidence, integration/E2E evidence, and remaining issues.
+6. When the active gate is REVIEW PENDING, call squad_review with contract checks, diff review, actual command/result evidence, integration/E2E evidence, and remaining issues. When it is REVIEW FAILED, route same-squad rework first; another verdict cannot overwrite the failed evidence.
 
-Do not ask the user whether you should verify. Do not merely summarize the squad report. Until squad_review records PASS/PASS_WITH_ISSUES, the work is not accepted.
+Do not ask the user whether you should verify. Do not merely summarize the squad report. Until fresh rework is independently reviewed and squad_review records PASS/PASS_WITH_ISSUES, the work is not accepted.
 </squad_review_required>`;
 }
 

package/src/scheduler.ts

@@ -11,11 +11,12 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { AgentDef, Squad, SquadConfig, Task, TaskMailboxEntry, TaskMessage, TaskStatus } from "./types.js";
+import type { AgentDef, Squad, SquadConfig, SuspendedStallAttention, Task, TaskMailboxEntry, TaskMessage, TaskStatus } from "./types.js";
 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";
@@ -34,6 +35,7 @@ export type SchedulerEventType =
 	| "task_rework"
 	| "squad_review_required"
 	| "squad_failed"
+	| "suspended_stall"
 	| "orchestrator_reply"
 	| "escalation"
 	| "activity";
@@ -49,6 +51,61 @@ export interface SchedulerEvent {
 
 export type SchedulerEventListener = (event: SchedulerEvent) => void;
 
+export interface SuspendedStallState {
+	fingerprint: string;
+	suspendedTaskIds: string[];
+	blockedTaskIds: string[];
+}
+
+/** Pure derivation of an explicit-suspension stall from one persisted DAG. */
+export function deriveSuspendedStall(tasks: Task[]): SuspendedStallState | null {
+	const relevant = tasks.filter((task) => task.status !== "cancelled");
+	const byId = new Map(relevant.map((task) => [task.id, task]));
+	const suspendedTaskIds = relevant
+		.filter((task) => task.status === "suspended")
+		.map((task) => task.id)
+		.sort((left, right) => left.localeCompare(right));
+	if (suspendedTaskIds.length === 0) return null;
+	const suspended = new Set(suspendedTaskIds);
+
+	const reachesSuspended = (taskId: string, seen = new Set<string>()): boolean => {
+		if (suspended.has(taskId)) return true;
+		if (seen.has(taskId)) return false;
+		seen.add(taskId);
+		const task = byId.get(taskId);
+		if (!task) return false;
+		return task.depends.some((dependencyId) => reachesSuspended(dependencyId, seen));
+	};
+	const suspensionBlocked = (task: Task): boolean => task.status === "blocked" && task.depends.some((dependencyId) => {
+		const dependency = byId.get(dependencyId);
+		return dependency?.status !== "done" && reachesSuspended(dependencyId);
+	});
+	const runnableOrLive = relevant.some((task) => task.status === "in_progress" || (
+		task.status === "pending" && task.depends.every((dependencyId) => byId.get(dependencyId)?.status === "done")
+	));
+	if (runnableOrLive) return null;
+
+	const blockedTaskIds = relevant.filter(suspensionBlocked).map((task) => task.id).sort((left, right) => left.localeCompare(right));
+	const blocked = new Set(blockedTaskIds);
+	const terminal = new Set<TaskStatus>(["done", "failed", "cancelled"]);
+	if (!relevant.every((task) => suspended.has(task.id) || terminal.has(task.status) || blocked.has(task.id))) return null;
+
+	return {
+		fingerprint: JSON.stringify([suspendedTaskIds, blockedTaskIds]),
+		suspendedTaskIds,
+		blockedTaskIds,
+	};
+}
+
+/** Complete, actionable wake text; semantic task IDs are never abbreviated. */
+export function formatSuspendedStallAttention(squadId: string, attention: Pick<SuspendedStallAttention, "suspendedTaskIds" | "blockedTaskIds">): string {
+	return `[squad] SUSPENDED WORK NEEDS ACTION in '${squadId}'.\n` +
+		`Suspended task IDs: ${attention.suspendedTaskIds.join(", ")}\n` +
+		`Blocked by suspended work: ${attention.blockedTaskIds.length > 0 ? attention.blockedTaskIds.join(", ") : "none"}\n` +
+		"No task was resumed automatically.\n" +
+		`Resume intentionally with squad_modify { action: "resume_task", squadId: "${squadId}", taskId: "<exact-task-id>" } for each task you choose.`;
+}
+
 /** Host-session capabilities passed in by the extension (index.ts) */
 export interface SchedulerSpawnContext {
 	/** Resolve a model string (or null = default model) to its context window in tokens */
@@ -76,6 +133,8 @@ export class Scheduler {
 	private spawnRetries = new Set<string>();
 	/** Periodic level-triggered reconcile (heals missed events / out-of-band store edits) */
 	private reconcileTimer: ReturnType<typeof setInterval> | null = null;
+	/** Suppress duplicate edge emission within one scheduler; disk remains the outbox. */
+	private attentionEmittedFingerprint: string | null = null;
 
 	/** Get the project cwd for this squad (from squad.json) */
 	getProjectCwd(): string | undefined {
@@ -153,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;
@@ -250,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);
 
@@ -258,7 +346,7 @@ export class Scheduler {
 		// mutation/RPC delivery, reopen exactly that task on reconstruction.
 		let recoveredMailbox = false;
 		for (const task of tasks) {
-			if (task.status === "cancelled") continue;
+			if (task.status === "cancelled" || task.status === "suspended") continue;
 			if (this.pool.isRunning(task.id)) continue;
 			if (store.loadPendingTaskMessages(this.squadId, task.id).length === 0) continue;
 			if (task.status === "done") await this.invalidateDescendants(task.id);
@@ -309,6 +397,7 @@ export class Scheduler {
 		}
 
 		await this.scheduleReadyTasks();
+		this.reconcileSuspendedStallAttention();
 
 		const freshSquad = store.loadSquad(this.squadId);
 		if (freshSquad && (freshSquad.status === "running" || freshSquad.status === "failed")) {
@@ -328,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;
 		}
 
@@ -477,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
@@ -625,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));
@@ -664,7 +763,8 @@ export class Scheduler {
 	}
 
 	private handleUnexpectedAgentExit(event: AgentEvent): void {
-		if (store.loadTask(this.squadId, event.taskId)?.status === "cancelled") return;
+		const status = store.loadTask(this.squadId, event.taskId)?.status;
+		if (status === "cancelled" || status === "suspended") return;
 		const exitCode = event.data?.exitCode ?? 1;
 		const turnCount = event.data?.turnCount ?? 0;
 		const stderr = event.data?.stderr || "";
@@ -794,7 +894,17 @@ export class Scheduler {
 			}
 
 			case "agent_settled": {
-				if (store.loadTask(this.squadId, event.taskId)?.status === "cancelled") return;
+				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.
@@ -846,12 +956,18 @@ export class Scheduler {
 		const task = store.loadTask(this.squadId, taskId);
 		if (!task) return;
 
-		// Guard against double-completion and late callbacks after cancellation.
-		if (task.status === "done" || task.status === "cancelled") return;
+		// Guard against double-completion and late callbacks after cancellation or
+		// an explicit pause. Only exact resume_task may revive suspended work.
+		if (task.status === "done" || task.status === "cancelled" || task.status === "suspended") return;
 
 		// 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");
 
@@ -905,6 +1021,11 @@ export class Scheduler {
 		debug("squad-scheduler", `handleTaskCompleted: scheduling next ready tasks`);
 		await this.scheduleReadyTasks();
 
+		// A completion can remove the last independent runnable task and expose a
+		// stall behind an explicitly suspended task. Derive/wake immediately rather
+		// than waiting for the periodic reconciliation timer.
+		this.reconcileSuspendedStallAttention();
+
 		// Re-check squad completion with fresh data AFTER scheduling
 		const freshTasks = store.loadAllTasks(this.squadId);
 		const freshSquad = store.loadSquad(this.squadId);
@@ -938,6 +1059,9 @@ export class Scheduler {
 		this.pool.kill(taskId);
 		this.updateContext();
 
+		// Failure can likewise expose a suspended-only cut in the remaining DAG.
+		this.reconcileSuspendedStallAttention();
+
 		// Check if squad should be marked failed
 		const tasks = store.loadAllTasks(this.squadId);
 		const squad = store.loadSquad(this.squadId);
@@ -1047,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})`,
@@ -1055,6 +1184,7 @@ export class Scheduler {
 				status: "pending",
 				depends: [],
 				...(implTask.inheritContext ? { inheritContext: true } : {}),
+				...(squad.spec ? { fileSpecDelta: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,
@@ -1068,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})`,
@@ -1076,6 +1205,7 @@ export class Scheduler {
 				agent: task.agent,
 				status: "blocked",
 				depends: [reworkId],
+				...(squad.spec ? { fileSpecDelta: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,
@@ -1157,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");
@@ -1409,6 +1551,7 @@ export class Scheduler {
 			setTimeout(() => this.pool.kill(taskId), 3000);
 		}
 		store.updateTaskStatus(this.squadId, taskId, "suspended");
+		this.reconcileSuspendedStallAttention();
 		this.updateContext();
 	}
 
@@ -1503,9 +1646,12 @@ export class Scheduler {
 
 	/** Resume one exact task. Reopening completed work invalidates descendants and
 	 * archives a completed active review before fresh scheduling begins. */
-	async resumeTask(taskId: string): Promise<void> {
+	async resumeTask(taskId: string): Promise<"resumed" | "already_running"> {
 		const task = store.loadTask(this.squadId, taskId);
 		if (!task) throw new Error(`Task not found: ${taskId}`);
+		const live = this.pool.isRunning(taskId);
+		if (task.status === "in_progress" && live) return "already_running";
+		if (live) throw new Error(`Task '${taskId}' has a live child but durable status '${task.status}'; no duplicate resume was started.`);
 		if (task.status === "done") await this.invalidateDescendants(taskId);
 		const tasks = store.loadAllTasks(this.squadId);
 		const dependenciesDone = task.depends.every(
@@ -1518,6 +1664,18 @@ export class Scheduler {
 		this.reopenSquadForWork();
 		await this.start();
 		this.updateContext();
+		return "resumed";
+	}
+
+	/** Mark an exact pending outbox fingerprint delivered after host acceptance. */
+	acknowledgeSuspendedStall(fingerprint: string): boolean {
+		const squad = store.loadSquad(this.squadId);
+		const attention = squad?.suspendedStallAttention;
+		if (!squad || !attention || attention.fingerprint !== fingerprint || attention.delivery !== "pending") return false;
+		attention.delivery = "delivered";
+		attention.deliveredAt = store.now();
+		store.saveSquad(squad);
+		return true;
 	}
 
 	/**
@@ -1531,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);
@@ -1601,6 +1761,7 @@ export class Scheduler {
 				beginOrchestratorRework(squad);
 				store.saveSquad(squad);
 			}
+			this.reconcileSuspendedStallAttention();
 			this.checkSquadCompletion(store.loadAllTasks(this.squadId), squad);
 		}
 		this.updateContext();
@@ -1610,6 +1771,38 @@ export class Scheduler {
 	// Helpers
 	// =========================================================================
 
+	private reconcileSuspendedStallAttention(): void {
+		const squad = store.loadSquad(this.squadId);
+		if (!squad) return;
+		const derived = deriveSuspendedStall(store.loadAllTasks(this.squadId));
+		if (!derived) {
+			if (squad.suspendedStallAttention) {
+				delete squad.suspendedStallAttention;
+				store.saveSquad(squad);
+			}
+			this.attentionEmittedFingerprint = null;
+			return;
+		}
+
+		let attention = squad.suspendedStallAttention;
+		if (!attention || attention.fingerprint !== derived.fingerprint) {
+			attention = {
+				kind: "suspended_stall",
+				...derived,
+				detectedAt: store.now(),
+				delivery: "pending",
+				deliveredAt: null,
+			};
+			squad.suspendedStallAttention = attention;
+			store.saveSquad(squad);
+			this.attentionEmittedFingerprint = null;
+		}
+		if (attention.delivery === "pending" && this.attentionEmittedFingerprint !== attention.fingerprint) {
+			this.attentionEmittedFingerprint = attention.fingerprint;
+			this.emit({ type: "suspended_stall", squadId: this.squadId, data: attention });
+		}
+	}
+
 	private extractAssistantText(msg: any): string | null {
 		if (!msg.content) return null;
 		const textParts = msg.content

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

@@ -120,6 +120,7 @@ When you receive `[squad] Agent needs attention`:
 4. **If you can't**: ask the user, then relay their answer via `squad_message`
 
 Common escalation patterns:
+- **`SUSPENDED WORK NEEDS ACTION`** → Read every exact suspended task ID and blocked descendant. Do not assume consent and do not use whole-squad `resume`; resume only each intended task with `squad_modify { action: "resume_task", squadId: "<exact squad>", taskId: "<exact task>" }`. Nothing resumes automatically.
 - **"Which approach should I use?"** → Ask the user for preference, relay via `squad_message`
 - **"I need info from another agent"** → Check if that agent is done, relay their output
 - **"I'm blocked by a failing test"** → Check the error, suggest a fix via `squad_message`
@@ -152,12 +153,16 @@ Use `squad_modify` when:
 - **`cancel_task`**: A task is no longer needed. Cancellation is refused while any non-cancelled task directly depends on it. First call `set_dependencies` for every dependent named in the refusal, then retry `cancel_task`. Cancellation never cascades and never removes or rewrites dependencies automatically.
 - **`pause_task`** / **`resume_task`**: Temporarily halt or explicitly revive an agent; `resume_task` is also the only action that revives a cancelled task.
 - **`pause`** / **`resume`**: Stop/restart the entire squad
-- **`cancel`**: Abort everything (user changed their mind)
+- **`cancel`**: Abort everything (user changed their mind). This destructive tool action requires the exact `squadId`; never infer it from focus or recency. The result must name the affected squad. Interactive `/squad cancel` is the only cancellation shorthand that may use the visibly focused squad.
+
+A suspended task is an explicit pause. Scheduler restart, reconciliation, dependency edits, and attention delivery must not be treated as permission to resume it. When durable suspended-stall attention is active, use `squad_status` once to see the complete IDs and exact-squad guidance, then resume only the tasks deliberately chosen.
 
 ## After Agents Finish — Mandatory Independent Orchestrator Review
 
 Agent execution finishing is **not completion or acceptance**. When you receive `[squad] TASK EXECUTION FINISHED` / `<squad_review_required>`, every squad output—including QA PASS—is an untrusted claim. You are the independent acceptance authority.
 
+Read acceptance labels literally: `◆ REVIEW PENDING · independent review required` means review has not happened; `✗ REVIEW FAILED · awaiting same-squad rework` means review happened and rejected the candidate. Task progress such as `3/3` is execution progress only. A failed gate requires concrete rework in that same exact squad before a fresh review can exist; never overwrite the failed verdict or create a separate squad to evade it.
+
 You MUST do all of this before telling the user the work succeeded:
 1. **Re-read the original contract**: reconstruct every requirement, boundary, and later clarification from the user's main-session conversation. The squad goal/task plan is only a secondary aid and cannot narrow the original request.
 2. **Inspect reality, not reports**: read the actual working-tree/commit diff and relevant source. Check every changed line for correctness, scope, integration points, unintended changes, error paths, security, and regressions.

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);
 		});