pi-crew 0.1.2 → 0.1.4

package/README.md

@@ -2,17 +2,21 @@
 
 `pi-crew` is a Pi extension/package for coordinated AI teams: autonomous routing, manual slash-command controls, durable run state, artifacts, async/background execution, optional worktree isolation, resource management, validation, import/export, dashboard helpers, and safe API interop.
 
-It is intentionally located at workspace root:
+NPM package:
 
 ```text
-pi-crew/
+pi-crew
 ```
 
-not under `Source/`.
+GitHub repository:
+
+```text
+https://github.com/baphuongna/pi-crew
+```
 
 ## Status
 
-`pi-crew` is implemented as a local Pi package with safe execution defaults and product-oriented foundations.
+`pi-crew` is published on npm and implemented with safe execution defaults and product-oriented foundations.
 
 Current highlights:
 
@@ -33,6 +37,7 @@ Current highlights:
 - retryable model fallback attempts per task
 - aggregate usage totals in status/summary
 - progress, summary, prompt, result, log, diff, patch, export artifacts
+- task packets, verification/green-contract evidence, policy decision artifacts, and task graph metadata
 - opt-in git worktree isolation per task
 - worktree branch mismatch detection
 - dirty worktree preservation unless `force` is explicitly set
@@ -63,7 +68,13 @@ From the workspace root for local development:
 pi install ./pi-crew
 ```
 
-Optional config bootstrap:
+Optional config bootstrap after npm install:
+
+```bash
+pi-crew
+```
+
+Optional config bootstrap from a local clone:
 
 ```bash
 node ./pi-crew/install.mjs
@@ -144,6 +155,14 @@ Supported config:
     "magicKeywords": {
       "review": ["review", "audit", "inspect"]
     }
+  },
+  "limits": {
+    "maxConcurrentWorkers": 3,
+    "maxTaskDepth": 2,
+    "maxChildrenPerTask": 5,
+    "maxRunMinutes": 60,
+    "maxRetriesPerTask": 1,
+    "heartbeatStaleMs": 60000
   }
 }
 ```
@@ -663,25 +682,11 @@ pi-crew/docs/live-mailbox-runtime.md
 pi-crew/docs/publishing.md
 ```
 
-Workspace-level design/progress docs:
-
-```text
-docs/pi-crew-source-review-and-lessons.md
-docs/pi-crew-architecture.md
-docs/pi-crew-mvp-plan.md
-docs/pi-crew-*-progress-2026-04-26.md
-```
-
-## Known remaining release metadata
-
-Package metadata still needs real project values before publishing:
+Historical workspace-level design/progress docs may exist in the original development workspace under `docs/pi-crew-*`, but package-maintained docs live under `pi-crew/docs/`.
 
-- `author`
-- `repository`
-- `homepage`
-- `bugs`
+## Local Pi smoke
 
-Local Pi smoke still requires an actual Pi environment:
+A local Pi smoke test requires an installed Pi CLI and a real Pi environment:
 
 ```bash
 cd pi-crew

package/install.mjs

@@ -7,7 +7,7 @@ const configDir = path.join(os.homedir(), ".pi", "agent", "extensions", "pi-crew
 const configPath = path.join(configDir, "config.json");
 fs.mkdirSync(configDir, { recursive: true });
 if (!fs.existsSync(configPath)) {
-  fs.writeFileSync(configPath, `${JSON.stringify({ asyncByDefault: false, executeWorkers: false, notifierIntervalMs: 5000, requireCleanWorktreeLeader: true, autonomous: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: false, allowWorktreeSuggestion: true } }, null, 2)}\n`, "utf-8");
+  fs.writeFileSync(configPath, `${JSON.stringify({ asyncByDefault: false, executeWorkers: false, notifierIntervalMs: 5000, requireCleanWorktreeLeader: true, autonomous: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: false, allowWorktreeSuggestion: true }, limits: { maxConcurrentWorkers: 3, maxTaskDepth: 2, maxChildrenPerTask: 5, maxRunMinutes: 60, maxRetriesPerTask: 1, heartbeatStaleMs: 60000 } }, null, 2)}\n`, "utf-8");
   console.log(`Created default pi-crew config: ${configPath}`);
 } else {
   console.log(`pi-crew config already exists: ${configPath}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/schema.json

@@ -40,6 +40,20 @@
           }
         }
       }
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Runtime safety limits for crew workers and policy decisions.",
+      "properties": {
+        "maxConcurrentWorkers": { "type": "integer", "minimum": 1 },
+        "maxTaskDepth": { "type": "integer", "minimum": 1 },
+        "maxChildrenPerTask": { "type": "integer", "minimum": 1 },
+        "maxRunMinutes": { "type": "integer", "minimum": 1 },
+        "maxRetriesPerTask": { "type": "integer", "minimum": 1 },
+        "maxTasksPerRun": { "type": "integer", "minimum": 1 },
+        "heartbeatStaleMs": { "type": "integer", "minimum": 1 }
+      }
     }
   }
 }

