pi-crew 0.1.6 → 0.1.8

package/src/extension/team-tool.ts

@@ -21,7 +21,7 @@ import { getPiSpawnCommand } from "../runtime/pi-spawn.ts";
 import { executeTeamRun } from "../runtime/team-runner.ts";
 import { spawnBackgroundTeamRun } from "../runtime/async-runner.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../runtime/process-status.ts";
-import { appendEvent, readEvents } from "../state/event-log.ts";
+import { appendEvent, readEvents, readEventsCursor } from "../state/event-log.ts";
 import { cleanupRunWorktrees } from "../worktree/cleanup.ts";
 import { piTeamsHelp } from "./help.ts";
 import { initializeProject } from "./project-init.ts";
@@ -35,10 +35,15 @@ import { formatValidationReport, validateResources } from "./validate-resources.
 import { formatRecommendation, recommendTeam } from "./team-recommendation.ts";
 import { toolResult, type PiTeamsToolResult } from "./tool-result.ts";
 import { touchWorkerHeartbeat } from "../runtime/worker-heartbeat.ts";
-import { agentEventsPath, agentOutputPath, readCrewAgentEvents, readCrewAgentStatus, readCrewAgents } from "../runtime/crew-agent-records.ts";
+import { agentEventsPath, agentOutputPath, readCrewAgentEvents, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../runtime/crew-agent-records.ts";
 import { resolveCrewRuntime } from "../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../runtime/live-session-runtime.ts";
 import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../runtime/agent-control.ts";
+import { buildAgentDashboard, readAgentOutput } from "../runtime/agent-observability.ts";
+import { readForegroundControlStatus, writeForegroundInterruptRequest } from "../runtime/foreground-control.ts";
+import { listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../runtime/live-agent-manager.ts";
+import { appendLiveAgentControlRequest } from "../runtime/live-agent-control.ts";
+import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
 
 export interface TeamToolDetails {
 	action: string;
@@ -47,7 +52,11 @@ export interface TeamToolDetails {
 	artifactsRoot?: string;
 }
 
-type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "model">>;
+type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "model">> & {
+	modelRegistry?: unknown;
+	sessionManager?: { getBranch?: () => unknown[] };
+	events?: { emit?: (event: string, data: unknown) => void };
+};
 
 function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
 	return toolResult(text, details, isError);
@@ -57,6 +66,29 @@ function formatScoped(name: string, source: string, description: string): string
 	return `- ${name} (${source}): ${description}`;
 }
 
+function extractTextContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.map((part) => part && typeof part === "object" && !Array.isArray(part) && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
+}
+
+function buildParentContext(ctx: TeamContext): string | undefined {
+	const branch = ctx.sessionManager?.getBranch?.();
+	if (!Array.isArray(branch) || branch.length === 0) return undefined;
+	const parts: string[] = [];
+	for (const entry of branch.slice(-20)) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const record = entry as { type?: unknown; message?: unknown; summary?: unknown };
+		if (record.type === "compaction" && typeof record.summary === "string") parts.push(`[Summary]: ${record.summary}`);
+		const message = record.message && typeof record.message === "object" && !Array.isArray(record.message) ? record.message as { role?: unknown; content?: unknown } : undefined;
+		if (!message || (message.role !== "user" && message.role !== "assistant")) continue;
+		const text = extractTextContent(message.content).trim();
+		if (text) parts.push(`[${message.role === "user" ? "User" : "Assistant"}]: ${text}`);
+	}
+	if (!parts.length) return undefined;
+	return [`# Parent Conversation Context`, "The following context was inherited from the parent Pi session. Treat it as reference-only.", "", parts.join("\n\n")].join("\n");
+}
+
 export function handleList(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	const resource = params.resource;
 	const blocks: string[] = [];
@@ -134,6 +166,18 @@ function commandExists(command: string, args: string[]): { ok: boolean; detail:
 	return { ok: false, detail: output.error?.message ?? firstOutputLine(output.stdout, output.stderr) };
 }
 
+function effectiveRunConfig(base: PiTeamsConfig, rawOverride: unknown): PiTeamsConfig {
+	const patch = configPatchFromConfig(rawOverride);
+	return {
+		...base,
+		...patch,
+		limits: patch.limits ? { ...(base.limits ?? {}), ...patch.limits } : base.limits,
+		runtime: patch.runtime ? { ...(base.runtime ?? {}), ...patch.runtime } : base.runtime,
+		control: patch.control ? { ...(base.control ?? {}), ...patch.control } : base.control,
+		worktree: patch.worktree ? { ...(base.worktree ?? {}), ...patch.worktree } : base.worktree,
+	};
+}
+
 function piCommandExists(): { ok: boolean; detail: string } {
 	const spec = getPiSpawnCommand(["--version"]);
 	const output = spawnSync(spec.command, spec.args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
@@ -259,9 +303,10 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		return result(text, { action: "run", status: "ok", runId: updatedManifest.runId, artifactsRoot: updatedManifest.artifactsRoot });
 	}
 
-	const runtime = await resolveCrewRuntime(loadedConfig.config);
+	const runtime = await resolveCrewRuntime(effectiveRunConfig(loadedConfig.config, params.config));
 	const executeWorkers = runtime.kind === "child-process";
-	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime });
+	const executedConfig = effectiveRunConfig(loadedConfig.config, params.config);
+	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry });
 	const text = [
 		`Created pi-crew run ${executed.manifest.runId}.`,
 		`Team: ${team.name}`,
@@ -272,9 +317,11 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		`Artifacts: ${executed.manifest.artifactsRoot}`,
 		"",
 		`Runtime: ${runtime.kind}${runtime.fallback ? ` (fallback from ${runtime.requestedMode})` : ""}${runtime.reason ? ` - ${runtime.reason}` : ""}`,
-		executeWorkers
+		runtime.kind === "child-process"
 			? "Child Pi worker execution was enabled."
-			: "Safe scaffold mode: child Pi workers were not launched. Set PI_TEAMS_EXECUTE_WORKERS=1 or runtime.mode=child-process to enable real worker execution.",
+			: runtime.kind === "live-session"
+				? "Experimental live-session worker execution was enabled."
+				: "Safe scaffold mode: child Pi workers were not launched. Set PI_CREW_EXECUTE_WORKERS=1, PI_TEAMS_EXECUTE_WORKERS=1, or runtime.mode=child-process to enable real worker execution.",
 	].join("\n");
 	return result(text, { action: "run", status: executed.manifest.status === "failed" ? "error" : "ok", runId: executed.manifest.runId, artifactsRoot: executed.manifest.artifactsRoot }, executed.manifest.status === "failed");
 }
