pi-crew 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -68,6 +68,7 @@
     "@mariozechner/pi-tui": "*"
   },
   "dependencies": {
+    "jiti": "^2.6.1",
     "typebox": "^1.1.24"
   },
   "devDependencies": {

package/schema.json

@@ -54,6 +54,30 @@
         "maxTasksPerRun": { "type": "integer", "minimum": 1 },
         "heartbeatStaleMs": { "type": "integer", "minimum": 1 }
       }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Crew runtime selection and live-agent behavior knobs.",
+      "properties": {
+        "mode": { "type": "string", "enum": ["auto", "scaffold", "child-process", "live-session"] },
+        "preferLiveSession": { "type": "boolean" },
+        "allowChildProcessFallback": { "type": "boolean" },
+        "maxTurns": { "type": "integer", "minimum": 1 },
+        "graceTurns": { "type": "integer", "minimum": 1 },
+        "inheritContext": { "type": "boolean" },
+        "promptMode": { "type": "string", "enum": ["replace", "append"] },
+        "groupJoin": { "type": "string", "enum": ["off", "group", "smart"] }
+      }
+    },
+    "control": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Agent control-plane settings for attention/stale activity detection.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "needsAttentionAfterMs": { "type": "integer", "minimum": 1 }
+      }
     }
   }
 }

package/src/config/config.ts

@@ -23,6 +23,24 @@ export interface CrewLimitsConfig {
 	heartbeatStaleMs?: number;
 }
 
+export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
+
+export interface CrewRuntimeConfig {
+	mode?: CrewRuntimeMode;
+	preferLiveSession?: boolean;
+	allowChildProcessFallback?: boolean;
+	maxTurns?: number;
+	graceTurns?: number;
+	inheritContext?: boolean;
+	promptMode?: "replace" | "append";
+	groupJoin?: "off" | "group" | "smart";
+}
+
+export interface CrewControlConfig {
+	enabled?: boolean;
+	needsAttentionAfterMs?: number;
+}
+
 export interface PiTeamsConfig {
 	asyncByDefault?: boolean;
 	executeWorkers?: boolean;
@@ -30,6 +48,8 @@ export interface PiTeamsConfig {
 	requireCleanWorktreeLeader?: boolean;
 	autonomous?: PiTeamsAutonomousConfig;
 	limits?: CrewLimitsConfig;
+	runtime?: CrewRuntimeConfig;
+	control?: CrewControlConfig;
 }
 
 export interface LoadedPiTeamsConfig {
@@ -77,6 +97,18 @@ function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfi
 			...withoutUndefined((override.limits ?? {}) as Record<string, unknown>),
 		};
 	}
+	if (base.runtime || override.runtime) {
+		merged.runtime = {
+			...(base.runtime ?? {}),
+			...withoutUndefined((override.runtime ?? {}) as Record<string, unknown>),
+		};
+	}
+	if (base.control || override.control) {
+		merged.control = {
+			...(base.control ?? {}),
+			...withoutUndefined((override.control ?? {}) as Record<string, unknown>),
+		};
+	}
 	return merged;
 }
 
@@ -146,6 +178,36 @@ function parseLimitsConfig(value: unknown): CrewLimitsConfig | undefined {
 	return Object.values(limits).some((entry) => entry !== undefined) ? limits : undefined;
 }
 
+function parseRuntimeMode(value: unknown): CrewRuntimeMode | undefined {
+	return value === "auto" || value === "scaffold" || value === "child-process" || value === "live-session" ? value : undefined;
+}
+
+function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const runtime: CrewRuntimeConfig = {
+		mode: parseRuntimeMode(obj.mode),
+		preferLiveSession: typeof obj.preferLiveSession === "boolean" ? obj.preferLiveSession : undefined,
+		allowChildProcessFallback: typeof obj.allowChildProcessFallback === "boolean" ? obj.allowChildProcessFallback : undefined,
+		maxTurns: parsePositiveInteger(obj.maxTurns),
+		graceTurns: parsePositiveInteger(obj.graceTurns),
+		inheritContext: typeof obj.inheritContext === "boolean" ? obj.inheritContext : undefined,
+		promptMode: obj.promptMode === "replace" || obj.promptMode === "append" ? obj.promptMode : undefined,
+		groupJoin: obj.groupJoin === "off" || obj.groupJoin === "group" || obj.groupJoin === "smart" ? obj.groupJoin : undefined,
+	};
+	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
+}
+
+function parseControlConfig(value: unknown): CrewControlConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const control: CrewControlConfig = {
+		enabled: typeof obj.enabled === "boolean" ? obj.enabled : undefined,
+		needsAttentionAfterMs: parsePositiveInteger(obj.needsAttentionAfterMs),
+	};
+	return Object.values(control).some((entry) => entry !== undefined) ? control : undefined;
+}
+
 function parseConfig(raw: unknown): PiTeamsConfig {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 	const obj = raw as Record<string, unknown>;
@@ -156,6 +218,8 @@ function parseConfig(raw: unknown): PiTeamsConfig {
 		requireCleanWorktreeLeader: typeof obj.requireCleanWorktreeLeader === "boolean" ? obj.requireCleanWorktreeLeader : undefined,
 		autonomous: parseAutonomousConfig(obj.autonomous),
 		limits: parseLimitsConfig(obj.limits),
+		runtime: parseRuntimeConfig(obj.runtime),
+		control: parseControlConfig(obj.control),
 	};
 }
 