package/src/config/config.ts

@@ -13,12 +13,23 @@ export interface PiTeamsAutonomousConfig {
 	magicKeywords?: Record<string, string[]>;
 }
 
+export interface CrewLimitsConfig {
+	maxConcurrentWorkers?: number;
+	maxTaskDepth?: number;
+	maxChildrenPerTask?: number;
+	maxRunMinutes?: number;
+	maxRetriesPerTask?: number;
+	maxTasksPerRun?: number;
+	heartbeatStaleMs?: number;
+}
+
 export interface PiTeamsConfig {
 	asyncByDefault?: boolean;
 	executeWorkers?: boolean;
 	notifierIntervalMs?: number;
 	requireCleanWorktreeLeader?: boolean;
 	autonomous?: PiTeamsAutonomousConfig;
+	limits?: CrewLimitsConfig;
 }
 
 export interface LoadedPiTeamsConfig {
@@ -60,6 +71,12 @@ function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfi
 			...withoutUndefined((override.autonomous ?? {}) as Record<string, unknown>),
 		};
 	}
+	if (base.limits || override.limits) {
+		merged.limits = {
+			...(base.limits ?? {}),
+			...withoutUndefined((override.limits ?? {}) as Record<string, unknown>),
+		};
+	}
 	return merged;
 }
 
@@ -110,6 +127,25 @@ function parseAutonomousConfig(value: unknown): PiTeamsAutonomousConfig | undefi
 	};
 }
 
+function parsePositiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function parseLimitsConfig(value: unknown): CrewLimitsConfig | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const obj = value as Record<string, unknown>;
+	const limits: CrewLimitsConfig = {
+		maxConcurrentWorkers: parsePositiveInteger(obj.maxConcurrentWorkers),
+		maxTaskDepth: parsePositiveInteger(obj.maxTaskDepth),
+		maxChildrenPerTask: parsePositiveInteger(obj.maxChildrenPerTask),
+		maxRunMinutes: parsePositiveInteger(obj.maxRunMinutes),
+		maxRetriesPerTask: parsePositiveInteger(obj.maxRetriesPerTask),
+		maxTasksPerRun: parsePositiveInteger(obj.maxTasksPerRun),
+		heartbeatStaleMs: parsePositiveInteger(obj.heartbeatStaleMs),
+	};
+	return Object.values(limits).some((entry) => entry !== undefined) ? limits : undefined;
+}
+
 function parseConfig(raw: unknown): PiTeamsConfig {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 	const obj = raw as Record<string, unknown>;
@@ -119,6 +155,7 @@ function parseConfig(raw: unknown): PiTeamsConfig {
 		notifierIntervalMs: typeof obj.notifierIntervalMs === "number" && Number.isFinite(obj.notifierIntervalMs) && obj.notifierIntervalMs >= 1000 ? obj.notifierIntervalMs : undefined,
 		requireCleanWorktreeLeader: typeof obj.requireCleanWorktreeLeader === "boolean" ? obj.requireCleanWorktreeLeader : undefined,
 		autonomous: parseAutonomousConfig(obj.autonomous),
+		limits: parseLimitsConfig(obj.limits),
 	};
 }
 

package/src/extension/team-tool.ts

@@ -256,7 +256,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	}
 
 	const executeWorkers = loadedConfig.config.executeWorkers === true || process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers });
+	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits });
 	const text = [
 		`Created pi-crew run ${executed.manifest.runId}.`,
 		`Team: ${team.name}`,
@@ -306,8 +306,10 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		`Artifacts: ${manifest.artifactsRoot}`,
 		...(asyncLivenessLine ? [asyncLivenessLine] : []),
 		"Tasks:",
-		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${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)"]),
+		...(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"}`,
+		"Policy decisions:",
+		...(manifest.policyDecisions?.length ? manifest.policyDecisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`) : ["- (none)"]),
 		`Total usage: ${formatUsage(totalUsage)}`,
 		"",
 		"Recent artifacts:",
@@ -369,7 +371,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		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 });
+		const executed = await executeTeamRun({ manifest: loaded.manifest, tasks: resetTasks, team, workflow, agents: allAgents(discoverAgents(ctx.cwd)), executeWorkers, limits: loadedConfig.config.limits });
 		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");
 	});
 }

package/src/runtime/background-runner.ts

@@ -3,6 +3,7 @@ import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { appendEvent } from "../state/event-log.ts";
 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";
 
 function argValue(name: string): string | undefined {
@@ -27,8 +28,9 @@ async function main(): Promise<void> {
 		const workflow = allWorkflows(discoverWorkflows(cwd)).find((candidate) => candidate.name === manifest.workflow);
 		if (!workflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
 		const agents = allAgents(discoverAgents(cwd));
-		const executeWorkers = process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
-		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers });
+		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 });
 		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/green-contract.ts

@@ -0,0 +1,46 @@
+import type { GreenLevel, VerificationContract, VerificationEvidence } from "../state/types.ts";
+
+const GREEN_ORDER: Record<GreenLevel, number> = {
+	none: 0,
+	targeted: 1,
+	package: 2,
+	workspace: 3,
+	merge_ready: 4,
+};
+
+export interface GreenContractOutcome {
+	requiredGreenLevel: GreenLevel;
+	observedGreenLevel: GreenLevel;
+	satisfied: boolean;
+}
+
+export function greenLevelSatisfies(observed: GreenLevel, required: GreenLevel): boolean {
+	return GREEN_ORDER[observed] >= GREEN_ORDER[required];
+}
+
+export function evaluateGreenContract(contract: VerificationContract, evidence?: VerificationEvidence): GreenContractOutcome {
+	const observedGreenLevel = evidence?.observedGreenLevel ?? "none";
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: greenLevelSatisfies(observedGreenLevel, contract.requiredGreenLevel),
+	};
+}
+
+export function inferGreenLevelFromTask(success: boolean, contract: VerificationContract): GreenLevel {
+	if (!success) return "none";
+	if (contract.requiredGreenLevel === "none") return "none";
+	return contract.allowManualEvidence ? contract.requiredGreenLevel : "targeted";
+}
+
+export function createVerificationEvidence(contract: VerificationContract, success: boolean, notes: string): VerificationEvidence {
+	const observedGreenLevel = inferGreenLevelFromTask(success, contract);
+	const outcome = evaluateGreenContract(contract, { requiredGreenLevel: contract.requiredGreenLevel, observedGreenLevel, satisfied: false, commands: [], notes });
+	return {
+		requiredGreenLevel: contract.requiredGreenLevel,
+		observedGreenLevel,
+		satisfied: outcome.satisfied,
+		commands: contract.commands.map((cmd) => ({ cmd, status: "not_run" as const })),
+		notes,
+	};
+}

package/src/runtime/policy-engine.ts

@@ -0,0 +1,55 @@
+import type { CrewLimitsConfig } from "../config/config.ts";
+import type { PolicyDecision, PolicyDecisionAction, PolicyDecisionReason, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { evaluateGreenContract } from "./green-contract.ts";
+import { isWorkerHeartbeatStale } from "./worker-heartbeat.ts";
+
+export interface PolicyEngineInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	limits?: CrewLimitsConfig;
+	now?: Date;
+}
+
+function decision(action: PolicyDecisionAction, reason: PolicyDecisionReason, message: string, taskId?: string): PolicyDecision {
+	return {
+		action,
+		reason,
+		message,
+		taskId,
+		createdAt: new Date().toISOString(),
+	};
+}
+
+export function evaluateCrewPolicy(input: PolicyEngineInput): PolicyDecision[] {
+	const decisions: PolicyDecision[] = [];
+	const maxTasksPerRun = input.limits?.maxTasksPerRun;
+	if (maxTasksPerRun !== undefined && input.tasks.length > maxTasksPerRun) {
+		decisions.push(decision("block", "limit_exceeded", `Run has ${input.tasks.length} tasks, exceeding maxTasksPerRun=${maxTasksPerRun}.`));
+	}
+
+	for (const task of input.tasks) {
+		if (task.status === "failed") {
+			const retryCount = task.policy?.retryCount ?? 0;
+			const maxRetries = input.limits?.maxRetriesPerTask ?? 0;
+			decisions.push(decision(retryCount < maxRetries ? "retry" : "escalate", "task_failed", task.error ? `Task failed: ${task.error}` : "Task failed.", task.id));
+		}
+		if (task.heartbeat && isWorkerHeartbeatStale(task.heartbeat, input.limits?.heartbeatStaleMs ?? 60_000, input.now)) {
+			decisions.push(decision("escalate", "worker_stale", "Worker heartbeat is stale.", task.id));
+		}
+		if (task.taskPacket?.verification) {
+			const outcome = evaluateGreenContract(task.taskPacket.verification, task.verification);
+			if (!outcome.satisfied && task.status === "completed") {
+				decisions.push(decision("block", "green_unsatisfied", `Green contract unsatisfied: required=${outcome.requiredGreenLevel}, observed=${outcome.observedGreenLevel}.`, task.id));
+			}
+		}
+	}
+
+	if (decisions.length === 0 && input.tasks.length > 0 && input.tasks.every((task) => task.status === "completed")) {
+		decisions.push(decision("closeout", "run_complete", "All tasks completed and no policy blockers were found."));
+	}
+	return decisions;
+}
+
+export function summarizePolicyDecisions(decisions: PolicyDecision[]): string[] {
+	return decisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`);
+}

package/src/runtime/task-packet.ts

@@ -0,0 +1,84 @@
+import * as path from "node:path";
+import type { TeamRunManifest, TaskPacket, TaskScope, VerificationContract } from "../state/types.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+
+export interface BuildTaskPacketInput {
+	manifest: TeamRunManifest;
+	step: WorkflowStep;
+	taskId: string;
+	cwd: string;
+	worktreePath?: string;
+}
+
+export interface TaskPacketValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+export function inferTaskScope(step: WorkflowStep): TaskScope {
+	const reads = step.reads === false ? [] : step.reads ?? [];
+	if (reads.length === 1) return "single_file";
+	if (reads.length > 1) return "module";
+	return "workspace";
+}
+
+export function defaultVerificationContract(step: WorkflowStep): VerificationContract {
+	return {
+		requiredGreenLevel: step.verify ? "targeted" : "none",
+		commands: [],
+		allowManualEvidence: true,
+	};
+}
+
+export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
+	const scope = inferTaskScope(input.step);
+	const reads = input.step.reads === false ? [] : input.step.reads ?? [];
+	const scopePath = reads.length === 1 ? reads[0] : reads.length > 1 ? reads.join(", ") : undefined;
+	return {
+		objective: input.step.task.replaceAll("{goal}", input.manifest.goal),
+		scope,
+		scopePath,
+		repo: path.basename(input.manifest.cwd) || input.manifest.cwd,
+		worktree: input.worktreePath,
+		branchPolicy: input.manifest.workspaceMode === "worktree" ? "Use the assigned task worktree and avoid modifying the leader checkout." : "Use the current checkout; do not create branches unless explicitly requested.",
+		acceptanceTests: [],
+		commitPolicy: "Do not commit unless explicitly requested by the user or workflow.",
+		reportingContract: "Report changed files, verification evidence, blockers, and next recommended action.",
+		escalationPolicy: "Stop and report if scope is ambiguous, destructive action is needed, permissions are missing, or verification cannot be completed.",
+		constraints: [
+			"Stay within the assigned task scope.",
+			"Do not claim completion without verification evidence.",
+			"Use mailbox/API state for coordination when available.",
+		],
+		expectedArtifacts: ["prompt", "result", "verification"],
+		verification: defaultVerificationContract(input.step),
+	};
+}
+
+export function validateTaskPacket(packet: TaskPacket): TaskPacketValidationResult {
+	const errors: string[] = [];
+	if (!packet.objective.trim()) errors.push("objective must not be empty");
+	if (!packet.repo.trim()) errors.push("repo must not be empty");
+	if (!packet.branchPolicy.trim()) errors.push("branchPolicy must not be empty");
+	if (!packet.commitPolicy.trim()) errors.push("commitPolicy must not be empty");
+	if (!packet.reportingContract.trim()) errors.push("reportingContract must not be empty");
+	if (!packet.escalationPolicy.trim()) errors.push("escalationPolicy must not be empty");
+	if ((packet.scope === "module" || packet.scope === "single_file" || packet.scope === "custom") && !packet.scopePath?.trim()) {
+		errors.push(`scopePath is required for scope '${packet.scope}'`);
+	}
+	for (const [index, test] of packet.acceptanceTests.entries()) {
+		if (!test.trim()) errors.push(`acceptanceTests contains an empty value at index ${index}`);
+	}
+	return { valid: errors.length === 0, errors };
+}
+
+export function renderTaskPacket(packet: TaskPacket): string {
+	return [
+		"# Task Packet",
+		"",
+		"```json",
+		JSON.stringify(packet, null, 2),
+		"```",
+		"",
+	].join("\n");
+}

