pi-squad 0.16.3 → 0.16.5

package/README.md

@@ -52,8 +52,10 @@ Squad agents—including QA/reviewer agents—produce candidate work and evidenc
 - Persisted status becomes `review`, never directly `done`.
 - A persistent `<squad_review_required>` system reminder tells main Pi to re-read the original conversation contract, inspect the actual diff/source, rerun verification independently, and run integration/E2E where applicable.
 - Main Pi must call `squad_review` with requirement-by-requirement contract checks, diff review, actual command/result evidence, integration/E2E evidence, and issues.
-- Only `pass` or `pass_with_issues` changes the squad to `done`; `fail` leaves it review-blocked for fixes and re-review.
-- Pending review survives Pi restarts and is restored on the next session.
+- Only `pass` or `pass_with_issues` changes the squad to `done`; `fail` leaves it review-blocked and cannot be overwritten by another verdict.
+- Failed review is reworked in the **same authoritative squad**: use `squad_modify` with that `squadId` and `add_task` or `resume_task` (or `resume` when interrupted work exists). These operations reconstruct the scheduler after restart. `/squad resume <squad-id>` provides the same resume path.
+- When rework begins, the failed attempt moves to `reviewHistory`, the squad returns to `running`, and its evidence remains auditable. After every rework task settles, a fresh pending review becomes the active gate and `squad_review` is required again.
+- Pending and failed review gates survive Pi restarts and are restored on the next session. A separate squad never links to, remediates, or accepts the failed gate.
 
 The completion report is explicitly labeled **untrusted and not yet accepted**. Main Pi must never merely relay it or ask whether verification should be run.
 
@@ -139,7 +141,7 @@ Bundled agent definitions are copied to `~/.pi/squad/agents/` on first run. Edit
 
 **@mention routing**: Agents write `@frontend what token format?` in their output. The router delivers it in real-time via RPC `steer()`.
 
-**Main-session request/reply**: `squad_message` resolves an agent name to its live task, durably records the full request, and writes the documented JSONL RPC command `{"type":"steer","message":"..."}` to the child. By default (`expectReply: true`), the next substantive agent response is durably marked as the reply, pushed into the main Pi session, and wakes it via follow-up delivery; ordinary later activity remains panel-only. The pending reply marker survives scheduler reconstruction. Use `expectReply: false` for fire-and-forget steering. pi-squad waits for Pi's final `agent_settled` event before closing the child; low-level `agent_end` never kills queued continuations.
+**Main-session request/reply**: `squad_message` addresses one exact task ID. An agent name is accepted only as shorthand for exactly one currently live task, so two tasks assigned to the same role never share or steal messages. Requests are written first to the task's durable mailbox, then delivered with correlated Pi RPC. A completed task is reopened and resumed with `pi --session <its-original-session-file>`; only a task without a session binding receives a new session. This also works after scheduler/main-process reconstruction. By default (`expectReply: true`), the next substantive response is durably marked as the reply, pushed into main Pi, and wakes it; use `expectReply: false` for fire-and-forget steering. pi-squad waits for Pi's final `agent_settled` event before marking the task done or closing the child; low-level `agent_end` never kills queued continuations.
 
 ### Smart Planner
 
@@ -171,7 +173,7 @@ Shows live squad progress. Truncated to terminal width — no wrapping, determin
 
 ### Panel (Ctrl+Q)
 
-Full overlay with task list, live activity preview, and scrollable message view.
+Full overlay with task list, live activity preview, and scrollable message view. The view opens at the live tail but can scroll back through the complete durable history, including acknowledged and older orchestrator/human messages; multiline bodies are not shortened. Main-Pi requests are labeled `ORCHESTRATOR` and panel/user input is labeled `YOU`.
 
 | Key | Action |
 |---|---|
@@ -188,10 +190,11 @@ Full overlay with task list, live activity preview, and scrollable message view.
 | Command | Description |
 |---|---|
 | `/squad select` | Pick a squad to view |
+| `/squad resume [squad-id]` | Reconstruct and resume an exact paused/failed/failed-review squad |
 | `/squad list` | List project squads |
 | `/squad all` | List all squads |
 | `/squad agents` | Manage agent definitions |
-| `/squad msg [agent] text` | Send message to agent |
+| `/squad msg [task-id\|running-agent] text` | Message an exact task, or use an agent name only when it has one live task |
 | `/squad widget` | Toggle widget |
 | `/squad panel` | Toggle panel |
 | `/squad cancel` | Cancel running squad |
