pi-crew 0.9.53 → 0.9.55

package/src/workflows/topology-analyzer.ts

@@ -0,0 +1,203 @@
+// src/workflows/topology-analyzer.ts
+//
+// Workflow topology classifier. Given a WorkflowConfig, returns a TopologyAnalysis
+// describing the structural shape (single / sequential / concurrent / complex-dag
+// / dynamic). The shape is used by the preflight validator to enforce the
+// "don't use pi-crew for sequential independent agents" rule from .crew/knowledge.md.
+//
+// Algorithm (high level):
+//   1. runtime === "dynamic"  →  DYNAMIC  (chain/script workflows decide at runtime)
+//   2. stepCount === 1        →  SINGLE   (one step: no concurrency, no DAG)
+//   3. parallelGroupCount >= 1 AND max-fanout >= 3  →  CONCURRENT
+//   4. stepCount >= 4 AND has-multi-deps  →  COMPLEX_DAG
+//   5. else                   →  SEQUENTIAL
+//
+// "Has-multi-deps" = at least one step lists 2+ dependsOn. This is the
+// unambiguous signal of a branching DAG (diamond patterns, fan-in joins).
+// Plain linear chains with high depth are still SEQUENTIAL — Run #3 fast-fix
+// (3 steps linear, depth 3) and the default workflow (4 steps linear, depth 4)
+// are both sequential by this rule; raw Agent calls are faster for both.
+
+import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
+
+export type WorkflowTopology = "single" | "sequential" | "concurrent" | "complex-dag" | "dynamic";
+
+export type TopologyRecommendation = "raw_agent" | "fast_fix" | "parallel_research" | "implementation_adaptive" | "any";
+
+export interface TopologyAnalysis {
+	topology: WorkflowTopology;
+	stepCount: number;
+	parallelGroupCount: number;
+	fanOutDegree: number;
+	dagDepth: number;
+	recommendation: TopologyRecommendation;
+	reason: string;
+}
+
+/** Distinct parallelGroup values across all steps. Empty if no step sets a group. */
+export function parallelGroupsFromSteps(steps: WorkflowStep[]): Set<string> {
+	const out = new Set<string>();
+	for (const step of steps) {
+		if (step.parallelGroup !== undefined) out.add(step.parallelGroup);
+	}
+	return out;
+}
+
+/** Max group size across all parallelGroup values. 0 if no step sets a group. */
+export function fanOutDegreeFromSteps(steps: WorkflowStep[]): number {
+	const counts = new Map<string, number>();
+	for (const step of steps) {
+		if (step.parallelGroup === undefined) continue;
+		counts.set(step.parallelGroup, (counts.get(step.parallelGroup) ?? 0) + 1);
+	}
+	let max = 0;
+	for (const count of counts.values()) if (count > max) max = count;
+	return max;
+}
+
+/**
+ * Longest-path DAG depth from roots. A root is a step with no dependsOn.
+ * Returns 0 for an empty list, 1 for a list of roots only with no inter-step deps.
+ *
+ * Defensive: a step depending on an unknown id is treated as a root
+ * (validate-workflow.ts catches real cycles before this runs; this is
+ * belt-and-suspenders against malformed inputs).
+ */
+export function dagDepthFromSteps(steps: WorkflowStep[]): number {
+	if (steps.length === 0) return 0;
+	const ids = new Set(steps.map((s) => s.id));
+	// Build adjacency and indegree. Unknown deps are dropped to avoid phantom edges.
+	const indeg = new Map<string, number>();
+	const adj = new Map<string, string[]>();
+	for (const step of steps) {
+		const deps = (step.dependsOn ?? []).filter((d) => ids.has(d));
+		indeg.set(step.id, deps.length);
+		// step.id's parents are deps; deps's children include step.id.
+		adj.set(step.id, adj.get(step.id) ?? []);
+		for (const dep of deps) {
+			const children = adj.get(dep) ?? [];
+			children.push(step.id);
+			adj.set(dep, children);
+		}
+	}
+	// Kahn-style BFS. depth[v] = max(depth[parent]) + 1, roots = 1.
+	const depth = new Map<string, number>();
+	const queue: string[] = [];
+	for (const [id, n] of indeg) {
+		if (n === 0) {
+			depth.set(id, 1);
+			queue.push(id);
+		}
+	}
+	let maxDepth = 0;
+	while (queue.length > 0) {
+		const v = queue.shift()!;
+		const dv = depth.get(v) ?? 0;
+		if (dv > maxDepth) maxDepth = dv;
+		for (const child of adj.get(v) ?? []) {
+			const cand = dv + 1;
+			if (cand > (depth.get(child) ?? 0)) depth.set(child, cand);
+			indeg.set(child, (indeg.get(child) ?? 0) - 1);
+			if ((indeg.get(child) ?? 0) === 0) queue.push(child);
+		}
+	}
+	return maxDepth;
+}
+
+/** True if at least one step lists 2+ dependsOn entries. */
+function hasMultiDeps(steps: WorkflowStep[]): boolean {
+	for (const step of steps) {
+		if ((step.dependsOn?.length ?? 0) >= 2) return true;
+	}
+	return false;
+}
+
+/**
+ * Classify a workflow's topology. See file header for the rule order.
+ * Pure function — no I/O, no side effects, no exceptions.
+ */
+export function analyzeWorkflowTopology(workflow: WorkflowConfig): TopologyAnalysis {
+	// Chain/dynamic workflows: runtime decides the topology at execution time.
+	// Don't try to classify the empty `steps: []` (DynamicWorkflowConfig forces
+	// it to be empty).
+	if (workflow.runtime === "dynamic") {
+		return {
+			topology: "dynamic",
+			stepCount: 0,
+			parallelGroupCount: 0,
+			fanOutDegree: 0,
+			dagDepth: 0,
+			recommendation: "any",
+			reason: "Chain/dynamic workflow — runtime decides topology",
+		};
+	}
+
+	const steps = workflow.steps;
+	const stepCount = steps.length;
+	const parallelGroupCount = parallelGroupsFromSteps(steps).size;
+	const fanOutDegree = fanOutDegreeFromSteps(steps);
+	const dagDepth = dagDepthFromSteps(steps);
+
+	// Explicit topology override from frontmatter `topology:` field.
+	// When set, the author has already classified the workflow — respect that.
+	// We still compute structural metrics so telemetry can show the delta.
+	if (workflow.topology !== undefined && workflow.topology !== "dynamic") {
+		const recommendation: TopologyRecommendation =
+			workflow.topology === "single" || workflow.topology === "sequential"
+				? "raw_agent"
+				: workflow.topology === "concurrent"
+					? "parallel_research"
+					: workflow.topology === "complex-dag"
+						? "implementation_adaptive"
+						: "any";
+		return {
+			topology: workflow.topology,
+			stepCount,
+			parallelGroupCount,
+			fanOutDegree,
+			dagDepth,
+			recommendation,
+			reason: `Explicit topology from frontmatter: '${workflow.topology}'`,
+		};
+	}
+
+	let topology: WorkflowTopology;
+	let recommendation: TopologyRecommendation;
+	let reason: string;
+
+	// Note: explicit `workflow.topology` override is handled BEFORE the variable
+	// declarations below (in the block above). If we reach here, auto-classify.
+
+	if (stepCount === 1) {
+		topology = "single";
+		recommendation = "raw_agent";
+		reason = "Single-task workflow: no concurrency or DAG structure to justify pi-crew overhead.";
+	} else if (parallelGroupCount >= 1 && fanOutDegree >= 3) {
+		topology = "concurrent";
+		recommendation = "parallel_research";
+		reason = `Concurrent fan-out: ${fanOutDegree} steps in parallel group(s) of size ≥3.`;
+	} else if (stepCount >= 4 && hasMultiDeps(steps)) {
+		topology = "complex-dag";
+		recommendation = "implementation_adaptive";
+		reason = `Complex DAG: ${stepCount} steps with branching (≥2 deps on ≥1 node), depth ${dagDepth}.`;
+	} else {
+		topology = "sequential";
+		if (stepCount <= 3) {
+			recommendation = "raw_agent";
+			reason = `Sequential chain of ${stepCount} steps — raw Agent calls are faster.`;
+		} else {
+			recommendation = "fast_fix";
+			reason = `Sequential chain of ${stepCount} steps — audit-trail-justified, but raw calls remain faster.`;
+		}
+	}
+
+	return {
+		topology,
+		stepCount,
+		parallelGroupCount,
+		fanOutDegree,
+		dagDepth,
+		recommendation,
+		reason,
+	};
+}

