pi-crew 0.6.1 → 0.6.4

package/src/state/decision-ledger.ts

@@ -1,6 +1,9 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
-import { dirname } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { assertSafePathId } from "../utils/safe-paths.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
+import { withFileLockSync } from "./locks.ts";
 
 export interface CoherenceMark {
 	matchesPrior: boolean;
@@ -24,16 +27,27 @@ export interface RolloutEntry {
  * Get the ledger file path for a given run ID.
  * SECURITY: Accept stateRoot param to use it for path computation
  * instead of hardcoded path, ensuring stateRoot containment.
+ * Uses projectCrewRoot() to honour the `.pi/teams/` fallback for `.pi`-based
+ * projects (see issue #29).
  */
-function getLedgerPath(runId: string, stateRoot?: string): string {
-	const base = stateRoot ?? `.crew/state/runs/${runId}`;
+function getLedgerPath(
+	runId: string,
+	stateRoot?: string,
+	cwd?: string,
+): string {
+	const base =
+		stateRoot ??
+		join(projectCrewRoot(cwd ?? process.cwd()), "state", "runs", runId);
 	return `${base}/decision-ledger.jsonl`;
 }
 
 /**
  * Compute coherence marks based on existing ledger entries.
  */
-function computeCoherence(entry: RolloutEntry, ledger: RolloutEntry[]): CoherenceMark {
+function computeCoherence(
+	entry: RolloutEntry,
+	ledger: RolloutEntry[],
+): CoherenceMark {
 	if (ledger.length === 0) {
 		return {
 			matchesPrior: false,
@@ -46,15 +60,21 @@ function computeCoherence(entry: RolloutEntry, ledger: RolloutEntry[]): Coherenc
 	const previousEntry = ledger[ledger.length - 1];
 	const matchesPrior: boolean =
 		entry.decisionMark === previousEntry.decisionMark ||
-		Boolean(entry.priorWinner && entry.topCandidates.includes(entry.priorWinner));
+		Boolean(
+			entry.priorWinner &&
+				entry.topCandidates.includes(entry.priorWinner),
+		);
 
 	// Check last 10 entries for recursive pattern
 	const recentEntries = ledger.slice(-10);
 	const recentDecisions = recentEntries.map((e) => e.decisionMark);
 	const currentDecision = entry.decisionMark;
 
-	const recursiveMatches = recentDecisions.filter((d) => d === currentDecision).length;
-	const matchesRecursive = recursiveMatches >= Math.ceil(recentDecisions.length / 2); // At least half match
+	const recursiveMatches = recentDecisions.filter(
+		(d) => d === currentDecision,
+	).length;
+	const matchesRecursive =
+		recursiveMatches >= Math.ceil(recentDecisions.length / 2); // At least half match
 
 	const promotionAllowed = matchesPrior || matchesRecursive;
 
@@ -82,6 +102,7 @@ function computeCoherence(entry: RolloutEntry, ledger: RolloutEntry[]): Coherenc
  * Creates the directory and ledger file if they don't exist.
  */
 export function initLedger(runId: string): void {
+	assertSafePathId("runId", runId);
 	const ledgerPath = getLedgerPath(runId);
 	const dir = dirname(ledgerPath);
 
@@ -99,8 +120,11 @@ export function initLedger(runId: string): void {
  * Append a new entry to the decision ledger.
  * Automatically computes and adds coherence marks.
  * FIX: Uses atomic write to prevent partial writes on crash.
+ * FIX: Uses withFileLockSync to prevent concurrent appendEntry calls from
+ * losing entries (classic read-check-write race).
  */
 export function appendEntry(runId: string, entry: RolloutEntry): RolloutEntry {
+	assertSafePathId("runId", runId);
 	// Ensure directory exists
 	const ledgerPath = getLedgerPath(runId);
 	const dir = dirname(ledgerPath);
@@ -108,28 +132,35 @@ export function appendEntry(runId: string, entry: RolloutEntry): RolloutEntry {
 		mkdirSync(dir, { recursive: true });
 	}
 
-	// Get existing entries to compute coherence (and use same result for write)
-	const ledger = getLedger(runId);
-
-	// Compute coherence
-	const coherenceMark = computeCoherence(entry, ledger);
-	const entryWithCoherence: RolloutEntry = {
-		...entry,
-		coherenceMark,
-	};
-
-	// Append to JSONL file using atomic write to prevent corruption
-	// Use the already-loaded ledger content (no double-read)
-	const line = JSON.stringify(entryWithCoherence) + "\n";
-	const existingContent = ledger.length > 0 ? ledger.map((e) => JSON.stringify(e)).join("\n") + "\n" : "";
-	atomicWriteFile(ledgerPath, existingContent + line);
-	return entryWithCoherence;
+	// FIX: Wrap read+write in file lock to prevent concurrent writers from
+	// reading stale state and overwriting each other's entries.
+	let entryWithCoherence: RolloutEntry;
+	withFileLockSync(ledgerPath, () => {
+		// Get existing entries to compute coherence (and use same result for write)
+		const ledger = getLedger(runId);
+
+		// Compute coherence
+		const coherenceMark = computeCoherence(entry, ledger);
+		entryWithCoherence = { ...entry, coherenceMark };
+
+		// Append to JSONL file using atomic write to prevent corruption
+		// Use the already-loaded ledger content (no double-read)
+		const line = JSON.stringify(entryWithCoherence) + "\n";
+		const existingContent =
+			ledger.length > 0
+				? ledger.map((e) => JSON.stringify(e)).join("\n") + "\n"
+				: "";
+		atomicWriteFile(ledgerPath, existingContent + line);
+	});
+
+	return entryWithCoherence!;
 }
 
 /**
  * Read all entries from the decision ledger.
  */
 export function getLedger(runId: string): RolloutEntry[] {
+	assertSafePathId("runId", runId);
 	const ledgerPath = getLedgerPath(runId);
 
 	if (!existsSync(ledgerPath)) {
@@ -151,6 +182,7 @@ export function getLedger(runId: string): RolloutEntry[] {
  * Get the most recent entry from the decision ledger.
  */
 export function getLatestDecision(runId: string): RolloutEntry | null {
+	assertSafePathId("runId", runId);
 	const ledger = getLedger(runId);
 	if (ledger.length === 0) {
 		return null;
@@ -162,6 +194,7 @@ export function getLatestDecision(runId: string): RolloutEntry | null {
  * Generate a human-readable markdown summary of the ledger.
  */
 export function summarizeLedger(runId: string): string {
+	assertSafePathId("runId", runId);
 	const ledger = getLedger(runId);
 
 	if (ledger.length === 0) {
@@ -191,12 +224,20 @@ export function summarizeLedger(runId: string): string {
 			lines.push(`- **Prior Winner**: ${entry.priorWinner}`);
 		}
 
-		lines.push(`- **Top Candidates**: ${entry.topCandidates.join(", ") || "(none)"}`);
+		lines.push(
+			`- **Top Candidates**: ${entry.topCandidates.join(", ") || "(none)"}`,
+		);
 		lines.push("");
 		lines.push("#### Coherence");
-		lines.push(`- **Matches Prior**: ${entry.coherenceMark.matchesPrior ? "✓" : "✗"}`);
-		lines.push(`- **Matches Recursive**: ${entry.coherenceMark.matchesRecursive ? "✓" : "✗"}`);
-		lines.push(`- **Promotion Allowed**: ${entry.coherenceMark.promotionAllowed ? "✓" : "✗"}`);
+		lines.push(
+			`- **Matches Prior**: ${entry.coherenceMark.matchesPrior ? "✓" : "✗"}`,
+		);
+		lines.push(
+			`- **Matches Recursive**: ${entry.coherenceMark.matchesRecursive ? "✓" : "✗"}`,
+		);
+		lines.push(
+			`- **Promotion Allowed**: ${entry.coherenceMark.promotionAllowed ? "✓" : "✗"}`,
+		);
 		lines.push(`- **Reason**: ${entry.coherenceMark.reason}`);
 		lines.push("");
 	}
@@ -218,8 +259,12 @@ export function summarizeLedger(runId: string): string {
 	lines.push(`| Decay    | ${decayCount} |`);
 	lines.push("");
 
-	const promotedCount = ledger.filter((e) => e.coherenceMark.promotionAllowed).length;
-	lines.push(`**Promotion Rate**: ${promotedCount}/${ledger.length} (${((promotedCount / ledger.length) * 100).toFixed(1)}%)`);
+	const promotedCount = ledger.filter(
+		(e) => e.coherenceMark.promotionAllowed,
+	).length;
+	lines.push(
+		`**Promotion Rate**: ${promotedCount}/${ledger.length} (${((promotedCount / ledger.length) * 100).toFixed(1)}%)`,
+	);
 
 	return lines.join("\n");
 }
@@ -229,110 +274,126 @@ export function summarizeLedger(runId: string): string {
  * FIX: This preserves all previous entries while updating just the last one.
  * Previously this would truncate the entire ledger!
  */
-function overrideLastEntry(runId: string, coherenceMark: import("./types.js").CoherenceMark): RolloutEntry {
-	const ledger = getLedger(runId);
-	if (ledger.length === 0) {
-		throw new Error(`No ledger entries found for run ${runId}`);
-	}
-	// Update the last entry with the new coherence mark
-	const lastIndex = ledger.length - 1;
-	ledger[lastIndex] = { ...ledger[lastIndex], coherenceMark };
-	// Rewrite entire ledger to preserve all entries
-	const ledgerPath = getLedgerPath(runId);
-	atomicWriteFile(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n");
-	return ledger[lastIndex];
-}
+// NOTE: overrideLastEntry was dead code (never called). Removed in post-v0.6.2 review.
+// If needed in the future, re-implement with assertSafePathId guard.
 
 /**
  * Promote a candidate by marking it as accepted with proper coherence.
+ * FIX: Wrap read+write in file lock to prevent concurrent promotion/decay
+ * calls from losing entries.
  */
-export function promoteCandidate(runId: string, candidate: string): RolloutEntry {
-	const latestDecision = getLatestDecision(runId);
+export function promoteCandidate(
+	runId: string,
+	candidate: string,
+): RolloutEntry {
+	assertSafePathId("runId", runId);
+	assertSafePathId("candidate", candidate);
 
-	// Get existing entries to compute proper coherence
-	const ledger = getLedger(runId);
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
 
-	// Create entry without coherence first
-	const entryWithoutCoherence = {
-		rolloutId: `promote-${Date.now()}`,
-		timestamp: new Date().toISOString(),
-		priorWinner: latestDecision?.topCandidates[0],
-		searchSpace: latestDecision?.searchSpace || "unknown",
-		trialCount: (latestDecision?.trialCount || 0) + 1,
-		topCandidates: [candidate],
-		decisionMark: "accept" as const,
-	};
+	let entry: RolloutEntry;
+	withFileLockSync(ledgerPath, () => {
+		const latestDecision = getLatestDecision(runId);
+
+		// Get existing entries to compute proper coherence
+		const ledger = getLedger(runId);
+
+		// Create entry without coherence first
+		const entryWithoutCoherence = {
+			rolloutId: `promote-${Date.now()}`,
+			timestamp: new Date().toISOString(),
+			priorWinner: latestDecision?.topCandidates[0],
+			searchSpace: latestDecision?.searchSpace || "unknown",
+			trialCount: (latestDecision?.trialCount || 0) + 1,
+			topCandidates: [candidate],
+			decisionMark: "accept" as const,
+		};
 
-	// Compute coherence (empty ledger = no matches)
-	const coherenceMark = computeCoherence(entryWithoutCoherence as RolloutEntry, ledger);
+		// Compute coherence (empty ledger = no matches)
+		const coherenceMark = computeCoherence(
+			entryWithoutCoherence as RolloutEntry,
+			ledger,
+		);
 
-	// Manual promotion always allows further promotion
-	coherenceMark.promotionAllowed = true;
-	coherenceMark.reason = "Manual promotion - promotion allowed";
+		// Manual promotion always allows further promotion
+		coherenceMark.promotionAllowed = true;
+		coherenceMark.reason = "Manual promotion - promotion allowed";
 
-	// Create full entry with coherence
-	const entry: RolloutEntry = {
-		...entryWithoutCoherence,
-		coherenceMark,
-	};
+		// Create full entry with coherence
+		entry = { ...entryWithoutCoherence, coherenceMark };
 
-	// Always push new entry (append-only pattern)
-	ledger.push(entry);
+		// Always push new entry (append-only pattern)
+		ledger.push(entry);
 
-	// Rewrite entire ledger atomically to preserve all entries
-	const ledgerPath = getLedgerPath(runId);
-	const dir = dirname(ledgerPath);
-	if (!existsSync(dir)) {
-		mkdirSync(dir, { recursive: true });
-	}
-	atomicWriteFile(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n");
+		// Rewrite entire ledger atomically to preserve all entries
+		atomicWriteFile(
+			ledgerPath,
+			ledger.map((e) => JSON.stringify(e)).join("\n") + "\n",
+		);
+	});
 
-	return entry;
+	return entry!;
 }
 
 /**
  * Decay a candidate by marking it as accepted with proper coherence.
+ * FIX: Wrap read+write in file lock to prevent concurrent promotion/decay
+ * calls from losing entries.
  */
 export function decayCandidate(runId: string, candidate: string): RolloutEntry {
-	const latestDecision = getLatestDecision(runId);
+	assertSafePathId("runId", runId);
+	assertSafePathId("candidate", candidate);
 
-	// Get existing entries to compute proper coherence
-	const ledger = getLedger(runId);
+	const ledgerPath = getLedgerPath(runId);
+	const dir = dirname(ledgerPath);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
 
-	// Create entry without coherence first
-	const entryWithoutCoherence = {
-		rolloutId: `decay-${Date.now()}`,
-		timestamp: new Date().toISOString(),
-		priorWinner: latestDecision?.topCandidates[0],
-		searchSpace: latestDecision?.searchSpace || "unknown",
-		trialCount: (latestDecision?.trialCount || 0) + 1,
-		topCandidates: [candidate],
-		decisionMark: "decay" as const,
-	};
+	let entry: RolloutEntry;
+	withFileLockSync(ledgerPath, () => {
+		const latestDecision = getLatestDecision(runId);
+
+		// Get existing entries to compute proper coherence
+		const ledger = getLedger(runId);
+
+		// Create entry without coherence first
+		const entryWithoutCoherence = {
+			rolloutId: `decay-${Date.now()}`,
+			timestamp: new Date().toISOString(),
+			priorWinner: latestDecision?.topCandidates[0],
+			searchSpace: latestDecision?.searchSpace || "unknown",
+			trialCount: (latestDecision?.trialCount || 0) + 1,
+			topCandidates: [candidate],
+			decisionMark: "decay" as const,
+		};
 
-	// Compute coherence (empty ledger = no matches)
-	const coherenceMark = computeCoherence(entryWithoutCoherence as RolloutEntry, ledger);
+		// Compute coherence (empty ledger = no matches)
+		const coherenceMark = computeCoherence(
+			entryWithoutCoherence as RolloutEntry,
+			ledger,
+		);
 
-	// Manual decay never allows promotion
-	coherenceMark.promotionAllowed = false;
-	coherenceMark.reason = "Manual decay - promotion not allowed";
+		// Manual decay never allows promotion
+		coherenceMark.promotionAllowed = false;
+		coherenceMark.reason = "Manual decay - promotion not allowed";
 
-	// Create full entry with coherence
-	const entry: RolloutEntry = {
-		...entryWithoutCoherence,
-		coherenceMark,
-	};
+		// Create full entry with coherence
+		entry = { ...entryWithoutCoherence, coherenceMark };
 
-	// Always push new entry (append-only pattern)
-	ledger.push(entry);
+		// Always push new entry (append-only pattern)
+		ledger.push(entry);
 
-	// Rewrite entire ledger to preserve all entries
-	const ledgerPath = getLedgerPath(runId);
-	const dir = dirname(ledgerPath);
-	if (!existsSync(dir)) {
-		mkdirSync(dir, { recursive: true });
-	}
-	atomicWriteFile(ledgerPath, ledger.map((e) => JSON.stringify(e)).join("\n") + "\n");
+		// Rewrite entire ledger to preserve all entries
+		atomicWriteFile(
+			ledgerPath,
+			ledger.map((e) => JSON.stringify(e)).join("\n") + "\n",
+		);
+	});
 
-	return entry;
-}
+	return entry!;
+}

package/src/state/event-log-rotation.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { readEvents } from "./event-log.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { withEventLogLockSync } from "./event-log.ts";
 
 export interface RotationConfig {
 	maxFileSizeBytes: number;
@@ -47,6 +48,7 @@ export interface CompactionResult {
 	compactedSize: number;
 	eventsRemoved: number;
 	eventsKept: number;
+	recoveryFailed?: boolean;
 }
 
 /**
@@ -72,54 +74,74 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
 	if (originalCount <= cfg.compactToCount) return undefined;
 	const kept = allEvents.slice(-cfg.compactToCount);
 	const lines = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
-	try {
-		atomicWriteFile(eventsPath, lines);
-	} catch {
-		// Concurrent write conflict — skip compaction this cycle
-		return undefined;
-	}
-	// C2: Re-read to recover any events appended during the compaction window.
-	// If events were appended and then overwritten by atomicWriteFile, they are LOST.
-	// Detect this and re-append any missing events.
-	try {
-		const afterWrite = readEvents(eventsPath);
-		const appendedDuringWindow = afterWrite.length - kept.length;
-		if (appendedDuringWindow >= 0) {
-			// No data loss — either events were appended and kept, or nothing happened.
+
+	// FIX: Wrap entire read-compact-write-recover sequence in lock to prevent
+	// event loss during compaction. Without lock, events can be appended between
+	// read and write, lost silently.
+	return withEventLogLockSync(eventsPath, () => {
+		try {
+			atomicWriteFile(eventsPath, lines);
+		} catch (err) {
+			// Concurrent write conflict — skip compaction this cycle
+			logInternalError("event-log-rotation.compact", err, `eventsPath=${eventsPath}`);
+			return undefined;
+		}
+		// C2: Re-read to recover any events appended during the compaction window.
+			// Events appended during the compaction window are preserved because they
+			// appear in afterWrite and the condition afterWrite.length >= kept.length is
+			// true, so they are included in the return stats without entering the
+			// recovery branch.
+		try {
+			const afterWrite = readEvents(eventsPath);
+			// FIX: Check if events were actually lost (afterWrite.length < kept.length)
+			// rather than using appendedDuringWindow >= 0 which is always true.
+			// Also use sequence numbers for comparison instead of JSON.stringify
+			// which is fragile due to key ordering and floating point differences.
+			if (afterWrite.length >= kept.length) {
+				// No data loss — either events were appended and kept, or nothing happened.
+				return {
+					originalSize,
+					compactedSize: fs.statSync(eventsPath).size,
+					eventsRemoved: originalCount - kept.length,
+					eventsKept: kept.length + Math.max(0, afterWrite.length - kept.length),
+				};
+			}
+			// afterWrite.length < kept.length — events were lost during compaction window.
+			// Find missing events and re-append them.
+			// FIX: Use sequence numbers for comparison instead of JSON.stringify.
+			const afterSeqs = new Set(afterWrite.map((e) => e.metadata?.seq).filter((s): s is number => s !== undefined));
+			const missingEvents = kept.filter((e) => e.metadata?.seq === undefined || !afterSeqs.has(e.metadata.seq));
+			let recoveredCount = 0;
+			let recoveryFailed = false;
+			for (const event of missingEvents) {
+				try {
+					// Use atomicWriteFile for recovery append too — safer than plain appendFileSync
+					atomicWriteFile(eventsPath, JSON.stringify(event) + "\n");
+					recoveredCount++;
+				} catch (err) {
+					recoveryFailed = true;
+					// FIX: Log when recovery append fails to avoid silent event loss
+					logInternalError("event-log-rotation.recovery", err, `eventsPath=${eventsPath} lostEvent=${JSON.stringify(event).slice(0, 100)}`);
+				}
+			}
 			return {
 				originalSize,
 				compactedSize: fs.statSync(eventsPath).size,
 				eventsRemoved: originalCount - kept.length,
-				eventsKept: kept.length + Math.max(0, appendedDuringWindow),
+				eventsKept: kept.length + recoveredCount,
+				recoveryFailed,
+			};
+		} catch {
+			// Post-write verification failed — compaction likely succeeded.
+			const compactedSize = fs.statSync(eventsPath).size;
+			return {
+				originalSize,
+				compactedSize,
+				eventsRemoved: originalCount - kept.length,
+				eventsKept: kept.length,
 			};
 		}
-		// afterWrite.length < kept.length — events were lost during compaction window.
-		// Find missing events and re-append them.
-		const afterSet = new Set(afterWrite.map((e) => JSON.stringify(e)));
-		const missingEvents = kept.filter((e) => !afterSet.has(JSON.stringify(e)));
-		for (const event of missingEvents) {
-			try {
-				fs.appendFileSync(eventsPath, JSON.stringify(event) + "\n", "utf-8");
-			} catch {
-				// Append failed — log but don't throw.
-			}
-		}
-		return {
-			originalSize,
-			compactedSize: fs.statSync(eventsPath).size,
-			eventsRemoved: originalCount - kept.length,
-			eventsKept: kept.length,
-		};
-	} catch {
-		// Post-write verification failed — compaction likely succeeded.
-		const compactedSize = fs.statSync(eventsPath).size;
-		return {
-			originalSize,
-			compactedSize,
-			eventsRemoved: originalCount - kept.length,
-			eventsKept: kept.length,
-		};
-	}
+	});
 }
 
 /**
@@ -131,16 +153,24 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
  */
 export function rotateEventLog(eventsPath: string): boolean {
 	if (!fs.existsSync(eventsPath)) return false;
-	try {
-		const ts = new Date().toISOString().replace(/[:.]/g, "-");
-		const archivePath = `${eventsPath}.${ts}.archive.jsonl`;
-		fs.renameSync(eventsPath, archivePath);
-		fs.writeFileSync(eventsPath, "", "utf-8");
-		return true;
-	} catch (error) {
-		logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);
-		return false;
-	}
+	// FIX: Wrap rotation in lock to prevent race conditions with concurrent readers.
+	// Order of operations: (1) create new empty file, (2) rename old file to archive.
+	// This ensures eventsPath always exists — a reader never sees a missing file.
+	return withEventLogLockSync(eventsPath, () => {
+		try {
+			const ts = new Date().toISOString().replace(/[:.]/g, "-");
+			const archivePath = `${eventsPath}.${ts}.archive.jsonl`;
+			// Step 1: create new empty file at eventsPath FIRST
+			// This ensures eventsPath always exists for readers
+			atomicWriteFile(eventsPath, "");
+			// Step 2: rename old content to archive (after new file is in place)
+			fs.renameSync(eventsPath, archivePath);
+			return true;
+		} catch (error) {
+			logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);
+			return false;
+		}
+	});
 }
 
 export interface EventLogStats {