pi-crew 0.1.6 → 0.1.8

package/src/runtime/pi-args.ts

@@ -7,12 +7,14 @@ import type { AgentConfig } from "../agents/agent-config.ts";
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const PROMPT_RUNTIME_EXTENSION_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "prompt", "prompt-runtime.ts");
 const TASK_ARG_LIMIT = 8000;
+const DEFAULT_MAX_CREW_DEPTH = 2;
 
 export interface BuildPiWorkerArgsInput {
 	task: string;
 	agent: AgentConfig;
 	model?: string;
 	sessionEnabled?: boolean;
+	maxDepth?: number;
 }
 
 export interface BuildPiWorkerArgsResult {
@@ -28,6 +30,25 @@ export function applyThinkingSuffix(model: string | undefined, thinking: string
 	return `${model}:${thinking}`;
 }
 
+export function currentCrewDepth(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env.PI_CREW_DEPTH ?? env.PI_TEAMS_DEPTH ?? "0";
+	const parsed = Number(raw);
+	return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+export function resolveCrewMaxDepth(inputMaxDepth?: number, env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env.PI_CREW_MAX_DEPTH ?? env.PI_TEAMS_MAX_DEPTH;
+	const envDepth = raw !== undefined ? Number(raw) : NaN;
+	if (Number.isInteger(envDepth) && envDepth >= 0) return envDepth;
+	return Number.isInteger(inputMaxDepth) && inputMaxDepth !== undefined && inputMaxDepth >= 0 ? inputMaxDepth : DEFAULT_MAX_CREW_DEPTH;
+}
+
+export function checkCrewDepth(inputMaxDepth?: number, env: NodeJS.ProcessEnv = process.env): { blocked: boolean; depth: number; maxDepth: number } {
+	const depth = currentCrewDepth(env);
+	const maxDepth = resolveCrewMaxDepth(inputMaxDepth, env);
+	return { depth, maxDepth, blocked: depth >= maxDepth };
+}
+
 export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerArgsResult {
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
@@ -61,11 +82,19 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 		args.push(`Task: ${input.task}`);
 	}
 
+	const parentDepth = currentCrewDepth();
+	const maxDepth = resolveCrewMaxDepth(input.maxDepth);
 	return {
 		args,
 		env: {
+			PI_CREW_INHERIT_PROJECT_CONTEXT: input.agent.inheritProjectContext ? "1" : "0",
+			PI_CREW_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
+			PI_CREW_DEPTH: String(parentDepth + 1),
+			PI_CREW_MAX_DEPTH: String(maxDepth),
 			PI_TEAMS_INHERIT_PROJECT_CONTEXT: input.agent.inheritProjectContext ? "1" : "0",
 			PI_TEAMS_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
+			PI_TEAMS_DEPTH: String(parentDepth + 1),
+			PI_TEAMS_MAX_DEPTH: String(maxDepth),
 		},
 		tempDir,
 	};

package/src/runtime/runtime-resolver.ts

@@ -48,7 +48,7 @@ export async function isLiveSessionRuntimeAvailable(timeoutMs = 1500, env: NodeJ
 
 export async function resolveCrewRuntime(config: PiTeamsConfig, env: NodeJS.ProcessEnv = process.env): Promise<CrewRuntimeCapabilities> {
 	const requestedMode = config.runtime?.mode ?? "auto";
-	const executeWorkers = config.executeWorkers === true || env.PI_TEAMS_EXECUTE_WORKERS === "1";
+	const executeWorkers = config.executeWorkers === true || env.PI_CREW_EXECUTE_WORKERS === "1" || env.PI_TEAMS_EXECUTE_WORKERS === "1";
 	if (requestedMode === "scaffold") return scaffoldCaps(requestedMode);
 	if (requestedMode === "child-process") return childCaps(requestedMode, executeWorkers ? undefined : "child-process requested but executeWorkers is not enabled; caller should refuse or fall back explicitly.");
 	if (requestedMode === "live-session" || (requestedMode === "auto" && config.runtime?.preferLiveSession === true)) {

package/src/runtime/sidechain-output.ts

@@ -0,0 +1,28 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface SidechainEntry {
+	isSidechain: true;
+	agentId: string;
+	type: string;
+	message: unknown;
+	timestamp: string;
+	cwd: string;
+}
+
+export function writeSidechainEntry(filePath: string, entry: Omit<SidechainEntry, "isSidechain" | "timestamp">): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.appendFileSync(filePath, `${JSON.stringify({ isSidechain: true, timestamp: new Date().toISOString(), ...entry })}\n`, "utf-8");
+}
+
+export function sidechainOutputPath(stateRoot: string, taskId: string): string {
+	return path.join(stateRoot, "agents", taskId, "sidechain.output.jsonl");
+}
+
+export function eventToSidechainType(event: unknown): string | undefined {
+	if (!event || typeof event !== "object" || Array.isArray(event)) return undefined;
+	const type = (event as { type?: unknown }).type;
+	if (type === "message_start" || type === "message_update" || type === "message_end") return "message";
+	if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") return "tool";
+	return typeof type === "string" ? type : undefined;
+}

package/src/runtime/task-runner.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import type { AgentConfig } from "../agents/agent-config.ts";
+import type { CrewLimitsConfig, CrewRuntimeConfig } from "../config/config.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent } from "../state/event-log.ts";
@@ -7,7 +8,7 @@ import { saveRunManifest, saveRunTasks } from "../state/state-store.ts";
 import { createTaskClaim } from "../state/task-claims.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
-import { captureWorktreeDiff, prepareTaskWorkspace } from "../worktree/worktree-manager.ts";
+import { captureWorktreeDiff, captureWorktreeDiffStat, prepareTaskWorkspace } from "../worktree/worktree-manager.ts";
 import { buildModelCandidates, formatModelAttemptNote, isRetryableModelFailure, type ModelAttemptSummary } from "./model-fallback.ts";
 import { parsePiJsonOutput, type ParsedPiJsonOutput } from "./pi-json-output.ts";
 import { runChildPi } from "./child-pi.ts";
@@ -18,7 +19,9 @@ import { permissionForRole } from "./role-permission.ts";
 import { collectDependencyOutputContext, renderDependencyOutputContext, writeTaskInputsArtifact, writeTaskSharedOutput } from "./task-output-context.ts";
 import { appendCrewAgentEvent, appendCrewAgentOutput, emptyCrewAgentProgress, recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { parseSessionUsage } from "./session-usage.ts";
-import type { CrewAgentProgress } from "./crew-agent-runtime.ts";
+import type { CrewAgentProgress, CrewRuntimeKind } from "./crew-agent-runtime.ts";
+import { buildMemoryBlock } from "./agent-memory.ts";
+import { runLiveSessionTask } from "./live-session-runtime.ts";
 
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
@@ -28,6 +31,12 @@ export interface TaskRunnerInput {
 	agent: AgentConfig;
 	signal?: AbortSignal;
 	executeWorkers: boolean;
+	runtimeKind?: CrewRuntimeKind;
+	runtimeConfig?: CrewRuntimeConfig;
+	parentContext?: string;
+	parentModel?: unknown;
+	modelRegistry?: unknown;
+	limits?: CrewLimitsConfig;
 	dependencyContextText?: string;
 }
 
@@ -55,7 +64,8 @@ function coordinationBridgeInstructions(task: TeamTaskState): string {
 	].join("\n");
 }
 
-function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState): string {
+function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: TeamTaskState, agent?: AgentConfig): string {
+	const memoryBlock = agent?.memory ? buildMemoryBlock(agent.name, agent.memory, task.cwd, Boolean(agent.tools?.some((tool) => tool === "write" || tool === "edit"))) : "";
 	return [
 		"# pi-crew Worker Runtime Context",
 		`Run ID: ${manifest.runId}`,
@@ -86,6 +96,7 @@ function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: T
 		task.taskPacket ? renderTaskPacket(task.taskPacket) : "",
 		"",
 		(inputDependencyContext(task) || ""),
+		memoryBlock,
 		"Task:",
 		step.task.replaceAll("{goal}", manifest.goal),
 	].join("\n");
@@ -190,6 +201,9 @@ function applyAgentProgressEvent(progress: CrewAgentProgress, event: unknown, st
 		next.currentToolArgs = undefined;
 		next.currentToolStartedAt = undefined;
 	}
+	if ((obj?.type === "tool_execution_error" || obj?.type === "tool_execution_failed") && next.currentTool) {
+		next.failedTool = next.currentTool;
+	}
 	const usage = eventUsage(event);
 	if (usage) {
 		next.tokens = (usage.input ?? 0) + (usage.output ?? 0);
@@ -222,12 +236,13 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		...(dependencyContextText ? { dependencyContextText } : {}),
 	} as TeamTaskState;
 	let tasks = updateTask(input.tasks, task);
+	const runtimeKind = input.runtimeKind ?? (input.executeWorkers ? "child-process" : "scaffold");
 	saveRunTasks(manifest, tasks);
-	upsertCrewAgent(manifest, recordFromTask(manifest, task, input.executeWorkers ? "child-process" : "scaffold"));
-	appendEvent(manifest.eventsPath, { type: "task.started", runId: manifest.runId, taskId: task.id, data: { role: task.role, agent: task.agent, cwd: task.cwd, worktreePath: workspace.worktreePath, worktreeBranch: workspace.branch, worktreeReused: workspace.reused } });
+	upsertCrewAgent(manifest, recordFromTask(manifest, task, runtimeKind));
+	appendEvent(manifest.eventsPath, { type: "task.started", runId: manifest.runId, taskId: task.id, data: { role: task.role, agent: task.agent, runtime: runtimeKind, cwd: task.cwd, worktreePath: workspace.worktreePath, worktreeBranch: workspace.branch, worktreeReused: workspace.reused } });
 	const permissionMode = permissionForRole(task.role);
 
-	const prompt = renderTaskPrompt(manifest, input.step, task);
+	const prompt = renderTaskPrompt(manifest, input.step, task, input.agent);
 	const promptArtifact = writeArtifact(manifest.artifactsRoot, {
 		kind: "prompt",
 		relativePath: `prompts/${task.id}.md`,
@@ -243,7 +258,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 	let modelAttempts: ModelAttemptSummary[] | undefined;
 	let parsedOutput: ParsedPiJsonOutput | undefined;
 
-	let startupEvidence = createStartupEvidence({ command: input.executeWorkers ? "pi" : "safe-scaffold", startedAt: new Date(task.startedAt ?? new Date().toISOString()), finishedAt: new Date(), promptSentAt: new Date(task.startedAt ?? new Date().toISOString()), promptAccepted: true, exitCode: 0 });
+	let startupEvidence = createStartupEvidence({ command: runtimeKind === "child-process" ? "pi" : runtimeKind === "live-session" ? "live-session" : "safe-scaffold", startedAt: new Date(task.startedAt ?? new Date().toISOString()), finishedAt: new Date(), promptSentAt: new Date(task.startedAt ?? new Date().toISOString()), promptAccepted: true, exitCode: 0 });
 	const inputsArtifact = writeTaskInputsArtifact(manifest, task, dependencyContext);
 	const coordinationArtifact = writeArtifact(manifest.artifactsRoot, {
 		kind: "metadata",
@@ -251,7 +266,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		content: `${coordinationBridgeInstructions(task)}\n`,
 		producer: task.id,
 	});
-	if (input.executeWorkers) {
+	if (runtimeKind === "child-process") {
 		const candidates = buildModelCandidates(input.step.model ?? input.agent.model, input.agent.fallbackModels, undefined);
 		const attemptModels = candidates.length > 0 ? candidates : [input.step.model ?? input.agent.model];
 		const logs: string[] = [];
@@ -269,6 +284,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 				model,
 				signal: input.signal,
 				transcriptPath,
+				maxDepth: input.limits?.maxTaskDepth,
 				onStdoutLine: (line) => appendCrewAgentOutput(manifest, task.id, line),
 				onJsonEvent: (event) => {
 					appendCrewAgentEvent(manifest, task.id, event);
@@ -320,6 +336,55 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 				producer: task.id,
 			});
 		}
+	} else if (runtimeKind === "live-session") {
+		const transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
+		const attemptStartedAt = new Date();
+		const liveResult = await runLiveSessionTask({
+			manifest,
+			task,
+			step: input.step,
+			agent: input.agent,
+			prompt,
+			signal: input.signal,
+			transcriptPath,
+			runtimeConfig: input.runtimeConfig,
+			parentContext: input.parentContext,
+			parentModel: input.parentModel,
+			modelRegistry: input.modelRegistry,
+			onOutput: (text) => appendCrewAgentOutput(manifest, task.id, text),
+			onEvent: (event) => {
+				appendCrewAgentEvent(manifest, task.id, event);
+				task = { ...task, agentProgress: applyAgentProgressEvent(task.agentProgress ?? emptyCrewAgentProgress(), event, task.startedAt) };
+				tasks = updateTask(tasks, task);
+				upsertCrewAgent(manifest, recordFromTask(manifest, task, "live-session"));
+				appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, taskId: task.id, data: { event } });
+			},
+		});
+		startupEvidence = createStartupEvidence({ command: "live-session", startedAt: attemptStartedAt, finishedAt: new Date(), promptSentAt: attemptStartedAt, promptAccepted: liveResult.exitCode === 0 && !liveResult.error, stderr: liveResult.stderr, error: liveResult.error, exitCode: liveResult.exitCode });
+		exitCode = liveResult.exitCode;
+		error = liveResult.error || (liveResult.exitCode && liveResult.exitCode !== 0 ? liveResult.stderr || `Live session exited with ${liveResult.exitCode}` : undefined);
+		parsedOutput = { finalText: liveResult.stdout, textEvents: liveResult.stdout ? [liveResult.stdout] : [], jsonEvents: liveResult.jsonEvents, usage: liveResult.usage };
+		if (liveResult.usage) task = { ...task, usage: liveResult.usage, agentProgress: applyUsageToProgress(task.agentProgress, liveResult.usage) };
+		resultArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "result",
+			relativePath: `results/${task.id}.txt`,
+			content: liveResult.stdout || liveResult.stderr || "(no output)",
+			producer: task.id,
+		});
+		logArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "log",
+			relativePath: `logs/${task.id}.log`,
+			content: [`runtime=live-session`, `finalExitCode=${exitCode ?? "null"}`, `jsonEvents=${liveResult.jsonEvents}`, liveResult.usage ? `usage=${JSON.stringify(liveResult.usage)}` : "", "", "STDOUT:", liveResult.stdout, "", "STDERR:", liveResult.stderr].join("\n"),
+			producer: task.id,
+		});
+		if (fs.existsSync(transcriptPath)) {
+			transcriptArtifact = writeArtifact(manifest.artifactsRoot, {
+				kind: "log",
+				relativePath: `transcripts/${task.id}.jsonl`,
+				content: fs.readFileSync(transcriptPath, "utf-8"),
+				producer: task.id,
+			});
+		}
 	} else {
 		resultArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "result",
@@ -340,6 +405,12 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		content: captureWorktreeDiff(workspace.worktreePath),
 		producer: task.id,
 	}) : undefined;
