pi-crew 0.10.2 → 0.10.3

package/src/state/atomic-write.ts

@@ -267,7 +267,7 @@ function isTargetNotSymlink(filePath: string): boolean {
  * entry is correctly reusable for every file written into that dir (no
  * cross-file cache poisoning).
  */
-function isSymlinkSafeDirCached(filePath: string): boolean {
+export 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.
@@ -549,6 +549,91 @@ function normalizeOptions(arg: unknown): { expectedHash?: string; durability: Wr
 	return { durability: "full", mode: undefined, compact: undefined };
 }
 
+// PERF (2026-08-24): every atomic write ran mkdirSync(recursive) on a parent
+// that exists for the lifetime of a run. Memoize known-existing dirs; on the
+// ENOENT retry at temp-open (memoized dir deleted underneath us) BOTH the dir
+// memo AND the symlink-safety caches for that dir are dropped (forgetDir +
+// invalidateSymlinkSafeCache) so a deleted-then-recreated tree re-runs the
+// full symlink walk on the next write — without the invalidation the stale
+// dir verdict would be trusted for up to the 10s symlinkSafeCache TTL.
+const knownDirs = new Set<string>();
+const KNOWN_DIRS_MAX = 512;
+export function ensureDirSync(dirPath: string): void {
+	if (knownDirs.has(dirPath)) return;
+	fs.mkdirSync(dirPath, { recursive: true });
+	if (knownDirs.size >= KNOWN_DIRS_MAX) {
+		const oldest = knownDirs.keys().next().value;
+		if (oldest !== undefined) knownDirs.delete(oldest);
+	}
+	knownDirs.add(dirPath);
+}
+function forgetDir(dirPath: string): void {
+	knownDirs.delete(dirPath);
+}
+
+// T8 (perf round 2, 2026-08-25): grouped parent-dir fsync for coalesced drains.
+//
+// A full-durability atomic write fsyncs (1) the data file and (2) the parent
+// directory after the rename. When a coalesced DRAIN
+// (`flushPendingAtomicWrites()` with no argument) serially flushes N pending
+// files, the per-file parent-dir fsync is redundant: rename(2) is atomic and
+// visible to readers the instant it happens (independent of the dir fsync),
+// and ONE fsync of the parent dir after ALL renames makes every rename in
+// that dir crash-durable in a single journal commit. Measured on this repo's
+// state burst (4 files, one dir): 59.4ms serial per-file dir-fsync vs 22.9ms
+// with one shared trailing dir-fsync (−61%), full durability preserved. Files
+// in distinct dirs still group per-dir.
+//
+// Ordering (R16-B1): every rename completes BEFORE the trailing dir-fsync —
+// guaranteed because the drain loop is serial and synchronous and the
+// trailing fsync only runs after the loop.
+//
+// Scoping: `dirFsyncDeferralDepth` is raised ONLY around the global-drain
+// loop, so the deferral never leaks to other callers — direct `atomicWriteJson`
+// / `atomicWriteFile` calls, the terminal `skipCoalesce` path, scoped
+// `flushPendingAtomicWrites(filePath)` flushes, and coalesce-timer
+// `flushOnePendingAtomicWrite` callbacks all run at depth 0 and keep their
+// immediate dir-fsync. `pendingDirFsyncs` is drained from the drain's
+// `finally` so a mid-drain throw still fsyncs the dirs of files that were
+// already renamed. Nested drains are impossible via the existing
+// `flushInProgress` guard. There is no async drain counterpart today; the
+// async path therefore NEVER defers (see its comment at the dir-fsync site).
+const pendingDirFsyncs = new Set<string>();
+let dirFsyncDeferralDepth = 0;
+
+/** Immediate (ungrouped) parent-dir fsync — the pre-T8 inline behavior. */
+function fsyncParentDirImmediate(filePath: string): void {
+	try {
+		const dirFd = fs.openSync(path.dirname(filePath), "r");
+		fs.fsyncSync(dirFd);
+		fs.closeSync(dirFd);
+	} catch {
+		/* best-effort — not all filesystems support directory fsync */
+	}
+}
+
+/** Flush the dirs accumulated by a grouped drain: ONE open+fsync+close per
+ *  DISTINCT dir. Called from the drain's `finally` so it fires even when the
+ *  serial loop threw mid-drain — files renamed before the throw must still
+ *  become crash-durable. Best-effort per dir, mirroring the inline path.
+ *  The set is snapshotted+cleared up front so a throwing dir cannot skip the
+ *  remaining dirs or leak entries into the next drain. */
+function fsyncPendingParentDirs(): void {
+	if (pendingDirFsyncs.size === 0) return;
+	const dirs = [...pendingDirFsyncs];
+	pendingDirFsyncs.clear();
+	if (process.platform === "win32") return;
+	for (const dir of dirs) {
+		try {
+			const dirFd = fs.openSync(dir, "r");
+			fs.fsyncSync(dirFd);
+			fs.closeSync(dirFd);
+		} catch {
+			/* best-effort — not all filesystems support directory fsync */
+		}
+	}
+}
+
 export function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): void {
 	cancelPendingCoalescedWrite(filePath);
 	const { durability, mode } = normalizeOptions(options);
@@ -581,7 +666,9 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 	};
 	const dirPath = path.dirname(filePath);
 	try {
-		fs.mkdirSync(dirPath, { recursive: true });
+		// PERF (2026-08-24): memoized — on a memo hit this cannot throw, so the
+		// EPERM fallback below only ever runs when mkdir actually executed.
+		ensureDirSync(dirPath);
 	} catch (error) {
 		if (process.platform === "win32" && (error as NodeJS.ErrnoException).code === "EPERM") {
 			// mkdir hit a short/long-name alias wall — retry with the canonical
@@ -604,7 +691,24 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 	// removes a leftover instead of being skipped by the stale `fd` guard.
 	let tempNeedsCleanup = false;
 	try {
-		fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, mode ?? 0o600);
+		// PERF (2026-08-24): the memoized parent may have been deleted after
+		// memoization — openSync then fails ENOENT. Forget the memo, re-create
+		// the dir, and retry the open exactly once; a second failure re-throws
+		// (through the outer finally, which has nothing to clean up yet since
+		// the temp never existed).
+		try {
+			fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, mode ?? 0o600);
+		} catch (openError) {
+			if ((openError as NodeJS.ErrnoException).code !== "ENOENT") throw openError;
+			forgetDir(dirPath);
+			// Parity hardening: drop the symlink-safety verdict for this dir too —
+			// the memoized dir may have been deleted and RECREATED (possibly as a
+			// symlink or with symlinked ancestors), and the cached verdict would
+			// otherwise stay trusted for up to the 10s TTL.
+			invalidateSymlinkSafeCache(dirPath);
+			ensureDirSync(dirPath);
+			fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, mode ?? 0o600);
+		}
 		tempNeedsCleanup = true; // ST-7: temp file now exists on disk
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = fs.fstatSync(fd);
@@ -657,13 +761,16 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 			// where the Windows-specific rename path in renameWithLinkSync already
 			// uses MoveFileEx which is fully durable).
 			// F4: honor durability — best-effort also skips the parent-dir fsync.
+			// T8: inside a coalesced DRAIN (dirFsyncDeferralDepth > 0 — raised only
+			// by flushPendingAtomicWrites() with no argument) DEFER the dir fsync:
+			// accumulate the dirname in pendingDirFsyncs and let the drain issue
+			// ONE fsync per distinct dir after all renames. Every other caller
+			// runs at depth 0 and keeps this immediate dir-fsync unchanged.
 			if (durability === "full" && process.platform !== "win32") {
-				try {
-					const dirFd = fs.openSync(path.dirname(filePath), "r");
-					fs.fsyncSync(dirFd);
-					fs.closeSync(dirFd);
-				} catch {
-					/* best-effort — not all filesystems support directory fsync */
+				if (dirFsyncDeferralDepth > 0) {
+					pendingDirFsyncs.add(path.dirname(filePath));
+				} else {
+					fsyncParentDirImmediate(filePath);
 				}
 			}
 		} catch (renameError) {
@@ -731,16 +838,36 @@ export async function atomicWriteFileAsync(filePath: string, content: string, op
 	}
 	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 });
