pi-crew 0.9.42 → 0.9.46

package/src/runtime/resilient-edit.ts

@@ -25,13 +25,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type ReplaceResult, replace } from "../runtime/replace.ts";
 
-interface ToolLike {
+interface EditToolLike {
 	name: string;
 	description: string;
 	parameters: unknown;
-	execute: (toolCallId: string, params: any, signal: any, onUpdate: any) => Promise<unknown>;
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	[key: string]: any;
+	execute: (toolCallId: string, params: unknown, signal: unknown, onUpdate: unknown) => Promise<unknown>;
 }
 
 interface EditParams {
@@ -62,12 +60,11 @@ function isNotFoundResult(result: unknown): boolean {
 /** Detect whether pi-diff is loaded (to avoid double-wrapping edit). */
 function isPiDiffLoaded(pi: ExtensionAPI): boolean {
 	try {
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		const piAny = pi as any;
-		const extensions = piAny?.extensions ?? piAny?._extensions ?? [];
+		const piExt = pi as unknown as { extensions?: unknown[] | Record<string, unknown>; _extensions?: unknown[] };
+		const extensions = piExt?.extensions ?? piExt?._extensions ?? [];
 		const names = Array.isArray(extensions)
 			? extensions.map((e: unknown) => (typeof e === "string" ? e : ((e as { name?: string })?.name ?? "")))
-			: Object.keys(extensions);
+			: Object.keys(extensions as Record<string, unknown>);
 		return names.some((n: string) => typeof n === "string" && n.includes("pi-diff"));
 	} catch {
 		return false;
@@ -82,28 +79,32 @@ function isPiDiffLoaded(pi: ExtensionAPI): boolean {
  * @param tools   optional injected tool registry (for testing)
  * @returns true if the wrapper was applied, false if skipped
  */
-export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: ToolLike }): boolean {
+export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: EditToolLike }): boolean {
 	// Auto-disable if pi-diff is present (it has its own replace integration).
 	if (isPiDiffLoaded(pi)) {
 		return false;
 	}
 
-	const t = tools ?? (pi as unknown as { tools?: { edit?: ToolLike } }).tools;
+	const t = tools ?? (pi as unknown as { tools?: { edit?: EditToolLike } }).tools;
 	if (!t?.edit?.execute) return false;
 
 	const nativeExecute = t.edit.execute.bind(t.edit);
 
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	t.edit.execute = async function resilientExecute(toolCallId: string, params: any, signal: any, onUpdate: any): Promise<unknown> {
+	t.edit.execute = async function resilientExecute(
+		toolCallId: string,
+		params: unknown,
+		signal: unknown,
+		onUpdate: unknown,
+	): Promise<unknown> {
 		try {
 			const result = await nativeExecute(toolCallId, params, signal, onUpdate);
 			if (!isNotFoundResult(result)) return result;
 			// Fall through to resilient retry.
-			return await retryWithReplace(params, toolCallId, signal, onUpdate);
+			return await retryWithReplace(params as EditParams, toolCallId, signal, onUpdate);
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			if (NOT_FOUND_PATTERNS.some((re) => re.test(msg))) {
-				return await retryWithReplace(params, toolCallId, signal, onUpdate);
+				return await retryWithReplace(params as EditParams, toolCallId, signal, onUpdate);
 			}
 			throw err;
 		}
@@ -111,7 +112,7 @@ export function wrapEditWithResilientReplace(pi: ExtensionAPI, tools?: { edit: T
 
 	return true;
 
-	async function retryWithReplace(params: EditParams, toolCallId: string, signal: any, onUpdate: any): Promise<unknown> {
+	async function retryWithReplace(params: EditParams, toolCallId: string, signal: unknown, onUpdate: unknown): Promise<unknown> {
 		const filePath = params.path ?? params.filePath;
 		const oldStr = params.oldString ?? params.old_string;
 		const newStr = params.newString ?? params.new_string;

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

@@ -5,8 +5,10 @@ import { saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { runChildPi } from "./child-pi.ts";
+import { DEFAULT_RETRY_POLICY, executeWithRetry } from "./retry-executor.ts";
 import { permissionForRole } from "./role-permission.ts";
 import type { CrewRuntimeMode } from "./runtime-resolver.ts";
+import { sanitizeTaskText } from "./task-packet.ts";
 import { splitCoalescedOutput } from "./task-runner/output-splitter.ts";
 import { mergeArtifacts } from "./team-runner-artifacts.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
@@ -78,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;
@@ -85,38 +99,65 @@ 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 runChildPi({
-				cwd: firstTask.cwd,
-				task: combinedPrompt,
-				agent,
-				signal,
-				excludeContextBash: true,
-				maxTurns: 5,
-				onJsonEvent: (e) => input.onJsonEvent?.(firstTask.id, manifest.runId, e),
-			});
+			const result = await executeWithRetry(
+				async () => {
+					return await runChildPi({
+						cwd: firstTask.cwd,
+						task: combinedPrompt,
+						agent,
+						signal,
+						excludeContextBash: true,
+						maxTurns: 5,
+						onJsonEvent: (e) => input.onJsonEvent?.(firstTask.id, manifest.runId, e),
+					});
+				},
+				DEFAULT_RETRY_POLICY,
+				{ signal },
+			);
 			rawOutput = result.rawFinalText ?? result.stdout ?? "";
 			success = result.exitStatus?.exitCode === 0;
 		} catch (err) {
 			rawOutput = `Worker dispatch failed: ${err instanceof Error ? err.message : String(err)}`;
 			success = false;
 		} finally {
-			clearInterval(heartbeatTimer);
+			if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
 		}
 	}
 
@@ -155,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,
@@ -193,7 +258,7 @@ async function buildCoalescedPrompt(
 				`### Task ${idx + 1} of ${groupTasks.length} (id: ${task.id})`,
 				`Step: ${step.id}`,
 				`Role: ${step.role}`,
-				`Task: ${step.task.replaceAll("{goal}", manifest.goal)}`,
+				`Task: ${sanitizeTaskText(step.task.replaceAll("{goal}", manifest.goal))}`,
 			].join("\n");
 		})
 		.join("\n\n---\n\n");

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/runtime/task-runner/prompt-builder.ts

@@ -4,7 +4,7 @@ import type { TaskOutputSchema, TeamRunManifest, TeamTaskState } from "../../sta
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { buildMemoryBlock } from "../agent-memory.ts";
 import { permissionForRole } from "../role-permission.ts";
-import { HANDOFF_TEMPLATE, renderTaskPacket } from "../task-packet.ts";
+import { HANDOFF_TEMPLATE, renderTaskPacket, sanitizeTaskText } from "../task-packet.ts";
 import { buildWorkspaceTree } from "../workspace-tree.ts";
 import { renderSuggestedFilesSection, runRetrievalCycle } from "./retrieval-orchestrator.ts";
 
@@ -267,7 +267,7 @@ export async function renderTaskPrompt(
 		memoryBlock,
 		task.taskPacket?.outputSchema ? renderOutputSchemaBlock(task.taskPacket.outputSchema) : "",
 		"Task:",
-		step.task.replaceAll("{goal}", manifest.goal),
+		sanitizeTaskText(step.task.replaceAll("{goal}", manifest.goal)),
 		"",
 		"When your task is complete, structure your final output using this handoff template:",
 		HANDOFF_TEMPLATE,

package/src/runtime/team-runner.ts

@@ -9,7 +9,7 @@ import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { PluginRegistry } from "../plugins/plugin-registry.ts";
 import { NextJsPlugin, VitePlugin, VitestPlugin } from "../plugins/plugins/index.ts";
 import { hashArtifactContent as hashContent, writeArtifact } from "../state/artifact-store.ts";
-import { atomicWriteFile } from "../state/atomic-write.ts";
+import { atomicWriteFile, flushPendingAtomicWrites } from "../state/atomic-write.ts";
 import { appendEvent, appendEventAsync, appendEventBuffered, appendEventFireAndForget, flushEventLogBuffer } from "../state/event-log.ts";
 import { HealthStore } from "../state/health-store.ts";
 import { withRunLock } from "../state/locks.ts";
@@ -1615,6 +1615,11 @@ async function executeTeamRunCore(
 		// Read committed manifest from disk inside the lock so artifact merge is based
 		// on committed state, not in-memory state that may differ from disk.
 		const mergeResult = await withRunLock(manifest, async () => {
+			// NEW-D1: flush any pending coalesced atomic writes before reading from
+			// disk. Without this, a worker's async manifest save (coalesced by
+			// atomic-write) may not be committed yet, causing a lost-update on the
+			// merge read. flushPendingAtomicWrites forces all queued writes to disk.
+			flushPendingAtomicWrites();
 			const disk = loadRunManifestById(manifest.cwd, manifest.runId);
 			const diskManifest = disk?.manifest ?? manifest;
 			const diskArtifacts = diskManifest.artifacts;

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) {
@@ -998,6 +1038,7 @@ export function appendEventBuffered(eventsPath: string, event: AppendTeamEvent,
 				});
 			}, bufferMs);
 			bufferedTimers.set(eventsPath, timer);
+			timer.unref();
 		}
 	});
 }
@@ -1216,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;