+	const diffStatArtifact = workspace.worktreePath ? writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: `metadata/${task.id}.diff-stat.json`,
+		content: `${JSON.stringify({ ...captureWorktreeDiffStat(workspace.worktreePath), syntheticPaths: workspace.syntheticPaths ?? [], nodeModulesLinked: workspace.nodeModulesLinked ?? false }, null, 2)}\n`,
+		producer: task.id,
+	}) : undefined;
 
 	task = {
 		...task,
@@ -349,9 +420,9 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		modelAttempts,
 		usage: parsedOutput?.usage,
 		jsonEvents: parsedOutput?.jsonEvents,
-		agentProgress: task.agentProgress,
+		agentProgress: error && task.agentProgress?.currentTool ? { ...task.agentProgress, failedTool: task.agentProgress.currentTool } : task.agentProgress,
 		error,
-		verification: createVerificationEvidence(taskPacket.verification, !error, error ? `Task failed: ${error}` : input.executeWorkers ? "Worker finished without reporting a verification failure." : "Safe scaffold mode; verification commands were not executed."),
+		verification: createVerificationEvidence(taskPacket.verification, !error, error ? `Task failed: ${error}` : runtimeKind === "scaffold" ? "Safe scaffold mode; verification commands were not executed." : `${runtimeKind} worker finished without reporting a verification failure.`),
 		promptArtifact,
 		resultArtifact,
 		claim: undefined,
@@ -385,10 +456,10 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		content: `${JSON.stringify({ role: task.role, permissionMode }, null, 2)}\n`,
 		producer: task.id,
 	});