@@ -205,8 +208,8 @@ Full overlay with task list, live activity preview, and scrollable message view.
 |---|---|
 | `squad` | Start a squad with goal + optional tasks/config |
 | `squad_status` | Check progress, costs, task states |
-| `squad_message` | Send message to a running agent |
-| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads |
+| `squad_message` | Durably message an exact task; completed tasks reopen on their original session |
+| `squad_modify` | Add/cancel/complete/pause/resume tasks or squads; accepts `squadId` for exact same-squad failed-review rework |
 
 The main agent sees available agents in its system prompt and squad state when a squad is active.
 
@@ -245,7 +248,8 @@ squad({
 - **Cost**: the agent pays the entire conversation history as input tokens on every turn — use sparingly
 - **Context-window guard**: the fork is skipped automatically when the estimated session size exceeds 50% of the agent model's context window (agents on smaller-context models silently degrade to standard squad context; the skip is recorded in the task's message log and `debug.log`)
 - Requires the main session to have a session file (skipped under `--no-session`)
-- Forked child sessions are stored under `~/.pi/squad/<squad-id>/sessions/`, not in your project's session list
+- Each child session is stored under its task directory at `~/.pi/squad/<squad-id>/<task-id>/session/`, not in your project's session list
+- 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
 
 ### Custom Agents
@@ -298,14 +302,17 @@ Configure with `/squad advisor` (on/off, model, max calls per task, reasoning ef
 
 ### Meaningful Work Check
 
-Agents must complete at least 1 LLM turn AND make at least 1 tool call to be marked as "done". Agents that exit cleanly but did no work (rate limit, API error, model not found) are retried once, then failed — never silently marked successful.
+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.
 
 ### Session Resilience
 
-- In-progress tasks are **suspended** on session crash, **resumed** on next startup
-- Failure is never terminal: `resume` recovers failed squads (failed tasks reset to pending), `complete_task` marks recovered work done and schedules dependents, and a 60s reconcile loop re-derives scheduling from persisted state so out-of-band store edits can't strand ready tasks
-- Squads are fully reconstructable from JSON files on disk
-- Spawn failures are retried once with a 2-second delay
+- Every task owns one durable Pi session. New tasks create it under their task directory; stale, suspended, failed, or explicitly reopened tasks resume that same session rather than starting over. A pre-prompt retry may refresh Pi's provisional session ID only while the bound file is the same and its JSONL has not materialized; afterward both file and ID are immutable.
+- Legacy tasks without a session binding migrate on first reopen by creating a task-owned session and seeding its first prompt with the complete persisted multiline message history and prior task output—without truncation.
+- In-progress tasks are **suspended** on orderly shutdown; ordinary orphaned work is paused for explicit resume. If a scheduler itself is reconstructed, stale `in_progress` state is resumed by reconciliation. Independently, extension startup always reconstructs any project squad with pending mailbox entries—including `review` or already accepted `done` squads—and resumes delivery without another user action.
+- A durable message to a completed task clears its prior completion/review state, reopens the squad, keeps the task `in_progress` while its agent is live, and requires a fresh orchestrator review after the final `agent_settled`. Every transitive descendant is re-blocked and reruns in dependency order, so results derived from the reopened dependency cannot remain falsely complete.
+- Failure is never terminal: `resume` recovers failed squads (failed tasks reset to pending), `complete_task` marks recovered work done and schedules dependents, and a 60s reconcile loop re-derives scheduling from persisted state so out-of-band store edits can't strand ready tasks.
+- Mail is acknowledged only after Pi accepts the correlated RPC command. Pending and acknowledged entries remain task-addressed on disk, survive process restart, and remain visible in history. Queue and acknowledgement read/modify/write operations are serialized across processes so concurrent mutations cannot overwrite messages or delivery state.
+- Squads are fully reconstructable from JSON files on disk. Unexpected child exits are retried once after 2 seconds on the same bound task session.
 - All errors logged to `~/.pi/squad/debug.log` (always for errors, `PI_SQUAD_DEBUG=1` for verbose)
 
 ### Health Monitoring
@@ -331,8 +338,10 @@ All state in `~/.pi/squad/`. No database, no daemon. Writes are atomic. JSONL re
     ├── squad.json       — goal, status, config, cwd
     ├── context.json     — live state snapshot
     └── {task-id}/
-        ├── task.json    — status, output, usage, retryOf, qaFeedback
-        └── messages.jsonl  — conversation log
+        ├── task.json      — status, output, usage, immutable session binding, retry metadata
+        ├── messages.jsonl — append-only conversation history
+        ├── mailbox.json   — task-addressed inbound mail, including delivery acknowledgements
+        └── session/       — this task's durable Pi session JSONL
 ```
 
 ## Architecture

package/package.json

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

package/src/agent-pool.ts

@@ -6,10 +6,11 @@
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentDef, AgentActivity, Task, TaskMessage } from "./types.js";
+import type { AgentDef, AgentActivity, TaskSession } from "./types.js";
 import { buildAgentSystemPrompt, type ProtocolBuildOptions } from "./protocol.js";
 import { debug, logError } from "./logger.js";
 
@@ -22,8 +23,8 @@ export interface AgentProcess {
 	agentName: string;
 	process: ChildProcess;
 	activity: AgentActivity;
-	/** Queued messages for this agent (received while stopped, consumed on spawn) */
-	pendingMessages: TaskMessage[];
+	/** Durable Pi session owned by this task. */
+	session: TaskSession;
 	/** Abort controller for cleanup */
 	aborted: boolean;
 }
@@ -34,6 +35,7 @@ export type AgentEventType =
 	| "tool_execution_end"
 	| "turn_end"
 	| "agent_end"
+	| "agent_settled"
 	| "error";
 
 export interface AgentEvent {
@@ -77,7 +79,12 @@ function attachLineReader(
 export class AgentPool {
 	private agents = new Map<string, AgentProcess>();
 	private listeners: AgentEventListener[] = [];
-	private messageQueues = new Map<string, TaskMessage[]>();
+	private responseWaiters = new Map<string, {
+		process: ChildProcess;
+		resolve: (event: any) => void;
+		reject: (error: Error) => void;
+		timer: ReturnType<typeof setTimeout>;
+	}>();
 
 	/** Subscribe to agent events */
 	onEvent(listener: AgentEventListener): () => void {
@@ -124,20 +131,6 @@ export class AgentPool {
 			.map((a) => a.agentName);
 	}
 
-	/** Queue a message for an agent (delivered on next spawn or via steer if running) */
-	queueMessage(agentName: string, message: TaskMessage): void {
-		const queue = this.messageQueues.get(agentName) || [];
-		queue.push(message);
-		this.messageQueues.set(agentName, queue);
-	}
-
-	/** Consume queued messages for an agent */
-	consumeQueue(agentName: string): TaskMessage[] {
-		const queue = this.messageQueues.get(agentName) || [];
-		this.messageQueues.delete(agentName);
-		return queue;
-	}
-
 	/**
 	 * Spawn a pi process in RPC mode for a task.
 	 */
@@ -147,10 +140,14 @@ export class AgentPool {
 		protocolOptions: ProtocolBuildOptions;
 		cwd: string;
 		skillPaths: string[];
-		/** Fork the given session file so the agent inherits its conversation context */
+		/** Resume this task's already-bound durable Pi session. */
+		resumeSession?: TaskSession;
+		/** Create a new durable session here (new tasks only). */
+		sessionDir?: string;
+		/** Fork the given session file so a new task inherits main-session context. */
 		forkSession?: { file: string; sessionDir: string };
 	}): Promise<AgentProcess> {
-		const { taskId, agentDef, protocolOptions, cwd, skillPaths, forkSession } = options;
+		const { taskId, agentDef, protocolOptions, cwd, skillPaths, resumeSession, sessionDir, forkSession } = options;
 
 		// Kill existing process for this task if any
 		if (this.agents.has(taskId)) {
@@ -164,7 +161,7 @@ export class AgentPool {
 		fs.writeFileSync(promptFile, systemPrompt, "utf-8");
 
 		// Build pi CLI args
-		const args = buildPiArgs(agentDef, promptFile, skillPaths, forkSession);
+		const args = buildPiArgs(agentDef, promptFile, skillPaths, { resumeSession, sessionDir, forkSession });
 
 		// Spawn pi process — set env var to prevent recursive squad extension loading
 		const invocation = getPiInvocation(["--mode", "rpc", ...args]);
@@ -190,7 +187,8 @@ export class AgentPool {
 			agentName: agentDef.name,
 			process: proc,
 			activity,
-			pendingMessages: this.consumeQueue(agentDef.name),
+			// Replaced with the authoritative get_state values before spawn returns.
+			session: resumeSession ?? { file: "" },
 			aborted: false,
 		};
 
@@ -212,26 +210,31 @@ export class AgentPool {
 			}
 		});
 
-		let agentEndEmitted = false;
+		let terminalEventEmitted = false;
 		let stdoutLines = 0;
 		proc.on("exit", (code, signal) => {
+			this.rejectResponseWaiters(proc, new Error(`Agent ${agentDef.name} exited before RPC response`));
 			// 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 || "(empty)"}`);
 			}