package/src/workflows/validate-workflow.ts

@@ -0,0 +1,50 @@
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { WorkflowConfig } from "./workflow-config.ts";
+
+export function validateWorkflowForTeam(workflow: WorkflowConfig, team: TeamConfig): string[] {
+	const errors: string[] = [];
+	const roles = new Set(team.roles.map((role) => role.name));
+	const stepIds = new Set<string>();
+
+	for (const step of workflow.steps) {
+		if (stepIds.has(step.id)) errors.push(`Duplicate workflow step id '${step.id}'.`);
+		stepIds.add(step.id);
+		if (!roles.has(step.role)) errors.push(`Step '${step.id}' references unknown team role '${step.role}'.`);
+	}
+
+	for (const step of workflow.steps) {
+		for (const dep of step.dependsOn ?? []) {
+			if (!stepIds.has(dep)) errors.push(`Step '${step.id}' depends on unknown step '${dep}'.`);
+		}
+	}
+
+	// Validate output field types
+	for (const step of workflow.steps) {
+		if (step.output !== undefined && step.output !== false && typeof step.output !== "string") {
+			errors.push(`Step '${step.id}' has invalid 'output' field: expected string or false, got ${typeof step.output}.`);
+		}
+		if (typeof step.output === "string" && step.output.trim() === "") {
+			errors.push(`Step '${step.id}' has empty 'output' string.`);
+		}
+	}
+
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const byId = new Map(workflow.steps.map((step) => [step.id, step]));
+
+	function visit(id: string, trail: string[]): void {
+		if (visited.has(id)) return;
+		if (visiting.has(id)) {
+			errors.push(`Workflow dependency cycle detected: ${[...trail, id].join(" -> ")}.`);
+			return;
+		}
+		visiting.add(id);
+		const step = byId.get(id);
+		for (const dep of step?.dependsOn ?? []) visit(dep, [...trail, id]);
+		visiting.delete(id);
+		visited.add(id);
+	}
+
+	for (const step of workflow.steps) visit(step.id, []);
+	return [...new Set(errors)];
+}