-	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, promptArtifact, resultArtifact, inputsArtifact, coordinationArtifact, packetArtifact, verificationArtifact, startupArtifact, permissionArtifact, ...(sharedOutputArtifact ? [sharedOutputArtifact] : []), ...(logArtifact ? [logArtifact] : []), ...(transcriptArtifact ? [transcriptArtifact] : []), ...(diffArtifact ? [diffArtifact] : [])] };
+	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, promptArtifact, resultArtifact, inputsArtifact, coordinationArtifact, packetArtifact, verificationArtifact, startupArtifact, permissionArtifact, ...(sharedOutputArtifact ? [sharedOutputArtifact] : []), ...(logArtifact ? [logArtifact] : []), ...(transcriptArtifact ? [transcriptArtifact] : []), ...(diffArtifact ? [diffArtifact] : []), ...(diffStatArtifact ? [diffStatArtifact] : [])] };
 	saveRunManifest(manifest);
 	saveRunTasks(manifest, tasks);
-	upsertCrewAgent(manifest, recordFromTask(manifest, task, input.executeWorkers ? "child-process" : "scaffold"));
+	upsertCrewAgent(manifest, recordFromTask(manifest, task, runtimeKind));
 	appendEvent(manifest.eventsPath, { type: error ? "task.failed" : "task.completed", runId: manifest.runId, taskId: task.id, message: error });
 	return { manifest, tasks };
 }

