pi-crew 0.1.49 → 0.2.0

package/src/runtime/notebook-helpers.ts

@@ -1,90 +1,90 @@
-export interface NotebookCell {
-  index: number;
-  cellType: "code" | "markdown" | "raw";
-  source: string;
-  outputs?: unknown[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface Notebook {
-  cells: NotebookCell[];
-  metadata?: Record<string, unknown>;
-  nbformat: number;
-}
-
-/** Check if a file path is a notebook */
-export function isNotebookPath(filePath: string): boolean {
-  return filePath.toLowerCase().endsWith(".ipynb");
-}
-
-function normalizeSource(source: unknown): string {
-  if (typeof source === "string") return source;
-  if (Array.isArray(source)) return source.join("");
-  return "";
-}
-
-/** Parse a .ipynb JSON file into a Notebook structure */
-export function parseNotebook(content: string): Notebook {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(content);
-  } catch {
-    return { cells: [], nbformat: 4 };
-  }
-  if (typeof raw !== "object" || raw === null) return { cells: [], nbformat: 4 };
-  const obj = raw as Record<string, unknown>;
-  const nbformat = typeof obj.nbformat === "number" ? obj.nbformat : 4;
-  const rawCells = Array.isArray(obj.cells) ? obj.cells : [];
-  const cells: NotebookCell[] = rawCells
-    .map((c: unknown, i: number): NotebookCell | null => {
-      if (typeof c !== "object" || c === null) return null;
-      const cell = c as Record<string, unknown>;
-      const cellType = cell.cell_type;
-      if (cellType !== "code" && cellType !== "markdown" && cellType !== "raw") return null;
-      return {
-        index: i,
-        cellType,
-        source: normalizeSource(cell.source),
-        outputs: Array.isArray(cell.outputs) ? cell.outputs : undefined,
-        metadata:
-          cell.metadata && typeof cell.metadata === "object" && !Array.isArray(cell.metadata)
-            ? (cell.metadata as Record<string, unknown>)
-            : undefined,
-      };
-    })
-    .filter((c: NotebookCell | null): c is NotebookCell => c !== null);
-  const metadata =
-    obj.metadata && typeof obj.metadata === "object" && !Array.isArray(obj.metadata)
-      ? (obj.metadata as Record<string, unknown>)
-      : undefined;
-  return { cells, metadata, nbformat };
-}
-
-/** Get a specific cell by index */
-export function getCell(notebook: Notebook, index: number): NotebookCell | undefined {
-  return notebook.cells.find((c) => c.index === index);
-}
-
-/** Update a cell's source content, returning a new Notebook */
-export function updateCell(notebook: Notebook, index: number, source: string): Notebook {
-  const cells = notebook.cells.map((c) =>
-    c.index === index ? { ...c, source } : c,
-  );
-  return { ...notebook, cells };
-}
-
-/** Serialize a Notebook back to .ipynb JSON string */
-export function serializeNotebook(notebook: Notebook): string {
-  const raw = {
-    nbformat: notebook.nbformat,
-    nbformat_minor: 5,
-    metadata: notebook.metadata ?? {},
-    cells: notebook.cells.map((c) => ({
-      cell_type: c.cellType,
-      source: c.source,
-      metadata: c.metadata ?? {},
-      ...(c.cellType === "code" ? { outputs: c.outputs ?? [], execution_count: null } : {}),
-    })),
-  };
-  return JSON.stringify(raw, null, 2) + "\n";
-}
+export interface NotebookCell {
+  index: number;
+  cellType: "code" | "markdown" | "raw";
+  source: string;
+  outputs?: unknown[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface Notebook {
+  cells: NotebookCell[];
+  metadata?: Record<string, unknown>;
+  nbformat: number;
+}
+
+/** Check if a file path is a notebook */
+export function isNotebookPath(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith(".ipynb");
+}
+
+function normalizeSource(source: unknown): string {
+  if (typeof source === "string") return source;
+  if (Array.isArray(source)) return source.join("");
+  return "";
+}
+
+/** Parse a .ipynb JSON file into a Notebook structure */
+export function parseNotebook(content: string): Notebook {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(content);
+  } catch {
+    return { cells: [], nbformat: 4 };
+  }
+  if (typeof raw !== "object" || raw === null) return { cells: [], nbformat: 4 };
+  const obj = raw as Record<string, unknown>;
+  const nbformat = typeof obj.nbformat === "number" ? obj.nbformat : 4;
+  const rawCells = Array.isArray(obj.cells) ? obj.cells : [];
+  const cells: NotebookCell[] = rawCells
+    .map((c: unknown, i: number): NotebookCell | null => {
+      if (typeof c !== "object" || c === null) return null;
+      const cell = c as Record<string, unknown>;
+      const cellType = cell.cell_type;
+      if (cellType !== "code" && cellType !== "markdown" && cellType !== "raw") return null;
+      return {
+        index: i,
+        cellType,
+        source: normalizeSource(cell.source),
+        outputs: Array.isArray(cell.outputs) ? cell.outputs : undefined,
+        metadata:
+          cell.metadata && typeof cell.metadata === "object" && !Array.isArray(cell.metadata)
+            ? (cell.metadata as Record<string, unknown>)
+            : undefined,
+      };
+    })
+    .filter((c: NotebookCell | null): c is NotebookCell => c !== null);
+  const metadata =
+    obj.metadata && typeof obj.metadata === "object" && !Array.isArray(obj.metadata)
+      ? (obj.metadata as Record<string, unknown>)
+      : undefined;
+  return { cells, metadata, nbformat };
+}
+
+/** Get a specific cell by index */
+export function getCell(notebook: Notebook, index: number): NotebookCell | undefined {
+  return notebook.cells.find((c) => c.index === index);
+}
+
+/** Update a cell's source content, returning a new Notebook */
+export function updateCell(notebook: Notebook, index: number, source: string): Notebook {
+  const cells = notebook.cells.map((c) =>
+    c.index === index ? { ...c, source } : c,
+  );
+  return { ...notebook, cells };
+}
+
+/** Serialize a Notebook back to .ipynb JSON string */
+export function serializeNotebook(notebook: Notebook): string {
+  const raw = {
+    nbformat: notebook.nbformat,
+    nbformat_minor: 5,
+    metadata: notebook.metadata ?? {},
+    cells: notebook.cells.map((c) => ({
+      cell_type: c.cellType,
+      source: c.source,
+      metadata: c.metadata ?? {},
+      ...(c.cellType === "code" ? { outputs: c.outputs ?? [], execution_count: null } : {}),
+    })),
+  };
+  return JSON.stringify(raw, null, 2) + "\n";
+}

package/src/runtime/orphan-sentinel.ts

@@ -1,7 +1,7 @@
-/**
- * Orphan sentinel — DEPRECATED, replaced by parent-guard.ts.
- *
- * Keeping this file as a no-op placeholder until all references are removed.
- * Workers now self-monitor via startParentGuard() instead of relying on
- * an external sentinel process.
- */
+/**
+ * Orphan sentinel — DEPRECATED, replaced by parent-guard.ts.
+ *
+ * Keeping this file as a no-op placeholder until all references are removed.
+ * Workers now self-monitor via startParentGuard() instead of relying on
+ * an external sentinel process.
+ */

package/src/runtime/parallel-research.ts

@@ -1,44 +1,44 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
-
-export function sourcePiProjects(cwd: string): string[] {
-	const sourceDir = path.join(cwd, "Source");
-	try {
-		return fs.readdirSync(sourceDir, { withFileTypes: true })
-			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
-			.map((entry) => `Source/${entry.name}`)
-			.sort();
-	} catch {
-		return [];
-	}
-}
-
-export function chunkProjects(projects: string[], target = 6): string[][] {
-	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
-	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
-	return chunks.filter((chunk) => chunk.length > 0);
-}
-
-export function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: string): WorkflowConfig {
-	if (workflow.name !== "parallel-research") return workflow;
-	const projects = sourcePiProjects(cwd);
-	if (projects.length === 0) return workflow;
-	const chunks = chunkProjects(projects, Math.min(8, Math.max(4, Math.ceil(projects.length / 3))));
-	const exploreSteps: WorkflowStep[] = chunks.map((paths, index) => ({
-		id: `explore-shard-${index + 1}`,
-		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"),
-	}));
-	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.` },
-			...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." },
-		],
-	};
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+
+export function sourcePiProjects(cwd: string): string[] {
+	const sourceDir = path.join(cwd, "Source");
+	try {
+		return fs.readdirSync(sourceDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
+			.map((entry) => `Source/${entry.name}`)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+export function chunkProjects(projects: string[], target = 6): string[][] {
+	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
+	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
+	return chunks.filter((chunk) => chunk.length > 0);
+}
+
+export function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: string): WorkflowConfig {
+	if (workflow.name !== "parallel-research") return workflow;
+	const projects = sourcePiProjects(cwd);
+	if (projects.length === 0) return workflow;
+	const chunks = chunkProjects(projects, Math.min(8, Math.max(4, Math.ceil(projects.length / 3))));
+	const exploreSteps: WorkflowStep[] = chunks.map((paths, index) => ({
+		id: `explore-shard-${index + 1}`,
+		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"),
+	}));
+	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.` },
+			...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." },
+		],
+	};
+}

