pi-crew 0.9.44 → 0.9.46

package/src/runtime/role-permission.ts

@@ -1,20 +1,45 @@
 export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
 
+// (FIND-12 R1 review: the AgentPermissionOptions opt-in was dropped — no caller
+// passed `options` and AgentConfig has no `permissions` field, so it was dead
+// code. Custom write-capable roles must instead be added to WRITE_ROLES below.)
+
 // Read-only roles: cannot mutate files/source. `verifier` is NOT here — it runs
 // tests (bash + cache writes) so it is a WRITE role (F4). `planner` stays
 // read-only to preserve the plan-approval gate boundary (F3).
 const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "analyst", "critic", "planner"]);
-const WRITE_ROLES = new Set(["executor", "test-engineer", "writer", "verifier"]);
+// Write-capable roles: can mutate files/source within the workspace.
+// FIND-12 (R1 review): this is an EXPLICIT allowlist — every shipped write-capable
+// role must be listed here, otherwise default-deny demotes it to read-only.
+// `agent` is the default direct-agent role (run.ts); `cold-verifier` runs bash/
+// cache writes; `chain-executor` is the chain-workflow executor variant;
+// `worker` is the autonomous goal-loop + dynamic-workflow executor role
+// (goal-loop-runner.ts, run.ts dynamic workflow synthesis).
+const WRITE_ROLES = new Set(["executor", "test-engineer", "writer", "verifier", "agent", "cold-verifier", "chain-executor", "worker"]);
 export interface PermissionCheckResult {
 	allowed: boolean;
 	mode: RolePermissionMode;
 	reason?: string;
 }
 