package/src/runtime/team-runner.ts

@@ -27,6 +27,9 @@ export interface ExecuteTeamRunInput {
 	limits?: CrewLimitsConfig;
 	runtime?: CrewRuntimeCapabilities;
 	runtimeConfig?: CrewRuntimeConfig;
+	parentContext?: string;
+	parentModel?: unknown;
+	modelRegistry?: unknown;
 	signal?: AbortSignal;
 }
 
@@ -174,7 +177,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		const results = await Promise.all(readyBatch.map((task) => {
 			const step = findStep(input.workflow, task);
 			const agent = findAgent(input.agents, task);
-			return runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
+			return runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers, runtimeKind: input.runtime?.kind, runtimeConfig: input.runtimeConfig, parentContext: input.parentContext, parentModel: input.parentModel, modelRegistry: input.modelRegistry, limits: input.limits });
 		}));
 		manifest = { ...results.at(-1)!.manifest, artifacts: mergeArtifacts([manifest.artifacts, ...results.map((item) => item.manifest.artifacts)].flat()) };
 		tasks = mergeTaskUpdates(tasks, results);

package/src/state/event-log.ts

@@ -94,6 +94,25 @@ export function readEvents(eventsPath: string): TeamEvent[] {
 		.map((line) => JSON.parse(line) as TeamEvent);
 }
 
