pi-squad 0.16.5 → 0.16.7

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";
 
 // ============================================================================
@@ -24,6 +25,8 @@ function statusIcon(status: TaskStatus, th: Theme): string {
 			return th.fg("error", "✗");
 		case "suspended":
 			return th.fg("muted", "⏸");
+		case "cancelled":
+			return th.fg("muted", "⊘");
 		case "pending":
 		default:
 			return th.fg("dim", "·");
@@ -42,6 +45,8 @@ function statusLabel(status: TaskStatus): string {
 			return "FAILED";
 		case "suspended":
 			return "paused";
+		case "cancelled":
+			return "cancelled";
 		case "pending":
 			return "pending";
 	}
@@ -86,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));
@@ -241,11 +255,15 @@ export class TaskListView {
 	private renderSummary(tasks: Task[], width: number): string {
 		const th = this.theme;
 		const done = tasks.filter((t) => t.status === "done").length;
+		const cancelled = tasks.filter((t) => t.status === "cancelled").length;
 		const total = tasks.length;
+		const activeTotal = total - cancelled;
 		const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 
 		const parts: string[] = [];
-		parts.push(th.fg("accent", `${done}/${total}`));
+		parts.push(th.fg("accent", cancelled > 0
+			? `${done}/${activeTotal} active tasks done · ${cancelled} cancelled · ${total} total`
+			: `${done}/${total}`));
 		if (totalCost > 0) parts.push(th.fg("dim", `$${totalCost.toFixed(4)}`));
 
 		// Find squad creation time for elapsed

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/report.ts

@@ -5,10 +5,18 @@ import type { Task } from "./types.js";
  * This is durable report data, not a UI preview: never shorten task output.
  */
 export function buildCompletionSummary(tasks: Task[]): string {
-	return tasks
+	const completed = tasks
 		.filter((task) => task.status === "done")
 		.map((task) => `- ${task.id} (${task.agent}): ${task.output || "done"}`)
 		.join("\n");
+	const cancelled = tasks
+		.filter((task) => task.status === "cancelled")
+		.map((task) => `- ${task.id} (${task.agent}): cancelled`)
+		.join("\n");
+
+	return [completed, cancelled ? `CANCELLED TASKS (neutral; not successful output)\n${cancelled}` : ""]
+		.filter(Boolean)
+		.join("\n\n");
 }
 
 /** Build the full failure handoff without shortening diagnostics. */

package/src/review.ts

@@ -92,6 +92,13 @@ 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 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 delegatedPlan = tasks
 		.map((task) => `- ${task.id} (${task.agent}): ${task.title}\n  ${task.description || "(no description)"}`)
 		.join("\n");
@@ -101,6 +108,8 @@ 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}
+Acceptance: ${reviewLabel}
+${reviewAction}
 
 Delegated plan (non-authoritative):
 ${delegatedPlan}
@@ -111,9 +120,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,7 +11,7 @@
 
 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";
@@ -34,6 +34,7 @@ export type SchedulerEventType =
 	| "task_rework"
 	| "squad_review_required"
 	| "squad_failed"
+	| "suspended_stall"
 	| "orchestrator_reply"
 	| "escalation"
 	| "activity";
@@ -49,6 +50,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 +132,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 {
@@ -258,6 +316,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" || 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);
@@ -308,6 +367,12 @@ export class Scheduler {
 		}
 
 		await this.scheduleReadyTasks();
+		this.reconcileSuspendedStallAttention();
+
+		const freshSquad = store.loadSquad(this.squadId);
+		if (freshSquad && (freshSquad.status === "running" || freshSquad.status === "failed")) {
+			this.checkSquadCompletion(store.loadAllTasks(this.squadId), freshSquad);
+		}
 	}
 
 	// =========================================================================
@@ -658,6 +723,8 @@ export class Scheduler {
 	}
 
 	private handleUnexpectedAgentExit(event: AgentEvent): void {
+		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 || "";
@@ -787,6 +854,8 @@ export class Scheduler {
 			}
 
 			case "agent_settled": {
+				const status = store.loadTask(this.squadId, event.taskId)?.status;
+				if (status === "cancelled" || status === "suspended") 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.
@@ -838,8 +907,9 @@ export class Scheduler {
 		const task = store.loadTask(this.squadId, taskId);
 		if (!task) return;
 
-		// Guard against double-completion
-		if (task.status === "done") 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);
@@ -897,6 +967,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);
@@ -907,6 +982,7 @@ export class Scheduler {
 	}
 
 	private handleTaskFailed(taskId: string, error: string): void {
+		if (store.loadTask(this.squadId, taskId)?.status === "cancelled") return;
 		store.updateTaskStatus(this.squadId, taskId, "failed", {
 			error,
 			completed: store.now(),
@@ -929,6 +1005,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);
@@ -1148,10 +1227,11 @@ export class Scheduler {
 	private checkSquadCompletion(tasks: Task[], squad: Squad): void {
 		if (tasks.length === 0) return;
 
-		const allDone = tasks.every((t) => t.status === "done");
-		const anyFailed = tasks.some((t) => t.status === "failed");
-		const anyInProgress = tasks.some(
-			(t) => t.status === "in_progress" || t.status === "pending",
+		const relevant = tasks.filter((task) => task.status !== "cancelled");
+		const allDone = relevant.every((task) => task.status === "done");
+		const anyFailed = relevant.some((task) => task.status === "failed");
+		const anyInProgress = relevant.some(
+			(task) => task.status === "in_progress" || task.status === "pending",
 		);
 
 		if (allDone) {
@@ -1163,9 +1243,9 @@ export class Scheduler {
 			this.emit({ type: "squad_review_required", squadId: this.squadId });
 		} else if (anyFailed && !anyInProgress) {
 			// All remaining tasks are blocked/failed with no way forward
-			const blockedCount = tasks.filter((t) => t.status === "blocked").length;
-			const failedCount = tasks.filter((t) => t.status === "failed").length;
-			if (blockedCount + failedCount === tasks.filter((t) => t.status !== "done").length) {
+			const blockedCount = relevant.filter((task) => task.status === "blocked").length;
+			const failedCount = relevant.filter((task) => task.status === "failed").length;
+			if (blockedCount + failedCount === relevant.filter((task) => task.status !== "done").length) {
 				squad.status = "failed";
 				store.saveSquad(squad);
 				this.emit({ type: "squad_failed", squadId: this.squadId });
@@ -1297,6 +1377,7 @@ export class Scheduler {
 			if (seen.has(descendant.id)) continue;
 			seen.add(descendant.id);
 			queue.push(...(byDependency.get(descendant.id) ?? []));
+			if (descendant.status === "cancelled") continue;
 			store.updateTaskStatus(this.squadId, descendant.id, "blocked", {
 				completed: null,
 				error: null,
@@ -1353,6 +1434,8 @@ export class Scheduler {
 			expectsReply,
 		});
 
+		if (task.status === "cancelled") return false;
+
 		const request = expectsReply
 			? `[squad] Main orchestrator requests a direct response:\n${message}\n\nReply directly in your next assistant message. That complete message will be forwarded automatically to the main session.`
 			: `[squad] Main orchestrator message:\n${message}`;
@@ -1387,12 +1470,16 @@ export class Scheduler {
 
 	/** Pause a running task */
 	async pauseTask(taskId: string): Promise<void> {
+		const task = store.loadTask(this.squadId, taskId);
+		if (!task) throw new Error(`Task not found: ${taskId}`);
+		if (task.status === "cancelled") throw new Error(`Task '${taskId}' is cancelled; use resume_task to revive it.`);
 		if (this.pool.isRunning(taskId)) {
 			await this.pool.steer(taskId, "[squad] Task paused by user. Summarize your current state.");
 			// Give agent a moment to respond, then kill
 			setTimeout(() => this.pool.kill(taskId), 3000);
 		}
 		store.updateTaskStatus(this.squadId, taskId, "suspended");
+		this.reconcileSuspendedStallAttention();
 		this.updateContext();
 	}
 
@@ -1405,11 +1492,94 @@ export class Scheduler {
 		this.updateContext();
 	}
 
+	/** Atomically replace one task's dependency list after validating the complete historical DAG. */
+	async setDependencies(taskId: string, depends: string[]): Promise<void> {
+		const tasks = store.loadAllTasks(this.squadId);
+		const target = tasks.find((task) => task.id === taskId);
+		if (!target) throw new Error(`Task not found: ${taskId}`);
+		if (target.status === "in_progress") {
+			throw new Error(`Cannot edit dependencies for in_progress task '${taskId}'; pause or cancel it first.`);
+		}
+		if (target.status === "done") {
+			throw new Error(`Cannot edit dependencies for done task '${taskId}'; resume it first so descendant invalidation remains authoritative.`);
+		}
+
+		const duplicate = depends.find((dependency, index) => depends.indexOf(dependency) !== index);
+		if (duplicate) throw new Error(`Duplicate dependency '${duplicate}' for task '${taskId}'.`);
+		if (depends.includes(taskId)) throw new Error(`Task '${taskId}' cannot depend on itself.`);
+		const known = new Set(tasks.map((task) => task.id));
+		const unknown = depends.filter((dependency) => !known.has(dependency));
+		if (unknown.length > 0) throw new Error(`Unknown dependency task(s): ${unknown.join(", ")}.`);
+
+		const wasRunnable = target.status === "pending" && target.depends.every(
+			(dependency) => tasks.find((candidate) => candidate.id === dependency)?.status === "done",
+		);
+		const graph = new Map(tasks.map((task) => [task.id, [...task.depends]]));
+		graph.set(taskId, [...depends]);
+		for (const [id, dependencies] of graph) {
+			const seen = new Set<string>();
+			for (const dependency of dependencies) {
+				if (!known.has(dependency)) throw new Error(`Task '${id}' depends on unknown task '${dependency}'.`);
+				if (dependency === id) throw new Error(`Task '${id}' cannot depend on itself.`);
+				if (seen.has(dependency)) throw new Error(`Duplicate dependency '${dependency}' for task '${id}'.`);
+				seen.add(dependency);
+			}
+		}
+		const color = new Map<string, 0 | 1 | 2>();
+		const stack: string[] = [];
+		const visit = (id: string): void => {
+			const state = color.get(id) ?? 0;
+			if (state === 2) return;
+			if (state === 1) {
+				const start = stack.indexOf(id);
+				const cycle = [...stack.slice(start), id];
+				throw new Error(`Dependency cycle detected: ${cycle.join(" -> ")}`);
+			}
+			color.set(id, 1);
+			stack.push(id);
+			for (const dependency of graph.get(id) ?? []) visit(dependency);
+			stack.pop();
+			color.set(id, 2);
+		};
+		for (const id of graph.keys()) visit(id);
+
+		target.depends = [...depends];
+		if (target.status === "pending" || target.status === "blocked") {
+			target.status = depends.every(
+				(dependency) => tasks.find((candidate) => candidate.id === dependency)?.status === "done",
+			) ? "pending" : "blocked";
+		}
+		store.saveTask(this.squadId, target);
+		store.appendMessage(this.squadId, taskId, {
+			ts: store.now(),
+			from: "system",
+			type: "status",
+			text: `Dependencies updated: ${depends.length > 0 ? depends.join(", ") : "none"}`,
+		});
+
+		this.killBlockedAgents();
+		const squad = store.loadSquad(this.squadId);
+		const runnable = target.status === "pending" && target.depends.every(
+			(dependency) => tasks.find((candidate) => candidate.id === dependency)?.status === "done",
+		);
+		const createdRunnableWork = runnable && !wasRunnable;
+		if (createdRunnableWork && squad && squad.status !== "paused" && squad.status !== "running") {
+			this.reopenSquadForWork();
+			await this.start();
+		} else if (squad?.status === "running") {
+			await this.start();
+		}
+		this.updateContext();
+	}
+
 	/** 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(
@@ -1422,6 +1592,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;
 	}
 
 	/**
@@ -1434,6 +1616,7 @@ export class Scheduler {
 		const task = store.loadTask(this.squadId, taskId);
 		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.`);
 
 		if (this.pool.isRunning(taskId)) {
 			await this.pool.kill(taskId);
@@ -1467,14 +1650,46 @@ export class Scheduler {
 		this.updateContext();
 	}
 
-	/** Cancel a task */
+	/** Cancel one task after ensuring no live historical task still depends on it. */
 	async cancelTask(taskId: string): Promise<void> {
-		if (this.pool.isRunning(taskId)) {
-			await this.pool.kill(taskId);
+		const task = store.loadTask(this.squadId, taskId);
+		if (!task) throw new Error(`Task not found: ${taskId}`);
+		if (task.status === "cancelled") return;
+
+		const dependents = store.loadAllTasks(this.squadId)
+			.filter((candidate) => candidate.status !== "cancelled" && candidate.depends.includes(taskId))
+			.sort((left, right) => left.id.localeCompare(right.id));
+		if (dependents.length > 0) {
+			throw new Error([
+				`Cannot cancel task '${taskId}': it is still required by:`,
+				...dependents.map((dependent) => `- ${dependent.id} [${dependent.status}]`),
+				"",
+				'Update each dependent first with squad_modify action "set_dependencies",',
+				"then retry cancel_task. Cancellation does not rewrite or cascade dependencies.",
+			].join("\n"));
 		}
-		store.updateTaskStatus(this.squadId, taskId, "failed", {
-			error: "Cancelled by user",
+
+		if (this.pool.isRunning(taskId)) await this.pool.kill(taskId);
+		store.updateTaskStatus(this.squadId, taskId, "cancelled", {
+			error: null,
+			completed: store.now(),
 		});
+		store.appendMessage(this.squadId, taskId, {
+			ts: store.now(),
+			from: "system",
+			type: "status",
+			text: "Task cancelled by orchestrator",
+		});
+
+		const squad = store.loadSquad(this.squadId);
+		if (squad) {
+			if (squad.status === "done" || (squad.status === "review" && squad.review?.status !== "pending")) {
+				beginOrchestratorRework(squad);
+				store.saveSquad(squad);
+			}
+			this.reconcileSuspendedStallAttention();
+			this.checkSquadCompletion(store.loadAllTasks(this.squadId), squad);
+		}
 		this.updateContext();
 	}
 
@@ -1482,6 +1697,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`
@@ -142,21 +143,26 @@ Send small, scoped corrections instead of restarting the task:
 - Name exactly what to change and what to keep: "Change only the header component — keep the layout and routes as they are."
 - Add missing information the moment you learn it — don't wait for the agent to get stuck
 - If the user manually edited or reverted files the agent touched, tell the agent immediately so it doesn't overwrite the human's changes
-- If an agent starts doing work that's no longer needed, narrow its scope via `squad_message` or stop it with `squad_modify` `cancel_task` — don't let it burn tokens on obsolete work
+- If an agent starts doing work that's no longer needed, narrow its scope via `squad_message`. Before using `squad_modify` `cancel_task`, repair every direct dependent explicitly as described below.
 
 ## Modifying a Running Squad
 
 Use `squad_modify` when:
 - **`add_task`**: User requests something not in the original plan
-- **`cancel_task`**: A task is no longer needed
-- **`pause_task`** / **`resume_task`**: Temporarily halt an agent
+- **`set_dependencies`**: Replace a task's dependency list with top-level `taskId` and `depends`, e.g. `{ action: "set_dependencies", taskId: "publish", depends: ["build"] }`. This is allowed only for tasks that are not running or done; the complete replacement is validated atomically for unknown IDs, self-dependencies, duplicates, and cycles.
+- **`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.