package/src/runtime/phase-progress.ts

@@ -0,0 +1,217 @@
+/**
+ * Phase progress calculator for pi-crew runs.
+ *
+ * Groups tasks by their adaptive phase metadata and computes per-phase
+ * and overall progress metrics including estimated remaining time.
+ */
+import type { TeamTaskState } from "../state/types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PhaseInfo {
+	/** Phase name, e.g. "explore", "plan", "execute", "verify" */
+	phase: string;
+	/** 0-based index among all phases */
+	index: number;
+	/** Total tasks in this phase */
+	total: number;
+	/** Completed tasks */
+	completed: number;
+	/** Failed tasks */
+	failed: number;
+	/** Currently running tasks */
+	running: number;
+	/** Still queued (not started) */
+	queued: number;
+	/** (completed + failed) / total * 100, rounded to 1 decimal */
+	percentage: number;
+}
+
+export interface RunProgress {
+	/** Breakdown per phase, in phase order */
+	phases: PhaseInfo[];
+	/** Overall (completed + failed) / total * 100 */
+	overallPercentage: number;
+	/** Phase that currently has running or queued tasks, or null */
+	currentPhase: string | null;
+	/** Estimated remaining ms based on avg task duration × remaining tasks */
+	estimatedRemainingMs: number;
+	/** Total task count */
+	totalTasks: number;
+	/** Completed task count */
+	completedTasks: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "skipped"]);
+
+/**
+ * Extract the phase label for a task.
+ *
+ * Priority:
+ * 1. `task.adaptive.phase` (set by adaptive planner)
+ * 2. Infer from stepId prefix: `adaptive-<phaseIndex>-...` → use the numeric phase index
+ * 3. Fallback: `"default"`
+ */
+function extractPhase(task: TeamTaskState): string {
+	if (task.adaptive?.phase) return task.adaptive.phase;
+	if (task.stepId?.startsWith("adaptive-")) {
+		const parts = task.stepId.split("-");
+		// adaptive-<phaseIndex>-<taskIndex>-<role> → parts[1] is the phase index
+		if (parts.length >= 3 && parts[1]) return parts[1];
+	}
+	return "default";
+}
+
+/**
+ * Compute task duration in ms from startedAt → finishedAt.
+ * Returns undefined if timestamps are missing or invalid.
+ */
+function taskDurationMs(task: TeamTaskState): number | undefined {
+	if (!task.startedAt || !task.finishedAt) return undefined;
+	const start = new Date(task.startedAt).getTime();
+	const end = new Date(task.finishedAt).getTime();
+	const duration = end - start;
+	return Number.isFinite(duration) && duration > 0 ? duration : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute phase-aware progress for a set of tasks.
+ *
+ * Groups tasks by phase, calculates per-phase and overall percentages,
+ * and estimates remaining time from the average duration of completed tasks.
+ */
+export function computePhaseProgress(tasks: TeamTaskState[]): RunProgress {
+	if (tasks.length === 0) {
+		return {
+			phases: [],
+			overallPercentage: 0,
+			currentPhase: null,
+			estimatedRemainingMs: 0,
+			totalTasks: 0,
+			completedTasks: 0,
+		};
+	}
+
+	// Preserve insertion order of first-seen phase
+	const phaseOrder: string[] = [];
+	const phaseGroups = new Map<string, TeamTaskState[]>();
+
+	for (const task of tasks) {
+		const phase = extractPhase(task);
+		if (!phaseGroups.has(phase)) {
+			phaseGroups.set(phase, []);
+			phaseOrder.push(phase);
+		}
+		phaseGroups.get(phase)!.push(task);
+	}
+
+	let totalCompleted = 0;
+	let totalTerminal = 0;
+	let totalDurationSum = 0;
+	let totalDurationCount = 0;
+	let currentPhase: string | null = null;
+
+	const phases: PhaseInfo[] = phaseOrder.map((phase, index) => {
+		const group = phaseGroups.get(phase)!;
+		let completed = 0;
+		let failed = 0;
+		let running = 0;
+		let queued = 0;
+		let hasRunningOrQueued = false;
+
+		for (const task of group) {
+			const status = task.status;
+			if (status === "completed") {
+				completed++;
+				totalCompleted++;
+				totalTerminal++;
+				const dur = taskDurationMs(task);
+				if (dur !== undefined) {
+					totalDurationSum += dur;
+					totalDurationCount++;
+				}
+			} else if (status === "failed") {
+				failed++;
+				totalTerminal++;
+				const dur = taskDurationMs(task);
+				if (dur !== undefined) {
+					totalDurationSum += dur;
+					totalDurationCount++;
+				}
+			} else if (status === "running" || status === "waiting") {
+				running++;
+				hasRunningOrQueued = true;
+			} else if (status === "queued") {
+				queued++;
+				hasRunningOrQueued = true;
+			}
+			// cancelled, skipped → counted in total but not completed/failed
+		}
+
+		if (hasRunningOrQueued && currentPhase === null) {
+			currentPhase = phase;
+		}
+
+		const terminal = completed + failed;
+		const percentage = group.length > 0 ? Math.round((terminal / group.length) * 1000) / 10 : 0;
+
+		return {
+			phase,
+			index,
+			total: group.length,
+			completed,
+			failed,
+			running,
+			queued,
+			percentage,
+		};
+	});
+
+	const overallPercentage = tasks.length > 0 ? Math.round((totalTerminal / tasks.length) * 1000) / 10 : 0;
+
+	// Estimate remaining time: avg duration × remaining non-terminal tasks
+	const remainingTasks = tasks.length - totalTerminal;
+	let estimatedRemainingMs = 0;
+	if (totalDurationCount > 0 && remainingTasks > 0) {
+		const avgDuration = totalDurationSum / totalDurationCount;
+		estimatedRemainingMs = Math.round(avgDuration * remainingTasks);
+	}
+
+	return {
+		phases,
+		overallPercentage,
+		currentPhase,
+		estimatedRemainingMs,
+		totalTasks: tasks.length,
+		completedTasks: totalCompleted,
+	};
+}
+
+/**
+ * Format a human-readable phase progress line.
+ *
+ * Example: "Phase 2/4 execute: 60.0% (3/5)"
+ * Returns empty string when there are no phases.
+ */
+export function formatPhaseProgressLine(runProgress: RunProgress): string {
+	if (runProgress.phases.length === 0) return "";
+	const current = runProgress.currentPhase;
+	if (!current) {
+		// All done — show summary
+		return `All ${runProgress.phases.length} phases done: ${runProgress.overallPercentage}% (${runProgress.completedTasks}/${runProgress.totalTasks})`;
+	}
+	const currentPhaseInfo = runProgress.phases.find((p) => p.phase === current);
+	if (!currentPhaseInfo) return `${runProgress.overallPercentage}% done`;
+	const done = currentPhaseInfo.completed + currentPhaseInfo.failed;
+	return `Phase ${currentPhaseInfo.index + 1}/${runProgress.phases.length} ${current}: ${currentPhaseInfo.percentage}% (${done}/${currentPhaseInfo.total})`;
+}

package/src/runtime/pi-args.ts

@@ -57,6 +57,33 @@ export function checkCrewDepth(inputMaxDepth?: number, env: NodeJS.ProcessEnv =
 	return { depth, maxDepth, blocked: depth >= maxDepth };
 }
 
+/**
+ * Create a safe temp directory with symlink protection.
+ * 1. mkdtempSync to create the directory
+ * 2. lstatSync to verify it is not a symlink (TOCTOU safety)
+ * 3. realpathSync to resolve the canonical path
+ */
+function createSafeTempDir(base: string, prefix: string): string {
+	if (!fs.existsSync(base)) fs.mkdirSync(base, { recursive: true });
+	// Verify base dir is not a symlink (TOCTOU safety)
+	const baseStat = fs.lstatSync(base);
+	if (baseStat.isSymbolicLink()) throw new Error("Refusing to create temp dir in symlinked base: " + base);
+	// Resolve base to canonical path before joining
+	const resolvedBase = fs.realpathSync(base);
+	const rawTempDir = fs.mkdtempSync(path.join(resolvedBase, prefix));
+	try {
+		const stat = fs.lstatSync(rawTempDir);
+		if (stat.isSymbolicLink()) throw new Error("temp dir is a symlink");
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("symlink")) {
+			fs.rmSync(rawTempDir, { recursive: true, force: true });
+			throw new Error("Refusing to use symlinked temp directory.");
+		}
+		throw e;
+	}
+	return fs.realpathSync(rawTempDir);
+}
+
 export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerArgsResult {
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
@@ -83,14 +110,23 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 
 	let tempDir: string | undefined;
 	if (input.agent.systemPrompt) {
-		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-"));
+		// On Windows, prefer a subdirectory within the user's profile over system temp
+		const tmpBase = process.platform === "win32" && os.homedir()
+			? path.join(os.homedir(), ".pi-crew", "tmp")
+			: os.tmpdir();
+		tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
 		const promptPath = path.join(tempDir, `${input.agent.name.replace(/[^\w.-]/g, "_")}.md`);
 		fs.writeFileSync(promptPath, input.agent.systemPrompt, { mode: 0o600 });
 		args.push(input.agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptPath);
 	}
 
 	if (input.task.length > TASK_ARG_LIMIT) {
-		if (!tempDir) tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-"));
+		if (!tempDir) {
+			const tmpBase = process.platform === "win32" && os.homedir()
+				? path.join(os.homedir(), ".pi-crew", "tmp")
+				: os.tmpdir();
+			tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
+		}
 		const taskPath = path.join(tempDir, "task.md");
 		fs.writeFileSync(taskPath, input.task, { mode: 0o600 });
 		args.push(`@${taskPath}`);