pi-squad 0.16.6 → 0.16.7

package/README.md

@@ -56,6 +56,7 @@ Squad agents—including QA/reviewer agents—produce candidate work and evidenc
 - Failed review is reworked in the **same authoritative squad**: use `squad_modify` with that `squadId` and `add_task` or `resume_task` (or `resume` when interrupted work exists). These operations reconstruct the scheduler after restart. `/squad resume <squad-id>` provides the same resume path.
 - When rework begins, the failed attempt moves to `reviewHistory`, the squad returns to `running`, and its evidence remains auditable. After every rework task settles, a fresh pending review becomes the active gate and `squad_review` is required again.
 - Pending and failed review gates survive Pi restarts and are restored on the next session. A separate squad never links to, remediates, or accepts the failed gate.
+- Every UI/status surface keeps execution progress adjacent to an explicit acceptance state: `◆ REVIEW PENDING · independent review required` means no verdict exists yet; `✗ REVIEW FAILED · awaiting same-squad rework` means the candidate was rejected. A truthful `3/3` task count never means a failed candidate was accepted.
 
 The completion report is explicitly labeled **untrusted and not yet accepted**. Main Pi must never merely relay it or ask whether verification should be run.
 
@@ -77,6 +78,18 @@ architect → frontend ─┘
 
 Architect runs first. Backend and frontend run in parallel after architect completes. QA waits for both.
 
+### Suspended Work Requires Explicit Action
+
+Suspension is an explicit pause, not a retry signal. If every remaining non-cancelled task is suspended or transitively blocked by suspended work, pi-squad durably wakes the main orchestrator once for that exact stall state. The widget shows `⚠ SUSPENDED — explicit resume required`; `squad_status` and the detail panel list every exact suspended task ID and blocked descendant.
+
+Nothing resumes automatically. Choose each task intentionally with an exact squad and task ID:
+
+```javascript
+squad_modify({ action: "resume_task", squadId: "<exact-squad-id>", taskId: "<exact-task-id>" })
+```
+
+Repeated reconciliation and restart do not create notification storms. A delivered stall remains visible until explicit resumption changes the state; a different suspended/blocked set is a new actionable episode.
+
 ### QA Rework Loop
 
 When a QA agent outputs `## Verdict: FAIL`, the scheduler automatically:
@@ -156,9 +169,13 @@ When the main agent provides tasks directly (via the `tasks` parameter), unknown
 
 ### Widget (above editor)
 