-			// Capture activity stats BEFORE deleting the agent
+			// Capture activity stats before cleanup. A delayed exit callback from an
+			// old child must never delete or mutate a replacement registered for the
+			// same task ID.
 			const finalActivity = agentProc.activity;
-			// 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;
+			const isCurrentChild = this.agents.get(taskId) === agentProc;
+			if (isCurrentChild) this.agents.delete(taskId);
+			// Only the currently registered child may report an unexpected exit.
+			// Intentional shutdown must not reopen a suspended or cancelled task.
+			if (isCurrentChild && !terminalEventEmitted && !agentProc.aborted) {
+				terminalEventEmitted = true;
 				this.emit({
 					type: "agent_end",
 					taskId,
 					agentName: agentDef.name,
 					data: {
 						exitCode: code,
+						unexpectedExit: true,
 						// Preserve complete diagnostics for task failure reports and recovery.
 						stderr,
 						turnCount: finalActivity.turnCount,
@@ -247,8 +250,8 @@ export class AgentPool {
 			}, 500);
 		});
 
-		// Expose the guard so handleRpcEvent can set it
-		(agentProc as any)._agentEndEmitted = () => { agentEndEmitted = true; };
+		// Expose the guard so handleRpcEvent can mark final settlement.
+		(agentProc as any)._terminalEventEmitted = () => { terminalEventEmitted = true; };
 
 		// Wait for process to initialize — pi needs time to load extensions, models, etc.
 		await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -259,25 +262,43 @@ export class AgentPool {
 			);
 		}
 