+	// PERF (2026-08-24): shared dir memo — a sync mkdir on an existing dir is one
+	// cheap syscall; replacing `await fs.promises.mkdir` is fine because the
+	// memoized hit does not throw and does not yield the event loop.
+	ensureDirSync(path.dirname(filePath));
 	const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;
 	let fd: fs.promises.FileHandle | undefined;
 	try {
 		const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-		fd = await fs.promises.open(
-			tempPath,
-			fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW,
-			mode ?? 0o600,
-		);
+		// PERF (2026-08-24): same ENOENT retry as the sync path — the memoized
+		// dir may have been deleted between memoization and this open.
+		try {
+			fd = await fs.promises.open(
+				tempPath,
+				fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW,
+				mode ?? 0o600,
+			);
+		} catch (openError) {
+			if ((openError as NodeJS.ErrnoException).code !== "ENOENT") throw openError;
+			forgetDir(path.dirname(filePath));
+			// Parity hardening (async twin of the sync path): drop the cached
+			// symlink-safety verdict alongside the dir memo so a recreated dir
+			// re-runs the walk on the next write.
+			invalidateSymlinkSafeCache(path.dirname(filePath));
+			ensureDirSync(path.dirname(filePath));
+			fd = await fs.promises.open(
+				tempPath,
+				fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW,
+				mode ?? 0o600,
+			);
+		}
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = await fd.stat();
 		if (!openedStat.isFile()) {
@@ -773,6 +900,14 @@ export async function atomicWriteFileAsync(filePath: string, content: string, op
 		// some Linux filesystems, so a crash between rename and journal flush
 		// could leave a stale directory entry. The sync path already does this;
 		// this brings the async path to durability parity.
+		// T8: the grouped dir-fsync (pendingDirFsyncs) deliberately does NOT
+		// apply here. There is no ASYNC coalesced drain — the drain loop in
+		// flushPendingAtomicWrites() is fully synchronous and calls only the
+		// sync atomicWriteFile, so an async write can never observe
+		// dirFsyncDeferralDepth > 0. Deferring here would add dirs to a set
+		// whose trailing flush has already run (worse than not fsyncing at
+		// all). If an async drain is ever added, it must collect distinct dirs
+		// and Promise.all their fsyncs at the end of the drain.
 		if (durability === "full" && process.platform !== "win32") {
 			try {
 				const dirFd = await fs.promises.open(path.dirname(filePath), "r");
@@ -832,7 +967,12 @@ export async function atomicWriteJsonAsync<T>(filePath: string, value: T, option
 // Auto-flush hooks: process exit / SIGTERM / SIGINT, plus an exposed
 // `flushPendingAtomicWrites()` for cleanupRuntime.
 interface CoalescedAtomicWrite {
-	content: string;
+	/** PERF (2026-08-24): the value is stringified at FLUSH time, not queue
+	 *  time (see atomicWriteJsonCoalesced). Flushed content reflects the
+	 *  object's state at flush time. */
+	value: unknown;
+	/** PERF-6: formatting captured at queue time, applied at flush time. */
+	compact: boolean;
 	timer: ReturnType<typeof setTimeout>;
 	coalesceMs: number;
 	retryCount: number;
@@ -880,10 +1020,16 @@ export function atomicWriteJsonCoalesced<T>(
 		atomicWriteJson(filePath, value, options);
 		return;
 	}
-	// PERF-6: honor compact — normalize BEFORE serializing so the buffered content
-	// uses the caller's preferred formatting.
+	// PERF-6: honor compact — normalize BEFORE queueing so the buffered entry
+	// carries the caller's preferred formatting for the flush-time stringify.
 	const normalized = normalizeOptions(options);
-	const content = `${normalized.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`;
+	// PERF (2026-08-24): stringify moved to FLUSH time. persistSingleTaskUpdate
+	// re-saves every ~500ms per task while the coalesce window is 50ms — callers
+	// that keep writing overwrite the pending entry before it ever flushes, so
+	// eager stringify burned a full-array serialize per save for nothing.
+	// NOTE (semantic): the flushed content reflects the object's state at flush
+	// time. All current callers hand us a freshly built array and drop it; if a
+	// future caller mutates after queueing, that mutation persists.
 	const previous = pendingAtomicWrites.get(filePath);
 	if (previous) clearTimeout(previous.timer);
 	const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), coalesceMs);
@@ -891,7 +1037,8 @@ export function atomicWriteJsonCoalesced<T>(
 	// Issue 2 fix: increment generation for each new entry
 	const generation = ++writeGeneration;
 	pendingAtomicWrites.set(filePath, {
-		content,
+		value,
+		compact: normalized.compact === true,
 		timer,
 		coalesceMs,
 		retryCount: 0,
@@ -909,7 +1056,11 @@ function flushOnePendingAtomicWrite(filePath: string): void {
 	const savedGeneration = entry.generation;
 	clearTimeout(entry.timer);
 	try {
-		atomicWriteFile(filePath, entry.content, { durability: entry.durability });
+		// PERF (2026-08-24): stringify happens HERE (flush time), not at queue
+		// time — see the note in atomicWriteJsonCoalesced. No defensive deep-copy
+		// of entry.value: that would reintroduce the cost this change removes.
+		const content = `${entry.compact ? JSON.stringify(entry.value) : JSON.stringify(entry.value, null, 2)}\n`;
+		atomicWriteFile(filePath, 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).
@@ -919,25 +1070,34 @@ function flushOnePendingAtomicWrite(filePath: string): void {
 		}
 	} catch (error) {
 		logInternalError("atomic-write.coalesced-flush", error, filePath, "error");
-		// Issue 1 fix: set a fresh timer for failed entries before returning.
-		// This ensures failed entries are retried without waiting for another
-		// write to arrive. Only set timer if this entry is still current
-		// (not replaced by a newer write during the flush).
+		// ISSUE (2026-08-26, dead-retry-path fix): atomicWriteFile's first
+		// statement cancels the pending entry (cancelPendingCoalescedWrite),
+		// so when the write throws, the map no longer holds this entry — the
+		// previous retry logic looked the map up, found nothing, and silently
+		// dropped the buffered write (no retry, no propagation). RE-ADD the
+		// captured entry (unless a NEWER write re-queued during the flush —
+		// its generation would differ) so the backoff retry below fires on
+		// real data instead of a phantom lookup.
 		const current = pendingAtomicWrites.get(filePath);
-		if (current?.generation === savedGeneration) {
-			current.retryCount++;
-			if (current.retryCount >= MAX_FLUSH_RETRIES) {
-				// Max retries exceeded - remove entry and propagate error to callers
-				pendingAtomicWrites.delete(filePath);
-				// Re-throw so callers can handle the persistent failure
-				throw error;
-			}
-			// Exponential backoff: base delay * 2^(retryCount-1), capped at 30 seconds
-			const backoffMs = Math.min(30000, current.coalesceMs * 2 ** (current.retryCount - 1));
-			const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), backoffMs);
-			timer.unref();
-			current.timer = timer;
+		if (current !== undefined && current.generation !== savedGeneration) {
+			// A newer write arrived during the flush — leave it alone.
+			return;
+		}
+		const entryToRetry = current ?? entry;
+		entryToRetry.retryCount++;
+		if (entryToRetry.retryCount >= MAX_FLUSH_RETRIES) {
+			// Max retries exceeded - remove entry and propagate error to callers
+			pendingAtomicWrites.delete(filePath);
+			// Re-throw so callers can handle the persistent failure
+			throw error;
 		}
+		// Exponential backoff: base delay * 2^(retryCount-1), capped at 30 seconds
+		const backoffMs = Math.min(30000, entryToRetry.coalesceMs * 2 ** (entryToRetry.retryCount - 1));
+		clearTimeout(entryToRetry.timer);
+		const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), backoffMs);
+		timer.unref();
+		entryToRetry.timer = timer;
+		pendingAtomicWrites.set(filePath, entryToRetry);
 	}
 }
 
@@ -975,18 +1135,37 @@ function cancelPendingCoalescedWrite(filePath: string): void {
  * Re-entrancy guard (`flushInProgress`) applies to both modes: a scoped flush
  * triggered while a global flush is running is a no-op (the global flush
  * already covers this file), and vice versa.
+ *
+ * T8: the GLOBAL drain (no argument) groups the parent-dir fsync — each
+ * flushed file keeps its data fsync but defers the dir fsync, and after the
+ * serial loop completes (all renames done → R16-B1 ordering) ONE fsync is
+ * issued per distinct pending dir. The trailing fsync lives in the `finally`
+ * so a mid-drain throw (a flush that exhausted MAX_FLUSH_RETRIES) still
+ * makes the already-renamed files crash-durable. Scoped flushes and
+ * coalesce-timer flushes keep the immediate per-file dir fsync.
  */
 export function flushPendingAtomicWrites(filePath?: string): void {
 	if (flushInProgress > 0) return;
 	flushInProgress++;
+	const drainAll = filePath === undefined;
+	if (drainAll) dirFsyncDeferralDepth++;
 	try {
-		if (filePath === undefined) {
+		if (drainAll) {
 			for (const pending of [...pendingAtomicWrites.keys()]) flushOnePendingAtomicWrite(pending);
 		} else if (pendingAtomicWrites.has(filePath)) {
 			flushOnePendingAtomicWrite(filePath);
 		}
 	} finally {
-		flushInProgress--;
+		try {
+			if (drainAll) {
+				// Decrement BEFORE flushing the deferred dirs so nothing inside
+				// the trailing fsync could observe a deferral scope.
+				dirFsyncDeferralDepth--;
+				fsyncPendingParentDirs();
+			}
+		} finally {
+			flushInProgress--;
+		}
 	}
 }
 

package/src/state/coordination/locks.ts

@@ -5,7 +5,7 @@ import * as path from "node:path";
 import { DEFAULT_LOCKS } from "../../config/defaults.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { sleepSync } from "../../utils/sleep.ts";
-import { isSymlinkSafePath } from "../atomic-write.ts";
+import { ensureDirSync, isSymlinkSafeDirCached, isSymlinkSafePath } from "../atomic-write.ts";
 import type { TeamRunManifest } from "../types.ts";
 
 export interface RunLockOptions {
@@ -415,10 +415,12 @@ export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunL
 	if (fileLockHeldByUs.get(lockFile)) {
 		return fn();
 	}
-	// FIX: Validate the parent directory is not a symlink BEFORE calling mkdirSync.
-	// Between mkdir and lock acquisition, an attacker could plant a symlink.
-	if (!isSymlinkSafePath(path.dirname(lockFile))) throw new Error("Refusing: parent of lock directory is a symlink");
-	fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+	// PERF (2026-08-24): pre-loop check uses the 10s-TTL cached verdict (same
+	// tradeoff atomic writes already make). The RETRY loop below keeps the
+	// UNCACHED re-validation — TOCTOU rigor is preserved exactly where a race
+	// is actually being retried.
+	if (!isSymlinkSafeDirCached(path.dirname(lockFile))) throw new Error("Refusing: parent of lock directory is a symlink");
+	ensureDirSync(path.dirname(lockFile));
 	// Round 26 (BUG 2): REMOVED the pre-acquisition target-file-existence check.
 	// It was racy — between statSync(target) and acquire, a concurrent process
 	// could acquire the lock to CREATE the target, and we'd delete its active

package/src/state/coordination/mailbox.ts

@@ -9,7 +9,7 @@ import { withFileLockAsync, withFileLockSync } from "./locks.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
 export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
-export type MailboxMessageKind = "message" | "steer" | "follow-up" | "response" | "group_join";
+export type MailboxMessageKind = "message" | "notify" | "steer" | "follow-up" | "response" | "group_join";
 export type MailboxMessagePriority = "urgent" | "normal" | "low";
 export type MailboxDeliveryMode = "interrupt" | "next_turn";
 
@@ -257,7 +257,14 @@ function isStatus(value: unknown): value is MailboxMessageStatus {
 }
 
 function isKind(value: unknown): value is MailboxMessageKind {
-	return value === "message" || value === "steer" || value === "follow-up" || value === "response" || value === "group_join";
+	return (
+		value === "message" ||
+		value === "notify" ||
+		value === "steer" ||
+		value === "follow-up" ||
+		value === "response" ||
+		value === "group_join"
+	);
 }
 
 function isPriority(value: unknown): value is MailboxMessagePriority {
@@ -309,8 +316,9 @@ function parseMailboxMessage(raw: unknown, expectedDirection: MailboxDirection):
 	};
 }
 
-function readMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
-	if (!fs.existsSync(filePath)) return [];
+/** Raw read+parse of one mailbox JSONL file (extracted verbatim from the old
+ *  readMailboxFile body). Callers go through cachedMailboxRead instead. */
+function parseMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
 	const messages: MailboxMessage[] = [];
 	const raw = fs.readFileSync(filePath, "utf-8");
 	for (const line of raw.split(/\r?\n/).filter(Boolean)) {
@@ -324,18 +332,50 @@ function readMailboxFile(filePath: string, direction: MailboxDirection): Mailbox
 	return messages;
 }
 
+// PERF (2026-08-24): parked workers poll all mailboxes every 500ms and used to
+// read+parse every file each tick. Parse results are now memoized per file by
+// (mtime, size); append/rotate change mtime so invalidation is automatic.
+// Entries hold the parsed array; readers get a shallow copy (array of refs) —
+// 100x cheaper than re-reading, and callers never mutate message objects.
+const mailboxParseCache = new Map<string, { mtimeMs: number; size: number; messages: MailboxMessage[] }>();
+const MAILBOX_PARSE_CACHE_MAX = 128;
+function cachedMailboxRead(filePath: string, direction: MailboxDirection): MailboxMessage[] {
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(filePath);
+	} catch {
+		// Missing (or vanished, e.g. pruned archive) → drop any stale entry.
+		mailboxParseCache.delete(filePath);
+		return [];
+	}
+	const hit = mailboxParseCache.get(filePath);
+	if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.messages.slice();
+	const messages = parseMailboxFile(filePath, direction);
+	if (mailboxParseCache.size >= MAILBOX_PARSE_CACHE_MAX) {
+		const oldest = mailboxParseCache.keys().next().value;
+		if (oldest !== undefined) mailboxParseCache.delete(oldest);
+	}
+	mailboxParseCache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, messages });
+	return messages.slice();
+}
+
 function safeReadMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
-	if (!fs.existsSync(filePath)) return [];
-	const messages: MailboxMessage[] = readMailboxFile(filePath, direction);
+	// PERF: stat-gated primary read — ENOENT is handled inside cachedMailboxRead.
+	const messages = cachedMailboxRead(filePath, direction);
 	// 3.3 — also include any rotated archive files alongside the live file.
 	// Archive naming: `<filename>.<isoTimestamp>.archive.jsonl`.
+	// PERF: archives are immutable once written (rotation only ever creates
+	// new ones — see rotateMailboxFileIfNeeded's rename + atomicWriteFile
+	// sequence), so they route through cachedMailboxRead too and permanently
+	// hit after the first parse. pruneOldMailboxArchives deleting an archive
+	// is covered by cachedMailboxRead's ENOENT → cache-delete branch.
 	try {
 		const dir = path.dirname(filePath);
 		const base = path.basename(filePath);
 		for (const entry of fs.readdirSync(dir)) {
 			if (!entry.startsWith(`${base}.`) || !entry.endsWith(".archive.jsonl")) continue;
 			const archivePath = path.join(dir, entry);
-			messages.push(...readMailboxFile(archivePath, direction));
+			messages.push(...cachedMailboxRead(archivePath, direction));
 		}
 	} catch {
 		// Directory missing — nothing to read.
@@ -610,8 +650,10 @@ export function appendMailboxMessage(
 		const delivery = readDeliveryState(manifest);
 		delivery.messages[complete.id] = complete.status;
 		delivery.updatedAt = createdAt;
-		// F4: complete transitions are terminal-ish — keep full durability.
-		writeDeliveryState(manifest, delivery, { durability: "full" });
+		// F4: delivery state is informational and overwritten by the next message —
+		// drop explicit full durability so the default (best-effort) applies; a hard
+		// crash only risks re-delivery, the accepted semantics of the default path.
+		writeDeliveryState(manifest, delivery);
 	});
 	notifyMailboxAppended(complete);
 	return complete;
@@ -721,7 +763,11 @@ export async function appendMailboxMessageAsync(
 		const delivery = readDeliveryState(manifest);
 		delivery.messages[complete.id] = complete.status;
 		delivery.updatedAt = createdAt;
-		writeDeliveryState(manifest, delivery, { durability: "full" });
+		// PERF round 2 (mirror of the sync-twin fix at :647): delivery.json is
+		// informational and the next message overwrites it — drop the forced
+		// full durability so the default (best-effort) applies here too. A
+		// crash risks re-delivery only, the accepted default-path semantics.
+		writeDeliveryState(manifest, delivery);
 	});
 	notifyMailboxAppended(complete);
 	return complete;