-Shows live squad progress. Truncated to terminal width — no wrapping, deterministic height.
+Shows live execution progress plus a distinct acceptance/attention state. Truncation is viewport-only: no wrapping, deterministic height, with complete IDs and evidence retained for detail/status output.
 
 ```
+◆ squad Build task API 3/3 · ◆ REVIEW PENDING · independent review required
+✗ squad Build task API 3/3 · ✗ REVIEW FAILED · awaiting same-squad rework
+⚠ SUSPENDED — explicit resume required · ^q detail
+
 ⏳ squad Build task API 2/3 $0.58 3m12s  ^q detail · /squad msg
   ✓ api (backend) 2m12s Created CRUD REST API with validation
   ⏳ tests (qa) 45s → bash npm test
@@ -197,7 +214,7 @@ Full overlay with task list, live activity preview, and scrollable message view.
 | `/squad msg [task-id\|running-agent] text` | Message an exact task, or use an agent name only when it has one live task |
 | `/squad widget` | Toggle widget |
 | `/squad panel` | Toggle panel |
-| `/squad cancel` | Cancel running squad |
+| `/squad cancel` | Cancel the visibly focused squad; the notification names it and the focused widget/status clear |
 | `/squad clear` | Dismiss widget |
 | `/squad cleanup` | Delete squad data |
 | `/squad enable/disable` | Enable/disable the extension |
@@ -209,7 +226,9 @@ Full overlay with task list, live activity preview, and scrollable message view.
 | `squad` | Start a squad with goal + optional tasks/config |
 | `squad_status` | Check progress, costs, task states |
 | `squad_message` | Durably message an exact task; completed tasks reopen on their original session |
-| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads, or replace a task's dependencies with `set_dependencies`; accepts `squadId` for exact same-squad failed-review rework |
+| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads, or replace a task's dependencies with `set_dependencies`; exact `squadId` is required for destructive whole-squad `cancel` and recommended for all task actions |
+
+Tool-level whole-squad cancellation never infers a target: `squad_modify({ action: "cancel", squadId: "<exact-squad-id>" })` affects only that persisted squad and names it in the result. Omitting `squadId` is rejected without changing any squad. Interactive `/squad cancel` instead uses the squad visibly focused in the current UI and names the affected squad.
 
 Dependency repair uses top-level `taskId` and `depends`, for example `squad_modify({ action: "set_dependencies", taskId: "publish", depends: ["build"] })`. The replacement is validated atomically (known IDs, no self-reference, duplicates, or cycles) and is allowed only while the task is not running or done.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.16.6",
+  "version": "0.16.7",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {

package/src/index.ts

@@ -14,9 +14,9 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Squad, Task, SquadConfig, PlannerOutput } from "./types.js";
+import type { Squad, Task, SquadConfig, PlannerOutput, SuspendedStallAttention } from "./types.js";
 import { DEFAULT_SQUAD_CONFIG, THINKING_LEVELS } from "./types.js";
-import { Scheduler, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
+import { Scheduler, formatSuspendedStallAttention, type SchedulerEvent, type SchedulerSpawnContext } from "./scheduler.js";
 import { runPlanner } from "./planner.js";
 import { validatePlan, PLAN_STRUCTURE_RULES } from "./plan-rules.js";
 import { ADVISOR_SYSTEM_PROMPT, buildAdvisorConsultText, type AdvisorConsultInput } from "./advisor.js";
@@ -27,6 +27,7 @@ import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildCompletionSummary, buildFailureSummary } from "./report.js";
 import { buildOrchestratorReviewGate, recordOrchestratorReview } from "./review.js";
+import { formatSuspendedAttention, getReviewPresentation } from "./presentation.js";
 
 // ============================================================================
 // State
@@ -186,6 +187,21 @@ function getActiveScheduler(): Scheduler | null {
 	return schedulers.get(activeSquadId) || null;
 }
 
+/** Restore the single focus/widget invariant after destructive exact cancellation. */
+function repairFocusAfterCancellation(cancelledId: string): void {
+	if (activeSquadId === cancelledId || (activeSquadId !== null && !store.loadSquad(activeSquadId))) {
+		activeSquadId = null;
+	}
+	widgetState.squadId = activeSquadId;
+	widgetControls?.requestUpdate();
+}
+
+function activeSuspendedAttentionForProject(cwd: string): Array<{ squadId: string; attention: SuspendedStallAttention }> {
+	return store.listSquadsForProject(cwd)
+		.filter((squad) => Boolean(squad.suspendedStallAttention))
+		.map((squad) => ({ squadId: squad.id, attention: squad.suspendedStallAttention! }));
+}
+
 /** Reconstruct and focus one exact persisted squad without creating/linking another. */
 function ensureScheduler(pi: ExtensionAPI, squadId: string, skillPaths: string[]): Scheduler {
 	let scheduler = schedulers.get(squadId);
@@ -244,6 +260,24 @@ export default function (pi: ExtensionAPI) {
 	const skillsDir = path.join(path.dirname(new URL(import.meta.url).pathname), "skills");
 	const squadSkillPaths = getSquadSkillPaths(skillsDir);
 
+	/** Cancel one persisted exact squad without ever inferring or changing focus. */
+	const cancelExactSquad = async (squadId: string): Promise<boolean> => {
+		const squad = store.loadSquad(squadId);
+		if (!squad) return false;
+		const live = schedulers.get(squadId);
+		if (live) await live.stop();
+		else await new Scheduler(squadId, squadSkillPaths, schedulerSpawnContext).stop();
+		const fresh = store.loadSquad(squadId);
+		if (fresh) {
+			fresh.status = "failed";
+			delete fresh.suspendedStallAttention;
+			store.saveSquad(fresh);
+		}
+		schedulers.delete(squadId);
+		repairFocusAfterCancellation(squadId);
+		return true;
+	};
+
 	// =========================================================================
 	// Context Injection — give main agent awareness of squad state
 	// =========================================================================
@@ -255,9 +289,12 @@ export default function (pi: ExtensionAPI) {
 		const pendingReviewGates = store.findActiveSquads()
 			.filter((s) => s.cwd === ctx.cwd && s.status === "review")
 			.map((s) => ({ squad: s, gate: buildOrchestratorReviewGate(s, store.loadAllTasks(s.id)) }));
+		const suspendedAttention = activeSuspendedAttentionForProject(ctx.cwd)
+			.map(({ squadId, attention }) => formatSuspendedStallAttention(squadId, attention));
+		const durablePrompts = [...pendingReviewGates.map(({ gate }) => gate), ...suspendedAttention];
 		if (!squadEnabled) {
-			if (pendingReviewGates.length === 0) return;
-			return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+			if (durablePrompts.length === 0) return;
+			return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 		}
 
 		// When a squad is active, inject its status
@@ -265,15 +302,16 @@ export default function (pi: ExtensionAPI) {
 			const squad = store.loadSquad(activeSquadId);
 			if (!squad) {
 				activeSquadId = null;
-				if (pendingReviewGates.length > 0) {
-					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				widgetState.squadId = null;
+				if (durablePrompts.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
 				return;
 			}
 			const tasks = store.loadAllTasks(activeSquadId);
 			if (tasks.length === 0) {
-				if (pendingReviewGates.length > 0) {
-					return { systemPrompt: event.systemPrompt + "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") };
+				if (durablePrompts.length > 0) {
+					return { systemPrompt: event.systemPrompt + "\n\n" + durablePrompts.join("\n\n") };
 				}
 				return;
 			}
@@ -281,21 +319,24 @@ export default function (pi: ExtensionAPI) {
 			const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 
 			const taskLines = tasks.map((t) => {
-				const icon = t.status === "done" ? "✓" : t.status === "in_progress" ? "⏳" : t.status === "failed" ? "✗" : t.status === "blocked" ? "◻" : t.status === "cancelled" ? "⊘" : "·";
+				const icon = t.status === "done" ? "✓" : t.status === "in_progress" ? "⏳" : t.status === "failed" ? "✗" : t.status === "blocked" ? "◻" : t.status === "suspended" ? "⏸" : t.status === "cancelled" ? "⊘" : "·";
 				let line = `  ${icon} ${t.id} (${t.agent}) [${t.status}]`;
 				if (t.output) line += ` — ${t.output}`;
 				if (t.error) line += ` ERROR: ${t.error}`;
 				return line;
 			}).join("\n");
 
+			const reviewPresentation = getReviewPresentation(squad);
 			const squadContext = [
 				`<squad_status>`,
 				`Squad: ${squad.id} — ${squad.goal}`,
 				`Status: ${squad.status} | ${formatTaskProgress(tasks)} | $${totalCost.toFixed(2)}`,
+				...(reviewPresentation ? [`Acceptance: ${reviewPresentation.label}`] : []),
 				taskLines,
 				`</squad_status>`,
 				...(squad.status === "review" ? [buildOrchestratorReviewGate(squad, tasks)] : []),
 				...pendingReviewGates.filter(({ squad: pending }) => pending.id !== squad.id).map(({ gate }) => gate),
+				...suspendedAttention,
 				`You have an active squad. Use squad_message to talk to agents, squad_status for details, squad_modify to change tasks.`,
 				`Do NOT poll squad_status in a loop or sleep-wait — the squad wakes you automatically on completion, failure, or escalation. Keep helping the user with other work, or end your turn and stay idle.`,
 			].join("\n");
@@ -323,7 +364,7 @@ export default function (pi: ExtensionAPI) {
 
 		return {
 			systemPrompt: event.systemPrompt + "\n\n" + squadNudge +
-				(pendingReviewGates.length > 0 ? "\n\n" + pendingReviewGates.map(({ gate }) => gate).join("\n\n") : ""),
+				(durablePrompts.length > 0 ? "\n\n" + durablePrompts.join("\n\n") : ""),
 		};
 	});
 
@@ -452,6 +493,7 @@ export default function (pi: ExtensionAPI) {
 						task.status === "in_progress" ? "⏳" :
 						task.status === "blocked" ? "◻" :
 						task.status === "failed" ? "✗" :
+						task.status === "suspended" ? "⏸" :
 						task.status === "cancelled" ? "⊘" :
 						"·";
 					let line = `${icon} ${taskId} (${task.agent}) — ${task.title} [${task.status}]`;
@@ -461,13 +503,16 @@ export default function (pi: ExtensionAPI) {
 				.join("\n");
 
 			const durableTasks = store.loadAllTasks(id!);
+			const squad = store.loadSquad(id!);
+			const review = squad ? getReviewPresentation(squad) : null;
 			const summary = [
 				`Squad: ${id}`,
 				`Status: ${context.status}`,
 				`Progress: ${formatTaskProgress(durableTasks)}`,
 				`Elapsed: ${context.elapsed}`,
 				`Cost: $${context.costs.total.toFixed(4)}`,
-				...(context.status === "review" ? ["Acceptance: BLOCKED — independent main-orchestrator review required via squad_review"] : []),
+				...(review ? [`Acceptance: ${review.label}`] : []),
+				...(squad ? formatSuspendedAttention(squad) : []),
 				"",
 				"Tasks:",
 				taskLines,
@@ -604,9 +649,9 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_modify",
 		label: "Squad Modify",
-		description: "Modify one exact squad: add_task, set_dependencies (top-level depends), cancel_task, complete_task (mark done + schedule dependents), pause, resume_task, resume (including failed-review rework), cancel. Task actions reconstruct the persisted scheduler after restart when needed.",
+		description: "Modify a squad. The destructive cancel action requires an exact squadId and never infers focus; task actions reconstruct the persisted scheduler after restart when needed.",
 		parameters: Type.Object({
-			squadId: Type.Optional(Type.String({ description: "Exact squad to modify (recommended for failed-review rework; default: focused/recoverable project squad)" })),
+			squadId: Type.Optional(Type.String({ description: "Exact squad to modify; required for cancel (other actions may use the focused/recoverable project squad)" })),
 			action: Type.Union(
 				[
 					Type.Literal("add_task"),
@@ -637,6 +682,22 @@ export default function (pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (params.action === "cancel") {
+				if (!params.squadId?.trim()) {
+					return { content: [{ type: "text" as const, text: "cancel requires exact squadId; no squad was changed." }], details: undefined };
+				}
+				const squadId = params.squadId.trim();
+				if (!store.loadSquad(squadId)) {
+					return { content: [{ type: "text" as const, text: `Squad '${squadId}' not found; no squad was changed.` }], details: undefined };
+				}
+				try {
+					await cancelExactSquad(squadId);
+				} catch (error) {
+					return { content: [{ type: "text" as const, text: `Cancel failed for squad '${squadId}': ${(error as Error).message}` }], details: undefined };
+				}
+				return { content: [{ type: "text" as const, text: `Squad '${squadId}' cancelled.` }], details: undefined };
+			}
+
 			if (params.action === "resume") {
 				const squad = resolveResumeSquad(ctx.cwd, params.squadId);
 				if (!squad) {
@@ -742,9 +803,12 @@ export default function (pi: ExtensionAPI) {
 				case "resume_task": {
 					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
 					try {
-						await activeScheduler.resumeTask(params.taskId);
+						const result = await activeScheduler.resumeTask(params.taskId);
+						if (result === "already_running") {
+							return { content: [{ type: "text" as const, text: `Task '${params.taskId}' is already running in squad '${squadId}'; no duplicate resume was started.` }], details: undefined };
+						}
 					} catch (err) {
-						return { content: [{ type: "text" as const, text: `resume_task failed: ${(err as Error).message}` }], details: undefined };
+						return { content: [{ type: "text" as const, text: `resume_task failed for task '${params.taskId}' in squad '${squadId}': ${(err as Error).message}` }], details: undefined };
 					}
 					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed in squad '${squadId}'.` }], details: undefined };
 				}
