pi-squad 0.19.5 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-07-26
+
+### Added
+
+- `squad_modify add_task` accepts `forkFromTask: "<task id>"`: the new task's session is forked from the source task's durable session, so follow-up and review-rework agents continue with the source's complete context instead of redoing everything. Validated at add time (source must exist and have run once; mutually exclusive with `inheritContext`) and guarded by the same 50%-of-context-window check as `inheritContext`.
+
+### Fixed
+
+- Provider/API outages no longer leave tasks permanently unretriable. Unexpected agent exits now retry on the same durable session with backoff (2s/10s/30s/60s/120s, `PI_SQUAD_SPAWN_RETRIES` overrides the count) instead of a single 2s retry whose in-memory flag was never cleared — previously one early blip consumed the only retry forever, and a resumed task could instantly re-fail terminally. Successful completion and explicit `resume`/`resume_task` grant a fresh budget, and the terminal failure message now teaches the exact recovery call.
+- A failed `squad_review` verdict now responds with explicit same-squad rework instructions (add `-fix` tasks, ideally `forkFromTask` the reviewed implementation) and forbids cancelling or abandoning the squad, closing the observed "review failed → squad stopped, no rework requested" drift.
+
 ## [0.19.5] - 2026-07-24
 
 ### Fixed

package/README.md

