pi-crew 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.5.8] — Final 5 Low-Severity Issue Fixes (2026-06-01)
+
+### Phase 5 (Final): Race Conditions + Edge Cases
+
+- **Issue #12: `acquireLockWithRetry` race** (Low) — `src/state/locks.ts`: added `isLockHolderAlive()` check. Now uses BOTH staleness AND PID liveness: fresh + alive holder = fail, else = safe to clear. Prevents stealing a lock from a still-running process whose PID was recently reused.
+
+- **Issue #13: `loadRunManifestById` TOCTOU** (Low) — `src/state/state-store.ts`: retry-on-stat-mismatch approach. Re-stat and re-read in a loop (up to 3 attempts) until size/mtime are stable across stat and read. Catches torn writes without depending on `withFileLockSync`.
+
+- **Issue #14: `cleanupOldArtifacts` N stat calls** (Low) — `src/state/artifact-store.ts`: use `Dirent.isDirectory()` from `readdirSync({ withFileTypes: true })` to avoid `statSync` for type info. `statSync` now only for mtime.
+
+- **Issue #15: `validateMailbox` concurrent access** (Low) — `src/state/mailbox.ts`: wrap read + optional repair in `withFileLockSync`.
+
+- **Issue #16: `updateMailboxMessageReply` concurrent rewrite** (Low) — `src/state/mailbox.ts`: wrap read-modify-write in `withFileLockSync`.
+
+### Bug fix in `withFileLockSync`
+
+- `src/state/locks.ts`: use separate `.lock` sidecar instead of the file path itself. Previously `withFileLockSync(path)` used `path` as the lock file, colliding with append/read operations on the same path.
+
+### Tests
+
+- 2282 tests pass / 0 failures (`npm test`).
+
 ## [0.5.7] — 11 Issue Fixes Across 5 Phases (2026-06-01)
 
 ### Phase 1: Schema/Type Fixes

package/README.md

@@ -9,7 +9,7 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.5.7**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.5.8**: See [CHANGELOG.md](CHANGELOG.md).
 
 ### Security highlights (v0.5.5)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/state/artifact-store.ts