@@ -769,19 +833,7 @@ export default function (pi: ExtensionAPI) {
 					return { content: [{ type: "text" as const, text: "Squad paused. Use squad_modify with action 'resume' to continue." }], details: undefined };
 				}
 
-				// Note: "resume" is handled above, before the activeScheduler guard.
-
-				case "cancel": {
-					await activeScheduler.stop();
-					const squad = store.loadSquad(activeSquadId);
-					if (squad) {
-						squad.status = "failed";
-						store.saveSquad(squad);
-					}
-					schedulers.delete(activeSquadId);
-					activeSquadId = null;
-					return { content: [{ type: "text" as const, text: "Squad cancelled." }], details: undefined };
-				}
+				// Note: "resume" and exact-ID "cancel" are handled above.
 
 				default:
 					return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }], details: undefined };
@@ -822,6 +874,21 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// Reconstruct schedulers for explicit-suspension stalls without resuming any
+		// task. Reconcile derives/persists a missing outbox record and emits only a
+		// pending fingerprint; delivered attention remains durable and silent.
+		const suspensionCandidates = store.listSquadsForProject(ctx.cwd)
+			.filter((squad) => Boolean(squad.suspendedStallAttention) || store.loadAllTasks(squad.id).some((task) => task.status === "suspended"));
+		for (const squad of suspensionCandidates) {
+			let scheduler = schedulers.get(squad.id);
+			if (!scheduler) {
+				scheduler = new Scheduler(squad.id, squadSkillPaths, schedulerSpawnContext);
+				schedulers.set(squad.id, scheduler);
+				wireSchedulerEvents(pi, scheduler, squad.id);
+			}
+			await scheduler.start();
+		}
+
 		// Mailbox recovery is automatic after extension/main-process restart. Scan
 		// every project squad (including accepted done squads) because a crash can
 		// occur after the mailbox-first write but before the squad/task is reopened.
