pi-squad 0.17.1 → 0.18.0

package/src/lifecycle.ts

@@ -0,0 +1,164 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { setupSquadWidget } from "./panel/squad-widget.js";
+import { activateSquadView, openPanel } from "./panel-runtime.js";
+import { buildOrchestratorReviewGate } from "./review.js";
+import { reviveScheduler } from "./scheduler-runtime.js";
+import * as store from "./store.js";
+import type { Squad } from "./types.js";
+import { DISABLED_GUIDANCE, focusSquad, formatTaskProgress, runtime } from "./runtime.js";
+
+export function registerLifecycle(pi: ExtensionAPI, squadSkillPaths: string[]): void {
+/** Register a dynamically gated Ctrl+Q path; disabled mode can only show guidance. */
+const registerTerminalPanelToggle = (ctx: ExtensionContext): void => {
+	if (!ctx.hasUI) return;
+	ctx.ui.onTerminalInput((data) => {
+		if (data !== "\x11") return undefined;
+		if (!runtime.squadEnabled) {
+			ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+			return { consume: true };
+		}
+		// If overlay is already open, let the panel's own handler deal with it.
+		if (runtime.overlayOpen) return undefined;
+		if (!runtime.activeSquadId) {
+			const latest = store.findLatestSquad(ctx.cwd)
+				|| store.listSquads().map((id) => store.loadSquad(id)).filter((s): s is Squad => s !== null).sort((a, b) => b.created.localeCompare(a.created))[0];
+			if (latest) activateSquadView(latest.id, ctx);
+			else {
+				ctx.ui.notify("No squads found. Use /squad or the squad tool.", "info");
+				return { consume: true };
+			}
+		}
+		if (runtime.activeSquadId) {
+			openPanel(pi, ctx, reviveScheduler(pi, runtime.activeSquadId, squadSkillPaths), runtime.activeSquadId, squadSkillPaths);
+		}
+		return { consume: true };
+	});
+};
+
+// =========================================================================
+// Session Lifecycle
+// =========================================================================
+
+pi.on("session_start", async (_event, ctx) => {
+	// Re-read before touching focus, widgets, runtime.schedulers, or persisted work.
+	runtime.squadEnabled = store.loadSquadSettings().enabled;
+	runtime.uiCtx = ctx;
+
+	// A session replacement may not deliver shutdown first. Never carry a
+	// focused squad across projects, and never seed a new widget from stale state.
+	runtime.widgetControls?.dispose();
+	runtime.widgetControls = null;
+	registerTerminalPanelToggle(ctx);
+	if (!runtime.squadEnabled) {
+		runtime.widgetState.enabled = false;
+		focusSquad(null);
+		return;
+	}
+	runtime.widgetState.enabled = true;
+	const focused = runtime.activeSquadId ? store.loadSquad(runtime.activeSquadId) : null;
+	focusSquad(focused?.cwd === ctx.cwd ? runtime.activeSquadId : null);
+
+	// Install component-based widget
+	if (ctx.hasUI) {
+		runtime.widgetControls = setupSquadWidget(ctx, runtime.widgetState);
+	}
+
+	// Clean up orphaned squads from crashed sessions:
+	// If a squad is "running" but has no live scheduler, its parent died.
+	// Suspend in-progress tasks and mark the squad as paused so it doesn't
+	// block new squads or trigger confusing followUp messages.
+	const orphaned = store.findActiveSquads()
+		.filter((s) => s.cwd === ctx.cwd && s.status === "running");
+	for (const squad of orphaned) {
+		const tasks = store.loadAllTasks(squad.id);
+		let hadInProgress = false;
+		for (const task of tasks) {
+			if (task.status === "in_progress") {
+				store.updateTaskStatus(squad.id, task.id, "suspended");
+				hadInProgress = true;
+			}
+		}
+		if (hadInProgress) {
+			squad.status = "paused";
+			store.saveSquad(squad);
+		}
+	}
+
+	// Audit file-spec evidence on restart. Review/running/failed work is reopened;
+	// an explicitly paused squad remains paused and suspended/cancelled tasks stay untouched.
+	for (const squad of store.listSquadsForProject(ctx.cwd).filter((candidate) => candidate.spec && ["running", "failed", "paused", "review"].includes(candidate.status))) {
+		const scheduler = reviveScheduler(pi, squad.id, squadSkillPaths);
+		const invalid = await scheduler.auditSpecAttestations();
+		if (invalid.length > 0 && squad.status !== "paused") await scheduler.start();
+	}
+
+	// Reconstruct runtime.schedulers for explicit-suspension stalls without resuming any
+	// task. Reconcile derives/persists a missing outbox record and emits only a
+	// pending fingerprint; delivered attention remains durable and silent.
+	const suspensionCandidates = store.listSquadsForProject(ctx.cwd)
+		.filter((squad) => Boolean(squad.suspendedStallAttention) || store.loadAllTasks(squad.id).some((task) => task.status === "suspended"));
+	for (const squad of suspensionCandidates) {
+		const scheduler = reviveScheduler(pi, squad.id, squadSkillPaths);
+		await scheduler.start();
+	}
+
+	// Mailbox recovery is automatic after extension/main-process restart. Scan
+	// every project squad (including accepted done squads) because a crash can
+	// occur after the mailbox-first write but before the squad/task is reopened.
+	const pendingMailSquads = store.listSquadsForProject(ctx.cwd)
+		.filter((squad) => store.loadAllTasks(squad.id)
+			.some((task) => task.status !== "cancelled" && store.loadPendingTaskMessages(squad.id, task.id).length > 0))
+		.sort((a, b) => b.created.localeCompare(a.created));
+	for (const squad of pendingMailSquads) {
+		const scheduler = reviveScheduler(pi, squad.id, squadSkillPaths);
+		await scheduler.start();
+	}
+	if (pendingMailSquads.length > 0) focusSquad(pendingMailSquads[0].id);
+
+	// Notify about paused squads only if they have real completed work
+	const paused = store.findActiveSquads()
+		.filter((s) => s.cwd === ctx.cwd && s.status === "paused");
+	if (paused.length > 0) {
+		const squad = paused[0];
+		const tasks = store.loadAllTasks(squad.id);
+		const done = tasks.filter(t => t.status === "done").length;
+		// Only notify if at least 1 task completed — worth resuming
+		if (done > 0) {
+			pi.sendMessage({
+				customType: "squad-paused",
+				content: `[squad] Found paused squad "${squad.id}" (${squad.spec ? `file spec sha256=${squad.spec.sha256}` : squad.goal}) — ${formatTaskProgress(tasks)}. ` +
+					`Use squad_modify with action "resume" to continue, or start a new squad.`,
+				display: true,
+			});
+		}
+	}
+
+	// Restore pending acceptance gates after a main-session restart. Review is
+	// persisted state, not a one-shot completion message that can be missed.
+	const pendingReviews = store.findActiveSquads()
+		.filter((s) => s.cwd === ctx.cwd && s.status === "review");
+	if (pendingReviews.length > 0) {
+		const squad = pendingReviews.sort((a, b) => b.created.localeCompare(a.created))[0];
+		focusSquad(squad.id);
+		const tasks = store.loadAllTasks(squad.id);
+		pi.sendMessage({
+			customType: "squad-review-required",
+			content: `[squad] Restored mandatory orchestrator review for "${squad.id}" after session restart. The work remains untrusted and not accepted.\n\n${buildOrchestratorReviewGate(squad, tasks)}`,
+			display: true,
+		});
+	}
+
+});
+
+pi.on("session_shutdown", async () => {
+	focusSquad(null);
+	runtime.widgetControls?.dispose();
+	runtime.widgetControls = null;
+	for (const [id, sched] of runtime.schedulers) {
+		await sched.stop();
+	}
+	runtime.schedulers.clear();
+	runtime.uiCtx = null;
+});
+
+}