-		// Send initial prompt
-		const taskPrompt = `Your task: ${protocolOptions.task.title}\n\n${protocolOptions.task.description || ""}`;
-		this.sendRpcCommand(proc, { type: "prompt", message: taskPrompt });
+		// Persisted session identity is authoritative. Capture it before any prompt
+		// is sent so a crash/retry can only resume this task's original context.
+		const state = await this.requestRpc(proc, { type: "get_state" });
+		const rawSessionFile = state?.data?.sessionFile;
+		if (!state?.success || typeof rawSessionFile !== "string" || rawSessionFile.length === 0) {
+			await this.kill(taskId);
+			throw new Error(`Agent ${agentDef.name} did not expose a durable session file`);
+		}
+		agentProc.session = {
+			file: path.isAbsolute(rawSessionFile) ? path.normalize(rawSessionFile) : path.resolve(cwd, rawSessionFile),
+			...(typeof state.data?.sessionId === "string" && state.data.sessionId
+				? { sessionId: state.data.sessionId }
+				: {}),
+		};
 
 		return agentProc;
 	}
 
+	/** Start a turn in an initialized task session. */
+	async prompt(taskId: string, message: string): Promise<boolean> {
+		const agent = this.agents.get(taskId);
+		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
+		return this.requestAccepted(agent.process, { type: "prompt", message });
+	}
+
 	/** Inject a steering message into a running agent */
 	async steer(taskId: string, message: string): Promise<boolean> {
 		const agent = this.agents.get(taskId);
 		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
-		return this.sendRpcCommand(agent.process, { type: "steer", message });
+		return this.requestAccepted(agent.process, { type: "steer", message });
 	}
 
 	/** Queue a follow-up message for after the current turn */
 	async followUp(taskId: string, message: string): Promise<boolean> {
 		const agent = this.agents.get(taskId);
 		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
-		return this.sendRpcCommand(agent.process, { type: "follow_up", message });
+		return this.requestAccepted(agent.process, { type: "follow_up", message });
 	}
 
 	/** Abort the current operation */
