pi-squad 0.7.2 → 0.14.0

package/src/monitor.ts

@@ -11,16 +11,23 @@
 
 import type { AgentPool } from "./agent-pool.js";
 import type { HealthStatus } from "./types.js";
+import { debug } from "./logger.js";
 
 // ============================================================================
 // Config
 // ============================================================================
 
-const IDLE_WARNING_MS = 3 * 60 * 1000; // 3 min no output → warn
-const STUCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 min no output → intervene
-const HARD_CEILING_MS = 30 * 60 * 1000; // 30 min total → force stop
+/** Env-overridable for testing (PI_SQUAD_IDLE_MS etc.) */
+function envMs(name: string, fallback: number): number {
+	const v = Number(process.env[name]);
+	return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+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 LOOP_THRESHOLD = 5; // same tool call 5x → looping
-const POLL_INTERVAL_MS = 30 * 1000; // check every 30s
+const POLL_INTERVAL_MS = envMs("PI_SQUAD_POLL_MS", 30 * 1000); // check interval
 
 // ============================================================================
 // Types
@@ -51,6 +58,8 @@ export class Monitor {
 	private warned = new Set<string>();
 	/** Track which agents have been steered for stuck (to avoid repeated steers) */
 	private stuckSteered = new Set<string>();
+	/** Track which tasks have been escalated (one escalation per stuck episode) */
+	private escalated = new Set<string>();
 
 	constructor(pool: AgentPool, squadId: string) {
 		this.pool = pool;
@@ -90,6 +99,7 @@ export class Monitor {
 		}
 		this.warned.clear();
 		this.stuckSteered.clear();
+		this.escalated.clear();
 	}
 
 	/** Check all running agents */
@@ -132,11 +142,13 @@ export class Monitor {
 
 	/** Take action based on health status */
 	private handleHealth(taskId: string, agentName: string, status: HealthStatus): void {
+		if (status !== "healthy") debug("squad-monitor", `${taskId} (${agentName}): ${status}`);
 		switch (status) {
 			case "healthy":
-				// Clear warning flags
+				// Clear warning flags — a new stuck episode escalates again
 				this.warned.delete(taskId);
 				this.stuckSteered.delete(taskId);
+				this.escalated.delete(taskId);
 				break;
 
 			case "idle_warning":
@@ -166,8 +178,9 @@ export class Monitor {
 							"Summarize what you've done and what's blocking you. " +
 							"If you can't proceed, state what you need.",
 					});
-				} else {
-					// Already steered once, escalate
+				} else if (!this.escalated.has(taskId)) {
+					// Already steered once — escalate, but only once per stuck episode
+					this.escalated.add(taskId);
 					this.emit({
 						type: "escalate",
 						taskId,

package/src/panel/message-view.ts

@@ -4,8 +4,8 @@
  * TUI corruption from large message histories.
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { TaskMessage } from "../types.js";
 import * as store from "../store.js";
 

package/src/panel/squad-panel.ts

@@ -9,9 +9,9 @@
  * - done() closes the overlay cleanly
  */
 
-import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
-import { matchesKey, visibleWidth, truncateToWidth } from "@mariozechner/pi-tui";
-import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
+import { matchesKey, visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { PanelState, PanelView } from "../types.js";
 import type { Scheduler } from "../scheduler.js";
 import { TaskListView } from "./task-list.js";

package/src/panel/squad-widget.ts

@@ -10,9 +10,9 @@
  * lines and calls setWidget() again.
  */
 
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { Component, TUI } from "@mariozechner/pi-tui";
-import type { Theme } from "@mariozechner/pi-coding-agent";
+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 { TaskStatus } from "../types.js";
 import * as store from "../store.js";
 

package/src/panel/task-list.ts

@@ -2,8 +2,8 @@
  * task-list.ts — Task tree view with status icons, live activity preview.
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth } from "@mariozechner/pi-tui";
+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 * as store from "../store.js";

package/src/plan-rules.ts

@@ -0,0 +1,134 @@
+/**
+ * plan-rules.ts — Single source of truth for squad planning behavior.
+ *
+ * Used by BOTH planning paths so they behave identically:
+ * - The planner agent (planner.ts injects these into its prompt)
+ * - The main pi session (index.ts injects these into the squad tool
+ *   description / hint, and validatePlan() enforces them at submission)
+ */
+
+// ============================================================================
+// Shared prompt fragments
+// ============================================================================
+
+/** How to structure task descriptions (Goal/Context/Output/Boundaries/Verify) */
+export const TASK_DESCRIPTION_GUIDE = `Structure each task description around these parts (include only the parts that help):
+- **Goal**: the outcome, stated first. Describe the result, not step-by-step process — prescribe steps only when the process itself matters
+- **Context**: the specific files, contracts, or dependency outputs the agent should read — name where to look, don't dump everything
+- **Output**: the expected deliverable — files, format, level of detail
+- **Boundaries**: what must stay unchanged (public APIs, schemas, config), what the agent must not do, and anything requiring escalation instead of guessing
+- **Verify**: the exact command or check that proves the task is done (e.g. "npm test -- auth", "curl /api/health returns 200")`;
+
+/** Structural rules for a good plan */
+export const PLAN_STRUCTURE_RULES = `- Task IDs must be short kebab-case (e.g., "setup-db", "auth-middleware")
+- Dependencies must reference task IDs from the same plan
+- First task(s) should have empty depends: []
+- When tasks share an interface (API endpoints, database schema, data formats), create a design/contract task first that defines the contract, and make consuming tasks depend on it
+- Include a final QA/verification task if there are user-facing changes
+- Don't over-decompose — 3-7 tasks is usually right for most goals
+- Scope tasks to required work only — no optional polish or nice-to-haves unless the goal asks for them`;
+
+// ============================================================================
+// Plan validation (enforcement — applies to planner AND main-session plans)
+// ============================================================================
+
+export interface PlanTaskInput {
+	id: string;
+	title: string;
+	description: string;
+	agent: string;
+	depends: string[];
+}
+
+export interface PlanValidation {
+	/** Hard failures — squad must not start */
+	errors: string[];
+	/** Rule violations worth reporting back to the plan author */
+	warnings: string[];
+}
+
+/** Does this task look like a QA/verification/review task? */
+function isQaLikeTask(task: PlanTaskInput): boolean {
+	const hay = `${task.id} ${task.title} ${task.agent}`.toLowerCase();
+	return /\b(qa|test|tests|testing|verif\w*|review|audit)\b/.test(hay);
+}
+
+/**
+ * Validate a plan's structure. Errors block squad creation;
+ * warnings are returned to the plan author for correction.
+ */
+export function validatePlan(tasks: PlanTaskInput[]): PlanValidation {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+
+	// Duplicate IDs
+	const ids = new Set<string>();
+	for (const t of tasks) {
+		if (ids.has(t.id)) errors.push(`Duplicate task id: "${t.id}"`);
+		ids.add(t.id);
+	}
+
+	// Unknown dependency references
+	for (const t of tasks) {
+		for (const dep of t.depends) {
+			if (!ids.has(dep)) {
+				errors.push(`Task "${t.id}" depends on unknown task "${dep}"`);
+			}
+		}
+	}
+
+	// Cycle detection (DFS, only over known deps)
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const byId = new Map(tasks.map((t) => [t.id, t]));
+	const inCycle: string[] = [];
+	const visit = (id: string): boolean => {
+		if (visited.has(id)) return false;
+		if (visiting.has(id)) return true;
+		visiting.add(id);
+		const task = byId.get(id);
+		if (task) {
+			for (const dep of task.depends) {
+				if (byId.has(dep) && visit(dep)) {
+					inCycle.push(id);
+					visiting.delete(id);
+					return true;
+				}
+			}
+		}
+		visiting.delete(id);
+		visited.add(id);
+		return false;
+	};
+	for (const t of tasks) {
+		if (visit(t.id) && inCycle.length > 0) {
+			errors.push(`Dependency cycle involving: ${[...new Set(inCycle)].join(", ")}`);
+			break;
+		}
+	}
+
+	// No entry point (every task has deps) — only meaningful without errors
+	if (tasks.length > 0 && errors.length === 0 && !tasks.some((t) => t.depends.length === 0)) {
+		errors.push("No task has empty depends — nothing can start");
+	}
+
+	// --- Warnings (planner rules) ---
+
+	if (tasks.length > 9) {
+		warnings.push(`${tasks.length} tasks — over-decomposed (3-7 is usually right). Consider merging related tasks.`);
+	}
+
+	if (tasks.length >= 3 && !tasks.some(isQaLikeTask)) {
+		warnings.push("No QA/verification task in the plan. Add a final task that tests the integrated result, or verify it yourself when the squad completes.");
+	}
+
+	for (const t of tasks) {
+		if (!t.description || t.description.trim().length === 0) {
+			warnings.push(`Task "${t.id}" has no description — the agent only gets the title.`);
+		} else if (!/verif|test|check|curl|run\b|npm |pnpm |cargo |pytest|tsc\b/i.test(t.description)) {
+			warnings.push(`Task "${t.id}" description has no Verify criterion — the agent won't know how to prove it's done.`);
+		}
+	}
+
+	return { errors, warnings };
+}

package/src/planner.ts

@@ -11,6 +11,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentDef, PlannerOutput } from "./types.js";
 import { loadAllAgentDefs, loadAgentDef } from "./store.js";
+import { PLAN_STRUCTURE_RULES, TASK_DESCRIPTION_GUIDE } from "./plan-rules.js";
 
 // ============================================================================
 // Planner
@@ -21,6 +22,10 @@ export interface PlannerOptions {
 	cwd: string;
 	/** If provided, use this model for planning instead of the planner agent's default */
 	model?: string;
+	/** Fallback model when neither `model` nor the planner agent def specifies one (squad default policy) */
+	fallbackModel?: string;
+	/** Fallback thinking level when the planner agent def doesn't specify one (squad default policy) */
+	fallbackThinking?: string;
 }
 
 /**
@@ -28,7 +33,7 @@ export interface PlannerOptions {
  * Returns the parsed plan or throws on failure.
  */
 export async function runPlanner(options: PlannerOptions): Promise<PlannerOutput> {
-	const { goal, cwd, model } = options;
+	const { goal, cwd, model, fallbackModel, fallbackThinking } = options;
 
 	const plannerDef = loadAgentDef("planner", cwd);
 	const allAgents = loadAllAgentDefs(cwd).filter((a) => a.name !== "planner" && !a.disabled);
@@ -62,7 +67,8 @@ export async function runPlanner(options: PlannerOptions): Promise<PlannerOutput
 			cwd,
 			prompt: `Read the prompt file at ${promptFile} and follow the instructions.`,
 			systemPromptFile: systemFile,
-			model: model || plannerDef?.model || undefined,
+			model: model || plannerDef?.model || fallbackModel || undefined,
+			thinking: plannerDef?.thinking || fallbackThinking || undefined,
 		});
 
 		const agentNames = new Set(allAgents.map((a) => a.name));
@@ -87,13 +93,15 @@ interface PiJsonOptions {
 	prompt: string;
 	systemPromptFile?: string;
 	model?: string;
+	thinking?: string;
 }
 
 async function runPiJson(options: PiJsonOptions): Promise<string> {
-	const { cwd, prompt, systemPromptFile, model } = options;
+	const { cwd, prompt, systemPromptFile, model, thinking } = options;
 
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (model) args.push("--model", model);
+	if (thinking) args.push("--thinking", thinking);
 	if (systemPromptFile) args.push("--append-system-prompt", systemPromptFile);
 	args.push(prompt);
 
@@ -244,13 +252,13 @@ Respond with a JSON object (and nothing else outside the JSON):
 {
   "agents": {
     "agent-name": {},
-    "agent-name": { "model": "override-model-if-needed" }
+    "agent-name": { "model": "override-model-if-needed", "thinking": "high" }
   },
   "tasks": [
     {
       "id": "short-kebab-id",
       "title": "Human-readable task title",
-      "description": "Detailed description of what to implement",
+      "description": "Goal: the outcome to achieve. Context: relevant files/contracts to read. Output: expected deliverable and format. Boundaries: what must NOT change. Verify: command or check that proves it works.",
       "agent": "agent-name",
       "depends": ["id-of-dependency", "another-dependency"]
     }
@@ -259,16 +267,12 @@ Respond with a JSON object (and nothing else outside the JSON):
 \`\`\`
 
 ## Rules
-- Task IDs must be short kebab-case (e.g., "setup-db", "auth-middleware")
+${PLAN_STRUCTURE_RULES}
 - Only reference agents that exist in the Available Agents list
-- Dependencies must reference task IDs from your own plan
-- First task(s) should have empty depends: []
-- Include a final QA/verification task if there are user-facing changes
-- Keep descriptions actionable — agent should know exactly what to build
-- Don't over-decompose — 3-7 tasks is usually right for most goals
-
-## Shared Contracts
-- When tasks share an interface (e.g., API endpoints, database schema, data formats), create a design/architecture task first that defines the contract, and make consuming tasks depend on it
+- Agent overrides are optional: "model" (a pi model id) and "thinking" (one of: off, minimal, low, medium, high, xhigh, max). Omit both to use defaults. Raise "thinking" only for tasks needing deep reasoning (architecture, security)
+
+## Task Descriptions
+${TASK_DESCRIPTION_GUIDE}
 - If tasks run in parallel, they MUST depend on a shared spec task that defines the interface between them
 - Frontend tasks should depend on backend API tasks — the frontend agent needs a running API to test against
 - In each task description, specify the exact API paths, data schemas, and conventions that the agent should follow or create

package/src/protocol.ts

@@ -56,7 +56,13 @@ The squad system will detect this and route help.
 - Read the dependency outputs below — don't redo completed work
 - Check the modified files list — coordinate before editing shared files
 - Ask for help if stuck — don't spin for more than a few minutes
-- Verify your work before claiming done
+- Verify your work before claiming done — report the commands you ran and their results
+
+## Boundaries
+- If required information is missing or ambiguous, ask (@mention or escalate) — flag gaps instead of guessing or inventing
+- Keep changes minimal and within your task's scope — don't refactor unrelated code or add unrequested polish
+- Respect your task's stated boundaries: keep public APIs, schemas, and configs unchanged unless the task says otherwise
+- Never take externally visible actions (git push, deploy, publish, send messages/emails) unless your task explicitly instructs it — prepare, don't ship
 `;
 }
 
@@ -262,10 +268,12 @@ function buildReworkContext(task: Task, squadId: string): string {
 
 	lines.push("## Instructions");
 	lines.push("- Read the QA feedback carefully — fix ONLY the reported issues");
+	lines.push("- FIRST reproduce each reported issue (run the failing test or repro steps) — confirm you see the failure before changing code");
 	lines.push("- Do NOT rewrite everything from scratch");
 	lines.push("- Make targeted, minimal fixes");
 	lines.push("- Re-run the failing tests to verify your fixes");
-	lines.push("- Include test output as evidence in your completion message\n");
+	lines.push("- Include test output as evidence in your completion message");
+	lines.push("- Follow the squad-debugging skill for the full repro-first rework discipline\n");
 
 	return lines.join("\n");
 }

package/src/scheduler.ts

@@ -9,6 +9,8 @@
  * - Detects squad completion
  */
 
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentDef, Squad, SquadConfig, Task, TaskMessage, TaskStatus } from "./types.js";
 import { AgentPool, type AgentEvent } from "./agent-pool.js";
 import { Monitor } from "./monitor.js";
@@ -16,6 +18,7 @@ import { Router } from "./router.js";
 import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
+import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
 
 // ============================================================================
 // Types
@@ -44,6 +47,16 @@ export interface SchedulerEvent {
 
 export type SchedulerEventListener = (event: SchedulerEvent) => void;
 
+/** 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 */
+	resolveContextWindow?: (model: string | null) => number | undefined;
+	/** Resolve the squad default model/thinking policy (settings.json + main session state) */
+	getDefaultModelThinking?: () => { model?: string; thinking?: string };
+	/** Consult the advisor model with a curated digest. Returns advice text, or null when disabled/unavailable. */
+	consultAdvisor?: (input: AdvisorConsultInput) => Promise<string | null>;
+}
+
 // ============================================================================
 // Scheduler
 // ============================================================================
@@ -55,6 +68,7 @@ export class Scheduler {
 	private router: Router;
 	private listeners: SchedulerEventListener[] = [];
 	private skillPaths: string[] = [];
+	private spawnContext?: SchedulerSpawnContext;
 	private running = false;
 	/** Track spawn retries to allow one retry per task */
 	private spawnRetries = new Set<string>();
@@ -64,9 +78,10 @@ export class Scheduler {
 		return store.loadSquad(this.squadId)?.cwd;
 	}
 
-	constructor(squadId: string, skillPaths: string[]) {
+	constructor(squadId: string, skillPaths: string[], spawnContext?: SchedulerSpawnContext) {
 		this.squadId = squadId;
 		this.skillPaths = skillPaths;
+		this.spawnContext = spawnContext;
 		this.pool = new AgentPool();
 		this.monitor = new Monitor(this.pool, squadId);
 		this.router = new Router(this.pool, squadId);
@@ -81,11 +96,16 @@ export class Scheduler {
 			} else if (action.type === "abort") {
 				this.handleTaskFailed(action.taskId, action.reason);
 			} else if (action.type === "escalate") {
-				this.emit({
-					type: "escalation",
-					squadId: this.squadId,
-					taskId: action.taskId,
-					message: action.reason,
+				// Advisor-first: try a strong-model rescue before interrupting the human
+				void this.tryAdvisorRescue(action.taskId, action.agentName, action.reason).then((rescued) => {
+					if (rescued) return;
+					this.emit({
+						type: "escalation",
+						squadId: this.squadId,
+						taskId: action.taskId,
+						agentName: action.agentName,
+						message: action.reason,
+					});
 				});
 			}
 		});
@@ -248,11 +268,25 @@ export class Scheduler {
 			return;
 		}
 
-		// Apply squad-level model override
+		// Apply squad-level model/thinking overrides
 		const squadAgentEntry = squad.agents[task.agent];
 		if (squadAgentEntry?.model) {
 			agentDef.model = squadAgentEntry.model;
 		}
+		if (squadAgentEntry?.thinking) {
+			agentDef.thinking = squadAgentEntry.thinking;
+		}
+
+		// Apply squad defaults for anything still unset (policy resolved by the
+		// extension host: "main" = main session's model/thinking, "pi-default" =
+		// leave unset, or an explicit value from ~/.pi/squad/settings.json)
+		const defaults = this.spawnContext?.getDefaultModelThinking?.();
+		if (!agentDef.model && defaults?.model) {
+			agentDef.model = defaults.model;
+		}
+		if (!agentDef.thinking && defaults?.thinking) {
+			agentDef.thinking = defaults.thinking;
+		}
 
 		// Build modified files map from all running agents
 		const modifiedFiles: Record<string, string[]> = {};
@@ -285,6 +319,9 @@ export class Scheduler {
 			agentName: task.agent,
 		});
 
+		// Decide whether to fork the main session for context inheritance
+		const forkSessionFile = this.resolveForkSession(task, squad, agentDef);
+
 		try {
 			await this.pool.spawn({
 				taskId: task.id,
@@ -299,6 +336,14 @@ export class Scheduler {
 				},
 				cwd: squad.cwd,
 				skillPaths: this.skillPaths,
+				...(forkSessionFile
+					? {
+							forkSession: {
+								file: forkSessionFile,
+								sessionDir: path.join(store.getSquadDir(this.squadId), "sessions"),
+							},
+						}
+					: {}),
 			});
 		} catch (error) {
 			this.handleTaskFailed(task.id, (error as Error).message);
@@ -307,6 +352,123 @@ export class Scheduler {
 		this.updateContext();
 	}
 
+	/** Advisor consultations per task (advisor-first escalation) */
+	private advisorAttempts = new Map<string, number>();
+
+	/**
+	 * Consult the advisor for a stuck agent and steer it with the advice.
+	 * Returns true when the agent was steered (escalation suppressed).
+	 * Returns false when the advisor is disabled, exhausted, unavailable,
+	 * failed, or explicitly said the problem needs human input.
+	 */
+	private async tryAdvisorRescue(taskId: string, agentName: string | undefined, reason: string): Promise<boolean> {
+		try {
+			const consult = this.spawnContext?.consultAdvisor;
+			if (!consult) return false;
+
+			const settings = store.loadSquadSettings();
+			if (!settings.advisor.enabled) return false;
+
+			const attempts = this.advisorAttempts.get(taskId) || 0;
+			if (attempts >= settings.advisor.maxCallsPerTask) {
+				debug("squad-advisor", `${taskId}: advisor exhausted (${attempts}/${settings.advisor.maxCallsPerTask}), escalating`);
+				return false;
+			}
+			if (!this.pool.isRunning(taskId)) return false;
+
+			const task = store.loadTask(this.squadId, taskId);
+			const squad = store.loadSquad(this.squadId);
+			if (!task || !squad) return false;
+			const agentDef = store.loadAgentDef(task.agent, squad.cwd);
+			const activity = this.pool.getActivity(taskId);
+
+			this.advisorAttempts.set(taskId, attempts + 1);
+
+			const input: AdvisorConsultInput = {
+				taskId,
+				taskTitle: task.title,
+				taskDescription: task.description,
+				agentName: task.agent,
+				agentRole: agentDef?.role || task.agent,
+				reason,
+				recentMessages: store.loadMessages(this.squadId, taskId).slice(-12).map((m) => ({ from: m.from, type: m.type, text: m.text })),
+				recentToolCalls: activity ? [...activity.recentToolCalls] : [],
+				turnCount: activity?.turnCount || 0,
+				elapsedMinutes: activity ? (Date.now() - activity.startedAt) / 60000 : 0,
+			};
+
+			const advice = await consult(input);
+			if (!advice) return false;
+
+			store.appendMessage(this.squadId, taskId, {
+				ts: store.now(),
+				from: "advisor",
+				type: "message",
+				text: advice,
+			});
+
+			// Advisor says a human decision is required — escalate with the advice attached
+			if (adviceNeedsHuman(advice)) {
+				this.emit({
+					type: "escalation",
+					squadId: this.squadId,
+					taskId,
+					agentName,
+					message: `${reason}\n\nAdvisor assessment:\n${advice.slice(0, 800)}`,
+				});
+				return true; // escalation already emitted with richer context
+			}
+
+			const delivered = await this.pool.steer(taskId, formatAdvisorSteerMessage(advice, reason));
+			debug("squad-advisor", `${taskId}: advisor steered agent (attempt ${attempts + 1}, delivered=${delivered})`);
+			return delivered;
+		} catch (error) {
+			logError("squad-advisor", `rescue failed for ${taskId}: ${(error as Error).message}`);
+			return false;
+		}
+	}
+
+	/**
+	 * 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.
+	 */
+	private resolveForkSession(task: Task, squad: Squad, agentDef: AgentDef): string | undefined {
+		if (!task.inheritContext) return undefined;
+
+		const skip = (reason: string): undefined => {
+			logError("squad-scheduler", `inheritContext 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.`,
+			});
+			return undefined;
+		};
+
+		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}`);
+
+		// Rough token estimate: JSONL bytes / 4. Overestimates (JSON overhead), which is safe.
+		const estTokens = Math.ceil(fs.statSync(sessionFile).size / 4);
+
+		const window = this.spawnContext?.resolveContextWindow?.(agentDef.model ?? null);
+		if (!window) {
+			return skip(`cannot determine context window for model "${agentDef.model || "(default)"}"`);
+		}
+		if (estTokens > window * 0.5) {
+			return skip(
+				`estimated session context (~${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", `inheritContext: forking ${sessionFile} for ${task.id} (~${Math.round(estTokens / 1000)}k tokens, window ${Math.round(window / 1000)}k)`);
+		return sessionFile;
+	}
+
 	// =========================================================================
 	// Event Handlers
 	// =========================================================================
@@ -599,7 +761,7 @@ export class Scheduler {
 	 */
 	private checkForRework(task: Task, output: string): boolean {
 		// Only trigger rework for QA/test agent tasks
-		const qaAgents = ["qa", "tester", "security"];
+		const qaAgents = ["qa", "tester", "security", "reviewer"];
 		if (!qaAgents.includes(task.agent)) return false;
 
 		// Parse verdict from output
@@ -610,7 +772,7 @@ export class Scheduler {
 		const allTasks = store.loadAllTasks(this.squadId);
 		const implDeps = task.depends
 			.map((depId) => allTasks.find((t) => t.id === depId))
-			.filter((t): t is Task => t !== null && !qaAgents.includes(t.agent));
+			.filter((t): t is Task => t !== undefined && !qaAgents.includes(t.agent));
 
 		if (implDeps.length === 0) return false;
 
@@ -649,6 +811,7 @@ export class Scheduler {
 				agent: implTask.agent,
 				status: "pending",
 				depends: [],
+				...(implTask.inheritContext ? { inheritContext: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,