package/src/panel/squad-panel.ts

@@ -41,6 +41,8 @@ export class SquadPanel implements Component, Focusable {
 	private done: (result: SquadPanelResult) => void;
 	private scheduler: Scheduler;
 	private squadId: string;
+	private isEnabled: () => boolean;
+	private onDisabled: () => void;
 
 	/** Callback for sending messages — set by the extension */
 	onSendMessage?: (taskId: string, message: string) => Promise<void>;
@@ -69,12 +71,16 @@ export class SquadPanel implements Component, Focusable {
 		scheduler: Scheduler,
 		squadId: string,
 		done: (result: SquadPanelResult) => void,
+		isEnabled: () => boolean = () => true,
+		onDisabled: () => void = () => {},
 	) {
 		this.tui = tui;
 		this.theme = theme;
 		this.scheduler = scheduler;
 		this.squadId = squadId;
 		this.done = done;
+		this.isEnabled = isEnabled;
+		this.onDisabled = onDisabled;
 
 		this.taskListView = new TaskListView(theme, squadId);
 		this.messageView = new MessageView(theme, squadId);
@@ -112,6 +118,12 @@ export class SquadPanel implements Component, Focusable {
 	// =========================================================================
 
 	handleInput(data: string): void {
+		if (!this.isEnabled()) {
+			this.onDisabled();
+			this.finish({ action: "close" });
+			return;
+		}
+
 		// Ctrl+Q or q: close panel
 		if (data === "\x11") {
 			this.finish({ action: "close" });
@@ -316,6 +328,10 @@ export class SquadPanel implements Component, Focusable {
 	// Lifecycle
 	// =========================================================================
 
+	close(): void {
+		this.finish({ action: "close" });
+	}
+
 	dispose(): void {
 		if (this.renderTimeout) {
 			clearTimeout(this.renderTimeout);

package/src/panel-runtime.ts

@@ -0,0 +1,157 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
+import { getReviewPresentation } from "./presentation.js";
+import type { Scheduler } from "./scheduler.js";
+import * as store from "./store.js";
+import type { Squad } from "./types.js";
+import { DISABLED_GUIDANCE, focusSquad, forceWidgetUpdate, formatTaskProgress, runtime } from "./runtime.js";
+import { reviveScheduler } from "./scheduler-runtime.js";
+
+// ============================================================================
+// Squad Selection & Activation
+// ============================================================================
+
+/**
+ * Show an interactive selector to pick a squad.
+ * Returns the selected squad or undefined if cancelled.
+ */
+export async function pickSquad(
+	ctx: import("@earendil-works/pi-coding-agent").ExtensionContext | import("@earendil-works/pi-coding-agent").ExtensionCommandContext,
+	squads: Squad[],
+	showProject = false,
+): Promise<Squad | undefined> {
+	if (squads.length === 0) return undefined;
+
+	const options = squads.map((s) => {
+		const tasks = store.loadAllTasks(s.id);
+		const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
+		const review = getReviewPresentation(s);
+		const icon = review?.icon ?? (s.status === "done" ? "✓" : s.status === "running" ? "⏳" : s.status === "failed" ? "✗" : "·");
+		const acceptance = review ? ` ${review.label}` : ` [${s.status}]`;
+		const project = showProject ? ` — ${s.cwd.split("/").pop()}` : "";
+		return `${icon} ${s.id}${acceptance} · ${formatTaskProgress(tasks)} $${cost.toFixed(2)}${project}`;
+	});
+
+	const choice = await ctx.ui.select("Select a squad", options);
+	if (choice === undefined) return undefined;
+
+	const idx = options.indexOf(choice);
+	return idx >= 0 ? squads[idx] : undefined;
+}
+
+/**
+ * Activate a squad for viewing in this session.
+ * Sets runtime.activeSquadId, starts widget, shows notification.
+ * Does NOT start a scheduler (view-only unless squad needs resuming).
+ */
+export function activateSquadView(squadId: string, ctx: import("@earendil-works/pi-coding-agent").ExtensionContext | import("@earendil-works/pi-coding-agent").ExtensionCommandContext): void {
+	if (!runtime.squadEnabled) {
+		ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+		return;
+	}
+	const squad = store.loadSquad(squadId);
+	if (!squad) {
+		ctx.ui.notify(`Squad '${squadId}' not found`, "error");
+		return;
+	}
+
+	// Selection is one atomic focus operation: panel, widget, status, and tools
+	// must all target this exact squad before control returns to the caller.
+	focusSquad(squadId);
+
+	// Compact notification — widget already shows full task details.
+	// Avoid large multi-line notifications that can break TUI layout.
+	const tasks = store.loadAllTasks(squadId);
+	const cost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
+	ctx.ui.notify(`Viewing: ${squad.id} [${squad.status}] ${formatTaskProgress(tasks)} $${cost.toFixed(2)}`, "info");
+}
+
+// ============================================================================
+// Panel — overlay via ctx.ui.custom() with proper done() lifecycle
+// ============================================================================
+
+/**
+ * Open the squad panel overlay.
+ * Uses the pi-interactive-shell pattern: ctx.ui.custom() returns a Promise
+ * that resolves when done() is called. The panel calls done() on close.
+ */
+export function openPanel(
+	pi: ExtensionAPI,
+	ctx: import("@earendil-works/pi-coding-agent").ExtensionContext,
+	scheduler: Scheduler,
+	squadId: string,
+	skillPaths: string[],
+): void {
+	if (!runtime.squadEnabled) {
+		ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+		return;
+	}
+	if (runtime.overlayOpen) return;
+	// Opening details also establishes authoritative focus. This covers callers
+	// that reconstructed or targeted a scheduler without going through selector UI.
+	focusSquad(squadId);
+	runtime.overlayOpen = true;
+
+	// The promise resolves when the panel calls done()
+	const panelPromise = ctx.ui.custom<SquadPanelResult>(
+		(tui, theme, _kb, done) => {
+			const panel = new SquadPanel(
+				tui,
+				theme,
+				scheduler,
+				squadId,
+				done,
+				() => runtime.squadEnabled,
+				() => ctx.ui.notify(DISABLED_GUIDANCE, "warning"),
+			);
+			runtime.closeOverlay = () => panel.close();
+
+			// Wire up message sending from panel
+			panel.onSendMessage = async (taskId: string, _prefill: string) => {
+				if (!runtime.squadEnabled) {
+					ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+					return;
+				}
+				const task = store.loadTask(squadId, taskId);
+				const agentName = task?.agent || taskId;
+				const input = await ctx.ui.input(`Message to ${agentName}`, "Type your message...");
+				if (!runtime.squadEnabled) {
+					ctx.ui.notify(DISABLED_GUIDANCE, "warning");
+					return;
+				}
+				if (input) {
+					const panelSched = reviveScheduler(pi, squadId, skillPaths);
+					await panelSched.start();
+					const delivered = await panelSched.sendHumanMessage(taskId, input);
+					ctx.ui.notify(
+						delivered ? `Sent to ${agentName}: "${input}"` : `Queued durably for ${taskId}`,
+						"info",
+					);
+				}
+				tui.requestRender();
+			};
+
+			return panel;
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				anchor: "center" as const,
+				width: "80%" as const,
+				maxHeight: "80%" as const,
+				margin: 2,
+			},
+		},
+	);
+
+	// When panel closes (done() called), clean up
+	panelPromise.then(() => {
+		runtime.overlayOpen = false;
+		runtime.closeOverlay = null;
+		forceWidgetUpdate();
+	}).catch(() => {
+		runtime.overlayOpen = false;
+		runtime.closeOverlay = null;
+	});
+}
+

package/src/protocol.ts

@@ -6,12 +6,11 @@
  * 2. Agent identity (role, custom prompt)
  * 3. Chain context (completed dependency outputs)
  * 4. Sibling awareness (parallel tasks, file map)
- * 5. Knowledge entries (decisions, conventions, findings)
- * 6. Queued messages (received while agent wasn't running)
+ * 5. Queued messages (received while agent wasn't running)
  */
 
-import type { AgentDef, KnowledgeEntry, Squad, Task, TaskMessage } from "./types.js";
-import { loadAllKnowledge, loadAllTasks, loadMessages } from "./store.js";
+import type { AgentDef, Squad, Task, TaskMessage } from "./types.js";
+import { loadAllTasks, loadMessages } from "./store.js";
 
 // ============================================================================
 // Squad Protocol (injected into every agent)
@@ -186,47 +185,6 @@ function buildSiblingAwareness(
 	return lines.join("\n") + "\n";
 }
 
-// ============================================================================
-// Knowledge
-// ============================================================================
-
-function buildKnowledgeSection(squadId: string): string {
-	const entries = loadAllKnowledge(squadId);
-	if (entries.length === 0) return "";
-
-	const decisions = entries.filter((e) => e.type === "decision");
-	const conventions = entries.filter((e) => e.type === "convention");
-	const findings = entries.filter((e) => e.type === "finding");
-
-	const lines: string[] = ["# Squad Knowledge\n"];
-
-	if (decisions.length > 0) {
-		lines.push("## Decisions");
-		for (const d of decisions) {
-			lines.push(`- ${d.text} (${d.from})`);
-		}
-		lines.push("");
-	}
-
-	if (conventions.length > 0) {
-		lines.push("## Project Conventions");
-		for (const c of conventions) {
-			lines.push(`- ${c.text} (${c.from})`);
-		}
-		lines.push("");
-	}
-
-	if (findings.length > 0) {
-		lines.push("## Findings");
-		for (const f of findings) {
-			lines.push(`- ${f.text} (${f.from})`);
-		}
-		lines.push("");
-	}
-
-	return lines.join("\n");
-}
-
 // ============================================================================
 // Queued Messages
 // ============================================================================
@@ -326,7 +284,6 @@ export function buildAgentSystemPrompt(options: ProtocolBuildOptions): string {
 			buildAgentIdentity(agentDef),
 			...(task.fileSpecDelta ? [buildTaskSection(task), buildReworkContext(task, squadId)] : []),
 			buildChainContext(task, allTasks, squadId),
-			buildKnowledgeSection(squadId),
 			buildQueuedMessages(queuedMessages),
 		].filter((section) => section.length > 0);
 		return fileSections.join("\n---\n\n");
@@ -339,7 +296,6 @@ export function buildAgentSystemPrompt(options: ProtocolBuildOptions): string {
 		buildReworkContext(task, squadId),
 		buildChainContext(task, allTasks, squadId),
 		buildSiblingAwareness(task, allTasks, modifiedFiles),
-		buildKnowledgeSection(squadId),
 		buildQueuedMessages(queuedMessages),
 	].filter((s) => s.length > 0);
 

package/src/report.ts

@@ -1,10 +1,45 @@
+import { execFileSync, type ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
 import type { Task } from "./types.js";
 
+const SNAPSHOT_COMMAND_OPTIONS: ExecFileSyncOptionsWithStringEncoding = {
+	encoding: "utf8",
+	timeout: 2_000,
+	maxBuffer: 256 * 1024,
+	windowsHide: true,
+	stdio: ["ignore", "pipe", "ignore"],
+};
+
+function buildWorkingTreeSnapshot(cwd: string): string {
+	try {
+		const insideWorkTree = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+			...SNAPSHOT_COMMAND_OPTIONS,
+			cwd,
+		}).trim();
+		if (insideWorkTree !== "true") return "";
+
+		const diffStat = execFileSync("git", ["diff", "--stat"], {
+			...SNAPSHOT_COMMAND_OPTIONS,
+			cwd,
+		}).trimEnd();
+		const status = execFileSync("git", ["status", "--short"], {
+			...SNAPSHOT_COMMAND_OPTIONS,
+			cwd,
+		});
+		const untrackedCount = status.match(/^\?\? /gm)?.length ?? 0;
+
+		return ["Working Tree Snapshot", diffStat, `Untracked files: ${untrackedCount}`]
+			.filter(Boolean)
+			.join("\n");
+	} catch {
+		return "";
+	}
+}
+
 /**
  * Build the full task handoff included in squad completion notifications.
  * This is durable report data, not a UI preview: never shorten task output.
  */
-export function buildCompletionSummary(tasks: Task[]): string {
+export function buildCompletionSummary(tasks: Task[], cwd?: string): string {
 	const completed = tasks
 		.filter((task) => task.status === "done")
 		.map((task) => `- ${task.id} (${task.agent}): ${task.output || "done"}`)
@@ -14,9 +49,12 @@ export function buildCompletionSummary(tasks: Task[]): string {
 		.map((task) => `- ${task.id} (${task.agent}): cancelled`)
 		.join("\n");
 
-	return [completed, cancelled ? `CANCELLED TASKS (neutral; not successful output)\n${cancelled}` : ""]
+	const legacySummary = [completed, cancelled ? `CANCELLED TASKS (neutral; not successful output)\n${cancelled}` : ""]
 		.filter(Boolean)
 		.join("\n\n");
+	const snapshot = cwd ? buildWorkingTreeSnapshot(cwd) : "";
+
+	return [legacySummary, snapshot].filter(Boolean).join("\n\n");
 }
 
 /** Build the full failure handoff without shortening diagnostics. */