pi-squad 0.16.0 → 0.16.2

package/README.md

@@ -127,7 +127,11 @@ Bundled agent definitions are copied to `~/.pi/squad/agents/` on first run. Edit
 
 ### Agent Collaboration
 
-**Chain context**: When task A completes, its output is injected into task B's system prompt. Downstream agents know what was built.
+**Chain context**: When task A completes, its complete output is injected into downstream prompts across the full dependency-ancestor closure (ancestors first, diamond dependencies deduplicated), not only the final direct edge. Integration and QA tasks therefore receive the original contracts their inputs were built from.
+
+**Completed-agent replies**: An `@agent` request aimed at an agent whose task already finished is answered immediately from that agent's durable task output. It is never queued for a nonexistent future spawn, and a blocker resolved this way does not escalate to the human.
+
+**Report-only work**: Planning/review agents may complete with a substantive assistant artifact even when they needed no tool call. Their output still passes through mandatory independent orchestrator review.
 
 **Shared filesystem**: All agents work in the same project directory. Upstream agents create files, downstream agents read and modify them.
 
@@ -135,6 +139,8 @@ 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 steering**: `squad_message` resolves an agent name to its live task, durably records the full message, and writes the documented JSONL RPC command `{"type":"steer","message":"..."}` to the child. pi-squad waits for Pi's final `agent_settled` event before closing the child; low-level `agent_end` no longer kills queued steering/follow-up continuations.
+
 ### Smart Planner
 
 The planner creates task breakdowns with proper dependency ordering:

package/package.json

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

package/src/agent-pool.ts