package/src/runtime/task-runner.ts

@@ -10,6 +10,8 @@ import { captureWorktreeDiff, prepareTaskWorkspace } from "../worktree/worktree-
 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";
+import { buildTaskPacket, renderTaskPacket } from "./task-packet.ts";
+import { createVerificationEvidence } from "./green-contract.ts";
 
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
@@ -43,7 +45,9 @@ function renderTaskPrompt(manifest: TeamRunManifest, step: WorkflowStep, task: T
 		"- Stay within the task scope unless the prompt explicitly says otherwise.",
 		"- Report blockers and verification evidence in the final result.",
 		"- Do not claim completion without evidence.",
+		"- Follow the Task Packet contract below; escalate if any contract field is impossible to satisfy.",
 		"",
+		task.taskPacket ? renderTaskPacket(task.taskPacket) : "",
 		"Task:",
 		step.task.replaceAll("{goal}", manifest.goal),
 	].join("\n");
@@ -56,10 +60,13 @@ function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): TeamTaskSta
 export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	let manifest = input.manifest;
 	const workspace = prepareTaskWorkspace(manifest, input.task);
+	const worktree = workspace.worktreePath && workspace.branch ? { path: workspace.worktreePath, branch: workspace.branch, reused: workspace.reused ?? false } : input.task.worktree;
+	const taskPacket = buildTaskPacket({ manifest, step: input.step, taskId: input.task.id, cwd: workspace.cwd, worktreePath: worktree?.path });
 	let task: TeamTaskState = {
 		...input.task,
 		cwd: workspace.cwd,
-		worktree: workspace.worktreePath && workspace.branch ? { path: workspace.worktreePath, branch: workspace.branch, reused: workspace.reused ?? false } : input.task.worktree,
+		worktree,
+		taskPacket,
 		status: "running",
 		startedAt: new Date().toISOString(),
 		claim: createTaskClaim(`task-runner:${input.task.id}`),
@@ -149,6 +156,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		usage: parsedOutput?.usage,
 		jsonEvents: parsedOutput?.jsonEvents,
 		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."),
 		promptArtifact,
 		resultArtifact,
 		claim: undefined,
@@ -156,7 +164,19 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		...(logArtifact ? { logArtifact } : {}),
 	};
 	tasks = updateTask(tasks, task);