package/src/extension/team-tool.ts

@@ -35,6 +35,10 @@ 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 { resolveCrewRuntime } from "../runtime/runtime-resolver.ts";
+import { probeLiveSessionRuntime } from "../runtime/live-session-runtime.ts";
+import { applyAttentionState, formatActivityAge, resolveCrewControlConfig } from "../runtime/agent-control.ts";
 
 export interface TeamToolDetails {
 	action: string;
@@ -255,8 +259,9 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		return result(text, { action: "run", status: "ok", runId: updatedManifest.runId, artifactsRoot: updatedManifest.artifactsRoot });
 	}
 
-	const executeWorkers = loadedConfig.config.executeWorkers === true || process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits });
+	const runtime = await resolveCrewRuntime(loadedConfig.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 text = [
 		`Created pi-crew run ${executed.manifest.runId}.`,
 		`Team: ${team.name}`,
@@ -266,9 +271,10 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		`State: ${executed.manifest.stateRoot}`,
 		`Artifacts: ${executed.manifest.artifactsRoot}`,
 		"",
+		`Runtime: ${runtime.kind}${runtime.fallback ? ` (fallback from ${runtime.requestedMode})` : ""}${runtime.reason ? ` - ${runtime.reason}` : ""}`,
 		executeWorkers
-			? "Child Pi worker execution was enabled with PI_TEAMS_EXECUTE_WORKERS=1."
-			: "Safe scaffold mode: child Pi workers were not launched. Set PI_TEAMS_EXECUTE_WORKERS=1 to enable real worker execution.",
+			? "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.",
 	].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");
 }
@@ -291,6 +297,8 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	const counts = new Map<string, number>();
 	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
 	const events = readEvents(manifest.eventsPath).slice(-8);