@@ -270,16 +270,14 @@ export class AgentPool {
 	async steer(taskId: string, message: string): Promise<boolean> {
 		const agent = this.agents.get(taskId);
 		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
-		this.sendRpcCommand(agent.process, { type: "steer", message });
-		return true;
+		return this.sendRpcCommand(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;
-		this.sendRpcCommand(agent.process, { type: "follow_up", message });
-		return true;
+		return this.sendRpcCommand(agent.process, { type: "follow_up", message });
 	}
 
 	/** Abort the current operation */
@@ -301,7 +299,7 @@ export class AgentPool {
 		agent.process.kill("SIGTERM");
 		// Force kill after 5s
 		const timer = setTimeout(() => {
-			if (!agent.process.killed) agent.process.kill("SIGKILL");
+			if (agent.process.exitCode === null) agent.process.kill("SIGKILL");
 		}, 5000);
 		await new Promise<void>((resolve) => {
 			agent.process.on("exit", () => {
@@ -337,9 +335,17 @@ export class AgentPool {
 	// Internal
 	// =========================================================================
 
-	private sendRpcCommand(proc: ChildProcess, command: Record<string, unknown>): void {
-		if (!proc.stdin || proc.stdin.destroyed) return;
-		proc.stdin.write(serializeJsonLine(command));
+	private sendRpcCommand(proc: ChildProcess, command: Record<string, unknown>): boolean {
+		if (!proc.stdin || proc.stdin.destroyed) return false;
+		try {
+			// Writable.write(false) means backpressure, not rejection; the bytes are
+			// still buffered. Reaching write() without throwing means the JSONL
+			// command was handed to the child stream.
+			proc.stdin.write(serializeJsonLine(command));
+			return true;
+		} catch {
+			return false;
+		}
 	}
 
 	private handleRpcEvent(agent: AgentProcess, event: any): void {
@@ -394,10 +400,12 @@ export class AgentPool {
 				data: event,
 			});
 		} else if (event.type === "agent_end") {
-			// 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.
-			debug("squad-pool", `agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
+			// agent_end is one low-level run. Pi may still process queued steer,
+			// follow-up, retry, or compaction continuations. Killing here races and
+			// drops main-session steering. agent_settled is the final lifecycle edge.
+			debug("squad-pool", `agent_end from RPC (awaiting settled): ${agent.agentName} (task: ${agent.taskId})`);
+		} 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;
 			if (guardFn) guardFn();
@@ -417,11 +425,12 @@ export class AgentPool {
 					filesModified: endActivity.modifiedFiles.size,
 				},
 			});
-			// Kill the RPC process since the agent's work is done
+			// The session is fully settled, so the RPC process can now close.
 			agent.process.kill("SIGTERM");
-			setTimeout(() => {
-				if (!agent.process.killed) agent.process.kill("SIGKILL");
+			const forceKill = setTimeout(() => {
+				if (agent.process.exitCode === null) agent.process.kill("SIGKILL");
 			}, 3000);
+			forceKill.unref();
 		} else if (event.type === "error") {
 			this.emit({
 				type: "error",

package/src/plan-rules.ts

@@ -53,6 +53,29 @@ function isQaLikeTask(task: PlanTaskInput): boolean {
 	return /\b(qa|test|tests|testing|verif\w*|review|audit)\b/.test(hay);
 }
 
+/** Task IDs explicitly named in a "depend on ..." Context sentence. */
+function describedDependencies(task: PlanTaskInput, knownIds: Set<string>): string[] {
+	const refs = new Set<string>();
+	for (const clause of task.description.matchAll(/\bdepend(?:s|ing)?\s+on\b([^.;\n]*)/gi)) {
+		for (const quoted of clause[1].matchAll(/`([^`]+)`/g)) {
+			if (knownIds.has(quoted[1])) refs.add(quoted[1]);
+		}
+	}
+	return [...refs];
+}
+
+function dependencyClosure(task: PlanTaskInput, byId: Map<string, PlanTaskInput>): Set<string> {
+	const closure = new Set<string>();
+	const visit = (id: string): void => {
+		if (closure.has(id)) return;
+		closure.add(id);
+		const dependency = byId.get(id);
+		if (dependency) for (const ancestor of dependency.depends) visit(ancestor);
+	};
+	for (const dependency of task.depends) visit(dependency);
+	return closure;
+}
+
 /**
  * Validate a plan's structure. Errors block squad creation;
  * warnings are returned to the plan author for correction.
@@ -125,8 +148,16 @@ export function validatePlan(tasks: PlanTaskInput[]): PlanValidation {
 	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.`);
+		} 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.`);
+			}
+			const closure = dependencyClosure(t, byId);
+			for (const described of describedDependencies(t, ids)) {
+				if (!closure.has(described)) {
+					warnings.push(`Task "${t.id}" says it depends on "${described}", but that task is absent from its formal dependency closure.`);
+				}
+			}
 		}
 	}
 

package/src/protocol.ts

@@ -90,9 +90,10 @@ function buildChainContext(task: Task, allTasks: Task[], squadId: string): strin
 
 	const sections: string[] = [];
 
-	for (const depId of task.depends) {
-		const dep = allTasks.find((t) => t.id === depId);
-		if (!dep || dep.status !== "done") continue;
+	// A downstream integration/QA task needs the contracts its direct inputs
+	// were built from, not only the last edge in the DAG. Walk the complete
+	// ancestor closure, ancestors first, and deduplicate diamond dependencies.
+	for (const dep of completedDependencyClosure(task, allTasks)) {
 
 		let section = `## ${dep.id} (done by ${dep.agent})\n**${dep.title}**\n`;
 		if (dep.output) {
@@ -119,6 +120,24 @@ ${sections.join("\n---\n\n")}
 `;
 }
 
+function completedDependencyClosure(task: Task, allTasks: Task[]): Task[] {
+	const byId = new Map(allTasks.map((candidate) => [candidate.id, candidate]));
+	const seen = new Set<string>();
+	const ordered: Task[] = [];
+
+	const visit = (id: string): void => {
+		if (seen.has(id)) return;
+		seen.add(id);
+		const dependency = byId.get(id);
+		if (!dependency) return;
+		for (const ancestorId of dependency.depends) visit(ancestorId);
+		if (dependency.status === "done") ordered.push(dependency);
+	};
+
+	for (const dependencyId of task.depends) visit(dependencyId);
+	return ordered;
+}
+
 // ============================================================================
 // Sibling Awareness
 // ============================================================================

package/src/router.ts

@@ -47,12 +47,18 @@ export class Router {
 	processMessage(taskId: string, fromAgent: string, text: string): void {
 		// Parse @mentions
 		const mentions = this.parseMentions(text, fromAgent);
+		let resolvedFromDurableOutput = false;
 		for (const mention of mentions) {
-			this.routeMention(taskId, fromAgent, mention.target, mention.message);
+			const resolved = this.routeMention(taskId, fromAgent, mention.target, mention.message);
+			// Only suppress escalation when the resolved mention itself expressed
+			// the blocker; an unrelated completed-agent FYI must not hide another block.
+			resolvedFromDurableOutput =
+				(resolved && this.isBlockSignal(mention.message)) || resolvedFromDurableOutput;
 		}
 
-		// Detect block signals
-		if (this.isBlockSignal(text)) {
+		// Do not wake the human for a blocker we immediately resolved from a
+		// completed agent's durable task output.
+		if (this.isBlockSignal(text) && !resolvedFromDurableOutput) {
 			for (const listener of this.escalationListeners) {
 				listener(taskId, fromAgent, this.extractBlockReason(text));
 			}
@@ -67,7 +73,7 @@ export class Router {
 		fromAgent: string,
 		targetAgent: string,
 		message: string,
-	): void {
+	): boolean {
 		// Log the mention in the source task
 		store.appendMessage(this.squadId, sourceTaskId, {
 			ts: store.now(),
@@ -93,8 +99,41 @@ export class Router {
 				to: targetAgent,
 				text: message,
 			});
-		} else {
-			// Target not running — queue for later
+			return false;
+		}
+
+		const targetTasks = store.loadAllTasks(this.squadId).filter((task) => task.agent === targetAgent);
+		const hasFutureRun = targetTasks.some((task) =>
+			task.status === "pending" || task.status === "blocked" || task.status === "suspended" || task.status === "in_progress",
+		);
+		if (!hasFutureRun) {
+			const completed = targetTasks.filter((task) => task.status === "done" && task.output);
+			if (completed.length > 0) {
+				const durableReply = [
+					`[squad] @${targetAgent} has completed and is no longer running. Durable completed output:`,
+					...completed.map((task) => `\n## ${task.id}: ${task.title}\n${task.output}`),
+				].join("\n");
+				const reply = {
+					ts: store.now(),
+					from: targetAgent,
+					type: "reply" as const,
+					to: fromAgent,
+					text: durableReply,
+				};
+				store.appendMessage(this.squadId, sourceTaskId, reply);
+				if (this.pool.isRunning(sourceTaskId)) {
+					this.pool.steer(sourceTaskId, durableReply);
+				} else {
+					this.pool.queueMessage(fromAgent, reply);
+				}
+				return true;
+			}
+		}
+
+		// Target has future work and may spawn again — queue for that run. If the
+		// target is terminal with no output, do not create an undeliverable queue;
+		// leave the blocker unresolved so it escalates to the main orchestrator.
+		if (hasFutureRun) {
 			this.pool.queueMessage(targetAgent, {
 				ts: store.now(),
 				from: fromAgent,
@@ -103,6 +142,7 @@ export class Router {
 				text: message,
 			});
 		}
+		return false;
 	}
 
 	/**

package/src/scheduler.ts

@@ -622,15 +622,18 @@ export class Scheduler {
 				const turnCount = event.data?.turnCount ?? 0;
 				const toolCallCount = event.data?.toolCallCount ?? 0;
 
-				// Agent must have done real work: at least 1 turn AND at least 1 tool call.
-				// An agent that exits cleanly but with 0 turns/tools did nothing —
-				// likely hit a rate limit or API error. Treat as crash, not success.
-				const hadMeaningfulWork = turnCount > 0 && toolCallCount > 0;
+				// Tool use is strong evidence of work, but planning/review tasks can
+				// legitimately deliver a substantive report without calling a tool.
+				// Accept durable assistant output; the mandatory main-orchestrator
+				// review gate still decides whether the work satisfies the contract.
+				const hasSubstantiveOutput = store.loadMessages(this.squadId, event.taskId)
+					.some((message) => message.from === event.agentName && message.type === "text" && message.text.trim().length > 0);
+				const hadMeaningfulWork = turnCount > 0 && (toolCallCount > 0 || hasSubstantiveOutput);
 				if (hadMeaningfulWork) {
 					this.handleTaskCompleted(event.taskId).then(() => this.updateContext());
 				} else {
-					// Agent exited without doing real work (0 turns or 0 tool calls).
-					// Common causes: rate limit, API error, resource pressure, crash.
+					// Agent exited without a completed turn, tool work, or substantive
+					// assistant artifact. Common causes: rate limit/API/resource failure.
 					// Retry once before failing.
 					const retryKey = `spawn-retry:${event.taskId}`;
 					if (!this.spawnRetries.has(retryKey)) {
@@ -638,7 +641,7 @@ export class Scheduler {
 						const stderr = event.data?.stderr || "";
 						const reason = turnCount === 0
 							? `exited with 0 turns (likely rate limit or API error)`
-							: `exited with ${turnCount} turns but 0 tool calls (no work done)`;
+							: `exited with ${turnCount} turns but no tool calls or substantive output`;
 						logError("squad-scheduler", `Agent ${event.agentName} ${reason}, code=${exitCode}. Retrying in 2s... stderr: ${stderr}`);
 						store.updateTaskStatus(this.squadId, event.taskId, "pending");
 						store.appendMessage(this.squadId, event.taskId, {