@@ -348,7 +369,55 @@ export class AgentPool {
 		}
 	}
 
+	private async requestAccepted(proc: ChildProcess, command: Record<string, unknown>): Promise<boolean> {
+		try {
+			const response = await this.requestRpc(proc, command);
+			return response?.success === true;
+		} catch {
+			return false;
+		}
+	}
+
+	private requestRpc(proc: ChildProcess, command: Record<string, unknown>): Promise<any> {
+		const id = randomUUID();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.responseWaiters.delete(id);
+				reject(new Error(`Timed out waiting for RPC ${String(command.type)}`));
+			}, 10_000);
+			timer.unref();
+			this.responseWaiters.set(id, { process: proc, resolve, reject, timer });
+			if (!this.sendRpcCommand(proc, { ...command, id })) {
+				clearTimeout(timer);
+				this.responseWaiters.delete(id);
+				reject(new Error(`Failed to send RPC ${String(command.type)}`));
+			}
+		});
+	}
+
+	private rejectResponseWaiters(proc: ChildProcess, error: Error): void {
+		for (const [id, waiter] of this.responseWaiters) {
+			if (waiter.process !== proc) continue;
+			clearTimeout(waiter.timer);
+			this.responseWaiters.delete(id);
+			waiter.reject(error);
+		}
+	}
+
 	private handleRpcEvent(agent: AgentProcess, event: any): void {
+		if (event.type === "response" && typeof event.id === "string") {
+			const waiter = this.responseWaiters.get(event.id);
+			if (waiter) {
+				clearTimeout(waiter.timer);
+				this.responseWaiters.delete(event.id);
+				waiter.resolve(event);
+			}
+			return;
+		}
+		// Process stdout can drain after a replacement has already been installed.
+		// Ignore every stale lifecycle/activity event so the old child cannot
+		// evict, settle, or complete the new task process.
+		if (this.agents.get(agent.taskId) !== agent) return;
 		// Only genuine agent activity advances the idle clock. Command acks
 		// (type=response) and echoes of injected user messages (steer messages
 		// recorded as user-role message events) must NOT reset it — otherwise the
@@ -407,14 +476,14 @@ export class AgentPool {
 		} else if (event.type === "agent_settled") {
 			debug("squad-pool", `agent_settled from RPC: ${agent.agentName} (task: ${agent.taskId})`);
 			// Mark the guard to prevent double-emit from proc.on("exit")
-			const guardFn = (agent as any)._agentEndEmitted;
+			const guardFn = (agent as any)._terminalEventEmitted;
 			if (guardFn) guardFn();
 			// Capture activity stats BEFORE deleting
 			const endActivity = agent.activity;
 			// Remove from agents map BEFORE emitting so getRunningAgents() doesn't count it
 			this.agents.delete(agent.taskId);
 			this.emit({
-				type: "agent_end",
+				type: "agent_settled",
 				taskId: agent.taskId,
 				agentName: agent.agentName,
 				data: {
@@ -450,13 +519,23 @@ function buildPiArgs(
 	agentDef: AgentDef,
 	promptFile: string,
 	skillPaths: string[],
-	forkSession?: { file: string; sessionDir: string },
+	sessionOptions: {
+		resumeSession?: TaskSession;
+		sessionDir?: string;
+		forkSession?: { file: string; sessionDir: string };
+	},
 ): string[] {
-	// --fork cannot combine with --no-session; forked child sessions are
-	// stored under the squad's data dir to keep the user's session list clean.
-	const sessionArgs = forkSession
-		? ["--fork", forkSession.file, "--session-dir", forkSession.sessionDir]
-		: ["--no-session"];
+	const { resumeSession, sessionDir, forkSession } = sessionOptions;
+	if (resumeSession && forkSession) throw new Error("Cannot resume and fork a task session simultaneously");
+	// Existing tasks always reopen the exact bound file. Only tasks without a
+	// binding create a new session (optionally as a main-session fork).
+	const sessionArgs = resumeSession
+		? ["--session", resumeSession.file]
+		: forkSession
+			? ["--fork", forkSession.file, "--session-dir", forkSession.sessionDir]
+			: sessionDir
+				? ["--session-dir", sessionDir]
+				: (() => { throw new Error("A durable task session is required"); })();
 	const args: string[] = [...sessionArgs, "--append-system-prompt", promptFile];
 
 	if (agentDef.model) {