+/**
+ * Resolve the permission mode for a given role.
+ *
+ * FIND-12 (2026-07-20): **default-deny** — unknown/unrecognized roles now
+ * receive `"read_only"` instead of the previous permissive `"workspace_write"`.
+ * This prevents privilege escalation via typo'd or custom agent names that
+ * accidentally inherit write capabilities. Write-capable roles are an EXPLICIT
+ * allowlist (`WRITE_ROLES`); to add a custom write-capable role, add it there.
+ * (R1 review: a per-agent-config `permissions.workspaceWrite` opt-in was
+ * considered but dropped — it was unreachable from all 8 call sites.)
+ *
+ * @param role the role name (case-sensitive, must match exactly)
+ */
 export function permissionForRole(role: string): RolePermissionMode {
 	if (READ_ONLY_ROLES.has(role)) return "read_only";
 	if (WRITE_ROLES.has(role)) return "workspace_write";
-	return "workspace_write";
+	// FIND-12: default-deny for unknown/unrecognized roles.
+	return "read_only";
 }
 
 export function currentCrewRole(env: NodeJS.ProcessEnv = process.env): string | undefined {

package/src/runtime/run-coalesced-task-group.ts

@@ -80,6 +80,18 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 
 	let rawOutput = "";
 	let success = false;
+	// FIND-06: serialize heartbeat saves and retain the active save so terminal
+	// results can drain it before their final write.
+	let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	let heartbeatInFlight = false;
+	let heartbeatPromise: Promise<void> | null = null;
+	// FIND-06 P1 fix (R1 review): a heartbeat save that exceeds the 5s drain
+	// timeout continues in the background and can rename its temp file AFTER
+	// the terminal write, clobbering terminal state with the pre-terminal
+	// snapshot. finalWriteStarted lets the IIFE repair that by re-writing the
+	// (now-terminal) updatedTasks AFTER its own save resolves, so the terminal
+	// state always lands last regardless of disk timing.
+	let finalWriteStarted = false;
 	if (!executeWorkers) {
 		rawOutput = buildScaffoldOutput(groupTasks);
 		success = true;
@@ -87,20 +99,41 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 		// Heartbeat refresher: touch every task's heartbeat every 15s while the
 		// worker is alive. Set `alive: true` explicitly so post-completion
 		// staleness checks immediately recognize liveness.
-		const heartbeatTimer = setInterval(async () => {
-			const now = new Date().toISOString();
-			updatedTasks = updatedTasks.map((t) => {
-				if (!taskIds.includes(t.id)) return t;
-				return {
-					...t,
-					heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
-				};
-			});
-			try {
-				await saveRunTasksAsync(manifest, updatedTasks);
-			} catch {
-				// Run may have been pruned mid-dispatch — best-effort only.
-			}
+		heartbeatTimer = setInterval(() => {
+			// FIND-06: setInterval does not await async callbacks. Do not start a
+			// second read/modify/write while the preceding heartbeat save is active.
+			if (heartbeatInFlight) return;
+			heartbeatInFlight = true;
+			heartbeatPromise = (async () => {
+				try {
+					updatedTasks = updatedTasks.map((t) => {
+						if (!taskIds.includes(t.id)) return t;
+						// FIND-06 belt-and-suspenders: never replace terminal state or its
+						// resultArtifact with a heartbeat-only snapshot.
+						if (t.status === "completed" || t.status === "failed") return t;
+						return {
+							...t,
+							heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
+						};
+					});
+					await saveRunTasksAsync(manifest, updatedTasks);
+				} catch {
+					// Run may have been pruned mid-dispatch — best-effort only.
+				} finally {
+					heartbeatInFlight = false;
+					// FIND-06 P1 fix: if the terminal write started while our heartbeat
+					// save was in flight, re-write the (now-terminal) updatedTasks so
+					// our late snapshot cannot leave stale pre-terminal state on disk.
+					// Runs after our own save resolves, so it always lands last.
+					if (finalWriteStarted) {
+						try {
+							await saveRunTasksAsync(manifest, updatedTasks);
+						} catch {
+							// best-effort repair — same swallow policy as the heartbeat.
+						}
+					}
+				}
+			})();
 		}, 15_000);
 		try {
 			const result = await executeWithRetry(
@@ -124,7 +157,7 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			rawOutput = `Worker dispatch failed: ${err instanceof Error ? err.message : String(err)}`;
 			success = false;
 		} finally {
-			clearInterval(heartbeatTimer);
+			if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
 		}
 	}
 
@@ -163,6 +196,30 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			resultArtifact,
 		};
 	});
+
+	// FIND-06: stop ticks and drain the snapshot captured by any active
+	// heartbeat before persisting terminal results. Bound the wait so a stuck
+	// filesystem operation cannot block dispatch completion indefinitely.
+	// P1 fix (R1 review): set finalWriteStarted BEFORE the drain so any pending
+	// heartbeat IIFE observes it and re-writes the terminal state after its
+	// own (possibly late) save resolves — preventing a late heartbeat snapshot
+	// from clobbering the terminal write.
+	finalWriteStarted = true;
+	if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
+	const pendingHeartbeat = heartbeatPromise;
+	if (pendingHeartbeat) {
+		let drainTimeout: ReturnType<typeof setTimeout> | undefined;
+		try {
+			await Promise.race([
+				pendingHeartbeat,
+				new Promise<void>((resolve) => {
+					drainTimeout = setTimeout(resolve, 5_000);
+				}),
+			]);
+		} finally {
+			if (drainTimeout !== undefined) clearTimeout(drainTimeout);
+		}
+	}
 	await saveRunTasksAsync(manifest, updatedTasks);
 	let updatedManifest: TeamRunManifest = {
 		...manifest,

package/src/runtime/task-packet.ts

@@ -85,7 +85,7 @@ export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
 
 	// Generate a deterministic hash-based task ID for traceability and logging.
 	// Uses goal + step ID + run ID as content parts.
-	// TODO: Once TaskPacket type gains a hashId field, include this in the packet.
+	// TODO(hashId): tracked — add hashId to TaskPacket when the schema supports it.
 	const _taskHashId = generateTaskHashId([input.manifest.goal, input.step.id, input.manifest.runId]);
 
 	return {

package/src/state/event-log.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
 import { errors } from "../errors.ts";
 import { emitFromTeamEvent } from "../ui/run-event-bus.ts";
-import { type IncrementalReadState, readJsonlSince } from "../utils/incremental-reader.ts";
+import { type IncrementalReadState, readJsonlSince, readJsonlTail } from "../utils/incremental-reader.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { redactSecrets } from "../utils/redaction.ts";
 import { sleepSync } from "../utils/sleep.ts";
@@ -543,9 +543,13 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 		} catch {
 			/* file does not exist */
 		}
+		// FIND-10: track whether overflow handling modified the file so we can
+		// reuse fileStat for the post-overflow size check (avoids redundant stat).
+		let overflowHandled = false;
 		if (!isTerminal && fileStat) {
 			const stat = fileStat;
 			if (stat.size > MAX_EVENTS_BYTES) {
+				overflowHandled = true;
 				try {
 					compactEventLog(eventsPath);
 				} catch (error) {
@@ -564,11 +568,17 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 				}
 			}
 		}
+		// FIND-10: collapse redundant stat. If no overflow handling occurred,
+		// the file hasn't changed since fileStat — reuse it instead of re-stat'ing.
 		let sizeCheckStat: fs.Stats | undefined;
-		try {
-			sizeCheckStat = await fs.promises.stat(eventsPath).catch(() => undefined);
-		} catch {
-			/* file does not exist */
+		if (overflowHandled) {
+			try {
+				sizeCheckStat = await fs.promises.stat(eventsPath).catch(() => undefined);
+			} catch {
+				/* file does not exist */
+			}
+		} else {
+			sizeCheckStat = fileStat;
 		}
 		try {
 			if (sizeCheckStat && sizeCheckStat.size > MAX_EVENTS_BYTES) {
@@ -583,25 +593,44 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 			logInternalError("event-log.size-check", error, `eventsPath=${eventsPath}`);
 		}
 
+		// FIND-10: post-append stat captured from the same fd (non-worker path)
+		// for reuse in the cache update below, avoiding a redundant path stat.
+		let postAppendStat: fs.Stats | undefined;
 		if (!skippedDueToSize) {
 			const line = JSON.stringify(redactSecrets(fullEvent)) + "\n";
 			// Phase 1.5: when worker atomic writer is enabled, append via worker.
 			if (isWorkerAtomicWriterEnabled()) {
 				await appendFileViaWorker(eventsPath, line);
+				// Worker path: fsync via a separate open (worker manages its own fd).
+				const fd = await fs.promises.open(eventsPath, "r+");
+				try {
+					await fd.sync();
+				} finally {
+					await fd.close();
+				}
 			} else {
-				await fs.promises.appendFile(eventsPath, line, {
-					encoding: "utf-8",
-					flag: "a",
-				});
-			}
-			// FIX: fsync to ensure event content is flushed to disk before persisting
-			// the sequence number. This closes the crash window between appendFile and
-			// persistSequence where sequence reuse could occur on restart.
-			const fd = await fs.promises.open(eventsPath, "r+");
-			try {
-				await fd.sync();
-			} finally {
-				await fd.close();
+				// FIND-10: single-fd append+fsync. Opens in append mode, writes,
+				// fsyncs on the SAME fd, then closes — eliminating the separate
+				// open("r+") + sync that previously doubled the fd count. The
+				// fsync (seq-integrity protection) is preserved exactly: it still
+				// closes the crash window between append and persistSequence.
+				const fd = await fs.promises.open(eventsPath, "a");
+				try {
+					await fd.appendFile(line, "utf-8");
+					await fd.sync();
+					// FIND-10 R1 fix: the cache-optimization fd.stat() must NOT sit in the
+					// seq-durability critical path. If it threw (rare — fd invalidated),
+					// it would skip persistSequence below and reopen the seq-reuse
+					// window the fsync just closed. Guard it; fall back to undefined
+					// (the later cache-update takes a path stat instead).
+					try {
+						postAppendStat = await fd.stat();
+					} catch {
+						postAppendStat = undefined;
+					}
+				} finally {
+					await fd.close();
+				}
 			}
 			// FIX: Persist sequence AFTER successful appendFile to ensure sidecar
 			// is only updated when the event is definitively written. If appendFile
@@ -609,7 +638,11 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 			// preventing sequence reuse on restart.
 			persistSequence(eventsPath, seq);
 		}
+		// FIND-10: track whether compaction happened after the append so the
+		// cache-update stat can safely reuse postAppendStat (file unchanged).
+		let compactedAfterAppend = false;
 		if (appendCounter % 100 === 0 && needsRotation(eventsPath)) {
+			compactedAfterAppend = true;
 			try {
 				compactEventLog(eventsPath);
 			} catch (error) {
@@ -626,11 +659,18 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 		// Only update the cache here (the sidecar persist is already done).
 		const finalSeq = fullEvent.metadata?.seq ?? 0;
 		try {
+			// FIND-10: reuse post-append fd stat when available and no compaction
+			// happened after the append (file unchanged). Falls back to path stat
+			// for the worker path, skipped events, or post-compaction cases.
 			let statResult: fs.Stats | undefined;
-			try {
-				statResult = await fs.promises.stat(eventsPath).catch(() => undefined);
-			} catch {
-				/* file may not exist */
+			if (postAppendStat && !compactedAfterAppend) {
+				statResult = postAppendStat;
+			} else {
+				try {
+					statResult = await fs.promises.stat(eventsPath).catch(() => undefined);
+				} catch {
+					/* file may not exist */
+				}
 			}
 			if (statResult) {
 				if (sequenceCache.size >= MAX_SEQUENCE_CACHE_ENTRIES) {
@@ -1217,24 +1257,38 @@ export function readEventsCursor(eventsPath: string, options: EventCursorOptions
 		};
 	}
 
-	// Original behavior: read entire file.
-	// FIX (Round 14, H7): When called WITHOUT fromByteOffset on a large file,
-	// fall back to reading only the tail (last 1MB) plus metadata about the
-	// dropped prefix. This avoids O(n) memory load on hot UI paths while
-	// preserving a sensible default.
+	// FIND-05 default path: byte-level tail read (last 4MB) instead of
+	// full-file read. Bounds CPU to O(tail bytes) instead of O(total
+	// events). The legacy readEvents() full parse path is preserved for
+	// callers that explicitly need the full history (e.g. tests that
+	// assert exact contents) and as a small-file fallback.
+	//
+	// The 5000-event tail cap and the "event-log.cursor-full-read"
+	// warning are preserved. A separate cursor-tail-truncated warning is
+	// emitted whenever the file exceeds the 4MB tail budget, signalling
+	// that a prefix was dropped and callers should pass fromByteOffset for
+	// streaming reads.
+	const TAIL_BYTES = 4 * 1024 * 1024; // 4 MB
+	const TAIL_EVENT_CAP = 5000;
 	const sinceSeq = positiveInteger(options.sinceSeq) ?? 0;
 	const limit = positiveInteger(options.limit);
-	let all = readEvents(eventsPath);
-	const totalAll = all.length;
-	if (totalAll > 5000 && options.fromByteOffset === undefined) {
-		// TAIL READ: keep the most recent 5000 events to bound memory.
-		// Callers that need full history should pass fromByteOffset to stream.
+
+	const tail = readJsonlTail<TeamEvent>(eventsPath, TAIL_BYTES);
+	let all = tail.items;
+	if (tail.truncated) {
+		logInternalError("event-log.cursor-tail-truncated", {
+			eventsPath,
+			returned: all.length,
+			tailBytes: TAIL_BYTES,
+		});
+	}
+	if (all.length > TAIL_EVENT_CAP) {
 		logInternalError(
 			"event-log.cursor-full-read",
-			new Error(`readEventsCursor read entire ${totalAll}-event log; pass fromByteOffset for incremental reads`),
+			new Error(`readEventsCursor tail read dropped events from a larger log; pass fromByteOffset for incremental reads`),
 			`eventsPath=${eventsPath}`,
 		);
-		all = all.slice(-5000);
+		all = all.slice(-TAIL_EVENT_CAP);
 	}
 	const filtered = all.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
 	const events = limit !== undefined ? filtered.slice(0, limit) : filtered;

package/src/state/locks.ts

@@ -447,6 +447,59 @@ const lockCtx = new AsyncLocalStorage<Set<string>>();
 // at the top of withFileLockSync for the full deadlock mechanism.
 const fileLockHeldByUs = new Map<string, string>(); // lockFile -> token
 
+// --- Async file lock (non-blocking alternative to withFileLockSync) ---
+// Uses a promise-chain pattern to serialize per-path access without blocking
+// the Node.js event loop. Unlike withFileLockSync (which uses O_EXCL +
+// sleepSync for cross-process safety), this is **in-process only** —
+// sufficient for single-process mailbox writes (team-runner is single-process).
+// Mirrors the structure of withEventLogLockAsync in event-log.ts.
+const fileAsyncLocks = new Map<string, Promise<unknown>>();
+
+// FIND-02 follow-up (P3): re-entrance guard for the async file lock, mirroring
+// the lockCtx pattern used by withRunLock. A future caller doing same-path
+// nested withFileLockAsync(path, ...) inside another withFileLockAsync(path,
+// ...) in the SAME async context would otherwise deadlock (the nested call
+// chains after the outer's still-pending promise). AsyncLocalStorage scopes
+// the held set to the current async context so cross-context callers still
+// serialize via the promise chain (Phase 1 mailbox path is unaffected).
+const fileAsyncLockCtx = new AsyncLocalStorage<Set<string>>();
+
+export async function withFileLockAsync<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+	// Re-entrant within the same async context — run fn() directly (no chaining).
+	// Same semantics as the sync guard in withFileLockSync (fileLockHeldByUs)
+	// and the async guard in withRunLock (lockCtx).
+	if (fileAsyncLockCtx.getStore()?.has(filePath)) {
+		return await fn();
+	}
+	// Merge with the parent context's held set so nested DIFFERENT-path locks
+	// also bypass correctly (prevents cross-path deadlock, matching withRunLock).
+	const prevHeld = fileAsyncLockCtx.getStore() ?? new Set<string>();
+	const held = new Set(prevHeld);
+	held.add(filePath);
+	const prev = fileAsyncLocks.get(filePath) ?? Promise.resolve();
+	// Chain fn after the previous holder. `next` may reject (propagating to the
+	// caller), but `stored` never rejects so subsequent waiters aren't blocked.
+	// fn() is wrapped in fileAsyncLockCtx.run so nested same-context calls see
+	// `held` and bypass the promise chain (re-entrant), while cross-context
+	// callers chain normally via `prev`.
+	const next = prev.then(() => fileAsyncLockCtx.run(held, () => fn()));
+	const stored = next.then(
+		() => undefined,
+		() => undefined,
+	);
+	fileAsyncLocks.set(filePath, stored);
+	try {
+		return await next;
+	} finally {
+		// Compare-and-delete: only remove our entry if it still points at `stored`.
+		// With 3+ overlapping callers, an earlier caller's finally would otherwise
+		// delete a later caller's promise, breaking mutual exclusion.
+		if (fileAsyncLocks.get(filePath) === stored) {
+			fileAsyncLocks.delete(filePath);
+		}
+	}
+}
+
 export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, options: RunLockOptions = {}): T {
 	const filePath = lockPath(manifest);
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;

package/src/state/mailbox.ts

@@ -5,7 +5,7 @@ import { logInternalError } from "../utils/internal-error.ts";
 import { redactSecrets } from "../utils/redaction.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { withEventLogLockSync } from "./event-log.ts";
-import { withFileLockSync } from "./locks.ts";
+import { withFileLockAsync, withFileLockSync } from "./locks.ts";
 import type { TeamRunManifest } from "./types.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
@@ -377,19 +377,61 @@ function readAllInboxMessages(manifest: TeamRunManifest): MailboxMessage[] {
 	return readAllMessages(manifest, "inbox");
 }
 
+// FIND-01: in-process delivery cache to avoid O(N²) re-reads on every append.
+// Keyed by delivery file path; invalidated by mtime check on read + updated on
+// write. Team-runner is single-process so in-process caching is sufficient.
+const deliveryCache = new Map<string, { mtimeMs: number; state: MailboxDeliveryState }>();
+const MAX_DELIVERY_CACHE_ENTRIES = 256;
+// R1 review fix: setDeliveryCacheEntry stores an immutable snapshot (deep
+// copy of `messages`) so callers mutating the returned state cannot corrupt
+// the cache (TOCTOU race), and bounds the map size with FIFO eviction to
+// prevent unbounded growth across runs.
+function setDeliveryCacheEntry(filePath: string, entry: { mtimeMs: number; state: MailboxDeliveryState }): void {
+	if (deliveryCache.size >= MAX_DELIVERY_CACHE_ENTRIES) {
+		const oldest = deliveryCache.keys().next().value;
+		if (oldest !== undefined) deliveryCache.delete(oldest);
+	}
+	deliveryCache.set(filePath, {
+		mtimeMs: entry.mtimeMs,
+		state: { ...entry.state, messages: { ...entry.state.messages } },
+	});
+}
+
 export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliveryState {
+	const filePath = deliveryFile(manifest);
+	let stat: fs.Stats;
 	try {
-		const raw = JSON.parse(fs.readFileSync(deliveryFile(manifest), "utf-8")) as unknown;
+		stat = fs.statSync(filePath);
+	} catch (e) {
+		// R1 review fix: narrow to ENOENT so permission errors aren't silently
+		// treated as "missing file" (would wipe a valid cache entry).
+		if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+		deliveryCache.delete(filePath);
+		return { messages: {}, updatedAt: new Date().toISOString() };
+	}
+	const cached = deliveryCache.get(filePath);
+	if (cached && cached.mtimeMs === stat.mtimeMs) {
+		// R2 review fix: return a copy so callers mutating the result cannot
+		// leak into the cached snapshot (residual TOCTOU: the cache holds the
+		// snapshot until the next write replaces it; without this copy, a
+		// pre-write mutation by one caller would be persisted into the
+		// post-write snapshot by the next writer's setDeliveryCacheEntry).
+		return { ...cached.state, messages: { ...cached.state.messages } };
+	}
+	try {
+		const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
 		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid delivery state.");
 		const obj = raw as Record<string, unknown>;
 		const messages: Record<string, MailboxMessageStatus> = {};
 		if (obj.messages && typeof obj.messages === "object" && !Array.isArray(obj.messages)) {
 			for (const [id, status] of Object.entries(obj.messages)) if (isStatus(status)) messages[id] = status;
 		}
-		return {
+		const state: MailboxDeliveryState = {
 			messages,
 			updatedAt: typeof obj.updatedAt === "string" ? obj.updatedAt : new Date().toISOString(),
 		};
+		setDeliveryCacheEntry(filePath, { mtimeMs: stat.mtimeMs, state });
+		return state;
 	} catch {
 		return { messages: {}, updatedAt: new Date().toISOString() };
 	}
@@ -414,9 +456,20 @@ function writeDeliveryState(
 	// 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`, {
+	const filePath = deliveryFile(manifest, true);
+	atomicWriteFile(filePath, `${JSON.stringify(redactSecrets(state), null, 2)}\n`, {
 		durability: options?.durability ?? "best-effort",
 	});
+	// FIND-01: update cache with post-write mtime so subsequent reads get a hit.
+	try {
+		const postStat = fs.statSync(filePath);
+		// setDeliveryCacheEntry stores an immutable snapshot (deep copy of
+		// messages) so subsequent read-modify-write callers mutating the
+		// returned state cannot corrupt the cache.
+		setDeliveryCacheEntry(filePath, { mtimeMs: postStat.mtimeMs, state });
+	} catch {
+		deliveryCache.delete(filePath);
+	}
 }
 
 /**
@@ -541,6 +594,114 @@ export function appendFollowUpMessage(
 	});
 }
 
+/**
+ * FIND-02: Async variant of appendMailboxMessage for the live-session path.
+ * Uses withFileLockAsync (promise-chain, no sleepSync) instead of
+ * withEventLogLockSync/withFileLockSync, preventing event-loop stalls during
+ * steering/follow-up delivery. readDeliveryState/writeDeliveryState remain
+ * sync but are cheap thanks to the FIND-01 delivery cache.
+ */
+export async function appendMailboxMessageAsync(
+	manifest: TeamRunManifest,
+	message: Omit<MailboxMessage, "id" | "runId" | "createdAt" | "status"> & {
+		id?: string;
+		status?: MailboxMessageStatus;
+	},
+): Promise<MailboxMessage> {
+	if (message.taskId) ensureTaskMailbox(manifest, message.taskId);
+	else ensureRunMailbox(manifest);
+	const createdAt = new Date().toISOString();
+	const complete: MailboxMessage = {
+		id: message.id ?? `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+		runId: manifest.runId,
+		direction: message.direction,
+		from: message.from,
+		to: message.to,
+		body: message.body,
+		createdAt,
+		status: message.status ?? "queued",
+		kind: message.kind,
+		priority: message.priority,
+		deliveryMode: message.deliveryMode,
+		taskId: message.taskId,
+		data: message.data,
+		replyTo: message.replyTo,
+		replyFrom: message.replyFrom,
+		replyDeadline: message.replyDeadline,
+		repliedAt: message.repliedAt,
+		replyContent: message.replyContent,
+	};
+	const mbFile = mailboxFile(manifest, complete.direction, complete.taskId);
+	await withFileLockAsync(mbFile, async () => {
+		await fs.promises.appendFile(mbFile, `${JSON.stringify(redactSecrets(complete))}\n`, "utf-8");
+		rotateMailboxFileIfNeeded(mbFile);
+	});
+	// R1 review fix / plan §5 #6: delivery RMW uses the cross-process sync
+	// lock (withFileLockSync) so sync callers (acknowledgeMailboxMessage,
+	// replayPendingMailboxMessages) serialize against this async path. The
+	// body has no await, so sync locking is safe and restores the
+	// cross-process safety net that the async lock cannot provide.
+	withFileLockSync(deliveryFile(manifest, true), () => {
+		const delivery = readDeliveryState(manifest);
+		delivery.messages[complete.id] = complete.status;
+		delivery.updatedAt = createdAt;
+		writeDeliveryState(manifest, delivery, { durability: "full" });
+	});
+	return complete;
+}
+
+export async function appendSteeringMessageAsync(
+	manifest: TeamRunManifest,
+	input: {
+		taskId: string;
+		body: string;
+		from?: string;
+		to?: string;
+		priority?: MailboxMessagePriority;
+		status?: MailboxMessageStatus;
+		data?: Record<string, unknown>;
+	},
+): Promise<MailboxMessage> {
+	return appendMailboxMessageAsync(manifest, {
+		direction: "inbox",
+		from: input.from ?? "leader",
+		to: input.to ?? input.taskId,
+		taskId: input.taskId,
+		body: input.body,
+		kind: "steer",
+		priority: input.priority ?? "urgent",
+		deliveryMode: "interrupt",
+		status: input.status,
+		data: { ...(input.data ?? {}), kind: "steer" },
+	});
+}
+
+export async function appendFollowUpMessageAsync(
+	manifest: TeamRunManifest,
+	input: {
+		taskId: string;
+		body: string;
+		from?: string;
+		to?: string;
+		priority?: MailboxMessagePriority;
+		status?: MailboxMessageStatus;
+		data?: Record<string, unknown>;
+	},
+): Promise<MailboxMessage> {
+	return appendMailboxMessageAsync(manifest, {
+		direction: "inbox",
+		from: input.from ?? "leader",
+		to: input.to ?? input.taskId,
+		taskId: input.taskId,
+		body: input.body,
+		kind: "follow-up",
+		priority: input.priority ?? "normal",
+		deliveryMode: "next_turn",
+		status: input.status,
+		data: { ...(input.data ?? {}), kind: "follow-up" },
+	});
+}
+
 export function listMailboxByKind(manifest: TeamRunManifest, kind: MailboxMessageKind, direction?: MailboxDirection): MailboxMessage[] {
 	const messages = direction
 		? readAllMessages(manifest, direction)