-	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, promptArtifact, resultArtifact, ...(logArtifact ? [logArtifact] : []), ...(diffArtifact ? [diffArtifact] : [])] };
+	const packetArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: `metadata/${task.id}.task-packet.json`,
+		content: `${JSON.stringify(task.taskPacket, null, 2)}\n`,
+		producer: task.id,
+	});
+	const verificationArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: `metadata/${task.id}.verification.json`,
+		content: `${JSON.stringify(task.verification, null, 2)}\n`,
+		producer: task.id,
+	});
+	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, promptArtifact, resultArtifact, packetArtifact, verificationArtifact, ...(logArtifact ? [logArtifact] : []), ...(diffArtifact ? [diffArtifact] : [])] };
 	saveRunManifest(manifest);
 	saveRunTasks(manifest, tasks);
 	appendEvent(manifest.eventsPath, { type: error ? "task.failed" : "task.completed", runId: manifest.runId, taskId: task.id, message: error });

package/src/runtime/team-runner.ts

@@ -1,135 +1,162 @@
-import type { AgentConfig } from "../agents/agent-config.ts";
-import { writeArtifact } from "../state/artifact-store.ts";
-import type { TeamConfig } from "../teams/team-config.ts";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
-import { aggregateUsage, formatUsage } from "../state/usage.ts";
-import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
-import { runTeamTask } from "./task-runner.ts";
-
-export interface ExecuteTeamRunInput {
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	team: TeamConfig;
-	workflow: WorkflowConfig;
-	agents: AgentConfig[];
-	executeWorkers: boolean;
-	signal?: AbortSignal;
-}
-
-function findReadyTask(tasks: TeamTaskState[]): TeamTaskState | undefined {
-	const completedStepIds = new Set(tasks.filter((task) => task.status === "completed").map((task) => task.stepId).filter((id): id is string => id !== undefined));
-	return tasks.find((task) => task.status === "queued" && task.dependsOn.every((dep) => completedStepIds.has(dep)));
-}
-
-function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
-	const step = workflow.steps.find((candidate) => candidate.id === task.stepId);
-	if (!step) throw new Error(`Workflow step '${task.stepId}' not found for task '${task.id}'.`);
-	return step;
-}
-
-function findAgent(agents: AgentConfig[], task: TeamTaskState): AgentConfig {
-	const agent = agents.find((candidate) => candidate.name === task.agent);
-	if (!agent) throw new Error(`Agent '${task.agent}' not found for task '${task.id}'.`);
-	return agent;
-}
-
-function markBlocked(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
-	return tasks.map((task) => task.status === "queued" ? { ...task, status: "skipped", error: reason, finishedAt: new Date().toISOString() } : task);
-}
-
-function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string): TeamRunManifest {
-	const counts = new Map<string, number>();
-	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
-	const progress = writeArtifact(manifest.artifactsRoot, {
-		kind: "progress",
-		relativePath: "progress.md",
-		producer,
-		content: [
-			`# pi-crew progress ${manifest.runId}`,
-			"",
-			`Status: ${manifest.status}`,
-			`Team: ${manifest.team}`,
-			`Workflow: ${manifest.workflow ?? "(none)"}`,
-			`Updated: ${new Date().toISOString()}`,
-			`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
-			"",
-			"## Tasks",
-			...tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
-			"",
-		].join("\n"),
-	});
-	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress] };
-}
-
-export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
-	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
-	let tasks = input.tasks;
-	manifest = writeProgress(manifest, tasks, "team-runner");
-	saveRunManifest(manifest);
-
-	while (tasks.some((task) => task.status === "queued")) {
-		if (input.signal?.aborted) {
-			tasks = tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: "Run cancelled." } : task);
-			saveRunTasks(manifest, tasks);
-			manifest = updateRunStatus(manifest, "cancelled", "Run cancelled.");
-			return { manifest, tasks };
-		}
-
-		const failed = tasks.find((task) => task.status === "failed");
-		if (failed) {
-			tasks = markBlocked(tasks, `Blocked by failed task '${failed.id}'.`);
-			saveRunTasks(manifest, tasks);
-			manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
-			return { manifest, tasks };
-		}
-
-		const task = findReadyTask(tasks);
-		if (!task) {
-			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
-			saveRunTasks(manifest, tasks);
-			manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
-			return { manifest, tasks };
-		}
-
-		const step = findStep(input.workflow, task);
-		const agent = findAgent(input.agents, task);
-		const result = await runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
-		manifest = result.manifest;
-		tasks = result.tasks;
-		manifest = writeProgress(manifest, tasks, "team-runner");
-		saveRunManifest(manifest);
-	}
-
-	const failed = tasks.find((task) => task.status === "failed");
-	if (failed) {
-		manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
-	} else {
-		manifest = updateRunStatus(manifest, "completed", input.executeWorkers ? "Team workflow completed." : "Team workflow scaffold completed without launching child workers.");
-	}
-	manifest = writeProgress(manifest, tasks, "team-runner");
-	saveRunManifest(manifest);
-	const usage = aggregateUsage(tasks);
-	const summaryArtifact = writeArtifact(manifest.artifactsRoot, {
-		kind: "summary",
-		relativePath: "summary.md",
-		producer: "team-runner",
-		content: [
-			`# pi-crew run ${manifest.runId}`,
-			"",
-			`Status: ${manifest.status}`,
-			`Team: ${manifest.team}`,
-			`Workflow: ${manifest.workflow ?? "(none)"}`,
-			`Goal: ${manifest.goal}`,
-			`Usage: ${formatUsage(usage)}`,
-			"",
-			"## Tasks",
-			...tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
-			"",
-		].join("\n"),
-	});
-	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, summaryArtifact] };
-	saveRunManifest(manifest);
-	saveRunTasks(manifest, tasks);
-	return { manifest, tasks };
-}
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { CrewLimitsConfig } from "../config/config.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { saveRunManifest, saveRunTasks, updateRunStatus } from "../state/state-store.ts";
+import { aggregateUsage, formatUsage } from "../state/usage.ts";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts";
+import { runTeamTask } from "./task-runner.ts";
+
+export interface ExecuteTeamRunInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	team: TeamConfig;
+	workflow: WorkflowConfig;
+	agents: AgentConfig[];
+	executeWorkers: boolean;
+	limits?: CrewLimitsConfig;
+	signal?: AbortSignal;
+}
+
+function findReadyTask(tasks: TeamTaskState[]): TeamTaskState | undefined {
+	const completedStepIds = new Set(tasks.filter((task) => task.status === "completed").map((task) => task.stepId).filter((id): id is string => id !== undefined));
+	return tasks.find((task) => task.status === "queued" && task.dependsOn.every((dep) => completedStepIds.has(dep)));
+}
+
+function findStep(workflow: WorkflowConfig, task: TeamTaskState): WorkflowStep {
+	const step = workflow.steps.find((candidate) => candidate.id === task.stepId);
+	if (!step) throw new Error(`Workflow step '${task.stepId}' not found for task '${task.id}'.`);
+	return step;
+}
+
+function findAgent(agents: AgentConfig[], task: TeamTaskState): AgentConfig {
+	const agent = agents.find((candidate) => candidate.name === task.agent);
+	if (!agent) throw new Error(`Agent '${task.agent}' not found for task '${task.id}'.`);
+	return agent;
+}
+
+function markBlocked(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
+	return tasks.map((task) => task.status === "queued" ? { ...task, status: "skipped", error: reason, finishedAt: new Date().toISOString(), graph: task.graph ? { ...task.graph, queue: "blocked" } : undefined } : task);
+}
+
+function formatTaskProgress(task: TeamTaskState): string {
+	return `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.error ? ` - ${task.error}` : ""}`;
+}
+
+function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string): TeamRunManifest {
+	const counts = new Map<string, number>();
+	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	const progress = writeArtifact(manifest.artifactsRoot, {
+		kind: "progress",
+		relativePath: "progress.md",
+		producer,
+		content: [
+			`# pi-crew progress ${manifest.runId}`,
+			"",
+			`Status: ${manifest.status}`,
+			`Team: ${manifest.team}`,
+			`Workflow: ${manifest.workflow ?? "(none)"}`,
+			`Updated: ${new Date().toISOString()}`,
+			`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
+			"",
+			"## Tasks",
+			...tasks.map(formatTaskProgress),
+			"",
+		].join("\n"),
+	});
+	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress] };
+}
+
+function applyPolicy(manifest: TeamRunManifest, tasks: TeamTaskState[], limits?: CrewLimitsConfig): TeamRunManifest {
+	const decisions = evaluateCrewPolicy({ manifest, tasks, limits });
+	const policyArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: "policy-decisions.json",
+		producer: "policy-engine",
+		content: `${JSON.stringify(decisions, null, 2)}\n`,
+	});
+	for (const item of decisions) appendEvent(manifest.eventsPath, { type: item.action === "escalate" ? "policy.escalated" : "policy.action", runId: manifest.runId, taskId: item.taskId, message: item.message, data: { action: item.action, reason: item.reason } });
+	return { ...manifest, updatedAt: new Date().toISOString(), policyDecisions: decisions, artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "metadata" && artifact.path.endsWith("policy-decisions.json"))), policyArtifact] };
+}
+
+export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
+	let tasks = input.tasks;
+	manifest = writeProgress(manifest, tasks, "team-runner");
+	saveRunManifest(manifest);
+
+	while (tasks.some((task) => task.status === "queued")) {
+		if (input.signal?.aborted) {
+			tasks = tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: "Run cancelled." } : task);
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "cancelled", "Run cancelled.");
+			return { manifest, tasks };
+		}
+
+		const failed = tasks.find((task) => task.status === "failed");
+		if (failed) {
+			tasks = markBlocked(tasks, `Blocked by failed task '${failed.id}'.`);
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
+			return { manifest, tasks };
+		}
+
+		const task = findReadyTask(tasks);
+		if (!task) {
+			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
+			saveRunTasks(manifest, tasks);
+			manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
+			return { manifest, tasks };
+		}
+
+		const step = findStep(input.workflow, task);
+		const agent = findAgent(input.agents, task);
+		const result = await runTeamTask({ manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers });
+		manifest = result.manifest;
+		tasks = result.tasks;
+		manifest = writeProgress(manifest, tasks, "team-runner");
+		saveRunManifest(manifest);
+	}
+
+	const failed = tasks.find((task) => task.status === "failed");
+	manifest = applyPolicy(manifest, tasks, input.limits);
+	const blockingDecision = manifest.policyDecisions?.find((item) => item.action === "block" || item.action === "escalate");
+	if (failed) {
+		manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
+	} else if (blockingDecision) {
+		manifest = updateRunStatus(manifest, "blocked", blockingDecision.message);
+	} else {
+		manifest = updateRunStatus(manifest, "completed", input.executeWorkers ? "Team workflow completed." : "Team workflow scaffold completed without launching child workers.");
+	}
+	manifest = writeProgress(manifest, tasks, "team-runner");
+	saveRunManifest(manifest);
+	const usage = aggregateUsage(tasks);
+	const summaryArtifact = writeArtifact(manifest.artifactsRoot, {
+		kind: "summary",
+		relativePath: "summary.md",
+		producer: "team-runner",
+		content: [
+			`# pi-crew run ${manifest.runId}`,
+			"",
+			`Status: ${manifest.status}`,
+			`Team: ${manifest.team}`,
+			`Workflow: ${manifest.workflow ?? "(none)"}`,
+			`Goal: ${manifest.goal}`,
+			`Usage: ${formatUsage(usage)}`,
+			"",
+			"## Tasks",
+			...tasks.map(formatTaskProgress),
+			"",
+			"## Policy decisions",
+			...(manifest.policyDecisions?.length ? summarizePolicyDecisions(manifest.policyDecisions) : ["- (none)"]),
+			"",
+		].join("\n"),
+	});
+	manifest = { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts, summaryArtifact] };
+	saveRunManifest(manifest);
+	saveRunTasks(manifest, tasks);
+	return { manifest, tasks };
+}

