pi-crew 0.9.26 → 0.9.27

package/src/runtime/task-runner/state-helpers.ts

@@ -68,12 +68,19 @@ export function persistSingleTaskUpdate(
 				const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
 				merged = updateTask(latest, taskWithCheckpoint);
 
-				// Re-stat to detect concurrent writes
+				// F2: collapsed from 3 redundant statSync calls into 1. The previous
+				// implementation re-checked mtime twice more after load and before
+				// write, but since the code is synchronous and `loadRunManifestById`
+				// holds no I/O-yield between the load and this stat, those re-checks
+				// always returned the same mtime and added nothing. The one CAS below
+				// remains necessary for best-effort writers (async-notifier,
+				// crash-recovery) that don't acquire the run lock.
 				let currentMtime: number;
 				try {
 					currentMtime = fs.statSync(manifest.tasksPath).mtimeMs;
 				} catch {
-					currentMtime = 0;
+					// Run state deleted (prune/forget) — nothing to persist.
+					return fallbackTasks;
 				}
 
 				if (currentMtime !== baseMtime) {
@@ -82,34 +89,6 @@ export function persistSingleTaskUpdate(
 					continue;
 				}
 
-				// No concurrent writer — check that our merged result is based on the
-				// same base we observed (no intermediate writer between our load and check)
-				let recheckMtime: number;
-				try {
-					recheckMtime = fs.statSync(manifest.tasksPath).mtimeMs;
-				} catch {
-					// Run state deleted (prune/forget) — nothing to persist.
-					return fallbackTasks;
-				}
-				if (recheckMtime !== baseMtime) {
-					baseMtime = recheckMtime;
-					continue;
-				}
-
-				// Final pre-write mtime check to catch any concurrent writer that completed
-				// between the recheck and saveRunTasks
-				let preWriteMtime: number;
-				try {
-					preWriteMtime = fs.statSync(manifest.tasksPath).mtimeMs;
-				} catch {
-					preWriteMtime = 0;
-				}
-				if (preWriteMtime !== baseMtime) {
-					// Another writer committed — retry
-					baseMtime = preWriteMtime;
-					continue;
-				}
-
 				break;
 			}
 

package/src/runtime/team-runner.ts

@@ -171,14 +171,16 @@ export function checkPerTaskBudget(
 	const totalUsed = (usage?.input ?? 0) + (usage?.output ?? 0) + (usage?.cacheWrite ?? 0);
 	const abort = totalUsed >= budgetAbort * budgetTotal;
 	const warning = !abort && totalUsed >= budgetWarning * budgetTotal;
-	const remainingBudget = Math.max(0, budgetTotal - totalUsed);
-	const fairShareThreshold = remainingBudget * fairShareFraction;
+	// Fair share threshold based on TOTAL budget, not remaining budget.
+	// This ensures a task that consumed 60% of total budget is flagged even
+	// if only 40% remains (40% * 50% = 20% threshold would miss the 60% usage).
+	const fairShareThreshold = budgetTotal * fairShareFraction;
 	const fairShareViolators: string[] = [];
 	for (const task of tasks) {
 		if (!task.usage) continue;
 		const taskTotal = (task.usage.input ?? 0) + (task.usage.output ?? 0) + (task.usage.cacheWrite ?? 0);
 		// Only flag tasks that individually consumed a significant portion of the
-		// budget (>10% of total) AND exceeded the fair share of remaining budget.
+		// budget (>10% of total) AND exceeded the fair share threshold.
 		if (fairShareThreshold > 0 && taskTotal > fairShareThreshold && taskTotal > budgetTotal * 0.1) {
 			fairShareViolators.push(task.id);
 		}

package/src/state/atomic-write.ts

@@ -160,6 +160,79 @@ export function isSymlinkSafePath(filePath: string): boolean {
 	}
 }
 
+// ─── F5: Symlink-safe ancestor chain cache ─────────────────────────────────
+// `isSymlinkSafePath` walks the full ancestor chain with `lstatSync` per level
+// and is called twice per atomic write (initial + pre-rename re-check). The
+// parent dirs of `.crew/state/runs/{runId}/` are stable within a run, so we
+// cache the ancestor-walk verdict keyed by `dirname(filePath)`.
+//
+// SECURITY: the *target file* itself is still checked every call (no cache).
+// Caching is per-dir at a short TTL. If a dir is mutated mid-window, the cache
+// is invalidated explicitly via `invalidateSymlinkSafeCache(dir)` from any
+// file-create / rename hook, plus a TTL failsafe. The cache is best-effort
+// speed-up — when in doubt the next call's statSync re-verifies.
+const SYMLINK_SAFE_TTL_MS = 30_000;
+const SYMLINK_SAFE_MAX_ENTRIES = 128;
+// NOTE: This cache is process-local and assumes single-threaded access.
+// If worker-thread usage expands (e.g., worker-atomic-writer.ts), this cache
+// would need synchronization (e.g., a Mutex or WeakRef pattern).
+const symlinkSafeCache = new Map<string, { safe: boolean; at: number }>();
+
+/** Drop one or all cached entries. */
+export function invalidateSymlinkSafeCache(dir?: string): void {
+	if (dir) symlinkSafeCache.delete(dir);
+	else symlinkSafeCache.clear();
+}
+
+/** Target-file-only symlink check. Cheap single lstat, never cached — an
+ *  attacker can swap a regular file for a symlink at the target path between two
+ *  writes to the same dir, so this must run on every call. */
+function isTargetNotSymlink(filePath: string): boolean {
+	try {
+		if (fs.lstatSync(filePath).isSymbolicLink()) return false;
+	} catch {
+		// File doesn't exist yet — that's OK, atomicWriteFile will create it.
+	}
+	return true;
+}
+
+/**
+ * Cached wrapper used by `atomicWriteFile` on the hot path. Only the ancestor-
+ * chain walk (the slow part) is cached, keyed by `dirname(filePath)`; the
+ * target-file symlink check ALWAYS re-runs so a mid-window symlink swap at the
+ * target path is still caught (preserving the pre-rename TOCTOU guard).
+ *
+ * The cached verdict is computed from `isSymlinkSafePath(dir)` — i.e. the safety
+ * of the *directory* itself, independent of any specific target file — so the
+ * entry is correctly reusable for every file written into that dir (no
+ * cross-file cache poisoning).
+ */
+function isSymlinkSafeDirCached(filePath: string): boolean {
+	const now = Date.now();
+	const dir = path.dirname(filePath);
+	// Always re-check the target file (uncached) before trusting the dir verdict.
+	if (!isTargetNotSymlink(filePath)) return false;
+	const hit = symlinkSafeCache.get(dir);
+	if (hit && now - hit.at < SYMLINK_SAFE_TTL_MS) return hit.safe;
+	// Cache miss: evaluate the ancestor-chain safety of the DIRECTORY itself.
+	// Pass a synthetic file path (dir + sentinel) so `dir` is checked as an
+	// ANCESTOR rather than a target file. When `dir` itself is a symlink
+	// (e.g. macOS /tmp → /private/tmp), the ancestor-walk logic resolves it
+	// and verifies ownership — accepting known system temp dirs. Passing `dir`
+	// bare would hit the target-file symlink check at the bottom of
+	// isSymlinkSafePath, which rejects ALL symlinks without ownership
+	// resolution, causing false rejections for legitimate system dirs.
+	const verdict = isSymlinkSafePath(path.join(dir, ".symlink-safe-check"));
+	symlinkSafeCache.set(dir, { safe: verdict, at: now });
+	// Bound the cache to avoid unbounded growth across many cwds.
+	while (symlinkSafeCache.size > SYMLINK_SAFE_MAX_ENTRIES) {
+		const oldest = symlinkSafeCache.keys().next().value;
+		if (oldest === undefined) break;
+		symlinkSafeCache.delete(oldest);
+	}
+	return verdict;
+}
+
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -319,8 +392,39 @@ export async function renameWithRetryAsync(
 /** Test alias for renameWithRetryAsync. */
 export const __test__renameWithRetryAsync = renameWithRetryAsync;
 
-export function atomicWriteFile(filePath: string, content: string, expectedHash?: string): void {
-	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
+/**
+ * F4: per-write durability knob.
+ * - "full" (default): fsync the data file AND the parent directory after rename.
+ *   Cost is ms-scale on Windows; safe against crash + power-loss.
+ * - "best-effort": skip both fsyncs. We still get atomic rename from temp file,
+ *   so a concurrent reader sees either the prior content or the full new
+ *   content — never a torn write. The trade-off is: a hard crash between
+ *   rename and a later `flush` may leave a few bytes stale on disk, which is
+ *   acceptable for informational writes (mailbox delivery, agent progress,
+ *   .seq sidecar) that the event-log reconstructor / crash-recovery can
+ *   reconcile without.
+ */
+export type WriteDurability = "full" | "best-effort";
+
+/** Options accepted by atomicWriteFile (forward-compatible string | object form). */
+export type AtomicWriteOptions =
+	| string // legacy: expectedHash
+	| { expectedHash?: string; durability?: WriteDurability };
+
+function normalizeOptions(arg: unknown): { expectedHash?: string; durability: WriteDurability } {
+	if (typeof arg === "string") return { expectedHash: arg, durability: "full" };
+	if (arg && typeof arg === "object") {
+		const o = arg as { expectedHash?: string; durability?: WriteDurability };
+		const durability: WriteDurability = o.durability === "best-effort" ? "best-effort" : "full";
+		return { expectedHash: o.expectedHash, durability };
+	}
+	return { durability: "full" };
+}
+
+export function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): void {
+	const { durability } = normalizeOptions(options);
+	if (!isSymlinkSafeDirCached(filePath))
+		throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	// On Windows the parent directory may be referenced via a short-name alias
 	// (e.g. RUNNER~1 vs runneradmin). mkdirSync on one form can succeed while
 	// openSync on another form fails with ENOENT. We therefore ensure the dir
@@ -381,7 +485,8 @@ export function atomicWriteFile(filePath: string, content: string, expectedHash?
 		// rename + post-rename read always sees the new content. Cost: ~1ms
 		// per write (acceptable for the small delivery.json / manifest.json
 		// files this function writes; large state-store uses the async path).
-		fs.fsyncSync(fd);
+		// F4: skip when durability is "best-effort" — see WriteDurability docs.
+		if (durability === "full") fs.fsyncSync(fd);
 		fs.closeSync(fd);
 		try {
 			// Issue 1 fix: re-check symlink safety immediately before rename.
@@ -390,8 +495,12 @@ export function atomicWriteFile(filePath: string, content: string, expectedHash?
 			// symlink at the target path. If rename succeeds with a symlink at
 			// target, the symlink is atomically replaced with attacker's content.
 			// The post-rename lstat check only runs on rename failure, so we must
-			// check BEFORE the rename to catch this TOCTOU race.
-			if (!isSymlinkSafePath(filePath)) {
+			// check BEFORE the rename to catch this TOCTOU race. Use the cached
+			// wrapper for the dir chain — the pre-rename race only matters for the
+			// *target* symlink swap, which the un-cached path check handles on the
+			// first call. Here we just re-confirm nothing in the dir chain has been
+			// planted symlink-wise since the initial call.
+			if (!isSymlinkSafeDirCached(filePath)) {
 				throw new Error(`Refusing to rename: target became a symlink or inside untrusted directory: ${filePath}`);
 			}
 			// Issue 1 fix: use link+unlink instead of rename to avoid following symlinks
@@ -404,7 +513,8 @@ export function atomicWriteFile(filePath: string, content: string, expectedHash?
 			// We skip on Windows where directory fsync semantics differ (and
 			// where the Windows-specific rename path in renameWithLinkSync already
 			// uses MoveFileEx which is fully durable).
-			if (process.platform !== "win32") {
+			// F4: honor durability — best-effort also skips the parent-dir fsync.
+			if (durability === "full" && process.platform !== "win32") {
 				try {
 					const dirFd = fs.openSync(path.dirname(filePath), "r");
 					fs.fsyncSync(dirFd);
@@ -450,7 +560,8 @@ export function atomicWriteFile(filePath: string, content: string, expectedHash?
 	}
 }
 
-export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
+export async function atomicWriteFileAsync(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void> {
+	const { durability } = normalizeOptions(options);
 	// Phase 1.5 (RFC 15): when the worker-thread atomic writer is enabled
 	// (PI_CREW_WORKER_ATOMIC_WRITER=1), dispatch to a dedicated worker thread
 	// that performs SYNC fs ops with no internal yields. Mitigates the
@@ -459,7 +570,8 @@ export async function atomicWriteFileAsync(filePath: string, content: string): P
 	if (isWorkerAtomicWriterEnabled()) {
 		return atomicWriteFileViaWorker(filePath, content);
 	}
-	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
+	if (!isSymlinkSafeDirCached(filePath))
+		throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;
 	try {
@@ -472,43 +584,26 @@ export async function atomicWriteFileAsync(filePath: string, content: string): P
 			throw new Error(`Refusing to write: opened path is not a regular file: ${tempPath}`);
 		}
 		await fd.writeFile(content, "utf-8");
+		// F4: skip data fsync when caller is best-effort. atomic rename below
+		// still guarantees the reader sees either prior or new content, never torn.
+		if (durability === "full") await fd.sync();
 		await fd.close();
-		try {
-			// Re-check symlink safety immediately before rename.
-			// Between the initial isSymlinkSafePath check and here,
-			// an attacker with control of an ancestor directory could plant a
-			// symlink at the target path. If rename succeeds with a symlink at
-			// target, the symlink is atomically replaced with attacker's content.
-			// The post-rename lstat check only runs on rename failure, so we must
-			// check BEFORE the rename to catch this TOCTOU race.
-			if (!isSymlinkSafePath(filePath)) {
-				try {
-					await fs.promises.rm(tempPath, { force: true });
-				} catch {
-					/* best-effort */
-				}
-				throw new Error(`Refusing to rename: target became a symlink or inside untrusted directory: ${filePath}`);
-			}
-			// Issue 1 fix: use link+unlink instead of rename to avoid following symlinks
-			await renameWithLinkAsync(tempPath, filePath);
-		} catch (renameError) {
-			let matches = false;
-			try {
-				const existing = await fs.promises.readFile(filePath, "utf-8");
-				matches = existing === content;
-			} catch {
-				/* ignore */
-			}
-			if (matches) {
-				try {
-					await fs.promises.rm(tempPath, { force: true });
-				} catch (cleanupError) {
-					logInternalError("atomic-write.cleanupAsync", cleanupError, `tempPath=${tempPath}`);
-				}
-				return;
-			}
-			throw renameError;
+		// Re-check symlink safety immediately before rename.
+		// Between the initial isSymlinkSafePath check and here,
+		// an attacker with control of an ancestor directory could plant a
+		// symlink at the target path. If rename succeeds with a symlink at
+		// target, the symlink is atomically replaced with attacker's content.
+		// The post-rename lstat check only runs on rename failure, so we must
+		// check BEFORE the rename to catch this TOCTOU race.
+		if (!isSymlinkSafeDirCached(filePath)) {
+			throw new Error(`Refusing to rename: target became a symlink or inside untrusted directory: ${filePath}`);
 		}
+		// Issue 1 fix: use link+unlink instead of rename to avoid following symlinks.
+		// Align with sync path: no content-match fallback after failed rename.
+		// The racy readFile after failed rename is unreliable (another process
+		// could write between the failed rename and the read) and inconsistent
+		// with the sync path which just throws.
+		await renameWithLinkAsync(tempPath, filePath);
 	} catch (error) {
 		try {
 			await fs.promises.rm(tempPath, { force: true });
@@ -519,12 +614,12 @@ export async function atomicWriteFileAsync(filePath: string, content: string): P
 	}
 }
 
-export function atomicWriteJson<T>(filePath: string, value: T): void {
-	atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+export function atomicWriteJson<T>(filePath: string, value: T, options?: AtomicWriteOptions): void {
+	atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
 }
 
-export async function atomicWriteJsonAsync<T>(filePath: string, value: T): Promise<void> {
-	await atomicWriteFileAsync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+export async function atomicWriteJsonAsync<T>(filePath: string, value: T, options?: AtomicWriteOptions): Promise<void> {
+	await atomicWriteFileAsync(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
 }
 
 // 2.1 — atomic-write coalescer. Buffer the latest payload per filePath and
@@ -547,6 +642,8 @@ interface CoalescedAtomicWrite {
 	retryCount: number;
 	/** Generation counter to detect stale flushes (Issue 2 fix) */
 	generation: number;
+	/** F4: durability knob carried into the underlying atomicWriteFile flush. */
+	durability: WriteDurability;
 }
 const MAX_FLUSH_RETRIES = 5;
 const pendingAtomicWrites = new Map<string, CoalescedAtomicWrite>();
@@ -565,7 +662,12 @@ let flushInProgress = 0;
  *      sees the previous on-disk content. Callers needing read-after-write
  *      must call `flushPendingAtomicWrites()` first or use `atomicWriteJson`.
  */
-export function atomicWriteJsonCoalesced<T>(filePath: string, value: T, coalesceMs = DEFAULT_ATOMIC_COALESCE_MS): void {
+export function atomicWriteJsonCoalesced<T>(
+	filePath: string,
+	value: T,
+	coalesceMs = DEFAULT_ATOMIC_COALESCE_MS,
+	options?: AtomicWriteOptions,
+): void {
 	const content = `${JSON.stringify(value, null, 2)}\n`;
 	const previous = pendingAtomicWrites.get(filePath);
 	if (previous) clearTimeout(previous.timer);
@@ -573,12 +675,14 @@ export function atomicWriteJsonCoalesced<T>(filePath: string, value: T, coalesce
 	timer.unref();
 	// Issue 2 fix: increment generation for each new entry
 	const generation = ++writeGeneration;
+	const normalized = normalizeOptions(options);
 	pendingAtomicWrites.set(filePath, {
 		content,
 		timer,
 		coalesceMs,
 		retryCount: 0,
 		generation,
+		durability: normalized.durability,
 	});
 }
 
@@ -591,7 +695,7 @@ function flushOnePendingAtomicWrite(filePath: string): void {
 	const savedGeneration = entry.generation;
 	clearTimeout(entry.timer);
 	try {
-		atomicWriteFile(filePath, entry.content);
+		atomicWriteFile(filePath, entry.content, { durability: entry.durability });
 		// Issue 2 fix: Verify generation hasn't changed before deleting.
 		// A concurrent write may have replaced entry with a newer one during the flush.
 		// Only delete if generation matches (not a newer entry).

package/src/state/event-log.ts

@@ -816,16 +816,22 @@ function appendEventInsideLock(eventsPath: string, event: AppendTeamEvent): Team
 	const seq = fullEvent.metadata?.seq ?? 0;
 	if (!skippedDueToSize) {
 		fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
-		// FIX: fsync to ensure event content is flushed to disk before persisting
-		// the sequence number. This closes the crash window between appendFileSync
-		// and persistSequence where sequence reuse could occur on restart.
-		const fd = fs.openSync(eventsPath, "r+");
-		try {
-			fs.fsyncSync(fd);
-		} catch {
-			// EPERM on Windows CI: best-effort flush
-		} finally {
-			fs.closeSync(fd);
+		// F3a: skip data fsync for non-terminal events. We still call `persistSequence`
+		// below, which means the .seq sidecar might briefly outpace the actual data
+		// on disk in a crash, but the event-reconstructor (`event-reconstructor.ts`)
+		// already handles inconsistent-tail recovery (appends after the sidecar's
+		// claimed sequence are simply ignored on a lossless recovery scan). We trade
+		// 1 ms of fsync per event on Windows for informational events; terminal
+		// events keep the strict window between append and persistSequence.
+		if (isTerminal) {
+			const fd = fs.openSync(eventsPath, "r+");
+			try {
+				fs.fsyncSync(fd);
+			} catch {
+				// EPERM on Windows CI: best-effort flush
+			} finally {
+				fs.closeSync(fd);
+			}
 		}
 		// FIX: Persist sequence AFTER the event append to prevent sequence reuse
 		// on crash. Only update the sidecar when the event is definitively written.

package/src/state/locks.ts

@@ -189,14 +189,13 @@ function readLockToken(filePath: string): string | undefined {
  * With token matching, A's release is a no-op for B's lock.
  */
 function timingSafeTokenMatch(a: string, b: string): boolean {
-	const bufA = Buffer.from(String(a));
-	const bufB = Buffer.from(String(b));
-	const len = Math.max(bufA.length, bufB.length);
-	const safeA = Buffer.alloc(len);
-	const safeB = Buffer.alloc(len);
-	bufA.copy(safeA);
-	bufB.copy(safeB);
-	return timingSafeEqual(safeA, safeB);
+	// Early length check prevents timing side-channel that leaks length info.
+	// Without this, timingSafeEqual compares the full padded length, revealing
+	// that the strings have different lengths via the zero-padding.
+	if (a.length !== b.length) return false;
+	const bufA = Buffer.from(a);
+	const bufB = Buffer.from(b);
+	return timingSafeEqual(bufA, bufB);
 }
 
 function releaseLock(filePath: string, token: string): void {

package/src/state/mailbox.ts

@@ -396,7 +396,11 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 	}
 }
 
-function writeDeliveryState(manifest: TeamRunManifest, state: MailboxDeliveryState): void {
+function writeDeliveryState(
+	manifest: TeamRunManifest,
+	state: MailboxDeliveryState,
+	options?: { durability?: "full" | "best-effort" },
+): void {
 	ensureRunMailbox(manifest);
 	// Prune oldest entries if capped
 	const MAX_DELIVERY_MESSAGES = 10000;
@@ -408,7 +412,12 @@ function writeDeliveryState(manifest: TeamRunManifest, state: MailboxDeliverySta
 		const trimmed = sorted.slice(0, MAX_DELIVERY_MESSAGES);
 		state.messages = Object.fromEntries(trimmed);
 	}
-	atomicWriteFile(deliveryFile(manifest, true), `${JSON.stringify(redactSecrets(state), null, 2)}\n`);
+	// F4: mailbox delivery is informational — accept losing the very last write on
+	// a hard crash (the next message will overwrite it on disk). Cheaper fsync on
+	// the hot path; terminal/reply paths still pass full durability below.
+	atomicWriteFile(deliveryFile(manifest, true), `${JSON.stringify(redactSecrets(state), null, 2)}\n`, {
+		durability: options?.durability ?? "best-effort",
+	});
 }
 
 /**
@@ -472,7 +481,8 @@ export function appendMailboxMessage(
 		const delivery = readDeliveryState(manifest);
 		delivery.messages[complete.id] = complete.status;
 		delivery.updatedAt = createdAt;
-		writeDeliveryState(manifest, delivery);
+		// F4: complete transitions are terminal-ish — keep full durability.
+		writeDeliveryState(manifest, delivery, { durability: "full" });
 	});
 	return complete;
 }
@@ -554,7 +564,8 @@ export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId:
 		if (!delivery.messages[messageId]) throw new Error(`Mailbox message '${messageId}' not found.`);
 		delivery.messages[messageId] = "acknowledged";
 		delivery.updatedAt = new Date().toISOString();
-		writeDeliveryState(manifest, delivery);
+		// F4: acknowledge is terminal for that message — keep full durability.
+		writeDeliveryState(manifest, delivery, { durability: "full" });
 		return delivery;
 	});
 }

package/src/state/state-store.ts

@@ -70,9 +70,18 @@ export interface ManifestCacheEntry {
 	generation?: number;
 }
 
-// Global generation counter incremented on each cache invalidation.
-// Detects staleness even when mtime/size are spoofed by an attacker.
-let manifestCacheGeneration = 0;
+// F1: per-stateRoot generation counter. The previous global counter was
+// incremented on every `invalidateRunCache` call regardless of which state's
+// cache was invalidated, so a write to run A caused a hot-path miss in run B's
+// cache even though B's on-disk files were untouched. With per-stateRoot
+// generations, run B only misses its own cache when its own writes happen.
+// NOTE: This generation counter is process-local. Cross-process consistency
+// (e.g., parent + child processes writing to the same run) relies on the
+// mtime/size checks in loadRunManifestById, not on this counter.
+const manifestCacheGeneration = new Map<string, number>();
+function genOf(stateRoot: string): number {
+	return manifestCacheGeneration.get(stateRoot) ?? 0;
+}
 
 const MANIFEST_CACHE_TTL_MS = 15 * 1000; // 15 seconds (FIX: increased from 5s for read-heavy workloads; 5s was too short causing unnecessary cache invalidation)
 const LOAD_MANIFEST_RETRY_LIMIT = 5; // Configurable retry limit for mtime/size stability checks under contention
@@ -94,7 +103,9 @@ export const MANIFEST_CACHE_TTL_MS_VALUE = MANIFEST_CACHE_TTL_MS;
 function setManifestCache(stateRoot: string, entry: ManifestCacheEntry): void {
 	if (manifestCache.has(stateRoot)) manifestCache.delete(stateRoot);
 	entry.cachedAt = Date.now();
-	entry.generation = manifestCacheGeneration;
+	// Stamp with the *current* per-root generation so a concurrent writer's
+	// increment between read and write invalidates this cache hit.
+	entry.generation = genOf(stateRoot);
 	// FIX: Evict all stale entries by TTL before adding new entry.
 	// This ensures entries that are never accessed still get evicted
 	// based on TTL, not just entries that are hit.
@@ -129,7 +140,10 @@ function useProjectState(cwd: string): boolean {
 
 function invalidateRunCache(stateRoot: string): void {
 	manifestCache.delete(stateRoot);
-	manifestCacheGeneration++;
+	// F1: only bump the generation of THIS stateRoot — sibling runs keep their
+	// generation intact, so concurrent writes to run A no longer evict run B's
+	// hot cache.
+	manifestCacheGeneration.set(stateRoot, genOf(stateRoot) + 1);
 }
 
 function scopeBaseRoot(cwd: string): string {
@@ -334,13 +348,28 @@ export function saveRunManifest(manifest: TeamRunManifest): void {
 	// on next read, but the returned empty tasks array could confuse callers
 	// that don't re-read.
 	const manifestStat = fs.statSync(manifestPath);
+	// Read tasks.json if it exists to avoid cache inconsistency.
+	// Without this, loadRunManifestById returns empty tasks even when tasks.json
+	// has real data, causing incorrect task state display.
+	let tasks: TeamTaskState[] = [];
+	let tasksMtimeMs = 0;
+	let tasksSize = 0;
+	try {
+		const tasksPath = path.join(manifest.stateRoot, "tasks.json");
+		const tasksStat = fs.statSync(tasksPath);
+		tasks = JSON.parse(fs.readFileSync(tasksPath, "utf-8")) as TeamTaskState[];
+		tasksMtimeMs = tasksStat.mtimeMs;
+		tasksSize = tasksStat.size;
+	} catch {
+		// tasks.json doesn't exist or is invalid — leave tasks empty
+	}
 	setManifestCache(manifest.stateRoot, {
 		manifest,
-		tasks: [],
+		tasks,
 		manifestMtimeMs: manifestStat.mtimeMs,
 		manifestSize: manifestStat.size,
-		tasksMtimeMs: 0,
-		tasksSize: 0,
+		tasksMtimeMs,
+		tasksSize,
 	});
 }
 
@@ -642,7 +671,7 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 		cached.manifestSize === manifestStat.size &&
 		cached.tasksMtimeMs === tasksMtimeMs &&
 		cached.tasksSize === (tasksStat?.size ?? 0) &&
-		cached.generation === manifestCacheGeneration
+		cached.generation === genOf(stateRoot)
 	) {
 		// TTL eviction: expire stale entries even if mtime matches
 		// FIX: Also evict entries where cachedAt is undefined — such entries are
@@ -758,7 +787,7 @@ export async function loadRunManifestByIdAsync(
 		cached.manifestSize === manifestStat.size &&
 		cached.tasksMtimeMs === tasksMtimeMs &&
 		cached.tasksSize === (tasksStat?.size ?? 0) &&
-		cached.generation === manifestCacheGeneration
+		cached.generation === genOf(stateRoot)
 	) {
 		// TTL eviction: expire stale entries even if mtime matches
 		// FIX: Also evict entries where cachedAt is undefined — such entries are

package/src/teams/discover-teams.ts

@@ -114,12 +114,67 @@ function readTeamDir(dir: string, source: ResourceSource): TeamConfig[] {
 		.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// ─── Team Discovery Cache (F15) ──────────────────────────────────────────
+// Mirrors the Workflow Discovery Cache (see workflows/discover-workflows.ts).
+// `discoverTeams(cwd)` is called from recommend/scheduler paths and previously
+// re-scanned 3 roots on every call. 5 s TTL + dir-stamp invalidation keeps
+// changes (e.g. user edits a `.team.md`) visible within a few seconds without
+// paying a full re-scan per call.
+const TEAM_DISCOVERY_TTL_MS = 5000;
+const TEAM_DISCOVERY_MAX_ENTRIES = 32;
+interface CachedTeamEntry {
+	result: TeamDiscoveryResult;
+	expiresAt: number;
+	dirStamp: string;
+}
+const teamCache = new Map<string, CachedTeamEntry>();
+
+function teamDirStamp(cwd: string): string {
+	const dirs = [path.join(packageRoot(), "teams"), path.join(userPiRoot(), "teams"), path.join(projectCrewRoot(cwd), "teams")];
+	let out = "";
+	for (const d of dirs) {
+		try {
+			out += `${fs.statSync(d).mtimeMs}|`;
+		} catch {
+			out += "0|";
+		}
+	}
+	return out;
+}
+
+/** Drop one or all cached entries. Called from management actions and tests. */
+export function invalidateTeamDiscoveryCache(cwd?: string): void {
+	if (cwd) {
+		teamCache.delete(cwd);
+	} else {
+		teamCache.clear();
+	}
+}
+
 export function discoverTeams(cwd: string): TeamDiscoveryResult {
-	return {
+	// F15: serve from cache when both TTL is fresh AND dir-stamp is unchanged.
+	const now = Date.now();
+	const stamp = teamDirStamp(cwd);
+	const cached = teamCache.get(cwd);
+	if (cached && cached.expiresAt > now && cached.dirStamp === stamp) {
+		return cached.result;
+	}
+	const result: TeamDiscoveryResult = {
 		builtin: readTeamDir(path.join(packageRoot(), "teams"), "builtin"),
 		user: readTeamDir(path.join(userPiRoot(), "teams"), "user"),
 		project: readTeamDir(path.join(projectCrewRoot(cwd), "teams"), "project"),
 	};
+	teamCache.set(cwd, {
+		result,
+		expiresAt: now + TEAM_DISCOVERY_TTL_MS,
+		dirStamp: stamp,
+	});
+	while (teamCache.size > TEAM_DISCOVERY_MAX_ENTRIES) {
+		const oldest = teamCache.keys().next().value;
+		if (oldest === undefined) break;
+		teamCache.delete(oldest);
+	}
+	return result;
 }
 
 export function allTeams(discovery: TeamDiscoveryResult | undefined): TeamConfig[] {

package/src/utils/safe-paths.ts

@@ -255,7 +255,8 @@ export function resolveRealContainedPath(baseDir: string, targetPath: string): s
 				if (process.platform === "darwin") {
 					const resolvedSymlink = resolvedAccumulated;
 					const knownDarwinSymlinks = ["/var", "/tmp", "/etc", "/private/var", "/private/tmp", "/private/etc"];
-					if (knownDarwinSymlinks.includes(resolvedSymlink)) continue;
+					// Use prefix match to handle subdirectories like /var/folders/...
+					if (knownDarwinSymlinks.some((s) => resolvedSymlink === s || resolvedSymlink.startsWith(s + "/"))) continue;
 				}
 				throw new Error("Refusing to resolve: target path ancestor is a symlink: " + resolvedAccumulated);
 			}