pi-crew 0.5.25 → 0.6.1

package/src/ui/tool-render.ts

@@ -29,6 +29,15 @@ export interface AgentToolResultDetails {
 	results?: Array<{ agentId?: string; status?: string; output?: string; error?: string }>;
 }
 
+/** Combined type for renderAgentToolResult — handles both nested details and flat result shapes */
+interface AgentResultData extends AgentToolResultDetails {
+	agentId?: string;
+	status?: string;
+	error?: string;
+	output?: string;
+	runId?: string;
+}
+
 // ── Helpers ─────────────────────────────────────────────────────────
 
 export function formatTokens(n: number): string {
@@ -45,7 +54,8 @@ export function formatDuration(ms: number): string {
 	return s > 0 ? `${m}m${s}s` : `${m}m`;
 }
 
-export function formatContextUsage(tokens: number, contextWindow: number | undefined): string {
+/** @internal */
+function formatContextUsage(tokens: number, contextWindow: number | undefined): string {
 	if (!contextWindow) return `${formatTokens(tokens)} ctx`;
 	const pct = (tokens / contextWindow) * 100;
 	const maxStr = contextWindow >= 1_000_000 ? `${(contextWindow / 1_000_000).toFixed(1)}M` : `${Math.round(contextWindow / 1000)}k`;
@@ -294,7 +304,7 @@ export function renderAgentToolResult(
 	_options: unknown, theme: Theme, _context: unknown,
 ): Component {
 	// Handle both nested details and flattened result shape
-	const d = (result as any).details ?? result;
+	const d = (result.details ?? result) as AgentResultData;
 	const c = new Container();
 	const w = 116;
 
@@ -351,7 +361,7 @@ export function renderAgentToolResult(
 function extractText(content: unknown[] | undefined): string {
 	if (!content) return "(no output)";
 	if (!Array.isArray(content)) return String(content);
-	return content.filter((c: any) => c?.type === "text").map((c: any) => c?.text ?? "").join("\n") || "(no output)";
+	return content.filter((c): c is Record<string, unknown> => typeof c === "object" && c !== null && (c as Record<string, unknown>).type === "text").map((c) => String((c as Record<string, unknown>).text ?? "")).join("\n") || "(no output)";
 }
 
 function parseArgs(argsStr: string | undefined): Record<string, unknown> {

package/src/utils/fingerprint.ts

@@ -0,0 +1,183 @@
+/**
+ * Incremental fingerprinting — detect file changes to skip unchanged work.
+ *
+ * Pattern origin: Understand-Anything/packages/core/src/fingerprint.ts
+ * Content hash + structural signature per file. Change classifier:
+ * NONE (unchanged), COSMETIC (whitespace/comments only), STRUCTURAL (code changed).
+ * Only STRUCTURAL changes trigger re-analysis.
+ */
+
+import { createHash, type Hash } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type ChangeClass = "NONE" | "COSMETIC" | "STRUCTURAL";
+
+export interface FileFingerprint {
+	path: string;
+	contentHash: string;
+	structuralSignature: string;
+	lastModified: number; // mtime ms
+	changeClass: ChangeClass;
+}
+
+export interface FingerprintDelta {
+	added: string[];
+	removed: string[];
+	modified: FileFingerprint[]; // only STRUCTURAL changes
+	unchanged: number;
+}
+
+// ── Fingerprinting ───────────────────────────────────────────────────────
+
+/**
+ * Compute SHA-256 content hash of a file.
+ */
+export function computeContentHash(filePath: string): string {
+	try {
+		const content = readFileSync(filePath);
+		return createHash("sha256").update(content).digest("hex");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Extract a structural signature from source code.
+ *
+ * Captures function signatures, class methods, and import specifiers.
+ * Ignores whitespace, comments, and string content.
+ * Returns a hash of the structural elements.
+ */
+export function computeStructuralSignature(content: string, filePath: string): string {
+	const lines = content.split("\n");
+	const structural: string[] = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		// Skip empty lines and comments
+		if (trimmed.length === 0) continue;
+		if (trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) continue;
+
+		// Capture structural lines
+		if (
+			// Function/method declarations
+			/^(export\s+)?(async\s+)?function\s/.test(trimmed) ||
+			/^\w+\s*\(/.test(trimmed) && !/^(if|for|while|switch|return|throw|await)/.test(trimmed) ||
+			// Class declarations
+			/^(export\s+)?(abstract\s+)?class\s/.test(trimmed) ||
+			/^(public|private|protected|static|readonly|abstract)\s/.test(trimmed) ||
+			// Interface/type declarations
+			/^(export\s+)?(interface|type)\s/.test(trimmed) ||
+			// Import declarations
+			/^import\s/.test(trimmed) ||
+			// Export declarations
+			/^export\s+(default\s+)?(const|let|var|function|class|interface|type|enum)\s/.test(trimmed)
+		) {
+			structural.push(trimmed);
+		}
+	}
+
+	return createHash("sha256").update(structural.join("\n")).digest("hex");
+}
+
+/**
+ * Classify the change between two fingerprints.
+ */
+export function classifyChange(previous: FileFingerprint | undefined, current: FileFingerprint): ChangeClass {
+	if (!previous) return "STRUCTURAL"; // New file
+
+	if (previous.contentHash === current.contentHash) return "NONE";
+	if (previous.structuralSignature === current.structuralSignature) return "COSMETIC";
+	return "STRUCTURAL";
+}
+
+/**
+ * Compute fingerprint for a single file.
+ */
+export function fingerprintFile(filePath: string): FileFingerprint {
+	const content = readFileSync(filePath, "utf-8");
+	const stat = statSync(filePath);
+
+	return {
+		path: filePath,
+		contentHash: computeContentHash(filePath),
+		structuralSignature: computeStructuralSignature(content, filePath),
+		lastModified: stat.mtimeMs,
+		changeClass: "NONE", // will be classified during delta computation
+	};
+}
+
+// ── Fingerprint Store ────────────────────────────────────────────────────
+
+const MAX_FINGERPRINTS = 10000;
+
+/**
+ * Load fingerprint baseline from a JSON file.
+ */
+export function loadFingerprintBaseline(storePath: string): Map<string, FileFingerprint> {
+	const map = new Map<string, FileFingerprint>();
+	if (!existsSync(storePath)) return map;
+
+	try {
+		const data = JSON.parse(readFileSync(storePath, "utf-8")) as FileFingerprint[];
+		for (const fp of data) {
+			if (map.size >= MAX_FINGERPRINTS) break;
+			map.set(fp.path, fp);
+		}
+	} catch (error) {
+		logInternalError("fingerprint.load", error, `storePath=${storePath}`);
+	}
+	return map;
+}
+
+/**
+ * Save fingerprint baseline to a JSON file.
+ */
+export function saveFingerprintBaseline(storePath: string, fingerprints: Map<string, FileFingerprint>): void {
+	const entries = [...fingerprints.entries()].slice(0, MAX_FINGERPRINTS).map(([, fp]) => fp);
+	writeFileSync(storePath, JSON.stringify(entries, null, 2), "utf-8");
+}
+
+/**
+ * Compute delta between baseline and current fingerprints.
+ *
+ * Only returns STRUCTURAL changes in the `modified` field.
+ */
+export function computeFingerprintDelta(
+	baseline: Map<string, FileFingerprint>,
+	current: Map<string, FileFingerprint>,
+): FingerprintDelta {
+	const added: string[] = [];
+	const removed: string[] = [];
+	const modified: FileFingerprint[] = [];
+	let unchanged = 0;
+
+	// Find added and modified
+	for (const [path, currentFp] of current) {
+		const prev = baseline.get(path);
+		const changeClass = classifyChange(prev, currentFp);
+
+		if (!prev) {
+			added.push(path);
+		} else if (changeClass === "STRUCTURAL") {
+			modified.push({ ...currentFp, changeClass: "STRUCTURAL" });
+		} else if (changeClass === "COSMETIC") {
+			unchanged++; // cosmetic = treated as unchanged for re-analysis
+		} else {
+			unchanged++;
+		}
+	}
+
+	// Find removed
+	for (const path of baseline.keys()) {
+		if (!current.has(path)) {
+			removed.push(path);
+		}
+	}
+
+	return { added, removed, modified, unchanged };
+}

package/src/utils/fs-watch.ts

@@ -2,7 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { FSWatcher, WatchListener } from "node:fs";
 
-export const FS_WATCH_RETRY_DELAY_MS = 5000;
+/** @internal */
+const FS_WATCH_RETRY_DELAY_MS = 5000;
 
 export function closeWatcher(watcher: FSWatcher | null | undefined): void {
 	if (!watcher) {
@@ -85,4 +86,5 @@ export function watchCrewState(
 }
 
 // Re-export path helper so callers don't pull node:path just for join.
-export const joinPath = path.join;
+/** @internal */
+const joinPath = path.join;

package/src/utils/gh-protocol.ts

@@ -473,7 +473,8 @@ export function resolveGitHubUrl(parsed: Parsed, scheme: "issue" | "pr", cwd: st
  * Resolve a raw `issue://` or `pr://` URL string.
  * Convenience wrapper combining parse + resolve.
  */
-export function resolveGitHubProtocol(raw: string, scheme: "issue" | "pr", cwd: string): GhResult<unknown> {
+/** @internal */
+function resolveGitHubProtocol(raw: string, scheme: "issue" | "pr", cwd: string): GhResult<unknown> {
 	const parsed = parseGitHubUrl(raw, scheme);
 	return resolveGitHubUrl(parsed, scheme, cwd);
 }

package/src/utils/safe-paths.ts

@@ -11,6 +11,9 @@ export function assertSafePathId(kind: string, value: string): string {
 }
 
 export function resolveContainedPath(baseDir: string, targetPath: string): string {
+	if (targetPath.includes('\0')) {
+		throw new Error(`Security: path contains null byte`);
+	}
 	const base = path.resolve(baseDir);
 	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
 	const relative = path.relative(base, resolved);
@@ -41,6 +44,9 @@ export function resolveRealContainedPath(baseDir: string, targetPath: string): s
 }
 
 export function resolveContainedRelativePath(baseDir: string, relativePath: string, kind = "path"): string {
+	if (relativePath.includes('\0')) {
+		throw new Error(`Security: path contains null byte: ${kind}`);
+	}
 	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
 	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
 	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));

package/src/workflows/discover-workflows.ts

@@ -11,7 +11,7 @@ export interface WorkflowDiscoveryResult {
 	project: WorkflowConfig[];
 }
 
-const STEP_CONFIG_KEYS = new Set(["role", "dependsOn", "parallelGroup", "output", "reads", "model", "skills", "progress", "worktree", "verify", "task"]);
+const STEP_CONFIG_KEYS = new Set(["role", "dependsOn", "parallelGroup", "output", "reads", "model", "skills", "progress", "worktree", "verify", "task", "seedPaths", "preStepScript", "preStepArgs", "preStepTimeout"]);
 
 function parseStepSection(id: string, body: string): WorkflowStep | undefined {
 	const lines = body.trim().split("\n");
@@ -50,6 +50,10 @@ function parseStepSection(id: string, body: string): WorkflowStep | undefined {
 		progress: config.progress === "true" ? true : config.progress === "false" ? false : undefined,
 		worktree: config.worktree === "true" ? true : config.worktree === "false" ? false : undefined,
 		verify: config.verify === "true" ? true : config.verify === "false" ? false : undefined,
+		seedPaths: parseCsv(config.seedPaths) || undefined,
+		preStepScript: config.preStepScript || undefined,
+		preStepArgs: parseCsv(config.preStepArgs) || undefined,
+		preStepTimeout: parseOptionalInteger(config.preStepTimeout) ?? undefined,
 	};
 }
 

package/src/workflows/intermediate-store.ts

@@ -0,0 +1,173 @@
+/**
+ * Phase-gated intermediate store — persist workflow step outputs to disk.
+ *
+ * Pattern origin: Understand-Anything 7-phase pipeline where each phase
+ * writes structured JSON to intermediate/ directory. Phase N reads Phase N-1
+ * output from disk (not context). Enables:
+ * - Context isolation between steps
+ * - Incremental re-runs (skip completed phases)
+ * - Debugging (inspect intermediate outputs)
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface IntermediateOutput {
+	phase: string;
+	stepId: string;
+	timestamp: string;
+	data: unknown;
+}
+
+export interface IntermediateStoreConfig {
+	/** Root directory for intermediates (e.g., ".crew/intermediate/") */
+	intermediateDir: string;
+	/** File patterns to preserve across runs (e.g., ["scan-result.json"]) */
+	preservePatterns: string[];
+}
+
+// ── Store Operations ─────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: IntermediateStoreConfig = {
+	intermediateDir: ".crew/intermediate",
+	preservePatterns: [],
+};
+
+/**
+ * Ensure the intermediate directory exists.
+ */
+export function ensureIntermediateDir(config: Partial<IntermediateStoreConfig> = {}): string {
+	const dir = config.intermediateDir ?? DEFAULT_CONFIG.intermediateDir;
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+/**
+ * Write an intermediate output for a phase.
+ *
+ * @param config - Store configuration
+ * @param phase - Phase name (e.g., "explore", "analyze")
+ * @param stepId - Step ID for correlation
+ * @param data - Phase output data
+ * @returns Path to the written file
+ */
+export function writeIntermediate(
+	config: Partial<IntermediateStoreConfig>,
+	phase: string,
+	stepId: string,
+	data: unknown,
+): string {
+	const dir = ensureIntermediateDir(config);
+	const filename = `${phase}-${stepId}.json`;
+	const filePath = path.join(dir, filename);
+
+	const output: IntermediateOutput = {
+		phase,
+		stepId,
+		timestamp: new Date().toISOString(),
+		data,
+	};
+
+	writeFileSync(filePath, JSON.stringify(output, null, 2), "utf-8");
+	return filePath;
+}
+
+/**
+ * Read an intermediate output for a phase.
+ *
+ * @param config - Store configuration
+ * @param phase - Phase name
+ * @param stepId - Step ID
+ * @returns Parsed intermediate output, or undefined if not found
+ */
+export function readIntermediate(
+	config: Partial<IntermediateStoreConfig>,
+	phase: string,
+	stepId: string,
+): IntermediateOutput | undefined {
+	const dir = config.intermediateDir ?? DEFAULT_CONFIG.intermediateDir;
+	const filename = `${phase}-${stepId}.json`;
+	const filePath = path.join(dir, filename);
+
+	if (!existsSync(filePath)) return undefined;
+
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		return JSON.parse(content) as IntermediateOutput;
+	} catch (error) {
+		logInternalError("intermediate-store.read", error, `filePath=${filePath}`);
+		return undefined;
+	}
+}
+
+/**
+ * Read the most recent intermediate output for any phase.
+ *
+ * Useful when you don't know the exact stepId but want the latest
+ * output from a phase (e.g., for incremental re-runs).
+ */
+export function readLatestIntermediate(
+	config: Partial<IntermediateStoreConfig>,
+	phase: string,
+): IntermediateOutput | undefined {
+	const dir = config.intermediateDir ?? DEFAULT_CONFIG.intermediateDir;
+	if (!existsSync(dir)) return undefined;
+
+	const files = readdirSync(dir)
+		.filter((f) => f.startsWith(`${phase}-`) && f.endsWith(".json"))
+		.sort()
+		.reverse(); // most recent first
+
+	if (files.length === 0) return undefined;
+
+	try {
+		const content = readFileSync(path.join(dir, files[0]!), "utf-8");
+		return JSON.parse(content) as IntermediateOutput;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Clean up intermediate files, preserving specified patterns.
+ *
+ * @param config - Store configuration
+ * @returns Number of files removed
+ */
+export function cleanupIntermediates(config: Partial<IntermediateStoreConfig> = {}): number {
+	const dir = config.intermediateDir ?? DEFAULT_CONFIG.intermediateDir;
+	const preserve = config.preservePatterns ?? DEFAULT_CONFIG.preservePatterns;
+
+	if (!existsSync(dir)) return 0;
+
+	const files = readdirSync(dir);
+	let removed = 0;
+
+	for (const file of files) {
+		const shouldPreserve = preserve.some((pattern) => file.includes(pattern));
+		if (!shouldPreserve) {
+			try {
+				unlinkSync(path.join(dir, file));
+				removed++;
+			} catch (error) {
+				logInternalError("intermediate-store.cleanup", error, `file=${file}`);
+			}
+		}
+	}
+
+	return removed;
+}
+
+/**
+ * Check if a phase has completed (intermediate exists).
+ */
+export function hasPhaseCompleted(
+	config: Partial<IntermediateStoreConfig>,
+	phase: string,
+	stepId: string,
+): boolean {
+	return readIntermediate(config, phase, stepId) !== undefined;
+}

package/src/workflows/workflow-config.ts

@@ -17,6 +17,14 @@ export interface WorkflowStep {
 	/** 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;
 }
 
 export interface WorkflowConfig {

package/src/worktree/cleanup.ts

@@ -5,6 +5,7 @@ import type { TeamRunManifest } from "../state/types.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 
 export interface WorktreeCleanupResult {
 	removed: string[];
@@ -14,8 +15,10 @@ export interface WorktreeCleanupResult {
 	committedBranches: string[];
 }
 
+const GIT_SAFE_ENV = { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL", "PI_*", "PI_CREW_*"] }), LANG: "C", LC_ALL: "C" };
+
 function git(cwd: string, args: string[]): string {
-	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true }).trim();
+	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: GIT_SAFE_ENV, windowsHide: true }).trim();
 }
 
 function isDirty(worktreePath: string): boolean {
@@ -58,21 +61,21 @@ export function cleanupRunWorktrees(manifest: TeamRunManifest, options: { force?
 		if (dirty) {
 			// Commit changes to a branch instead of just preserving the worktree
 			try {
-				execFileSync("git", ["add", "-A"], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true });
+				execFileSync("git", ["add", "-A"], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: GIT_SAFE_ENV, windowsHide: true });
 				let safeDesc = entry.name.slice(0, 200);
 				// SECURITY: Strip any newlines that could be injected via a malicious worktree name
 				// to prevent newline injection in git commit messages
 				if (safeDesc.includes("\n")) {
 					safeDesc = safeDesc.replace(/[\r\n]+/g, " ");
 				}
-				execFileSync("git", ["commit", "-m", `pi-crew: ${safeDesc}`], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true });
+				execFileSync("git", ["commit", "-m", `pi-crew: ${safeDesc}`], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: GIT_SAFE_ENV, windowsHide: true });
 				// Create branch in the main repo pointing to this worktree's HEAD
 				try {
-					execFileSync("git", ["branch", branchName], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true });
+					execFileSync("git", ["branch", branchName], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: GIT_SAFE_ENV, windowsHide: true });
 				} catch {
 					// Branch already exists — use timestamp suffix
 					const tsBranch = `${branchName}-${Date.now()}`;
-					execFileSync("git", ["branch", tsBranch], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true });
+					execFileSync("git", ["branch", tsBranch], { cwd: worktreePath, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: GIT_SAFE_ENV, windowsHide: true });
 				}
 				result.committedBranches.push(branchName);
 				// Remove the worktree (branch persists)

package/src/worktree/worktree-manager.ts

@@ -25,7 +25,7 @@ export interface WorktreeDiffStat {
 }
 
 function git(cwd: string, args: string[]): string {
-	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LANG: "C", LC_ALL: "C" }, windowsHide: true }).trim();
+	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL", "PI_*", "PI_CREW_*"] }), LANG: "C", LC_ALL: "C" }, windowsHide: true }).trim();
 }
 
 function sanitizeBranchPart(value: string): string {