pi-squad 0.14.0 → 0.15.0

package/README.md

@@ -183,7 +183,7 @@ 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` | Send message to a running agent |
-| `squad_modify` | Add/cancel/pause/resume tasks or squads |
+| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads |
 
 The main agent sees available agents in its system prompt and squad state when a squad is active.
 
@@ -280,18 +280,21 @@ Agents must complete at least 1 LLM turn AND make at least 1 tool call to be mar
 ### Session Resilience
 
 - In-progress tasks are **suspended** on session crash, **resumed** on next startup
+- Failure is never terminal: `resume` recovers failed squads (failed tasks reset to pending), `complete_task` marks recovered work done and schedules dependents, and a 60s reconcile loop re-derives scheduling from persisted state so out-of-band store edits can't strand ready tasks
 - Squads are fully reconstructable from JSON files on disk
 - Spawn failures are retried once with a 2-second delay
 - All errors logged to `~/.pi/squad/debug.log` (always for errors, `PI_SQUAD_DEBUG=1` for verbose)
 
 ### Health Monitoring
 
+The monitor never kills or blocks work on its own — its strongest action is notifying the main Pi session so you (or the main agent) can decide.
+
 | Check | Threshold | Action |
 |---|---|---|
 | Idle warning | 3 minutes no output | Steer agent with nudge |
-| Stuck detection | 5 minutes no output | Abort and fail task |
+| Stuck detection | 5 minutes no output | Steer, then escalate to main session |
 | Loop detection | Same tool call 5x | Steer with warning |
-| Hard ceiling | 30 minutes total | Abort task |
+| Long-running check-in | Every 30 minutes total (`PI_SQUAD_CEILING_MS`) | Notify main session — work continues |
 
 ## Data Layout
 
@@ -320,7 +323,7 @@ src/
 ├── agent-pool.ts     — pi RPC process management, activity tracking
 ├── protocol.ts       — system prompt builder (chain context, sibling awareness, knowledge)
 ├── router.ts         — @mention parsing, cross-agent messaging
-├── monitor.ts        — health checks (idle, stuck, loop, ceiling)
+├── monitor.ts        — health checks (idle, stuck, loop, long-run notify)
 ├── planner.ts        — one-shot goal decomposition via LLM
 ├── logger.ts         — file-based logging (never writes to stderr)
 ├── panel/            — TUI overlay panel and widget

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {
@@ -48,5 +48,8 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1"
   }
 }

package/src/index.ts

@@ -461,7 +461,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_modify",
 		label: "Squad Modify",
-		description: "Modify the running squad: add_task, cancel_task, pause, resume, cancel (entire squad).",
+		description: "Modify the running squad: add_task, cancel_task, complete_task (mark done + schedule dependents), pause, resume (also recovers failed squads), cancel (entire squad).",
 		parameters: Type.Object({
 			action: Type.Union(
 				[
@@ -469,6 +469,7 @@ export default function (pi: ExtensionAPI) {
 					Type.Literal("cancel_task"),
 					Type.Literal("pause_task"),
 					Type.Literal("resume_task"),
+					Type.Literal("complete_task"),
 					Type.Literal("pause"),
 					Type.Literal("resume"),
 					Type.Literal("cancel"),
@@ -476,6 +477,7 @@ export default function (pi: ExtensionAPI) {
 				{ description: "Action to perform" },
 			),
 			taskId: Type.Optional(Type.String({ description: "Task ID for task-specific actions" })),
+			output: Type.Optional(Type.String({ description: "Result summary for complete_task (what was accomplished)" })),
 			task: Type.Optional(
 				Type.Object({
 					id: Type.String(),
@@ -493,11 +495,11 @@ export default function (pi: ExtensionAPI) {
 			if (params.action === "resume") {
 				// Find a squad to resume: use activeSquadId or find the latest paused one
 				const squadId = activeSquadId || store.findActiveSquads()
-					.filter((s) => s.cwd === ctx.cwd && s.status === "paused")
+					.filter((s) => s.cwd === ctx.cwd && (s.status === "paused" || s.status === "failed"))
 					.sort((a, b) => b.created.localeCompare(a.created))[0]?.id;
 
 				if (!squadId) {
-					return { content: [{ type: "text" as const, text: "No paused squad found to resume." }], details: undefined };
+					return { content: [{ type: "text" as const, text: "No paused or failed squad found to resume." }], details: undefined };
 				}
 
 				// Create a fresh scheduler if needed
@@ -632,6 +634,16 @@ export default function (pi: ExtensionAPI) {
 					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed.` }], details: undefined };
 				}
 