+	const controlConfig = resolveCrewControlConfig(loadConfig(ctx.cwd).config);
+	const crewAgents = readCrewAgents(manifest).map((agent) => applyAttentionState(manifest, agent, controlConfig));
 	const artifactLines = manifest.artifacts.slice(-10).map((artifact) => `- ${artifact.kind}: ${artifact.path}${artifact.sizeBytes !== undefined ? ` (${artifact.sizeBytes} bytes)` : ""}`);
 	const totalUsage = aggregateUsage(tasks);
 	const lines = [
@@ -308,6 +316,8 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		"Tasks:",
 		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
 		`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
+		"Agents:",
+		...(crewAgents.length ? crewAgents.map((agent) => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.progress?.activityState === "needs_attention" ? " needs_attention" : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`) : ["- (none)"]),
 		"Policy decisions:",
 		...(manifest.policyDecisions?.length ? manifest.policyDecisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`) : ["- (none)"]),
 		`Total usage: ${formatUsage(totalUsage)}`,
@@ -370,8 +380,9 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		saveRunTasks(loaded.manifest, resetTasks);
 		appendEvent(loaded.manifest.eventsPath, { type: "run.resume_requested", runId: loaded.manifest.runId });
 		const loadedConfig = loadConfig(ctx.cwd);
-		const executeWorkers = loadedConfig.config.executeWorkers === true || process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-		const executed = await executeTeamRun({ manifest: loaded.manifest, tasks: resetTasks, team, workflow, agents: allAgents(discoverAgents(ctx.cwd)), executeWorkers, limits: loadedConfig.config.limits });
+		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 });
 		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");
 	});
 }
@@ -446,12 +457,17 @@ function autonomousPatchFromConfig(config: unknown): PiTeamsAutonomousConfig {
 
 function configPatchFromConfig(config: unknown): PiTeamsConfig {
 	const cfg = configRecord(config);
+	const control = configRecord(cfg.control);
 	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,
+		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,
+		} : undefined,
 	};
 }
 
@@ -540,7 +556,7 @@ export function handleCleanup(params: TeamToolParamsValue, ctx: TeamContext): Pi
 	return result(lines.join("\n"), { action: "cleanup", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 }
 
-export function handleApi(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	if (!params.runId) return result("API requires runId.", { action: "api", status: "error" }, true);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId);
 	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
@@ -561,6 +577,61 @@ export function handleApi(params: TeamToolParamsValue, ctx: TeamContext): PiTeam
 	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 });
 	}
+	if (operation === "runtime-capabilities") {
+		const loadedConfig = loadConfig(ctx.cwd);
+		return result(JSON.stringify(await resolveCrewRuntime(loadedConfig.config), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "probe-live-session") {
+		return result(JSON.stringify(await probeLiveSessionRuntime(), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "list-agents") {
+		return result(JSON.stringify(readCrewAgents(loaded.manifest), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "get-agent-result") {
+		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 get-agent-result requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const task = loaded.tasks.find((item) => item.id === agent.taskId);
+		const text = task?.resultArtifact && fs.existsSync(task.resultArtifact.path) ? fs.readFileSync(task.resultArtifact.path, "utf-8") : JSON.stringify(agent, null, 2);
+		return result(text, { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	if (operation === "read-agent-status") {
+		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+		const agent = agentId ? readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId) : undefined;
+		const status = agent ? readCrewAgentStatus(loaded.manifest, agent.taskId) ?? agent : undefined;
+		if (!status) return result("API read-agent-status requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		return result(JSON.stringify(status, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+	}
+	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 });
+	}
+	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 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 === "nudge-agent") {
+		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 nudge-agent requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		const messageText = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : "Please report your current status, blocker, or smallest next step.";
+		const message = appendMailboxMessage(loaded.manifest, { direction: "inbox", from: "leader", to: agent.taskId, taskId: agent.taskId, body: messageText });
+		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 === "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);
+	}
 	if (operation === "read-mailbox") {
 		const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? cfg.direction as MailboxDirection : undefined;
 		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
@@ -762,7 +833,7 @@ export async function handleTeamTool(params: TeamToolParamsValue, ctx: TeamConte
 		}
 		case "doctor": return handleDoctor(ctx, params);
 		case "cleanup": return handleCleanup(params, ctx);
-		case "api": return handleApi(params, ctx);
+		case "api": return await handleApi(params, ctx);
 		case "events": return handleEvents(params, ctx);
 		case "artifacts": return handleArtifacts(params, ctx);
 		case "worktrees": return handleWorktrees(params, ctx);

package/src/runtime/agent-control.ts

@@ -0,0 +1,64 @@
+import type { PiTeamsConfig } from "../config/config.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+import { upsertCrewAgent } from "./crew-agent-records.ts";
+
+export interface CrewControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+}
+
+const DEFAULT_NEEDS_ATTENTION_MS = 60_000;
+
+function positiveInt(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+export function resolveCrewControlConfig(config: PiTeamsConfig | undefined): CrewControlConfig {
+	const raw = config as PiTeamsConfig & { control?: { enabled?: unknown; needsAttentionAfterMs?: unknown } } | undefined;
+	return {
+		enabled: raw?.control?.enabled === false ? false : true,
+		needsAttentionAfterMs: positiveInt(raw?.control?.needsAttentionAfterMs) ?? DEFAULT_NEEDS_ATTENTION_MS,
+	};
+}
+
+export function activityAgeMs(agent: CrewAgentRecord, now = Date.now()): number | undefined {
+	const timestamp = agent.progress?.lastActivityAt ?? agent.startedAt;
+	if (!timestamp) return undefined;
+	const ms = now - new Date(timestamp).getTime();
+	return Number.isFinite(ms) ? Math.max(0, ms) : undefined;
+}
+
+export function formatActivityAge(agent: CrewAgentRecord, now = Date.now()): string | undefined {
+	const age = activityAgeMs(agent, now);
+	if (age === undefined) return undefined;
+	if (age < 1000) return "active now";
+	const seconds = Math.floor(age / 1000);
+	if (seconds < 60) return agent.progress?.activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	return agent.progress?.activityState === "needs_attention" ? `no activity for ${minutes}m` : `active ${minutes}m ago`;
+}
+
+export function applyAttentionState(manifest: TeamRunManifest, agent: CrewAgentRecord, config: CrewControlConfig, now = Date.now()): CrewAgentRecord {
+	if (!config.enabled || agent.status !== "running") return agent;
+	const age = activityAgeMs(agent, now);
+	if (age === undefined || age <= config.needsAttentionAfterMs) return agent;
+	if (agent.progress?.activityState === "needs_attention") return agent;
+	const updated: CrewAgentRecord = {
+		...agent,
+		progress: {
+			...(agent.progress ?? { recentTools: [], recentOutput: [], toolCount: agent.toolUses ?? 0 }),
+			activityState: "needs_attention",
+		},
+	};
+	upsertCrewAgent(manifest, updated);
+	appendEvent(manifest.eventsPath, {
+		type: "agent.needs_attention",
+		runId: manifest.runId,
+		taskId: agent.taskId,
+		message: `${agent.agent} needs attention (no observed activity for ${Math.floor(age / 1000)}s).`,
+		data: { agentId: agent.id, ageMs: age, needsAttentionAfterMs: config.needsAttentionAfterMs },
+	});
+	return updated;
+}

package/src/runtime/async-runner.ts

@@ -1,9 +1,36 @@
 import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { TeamRunManifest } from "../state/types.ts";
 
+const require = createRequire(import.meta.url);
+
+function resolveJitiCliPath(): string | undefined {
+	const candidates: Array<() => string> = [
+		() => path.join(path.dirname(require.resolve("jiti/package.json")), "lib/jiti-cli.mjs"),
+		() => path.join(path.dirname(require.resolve("@mariozechner/jiti/package.json")), "lib/jiti-cli.mjs"),
+	];
+	for (const candidate of candidates) {
+		try {
+			const filePath = candidate();
+			if (fs.existsSync(filePath)) return filePath;
+		} catch {
+			// Try the next possible runtime dependency location.
+		}
+	}
+	return undefined;
+}
+
+export function getBackgroundRunnerCommand(runnerPath: string, cwd: string, runId: string): { args: string[]; loader: "jiti" | "strip-types" } {
+	const jitiCliPath = resolveJitiCliPath();
+	const runnerArgs = [runnerPath, "--cwd", cwd, "--run-id", runId];
+	return jitiCliPath
+		? { args: [jitiCliPath, ...runnerArgs], loader: "jiti" }
+		: { args: ["--experimental-strip-types", ...runnerArgs], loader: "strip-types" };
+}
+
 export interface SpawnBackgroundTeamRunResult {
 	pid?: number;
 	logPath: string;
@@ -14,7 +41,9 @@ export function spawnBackgroundTeamRun(manifest: TeamRunManifest): SpawnBackgrou
 	const logPath = path.join(manifest.stateRoot, "background.log");
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
 	const logFd = fs.openSync(logPath, "a");
-	const child = spawn(process.execPath, ["--experimental-strip-types", runnerPath, "--cwd", manifest.cwd, "--run-id", manifest.runId], {
+	const command = getBackgroundRunnerCommand(runnerPath, manifest.cwd, manifest.runId);
+	fs.appendFileSync(logPath, `[pi-crew] background loader=${command.loader}\n`, "utf-8");
+	const child = spawn(process.execPath, command.args, {
 		cwd: manifest.cwd,
 		detached: true,
 		stdio: ["ignore", logFd, logFd],

package/src/runtime/background-runner.ts

@@ -5,6 +5,7 @@ import { loadRunManifestById, updateRunStatus } from "../state/state-store.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 import { loadConfig } from "../config/config.ts";
 import { executeTeamRun } from "./team-runner.ts";
+import { resolveCrewRuntime } from "./runtime-resolver.ts";
 
 function argValue(name: string): string | undefined {
 	const index = process.argv.indexOf(name);
@@ -29,8 +30,9 @@ async function main(): Promise<void> {
 		if (!workflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
 		const agents = allAgents(discoverAgents(cwd));
 		const loadedConfig = loadConfig(cwd);
-		const executeWorkers = loadedConfig.config.executeWorkers === true || process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits });
+		const runtime = await resolveCrewRuntime(loadedConfig.config);
+		const executeWorkers = runtime.kind === "child-process";
+		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime });
 		manifest = result.manifest;
 		tasks = result.tasks;
 		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });

package/src/runtime/child-pi.ts

@@ -1,14 +1,21 @@
 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 { getPiSpawnCommand } from "./pi-spawn.ts";
 
+const POST_EXIT_STDIO_GUARD_MS = 3000;
+
 export interface ChildPiRunInput {
 	cwd: string;
 	task: string;
 	agent: AgentConfig;
 	model?: string;
 	signal?: AbortSignal;
+	transcriptPath?: string;
+	onStdoutLine?: (line: string) => void;
+	onJsonEvent?: (event: unknown) => void;
 }
 
 export interface ChildPiRunResult {
@@ -18,11 +25,65 @@ export interface ChildPiRunResult {
 	error?: string;
 }
 
+function appendTranscript(input: ChildPiRunInput, line: string): void {
+	if (!input.transcriptPath) return;
+	fs.mkdirSync(path.dirname(input.transcriptPath), { recursive: true });
+	fs.appendFileSync(input.transcriptPath, `${line}\n`, "utf-8");
+}
+
+export class ChildPiLineObserver {
+	private buffer = "";
+	private readonly input: ChildPiRunInput;
+
+	constructor(input: ChildPiRunInput) {
+		this.input = input;
+	}
+
+	observe(text: string): void {
+		this.buffer += text;
+		const lines = this.buffer.split(/\r?\n/);
+		this.buffer = lines.pop() ?? "";
+		for (const line of lines) this.emitLine(line);
+	}
+
+	flush(): void {
+		if (!this.buffer) return;
+		const line = this.buffer;
+		this.buffer = "";
+		this.emitLine(line);
+	}
+
+	private emitLine(line: string): void {
+		if (!line.trim()) return;
+		appendTranscript(this.input, line);
+		this.input.onStdoutLine?.(line);
+		try {
+			this.input.onJsonEvent?.(JSON.parse(line));
+		} catch {
+			// Raw stdout is allowed.
+		}
+	}
+}
+
+function observeStdoutChunk(input: ChildPiRunInput, text: string): void {
+	const observer = new ChildPiLineObserver(input);
+	observer.observe(text);
+	observer.flush();
+}
+
 export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
 	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
 	if (mock) {
-		if (mock === "success") return { exitCode: 0, stdout: `Mock child Pi success for ${input.agent.name}\n`, stderr: "" };
-		if (mock === "json-success") return { exitCode: 0, stdout: `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `Mock JSON success for ${input.agent.name}` }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`, stderr: "" };
+		if (mock === "success") {
+			const stdout = `Mock child Pi success for ${input.agent.name}\n`;
+			observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
+		if (mock === "json-success") {
+			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `Mock JSON success for ${input.agent.name}` }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+			observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
 		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "rate limit: mock failure" };
 		return { exitCode: 1, stdout: "", stderr: `mock failure: ${mock}` };
 	}
@@ -38,10 +99,15 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let stdout = "";
 			let stderr = "";
 			let settled = false;
+			let postExitGuard: NodeJS.Timeout | undefined;
+			const lineObserver = new ChildPiLineObserver(input);
 
 			const settle = (result: ChildPiRunResult): void => {
 				if (settled) return;
 				settled = true;
+				if (postExitGuard) clearTimeout(postExitGuard);
+				lineObserver.flush();
+				input.signal?.removeEventListener("abort", abort);
 				cleanupTempDir(built.tempDir);
 				resolve(result);
 			};
@@ -56,7 +122,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 
 			input.signal?.addEventListener("abort", abort, { once: true });
 			child.stdout?.on("data", (chunk: Buffer) => {
-				stdout += chunk.toString("utf-8");
+				const text = chunk.toString("utf-8");
+				stdout += text;
+				lineObserver.observe(text);
 			});
 			child.stderr?.on("data", (chunk: Buffer) => {
 				stderr += chunk.toString("utf-8");
@@ -64,8 +132,14 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			child.on("error", (error) => {
 				settle({ exitCode: null, stdout, stderr, error: error.message });
 			});
+			child.on("exit", () => {
+				postExitGuard = setTimeout(() => {
+					child.stdout?.destroy();
+					child.stderr?.destroy();
+				}, POST_EXIT_STDIO_GUARD_MS);
+				postExitGuard.unref?.();
+			});
 			child.on("close", (exitCode) => {
-				input.signal?.removeEventListener("abort", abort);
 				settle({ exitCode, stdout, stderr });
 			});
 		});