pi-crew 0.6.0 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -84,7 +84,7 @@
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
     "diff": "^5.2.0",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "typebox": "^1.1.38"
   },
   "devDependencies": {

package/src/agents/agent-config.ts

@@ -69,7 +69,8 @@ export function getAgentSessionOptions(role: string): {
  * @param agent - The agent configuration
  * @param role - The role name to use for tool restrictions (defaults to agent.name)
  */
-export function buildAgentSessionOptions(
+/** @internal */
+function buildAgentSessionOptions(
 	agent: AgentConfig,
 	role?: string,
 ): {

package/src/benchmark/feedback-loop.ts

@@ -4,13 +4,15 @@
 
 import type { RunMetrics } from "../state/run-metrics.ts";
 
-export interface FeedbackLoopStats {
+/** @internal */
+interface FeedbackLoopStats {
 	runsObserved: number;
 	avgSuccessRate: number;
 	recommendations: string[];
 }
 
-export class FeedbackLoop {
+/** @internal */
+class FeedbackLoop {
 	private runs: RunMetrics[] = [];
 	private static readonly MAX_RUNS = 1000;
 

package/src/config/config.ts

@@ -8,6 +8,7 @@ import {
 	PiTeamsConfigSchema,
 } from "../schema/config-schema.ts";
 import { withFileLockSync } from "../state/locks.ts";
+import { atomicWriteFile } from "../state/atomic-write.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 import { suggestConfigKey } from "./suggestions.ts";
@@ -79,7 +80,17 @@ function resolveHomeDir(): string {
 	// directory (e.g. withIsolatedHome) set PI_TEAMS_HOME to a tmp dir
 	// under /tmp; we skip the check in test environments (NODE_ENV=test)
 	// so existing tests don't break.
-	if (process.env.NODE_ENV === "test" || process.env.PI_CREW_SKIP_HOME_CHECK === "1") {
+	if (process.env.PI_CREW_SKIP_HOME_CHECK === "1") {
+		return envValue;
+	}
+	// NOTE: NODE_ENV=test bypass is intentional for test isolation only.
+	// It allows tests to use isolated temporary directories (e.g. withIsolatedHome
+	// sets PI_TEAMS_HOME to /tmp). This is NOT a security boundary — tests that
+	// need the validation skipped should set PI_CREW_SKIP_HOME_CHECK=1 explicitly.
+	// WARNING: Tests must NOT rely on PI_TEAMS_HOME for security boundaries in
+	// test environments. Any test verifying path-restriction behavior should set
+	// PI_CREW_SKIP_HOME_CHECK=1 and validate the path directly.
+	if (process.env.NODE_ENV === "test") {
 		return envValue;
 	}
 	try {
@@ -481,10 +492,22 @@ function mergeConfig(
 		};
 		if (Object.keys(merged.otlp.headers ?? {}).length === 0)
 			delete merged.otlp.headers;
-		// Validate OTLP headers for injection attacks (newlines, CR, null bytes)
+		// Validate OTLP headers for injection attacks:
+		// - Check top-level keys for dangerous prototype pollution patterns
+		// - Block all control characters (except tab=0x09, newline=0x0A) to prevent
+		//   header injection via CR/LF/zero-byte/etc.
 		const invalidHeaders: string[] = [];
 		for (const [k, v] of Object.entries(merged.otlp.headers ?? {})) {
-			if (/[\r\n\x00]/.test(String(v))) { invalidHeaders.push(k); }
+			// Check top-level key for dangerous names (only top-level keys are checked)
+			const checkKey = (key: string): boolean => {
+				const lowerKey = key.toLowerCase();
+				if (DANGEROUS_OBJECT_KEYS.has(lowerKey)) return true;
+				return false;
+			};
+			if (checkKey(k)) { invalidHeaders.push(k); continue; }
+			// Block any control characters except tab (0x09) in values
+			const valStr = String(v);
+			if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(valStr)) { invalidHeaders.push(k); }
 		}
 		if (invalidHeaders.length > 0) {
 			delete merged.otlp.headers;
@@ -511,10 +534,57 @@ const LIMIT_CEILINGS = {
 	runtimeGraceTurns: 1_000,
 } as const;
 
-function asRecord(value: unknown): Record<string, unknown> | undefined {
+/**
+ * Keys that could allow prototype pollution if merged into plain objects.
+ * NOTE: This set is comprehensive for ES2023 and earlier. When upgrading JavaScript
+ * versions, verify whether new dangerous Object.prototype properties have been added
+ * that could enable prototype pollution attacks.
+ */
+const DANGEROUS_OBJECT_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+	"hasOwnProperty",
+	"toString",
+	"valueOf",
+	"isPrototypeOf",
+	"propertyIsEnumerable",
+	"toLocaleString",
+	"__defineGetter__",
+	"__defineSetter__",
+	"__lookupGetter__",
+	"__lookupSetter__",
+]);
+
+/**
+ * Strips dangerous Object.prototype keys from an object.
+ * Returns a new object built with Object.create(null) to prevent
+ * prototype pollution attacks.
+ */
+function sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+	const sanitized: Record<string, unknown> = Object.create(null);
+	for (const [key, value] of Object.entries(obj)) {
+		// Case-insensitive check to catch __Proto__, CONSTRUCTOR, etc.
+		const lowerKey = key.toLowerCase();
+		if (DANGEROUS_OBJECT_KEYS.has(lowerKey)) continue;
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			sanitized[key] = sanitizeObject(value as Record<string, unknown>);
+		} else {
+			sanitized[key] = value;
+		}
+	}
+	return sanitized;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value))
 		return undefined;
-	return value as Record<string, unknown>;
+	// Defensive: create a sanitized copy to prevent prototype pollution.
+	// Uses Object.create(null) so the result has no prototype chain.
+	// WARNING: The returned object has no prototype methods (no hasOwnProperty,
+	// toString, etc.). Use Object.hasOwn(obj, key) or
+	// Object.prototype.hasOwnProperty.call(obj, key) for property checks.
+	return sanitizeObject(value as Record<string, unknown>);
 }
 
 function parseWithSchema<T extends TSchema>(
@@ -1190,7 +1260,29 @@ function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
 
 function readConfigRecord(filePath: string): Record<string, unknown> {
 	if (!fs.existsSync(filePath)) return {};
-	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
+	// Defense-in-depth: reject config files larger than 10 MB before parsing.
+	// This prevents memory exhaustion and blocks deeply nested JSON that could
+	// cause stack overflow during parsing.
+	const MAX_CONFIG_SIZE = 10 * 1024 * 1024;
+	const stat = fs.statSync(filePath);
+	if (stat.size > MAX_CONFIG_SIZE) {
+		logInternalError(
+			"config.file-too-large",
+			new Error(`config file exceeds ${MAX_CONFIG_SIZE} bytes`),
+			`path=${filePath}; size=${stat.size}`,
+		);
+		return {};
+	}
+	// Parse with depth limit to prevent stack overflow from deeply nested JSON.
+	// Nesting beyond 100 levels is almost certainly an attack or malformed file.
+	const MAX_JSON_DEPTH = 100;
+	let depth = 0;
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"), (_key, value) => {
+		if (++depth > MAX_JSON_DEPTH) {
+			throw new Error(`config JSON exceeds max depth ${MAX_JSON_DEPTH}`);
+		}
+		return value;
+	}) as unknown;
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
 	return raw as Record<string, unknown>;
 }
@@ -1244,7 +1336,7 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 		const projectPath = projectConfigPath(cwd);
 		const projectConfig = readOptionalConfig(projectPath);
 		// SECURITY FIX: Merge project config FIRST, then user config on top.
-		// This ensures user preferences always take precedence over project settings.
+		// Precedence formula: merge(projectConfig, userConfig) = userConfig wins.
 		// Sensitive fields have already been sanitized by sanitizeProjectConfig.
 		let effectiveConfig = {};
 		if (projectConfig.exists) {
@@ -1257,6 +1349,7 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 				...projectConfig.warnings,
 				...projectSafeConfig.warnings,
 			);
+			// merge(base=projectConfig, override=userConfig) → override wins
 			effectiveConfig = mergeConfig(effectiveConfig, projectSafeConfig.config);
 		}
 		// User config always takes precedence over project config
@@ -1265,19 +1358,20 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 
 
 		// `.pi/pi-crew.json` is the project-owned config file.
-		// SECURITY FIX: User config takes precedence over project-level `.pi/pi-crew.json`.
-		// This prevents malicious project configs from overriding user preferences.
+		// Merge project config FIRST (base), then user config on top (override).
+		// This ensures user preferences always take precedence over project settings.
+		// Sensitive fields have already been sanitized by sanitizeProjectConfig.
 		const piCrewJsonPath = projectPiCrewJsonPath(cwd);
 		const piCrewJsonConfig = readOptionalConfig(piCrewJsonPath);
 		if (piCrewJsonConfig.exists) {
 			warnings.push(...piCrewJsonConfig.warnings);
-			// Merge project config first, then user config on top
 			const projectPart = sanitizeProjectConfig(
 				piCrewJsonPath,
 				config,
 				piCrewJsonConfig.config,
 			);
 			warnings.push(...projectPart.warnings);
+			// base=project config, override=user config → user wins
 			const mergedProject = mergeConfig(projectPart.config, config);
 			config = mergedProject;
 			paths.push(piCrewJsonPath);
@@ -1319,10 +1413,9 @@ export function updateConfig(
 			merged = parseConfig(raw);
 		}
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(
+		atomicWriteFile(
 			filePath,
 			`${JSON.stringify(merged, null, 2)}\n`,
-			"utf-8",
 		);
 		return { path: filePath, config: merged };
 	});
@@ -1349,11 +1442,9 @@ export function updateAutonomousConfig(
 				? (current.autonomous as Record<string, unknown>)
 				: {};
 		current.autonomous = { ...currentAutonomous, ...patch };
-		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(
+		atomicWriteFile(
 			filePath,
 			`${JSON.stringify(current, null, 2)}\n`,
-			"utf-8",
 		);
 		return { path: filePath, config: parseConfig(current) };
 	});

package/src/errors.ts

@@ -0,0 +1,107 @@
+/**
+ * Error code taxonomy for pi-crew.
+ * Maps to semantic categories matching fallow's E001-E004 pattern.
+ */
+// Implemented as const object + type alias (not `enum`) so that Node's
+// `--experimental-strip-types` can load this module. TypeScript `enum`
+// syntax is not supported in strip-only mode.
+export const ErrorCode = {
+  FileReadError: "E001",            // Cannot read a file
+  FileWriteError: "E002",           // Cannot write a file
+  TaskNotFound: "E003",             // Referenced task ID does not exist
+  InvalidStatusTransition: "E004",  // Run/task status cannot legally transition
+  ConfigError: "E005",              // Malformed config or missing required field
+  ResourceNotFound: "E006",         // Agent/team/workflow not found in discovery paths
+} as const;
+
+export type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+
+const DEFAULT_HELP: Record<ErrorCode, string | undefined> = {
+  [ErrorCode.FileReadError]: "Check that the file exists and that the process has read permission.",
+  [ErrorCode.FileWriteError]: "Check that the disk is not full and that the process has write permission.",
+  [ErrorCode.TaskNotFound]: "The task may have been removed or the run may be in an inconsistent state. Use `team status` to verify.",
+  [ErrorCode.InvalidStatusTransition]: "Verify the run status using `team status` before retrying.",
+  [ErrorCode.ConfigError]: "Check the configuration file for syntax errors or missing required fields.",
+  [ErrorCode.ResourceNotFound]: "Use `team list` to see available agents, teams, and workflows.",
+};
+
+/**
+ * Structured error type for pi-crew.
+ * Display format:
+ *   error[E001]: Failed to read manifest.json: not found
+ *     context: while loading run state
+ *     help: Check that the file exists and that the process has read permission.
+ */
+export class CrewError extends Error {
+  readonly code: ErrorCode;
+  help?: string;
+  private _context?: string;
+
+  constructor(code: ErrorCode, message: string, help?: string) {
+    super(message);
+    this.name = "CrewError";
+    this.code = code;
+    this.help = help ?? DEFAULT_HELP[code];
+    Object.defineProperty(this, "message", { enumerable: true });
+    Object.defineProperty(this, "code", { enumerable: true });
+  }
+
+  withContext(context: string): this {
+    this._context = context;
+    return this;
+  }
+
+  withHelp(help: string): this {
+    this.help = help;
+    return this;
+  }
+
+  toString(): string {
+    let out = `error[${this.code}]: ${this.message}`;
+    if (this._context) out += `\n  context: ${this._context}`;
+    if (this.help) out += `\n  help: ${this.help}`;
+    return out;
+  }
+}
+
+export const errors = {
+  fileRead(path: string, source: NodeJS.ErrnoException): CrewError {
+    return new CrewError(
+      ErrorCode.FileReadError,
+      `Failed to read ${path}: ${source.code?.toLowerCase() ?? "unknown"}`,
+    ).withContext("file system read operation");
+  },
+
+  fileWrite(path: string, source: NodeJS.ErrnoException): CrewError {
+    return new CrewError(
+      ErrorCode.FileWriteError,
+      `Failed to write ${path}: ${source.code?.toLowerCase() ?? "unknown"}`,
+    ).withContext("file system write operation");
+  },
+
+  taskNotFound(taskId: string, runId?: string): CrewError {
+    const msg = runId
+      ? `Task '${taskId}' not found in run '${runId}'`
+      : `Task '${taskId}' not found`;
+    return new CrewError(ErrorCode.TaskNotFound, msg);
+  },
+
+  invalidStatusTransition(from: string, to: string): CrewError {
+    return new CrewError(
+      ErrorCode.InvalidStatusTransition,
+      `Invalid run status transition: ${from} -> ${to}`,
+    );
+  },
+
+  config(message: string): CrewError {
+    return new CrewError(ErrorCode.ConfigError, message)
+      .withContext("configuration loading");
+  },
+
+  resourceNotFound(type: string, name: string): CrewError {
+    return new CrewError(
+      ErrorCode.ResourceNotFound,
+      `${type} '${name}' not found in any discovery path`,
+    );
+  },
+} as const;

package/src/extension/async-notifier.ts

@@ -47,7 +47,7 @@ function isTaskActive(task: TeamTaskState): boolean {
 }
 
 function markActiveTasksAndAgentsFailed(run: TeamRunManifest, message: string): void {
-	const loaded = loadRunManifestById(run.cwd, run.runId);
+	const loaded = loadRunManifestById(run.cwd, run.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 	const tasks = loaded?.tasks ?? [];
 	const failedAt = new Date().toISOString();
 	if (tasks.some(isTaskActive)) {
@@ -73,7 +73,7 @@ export function markDeadAsyncRunIfNeeded(run: TeamRunManifest, now = Date.now(),
 	const asyncPid = run.async.pid;
 	const message = `Background runner died unexpectedly; check background.log (${liveness.detail}).`;
 	return withRunLockSync(run, () => {
-		const fresh = loadRunManifestById(run.cwd, run.runId);
+		const fresh = loadRunManifestById(run.cwd, run.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 		if (!fresh || !isActiveRunStatus(fresh.manifest.status)) return undefined;
 		const failed = updateRunStatus(fresh.manifest, "failed", message);
 		markActiveTasksAndAgentsFailed(failed, message);
@@ -125,6 +125,10 @@ export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifie
 			logInternalError("async-notifier", error, `interval=${intervalMs}`);
 		}
 	}, intervalMs);
+	// Defense-in-depth: never let the notifier timer keep the event loop alive.
+	// If stopAsyncRunNotifier is missed (session switch race), the next run of
+	// this interval is harmless, but the timer must not block process exit.
+	if (typeof state.interval.unref === "function") state.interval.unref();
 }
 
 export function stopAsyncRunNotifier(state: AsyncNotifierState): void {

package/src/extension/crew-cleanup.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { logInternalError } from "../utils/internal-error.ts";
+import { cleanupAllTrackedTempDirs } from "../runtime/pi-args.ts";
 // NOTE: globalProgressTracker import kept for documentation but not directly used
 // since we don't have agent IDs to untrack. Actual progress clearing should be
 // handled by the progress tracker itself on shutdown.
@@ -112,12 +113,14 @@ async function cleanupChildProcesses(): Promise<void> {
 }
 
 async function cleanupTempDirectories(): Promise<void> {
-	// NOTE: getTempDir is not available in paths.ts.
-	// For now, just log that cleanup is pending.
-	// Actual temp directory cleanup should be implemented by the run-graph
-	// or the specific code that creates temporary workspaces.
+	// Clean up every temp dir created in this process. Previously this was
+	// a stub that just logged; it caused /tmp/pi-crew-* dirs to accumulate
+	// from killed test runs and child-pi invocations. See issue #<n>.
 	try {
-		console.log(`[pi-crew] Temp directory cleanup deferred to run-graph`);
+		const result = cleanupAllTrackedTempDirs();
+		if (result.cleaned > 0) {
+			console.log(`[pi-crew] Cleaned ${result.cleaned} tracked temp dirs (${result.failed} failed)`);
+		}
 	} catch (error) {
 		logInternalError("crew-cleanup.temp", error);
 	}

package/src/extension/cross-extension-rpc.ts

@@ -32,6 +32,8 @@ function requestId(raw: unknown): string | undefined {
 
 function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
 	if (!id) return;
+	// SECURITY: Validate requestId format to prevent channel injection.
+	if (!/^[a-zA-Z0-9_-]+$/.test(id)) return;
 	events.emit(`${channel}:reply:${id}`, payload);
 }
 
@@ -59,6 +61,36 @@ function isAllowedRpcOperation(operation: string): boolean {
 	return RPC_ALLOWED_OPERATIONS.has(operation);
 }
 
+// SECURITY (HIGH #4 fix): In-memory rate limiter for RPC run requests.
+// Prevents any extension from spawning unlimited child processes.
+const RPC_RATE_LIMIT_MAX = 5; // Max 5 RPC run requests...
+const RPC_RATE_LIMIT_WINDOW_MS = 60_000; // ...per 60 seconds
+const rpcRunTimestamps: number[] = [];
+
+function checkRpcRateLimit(): { allowed: boolean; retryAfterMs?: number } {
+	const now = Date.now();
+	// Evict entries older than the window
+	const cutoff = now - RPC_RATE_LIMIT_WINDOW_MS;
+	while (rpcRunTimestamps.length > 0 && rpcRunTimestamps[0] < cutoff) {
+		rpcRunTimestamps.shift();
+	}
+	if (rpcRunTimestamps.length >= RPC_RATE_LIMIT_MAX) {
+		const oldestInWindow = rpcRunTimestamps[0];
+		const retryAfterMs = oldestInWindow + RPC_RATE_LIMIT_WINDOW_MS - now;
+		return { allowed: false, retryAfterMs: Math.max(retryAfterMs, 1000) };
+	}
+	return { allowed: true };
+}
+
+function recordRpcRun(): void {
+	rpcRunTimestamps.push(Date.now());
+}
+
+/** Reset the RPC rate limiter. Used primarily for testing. */
+export function resetRpcRateLimit(): void {
+	rpcRunTimestamps.length = 0;
+}
+
 function isAllowedRpcRunParams(params: TeamToolParamsValue): { ok: boolean; error?: string } {
 	// SECURITY: Require explicit intent for any RPC-initiated run creation.
 	// This prevents malicious extensions from spawning child Pi processes silently.
@@ -83,6 +115,12 @@ function on(events: EventBusLike, channel: string, handler: (raw: unknown) => vo
 	return typeof unsub === "function" ? unsub : () => {};
 }
 
+// SECURITY TRUST BOUNDARY: RPC channels (pi-crew:rpc:run, pi-crew:rpc:status,
+// pi-crew:rpc:live-control) are accessible to any extension on the shared event
+// bus. Mitigations applied: rate limiting (RPC_RATE_LIMIT_MAX), explicit intent
+// requirement for runs, operation allowlist for live-control reads, and cwd
+// containment validation. A full fix requires event-bus-level origin signing.
+
 export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () => ExtensionContext | undefined): PiCrewRpcHandle | undefined {
 	if (!events) return undefined;
 	const unsubs = [
@@ -90,6 +128,16 @@ export function registerPiCrewRpc(events: EventBusLike | undefined, getCtx: () =
 		on(events, "pi-crew:rpc:run", async (raw) => {
 			const id = requestId(raw);
 			try {
+				// SECURITY (HIGH #4 fix): Rate limit RPC run requests
+				const rateLimit = checkRpcRateLimit();
+				if (!rateLimit.allowed) {
+					reply(events, "pi-crew:rpc:run", id, {
+						success: false,
+						error: `RPC run rate limit exceeded. Max ${RPC_RATE_LIMIT_MAX} requests per ${RPC_RATE_LIMIT_WINDOW_MS / 1000}s. Retry after ${Math.ceil((rateLimit.retryAfterMs ?? 60000) / 1000)}s.`,
+					});
+					return;
+				}
+				recordRpcRun();
 				const ctx = getCtx();
 				if (!ctx) throw new Error("No active pi-crew session context.");
 				// Validate payload: only allow known fields from TeamToolParamsValue