+				case "complete_task": {
+					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }], details: undefined };
+					try {
+						await activeScheduler.completeTask(params.taskId, params.output);
+					} catch (err) {
+						return { content: [{ type: "text" as const, text: `complete_task failed: ${(err as Error).message}` }], details: undefined };
+					}
+					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' marked done — dependents unblocked and scheduled.` }], details: undefined };
+				}
+
 				case "pause": {
 					const squad = store.loadSquad(activeSquadId);
 					if (squad) {

package/src/monitor.ts

@@ -5,8 +5,11 @@
  * - Idle timeout (no output for N minutes)
  * - Stuck detection (no output for longer)
  * - Loop detection (same tool call repeated)
- * - Hard ceiling (max total runtime)
+ * - Long-running check-in (notify the main session; never aborts)
  * - File conflict warnings
+ *
+ * The monitor NEVER kills or blocks work on its own. Its strongest action is
+ * `notify`: tell the main Pi session so a human/main agent can check in.
  */
 
 import type { AgentPool } from "./agent-pool.js";
@@ -25,7 +28,7 @@ function envMs(name: string, fallback: number): number {
 
 const IDLE_WARNING_MS = envMs("PI_SQUAD_IDLE_MS", 3 * 60 * 1000); // no output → warn
 const STUCK_TIMEOUT_MS = envMs("PI_SQUAD_STUCK_MS", 5 * 60 * 1000); // no output → intervene
-const HARD_CEILING_MS = envMs("PI_SQUAD_CEILING_MS", 30 * 60 * 1000); // total → force stop
+const LONG_RUN_NOTIFY_MS = envMs("PI_SQUAD_CEILING_MS", 30 * 60 * 1000); // total → notify main session (no abort)
 const LOOP_THRESHOLD = 5; // same tool call 5x → looping
 const POLL_INTERVAL_MS = envMs("PI_SQUAD_POLL_MS", 30 * 1000); // check interval
 
@@ -33,7 +36,7 @@ const POLL_INTERVAL_MS = envMs("PI_SQUAD_POLL_MS", 30 * 1000); // check interval
 // Types
 // ============================================================================
 
-export type MonitorActionType = "steer" | "abort" | "escalate";
+export type MonitorActionType = "steer" | "escalate" | "notify";
 
 export interface MonitorAction {
 	type: MonitorActionType;
@@ -60,6 +63,8 @@ export class Monitor {
 	private stuckSteered = new Set<string>();
 	/** Track which tasks have been escalated (one escalation per stuck episode) */
 	private escalated = new Set<string>();
+	/** Last long-run threshold multiple notified per task (notify once per multiple) */
+	private longRunNotified = new Map<string, number>();
 
 	constructor(pool: AgentPool, squadId: string) {
 		this.pool = pool;
@@ -100,6 +105,7 @@ export class Monitor {
 		this.warned.clear();
 		this.stuckSteered.clear();
 		this.escalated.clear();
+		this.longRunNotified.clear();
 	}
 
 	/** Check all running agents */
@@ -112,7 +118,7 @@ export class Monitor {
 			if (!activity) continue;
 
 			const health = this.checkHealth(activity);
-			this.handleHealth(taskId, agentName, health);
+			this.handleHealth(taskId, agentName, health, activity);
 		}
 	}
 
@@ -133,7 +139,7 @@ export class Monitor {
 			if (unique.size === 1) return "looping";
 		}
 
-		if (totalMs >= HARD_CEILING_MS) return "exceeded_ceiling";
+		if (totalMs >= LONG_RUN_NOTIFY_MS) return "long_running";
 		if (idleMs >= STUCK_TIMEOUT_MS) return "stuck";
 		if (idleMs >= IDLE_WARNING_MS) return "idle_warning";
 
@@ -141,7 +147,12 @@ export class Monitor {
 	}
 
 	/** Take action based on health status */
-	private handleHealth(taskId: string, agentName: string, status: HealthStatus): void {
+	private handleHealth(
+		taskId: string,
+		agentName: string,
+		status: HealthStatus,
+		activity?: { startedAt: number },
+	): void {
 		if (status !== "healthy") debug("squad-monitor", `${taskId} (${agentName}): ${status}`);
 		switch (status) {
 			case "healthy":
@@ -203,15 +214,25 @@ export class Monitor {
 				});
 				break;
 
-			case "exceeded_ceiling":
-				this.emit({
-					type: "abort",
-					taskId,
-					agentName,
-					reason: `Agent ${agentName} exceeded time ceiling on ${taskId}`,
-					message: "",
-				});
+			case "long_running": {
+				// Never abort. Notify the main Pi session once per threshold multiple
+				// (30m, 60m, 90m, …) so it can check in if needed — work continues.
+				const totalMs = Date.now() - (activity?.startedAt ?? Date.now());
+				const multiple = Math.floor(totalMs / LONG_RUN_NOTIFY_MS);
+				const lastNotified = this.longRunNotified.get(taskId) ?? 0;
+				if (multiple > lastNotified) {
+					this.longRunNotified.set(taskId, multiple);
+					const minutes = Math.round(totalMs / 60_000);
+					this.emit({
+						type: "notify",
+						taskId,
+						agentName,
+						reason: `Agent ${agentName} has been working on ${taskId} for ${minutes}m. Still running — check on it if needed (steer, pause, or let it continue).`,
+						message: "",
+					});
+				}
 				break;
+			}
 		}
 	}
 }

package/src/scheduler.ts

@@ -72,6 +72,8 @@ export class Scheduler {
 	private running = false;
 	/** Track spawn retries to allow one retry per task */
 	private spawnRetries = new Set<string>();
+	/** Periodic level-triggered reconcile (heals missed events / out-of-band store edits) */
+	private reconcileTimer: ReturnType<typeof setInterval> | null = null;
 
 	/** Get the project cwd for this squad (from squad.json) */
 	getProjectCwd(): string | undefined {
@@ -93,8 +95,16 @@ export class Scheduler {
 		this.monitor.onAction((action) => {
 			if (action.type === "steer") {
 				this.pool.steer(action.taskId, action.message);
-			} else if (action.type === "abort") {
-				this.handleTaskFailed(action.taskId, action.reason);
+			} else if (action.type === "notify") {
+				// Informational only — tell the main Pi session directly (no advisor
+				// detour, no kill). The agent keeps working.
+				this.emit({
+					type: "escalation",
+					squadId: this.squadId,
+					taskId: action.taskId,
+					agentName: action.agentName,
+					message: action.reason,
+				});
 			} else if (action.type === "escalate") {
 				// Advisor-first: try a strong-model rescue before interrupting the human
 				void this.tryAdvisorRescue(action.taskId, action.agentName, action.reason).then((rescued) => {
@@ -160,13 +170,22 @@ export class Scheduler {
 	async start(): Promise<void> {
 		this.running = true;
 		this.monitor.start();
-		await this.scheduleReadyTasks();
+		await this.reconcile();
+		// Level-triggered safety net: periodically re-derive scheduling decisions
+		// from persisted state so missed in-memory events (crashes, out-of-band
+		// store edits, external recovery) cannot strand ready tasks.
+		this.reconcileTimer = setInterval(() => void this.reconcile(), 60_000);
+		(this.reconcileTimer as { unref?: () => void }).unref?.();
 	}
 
 	/** Stop the scheduler — kills all agents, saves state */
 	async stop(): Promise<void> {
 		this.running = false;
 		this.monitor.stop();
+		if (this.reconcileTimer) {
+			clearInterval(this.reconcileTimer);
+			this.reconcileTimer = null;
+		}
 
 		// Suspend in-progress tasks
 		const tasks = store.loadAllTasks(this.squadId);
@@ -179,17 +198,26 @@ export class Scheduler {
 		await this.pool.killAll();
 	}
 
-	/** Resume from suspended state */
+	/** Resume from suspended OR failed state. Failure is never terminal:
+	 * failed tasks are reset to pending and a failed squad becomes running. */
 	async resume(): Promise<void> {
 		const tasks = store.loadAllTasks(this.squadId);
 		for (const task of tasks) {
 			if (task.status === "suspended") {
 				store.updateTaskStatus(this.squadId, task.id, "pending");
+			} else if (task.status === "failed") {
+				store.updateTaskStatus(this.squadId, task.id, "pending", { error: null });
+				store.appendMessage(this.squadId, task.id, {
+					ts: store.now(),
+					from: "system",
+					type: "status",
+					text: "Reset failed → pending on squad resume",
+				});
 			}
 		}
 
 		const squad = store.loadSquad(this.squadId);
-		if (squad && squad.status === "paused") {
+		if (squad && (squad.status === "paused" || squad.status === "failed")) {
 			squad.status = "running";
 			store.saveSquad(squad);
 		}
@@ -197,6 +225,52 @@ export class Scheduler {
 		await this.start();
 	}
 
+	/**
+	 * Level-triggered reconciliation — derive scheduling from persisted state:
+	 * 1. Unblock blocked tasks whose deps are all done (missed autoUnblock events)
+	 * 2. Self-heal a "failed" squad when runnable work exists (out-of-band recovery)
+	 * 3. Schedule ready tasks
+	 * Safe to call any time; no-ops when nothing changed.
+	 */
+	async reconcile(): Promise<void> {
+		if (!this.running) return;
+		const squad = store.loadSquad(this.squadId);
+		if (!squad) return;
+
+		const tasks = store.loadAllTasks(this.squadId);
+
+		// 1. Blocked → pending when all deps are done (respects autoUnblock config)
+		if (squad.config.autoUnblock) {
+			for (const task of tasks) {
+				if (task.status !== "blocked") continue;
+				const allDepsDone = task.depends.every((depId) => {
+					const dep = tasks.find((t) => t.id === depId);
+					return dep?.status === "done";
+				});
+				if (allDepsDone) {
+					task.status = "pending";
+					store.updateTaskStatus(this.squadId, task.id, "pending");
+					this.emit({ type: "task_unblocked", squadId: this.squadId, taskId: task.id });
+				}
+			}
+		}
+
+		// 2. A "failed" squad with runnable work self-heals to running. This makes
+		// the terminal status derivable from task state instead of a one-way latch.
+		const hasRunnable = tasks.some((t) => {
+			if (t.status === "in_progress") return true;
+			if (t.status !== "pending") return false;
+			return t.depends.every((depId) => tasks.find((x) => x.id === depId)?.status === "done");
+		});
+		if (squad.status === "failed" && hasRunnable) {
+			squad.status = "running";
+			store.saveSquad(squad);
+			debug("squad-scheduler", "reconcile: failed squad has runnable work — healing to running");
+		}
+
+		await this.scheduleReadyTasks();
+	}
+
 	// =========================================================================
 	// Task Scheduling
 	// =========================================================================
@@ -1073,10 +1147,53 @@ export class Scheduler {
 		this.updateContext();
 	}
 
-	/** Resume a suspended task */
+	/** Resume a suspended/failed task. Reconciles so a failed squad heals too. */
 	async resumeTask(taskId: string): Promise<void> {
-		store.updateTaskStatus(this.squadId, taskId, "pending");
-		await this.scheduleReadyTasks();
+		store.updateTaskStatus(this.squadId, taskId, "pending", { error: null });
+		await this.reconcile();
+	}
+
+	/**
+	 * Mark a task done through the normal completion flow (admin/recovery path).
+	 * Unlike editing the store directly, this fires auto-unblock and scheduling,
+	 * so dependents transition pending → running. Skips the QA rework check —
+	 * a human/main agent marking a task done is an explicit override.
+	 */
+	async completeTask(taskId: string, output?: string): Promise<void> {
+		const task = store.loadTask(this.squadId, taskId);
+		if (!task) throw new Error(`Task not found: ${taskId}`);
+		if (task.status === "done") return;
+
+		if (this.pool.isRunning(taskId)) {
+			await this.pool.kill(taskId);
+		}
+
+		store.updateTaskStatus(this.squadId, taskId, "done", {
+			output: output ?? task.output ?? "Marked done (recovered/admin)",
+			error: null,
+			completed: store.now(),
+		});
+		store.appendMessage(this.squadId, taskId, {
+			ts: store.now(),
+			from: "system",
+			type: "done",
+			text: "Task marked done (recovered/admin)",
+		});
+		this.emit({
+			type: "task_completed",
+			squadId: this.squadId,
+			taskId,
+			agentName: task.agent,
+			message: output ?? "",
+		});
+
+		this.autoUnblock(taskId);
+		await this.reconcile();
+
+		const freshTasks = store.loadAllTasks(this.squadId);
+		const freshSquad = store.loadSquad(this.squadId);
+		if (freshSquad) this.checkSquadCompletion(freshTasks, freshSquad);
+		this.updateContext();
 	}
 
 	/** Cancel a task */

package/src/store.ts

@@ -269,9 +269,11 @@ export function listSquads(): string[] {
 }
 
 export function findActiveSquads(): Squad[] {
+	// Includes "failed": failure is recoverable (resume resets failed tasks), so
+	// failed squads must stay discoverable. All callers filter by status.
 	return listSquads()
 		.map((id) => loadSquad(id))
-		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused"));
+		.filter((s): s is Squad => s !== null && (s.status === "running" || s.status === "paused" || s.status === "failed"));
 }
 
 /** List squads filtered by project cwd. If no cwd, returns all. */

package/src/types.ts

@@ -223,7 +223,7 @@ export interface AgentActivity {
 	modifiedFiles: Set<string>;
 }
 
-export type HealthStatus = "healthy" | "idle_warning" | "stuck" | "looping" | "exceeded_ceiling";
+export type HealthStatus = "healthy" | "idle_warning" | "stuck" | "looping" | "long_running";
 
 // ============================================================================
 // Supervisor