+export interface EventCursorOptions {
+	sinceSeq?: number;
+	limit?: number;
+}
+
+function positiveInteger(value: number | undefined): number | undefined {
+	return value !== undefined && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+export function readEventsCursor(eventsPath: string, options: EventCursorOptions = {}): { events: TeamEvent[]; nextSeq: number; total: number } {
+	const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
+	const limit = positiveInteger(options.limit);
+	const all = readEvents(eventsPath);
+	const filtered = all.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
+	const events = limit !== undefined ? filtered.slice(0, limit) : filtered;
+	const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+	return { events, nextSeq: returnedMaxSeq, total: filtered.length };
+}
+
 export function dedupeTerminalEvents(events: TeamEvent[]): TeamEvent[] {
 	const seen = new Set<string>();
 	const output: TeamEvent[] = [];

package/src/ui/run-dashboard.ts

@@ -1,5 +1,7 @@
 import * as fs from "node:fs";
 import type { TeamRunManifest } from "../state/types.ts";
+import { readCrewAgents } from "../runtime/crew-agent-records.ts";
+import type { CrewAgentRecord } from "../runtime/crew-agent-runtime.ts";
 
 interface DashboardComponent {
 	invalidate(): void;
@@ -7,17 +9,43 @@ interface DashboardComponent {
 	handleInput(data: string): void;
 }
 
-export type RunDashboardAction = "status" | "summary" | "artifacts" | "api" | "reload";
+export type RunDashboardAction = "status" | "summary" | "artifacts" | "api" | "events" | "agents" | "agent-events" | "agent-output" | "agent-transcript" | "reload";
 export interface RunDashboardSelection {
 	runId: string;
 	action: RunDashboardAction;
 }
 
+const ANSI_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+
+function visibleLength(value: string): number {
+	return value.replace(ANSI_PATTERN, "").length;
+}
+
 function truncate(value: string, width: number): string {
 	if (width <= 0) return "";
-	if (value.length <= width) return value;
+	if (visibleLength(value) <= width) return value;
 	if (width <= 1) return "…";
-	return `${value.slice(0, width - 1)}…`;
+	let output = "";
+	let visible = 0;
+	for (let index = 0; index < value.length;) {
+		const slice = value.slice(index);
+		const ansi = slice.match(/^\u001b\[[0-?]*[ -/]*[@-~]/);
+		if (ansi?.[0]) {
+			output += ansi[0];
+			index += ansi[0].length;
+			continue;
+		}
+		const char = value[index]!;
+		if (visible >= width - 1) break;
+		output += char;
+		visible += 1;
+		index += char.length;
+	}
+	return `${output}\u001b[0m…`;
+}
+
+function padVisible(value: string, width: number): string {
+	return `${value}${" ".repeat(Math.max(0, width - visibleLength(value)))}`;
 }
 
 function statusIcon(status: string): string {
@@ -40,6 +68,30 @@ function readProgressPreview(run: TeamRunManifest, maxLines = 5): string[] {
 	}
 }
 
+function agentPreviewLine(agent: CrewAgentRecord): string {
+	const stats = [
+		agent.progress?.activityState,
+		agent.progress?.currentTool ? `tool=${agent.progress.currentTool}` : undefined,
+		agent.toolUses !== undefined ? `${agent.toolUses} tools` : undefined,
+		agent.progress?.tokens !== undefined ? `${agent.progress.tokens} tok` : undefined,
+		agent.progress?.turns !== undefined ? `${agent.progress.turns} turns` : undefined,
+		agent.progress?.failedTool ? `failedTool=${agent.progress.failedTool}` : undefined,
+	].filter((part): part is string => Boolean(part));
+	const recent = agent.progress?.recentOutput?.at(-1);
+	return `Agent: ${statusIcon(agent.status)} ${agent.taskId} ${agent.role}->${agent.agent}${stats.length ? ` · ${stats.join(" · ")}` : ""}${recent ? ` ⎿ ${recent}` : ""}`;
+}
+
+function readAgentPreview(run: TeamRunManifest, maxLines = 5): string[] {
+	try {
+		const agents = readCrewAgents(run);
+		if (!agents.length) return ["Agents: (none)"];
+		return ["Agents:", ...agents.slice(0, maxLines).map(agentPreviewLine), ...(agents.length > maxLines ? [`Agents: +${agents.length - maxLines} more`] : [])];
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return [`Agents: failed to read (${message})`];
+	}
+}
+
 function countByStatus(runs: TeamRunManifest[]): string {
 	const counts = new Map<string, number>();
 	for (const run of runs) counts.set(run.status, (counts.get(run.status) ?? 0) + 1);
@@ -64,19 +116,19 @@ export class RunDashboard implements DashboardComponent {
 		const borderWidth = Math.min(innerWidth, Math.max(0, width - 2));
 		const lines = [
 			`╭${"─".repeat(borderWidth)}╮`,
-			`│ ${truncate("pi-crew dashboard", innerWidth - 1).padEnd(innerWidth - 1)}│`,
-			`│ ${truncate("↑/↓/j/k select • r reload • p progress • s/u/a/i actions • q close", innerWidth - 1).padEnd(innerWidth - 1)}│`,
-			`│ ${truncate(`Runs: ${this.runs.length} • ${countByStatus(this.runs)}`, innerWidth - 1).padEnd(innerWidth - 1)}│`,
+			`│ ${padVisible(truncate("pi-crew dashboard", innerWidth - 1), innerWidth - 1)}│`,
+			`│ ${padVisible(truncate("↑/↓/j/k select • r reload • p progress • s/u/a/i actions • d agents • e/v/o viewers • q close", innerWidth - 1), innerWidth - 1)}│`,
+			`│ ${padVisible(truncate(`Runs: ${this.runs.length} • ${countByStatus(this.runs)}`, innerWidth - 1), innerWidth - 1)}│`,
 			`├${"─".repeat(borderWidth)}┤`,
 		];
 		if (this.runs.length === 0) {
-			lines.push(`│ ${truncate("No runs found.", innerWidth - 1).padEnd(innerWidth - 1)}│`);
+			lines.push(`│ ${padVisible(truncate("No runs found.", innerWidth - 1), innerWidth - 1)}│`);
 		} else {
 			for (let i = 0; i < Math.min(this.runs.length, 10); i++) {
 				const run = this.runs[i]!;
 				const marker = i === this.selected ? "›" : " ";
 				const text = `${marker} ${statusIcon(run.status)} ${run.runId} ${run.status} ${run.team}/${run.workflow ?? "none"} ${run.goal}`;
-				lines.push(`│ ${truncate(text, innerWidth - 1).padEnd(innerWidth - 1)}│`);
+				lines.push(`│ ${padVisible(truncate(text, innerWidth - 1), innerWidth - 1)}│`);
 			}
 			const selectedRun = this.runs[this.selected];
 			if (selectedRun) {
@@ -90,8 +142,8 @@ export class RunDashboard implements DashboardComponent {
 					selectedRun.async ? `Async: pid=${selectedRun.async.pid ?? "unknown"} log=${selectedRun.async.logPath}` : "Async: no",
 					`Goal: ${selectedRun.goal}`,
 				];
-				for (const detail of [...details, ...readProgressPreview(selectedRun, this.showFullProgress ? 20 : 5)]) {
-					lines.push(`│ ${truncate(detail, innerWidth - 1).padEnd(innerWidth - 1)}│`);
+				for (const detail of [...details, ...readAgentPreview(selectedRun), ...readProgressPreview(selectedRun, this.showFullProgress ? 20 : 5)]) {
+					lines.push(`│ ${padVisible(truncate(detail, innerWidth - 1), innerWidth - 1)}│`);
 				}
 			}
 		}
@@ -124,6 +176,26 @@ export class RunDashboard implements DashboardComponent {
 			this.done(runId ? { runId, action: "api" } : undefined);
 			return;
 		}
+		if (data === "d") {
+			const runId = this.runs[this.selected]?.runId;
+			this.done(runId ? { runId, action: "agents" } : undefined);
+			return;
+		}
+		if (data === "e") {
+			const runId = this.runs[this.selected]?.runId;
+			this.done(runId ? { runId, action: "agent-events" } : undefined);
+			return;
+		}
+		if (data === "o") {
+			const runId = this.runs[this.selected]?.runId;
+			this.done(runId ? { runId, action: "agent-output" } : undefined);
+			return;
+		}
+		if (data === "v") {
+			const runId = this.runs[this.selected]?.runId;
+			this.done(runId ? { runId, action: "agent-transcript" } : undefined);
+			return;
+		}
 		if (data === "r") {
 			this.done({ runId: this.runs[this.selected]?.runId ?? "", action: "reload" });
 			return;

package/src/utils/file-coalescer.ts

@@ -0,0 +1,33 @@
+interface TimerApi {
+	setTimeout(handler: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+const defaultTimerApi: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export interface FileCoalescer {
+	schedule(file: string, delayMs?: number): boolean;
+	clear(): void;
+}
+
+export function createFileCoalescer(handler: (file: string) => void, defaultDelayMs: number, timerApi: TimerApi = defaultTimerApi): FileCoalescer {
+	const pending = new Map<string, unknown>();
+	return {
+		schedule(file, delayMs = defaultDelayMs) {
+			if (pending.has(file)) return false;
+			const timer = timerApi.setTimeout(() => {
+				pending.delete(file);
+				handler(file);
+			}, delayMs);
+			pending.set(file, timer);
+			return true;
+		},
+		clear() {
+			for (const timer of pending.values()) timerApi.clearTimeout(timer);
+			pending.clear();
+		},
+	};
+}

package/src/worktree/worktree-manager.ts

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadConfig } from "../config/config.ts";
@@ -9,6 +9,15 @@ export interface PreparedTaskWorkspace {
 	worktreePath?: string;
 	branch?: string;
 	reused?: boolean;
+	nodeModulesLinked?: boolean;
+	syntheticPaths?: string[];
+}
+
+export interface WorktreeDiffStat {
+	filesChanged: number;
+	insertions: number;
+	deletions: number;
+	diffStat: string;
 }
 
 function git(cwd: string, args: string[]): string {
@@ -30,6 +39,47 @@ export function assertCleanLeader(repoRoot: string): void {
 	}
 }
 
+function linkNodeModulesIfPresent(repoRoot: string, worktreePath: string): boolean {
+	const source = path.join(repoRoot, "node_modules");
+	const target = path.join(worktreePath, "node_modules");
+	if (!fs.existsSync(source) || fs.existsSync(target)) return false;
+	try {
+		fs.symlinkSync(source, target, process.platform === "win32" ? "junction" : "dir");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function normalizeSyntheticPath(worktreePath: string, rawPath: string): string {
+	const resolved = path.resolve(worktreePath, rawPath);
+	const relative = path.relative(worktreePath, resolved);
+	if (!relative || relative === "." || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`synthetic path escapes worktree: ${rawPath}`);
+	return path.normalize(relative);
+}
+
+function runSetupHook(manifest: TeamRunManifest, task: TeamTaskState, repoRoot: string, worktreePath: string, branch: string): string[] {
+	const cfg = loadConfig(manifest.cwd).config.worktree;
+	if (!cfg?.setupHook) return [];
+	const hookPath = path.isAbsolute(cfg.setupHook) ? cfg.setupHook : path.resolve(repoRoot, cfg.setupHook);
+	if (!fs.existsSync(hookPath) || fs.statSync(hookPath).isDirectory()) throw new Error(`worktree setup hook not found or not a file: ${hookPath}`);
+	const nodeHook = hookPath.endsWith(".js") || hookPath.endsWith(".cjs") || hookPath.endsWith(".mjs");
+	const result = spawnSync(nodeHook ? process.execPath : hookPath, nodeHook ? [hookPath] : [], {
+		cwd: worktreePath,
+		encoding: "utf-8",
+		input: JSON.stringify({ version: 1, repoRoot, worktreePath, agentCwd: worktreePath, branch, runId: manifest.runId, taskId: task.id, agent: task.agent }),
+		timeout: cfg.setupHookTimeoutMs ?? 30_000,
+		shell: false,
+	});
+	if (result.error) throw new Error(`worktree setup hook failed: ${result.error.message}`);
+	if (result.status !== 0) throw new Error(`worktree setup hook failed with exit code ${result.status}: ${result.stderr || result.stdout || "no output"}`);
+	const trimmed = result.stdout.trim();
+	if (!trimmed) return [];
+	const parsed = JSON.parse(trimmed) as { syntheticPaths?: unknown };
+	if (!Array.isArray(parsed.syntheticPaths)) return [];
+	return [...new Set(parsed.syntheticPaths.filter((entry): entry is string => typeof entry === "string").map((entry) => normalizeSyntheticPath(worktreePath, entry)))];
+}
+
 export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskState): PreparedTaskWorkspace {
 	if (manifest.workspaceMode !== "worktree") return { cwd: task.cwd };
 	const repoRoot = findGitRoot(manifest.cwd);
@@ -47,7 +97,28 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 		return { cwd: worktreePath, worktreePath, branch, reused: true };
 	}
 	git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
-	return { cwd: worktreePath, worktreePath, branch, reused: false };
+	const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
+	const nodeModulesLinked = loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
+	return { cwd: worktreePath, worktreePath, branch, reused: false, nodeModulesLinked, syntheticPaths };
+}
+
+export function captureWorktreeDiffStat(worktreePath: string): WorktreeDiffStat {
+	try {
+		const diffStat = git(worktreePath, ["diff", "--stat"]);
+		const numstat = git(worktreePath, ["diff", "--numstat"]);
+		let filesChanged = 0;
+		let insertions = 0;
+		let deletions = 0;
+		for (const line of numstat.split(/\r?\n/).filter(Boolean)) {
+			const [add, del] = line.split(/\s+/);
+			filesChanged += 1;
+			insertions += Number(add) || 0;
+			deletions += Number(del) || 0;
+		}
+		return { filesChanged, insertions, deletions, diffStat };
+	} catch {
+		return { filesChanged: 0, insertions: 0, deletions: 0, diffStat: "" };
+	}
 }
 
 export function captureWorktreeDiff(worktreePath: string): string {