pi-crew 0.9.16 → 0.9.18

package/src/runtime/output-validator.ts

@@ -43,7 +43,12 @@ export function validateWorkerOutput(role: string, output: string): OutputValida
 
 	// Empty output always fails
 	if (!output || !output.trim()) {
-		return { valid: false, formatMatch: false, structurePreserved: false, issues: ["Empty output"] };
+		return {
+			valid: false,
+			formatMatch: false,
+			structurePreserved: false,
+			issues: ["Empty output"],
+		};
 	}
 
 	// Check role-specific format
@@ -87,7 +92,12 @@ export function validateWorkerOutput(role: string, output: string): OutputValida
  * Returns array of { file, line, severity, message } objects.
  */
 export function parseReviewerFindings(output: string): Array<{ file: string; line: number; severity: string; message: string }> {
-	const findings: Array<{ file: string; line: number; severity: string; message: string }> = [];
+	const findings: Array<{
+		file: string;
+		line: number;
+		severity: string;
+		message: string;
+	}> = [];
 	const lines = output.split("\n");
 
 	const SEVERITY_MAP: Record<string, string> = {
@@ -118,7 +128,12 @@ export function parseReviewerFindings(output: string): Array<{ file: string; lin
  * Returns array of { file, line, symbol, note } objects.
  */
 export function parseExplorerResults(output: string): Array<{ file: string; line: number; symbol: string; note: string }> {
-	const results: Array<{ file: string; line: number; symbol: string; note: string }> = [];
+	const results: Array<{
+		file: string;
+		line: number;
+		symbol: string;
+		note: string;
+	}> = [];
 	const lines = output.split("\n");
 
 	for (const line of lines) {

package/src/runtime/overflow-recovery.ts

@@ -166,9 +166,10 @@ export class OverflowRecoveryTracker {
 		const existing = this.timers.get(key);
 		if (existing) clearTimeout(existing);
 		const current = this.states.get(key);
-		const timeoutMs = current?.phase === "recovered" || current?.phase === "failed" || current?.phase === "none"
-			? TERMINAL_STATE_TTL_MS
-			: PHASE_TIMEOUT_MS;
+		const timeoutMs =
+			current?.phase === "recovered" || current?.phase === "failed" || current?.phase === "none"
+				? TERMINAL_STATE_TTL_MS
+				: PHASE_TIMEOUT_MS;
 
 		const timer = setTimeout(() => {
 			this.timers.delete(key);
@@ -202,4 +203,4 @@ export class OverflowRecoveryTracker {
 		timer.unref();
 		this.timers.set(key, timer);
 	}
-}
+}

package/src/runtime/parallel-research.ts

@@ -5,7 +5,8 @@ import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.
 export function sourcePiProjects(cwd: string): string[] {
 	const sourceDir = path.join(cwd, "Source");
 	try {
-		return fs.readdirSync(sourceDir, { withFileTypes: true })
+		return fs
+			.readdirSync(sourceDir, { withFileTypes: true })
 			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
 			.map((entry) => `Source/${entry.name}`)
 			.sort();
@@ -30,15 +31,38 @@ export function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: st
 		role: "explorer",
 		parallelGroup: "explore",
 		reads: paths,
-		task: [`Explore this dynamic shard for: {goal}`, "", "Paths:", ...paths.map((item) => `- ${item}`), "", "Focus on purpose, architecture, runtime/UI patterns, package config, docs, and lessons for pi-crew."].join("\n"),
+		task: [
+			`Explore this dynamic shard for: {goal}`,
+			"",
+			"Paths:",
+			...paths.map((item) => `- ${item}`),
+			"",
+			"Focus on purpose, architecture, runtime/UI patterns, package config, docs, and lessons for pi-crew.",
+		].join("\n"),
 	}));
 	return {
 		...workflow,
 		steps: [
-			{ id: "discover", role: "explorer", parallelGroup: "inventory", task: `Quickly inventory and validate ${projects.length} pi-* projects for: {goal}\n\nProjects:\n${projects.map((item) => `- ${item}`).join("\n")}\n\nDo not block shard work; summarize routing notes only.` },
+			{
+				id: "discover",
+				role: "explorer",
+				parallelGroup: "inventory",
+				task: `Quickly inventory and validate ${projects.length} pi-* projects for: {goal}\n\nProjects:\n${projects.map((item) => `- ${item}`).join("\n")}\n\nDo not block shard work; summarize routing notes only.`,
+			},
 			...exploreSteps,
-			{ id: "synthesize", role: "analyst", dependsOn: exploreSteps.map((step) => step.id), task: "Synthesize all dynamic shard findings. Identify common patterns, gaps, and concrete recommendations. Use discover output if available, but prioritize completed shard outputs." },
-			{ id: "write", role: "writer", dependsOn: ["synthesize"], output: "research-summary.md", task: "Write a concise final summary with evidence, risks, and actionable next steps." },
+			{
+				id: "synthesize",
+				role: "analyst",
+				dependsOn: exploreSteps.map((step) => step.id),
+				task: "Synthesize all dynamic shard findings. Identify common patterns, gaps, and concrete recommendations. Use discover output if available, but prioritize completed shard outputs.",
+			},
+			{
+				id: "write",
+				role: "writer",
+				dependsOn: ["synthesize"],
+				output: "research-summary.md",
+				task: "Write a concise final summary with evidence, risks, and actionable next steps.",
+			},
 		],
 	};
 }

package/src/runtime/parallel-utils.ts

@@ -76,9 +76,7 @@ async function mapConcurrentWithSignal<T, R>(
 	let aborted = false;
 
 	const abortController = new AbortController();
-	const workerSignal = signal
-		? AbortSignal.any([signal, abortController.signal])
-		: abortController.signal;
+	const workerSignal = signal ? AbortSignal.any([signal, abortController.signal]) : abortController.signal;
 
 	let rejectFirst: (error: unknown) => void;
 	const firstErrorPromise = new Promise<never>((_, reject) => {
@@ -140,14 +138,14 @@ export function aggregateParallelOutputs(
 				r.exitCode === -1
 					? "SKIPPED"
 					: r.exitCode == null || r.exitCode !== 0
-							? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
-							: r.error
-								? `WARNING: ${r.error}`
-								: !hasOutput && r.outputTargetPath && r.outputTargetExists === false
-									? `EMPTY OUTPUT (expected output file missing: ${r.outputTargetPath})`
-									: !hasOutput && !r.outputTargetPath
-										? "EMPTY OUTPUT (no textual response returned)"
-										: "";
+						? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+						: r.error
+							? `WARNING: ${r.error}`
+							: !hasOutput && r.outputTargetPath && r.outputTargetExists === false
+								? `EMPTY OUTPUT (expected output file missing: ${r.outputTargetPath})`
+								: !hasOutput && !r.outputTargetPath
+									? "EMPTY OUTPUT (no textual response returned)"
+									: "";
 			const body = status ? (hasOutput ? `${status}\n${r.output}` : status) : r.output;
 			return `${header}\n${body}`;
 		})

package/src/runtime/path-overlap.ts

@@ -0,0 +1,150 @@
+/**
+ * path-overlap.ts — write-path overlap detection for sequential scheduling (M5).
+ *
+ * Implements the writes-only path-intersection heuristic (per plan §11 decision
+ * #5). A pair of steps is considered overlapping ONLY when both declare the
+ * same write target (via `step.output`). Reads are intentionally ignored to
+ * avoid false positives (parallel reads are safe).
+ *
+ * Scope:
+ *   - export `detectWriteOverlap(stepA, stepB): boolean` — pair check
+ *   - export `selectNonOverlapping(steps, maxCount): WorkflowStep[]` — greedy
+ *     packer that returns at most `maxCount` steps such that no two returned
+ *     steps have overlapping write paths.
+ *   - export `filterReadyByWriteOverlap(taskIds, tasks, workflow, maxCount)` —
+ *     scheduler-side wrapper that translates TeamTaskState IDs to WorkflowSteps
+ *     and applies the overlap filter.
+ *
+ * Default greedy strategy: preserve declaration order; first step always wins
+ * because (a) deterministic for tests, (b) declaration order typically reflects
+ * author intent, (c) a future PR can swap to priority-based when M5 defaults
+ * flip to `true` in production.
+ *
+ * Out of scope: reads overlap detection (decision #5); deferral cap (decision
+ * #6; M5 first ship treats repeated deferral as best-effort; cap warning logged
+ * but not enforced, since M5 default = false means production isn't gated).
+ */
+
+import type { TeamTaskState } from "../state/types.ts";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+
+/**
+ * Extract the canonical write-target path of a step.
+ *
+ * Returns:
+ *   - `step.output` if it is a non-empty string (the file path produced).
+ *   - `undefined` otherwise (no declared write target → step has no write
+ *     overlap risk).
+ *
+ * `step.output === false` means "explicitly no output"; treated as no write.
+ */
+function extractWritePath(step: WorkflowStep): string | undefined {
+	if (typeof step.output === "string" && step.output.length > 0) return step.output;
+	return undefined;
+}
+
+/**
+ * Pairwise check: do stepA and stepB both write to the same path?
+ *
+ * O(1). Both steps must declare an `output` string; otherwise no overlap.
+ *
+ * Examples:
+ *   detectWriteOverlap({output: 'a.md'}, {output: 'a.md'}) → true
+ *   detectWriteOverlap({output: 'a.md'}, {output: 'b.md'}) → false
+ *   detectWriteOverlap({output: 'a.md'}, {output: false})  → false
+ *   detectWriteOverlap({output: 'a.md'}, {})              → false
+ */
+export function detectWriteOverlap(stepA: WorkflowStep, stepB: WorkflowStep): boolean {
+	const pathA = extractWritePath(stepA);
+	const pathB = extractWritePath(stepB);
+	if (!pathA || !pathB) return false;
+	return pathA === pathB;
+}
+
+/**
+ * Greedy packer: pick up to `maxCount` steps from `steps` such that no two
+ * PICKED steps have overlapping write paths.
+ *
+ * Algorithm:
+ *   - Iterates over `steps` in order.
+ *   - First step is always picked.
+ *   - Each subsequent step is picked iff (a) it doesn't overlap with any
+ *     already-picked step AND (b) we haven't reached `maxCount`.
+ *
+ * Returns the picked subset (a NEW array; does not mutate input).
+ *
+ * Used by scheduler when `limits.serializeOnPathOverlap = true`.
+ */
+export function selectNonOverlapping(steps: WorkflowStep[], maxCount: number): WorkflowStep[] {
+	const picked: WorkflowStep[] = [];
+	if (maxCount <= 0 || steps.length === 0) return picked;
+	for (const step of steps) {
+		if (picked.length >= maxCount) break;
+		let conflict = false;
+		for (const existing of picked) {
+			if (detectWriteOverlap(step, existing)) {
+				conflict = true;
+				break;
+			}
+		}
+		if (!conflict) picked.push(step);
+	}
+	return picked;
+}
+
+/**
+ * Scheduler-side wrapper: given a list of ready task IDs (from the task-graph
+ * ready queue), filter them by write-path overlap using the workflow step
+ * definitions.
+ *
+ * Behavior:
+ *   - Resolves each task ID → `TeamTaskState` → `WorkflowStep` via
+ *     `task.stepId` matching `workflow.steps[i].id`.
+ *   - Tasks whose step is missing from the workflow (e.g. ad-hoc tasks) are
+ *     always included (treated as having no declared write path).
+ *   - Returns the same array (identity-equal) when `enabled` is false, so
+ *     callers can skip the filter cheaply.
+ *
+ * Used by the team-runner scheduler when `limits.serializeOnPathOverlap`
+ * is `true` (per plan §11 decision #6, default is `false` so this is a
+ * no-op in v0.9.17 unless the workflow author opts in).
+ */
+export function filterReadyByWriteOverlap(
+	readyTaskIds: string[],
+	tasks: TeamTaskState[],
+	workflow: WorkflowConfig,
+	maxCount: number,
+	enabled: boolean,
+): string[] {
+	if (!enabled || maxCount <= 0 || readyTaskIds.length === 0) return readyTaskIds;
+	const taskById = new Map<string, TeamTaskState>(tasks.map((task) => [task.id, task]));
+	const stepById = new Map<string, WorkflowStep>(workflow.steps.map((step) => [step.id, step]));
+	const pickedSteps: WorkflowStep[] = [];
+	const pickedTaskIds: string[] = [];
+	for (const taskId of readyTaskIds) {
+		if (pickedTaskIds.length >= maxCount) break;
+		const task = taskById.get(taskId);
+		if (!task || !task.stepId) {
+			// No step reference: treat as no declared write path → never conflicts.
+			pickedTaskIds.push(taskId);
+			continue;
+		}
+		const step = stepById.get(task.stepId);
+		if (!step) {
+			pickedTaskIds.push(taskId);
+			continue;
+		}
+		let conflict = false;
+		for (const existing of pickedSteps) {
+			if (detectWriteOverlap(step, existing)) {
+				conflict = true;
+				break;
+			}
+		}
+		if (!conflict) {
+			pickedTaskIds.push(taskId);
+			pickedSteps.push(step);
+		}
+	}
+	return pickedTaskIds;
+}

package/src/runtime/peer-dep.ts

@@ -44,10 +44,7 @@ import { resolveNpmGlobalRoot } from "./pi-spawn.ts";
  * The pi-coding-agent peer dependency package name(s) we can be loaded by.
  * @earendil-works is the canonical scope; @mariozechner is the historical fork.
  */
-export const PEER_DEP_NAMES = [
-	"@earendil-works/pi-coding-agent",
-	"@mariozechner/pi-coding-agent",
-] as const;
+export const PEER_DEP_NAMES = ["@earendil-works/pi-coding-agent", "@mariozechner/pi-coding-agent"] as const;
 
 /**
  * Env var a parent pi-crew process sets on spawned children so they can resolve
@@ -155,10 +152,7 @@ function extractEsmMain(pkg: unknown): string | undefined {
  * container case) AND `<dir>/<pkg>` (handles a base that IS a node_modules
  * dir, e.g. the output of `npm root -g`), then walk up to root.
  */
-function findPackageDir(
-	start: string,
-	names: readonly string[],
-): { dir: string; name: string } | undefined {
+function findPackageDir(start: string, names: readonly string[]): { dir: string; name: string } | undefined {
 	let dir = path.resolve(start);
 	try {
 		if (fs.statSync(dir).isFile()) dir = path.dirname(dir);
@@ -168,10 +162,7 @@ function findPackageDir(
 	while (true) {
 		for (const name of names) {
 			const segs = name.split("/");
-			const candidates = [
-				path.join(dir, "node_modules", ...segs, "package.json"),
-				path.join(dir, ...segs, "package.json"),
-			];
+			const candidates = [path.join(dir, "node_modules", ...segs, "package.json"), path.join(dir, ...segs, "package.json")];
 			for (const pkgJson of candidates) {
 				try {
 					const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
@@ -194,14 +185,16 @@ function tryResolveFrom(base: string): ResolvedPeerDep | undefined {
 	const found = findPackageDir(base, PEER_DEP_NAMES);
 	if (!found) return undefined;
 	try {
-		const pkg = JSON.parse(
-			fs.readFileSync(path.join(found.dir, "package.json"), "utf-8"),
-		);
+		const pkg = JSON.parse(fs.readFileSync(path.join(found.dir, "package.json"), "utf-8"));
 		const mainRel = extractEsmMain(pkg);
 		if (!mainRel) return undefined;
 		const mainAbs = path.resolve(found.dir, mainRel);
 		if (!fs.existsSync(mainAbs)) return undefined;
-		return { dir: found.dir, name: found.name, mainUrl: pathToFileURL(mainAbs).href };
+		return {
+			dir: found.dir,
+			name: found.name,
+			mainUrl: pathToFileURL(mainAbs).href,
+		};
 	} catch {
 		return undefined;
 	}
@@ -261,7 +254,9 @@ function buildMissingMessage(): string {
 		`This usually means pi-crew and pi are installed in separate node_modules trees\n` +
 		`(e.g. pi-crew under ~/.pi/agent/npm/ but pi under an nvm/Volta/fnm global scope).\n` +
 		`Resolution bases tried:\n` +
-		peerDepResolutionBases().map((b) => `  - ${b}`).join("\n") +
+		peerDepResolutionBases()
+			.map((b) => `  - ${b}`)
+			.join("\n") +
 		`\nFix: install pi-crew in the SAME scope as pi, e.g.\n` +
 		`  npm install -g @earendil-works/pi-crew\n` +
 		`or set the env var ${PEER_DEP_DIR_ENV}=<path to the pi-coding-agent package dir>.`

package/src/runtime/per-write-validator.ts

@@ -68,9 +68,7 @@ export function validateJson(content: string, _filePath: string): ValidationResu
  * ONLY zero-cost synchronous validators belong here. Process-spawning
  * validators must be registered via a future opt-in path (see module doc).
  */
-const DEFAULT_VALIDATORS: ReadonlyMap<string, PerWriteValidator> = new Map([
-	["json", validateJson],
-]);
+const DEFAULT_VALIDATORS: ReadonlyMap<string, PerWriteValidator> = new Map([["json", validateJson]]);
 
 // ─────────────────────────────────────────────────────────────────────────
 // Dedup cache (path → last-validated content). Bounded; small.