pi-squad 0.7.2 → 0.15.0

package/src/monitor.ts

@@ -5,28 +5,38 @@
  * - Idle timeout (no output for N minutes)
  * - Stuck detection (no output for longer)
  * - Loop detection (same tool call repeated)
- * - Hard ceiling (max total runtime)
+ * - Long-running check-in (notify the main session; never aborts)
  * - File conflict warnings
+ *
+ * The monitor NEVER kills or blocks work on its own. Its strongest action is
+ * `notify`: tell the main Pi session so a human/main agent can check in.
  */
 
 import type { AgentPool } from "./agent-pool.js";
 import type { HealthStatus } from "./types.js";
+import { debug } from "./logger.js";
 
 // ============================================================================
 // Config
 // ============================================================================
 
-const IDLE_WARNING_MS = 3 * 60 * 1000; // 3 min no output → warn
-const STUCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 min no output → intervene
-const HARD_CEILING_MS = 30 * 60 * 1000; // 30 min total → force stop
+/** Env-overridable for testing (PI_SQUAD_IDLE_MS etc.) */
+function envMs(name: string, fallback: number): number {
+	const v = Number(process.env[name]);
+	return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+const IDLE_WARNING_MS = envMs("PI_SQUAD_IDLE_MS", 3 * 60 * 1000); // no output → warn
+const STUCK_TIMEOUT_MS = envMs("PI_SQUAD_STUCK_MS", 5 * 60 * 1000); // no output → intervene
+const LONG_RUN_NOTIFY_MS = envMs("PI_SQUAD_CEILING_MS", 30 * 60 * 1000); // total → notify main session (no abort)
 const LOOP_THRESHOLD = 5; // same tool call 5x → looping
-const POLL_INTERVAL_MS = 30 * 1000; // check every 30s
+const POLL_INTERVAL_MS = envMs("PI_SQUAD_POLL_MS", 30 * 1000); // check interval
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export type MonitorActionType = "steer" | "abort" | "escalate";
+export type MonitorActionType = "steer" | "escalate" | "notify";
 
 export interface MonitorAction {
 	type: MonitorActionType;
@@ -51,6 +61,10 @@ export class Monitor {
 	private warned = new Set<string>();
 	/** Track which agents have been steered for stuck (to avoid repeated steers) */
 	private stuckSteered = new Set<string>();
+	/** Track which tasks have been escalated (one escalation per stuck episode) */
+	private escalated = new Set<string>();
+	/** Last long-run threshold multiple notified per task (notify once per multiple) */
+	private longRunNotified = new Map<string, number>();
 
 	constructor(pool: AgentPool, squadId: string) {
 		this.pool = pool;
@@ -90,6 +104,8 @@ export class Monitor {
 		}
 		this.warned.clear();
 		this.stuckSteered.clear();
+		this.escalated.clear();
+		this.longRunNotified.clear();
 	}
 
 	/** Check all running agents */
@@ -102,7 +118,7 @@ export class Monitor {
 			if (!activity) continue;
 
 			const health = this.checkHealth(activity);
-			this.handleHealth(taskId, agentName, health);
+			this.handleHealth(taskId, agentName, health, activity);
 		}
 	}
 
@@ -123,7 +139,7 @@ export class Monitor {
 			if (unique.size === 1) return "looping";
 		}
 
-		if (totalMs >= HARD_CEILING_MS) return "exceeded_ceiling";
+		if (totalMs >= LONG_RUN_NOTIFY_MS) return "long_running";
 		if (idleMs >= STUCK_TIMEOUT_MS) return "stuck";
 		if (idleMs >= IDLE_WARNING_MS) return "idle_warning";
 
@@ -131,12 +147,19 @@ export class Monitor {
 	}
 
 	/** Take action based on health status */
-	private handleHealth(taskId: string, agentName: string, status: HealthStatus): void {
+	private handleHealth(
+		taskId: string,
+		agentName: string,
+		status: HealthStatus,
+		activity?: { startedAt: number },
+	): void {
+		if (status !== "healthy") debug("squad-monitor", `${taskId} (${agentName}): ${status}`);
 		switch (status) {
 			case "healthy":
-				// Clear warning flags
+				// Clear warning flags — a new stuck episode escalates again
 				this.warned.delete(taskId);
 				this.stuckSteered.delete(taskId);
+				this.escalated.delete(taskId);
 				break;
 
 			case "idle_warning":
@@ -166,8 +189,9 @@ export class Monitor {
 							"Summarize what you've done and what's blocking you. " +
 							"If you can't proceed, state what you need.",
 					});
-				} else {
-					// Already steered once, escalate
+				} else if (!this.escalated.has(taskId)) {
+					// Already steered once — escalate, but only once per stuck episode
+					this.escalated.add(taskId);
 					this.emit({
 						type: "escalate",
 						taskId,
@@ -190,15 +214,25 @@ export class Monitor {
 				});
 				break;
 
-			case "exceeded_ceiling":
-				this.emit({
-					type: "abort",
-					taskId,
-					agentName,
-					reason: `Agent ${agentName} exceeded time ceiling on ${taskId}`,
-					message: "",
-				});
+			case "long_running": {
+				// Never abort. Notify the main Pi session once per threshold multiple
+				// (30m, 60m, 90m, …) so it can check in if needed — work continues.
+				const totalMs = Date.now() - (activity?.startedAt ?? Date.now());
+				const multiple = Math.floor(totalMs / LONG_RUN_NOTIFY_MS);
+				const lastNotified = this.longRunNotified.get(taskId) ?? 0;
+				if (multiple > lastNotified) {
+					this.longRunNotified.set(taskId, multiple);
+					const minutes = Math.round(totalMs / 60_000);
+					this.emit({
+						type: "notify",
+						taskId,
+						agentName,
+						reason: `Agent ${agentName} has been working on ${taskId} for ${minutes}m. Still running — check on it if needed (steer, pause, or let it continue).`,
+						message: "",
+					});
+				}
 				break;
+			}
 		}
 	}
 }

package/src/panel/message-view.ts

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

package/src/panel/squad-panel.ts

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

package/src/panel/squad-widget.ts

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

package/src/panel/task-list.ts

@@ -2,8 +2,8 @@
  * task-list.ts — Task tree view with status icons, live activity preview.
  */
 
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { Task, TaskStatus } from "../types.js";
 import type { Scheduler } from "../scheduler.js";
 import * as store from "../store.js";

package/src/plan-rules.ts

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

package/src/planner.ts

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

package/src/protocol.ts

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