package/src/workflows/workflow-config.ts

@@ -0,0 +1,75 @@
+import type { ResourceSource } from "../agents/agent-config.ts";
+
+export interface WorkflowStep {
+	id: string;
+	role: string;
+	task: string;
+	/** Security (F-02): provenance of the workflow file that declared this step.
+	 *  Populated during discovery by discover-workflows.ts. Used by task-runner.ts
+	 *  to gate preStepScript execution — project-sourced workflows may NOT run
+	 *  pre-step scripts (RCE prevention). Undefined for manually-constructed steps. */
+	source?: ResourceSource;
+	dependsOn?: string[];
+	parallelGroup?: string;
+	output?: string | false;
+	reads?: string[] | false;
+	model?: string;
+	/** Additional skills for this step; false disables role-default injected skills for this step. */
+	skills?: string[] | false;
+	progress?: boolean;
+	worktree?: boolean;
+	verify?: boolean;
+	/** Per-step files to overlay into the worktree (in addition to global worktree.seedPaths).
+	 * Useful when only certain steps need access to local drafts or scripts. */
+	seedPaths?: string[];
+	/** Path to a deterministic script to run before dispatching the LLM worker.
+	 * Script stdout is injected into the worker's prompt as context.
+	 * Pattern origin: Understand-Anything deterministic pre-step pattern. */
+	preStepScript?: string;
+	/** Arguments for preStepScript. Passed as positional args. */
+	preStepArgs?: string[];
+	/** Timeout in ms for preStepScript. Default: 30000. */
+	preStepTimeout?: number;
+	/** Round 21 (E4): if true, a failing preStepScript does NOT abort the task.
+	 * The failure is logged as a warning and the task proceeds without the
+	 * pre-step output. Use for advisory hooks (e.g. optional test runs) whose
+	 * failure shouldn't block the workflow. Default: false (fail-fast). */
+	preStepOptional?: boolean;
+}
+
+export interface WorkflowConfig {
+	name: string;
+	description: string;
+	source: ResourceSource;
+	filePath: string;
+	steps: WorkflowStep[];
+	maxConcurrency?: number;
+	/** P2 dynamic-workflow discriminator. Default "static" (the .workflow.md step-list model).
+	 *  "dynamic" = the workflow is a JS/TS script (.dwf.ts) run via dynamic-workflow-runner.
+	 *  Backward-compatible: absent = "static". */
+	runtime?: "static" | "dynamic";
+	/** For runtime:"dynamic" — relative/absolute path to the .dwf.ts script. Unused for static. */
+	dynamicScript?: string;
+	/** For runtime:"dynamic" — per-workflow token budget. When set, ctx.agent() auto-rejects with
+	 *  ok:false once exhausted. Accumulated from each agent run's reported usage. */
+	maxTokenBudget?: number;
+	/** Explicit topology classification from frontmatter `topology:` field.
+	 *  When set, overrides the auto-classified topology in analyzeWorkflowTopology().
+	 *  Used by preflight-validator to enforce "don't use pi-crew for sequential chains".
+	 *  Valid values: 'single' | 'sequential' | 'concurrent' | 'complex-dag' | 'dynamic'.
+	 *  Absent = auto-classify from step structure (default). */
+	topology?: "single" | "sequential" | "concurrent" | "complex-dag" | "dynamic";
+	/** Round 25 (M6): coalesce micro-tasks. Default false (off). When true,
+	 *  multiple ready tasks sharing role + cwd are grouped into a single
+	 *  multi-task worker prompt to reduce per-task cold-start cost. Disabled
+	 *  in v0.9.17 unless the workflow author opts in. See
+	 *  src/runtime/coalesce-tasks.ts. */
+	coalesceMicroTasks?: boolean;
+}
+
+/** A dynamic workflow (runtime === "dynamic"). steps is empty — the script is the source of truth. */
+export interface DynamicWorkflowConfig extends WorkflowConfig {
+	runtime: "dynamic";
+	dynamicScript: string;
+	steps: [];
+}