package/src/state/contracts.ts

@@ -36,9 +36,19 @@ export const TEAM_EVENT_TYPES = [
 	"run.failed",
 	"run.cancelled",
 	"task.started",
+	"task.progress",
+	"task.blocked",
+	"task.green",
+	"task.red",
 	"task.completed",
 	"task.failed",
+	"review.approved",
+	"review.rejected",
+	"policy.action",
+	"policy.escalated",
+	"mailbox.timeout",
 	"worktree.cleanup",
+	"worktree.dirty",
 	"async.spawned",
 	"async.started",
 	"async.completed",

package/src/state/state-store.ts

@@ -39,18 +39,29 @@ export function createRunPaths(cwd: string, runId = createRunId()): RunPaths {
 }
 
 export function createTasksFromWorkflow(runId: string, workflow: WorkflowConfig, team: TeamConfig, cwd: string): TeamTaskState[] {
+	const stepToTaskId = new Map(workflow.steps.map((step, index) => [step.id, createTaskId(step.id, index)]));
 	return workflow.steps.map((step, index) => {
 		const role = team.roles.find((candidate) => candidate.name === step.role);
+		const id = stepToTaskId.get(step.id) ?? createTaskId(step.id, index);
+		const dependencies = step.dependsOn ?? [];
+		const children = workflow.steps.filter((candidate) => candidate.dependsOn?.includes(step.id)).map((candidate) => stepToTaskId.get(candidate.id)).filter((childId): childId is string => childId !== undefined);
 		return {
-			id: createTaskId(step.id, index),
+			id,
 			runId,
 			stepId: step.id,
 			role: step.role,
 			agent: role?.agent ?? step.role,
 			title: step.id,
 			status: "queued",
-			dependsOn: step.dependsOn ?? [],
+			dependsOn: dependencies,
 			cwd,
+			graph: {
+				taskId: id,
+				parentId: dependencies[0] ? stepToTaskId.get(dependencies[0]) : undefined,
+				children,
+				dependencies: dependencies.map((dep) => stepToTaskId.get(dep) ?? dep),
+				queue: dependencies.length ? "blocked" : "ready",
+			},
 		};
 	});
 }

package/src/state/types.ts

@@ -14,6 +14,66 @@ export interface ArtifactDescriptor {
 	expiresAt?: string;
 }
 
+export type TaskScope = "workspace" | "module" | "single_file" | "custom";
+export type GreenLevel = "none" | "targeted" | "package" | "workspace" | "merge_ready";
+
+export interface VerificationCommandResult {
+	cmd: string;
+	status: "passed" | "failed" | "not_run";
+	exitCode?: number | null;
+	outputArtifact?: ArtifactDescriptor;
+}
+
+export interface VerificationContract {
+	requiredGreenLevel: GreenLevel;
+	commands: string[];
+	allowManualEvidence: boolean;
+}
+
+export interface VerificationEvidence {
+	requiredGreenLevel: GreenLevel;
+	observedGreenLevel: GreenLevel;
+	satisfied: boolean;
+	commands: VerificationCommandResult[];
+	notes?: string;
+}
+
+export interface TaskPacket {
+	objective: string;
+	scope: TaskScope;
+	scopePath?: string;
+	repo: string;
+	worktree?: string;
+	branchPolicy: string;
+	acceptanceTests: string[];
+	commitPolicy: string;
+	reportingContract: string;
+	escalationPolicy: string;
+	constraints: string[];
+	expectedArtifacts: string[];
+	verification: VerificationContract;
+}
+
+export type PolicyDecisionAction = "retry" | "reassign" | "escalate" | "block" | "notify" | "cleanup" | "closeout";
+export type PolicyDecisionReason = "task_failed" | "worker_stale" | "green_unsatisfied" | "limit_exceeded" | "run_complete" | "mailbox_timeout" | "review_rejected" | "branch_stale" | "scope_mismatch";
+
+export interface PolicyDecision {
+	action: PolicyDecisionAction;
+	reason: PolicyDecisionReason;
+	message: string;
+	taskId?: string;
+	createdAt: string;
+}
+
+export interface TaskGraphNode {
+	taskId: string;
+	parentId?: string;
+	children: string[];
+	dependencies: string[];
+	queue: "ready" | "blocked" | "running" | "done";
+	sessionForkFrom?: string;
+}
+
 export interface AsyncRunState {
 	pid?: number;
 	logPath: string;
@@ -38,6 +98,7 @@ export interface TeamRunManifest {
 	artifacts: ArtifactDescriptor[];
 	async?: AsyncRunState;
 	summary?: string;
+	policyDecisions?: PolicyDecision[];
 }
 
 export interface UsageState {
@@ -85,4 +146,11 @@ export interface TeamTaskState {
 	error?: string;
 	claim?: TaskClaimState;
 	heartbeat?: WorkerHeartbeatState;
+	taskPacket?: TaskPacket;
+	verification?: VerificationEvidence;
+	graph?: TaskGraphNode;
+	policy?: {
+		retryCount?: number;
+		lastDecision?: PolicyDecision;
+	};
 }

package/src/ui/run-dashboard.ts

@@ -1,7 +1,12 @@
 import * as fs from "node:fs";
-import type { Component } from "@mariozechner/pi-tui";
 import type { TeamRunManifest } from "../state/types.ts";
 
+interface DashboardComponent {
+	invalidate(): void;
+	render(width: number): string[];
+	handleInput(data: string): void;
+}
+
 export type RunDashboardAction = "status" | "summary" | "artifacts" | "api" | "reload";
 export interface RunDashboardSelection {
 	runId: string;
@@ -41,7 +46,7 @@ function countByStatus(runs: TeamRunManifest[]): string {
 	return [...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none";
 }
 
-export class RunDashboard implements Component {
+export class RunDashboard implements DashboardComponent {
 	private selected = 0;
 	private showFullProgress = false;
 	private readonly runs: TeamRunManifest[];