pi-squad 0.4.14 → 0.6.0

package/README.md

@@ -22,7 +22,7 @@ Ask pi to do something complex. It calls the `squad` tool automatically:
 > Build a REST API with authentication, tests, and documentation
 ```
 
-Or be explicit with predefined tasks:
+The planner agent reads your codebase and creates a task breakdown automatically. Or be explicit:
 
 ```
 > Use squad: goal="Build task API", tasks=[
@@ -34,17 +34,18 @@ Or be explicit with predefined tasks:
 
 ### What Happens
 
-1. Extension creates tasks and starts the scheduler
+1. Planner analyzes the codebase and creates tasks (or uses your predefined tasks)
 2. A **live widget** appears above the editor showing task status
 3. Agents spawn as separate pi processes, work in parallel where dependencies allow
 4. QA agents can trigger **automatic rework loops** when they find bugs
-5. When complete, pi reports the summary with costs
+5. When complete, pi reports the summary — notifications don't pollute message history
+6. Multiple squads can run concurrently across different projects
 
 ## User Interface
 
 ### Widget (above editor)
 
-Always visible when a squad is active. Component-based, event-driven rendering — updates on every scheduler event with no polling.
+Always visible when a squad is active. Debounced updates with cache key to avoid flicker.
 
 ```
 ⏳ squad Build task API 2/3 $0.58 3m12s  ^q detail · /squad msg
@@ -57,7 +58,7 @@ Features:
 - Per-task elapsed time (warning color after 3 minutes)
 - Live tool call preview for running tasks
 - Stale detection — shows `⏳ idle` when agent has no output for 2+ minutes
-- Responsive — caps visible tasks based on terminal height
+- Responsive — caps visible tasks on small terminals, shows `+N more` overflow
 - Completion duration for finished tasks
 
 ### Status Bar (footer)
@@ -68,9 +69,9 @@ Features:
 
 ### Panel (Ctrl+Q)
 
-Centered overlay panel. Press `Ctrl+Q` to open/close.
+Centered overlay panel with proper lifecycle management. Press `Ctrl+Q` to open/close.
 
-**Task list:**
+**Task list** with sticky summary at bottom:
 ```
 ╭─ squad: Build task API ─────────────────────╮
 │ ▸ ✓ api (backend) 2m12s                     │
@@ -86,15 +87,18 @@ Centered overlay panel. Press `Ctrl+Q` to open/close.
 ╰──────────────────────────────────────────────╯
 ```
 
-**Message view** (Enter on a task):
+**Message view** (Enter on a task) — long text wraps instead of truncating:
 ```
 ╭─ tests · qa ⏳ ─────────────────────────────╮
 │ 10:03 qa                                     │
-│   Starting test implementation               │
+│   Starting test implementation. Will cover   │
+│      all CRUD endpoints, validation, and     │
+│      edge cases for empty input.             │
 │ 10:04 qa                                     │
 │   → write src/tasks.test.js                  │
 │ 10:05 YOU                                    │
 │   Also test edge cases for empty input       │
+│ ─ 65% ─ 24 msgs ─ ↑↓ scroll                │
 ├──────────────────────────────────────────────┤
 │ ↑↓ scroll  m send  esc back  ^q close       │
 ╰──────────────────────────────────────────────╯
@@ -110,10 +114,14 @@ Centered overlay panel. Press `Ctrl+Q` to open/close.
 | `/squad agents` | List, view, edit, enable/disable agents |
 | `/squad agents <name>` | Quick view of a specific agent |
 | `/squad msg [agent] text` | Send message to a running agent |
-| `/squad widget` | Toggle live widget |
+| `/squad widget` | Toggle live widget on/off |
 | `/squad panel` | Toggle overlay panel |
 | `/squad cancel` | Cancel running squad |
 | `/squad clear` | Dismiss widget, deactivate view |
+| `/squad cleanup` | Delete squad data (select one or all) |
+| `/squad cleanup all` | Delete all squad data |
+| `/squad enable` | Enable pi-squad (tools, widget, system prompt) |
+| `/squad disable` | Disable pi-squad completely |
 
 ## Keyboard Shortcuts
 
@@ -137,7 +145,21 @@ Centered overlay panel. Press `Ctrl+Q` to open/close.
 | `squad_message` | Send message to a running agent via `steer()` |
 | `squad_modify` | Add/cancel/pause/resume tasks, or cancel/resume entire squad |
 
-The main pi agent sees squad state in its system prompt automatically (`<squad_status>` block) and can relay messages, add tasks, or check status on your behalf.
+The main pi agent sees squad state in its system prompt automatically (`<squad_status>` block) and can relay messages, add tasks, or check status on your behalf. Squad notifications use `sendMessage({ display: true })` so they don't pollute the LLM's message history.
+
+## Multiple Concurrent Squads
+
+Multiple squads can run in parallel from the same pi session. Each squad has its own scheduler, agent pool, and disk state.
+
+```
+> Build the auth API          → starts squad-1
+> Build the dashboard UI      → starts squad-2 (runs in parallel)
+
+/squad list                   → see both, select which to view
+/squad select                 → switch widget/panel focus
+```
+
+All squads run independently in the background. The widget/panel shows whichever squad you're focused on.
 
 ## QA Rework Loop
 
@@ -190,7 +212,7 @@ All 42 tests passing. No issues found.
 
 ```
 config: {
-  maxConcurrency: 3,  // parallel agents
+  maxConcurrency: 3,  // parallel agents (default: 2)
   maxRetries: 2,      // rework attempts before escalation (default: 2)
 }
 ```
@@ -269,7 +291,7 @@ Create a JSON file in `~/.pi/squad/agents/` (global) or `{project}/.pi/squad/age
 
 - `model`: `null` = pi default. Override with any model ID your provider supports.
 - `tools`: `null` = all tools. Array like `["bash", "read", "write", "edit"]` to restrict.
-- `tags`: Used by the planner to match agents to tasks.
+- `tags`: Used by the planner to match agents to tasks automatically.
 - `disabled`: `true` = hidden from planner, tasks assigned to this agent will fail.
 - Project-local agents override global agents with the same name.
 
@@ -277,7 +299,7 @@ Create a JSON file in `~/.pi/squad/agents/` (global) or `{project}/.pi/squad/age
 
 ### Chain Context (primary)
 
-When task A completes, its **full output** is injected into task B's system prompt as a `# Completed Dependencies` section. Downstream agents read what was built and extend it.
+When task A completes, its **full output** is injected into task B's system prompt as a `# Completed Dependencies` section. Downstream agents read what was built and extend it — no need for explicit communication.
 
 ### Shared Filesystem
 
@@ -290,7 +312,7 @@ When agents run in parallel, each sees the other's status and modified files in
 ```
 # Sibling Tasks
 - template-engine [in_progress] — fullstack — Create HTML templates
-  
+
 ## Files Modified by Other Agents
 **fullstack:** src/templateEngine.js, templates/post.html
 ⚠️ Coordinate with the owning agent before editing files listed above.
@@ -319,6 +341,7 @@ When a pi session crashes (tmux dies, SIGKILL, etc.):
 - In-progress tasks are automatically **suspended** on next startup
 - Squad is marked as **paused**
 - Only squads with completed tasks trigger a notification
+- Squads with zero progress are silently paused (no noise)
 
 ### Resume
 
@@ -331,9 +354,14 @@ Resume a paused squad across sessions:
 The agent calls `squad_modify({ action: "resume" })`, which:
 1. Finds the latest paused squad for the project
 2. Creates a fresh scheduler from disk state
-3. Restarts suspended tasks
+3. Wires up event handlers for completion/failure/escalation
+4. Restarts suspended tasks
+
+All state lives on disk — squads are fully reconstructable from JSON files.
 
-All state lives on disk — squads are fully reconstructable.
+### Spawn Resilience
+
+Child agent processes occasionally fail during startup (transient resource pressure). The scheduler automatically retries once after a 2-second delay. If the retry also fails, the task is marked failed with a diagnostic log including PID, exit code, stderr, and stdout line count.
 
 ## Governance
 
@@ -343,13 +371,15 @@ All state lives on disk — squads are fully reconstructable.
 | **Concurrency control** | `maxConcurrency` limits parallel agents (default: 2) |
 | **Health monitoring** | Idle warning (3m), stuck intervention (5m), loop detection (same tool 5x), 30m hard ceiling |
 | **QA rework loop** | Auto-creates fix + retest tasks when QA fails (up to `maxRetries`) |
+| **Spawn retry** | Retries once on transient startup failures, then fails with diagnostics |
 | **File tracking** | Warns agents about files modified by other agents |
 | **@mention routing** | Parsed from output, delivered via RPC `steer()` |
-| **Escalation** | Blocked agents, stuck agents, and retry limit → notify main agent |
+| **Escalation** | Blocked agents, stuck agents, retry limit, spawn failure → notify main agent |
+| **Clean notifications** | Uses `sendMessage({ display: true })` — visible to user, not in LLM history |
 
 ## Data Layout
 
-All state lives in `~/.pi/squad/`. No database, no daemon, no external services. Writes are atomic (temp file + rename).
+All state lives in `~/.pi/squad/`. No database, no daemon, no external services. Writes are atomic (temp file + rename). JSONL reads are fault-tolerant (skip corrupt lines from concurrent writes).
 
 ```
 ~/.pi/squad/
@@ -364,7 +394,7 @@ All state lives in `~/.pi/squad/`. No database, no daemon, no external services.
     │   ├── decisions.jsonl
     │   └── findings.jsonl
     └── {task-id}/             — one directory per task
-        ├── task.json          — status, agent, output, usage
+        ├── task.json          — status, agent, output, usage, retryOf, qaFeedback
         └── messages.jsonl     — full conversation log
 ```
 
@@ -374,46 +404,51 @@ All state lives in `~/.pi/squad/`. No database, no daemon, no external services.
 src/
 ├── index.ts              — extension entry: tools, commands, widget, panel, lifecycle
 ├── types.ts              — Squad, Task, Agent, Message types
-├── store.ts              — JSON/JSONL file I/O with atomic writes
-├── scheduler.ts          — dependency DAG, concurrency, rework loop, task lifecycle
-├── agent-pool.ts         — pi RPC process spawn/steer/kill
-├── protocol.ts           — system prompt builder (7 sections)
+├── store.ts              — JSON/JSONL file I/O with atomic writes, fault-tolerant reads
+├── scheduler.ts          — dependency DAG, concurrency, rework loop, spawn retry, task lifecycle
+├── agent-pool.ts         — pi RPC process spawn/steer/kill, diagnostic logging
+├── protocol.ts           — system prompt builder (7 sections + rework context)
 ├── router.ts             — @mention parsing, cross-agent messaging
 ├── monitor.ts            — health checks: idle/stuck/loop/ceiling
 ├── supervisor.ts         — quality review, block analysis
 ├── planner.ts            — one-shot goal decomposition via LLM
 ├── panel/
 │   ├── squad-panel.ts    — overlay component (ctx.ui.custom with done())
-│   ├── squad-widget.ts   — component-based widget (setWidget factory)
-│   ├── task-list.ts      — task tree with status icons, elapsed time
-│   └── message-view.ts   — scrollable message log per task
+│   ├── squad-widget.ts   — string[] widget with debounce and cache
+│   ├── task-list.ts      — task tree with status icons, elapsed time, sticky summary
+│   └── message-view.ts   — scrollable message log with word wrap, fixed-height layout
 ├── skills/
 │   ├── supervisor/       — teaches main agent to supervise squads
 │   ├── squad-protocol/   — communication rules for child agents
 │   ├── collaboration/    — team interaction patterns
-│   └── verification/     — verify-before-done + structured verdicts
+│   └── verification/     — verify-before-done + structured QA verdicts
 └── agents/_defaults/     — 11 bundled agent definitions
 ```
 
 ## Test Results
 
 ### Simple (3 tasks, linear chain)
-- URL shortener API: 3 tasks, $0.83, 4.5 minutes
+- URL shortener API: 3 tasks, 30 turns, $0.83, 4.5 minutes
 - Backend → QA → Docs, all passing
 
-### Medium (6 tasks, diamond dependency)
-- Static blog engine: 6 tasks, $4.56, 24 minutes
-- Markdown parser → HTML converter → site generator → Express server → QA + Docs
-- 87+ tests passing
+### Medium (5 tasks, planner-decomposed)
+- Quiz API: 5 tasks, 82 turns, $3.11, 14 minutes
+- Planner auto-created: architect → backend → fullstack → QA + docs
+- 111 vitest tests passing, 3,637 lines of code
 
-### Complex (5 original + 4 auto-rework = 9 tasks)
-- Chat API with auth + rooms: 9 tasks, $4.60, 26 minutes
+### Complex with rework (5 original + 4 auto-rework = 9 tasks)
+- Chat API with auth + rooms: 9 tasks, 176 turns, $4.60, 26 minutes
 - QA found 2 bugs → 2 automatic rework cycles → both fixed and verified
-- 176 turns across 5 specialist agents
+- Dependency chain with parallel QA and rework loop
+
+### Parallel squads (2 squads running simultaneously)
+- Bookmarks API (2/2, $0.83) + Notes CLI (6/6 with 2 rework cycles, $1.17)
+- Both ran concurrently from the same pi session
+- Combined: 12 tasks, 101 turns, $2.00
 
 ## Requirements
 
-- [pi](https://github.com/badlogic/pi-mono) coding agent
+- [pi](https://github.com/badlogic/pi-mono) coding agent (v0.63.0+, recommended v0.64.0+)
 - An API key configured in pi (Anthropic, OpenRouter, etc.)
 - Node.js 18+
 

package/package.json

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

package/src/agent-pool.ts

@@ -11,6 +11,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentDef, AgentActivity, Task, TaskMessage } from "./types.js";
 import { buildAgentSystemPrompt, type ProtocolBuildOptions } from "./protocol.js";
+import { debug, logError } from "./logger.js";
 
 // ============================================================================
 // Types
@@ -165,6 +166,7 @@ export class AgentPool {
 
 		// Spawn pi process — set env var to prevent recursive squad extension loading
 		const invocation = getPiInvocation(["--mode", "rpc", ...args]);
+		debug("squad-pool", `spawn ${agentDef.name}: ${invocation.command} ${invocation.args.slice(0, 3).join(" ")} ...`);
 		const proc = spawn(invocation.command, invocation.args, {
 			cwd,
 			stdio: ["pipe", "pipe", "pipe"],
@@ -199,6 +201,7 @@ export class AgentPool {
 		});
 
 		attachLineReader(proc.stdout!, (line) => {
+			stdoutLines++;
 			try {
 				const event = JSON.parse(line);
 				this.handleRpcEvent(agentProc, event);
@@ -208,7 +211,14 @@ export class AgentPool {
 		});
 
 		let agentEndEmitted = false;
-		proc.on("exit", (code) => {
+		let stdoutLines = 0;
+		proc.on("exit", (code, signal) => {
+			// Log diagnostic info for debugging spawn failures
+			if (code !== 0 && code !== null) {
+				logError("squad-pool", `${agentDef.name} exited: code=${code} signal=${signal} pid=${proc.pid} stdoutLines=${stdoutLines} stderr=${stderr.slice(0, 300) || "(empty)"}`);
+			}
+			// Clean up agents map so getRunningAgents() doesn't count dead processes
+			this.agents.delete(taskId);
 			// Only emit if we haven't already emitted via RPC agent_end event
 			if (!agentEndEmitted) {
 				agentEndEmitted = true;
@@ -368,7 +378,7 @@ export class AgentPool {
 			// Pi RPC mode emits agent_end when the agent loop finishes.
 			// The RPC process stays alive waiting for more commands,
 			// so we need to explicitly kill it and emit our own agent_end.
-			console.error(`[squad-pool] agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
+			debug("squad-pool", `agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
 			// Mark the guard to prevent double-emit from proc.on("exit")
 			const guardFn = (agent as any)._agentEndEmitted;
 			if (guardFn) guardFn();

package/src/index.ts

@@ -21,6 +21,7 @@ import { runPlanner } from "./planner.js";
 import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
 import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js";
 import * as store from "./store.js";
+import { debug, logError } from "./logger.js";
 
 // ============================================================================
 // State
@@ -166,15 +167,17 @@ export default function (pi: ExtensionAPI) {
 			),
 		}),
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			if (!squadEnabled) return { content: [{ type: "text" as const, text: "Squad is disabled. Use /squad enable to re-enable." }] };
 			if (!uiCtx) uiCtx = ctx;
 
+			// Check if the user cancelled before we start
+			if (signal?.aborted) return { content: [{ type: "text" as const, text: "Cancelled." }] };
+
 			// Multiple squads can run concurrently — no guard needed
 
 			const squadId = store.makeTaskId(params.goal);
 			if (store.squadExists(squadId)) {
-				// Append timestamp to make unique
 				const uniqueId = `${squadId}-${Date.now().toString(36)}`;
 				return await startSquad(uniqueId, params, ctx.cwd, squadSkillPaths, pi);
 			}
@@ -346,15 +349,14 @@ export default function (pi: ExtensionAPI) {
 						switch (event.type) {
 							case "squad_completed": {
 								const tasks = store.loadAllTasks(squadId);
-								const summary = tasks
-									.filter((t) => t.status === "done")
-									.map((t) => `- ${t.id} (${t.agent}): ${t.output?.slice(0, 150) || "done"}`)
-									.join("\n");
 								const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 								const s = schedulers.get(squadId); if (s) s.updateContext();
+								const overview = store.loadOverview(squadId);
 								pi.sendMessage({
 									customType: "squad-completed",
-									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}`,
+									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
+										(overview ? `## Squad Overview\n\n${overview}\n\n` : "") +
+										`Total cost: $${totalCost.toFixed(4)}`,
 									display: true,
 								});
 								schedulers.delete(squadId);
@@ -365,9 +367,12 @@ export default function (pi: ExtensionAPI) {
 								const tasks = store.loadAllTasks(squadId);
 								const failed = tasks.filter((t) => t.status === "failed");
 								const done = tasks.filter((t) => t.status === "done");
+								const overview = store.loadOverview(squadId);
 								pi.sendMessage({
 									customType: "squad-failed",
-									content: `[squad] Squad "${squadId}" has stalled. ${done.length}/${tasks.length} done, ${failed.length} failed.\nFailed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}`,
+									content: `[squad] Squad "${squadId}" has stalled. ${done.length}/${tasks.length} done, ${failed.length} failed.\n` +
+										`Failed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}` +
+										(overview ? `\n\n## Squad Overview\n\n${overview}` : ""),
 									display: true,
 								}, { triggerTurn: true });
 								forceWidgetUpdate();
@@ -387,7 +392,7 @@ export default function (pi: ExtensionAPI) {
 
 				const resumeSched = schedulers.get(squadId)!;
 				resumeSched.resume().catch((err) => {
-					console.error(`[squad] Resume error: ${(err as Error).message}`);
+					logError("squad", `Resume error: ${(err as Error).message}`);
 				});
 
 				const tasks = store.loadAllTasks(squadId);
@@ -438,7 +443,7 @@ export default function (pi: ExtensionAPI) {
 				case "resume_task": {
 					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }] };
 					activeScheduler.resumeTask(params.taskId).catch((err) => {
-						console.error(`[squad] Resume task error: ${(err as Error).message}`);
+						logError("squad", `Resume task error: ${(err as Error).message}`);
 					});
 					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed.` }] };
 				}
@@ -1211,6 +1216,31 @@ async function startSquad(
 
 	store.saveSquad(squad);
 
+	// Create initial OVERVIEW.md with squad goal, task plan, and design contract
+	const planLines = [
+		`# Squad: ${params.goal}`,
+		``,
+		`**Created:** ${squad.created}`,
+		`**Tasks:** ${plan.tasks.length}`,
+		``,
+		`## Task Plan`,
+		``,
+		...plan.tasks.map((t) => {
+			const deps = t.depends.length > 0 ? ` (after: ${t.depends.join(", ")})` : "";
+			return `- **${t.id}** → ${t.agent}: ${t.title}${deps}`;
+		}),
+		``,
+	];
+
+	// Extract design contract from task descriptions — API paths, schemas,
+	// ports, file conventions — so parallel agents share a single source of truth.
+	const contractLines = buildDesignContract(plan.tasks, params.goal);
+	if (contractLines.length > 0) {
+		planLines.push(...contractLines);
+	}
+
+	store.appendOverview(squadId, planLines.join("\n"));
+
 	// Create task files
 	for (const taskDef of plan.tasks) {
 		const task: Task = {
@@ -1256,12 +1286,8 @@ async function startSquad(
 		// Update widget on every scheduler event
 		forceWidgetUpdate();
 		switch (event.type) {
-			case "squad_completed": {
+				case "squad_completed": {
 				const tasks = store.loadAllTasks(squadId);
-				const summary = tasks
-					.filter((t) => t.status === "done")
-					.map((t) => `- ${t.id} (${t.agent}): ${t.output?.slice(0, 150) || "done"}`)
-					.join("\n");
 				const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 
 				// Final context update before clearing scheduler
@@ -1270,12 +1296,17 @@ async function startSquad(
 					completedSched.updateContext();
 				}
 
-				// Use sendMessage with display:true — visible to user but doesn't
-				// pollute LLM message history. No triggerTurn needed for completions.
+				// Load the full overview document — contains the narrative of
+				// each task's output, decisions, issues, and files modified.
+				const overview = store.loadOverview(squadId);
+
+				// Send into LLM context (not display-only) so the main agent
+				// knows exactly what happened. No triggerTurn — user decides
+				// what to do next.
 				pi.sendMessage({
 					customType: "squad-completed",
 					content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
-						`Summary:\n${summary}\n\n` +
+						(overview ? `## Squad Overview\n\n${overview}\n\n` : "") +
 						`Total cost: $${totalCost.toFixed(4)}`,
 					display: true,
 				});
@@ -1290,14 +1321,14 @@ async function startSquad(
 				const tasks = store.loadAllTasks(squadId);
 				const failed = tasks.filter((t) => t.status === "failed");
 				const done = tasks.filter((t) => t.status === "done");
+				const overview = store.loadOverview(squadId);
 
-				// Squad failed — notify user. Use triggerTurn so the agent can
-				// suggest next steps (retry, modify, cancel).
 				pi.sendMessage({
 					customType: "squad-failed",
 					content: `[squad] Squad "${squadId}" has stalled. ` +
 						`${done.length}/${tasks.length} tasks done, ${failed.length} failed.\n` +
 						`Failed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}\n` +
+						(overview ? `\n## Squad Overview\n\n${overview}\n\n` : "\n") +
 						`Use squad_status for details or squad_modify to adjust.`,
 					display: true,
 				}, { triggerTurn: true });
@@ -1325,7 +1356,7 @@ async function startSquad(
 	// We must return immediately so the main agent's turn completes
 	// and the user regains interactive control.
 	scheduler.start().catch((err) => {
-		console.error(`[squad] Scheduler start error: ${(err as Error).message}`);
+		logError("squad", `Scheduler start error: ${(err as Error).message}`);
 	});
 
 	// Build response
@@ -1358,3 +1389,99 @@ function getSquadSkillPaths(skillsDir: string): string[] {
 		.map((d) => path.join(skillsDir, d.name))
 		.filter((dir) => fs.existsSync(path.join(dir, "SKILL.md")));
 }
+
+/**
+ * Extract a design contract from task descriptions.
+ *
+ * Scans all tasks for API paths, ports, file names, data schemas, and
+ * shared conventions. Produces a "## Design Contract" section in the
+ * OVERVIEW.md so that ALL agents (including parallel ones) share a
+ * single source of truth before they start working.
+ */
+function buildDesignContract(
+	tasks: Array<{ id: string; title: string; description: string; agent: string; depends: string[] }>,
+	goal: string,
+): string[] {
+	const lines: string[] = [];
+
+	// Collect API routes mentioned in any task description
+	const apiRoutes: string[] = [];
+	const ports: string[] = [];
+	const files: string[] = [];
+	const schemas: string[] = [];
+
+	const allText = tasks.map((t) => `${t.title}\n${t.description}`).join("\n") + "\n" + goal;
+
+	// Extract API paths like GET /foo, POST /bar/:id
+	const routePattern = /\b(GET|POST|PUT|PATCH|DELETE|HEAD)\s+(\/[\w\/:]+)/gi;
+	for (const match of allText.matchAll(routePattern)) {
+		const route = `${match[1].toUpperCase()} ${match[2]}`;
+		if (!apiRoutes.includes(route)) apiRoutes.push(route);
+	}
+
+	// Extract port numbers
+	const portPattern = /\b(?:port|PORT|Port)\s*[=:]?\s*(\d{4,5})\b/gi;
+	for (const match of allText.matchAll(portPattern)) {
+		if (!ports.includes(match[1])) ports.push(match[1]);
+	}
+
+	// Extract key file names mentioned (e.g., server.js, index.html)
+	const filePattern = /\b([\w-]+\.(js|ts|json|html|css|sh|mjs|cjs))\b/gi;
+	for (const match of allText.matchAll(filePattern)) {
+		const f = match[1];
+		if (!files.includes(f) && !['package.json'].includes(f)) files.push(f);
+	}
+
+	// Extract data schemas like {field, field, field}
+	const schemaPattern = /\{([a-zA-Z_][\w,\s\[\]?]+)\}/g;
+	for (const match of allText.matchAll(schemaPattern)) {
+		const fields = match[1].trim();
+		if (fields.includes(',') && fields.length > 5 && fields.length < 200) {
+			if (!schemas.includes(fields)) schemas.push(fields);
+		}
+	}
+
+	// Only emit a contract section if we found shared design elements
+	if (apiRoutes.length === 0 && ports.length === 0 && schemas.length === 0) {
+		return [];
+	}
+
+	lines.push(`## Design Contract`);
+	lines.push(``);
+	lines.push(`> **All agents MUST follow these specifications.** Do not invent`);
+	lines.push(`> alternative paths, ports, or schemas. If you need to deviate,`);
+	lines.push(`> document the reason in your output.`);
+	lines.push(``);
+
+	if (ports.length > 0) {
+		lines.push(`### Server`);
+		lines.push(`- Port: **${ports.join(", ")}**`);
+		lines.push(``);
+	}
+
+	if (apiRoutes.length > 0) {
+		lines.push(`### API Endpoints`);
+		for (const r of apiRoutes) {
+			lines.push(`- \`${r}\``);
+		}
+		lines.push(``);
+	}
+
+	if (schemas.length > 0) {
+		lines.push(`### Data Schemas`);
+		for (const s of schemas) {
+			lines.push(`- \`{ ${s} }\``);
+		}
+		lines.push(``);
+	}
+
+	if (files.length > 0) {
+		lines.push(`### Key Files`);
+		for (const f of files) {
+			lines.push(`- \`${f}\``);
+		}
+		lines.push(``);
+	}
+
+	return lines;
+}

package/src/logger.ts

@@ -0,0 +1,68 @@
+/**
+ * logger.ts — Squad debug logging to file, NOT stderr.
+ *
+ * Writing to stderr (console.error) corrupts the TUI because it bypasses
+ * the TUI's differential renderer. All squad debug output goes to a log
+ * file instead: ~/.pi/squad/debug.log
+ *
+ * Set PI_SQUAD_DEBUG=1 to enable logging. Without it, logs are silent.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const LOG_DIR = path.join(os.homedir(), ".pi", "squad");
+const LOG_FILE = path.join(LOG_DIR, "debug.log");
+const DEBUG = process.env.PI_SQUAD_DEBUG === "1";
+
+/** Max log file size before rotation (2MB) */
+const MAX_LOG_SIZE = 2 * 1024 * 1024;
+
+let rotationChecked = false;
+
+function ensureLogDir(): void {
+	try {
+		fs.mkdirSync(LOG_DIR, { recursive: true });
+	} catch { /* ignore */ }
+}
+
+function rotateIfNeeded(): void {
+	if (rotationChecked) return;
+	rotationChecked = true;
+	try {
+		const stat = fs.statSync(LOG_FILE);
+		if (stat.size > MAX_LOG_SIZE) {
+			const backup = LOG_FILE + ".old";
+			try { fs.unlinkSync(backup); } catch { /* ignore */ }
+			fs.renameSync(LOG_FILE, backup);
+		}
+	} catch { /* file doesn't exist yet, fine */ }
+}
+
+/**
+ * Log a debug message to ~/.pi/squad/debug.log.
+ * Only writes when PI_SQUAD_DEBUG=1 is set. Silent otherwise.
+ */
+export function debug(prefix: string, ...args: unknown[]): void {
+	if (!DEBUG) return;
+	write(prefix, ...args);
+}
+
+/**
+ * Always log to ~/.pi/squad/debug.log regardless of PI_SQUAD_DEBUG.
+ * Use for errors and critical events that should never be lost.
+ */
+export function logError(prefix: string, ...args: unknown[]): void {
+	write(prefix, ...args);
+}
+
+function write(prefix: string, ...args: unknown[]): void {
+	try {
+		ensureLogDir();
+		rotateIfNeeded();
+		const ts = new Date().toISOString();
+		const msg = args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+		fs.appendFileSync(LOG_FILE, `[${ts}] [${prefix}] ${msg}\n`);
+	} catch { /* never throw from logging */ }
+}

package/src/panel/message-view.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import type { TaskMessage } from "../types.js";
 import * as store from "../store.js";
 
@@ -159,11 +159,12 @@ export class MessageView {
 				case "text":
 				case "message":
 				case "reply": {
-					// Split text, strip any \r, ensure no embedded newlines survive
 					const textLines = msg.text.replace(/\r/g, "").split("\n");
 					const show = textLines.slice(0, MAX_TEXT_LINES);
 					for (const tl of show) {
-						lines.push(fit(`   ${tl}`, width));
+						// Wrap long lines instead of truncating
+						const wrapped = wrap(`   ${tl}`, width, "      ");
+						lines.push(...wrapped);
 					}
 					if (textLines.length > MAX_TEXT_LINES) {
 						lines.push(fit(`   ${th.fg("dim", `... +${textLines.length - MAX_TEXT_LINES} lines`)}`, width));
@@ -171,10 +172,10 @@ export class MessageView {
 					break;
 				}
 				case "done":
-					lines.push(fit(`   ${th.fg("success", "✓ " + msg.text)}`, width));
+					lines.push(...wrap(`   ✓ ${msg.text}`, width, "      "));
 					break;
 				case "error":
-					lines.push(fit(`   ${th.fg("error", "✗ " + msg.text)}`, width));
+					lines.push(...wrap(`   ✗ ${msg.text}`, width, "      "));
 					break;
 				case "status":
 					lines.push(fit(`   ${th.fg("dim", msg.text)}`, width));
@@ -186,12 +187,54 @@ export class MessageView {
 	}
 }
 
+/** Truncate a single line (for headers, tool calls, status — not text content) */
 function fit(line: string, width: number): string {
-	// Strip any newlines that would create extra terminal lines and break layout math
 	const clean = line.replace(/[\n\r]/g, " ");
 	return truncateToWidth(clean, width, "…");
 }
 
+/** Wrap a text line into multiple lines that fit within width.
+ *  Uses ANSI-aware visibleWidth for correct wrapping with styled text.
+ *  Returns array of lines, each guaranteed to fit within width. */
+function wrap(line: string, width: number, indent: string = "   "): string[] {
+	const clean = line.replace(/[\n\r]/g, " ");
+	// Fast path: already fits
+	if (visibleWidth(clean) <= width) return [clean];
+
+	// For styled text, we can't word-wrap by chars (ANSI codes break).
+	// Instead, strip to plain text, wrap that, then truncate styled lines.
+	const plain = stripAnsi(clean);
+	const indentW = visibleWidth(indent);
+	const firstW = width;
+	const contW = width - indentW;
+
+	const results: string[] = [];
+	let remaining = plain;
+	let isFirst = true;
+
+	while (remaining.length > 0) {
+		const maxW = isFirst ? firstW : contW;
+		if (remaining.length <= maxW) {
+			results.push(isFirst ? remaining : indent + remaining);
+			break;
+		}
+		// Find word break point
+		let breakAt = remaining.lastIndexOf(" ", maxW);
+		if (breakAt <= maxW * 0.3) breakAt = maxW; // No good break, hard cut
+		const chunk = remaining.slice(0, breakAt);
+		results.push(isFirst ? chunk : indent + chunk);
+		remaining = remaining.slice(breakAt).trimStart();
+		isFirst = false;
+	}
+
+	// Truncate each to be safe (handles edge cases)
+	return results.map(r => truncateToWidth(r, width, ""));
+}
+
+function stripAnsi(str: string): string {
+	return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
 function pad(lines: string[], max: number): string[] {
 	while (lines.length < max) lines.push("");
 	return lines.slice(0, max);

package/src/panel/squad-widget.ts

@@ -1,15 +1,17 @@
 /**
- * squad-widget.ts — Simple string[] widget for squad status.
+ * squad-widget.ts — Compact widget for squad status above the editor.
  *
- * Uses the simple setWidget(key, string[]) API which pi-tui handles
- * reliably. Component-based widgets with variable height cause TUI
- * layout corruption.
+ * Uses a component factory for setWidget so it can access terminal width
+ * and truncate every line to prevent Text wrapping. Without truncation,
+ * long lines wrap inside the Text component, causing unpredictable
+ * widget height changes that corrupt the TUI diff renderer.
  *
  * Updates are pushed by calling requestUpdate() which rebuilds the
- * string[] and calls setWidget() again.
+ * lines and calls setWidget() again.
  */
 
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Component, TUI } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { TaskStatus } from "../types.js";
 import * as store from "../store.js";
@@ -41,7 +43,10 @@ export interface SquadWidgetState {
 
 /**
  * Set up the squad widget. Returns control functions.
- * Uses simple string[] setWidget — no component factory.
+ *
+ * Uses a component factory so we can access TUI.terminal.columns and
+ * truncate every line, preventing Text word-wrapping that would cause
+ * unpredictable widget height changes.
  */
 export function setupSquadWidget(
 	ctx: { ui: { setWidget: Function; setStatus: Function; [key: string]: any }; hasUI?: boolean },
@@ -56,22 +61,16 @@ export function setupSquadWidget(
 	let renderTimer: ReturnType<typeof setTimeout> | null = null;
 	/** Cache key to skip redundant setWidget calls */
 	let lastCacheKey = "";
+	/** Last built lines — the factory re-uses these on each TUI render */
+	let currentLines: string[] = [];
 
-	function render(): void {
-		if (!state.enabled || !state.squadId) {
-			ctx.ui.setWidget("squad-tasks", undefined);
-			ctx.ui.setStatus("squad", undefined);
-			return;
-		}
+	function buildLines(): { lines: string[]; cacheKey: string; statusText: string } | null {
+		if (!state.enabled || !state.squadId) return null;
 
 		const th = ctx.ui.theme;
 		const tasks = store.loadAllTasks(state.squadId);
 		const squad = store.loadSquad(state.squadId);
-		if (!squad || tasks.length === 0) {
-			ctx.ui.setWidget("squad-tasks", undefined);
-			ctx.ui.setStatus("squad", undefined);
-			return;
-		}
+		if (!squad || tasks.length === 0) return null;
 
 		const lines: string[] = [];
 		const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -136,19 +135,77 @@ export function setupSquadWidget(
 			lines.push(`  ${th.fg("dim", `  +${tasks.length - maxVisible} more · ^q detail`)}`);
 		}
 
-		// Skip if nothing changed (avoid redundant setWidget calls that cause flicker)
 		const cacheKey = `${squad.status}:${tasks.map(t => `${t.id}=${t.status}:${t.usage.turns}`).join(",")}`;
-		if (cacheKey === lastCacheKey) return;
-		lastCacheKey = cacheKey;
 
-		ctx.ui.setWidget("squad-tasks", lines);
-
-		// Update status bar
 		const statusText = squad.status === "done"
 			? th.fg("success", `✓ squad ${doneCount}/${tasks.length}`)
 			: squad.status === "failed"
 			? th.fg("error", `✗ squad ${doneCount}/${tasks.length}`)
 			: th.fg("accent", `⏳ squad ${doneCount}/${tasks.length} $${totalCost.toFixed(2)}`);
+
+		return { lines, cacheKey, statusText };
+	}
+
+	/**
+	 * Widget component that renders pre-built lines truncated to terminal width.
+	 * Each line is guaranteed to fit on exactly one terminal row — no wrapping.
+	 * This keeps the widget height deterministic (= lines.length) so the TUI
+	 * diff renderer never sees unexpected height changes.
+	 */
+	class SquadWidgetComponent implements Component {
+		lines: string[] = [];
+
+		invalidate(): void { /* stateless — lines are rebuilt externally */ }
+
+		render(width: number): string[] {
+			// Truncate every line to terminal width so Text wrapping cannot
+			// add extra rows. One input line → exactly one output line.
+			return this.lines.map(line => {
+				const truncated = truncateToWidth(line, width);
+				// Pad to full width to prevent leftover characters from previous renders
+				const vw = visibleWidth(truncated);
+				const pad = Math.max(0, width - vw);
+				return truncated + " ".repeat(pad);
+			});
+		}
+	}
+
+	/** Persistent widget component instance — survives across setWidget calls */
+	let widgetComponent: SquadWidgetComponent | null = null;
+	let widgetInstalled = false;
+
+	function render(): void {
+		const result = buildLines();
+		if (!result) {
+			ctx.ui.setWidget("squad-tasks", undefined);
+			ctx.ui.setStatus("squad", undefined);
+			widgetInstalled = false;
+			return;
+		}
+
+		const { lines, cacheKey, statusText } = result;
+
+		// Skip if nothing changed (avoid redundant setWidget calls)
+		if (cacheKey === lastCacheKey) return;
+		lastCacheKey = cacheKey;
+
+		currentLines = lines;
+
+		if (!widgetInstalled) {
+			// Install the component factory once. On subsequent updates we just
+			// mutate widgetComponent.lines and requestRender — no setWidget churn.
+			widgetComponent = new SquadWidgetComponent();
+			widgetComponent.lines = lines;
+
+			const comp = widgetComponent;
+			ctx.ui.setWidget("squad-tasks", (_tui: TUI, _theme: Theme) => comp);
+			widgetInstalled = true;
+		} else if (widgetComponent) {
+			// Update lines in-place — the next TUI render picks them up.
+			// No setWidget call needed, avoiding component tree rebuild.
+			widgetComponent.lines = lines;
+		}
+
 		ctx.ui.setStatus("squad", statusText);
 	}
 

package/src/planner.ts

@@ -33,6 +33,14 @@ export async function runPlanner(options: PlannerOptions): Promise<PlannerOutput
 	const plannerDef = loadAgentDef("planner", cwd);
 	const allAgents = loadAllAgentDefs(cwd).filter((a) => a.name !== "planner" && !a.disabled);
 
+	if (allAgents.length === 0) {
+		throw new Error(
+			"No squad agents found. Agent definitions should be in ~/.pi/squad/agents/. " +
+			"This usually means the extension failed to load on first run (check /reload for errors). " +
+			"Try: /reload, then run the squad command again."
+		);
+	}
+
 	const agentList = allAgents
 		.map((a) => `- **${a.name}** (${a.role}): ${a.description} [tags: ${a.tags.join(", ")}]`)
 		.join("\n");
@@ -250,6 +258,13 @@ Respond with a JSON object (and nothing else outside the JSON):
 - 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
+- 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

@@ -11,7 +11,7 @@
  */
 
 import type { AgentDef, KnowledgeEntry, Squad, Task, TaskMessage } from "./types.js";
-import { loadAllKnowledge, loadAllTasks, loadMessages } from "./store.js";
+import { loadAllKnowledge, loadAllTasks, loadMessages, loadOverview } from "./store.js";
 
 // ============================================================================
 // Squad Protocol (injected into every agent)
@@ -54,7 +54,9 @@ The squad system will detect this and route help.
 ## Rules
 - Stay focused on YOUR task — don't do work assigned to other agents
 - Read the dependency outputs below — don't redo completed work
+- **Follow the Design Contract in the Squad Progress Document** — use the exact API paths, ports, schemas, and file names specified. Do NOT invent alternatives
 - Check the modified files list — coordinate before editing shared files
+- When creating APIs, clearly document all endpoints, request/response shapes, and status codes in your completion output
 - Ask for help if stuck — don't spin for more than a few minutes
 - Verify your work before claiming done
 `;
@@ -114,6 +116,20 @@ ${sections.join("\n---\n\n")}
 `;
 }
 
+// ============================================================================
+// Squad Progress Overview
+// ============================================================================
+
+export function buildOverviewSection(squadId: string): string {
+	const content = loadOverview(squadId);
+	if (!content.trim()) return "";
+
+	return `# Squad Progress Document
+
+${content.trim()}
+`;
+}
+
 // ============================================================================
 // Sibling Awareness
 // ============================================================================
@@ -293,6 +309,7 @@ export function buildAgentSystemPrompt(options: ProtocolBuildOptions): string {
 		buildTaskSection(task),
 		buildReworkContext(task, squadId),
 		buildChainContext(task, allTasks, squadId),
+		buildOverviewSection(squadId),
 		buildSiblingAwareness(task, allTasks, modifiedFiles),
 		buildKnowledgeSection(squadId),
 		buildQueuedMessages(queuedMessages),

package/src/scheduler.ts

@@ -14,6 +14,7 @@ import { AgentPool, type AgentEvent } from "./agent-pool.js";
 import { Monitor } from "./monitor.js";
 import { Router } from "./router.js";
 import * as store from "./store.js";
+import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
 
 // ============================================================================
@@ -55,6 +56,8 @@ export class Scheduler {
 	private listeners: SchedulerEventListener[] = [];
 	private skillPaths: string[] = [];
 	private running = false;
+	/** Track spawn retries to allow one retry per task */
+	private spawnRetries = new Set<string>();
 
 	/** Get the project cwd for this squad (from squad.json) */
 	getProjectCwd(): string | undefined {
@@ -181,13 +184,13 @@ export class Scheduler {
 	/** Find and spawn ready tasks up to concurrency limit */
 	private async scheduleReadyTasks(): Promise<void> {
 		if (!this.running) {
-			console.error("[squad-scheduler] scheduleReadyTasks: not running, skipping");
+			debug("squad-scheduler", "scheduleReadyTasks: not running, skipping");
 			return;
 		}
 
 		const squad = store.loadSquad(this.squadId);
 		if (!squad || squad.status !== "running") {
-			console.error(`[squad-scheduler] scheduleReadyTasks: squad status=${squad?.status}, skipping`);
+			debug("squad-scheduler", `scheduleReadyTasks: squad status=${squad?.status}, skipping`);
 			return;
 		}
 
@@ -195,22 +198,25 @@ export class Scheduler {
 		const runningCount = this.pool.getRunningAgents().length;
 		const available = squad.config.maxConcurrency - runningCount;
 
-		console.error(`[squad-scheduler] scheduleReadyTasks: ${tasks.length} tasks, ${runningCount} running, ${available} slots`);
+		debug("squad-scheduler", `scheduleReadyTasks: ${tasks.length} tasks, ${runningCount} running, ${available} slots`);
 
 		if (available <= 0) {
-			console.error("[squad-scheduler] scheduleReadyTasks: no available slots");
+			debug("squad-scheduler", "scheduleReadyTasks: no available slots");
 			return;
 		}
 
 		const ready = this.getReadyTasks(tasks);
-		console.error(`[squad-scheduler] scheduleReadyTasks: ${ready.length} ready tasks: ${ready.map(t => t.id).join(", ")}`);
+		debug("squad-scheduler", `scheduleReadyTasks: ${ready.length} ready tasks: ${ready.map(t => t.id).join(", ")}`);
 		const toSpawn = ready.slice(0, available);
 
 		for (const task of toSpawn) {
 			try {
 				await this.spawnAgentForTask(task, squad);
 			} catch (error) {
-				console.error(`[squad-scheduler] Failed to spawn ${task.id}: ${(error as Error).message}`);
+				logError("squad-scheduler", `Failed to spawn ${task.id}: ${(error as Error).message}`);
+				// MUST fail the task — otherwise it stays in_progress forever
+				// with no process (zombie state)
+				this.handleTaskFailed(task.id, `Spawn failed: ${(error as Error).message}`);
 			}
 		}
 
@@ -381,8 +387,29 @@ export class Scheduler {
 				if (exitCode === 0 || hadMeaningfulWork) {
 					this.handleTaskCompleted(event.taskId).then(() => this.updateContext());
 				} else {
-					const stderr = event.data?.stderr || "";
-					this.handleTaskFailed(event.taskId, `Agent exited with code ${exitCode}. ${stderr.slice(0, 500)}`);
+					// Agent died with no work done — retry once before failing.
+					// Transient failures (resource pressure, startup race) are common
+					// when multiple agents spawn simultaneously.
+					const retryKey = `spawn-retry:${event.taskId}`;
+					if (!this.spawnRetries.has(retryKey)) {
+						this.spawnRetries.add(retryKey);
+						const stderr = event.data?.stderr || "";
+						logError("squad-scheduler", `Agent ${event.agentName} died instantly (code ${exitCode}). Retrying in 2s... stderr: ${stderr.slice(0, 200)}`);
+						store.updateTaskStatus(this.squadId, event.taskId, "pending");
+						store.appendMessage(this.squadId, event.taskId, {
+							ts: store.now(),
+							from: "system",
+							type: "status",
+							text: `Agent crashed on startup (code ${exitCode}). Retrying...`,
+						});
+						// Delay retry to let resources settle
+						setTimeout(() => {
+							if (this.running) this.scheduleReadyTasks();
+						}, 2000);
+					} else {
+						const stderr = event.data?.stderr || "";
+						this.handleTaskFailed(event.taskId, `Agent exited with code ${exitCode} (retry exhausted). ${stderr.slice(0, 500)}`);
+					}
 					this.updateContext();
 				}
 				// Skip the updateContext() below — handled in the branches above
@@ -430,6 +457,10 @@ export class Scheduler {
 			text: "Task completed",
 		});
 
+		// Reload task after status update so overview has output, completed time, etc.
+		const updatedTask = store.loadTask(this.squadId, taskId) || task;
+		this.appendTaskOverview(updatedTask, taskId, messages);
+
 		this.emit({
 			type: "task_completed",
 			squadId: this.squadId,
@@ -444,7 +475,7 @@ export class Scheduler {
 
 		if (!reworkCreated) {
 			// Normal flow: auto-unblock dependents
-			console.error(`[squad-scheduler] handleTaskCompleted: ${taskId} done, auto-unblocking dependents`);
+			debug("squad-scheduler", `handleTaskCompleted: ${taskId} done, auto-unblocking dependents`);
 			this.autoUnblock(taskId);
 
 			// If this is a passing retest, also unblock dependents of the ORIGINAL
@@ -459,19 +490,19 @@ export class Scheduler {
 					rootId = root.retryOf;
 					root = allTasks.find((t) => t.id === rootId);
 				}
-				console.error(`[squad-scheduler] Retest passed — also unblocking dependents of original: ${rootId}`);
+				debug("squad-scheduler", `Retest passed — also unblocking dependents of original: ${rootId}`);
 				this.autoUnblock(rootId);
 			}
 		}
 
 		// Schedule next ready tasks (may spawn new agents)
-		console.error(`[squad-scheduler] handleTaskCompleted: scheduling next ready tasks`);
+		debug("squad-scheduler", `handleTaskCompleted: scheduling next ready tasks`);
 		await this.scheduleReadyTasks();
 
 		// Re-check squad completion with fresh data AFTER scheduling
 		const freshTasks = store.loadAllTasks(this.squadId);
 		const freshSquad = store.loadSquad(this.squadId);
-		console.error(`[squad-scheduler] handleTaskCompleted: final check — tasks: ${freshTasks.map(t => `${t.id}:${t.status}`).join(", ")}`);
+		debug("squad-scheduler", `handleTaskCompleted: final check — tasks: ${freshTasks.map(t => `${t.id}:${t.status}`).join(", ")}`);
 		if (freshSquad) {
 			this.checkSquadCompletion(freshTasks, freshSquad);
 		}
@@ -594,7 +625,7 @@ export class Scheduler {
 			const originalId = implTask.retryOf || implTask.id;
 
 			if (retryCount >= squad.config.maxRetries) {
-				console.error(`[squad-scheduler] Retry limit reached for ${originalId} (${retryCount}/${squad.config.maxRetries})`);
+				debug("squad-scheduler", `Retry limit reached for ${originalId} (${retryCount}/${squad.config.maxRetries})`);
 				this.emit({
 					type: "escalation",
 					squadId: this.squadId,
@@ -663,7 +694,7 @@ export class Scheduler {
 				message: `QA found issues in ${implTask.id}. Rework attempt ${fixN}.`,
 			});
 
-			console.error(`[squad-scheduler] Rework: ${reworkId} (${implTask.agent}) + retest ${retestId} (${task.agent})`);
+			debug("squad-scheduler", `Rework: ${reworkId} (${implTask.agent}) + retest ${retestId} (${task.agent})`);
 			createdAny = true;
 		}
 
@@ -905,6 +936,89 @@ export class Scheduler {
 			.map((p: any) => p.text);
 		return textParts.length > 0 ? textParts.join("\n") : null;
 	}
+
+	// =========================================================================
+	// Overview Document — append task summary after completion
+	// =========================================================================
+
+	/**
+	 * Build a concise markdown summary of a completed task and append it
+	 * to the squad's OVERVIEW.md. This gives subsequent agents a narrative
+	 * understanding of what was accomplished, issues hit, and decisions made.
+	 */
+	private appendTaskOverview(
+		task: Task,
+		taskId: string,
+		messages: import("./types.js").TaskMessage[],
+	): void {
+		try {
+			const lines: string[] = [];
+
+			// Header
+			lines.push(`## ${task.id}: ${task.title}`);
+			lines.push(``);
+			lines.push(`**Agent:** ${task.agent} | **Status:** ${task.status}`);
+			if (task.started && task.completed) {
+				const dur = new Date(task.completed).getTime() - new Date(task.started).getTime();
+				lines.push(`**Duration:** ${formatElapsed(dur)}`);
+			}
+			lines.push(``);
+
+			// Output
+			if (task.output) {
+				lines.push(`### Output`);
+				lines.push(task.output.slice(0, 800));
+				if (task.output.length > 800) lines.push(`... (truncated)`);
+				lines.push(``);
+			}
+
+			// Issues / errors encountered
+			const errors = messages.filter((m) => m.type === "error" && m.from !== "system");
+			if (errors.length > 0) {
+				lines.push(`### Issues Encountered`);
+				for (const err of errors.slice(-5)) {
+					lines.push(`- ${err.text.split("\n")[0].slice(0, 200)}`);
+				}
+				lines.push(``);
+			}
+
+			// Decisions — scan agent text for decision-like language
+			const decisionPatterns = /\b(decided|chose|approach|instead of|trade-?off|opted|going with|switched to|using .+ because)\b/i;
+			const agentTexts = messages.filter((m) => m.from === task.agent && m.type === "text");
+			const decisions: string[] = [];
+			for (const msg of agentTexts) {
+				for (const line of msg.text.split("\n")) {
+					if (decisionPatterns.test(line) && line.trim().length > 10) {
+						decisions.push(line.trim().slice(0, 200));
+					}
+				}
+			}
+			if (decisions.length > 0) {
+				lines.push(`### Decisions`);
+				for (const d of decisions.slice(-5)) {
+					lines.push(`- ${d}`);
+				}
+				lines.push(``);
+			}
+
+			// Files modified
+			const activity = this.pool.getActivity(taskId);
+			if (activity && activity.modifiedFiles.size > 0) {
+				lines.push(`### Files Modified`);
+				for (const f of Array.from(activity.modifiedFiles).slice(0, 15)) {
+					lines.push(`- ${f}`);
+				}
+				if (activity.modifiedFiles.size > 15) {
+					lines.push(`- ... and ${activity.modifiedFiles.size - 15} more`);
+				}
+				lines.push(``);
+			}
+
+			store.appendOverview(this.squadId, lines.join("\n"));
+		} catch (err) {
+			logError("squad-scheduler", `Failed to append overview for ${taskId}: ${(err as Error).message}`);
+		}
+	}
 }
 
 function formatElapsed(ms: number): string {

package/src/store.ts

@@ -405,6 +405,32 @@ export function loadAllKnowledge(squadId: string): KnowledgeEntry[] {
 	].sort((a, b) => a.ts.localeCompare(b.ts));
 }
 
+// ============================================================================
+// Overview Document (shared squad summary)
+// ============================================================================
+
+export function getOverviewPath(squadId: string): string {
+	return path.join(getSquadDir(squadId), "OVERVIEW.md");
+}
+
+export function loadOverview(squadId: string): string {
+	try {
+		return fs.readFileSync(getOverviewPath(squadId), "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+export function appendOverview(squadId: string, section: string): void {
+	const filePath = getOverviewPath(squadId);
+	ensureDir(path.dirname(filePath));
+	const existing = loadOverview(squadId);
+	const content = existing
+		? existing.trimEnd() + "\n\n---\n\n" + section.trim() + "\n"
+		: section.trim() + "\n";
+	fs.writeFileSync(filePath, content, "utf-8");
+}
+
 // ============================================================================
 // Rework Helpers
 // ============================================================================