@@ -1130,17 +1197,13 @@ export default function (pi: ExtensionAPI) {
 				}
 
 				case "cancel": {
-					const cancelSched = getActiveScheduler();
-					if (!cancelSched) {
-						ctx.ui.notify("No running squad to cancel", "info");
+					const cancelledId = activeSquadId;
+					if (!cancelledId) {
+						ctx.ui.notify("No focused squad to cancel", "info");
 						return;
 					}
-					await cancelSched.stop();
-					const squad = store.loadSquad(activeSquadId!);
-					if (squad) { squad.status = "failed"; store.saveSquad(squad); }
-					if (activeSquadId) schedulers.delete(activeSquadId);
-					forceWidgetUpdate();
-					ctx.ui.notify("Squad cancelled", "info");
+					await cancelExactSquad(cancelledId);
+					ctx.ui.notify(`Squad '${cancelledId}' cancelled`, "info");
 					return;
 				}
 
@@ -1501,9 +1564,11 @@ async function pickSquad(
 	const options = squads.map((s) => {
 		const tasks = store.loadAllTasks(s.id);
 		const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
-		const icon = s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "review" ? "◆" : s.status === "failed" ? "✗" : "·";
+		const review = getReviewPresentation(s);
+		const icon = review?.icon ?? (s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·");
+		const acceptance = review ? ` ${review.label}` : ` [${s.status}]`;
 		const project = showProject ? ` — ${s.cwd.split("/").pop()}` : "";
-		return `${icon} ${s.id} [${s.status}] ${formatTaskProgress(tasks)} $${cost.toFixed(2)}${project}`;
+		return `${icon} ${s.id}${acceptance} · ${formatTaskProgress(tasks)} $${cost.toFixed(2)}${project}`;
 	});
 
 	const choice = await ctx.ui.select("Select a squad", options);
@@ -1573,6 +1638,20 @@ function wireSchedulerEvents(pi: ExtensionAPI, scheduler: Scheduler, squadId: st
 				// can reopen the task immediately on its bound durable Pi session.
 				break;
 			}
+			case "suspended_stall": {
+				try {
+					const attention = event.data as SuspendedStallAttention;
+					pi.sendMessage({
+						customType: `squad-suspended-stall:${squadId}:${attention.fingerprint}`,
+						content: formatSuspendedStallAttention(squadId, attention),
+						display: true,
+					}, { triggerTurn: true, deliverAs: "followUp" });
+					scheduler.acknowledgeSuspendedStall(attention.fingerprint);
+				} catch (error) {
+					logError("squad-scheduler", `suspended-stall delivery failed for ${squadId}: ${(error as Error).message}`);
+				}
+				break;
+			}
 			case "squad_failed": {
 				const tasks = store.loadAllTasks(squadId);
 				const failed = tasks.filter((task) => task.status === "failed");

package/src/panel/squad-widget.ts

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

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/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,7 +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") 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 +367,7 @@ export class Scheduler {
 		}
 
 		await this.scheduleReadyTasks();
+		this.reconcileSuspendedStallAttention();
 
 		const freshSquad = store.loadSquad(this.squadId);
 		if (freshSquad && (freshSquad.status === "running" || freshSquad.status === "failed")) {
@@ -664,7 +723,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 +854,8 @@ export class Scheduler {
 			}
 
 			case "agent_settled": {
-				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;
 				// 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,8 +907,9 @@ 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);
@@ -905,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);
@@ -938,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);
@@ -1409,6 +1479,7 @@ export class Scheduler {
 			setTimeout(() => this.pool.kill(taskId), 3000);
 		}
 		store.updateTaskStatus(this.squadId, taskId, "suspended");
+		this.reconcileSuspendedStallAttention();
 		this.updateContext();
 	}
 
@@ -1503,9 +1574,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 +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;
 	}
 
 	/**
@@ -1601,6 +1687,7 @@ export class Scheduler {
 				beginOrchestratorRework(squad);
 				store.saveSquad(squad);
 			}
+			this.reconcileSuspendedStallAttention();
 			this.checkSquadCompletion(store.loadAllTasks(this.squadId), squad);
 		}
 		this.updateContext();
@@ -1610,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`
@@ -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/types.ts

@@ -85,6 +85,17 @@ export interface SquadReview {
 	issues: string[];
 }
 
+export interface SuspendedStallAttention {
+	kind: "suspended_stall";
+	/** Canonical identity of the exact suspended/blocked task sets. */
+	fingerprint: string;
+	suspendedTaskIds: string[];
+	blockedTaskIds: string[];
+	detectedAt: string;
+	delivery: "pending" | "delivered";
+	deliveredAt: string | null;
+}
+
 export interface SquadConfig {
 	maxConcurrency: number;
 	autoUnblock: boolean;
@@ -116,6 +127,8 @@ export interface Squad {
 	review?: SquadReview;
 	/** Completed prior review attempts retained as same-squad audit evidence. */
 	reviewHistory?: SquadReview[];
+	/** Durable, level-triggered attention for an explicit-suspension stall. */
+	suspendedStallAttention?: SuspendedStallAttention;
 }
 
 // ============================================================================