package/src/workflows/workflow-serializer.ts

@@ -0,0 +1,32 @@
+import type { WorkflowConfig, WorkflowStep } from "./workflow-config.ts";
+
+function serializeStep(step: WorkflowStep): string[] {
+	const lines = [`## ${step.id}`, `role: ${step.role}`];
+	if (step.dependsOn?.length) lines.push(`dependsOn: ${step.dependsOn.join(", ")}`);
+	if (step.parallelGroup) lines.push(`parallelGroup: ${step.parallelGroup}`);
+	if (step.output === false) lines.push("output: false");
+	else if (step.output) lines.push(`output: ${step.output}`);
+	if (step.reads === false) lines.push("reads: false");
+	else if (Array.isArray(step.reads) && step.reads.length > 0) lines.push(`reads: ${step.reads.join(", ")}`);
+	if (step.model) lines.push(`model: ${step.model}`);
+	if (step.skills === false) lines.push("skills: false");
+	else if (Array.isArray(step.skills) && step.skills.length > 0) lines.push(`skills: ${step.skills.join(", ")}`);
+	if (step.progress !== undefined) lines.push(`progress: ${step.progress ? "true" : "false"}`);
+	if (step.worktree !== undefined) lines.push(`worktree: ${step.worktree ? "true" : "false"}`);
+	if (step.verify !== undefined) lines.push(`verify: ${step.verify ? "true" : "false"}`);
+	lines.push("", step.task.trim(), "");
+	return lines;
+}
+
+export function serializeWorkflow(workflow: WorkflowConfig): string {
+	const lines = [
+		"---",
+		`name: ${workflow.name}`,
+		`description: ${workflow.description}`,
+		...(workflow.maxConcurrency !== undefined ? [`maxConcurrency: ${workflow.maxConcurrency}`] : []),
+		"---",
+		"",
+		...workflow.steps.flatMap(serializeStep),
+	];
+	return lines.join("\n");
+}