@@ -66,6 +66,10 @@ export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactClea
 	const cutoff = nowMs() - maxAgeMs;
 	let didCleanup = false;
 	try {
+		// FIX: Use { withFileTypes: true } to get Dirent objects (with isDirectory/isFile
+		// info), avoiding the need for a separate statSync per entry just to check the
+		// type. We still need statSync for mtime, but only on entries that passed the
+		// marker-file and symlink filters.
 		const entries = fs.readdirSync(artifactsRoot, { withFileTypes: true });
 		for (const entry of entries) {
 			if (entry.name === markerFile) continue;
@@ -74,7 +78,8 @@ export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactClea
 			try {
 				const stat = fs.statSync(target);
 				if (stat.mtimeMs >= cutoff) continue;
-				if (stat.isDirectory()) {
+				// Use Dirent info instead of stat.isDirectory() to save a stat call
+				if (entry.isDirectory()) {
 					fs.rmSync(target, { recursive: true, force: true });
 				} else {
 					fs.unlinkSync(target);

package/src/state/locks.ts

@@ -40,6 +40,25 @@ function isLockStale(filePath: string, staleMs: number): boolean {
 	}
 }
 
+function isLockHolderAlive(filePath: string): boolean {
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw) as { pid?: unknown };
+		const pid = typeof parsed.pid === "number" ? parsed.pid : undefined;
+		if (pid === undefined) return true; // Unknown holder — assume alive to be safe
+		try {
+			process.kill(pid, 0);
+			return true; // Signal 0 succeeded — process is alive
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			// EPERM: process exists but we don't have permission to signal it
+			return code === "EPERM";
+		}
+	} catch {
+		return true; // Can't read — assume alive to be safe
+	}
+}
+
 function writeLockFile(filePath: string): void {
 	const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
 	try {
@@ -62,11 +81,17 @@ function acquireLockWithRetry(filePath: string, staleMs: number): void {
 			if (Date.now() > deadline) {
 				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
 			}
-			// If lock is not stale, fail fast (sync should not wait for active locks)
-			if (!isLockStale(filePath, staleMs)) {
+			// FIX: Use both staleness AND PID liveness to decide if we can steal
+			// a lock. Previously only staleness was checked, so a process whose
+			// PID was recently reused by another process could have its lock
+			// stolen even while still active. Now: fresh+alive = fail, else = clear.
+			const isStale = isLockStale(filePath, staleMs);
+			const isHolderAlive = isLockHolderAlive(filePath);
+			if (!isStale && isHolderAlive) {
+				// Lock is fresh AND holder is alive — fail fast
 				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
 			}
-			// Lock is stale — try to clear it, but don't bail on rmSync error — let loop retry
+			// Lock is stale OR holder is dead — safe to clear
 			try {
 				fs.rmSync(filePath, { force: true });
 			} catch { /* race — let loop retry */ }
@@ -118,14 +143,19 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number): Pro
  * Uses the same O_EXCL atomic create strategy as run locks.
  */
 export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunLockOptions = {}): T {
+	// FIX: Use a separate .lock sidecar so the lock file doesn't collide with
+	// the file being protected. Previously withFileLockSync used the file path
+	// itself as the lock, which meant any operation on the same file (read,
+	// append, or even the lock acquisition itself) would race with the lock.
+	const lockFile = `${filePath}.lock`;
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	acquireLockWithRetry(filePath, staleMs);
+	fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+	acquireLockWithRetry(lockFile, staleMs);
 	try {
 		return fn();
 	} finally {
 		try {
-			fs.rmSync(filePath, { force: true });
+			fs.rmSync(lockFile, { force: true });
 		} catch {
 			// Best-effort lock cleanup.
 		}

package/src/state/mailbox.ts

@@ -6,6 +6,7 @@ import { redactSecrets } from "../utils/redaction.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { withEventLogLockSync } from "./event-log.ts";
+import { withFileLockSync } from "./locks.ts";
 import { DEFAULT_MAILBOX } from "../config/defaults.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
@@ -419,29 +420,34 @@ export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMes
 
 	for (const { filePath, direction } of filesToSearch) {
 		if (!fs.existsSync(filePath)) continue;
-		const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
-		let found = false;
-		const updatedLines: string[] = [];
-		for (const line of lines) {
-			try {
-				const parsed = JSON.parse(line) as unknown;
-				const msg = parseMailboxMessage(parsed, direction);
-				if (msg && msg.id === originalMessageId) {
-					msg.repliedAt = new Date().toISOString();
-					msg.replyContent = replyContent;
-					updatedLines.push(JSON.stringify(redactSecrets(msg)));
-					found = true;
-				} else {
+		// FIX: Wrap read-modify-write in withFileLockSync to prevent concurrent
+		// updates from clobbering each other (each reply rewrites the whole file).
+		const found = withFileLockSync(filePath, () => {
+			const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+			let localFound = false;
+			const updatedLines: string[] = [];
+			for (const line of lines) {
+				try {
+					const parsed = JSON.parse(line) as unknown;
+					const msg = parseMailboxMessage(parsed, direction);
+					if (msg && msg.id === originalMessageId) {
+						msg.repliedAt = new Date().toISOString();
+						msg.replyContent = replyContent;
+						updatedLines.push(JSON.stringify(redactSecrets(msg)));
+						localFound = true;
+					} else {
+						updatedLines.push(line);
+					}
+				} catch {
 					updatedLines.push(line);
 				}
-			} catch {
-				updatedLines.push(line);
 			}
-		}
-		if (found) {
-			atomicWriteFile(filePath, `${updatedLines.join("\n")}\n`);
-			return;
-		}
+			if (localFound) {
+				atomicWriteFile(filePath, `${updatedLines.join("\n")}\n`);
+			}
+			return localFound;
+		});
+		if (found) return;
 	}
 	// Not finding the original is non-fatal; the reply is still delivered.
 }
@@ -464,26 +470,31 @@ export function validateMailbox(manifest: TeamRunManifest, options: { repair?: b
 	for (const direction of ["inbox", "outbox"] as const) {
 		if (options.signal?.aborted) break;
 		const filePath = mailboxFile(manifest, direction);
-		const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
-		const validLines: string[] = [];
-		for (let i = 0; i < lines.length; i += 1) {
-			if (options.signal?.aborted) break;
-			const line = lines[i];
-			if (!line) continue;
-			try {
-				const parsed = JSON.parse(line) as unknown;
-				const message = parseMailboxMessage(parsed, direction);
-				if (!message) throw new Error("invalid message schema");
-				validLines.push(JSON.stringify(redactSecrets(message)));
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				issues.push({ level: "error", path: filePath, message });
+		// FIX: Wrap read + optional repair in withFileLockSync so concurrent appends
+		// don't race with the read-modify-write. Mailbox files are capped at 10MB
+		// (MAILBOX_ARCHIVE_THRESHOLD_BYTES), so the per-call memory is bounded.
+		withFileLockSync(filePath, () => {
+			const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+			const validLines: string[] = [];
+			for (let i = 0; i < lines.length; i += 1) {
+				if (options.signal?.aborted) break;
+				const line = lines[i];
+				if (!line) continue;
+				try {
+					const parsed = JSON.parse(line) as unknown;
+					const message = parseMailboxMessage(parsed, direction);
+					if (!message) throw new Error("invalid message schema");
+					validLines.push(JSON.stringify(redactSecrets(message)));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					issues.push({ level: "error", path: filePath, message });
+				}
 			}
-		}
-		if (options.repair && validLines.length !== lines.length) {
-			atomicWriteFile(filePath, `${validLines.join("\n")}${validLines.length ? "\n" : ""}`);
-			repaired.push(filePath);
-		}
+			if (options.repair && validLines.length !== lines.length) {
+				atomicWriteFile(filePath, `${validLines.join("\n")}${validLines.length ? "\n" : ""}`);
+				repaired.push(filePath);
+			}
+		});
 	}
 	const delivery = readDeliveryState(manifest);
 	const allMessages = readMailbox(manifest);

package/src/state/state-store.ts

@@ -324,18 +324,39 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 		}
 	}
 
-	const manifest = readJsonFile<TeamRunManifest>(manifestPath);
+	// FIX: Re-stat and re-read inside a single synchronous block to close the
+	// TOCTOU window. We use a sentinel-based re-read: if mtime/size changed
+	// between the initial stat and the read, re-read until stable. With file
+	// sizes typically small (<5MB), the extra cost is negligible. Note: this
+	// doesn't fully prevent torn writes — callers needing strict consistency
+	// should use withRunLock() around the whole load+modify+save sequence.
+	let attempts = 0;
+	let manifest: TeamRunManifest | undefined;
+	let tasks: TeamTaskState[] | undefined;
+	while (attempts < 3) {
+		const freshStat = fs.statSync(manifestPath);
+		manifest = readJsonFile<TeamRunManifest>(manifestPath);
+		const freshTasksStat = fs.existsSync(tasksPath) ? fs.statSync(tasksPath) : undefined;
+		tasks = readJsonFile<TeamTaskState[]>(tasksPath) ?? [];
+		// If size/mtime didn't change between stat and read, we're consistent.
+		if (freshStat.mtimeMs === manifestStat.mtimeMs && freshStat.size === manifestStat.size
+			&& (!freshTasksStat || (freshTasksStat.mtimeMs === tasksStat?.mtimeMs && freshTasksStat.size === tasksStat?.size))) {
+			break;
+		}
+		attempts += 1;
+		manifestStat = freshStat;
+		tasksStat = freshTasksStat;
+	}
 	if (!manifest || !validateRunManifestPaths(cwd, runId, manifest, stateRoot, tasksPath)) return undefined;
-	const tasks = readJsonFile<TeamTaskState[]>(tasksPath) ?? [];
 	setManifestCache(stateRoot, {
 		manifest,
-		tasks,
+		tasks: tasks ?? [],
 		manifestMtimeMs: manifestStat.mtimeMs,
 		manifestSize: manifestStat.size,
 		tasksMtimeMs,
 		tasksSize: tasksStat?.size ?? 0,
 	});
-	return { manifest, tasks };
+	return { manifest, tasks: tasks ?? [] };
 }
 
 export async function loadRunManifestByIdAsync(cwd: string, runId: string): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined> {