@@ -382,7 +429,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		const loadedConfig = loadConfig(ctx.cwd);
 		const runtime = await resolveCrewRuntime(loadedConfig.config);
 		const executeWorkers = runtime.kind === "child-process";
-		const executed = await executeTeamRun({ manifest: loaded.manifest, tasks: resetTasks, team, workflow, agents: allAgents(discoverAgents(ctx.cwd)), executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime });
+		const executed = await executeTeamRun({ manifest: loaded.manifest, tasks: resetTasks, team, workflow, agents: allAgents(discoverAgents(ctx.cwd)), executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry });
 		return result([`Resumed run ${executed.manifest.runId}.`, `Status: ${executed.manifest.status}`, `Tasks: ${executed.tasks.length}`, `Artifacts: ${executed.manifest.artifactsRoot}`].join("\n"), { action: "resume", status: executed.manifest.status === "failed" ? "error" : "ok", runId: executed.manifest.runId, artifactsRoot: executed.manifest.artifactsRoot }, executed.manifest.status === "failed");
 	});
 }
@@ -458,12 +505,39 @@ function autonomousPatchFromConfig(config: unknown): PiTeamsAutonomousConfig {
 function configPatchFromConfig(config: unknown): PiTeamsConfig {
 	const cfg = configRecord(config);
 	const control = configRecord(cfg.control);
+	const runtime = configRecord(cfg.runtime);
+	const limits = configRecord(cfg.limits);
+	const worktree = configRecord(cfg.worktree);
 	return {
 		asyncByDefault: typeof cfg.asyncByDefault === "boolean" ? cfg.asyncByDefault : undefined,
 		executeWorkers: typeof cfg.executeWorkers === "boolean" ? cfg.executeWorkers : undefined,
 		notifierIntervalMs: typeof cfg.notifierIntervalMs === "number" && Number.isFinite(cfg.notifierIntervalMs) ? cfg.notifierIntervalMs : undefined,
 		requireCleanWorktreeLeader: typeof cfg.requireCleanWorktreeLeader === "boolean" ? cfg.requireCleanWorktreeLeader : undefined,
 		autonomous: typeof cfg.autonomous === "object" && cfg.autonomous !== null && !Array.isArray(cfg.autonomous) ? autonomousPatchFromConfig(cfg.autonomous) : undefined,
+		limits: Object.keys(limits).length > 0 ? {
+			maxConcurrentWorkers: typeof limits.maxConcurrentWorkers === "number" && Number.isInteger(limits.maxConcurrentWorkers) && limits.maxConcurrentWorkers > 0 ? limits.maxConcurrentWorkers : undefined,
+			maxTaskDepth: typeof limits.maxTaskDepth === "number" && Number.isInteger(limits.maxTaskDepth) && limits.maxTaskDepth > 0 ? limits.maxTaskDepth : undefined,
+			maxChildrenPerTask: typeof limits.maxChildrenPerTask === "number" && Number.isInteger(limits.maxChildrenPerTask) && limits.maxChildrenPerTask > 0 ? limits.maxChildrenPerTask : undefined,
+			maxRunMinutes: typeof limits.maxRunMinutes === "number" && Number.isInteger(limits.maxRunMinutes) && limits.maxRunMinutes > 0 ? limits.maxRunMinutes : undefined,
+			maxRetriesPerTask: typeof limits.maxRetriesPerTask === "number" && Number.isInteger(limits.maxRetriesPerTask) && limits.maxRetriesPerTask > 0 ? limits.maxRetriesPerTask : undefined,
+			maxTasksPerRun: typeof limits.maxTasksPerRun === "number" && Number.isInteger(limits.maxTasksPerRun) && limits.maxTasksPerRun > 0 ? limits.maxTasksPerRun : undefined,
+			heartbeatStaleMs: typeof limits.heartbeatStaleMs === "number" && Number.isInteger(limits.heartbeatStaleMs) && limits.heartbeatStaleMs > 0 ? limits.heartbeatStaleMs : undefined,
+		} : undefined,
+		runtime: Object.keys(runtime).length > 0 ? {
+			mode: runtime.mode === "auto" || runtime.mode === "scaffold" || runtime.mode === "child-process" || runtime.mode === "live-session" ? runtime.mode : undefined,
+			preferLiveSession: typeof runtime.preferLiveSession === "boolean" ? runtime.preferLiveSession : undefined,
+			allowChildProcessFallback: typeof runtime.allowChildProcessFallback === "boolean" ? runtime.allowChildProcessFallback : undefined,
+			maxTurns: typeof runtime.maxTurns === "number" && Number.isInteger(runtime.maxTurns) && runtime.maxTurns > 0 ? runtime.maxTurns : undefined,
+			graceTurns: typeof runtime.graceTurns === "number" && Number.isInteger(runtime.graceTurns) && runtime.graceTurns > 0 ? runtime.graceTurns : undefined,
+			inheritContext: typeof runtime.inheritContext === "boolean" ? runtime.inheritContext : undefined,
+			promptMode: runtime.promptMode === "replace" || runtime.promptMode === "append" ? runtime.promptMode : undefined,
+			groupJoin: runtime.groupJoin === "off" || runtime.groupJoin === "group" || runtime.groupJoin === "smart" ? runtime.groupJoin : undefined,
+		} : undefined,
+		worktree: Object.keys(worktree).length > 0 ? {
+			setupHook: typeof worktree.setupHook === "string" && worktree.setupHook.trim() ? worktree.setupHook.trim() : undefined,
+			setupHookTimeoutMs: typeof worktree.setupHookTimeoutMs === "number" && Number.isInteger(worktree.setupHookTimeoutMs) && worktree.setupHookTimeoutMs > 0 ? worktree.setupHookTimeoutMs : undefined,
+			linkNodeModules: typeof worktree.linkNodeModules === "boolean" ? worktree.linkNodeModules : undefined,
+		} : undefined,
 		control: Object.keys(control).length > 0 ? {
 			enabled: typeof control.enabled === "boolean" ? control.enabled : undefined,
 			needsAttentionAfterMs: typeof control.needsAttentionAfterMs === "number" && Number.isInteger(control.needsAttentionAfterMs) && control.needsAttentionAfterMs > 0 ? control.needsAttentionAfterMs : undefined,
@@ -575,7 +649,12 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		return result(JSON.stringify(task, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "read-events") {
-		return result(JSON.stringify(readEvents(loaded.manifest.eventsPath), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		const sinceSeq = typeof cfg.sinceSeq === "number" ? cfg.sinceSeq : undefined;
+		const limit = typeof cfg.limit === "number" ? cfg.limit : undefined;
+		const payload = sinceSeq !== undefined || limit !== undefined
+			? readEventsCursor(loaded.manifest.eventsPath, { sinceSeq, limit })
+			: { events: readEvents(loaded.manifest.eventsPath), nextSeq: undefined, total: undefined };
+		return result(JSON.stringify(payload, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "runtime-capabilities") {
 		const loadedConfig = loadConfig(ctx.cwd);
@@ -604,18 +683,43 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	}
 	if (operation === "read-agent-events") {
 		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
-		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
-		if (!agent) return result("API read-agent-events requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-		return result(JSON.stringify({ path: agentEventsPath(loaded.manifest, agent.taskId), events: readCrewAgentEvents(loaded.manifest, agent.taskId) }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-events requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const sinceSeq = typeof cfg.sinceSeq === "number" ? cfg.sinceSeq : undefined;
+		const limit = typeof cfg.limit === "number" ? cfg.limit : undefined;
+		const payload = sinceSeq !== undefined || limit !== undefined
+			? readCrewAgentEventsCursor(loaded.manifest, agent.taskId, { sinceSeq, limit })
+			: { path: agentEventsPath(loaded.manifest, agent.taskId), events: readCrewAgentEvents(loaded.manifest, agent.taskId) };
+		return result(JSON.stringify(payload, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
 	if (operation === "read-agent-transcript") {
 		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
-		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
-		if (!agent) return result("API read-agent-transcript requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-transcript requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const transcriptPath = agent.transcriptPath && fs.existsSync(agent.transcriptPath) ? agent.transcriptPath : agentOutputPath(loaded.manifest, agent.taskId);
 		const text = fs.existsSync(transcriptPath) ? fs.readFileSync(transcriptPath, "utf-8") : "";
 		return result(text || `(no transcript at ${transcriptPath})`, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
+	if (operation === "read-agent-output") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agents = readCrewAgents(loaded.manifest);
+		const agent = agentId ? agents.find((item) => item.id === agentId || item.taskId === agentId) : agents[0];
+		if (!agent) return result("API read-agent-output requires config.agentId matching an agent id or task id, or at least one agent in the run.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const maxBytes = typeof cfg.maxBytes === "number" ? cfg.maxBytes : undefined;
+		return result(JSON.stringify(readAgentOutput(loaded.manifest, agent.taskId, maxBytes), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "agent-dashboard") {
+		return result(buildAgentDashboard(loaded.manifest).text, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "foreground-status") {
+		return result(JSON.stringify(readForegroundControlStatus(loaded.manifest, loaded.tasks), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "foreground-interrupt") {
+		const reason = typeof cfg.reason === "string" && cfg.reason.trim() ? cfg.reason.trim() : undefined;
+		return result(JSON.stringify(writeForegroundInterruptRequest(loaded.manifest, reason), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
 	if (operation === "nudge-agent") {
 		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
 		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
@@ -625,12 +729,34 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		appendEvent(loaded.manifest.eventsPath, { type: "agent.nudged", runId: loaded.manifest.runId, taskId: agent.taskId, message: messageText, data: { agentId: agent.id, mailboxMessageId: message.id } });
 		return result(JSON.stringify({ agentId: agent.id, mailboxMessage: message }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
+	if (operation === "list-live-agents") {
+		return result(JSON.stringify(listLiveAgents().filter((agent) => agent.runId === loaded.manifest.runId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
 	if (operation === "steer-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
-		const runtime = await resolveCrewRuntime(loadConfig(ctx.cwd).config);
-		if (!runtime.steer && operation === "steer-agent") return result(`Runtime '${runtime.kind}' does not support live steering. Use nudge-agent for mailbox-based child-process coordination.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-		if (!runtime.resume && operation === "resume-agent") return result(`Runtime '${runtime.kind}' does not support live resume.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-		if (operation === "interrupt-agent" && runtime.kind !== "live-session") return result(`Runtime '${runtime.kind}' does not expose per-agent interrupt yet. Use nudge-agent or cancel the run.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-		return result(`Operation '${operation}' is reserved for live-session runtime and is not active for this run yet.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		if (!agentId) return result(`API ${operation} requires config.agentId.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
+		const prompt = typeof cfg.prompt === "string" && cfg.prompt.trim() ? cfg.prompt.trim() : message;
+		try {
+			if (operation === "steer-agent") return result(JSON.stringify(await steerLiveAgent(agentId, message ?? "Please report current status and wrap up if possible."), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			if (operation === "resume-agent") {
+				if (!prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				return result(JSON.stringify(await resumeLiveAgent(agentId, prompt), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
+			return result(JSON.stringify(await stopLiveAgent(agentId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		} catch (error) {
+			const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+			if (!agent) {
+				const err = error instanceof Error ? error.message : String(error);
+				return result(err, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			}
+			if (operation === "resume-agent" && !prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: agent.taskId, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
+			publishLiveControlRealtime(request);
+			ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
+			appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
+			return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		}
 	}
 	if (operation === "read-mailbox") {
 		const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? cfg.direction as MailboxDirection : undefined;

package/src/prompt/prompt-runtime.ts

@@ -2,6 +2,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
+export const PI_CREW_INHERIT_PROJECT_CONTEXT_ENV = "PI_CREW_INHERIT_PROJECT_CONTEXT";
+export const PI_CREW_INHERIT_SKILLS_ENV = "PI_CREW_INHERIT_SKILLS";
 
 const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
 const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
@@ -13,6 +15,14 @@ function readBooleanEnv(name: string): boolean | undefined {
 	return value !== "0";
 }
 
+function readBooleanEnvAny(...names: string[]): boolean | undefined {
+	for (const name of names) {
+		const value = readBooleanEnv(name);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
 function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
 	let endIndex = prompt.length;
 	for (const header of nextHeaders) {
@@ -45,8 +55,8 @@ export function rewriteTeamWorkerPrompt(prompt: string, options: { inheritProjec
 
 export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", (event) => {
-		const inheritProjectContext = readBooleanEnv(PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
-		const inheritSkills = readBooleanEnv(PI_TEAMS_INHERIT_SKILLS_ENV);
+		const inheritProjectContext = readBooleanEnvAny(PI_CREW_INHERIT_PROJECT_CONTEXT_ENV, PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritSkills = readBooleanEnvAny(PI_CREW_INHERIT_SKILLS_ENV, PI_TEAMS_INHERIT_SKILLS_ENV);
 		if (inheritProjectContext === undefined && inheritSkills === undefined) return;
 		const rewritten = rewriteTeamWorkerPrompt(event.systemPrompt, {
 			inheritProjectContext: inheritProjectContext ?? true,

package/src/runtime/agent-memory.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type AgentMemoryScope = "user" | "project" | "local";
+const MAX_MEMORY_LINES = 200;
+
+export function isUnsafeMemoryName(name: string): boolean {
+	return !name || name.length > 128 || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+export function isSymlink(filePath: string): boolean {
+	try {
+		return fs.lstatSync(filePath).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+export function safeReadMemoryFile(filePath: string): string | undefined {
+	if (!fs.existsSync(filePath) || isSymlink(filePath)) return undefined;
+	try {
+		return fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+export function resolveMemoryDir(agentName: string, scope: AgentMemoryScope, cwd: string): string {
+	if (isUnsafeMemoryName(agentName)) throw new Error(`Unsafe agent name for memory directory: ${agentName}`);
+	if (scope === "user") return path.join(os.homedir(), ".pi", "agent-memory", agentName);
+	if (scope === "project") return path.join(cwd, ".pi", "agent-memory", agentName);
+	return path.join(cwd, ".pi", "agent-memory-local", agentName);
+}
+
+export function ensureMemoryDir(memoryDir: string): void {
+	if (fs.existsSync(memoryDir)) {
+		if (isSymlink(memoryDir)) throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+		return;
+	}
+	fs.mkdirSync(memoryDir, { recursive: true });
+}
+
+export function readMemoryIndex(memoryDir: string): string | undefined {
+	if (isSymlink(memoryDir)) return undefined;
+	const content = safeReadMemoryFile(path.join(memoryDir, "MEMORY.md"));
+	if (content === undefined) return undefined;
+	const lines = content.split(/\r?\n/);
+	return lines.length > MAX_MEMORY_LINES ? `${lines.slice(0, MAX_MEMORY_LINES).join("\n")}\n... (truncated at 200 lines)` : content;
+}
+
+export function buildMemoryBlock(agentName: string, scope: AgentMemoryScope, cwd: string, writable: boolean): string {
+	const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+	if (writable) ensureMemoryDir(memoryDir);
+	const existing = readMemoryIndex(memoryDir);
+	const mode = writable ? "read-write" : "read-only";
+	return [
+		`# Agent Memory (${mode})`,
+		`Memory scope: ${scope}`,
+		`Memory directory: ${memoryDir}`,
+		writable ? "Use this persistent directory to maintain useful long-term notes for this agent." : "You may reference existing memory, but do not create or modify memory files.",
+		"",
+		existing ? `## Current MEMORY.md\n${existing}` : "No MEMORY.md exists yet.",
+		writable ? [
+			"",
+			"## Memory Instructions",
+			"- Keep MEMORY.md concise (under 200 lines); store details in separate linked files.",
+			"- Reject stale memories; update or remove outdated notes.",
+			"- Use safe relative filenames inside the memory directory only.",
+		].join("\n") : "",
+	].filter(Boolean).join("\n");
+}

package/src/runtime/agent-observability.ts

@@ -0,0 +1,88 @@
+import * as fs from "node:fs";
+import type { TeamRunManifest } from "../state/types.ts";
+import { agentOutputPath, readCrewAgents } from "./crew-agent-records.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+export interface TextTailResult {
+	path: string;
+	text: string;
+	bytes: number;
+	truncated: boolean;
+}
+
+export function readTextTail(filePath: string, maxBytes = 64_000): TextTailResult {
+	if (!fs.existsSync(filePath)) return { path: filePath, text: "", bytes: 0, truncated: false };
+	const stat = fs.statSync(filePath);
+	const bytesToRead = Math.min(stat.size, Math.max(0, maxBytes));
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const buffer = Buffer.alloc(bytesToRead);
+		fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
+		return { path: filePath, text: buffer.toString("utf-8"), bytes: stat.size, truncated: stat.size > bytesToRead };
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function activityText(agent: CrewAgentRecord): string {
+	const parts: string[] = [];
+	if (agent.progress?.activityState) parts.push(agent.progress.activityState);
+	if (agent.progress?.currentTool) parts.push(`tool=${agent.progress.currentTool}`);
+	if (agent.toolUses !== undefined) parts.push(`tools=${agent.toolUses}`);
+	if (agent.progress?.tokens !== undefined) parts.push(`tokens=${agent.progress.tokens}`);
+	if (agent.progress?.turns !== undefined) parts.push(`turns=${agent.progress.turns}`);
+	if (agent.progress?.durationMs !== undefined) parts.push(`durationMs=${agent.progress.durationMs}`);
+	if (agent.progress?.failedTool) parts.push(`failedTool=${agent.progress.failedTool}`);
+	if (agent.progress?.recentOutput?.length) parts.push(`last=${agent.progress.recentOutput.at(-1)}`);
+	return parts.join(" ") || "idle";
+}
+
+function statusGlyph(status: CrewAgentRecord["status"]): string {
+	if (status === "completed") return "✓";
+	if (status === "failed") return "✗";
+	if (status === "running") return "▶";
+	if (status === "cancelled" || status === "stopped") return "■";
+	return "·";
+}
+
+function outputWarning(agent: CrewAgentRecord): string {
+	if (agent.status !== "completed") return "";
+	if (!agent.outputPath || !fs.existsSync(agent.outputPath)) return " no-output";
+	try {
+		return fs.statSync(agent.outputPath).size === 0 ? " no-output" : "";
+	} catch {
+		return " no-output";
+	}
+}
+
+function agentLine(agent: CrewAgentRecord): string {
+	return `- ${statusGlyph(agent.status)} ${agent.taskId} [${agent.status}] ${agent.role}->${agent.agent} runtime=${agent.runtime} ${activityText(agent)}${outputWarning(agent)}${agent.error ? ` error=${agent.error}` : ""}`;
+}
+
+export function buildAgentDashboard(manifest: TeamRunManifest): { text: string; groups: Record<string, CrewAgentRecord[]> } {
+	const agents = readCrewAgents(manifest);
+	const groups: Record<string, CrewAgentRecord[]> = {
+		running: agents.filter((agent) => agent.status === "running"),
+		queued: agents.filter((agent) => agent.status === "queued"),
+		recent: agents.filter((agent) => agent.status !== "running" && agent.status !== "queued"),
+	};
+	const lines = [
+		`Crew agents for ${manifest.runId}`,
+		`Run status: ${manifest.status}`,
+		`Counts: running=${groups.running.length}, queued=${groups.queued.length}, recent=${groups.recent.length}`,
+		"",
+		"## Running",
+		...(groups.running.length ? groups.running.map(agentLine) : ["- (none)"]),
+		"",
+		"## Queued",
+		...(groups.queued.length ? groups.queued.map(agentLine) : ["- (none)"]),
+		"",
+		"## Recent",
+		...(groups.recent.length ? groups.recent.slice(-10).map(agentLine) : ["- (none)"]),
+	];
+	return { text: lines.join("\n"), groups };
+}
+
+export function readAgentOutput(manifest: TeamRunManifest, taskId: string, maxBytes?: number): TextTailResult {
+	return readTextTail(agentOutputPath(manifest, taskId), maxBytes);
+}

package/src/runtime/child-pi.ts

@@ -2,10 +2,12 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agent-config.ts";
-import { buildPiWorkerArgs, cleanupTempDir } from "./pi-args.ts";
+import { buildPiWorkerArgs, checkCrewDepth, cleanupTempDir } from "./pi-args.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
 
 const POST_EXIT_STDIO_GUARD_MS = 3000;
+const FINAL_DRAIN_MS = 5000;
+const HARD_KILL_MS = 3000;
 
 export interface ChildPiRunInput {
 	cwd: string;
@@ -16,6 +18,9 @@ export interface ChildPiRunInput {
 	transcriptPath?: string;
 	onStdoutLine?: (line: string) => void;
 	onJsonEvent?: (event: unknown) => void;
+	maxDepth?: number;
+	finalDrainMs?: number;
+	hardKillMs?: number;
 }
 
 export interface ChildPiRunResult {
@@ -71,7 +76,25 @@ function observeStdoutChunk(input: ChildPiRunInput, text: string): void {
 	observer.flush();
 }
 
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function isFinalAssistantEvent(event: unknown): boolean {
+	const obj = asRecord(event);
+	if (!obj || obj.type !== "message_end") return false;
+	const message = asRecord(obj.message);
+	const role = message?.role;
+	if (role !== undefined && role !== "assistant") return false;
+	const stopReason = typeof message?.stopReason === "string" ? message.stopReason : typeof obj.stopReason === "string" ? obj.stopReason : undefined;
+	if (stopReason !== undefined && stopReason !== "stop") return false;
+	const content = Array.isArray(message?.content) ? message.content : [];
+	return !content.some((part) => asRecord(part)?.type === "toolCall");
+}
+
 export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
+	const depth = checkCrewDepth(input.maxDepth);
+	if (depth.blocked) return { exitCode: 1, stdout: "", stderr: `pi-crew depth guard blocked child worker: depth ${depth.depth} >= max ${depth.maxDepth}` };
 	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
 	if (mock) {
 		if (mock === "success") {
@@ -87,7 +110,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "rate limit: mock failure" };
 		return { exitCode: 1, stdout: "", stderr: `mock failure: ${mock}` };
 	}
-	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false });
+	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false, maxDepth: input.maxDepth });
 	const spawnSpec = getPiSpawnCommand(built.args);
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
@@ -99,13 +122,44 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let stdout = "";
 			let stderr = "";
 			let settled = false;
+			let childExited = false;
 			let postExitGuard: NodeJS.Timeout | undefined;
-			const lineObserver = new ChildPiLineObserver(input);
+			let finalDrainTimer: NodeJS.Timeout | undefined;
+			let hardKillTimer: NodeJS.Timeout | undefined;
+			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
+			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
+			let forcedFinalDrain = false;
+			const lineObserver = new ChildPiLineObserver({
+				...input,
+				onJsonEvent: (event) => {
+					input.onJsonEvent?.(event);
+					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
+					finalDrainTimer = setTimeout(() => {
+						if (settled || childExited) return;
+						forcedFinalDrain = true;
+						try { child.kill(process.platform === "win32" ? undefined : "SIGTERM"); } catch {}
+						hardKillTimer = setTimeout(() => {
+							if (settled || childExited) return;
+							try { child.kill(process.platform === "win32" ? undefined : "SIGKILL"); } catch {}
+						}, hardKillMs);
+						hardKillTimer.unref?.();
+					}, finalDrainMs);
+					finalDrainTimer.unref?.();
+				},
+			});
+
+			const clearFinalDrainTimers = (): void => {
+				if (finalDrainTimer) clearTimeout(finalDrainTimer);
+				if (hardKillTimer) clearTimeout(hardKillTimer);
+				finalDrainTimer = undefined;
+				hardKillTimer = undefined;
+			};
 
 			const settle = (result: ChildPiRunResult): void => {
 				if (settled) return;
 				settled = true;
 				if (postExitGuard) clearTimeout(postExitGuard);
+				clearFinalDrainTimers();
 				lineObserver.flush();
 				input.signal?.removeEventListener("abort", abort);
 				cleanupTempDir(built.tempDir);
@@ -133,6 +187,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				settle({ exitCode: null, stdout, stderr, error: error.message });
 			});
 			child.on("exit", () => {
+				childExited = true;
+				clearFinalDrainTimers();
 				postExitGuard = setTimeout(() => {
 					child.stdout?.destroy();
 					child.stderr?.destroy();
@@ -140,7 +196,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				postExitGuard.unref?.();
 			});
 			child.on("close", (exitCode) => {
-				settle({ exitCode, stdout, stderr });
+				settle({ exitCode, stdout, stderr, ...(forcedFinalDrain && !stderr.trim() ? { error: `Child Pi did not exit within ${finalDrainMs}ms after final assistant message; termination was requested.` } : {}) });
 			});
 		});
 	} finally {