package/src/worktree/branch-freshness.ts

@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
+import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
+
+// Read-only git operations only (rev-list, rev-parse, log). Sanitize env to
+// avoid leaking API keys/tokens to any git hook/alias/credential-helper.
+// C-1 fix (code-review 2026-06-23): previously inherited the full parent env.
+const GIT_SAFE_ENV = sanitizeEnvSecrets(process.env, {
+	allowList: [
+		"PATH",
+		"HOME",
+		"USER",
+		...WINDOWS_ESSENTIAL_ENV_VARS,
+		"SHELL",
+		"TERM",
+		"LANG",
+		"LC_ALL",
+		"GIT_CONFIG_GLOBAL",
+		"GIT_CONFIG_SYSTEM",
+		"GIT_EXEC_PATH",
+	],
+});
+
+export type BranchFreshnessStatus = "fresh" | "stale" | "diverged" | "unknown";
+export type StaleBranchPolicy = "warn" | "block" | "auto_rebase" | "auto_merge_forward";
+
+export interface BranchFreshness {
+	status: BranchFreshnessStatus;
+	branch?: string;
+	mainRef: string;
+	ahead: number;
+	behind: number;
+	missingFixes: string[];
+	message: string;
+	error?: string;
+}
+
+function git(cwd: string, args: string[]): string {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "pipe"],
+		env: GIT_SAFE_ENV,
+		windowsHide: true,
+	}).trim();
+}
+
+function count(cwd: string, range: string): number {
+	const raw = git(cwd, ["rev-list", "--count", range]);
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function checkBranchFreshness(cwd: string, mainRef = "main"): BranchFreshness {
+	try {
+		git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+		const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+		const behind = count(cwd, `${branch}..${mainRef}`);
+		const ahead = count(cwd, `${mainRef}..${branch}`);
+		const missingFixes =
+			behind > 0
+				? git(cwd, ["log", "--format=%s", `${branch}..${mainRef}`])
+						.split("\n")
+						.map((line) => line.trim())
+						.filter(Boolean)
+				: [];
+		if (behind === 0)
+			return {
+				status: "fresh",
+				branch,
+				mainRef,
+				ahead,
+				behind,
+				missingFixes,
+				message: `Branch '${branch}' is fresh against ${mainRef}.`,
+			};
+		if (ahead > 0)
+			return {
+				status: "diverged",
+				branch,
+				mainRef,
+				ahead,
+				behind,
+				missingFixes,
+				message: `Branch '${branch}' diverged from ${mainRef}: ahead=${ahead}, behind=${behind}.`,
+			};
+		return {
+			status: "stale",
+			branch,
+			mainRef,
+			ahead,
+			behind,
+			missingFixes,
+			message: `Branch '${branch}' is ${behind} commit(s) behind ${mainRef}.`,
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			status: "unknown",
+			mainRef,
+			ahead: 0,
+			behind: 0,
+			missingFixes: [],
+			message: "Branch freshness could not be determined.",
+			error: message,
+		};
+	}
+}
+
+export function shouldBlockForBranchFreshness(freshness: BranchFreshness, policy: StaleBranchPolicy = "warn"): boolean {
+	return policy === "block" && (freshness.status === "stale" || freshness.status === "diverged");
+}