@@ -284,6 +284,10 @@ squad({
 - Once created, that task-to-session binding is immutable; later resumes pass the original file through `--session`
 - Prefer restating the 3-5 key decisions in the task description — reach for `inheritContext` only when that's impractical
 
+### Task-to-Task Context (`forkFromTask`)
+
+Follow-up and review-rework tasks can fork an **existing task's** durable session instead of starting fresh: `squad_modify { action: "add_task", task: { id: "impl-fix-1", agent: "backend", forkFromTask: "impl", ... } }`. The new agent continues with the source task's complete conversation context — nothing is re-explored or redone. The source must have run at least once (it needs a durable session); the same 50%-of-context-window guard as `inheritContext` applies, and `forkFromTask` is mutually exclusive with `inheritContext`. This is the recommended shape for rework after a failed independent review.
+
 ### Custom Agents
 
 Create `~/.pi/squad/agents/my-agent.json` (global) or `{project}/.pi/squad/agents/my-agent.json` (project override):
@@ -334,7 +338,7 @@ Configure with `/squad advisor` (on/off, model, max calls per task, reasoning ef
 
 ### Meaningful Work Check
 
-Agents must complete at least one LLM turn and produce either a tool call or a substantive assistant artifact before they can be marked `done`. This permits legitimate report-only planning/review work while rejecting empty exits. A child that exits before final `agent_settled`, or settles without meaningful work, is resumed once on the same task session and then failed if the retry is exhausted.
+Agents must complete at least one LLM turn and produce either a tool call or a substantive assistant artifact before they can be marked `done`. This permits legitimate report-only planning/review work while rejecting empty exits. A child that exits before final `agent_settled` (typically a provider/API outage) is resumed on the same task session with backoff — 2s, 10s, 30s, 60s, 120s (override the attempt count with `PI_SQUAD_SPAWN_RETRIES`) — and only fails after the budget is exhausted. Successful completion or an explicit `resume_task`/`resume` grants a fresh budget, so an outage-failed task is always retriggerable once the provider recovers: `squad_modify { action: "resume_task", taskId: "..." }` reopens the same durable session and no work is redone.
 
 ### Session Resilience
 

package/package.json

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

package/src/scheduler.ts

@@ -22,6 +22,15 @@ import { buildAgentSystemPrompt } from "./protocol.js";
 import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
 import { beginOrchestratorReview, beginOrchestratorRework } from "./review.js";
 
+/** Backoff schedule for unexpected agent exits (provider/API outages). The
+ * last delay repeats when PI_SQUAD_SPAWN_RETRIES exceeds the schedule. */
+const SPAWN_RETRY_BACKOFF_MS = [2_000, 10_000, 30_000, 60_000, 120_000];
+
+function maxSpawnRetries(): number {
+	const value = Number(process.env.PI_SQUAD_SPAWN_RETRIES);
+	return Number.isFinite(value) && value >= 0 ? Math.floor(value) : SPAWN_RETRY_BACKOFF_MS.length;
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -130,7 +139,9 @@ export class Scheduler {
 	private spawnContext?: SchedulerSpawnContext;
 	private running = false;
 	/** Track spawn retries to allow one retry per task */
-	private spawnRetries = new Set<string>();
+	/** Spawn retries per task. Success and explicit resume grant a fresh budget
+	 * so a provider/API outage never leaves a task permanently unretriable. */
+	private spawnRetryCounts = new Map<string, number>();
 	/** 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. */
@@ -289,6 +300,9 @@ export class Scheduler {
 	/** Resume suspended/failed work. A failed review is archived only when
 	 * resumable work actually exists; a bare resume cannot bypass the gate. */
 	async resume(): Promise<void> {
+		// Every resume is an explicit operator decision: grant fresh spawn-retry
+		// budgets so provider-outage failures are always retriggerable.
+		this.spawnRetryCounts.clear();
 		const tasks = store.loadAllTasks(this.squadId);
 		let resumedWork = false;
 		for (const task of tasks) {
@@ -678,25 +692,44 @@ export class Scheduler {
 	}
 
 	/**
-	 * Decide whether this task's agent should be spawned as a fork of the main
-	 * pi session (context inheritance). Guards against blowing the child model's
-	 * context window: forks only when the estimated session tokens fit within
-	 * 50% of the agent model's context window.
+	 * Decide whether this task's agent should be spawned as a fork of an
+	 * existing session: another task's durable session (forkFromTaskId) or the
+	 * main pi session (inheritContext). Guards against blowing the child
+	 * model's context window: forks only when the estimated session tokens fit
+	 * within 50% of the agent model's context window.
 	 */
 	private resolveForkSession(task: Task, squad: Squad, agentDef: AgentDef): string | undefined {
-		if (!task.inheritContext) return undefined;
+		if (!task.inheritContext && !task.forkFromTaskId) return undefined;
 
 		const skip = (reason: string): undefined => {
-			logError("squad-scheduler", `inheritContext skipped for ${task.id}: ${reason}`);
+			logError("squad-scheduler", `session fork skipped for ${task.id}: ${reason}`);
 			store.appendMessage(this.squadId, task.id, {
 				ts: store.now(),
 				from: "system",
 				type: "status",
-				text: `Context inheritance skipped: ${reason}. Agent starts with standard squad context only.`,
+				text: `Session fork skipped: ${reason}. Agent starts with standard squad context only.`,
 			});
 			return undefined;
 		};
 
+		// Fork another task's durable session: the follow-up/rework agent
+		// continues with the source task's complete context.
+		if (task.forkFromTaskId) {
+			const source = store.loadTaskSession(this.squadId, task.forkFromTaskId);
+			if (!source || !fs.existsSync(source.file)) {
+				return skip(`fork source task '${task.forkFromTaskId}' has no durable session file`);
+			}
+			const estTokens = Math.ceil(fs.statSync(source.file).size / 4);
+			const window = this.spawnContext?.resolveContextWindow?.(agentDef.model ?? null);
+			// An unknown window does not veto an explicit operator/orchestrator
+			// request: task sessions are bounded, unlike whole main sessions.
+			if (window && estTokens > window * 0.5) {
+				return skip(`fork source session (~${Math.round(estTokens / 1000)}k tokens) exceeds 50% of ${agentDef.model || "default model"}'s ${Math.round(window / 1000)}k window — restate key context in the task description instead`);
+			}
+			debug("squad-scheduler", `forkFromTask: forking ${source.file} (task ${task.forkFromTaskId}) for ${task.id} (~${Math.round(estTokens / 1000)}k tokens)`);
+			return source.file;
+		}
+
 		const sessionFile = squad.sessionFile;
 		if (!sessionFile) return skip("main session has no session file (ephemeral --no-session run)");
 		if (!fs.existsSync(sessionFile)) return skip(`session file not found: ${sessionFile}`);
@@ -778,24 +811,32 @@ export class Scheduler {
 		const turnCount = event.data?.turnCount ?? 0;
 		const stderr = event.data?.stderr || "";
 		const retryKey = `spawn-retry:${event.taskId}`;
-		if (!this.spawnRetries.has(retryKey)) {
-			this.spawnRetries.add(retryKey);
+		const attempt = this.spawnRetryCounts.get(retryKey) ?? 0;
+		const maxRetries = maxSpawnRetries();
+		if (attempt < maxRetries) {
+			this.spawnRetryCounts.set(retryKey, attempt + 1);
+			const delayMs = SPAWN_RETRY_BACKOFF_MS[Math.min(attempt, SPAWN_RETRY_BACKOFF_MS.length - 1)];
 			const reason = turnCount === 0
-				? "exited with 0 turns (likely rate limit or API error)"
+				? "exited with 0 turns (likely rate limit or provider API error)"
 				: `exited before final agent_settled after ${turnCount} turns`;
-			logError("squad-scheduler", `Agent ${event.agentName} ${reason}, code=${exitCode}. Retrying in 2s... stderr: ${stderr}`);
+			logError("squad-scheduler", `Agent ${event.agentName} ${reason}, code=${exitCode}. Retry ${attempt + 1}/${maxRetries} in ${Math.round(delayMs / 1000)}s... stderr: ${stderr}`);
 			store.updateTaskStatus(this.squadId, event.taskId, "pending");
 			store.appendMessage(this.squadId, event.taskId, {
 				ts: store.now(),
 				from: "system",
 				type: "status",
-				text: `Agent ${reason}. Resuming the same task session...`,
+				text: `Agent ${reason}. Retry ${attempt + 1}/${maxRetries} resumes the same task session in ${Math.round(delayMs / 1000)}s...`,
 			});
-			setTimeout(() => {
+			const timer = setTimeout(() => {
 				if (this.running) this.scheduleReadyTasks();
-			}, 2000);
+			}, delayMs);
+			(timer as { unref?: () => void }).unref?.();
 		} else {
-			this.handleTaskFailed(event.taskId, `Agent exited with code ${exitCode} before final agent_settled (retry exhausted). ${stderr}`);
+			this.handleTaskFailed(
+				event.taskId,
+				`Agent exited with code ${exitCode} before final agent_settled (${maxRetries} backoff retries exhausted — likely provider/API outage). ${stderr}`.trimEnd() +
+					`\nWhen the provider recovers, squad_modify { action: "resume_task", taskId: "${event.taskId}" } reopens the same durable session with a fresh retry budget — no work is redone.`,
+			);
 		}
 		this.updateContext();
 	}
@@ -994,6 +1035,9 @@ export class Scheduler {
 			.filter((m) => m.from === task.agent && (m.type === "text" || m.type === "done"));
 		const output = agentMessages.map((m) => m.text).join("\n");
 
+		// A successful completion also restores the full spawn-retry budget for
+		// any later reopen of this task (rework, follow-up messages).
+		this.spawnRetryCounts.delete(`spawn-retry:${taskId}`);
 		// Clear any interim failure annotation (spawn retry, RPC race): a task
 		// that ultimately completed must not display a stale error forever.
 		store.updateTaskStatus(this.squadId, taskId, "done", {
@@ -1679,6 +1723,8 @@ export class Scheduler {
 	async resumeTask(taskId: string): Promise<"resumed" | "already_running"> {
 		const task = store.loadTask(this.squadId, taskId);
 		if (!task) throw new Error(`Task not found: ${taskId}`);
+		// Explicit resume grants a fresh spawn-retry budget (provider recovery).
+		this.spawnRetryCounts.delete(`spawn-retry:${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.`);

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

@@ -149,7 +149,9 @@ Send small, scoped corrections instead of restarting the task:
 ## Modifying a Running Squad
 
 Use `squad_modify` when:
-- **`add_task`**: User requests something not in the original plan
+- **`add_task`**: User requests something not in the original plan. For follow-up or review-rework work, set `forkFromTask: "<source task id>"` so the new agent forks the source task's durable session and continues with its full context instead of redoing everything (mutually exclusive with `inheritContext`; the source must have run at least once).
+- **Provider outage recovery**: a task that failed with "retries exhausted — likely provider/API outage" is not stuck. When the provider recovers, `{ action: "resume_task", taskId: "..." }` reopens the exact durable session with a fresh retry budget — never recreate the task from scratch for this.
+- **Failed independent review**: never cancel the squad or mark it failed. Add same-squad rework tasks (ideally with `forkFromTask` pointing at the reviewed implementation task), let them settle, re-verify, and submit a fresh `squad_review`.
 - **`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.

package/src/tools-registration.ts

@@ -362,7 +362,9 @@ pi.registerTool({
 		if (accepted && runtime.activeSquadId === id) focusSquad(null);
 		const text = accepted
 			? `Independent orchestrator review recorded for '${id}' (${params.verdict}). The squad is now accepted as done.`
-			: `Independent review FAILED for '${id}'. The squad remains review-required. Fix every issue, rerun verification/E2E, then submit a fresh squad_review.`;
+			: `Independent review FAILED for '${id}'. The squad remains review-required — do NOT cancel it, do NOT mark it failed, and do NOT stop here.\n` +
+				`Route same-squad rework NOW: squad_modify { action: "add_task", squadId: "${id}", task: { id: "<slice>-fix-1", agent: "<original implementer>", forkFromTask: "<original task id>", title: "...", description: "<the exact failed issues>" } }.\n` +
+				`forkFromTask reopens the implementer's full session context so nothing is redone. When rework settles, independently re-verify and submit a fresh squad_review.`;
 		return { content: [{ type: "text" as const, text }], details: undefined };
 	},
 });
@@ -457,6 +459,7 @@ pi.registerTool({
 				agent: Type.String(),
 				depends: Type.Optional(Type.Array(Type.String())),
 				inheritContext: Type.Optional(Type.Boolean({ description: "Fork the current pi session so the agent inherits this conversation's context (see squad tool docs for caveats)" })),
+				forkFromTask: Type.Optional(Type.String({ description: "Existing task ID in this squad whose durable session seeds the new task as a fork — the agent continues with that task's full context instead of redoing everything. Ideal for follow-up and review-rework tasks. Mutually exclusive with inheritContext." })),
 			}, { description: "Task definition for add_task" }),
 		),
 	}),
@@ -534,6 +537,18 @@ pi.registerTool({
 					const available = store.loadAllAgentDefs(targetCwd).filter((a) => !a.disabled).map((a) => a.name).join(", ");
 					return { content: [{ type: "text" as const, text: `Unknown agent '${params.task.agent}'. Available: ${available}` }], details: undefined };
 				}
+				const forkFromTask = params.task.forkFromTask?.trim();
+				if (forkFromTask) {
+					if (params.task.inheritContext) {
+						return { content: [{ type: "text" as const, text: "Choose either forkFromTask or inheritContext, not both." }], details: undefined };
+					}
+					if (!existingIds.has(forkFromTask)) {
+						return { content: [{ type: "text" as const, text: `forkFromTask '${forkFromTask}' not found in squad '${squadId}'. Existing tasks: ${[...existingIds].join(", ")}` }], details: undefined };
+					}
+					if (!store.loadTaskSession(squadId, forkFromTask)) {
+						return { content: [{ type: "text" as const, text: `forkFromTask '${forkFromTask}' has no durable session yet (it never spawned). Add the task without forkFromTask, or fork a task that has run.` }], details: undefined };
+					}
+				}
 				const dependencies = params.task.depends || [];
 				const task: Task = {
 					id: params.task.id,
@@ -543,6 +558,7 @@ pi.registerTool({
 					status: dependencies.every((dependency) => existing.find((candidate) => candidate.id === dependency)?.status === "done") ? "pending" : "blocked",
 					depends: dependencies,
 					...(params.task.inheritContext ? { inheritContext: true } : {}),
+					...(forkFromTask ? { forkFromTaskId: forkFromTask } : {}),
 					...(targetSquad.spec ? { fileSpecDelta: true } : {}),
 					created: store.now(),
 					started: null,

package/src/types.ts

@@ -169,6 +169,10 @@ export interface Task {
 	/** Fork the main pi session so this agent inherits the full conversation context.
 	 * Skipped automatically if the estimated context exceeds 50% of the agent model's window. */
 	inheritContext?: boolean;
+	/** Seed this task's new session as a fork of another task's durable session,
+	 * so follow-up/rework work continues with that task's full context instead of
+	 * starting fresh. Mutually exclusive with inheritContext. */
+	forkFromTaskId?: string;
 	created: string;
 	started: string | null;
 	completed: string | null;