pi-crew 0.11.21 → 0.11.23

package/src/runtime/verification/green-contract.ts

@@ -33,6 +33,18 @@ export function inferGreenLevelFromTask(success: boolean, contract: Verification
 	return contract.allowManualEvidence ? contract.requiredGreenLevel : "targeted";
 }
 
+/** R4-5 (DR-02 wave 2): true when the contract REQUIRES a green level but
+ *  configures zero verification commands — the default contract shape for
+ *  every `verify: true` step (task-packet defaultVerificationContract).
+ *  With no commands to run, satisfaction can only ever come from
+ *  self-attestation (allowManualEvidence → inferGreenLevelFromTask returns
+ *  the required level), which silently reports e.g. "targeted/targeted".
+ *  Surface that as `decorative: true` on the evidence instead of changing
+ *  the satisfied logic or the defaults (detection-first, no behavior flip). */
+export function isDecorativeVerification(contract: VerificationContract): boolean {
+	return contract.requiredGreenLevel !== "none" && contract.commands.length === 0;
+}
+
 export function createVerificationEvidence(contract: VerificationContract, success: boolean, notes: string): VerificationEvidence {
 	const observedGreenLevel = inferGreenLevelFromTask(success, contract);
 	const outcome = evaluateGreenContract(contract, {
@@ -42,6 +54,10 @@ export function createVerificationEvidence(contract: VerificationContract, succe
 		commands: [],
 		notes,
 	});
+	// R4-5: stamp the decorative flag so consumers (post-execution evidence
+	// builder, policy engine, UI) can tell self-attested satisfaction from
+	// command-backed satisfaction. Satisfied logic is untouched.
+	const decorative = isDecorativeVerification(contract);
 	return {
 		requiredGreenLevel: contract.requiredGreenLevel,
 		observedGreenLevel,
@@ -51,5 +67,6 @@ export function createVerificationEvidence(contract: VerificationContract, succe
 			status: "not_run" as const,
 		})),
 		notes,
+		...(decorative ? { decorative: true } : {}),
 	};
 }

package/src/runtime/verification/verification-gates.ts

@@ -144,6 +144,16 @@ export const CARGO_RUST_GATES: Array<{
 /**
  * Execute a single command and capture output.
  */
+/**
+ * P-4 (DR-04 round-7): accumulation cap while STREAMING child output. The
+ * final `slice(-100000)` already bounds the RESULT, but the live `output`
+ * buffer used to concatenate every chunk until close/timeout — a command
+ * emitting gigabytes held them ALL in memory (plus O(n²) string concat).
+ * Past this cap we stop concatenating and pin a "[truncated]" marker in the
+ * buffer; the final tail slice is unchanged.
+ */
+const OUTPUT_ACCUMULATION_CAP_CHARS = 200 * 1024;
+const OUTPUT_TRUNCATION_MARKER = "\n[truncated]";
 /** Characters/patterns that indicate dangerous shell metacharacters. */
 // Round 25 (VULN-3/VULN-4): also block raw newlines (sh -c treats \n as a
 // command separator -> injection) and bare $VARNAME references (can exfiltrate
@@ -253,8 +263,20 @@ export async function executeCommand(
 
 	const start = Date.now();
 	let output = "";
+	let capped = false;
 	let exitCode: number | null = null;
 
+	// P-4: single capped appender for BOTH streams — once the cap trips, later
+	// chunks are dropped (marker stays in the buffer; final slice keeps it).
+	const appendCapped = (chunk: Buffer): void => {
+		if (capped) return;
+		output += chunk.toString();
+		if (output.length > OUTPUT_ACCUMULATION_CAP_CHARS) {
+			capped = true;
+			output += OUTPUT_TRUNCATION_MARKER;
+		}
+	};
+
 	return new Promise((resolve) => {
 		const shell = spawn("sh", ["-c", command], {
 			cwd,
@@ -263,13 +285,9 @@ export async function executeCommand(
 			detached: true, // CORE-10: own process group so group-wide SIGKILL reaches children
 		});
 
-		shell.stdout?.on("data", (data) => {
-			output += data.toString();
-		});
+		shell.stdout?.on("data", appendCapped);
 
-		shell.stderr?.on("data", (data) => {
-			output += data.toString();
-		});
+		shell.stderr?.on("data", appendCapped);
 
 		// M-9 fix (code-review 2026-06-23): store the timeout handle so it can be
 		// cleared when the process exits normally, and unref it so it does not

package/src/runtime/workspace-lock.ts

@@ -28,6 +28,22 @@
  * Granularity: per-goal, held for the goal's lifetime (release() on goal end).
  * Contention: default QUEUE (poll until released or stale);
  *             opts.failOnWorkspaceBusy:true → THROW instead of queue.
+ *
+ * ─── HEARTBEAT REFRESH CONTRACT (WI-2 / DR-02 R4-3, 2026-10-15) ───
+ * The heartbeat is written ONCE at acquire. Clause (b) above marks a lock
+ * stale after HEARTBEAT_STALE_MS REGARDLESS of holder pid liveness — so a
+ * live goal whose loop runs longer than 60s would be force-stolen by a
+ * second goal on the same cwd (multi-goal clobber, audit R4-3). Holders that
+ * stay in a long-running loop MUST keep the heartbeat fresh via
+ * refreshWorkspaceLockHeartbeat(lockPath, goalId) — the goal-loop runner does
+ * this on a 15s unref-ed timer (startWorkspaceLockHeartbeatRefresh in
+ * goal-loop-runner.ts), stopped in the same finally that releases the lock.
+ * The refresh re-stamps ONLY `heartbeat` (all other fields + file format
+ * preserved) and ONLY while the lock still belongs to (goalId, pid) — a lock
+ * reclaimed by another goal is never clobbered. Decision note: the interval
+ * refresh was chosen over "drop clause (b) / PID-liveness-only staleness"
+ * because clause (b) is the only crash signal for kill -9'd holders on
+ * non-Linux platforms where /proc startTime is unavailable.
  */
 
 import { createHash } from "node:crypto";
@@ -149,6 +165,43 @@ function writeLock(lockPath: string, contents: WorkspaceLockContents): void {
 	atomicWriteJson(lockPath, contents);
 }
 
+export interface RefreshWorkspaceLockHeartbeatOptions {
+	/** Test injection: override current time (ms). Default Date.now(). */
+	now?: () => number;
+	/** Test injection: override the current pid. Default process.pid. */
+	pid?: number;
+}
+
+/**
+ * Refresh the heartbeat of a lock this goal still owns (WI-2 / DR-02 R4-3).
+ *
+ * Reads the lockfile and rewrites it with `heartbeat: now()` — preserving
+ * every other field (pid, startTime, goalId, acquiredAt) and the file format
+ * — ONLY when the lock still belongs to (goalId, pid). Returns false —
+ * leaving the file untouched — when the lockfile is missing, was reclaimed /
+ * re-acquired by another goal, or the write failed: refreshing must NEVER
+ * clobber a lock that someone else owns (same ownership guard philosophy as
+ * safeRelease). This is what keeps a >60s-running goal's lock from being
+ * force-stolen via isLockStale clause (b) despite a live pid.
+ *
+ * Non-throwing by contract: failures surface as false, never as an exception
+ * into the caller's loop (the goal-loop still wraps calls in try/catch →
+ * logInternalError warn as belt-and-braces, see goal-loop-runner.ts).
+ */
+export function refreshWorkspaceLockHeartbeat(lockPath: string, goalId: string, opts: RefreshWorkspaceLockHeartbeatOptions = {}): boolean {
+	try {
+		const current = readLock(lockPath);
+		if (!current) return false;
+		const pid = opts.pid ?? process.pid;
+		if (current.goalId !== goalId || current.pid !== pid) return false;
+		const now = opts.now ?? Date.now;
+		writeLock(lockPath, { ...current, heartbeat: now() });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * CLAIM the lockfile atomically via O_EXCL (cold-review #3 NIT #N1 fix).
  * The previous claim used temp+rename (writeLock), which is NOT cross-process atomic —

package/src/schema/team-tool-schema.ts

@@ -74,7 +74,7 @@ export function buildStringEnum(values: readonly string[], description: string,
 }
 
 // ───────────────────────────────────────────────────────────────────────────
-// API-5 facade split: the 54-action mega-tool schema is split into 5 domain
+// API-5 facade split: the 57-action mega-tool schema is split into 5 domain
 // schemas. Each domain owns a subset of the action union; all parameter fields
 // are shared across every variant so Phase 1 validation is identical to the
 // pre-split flat Object (additionalProperties: true → no tightening).
@@ -226,14 +226,20 @@ const sharedFields = {
 		// Also accept stringified numbers ("123456") — pi-ai coercion stringifies
 		// numeric values when a Union has a string-literal branch. handleTeamTool
 		// coerces strings back to numbers before handlers run.
+		// R7-5 (docs-truth): this value is ADVISORY metadata — the enforced
+		// deadline is the broker-clamped task.waiting.deadline, not this field.
 		Type.Union(
 			[
 				Type.Literal(""),
-				Type.Integer({ description: "Ms epoch deadline for a reply." }),
+				Type.Integer({
+					description:
+						"Advisory metadata only. The enforced deadline is auto-clamped by the broker (task.waiting.deadline); this value is recorded, not enforced.",
+				}),
 				Type.String({ pattern: NUMERIC_STRING_RE }),
 			],
 			{
-				description: "Ms epoch deadline for a reply.",
+				description:
+					"Advisory metadata only. The enforced deadline is auto-clamped by the broker (task.waiting.deadline); this value is recorded, not enforced.",
 			},
 		),
 	),
@@ -589,7 +595,7 @@ export interface TeamToolParamsValue {
 	replyTo?: string;
 	/** Task ID sending the reply. */
 	replyFrom?: string;
-	/** Ms epoch deadline for a reply. */
+	/** Advisory metadata only. The enforced deadline is auto-clamped by the broker (task.waiting.deadline); this value is recorded, not enforced. */
 	replyDeadline?: number;
 	/** Path to a markdown plan document for orchestration. */
 	planPath?: string;

package/src/state/coordination/mailbox.ts

@@ -375,9 +375,27 @@ function cachedMailboxRead(filePath: string, direction: MailboxDirection): Mailb
 	return messages.slice();
 }
 
+/** R7-3 (2026-10-16): rotated archive siblings of a live mailbox file,
+ *  sorted lexicographically. The archive name embeds an ISO timestamp, so
+ *  lexicographic order ≈ chronological (oldest first). */
+function listMailboxArchives(filePath: string): string[] {
+	try {
+		const dir = path.dirname(filePath);
+		const base = path.basename(filePath);
+		return fs
+			.readdirSync(dir)
+			.filter((entry) => entry.startsWith(`${base}.`) && entry.endsWith(".archive.jsonl"))
+			.sort()
+			.map((entry) => path.join(dir, entry));
+	} catch {
+		// Directory missing — nothing to read.
+		return [];
+	}
+}
+
 function safeReadMailboxFile(filePath: string, direction: MailboxDirection): MailboxMessage[] {
 	// PERF: stat-gated primary read — ENOENT is handled inside cachedMailboxRead.
-	const messages = cachedMailboxRead(filePath, direction);
+	const live = 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
@@ -385,18 +403,37 @@ function safeReadMailboxFile(filePath: string, direction: MailboxDirection): Mai
 	// 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(...cachedMailboxRead(archivePath, direction));
+	const archives = listMailboxArchives(filePath);
+	if (archives.length === 0) return live;
+	// R7-3 (2026-10-16) — same-id LAST-WINS merge, live file applied LAST.
+	//
+	// DESIGN: rotation moves a message into an archive and recreates an empty
+	// live file, so a message normally exists in exactly ONE place and a plain
+	// concat was duplicate-free. The exception is updateMailboxMessageReply:
+	// archives are IMMUTABLE history and are never rewritten, so when the
+	// original message lives only in an archive the reply is recorded as a
+	// COMPENSATING record — same id, reply metadata set — appended to the LIVE
+	// file. Merging by id (archives oldest→newest first, live file last)
+	// collapses the pair into a single reply-marked message, so readMailbox /
+	// readMailboxMessage expose ONE copy with repliedAt set; consumers
+	// (replayPendingMailboxMessages, listMailboxByKind, …) never see the
+	// duplicate reply-less archived original.
+	const merged: MailboxMessage[] = [];
+	const indexById = new Map<string, number>();
+	const upsert = (message: MailboxMessage): void => {
+		const existing = indexById.get(message.id);
+		if (existing === undefined) {
+			indexById.set(message.id, merged.length);
+			merged.push(message);
+		} else {
+			merged[existing] = message;
 		}
-	} catch {
-		// Directory missing — nothing to read.
+	};
+	for (const archivePath of archives) {
+		for (const message of cachedMailboxRead(archivePath, direction)) upsert(message);
 	}
-	return messages;
+	for (const message of live) upsert(message);
+	return merged;
 }
 
 /**
@@ -1138,6 +1175,15 @@ export function acknowledgeMailboxMessage(manifest: TeamRunManifest, messageId:
  * Update an original mailbox message with reply metadata.
  * Rewrites the mailbox file line containing the original message
  * to include `repliedAt` and `replyContent`.
+ *
+ * R7-3 (2026-10-16): the original may have been ROTATED out of the live file
+ * into a `*.archive.jsonl` sibling (rotateMailboxFileIfNeeded). Archives are
+ * IMMUTABLE history — they are never rewritten here. When the original is
+ * found only in an archive, a COMPENSATING record (same id + reply metadata)
+ * is appended to the LIVE file instead; safeReadMailboxFile merges by id
+ * last-wins (live overrides archive), so every reader sees the reply-marked
+ * message. Global run mailboxes AND every task mailbox (inbox + outbox, live
+ * + archives) are scanned.
  */
 export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMessageId: string, replyContent: string): void {
 	const directions: MailboxDirection[] = ["inbox", "outbox"];
@@ -1167,35 +1213,64 @@ export function updateMailboxMessageReply(manifest: TeamRunManifest, originalMes
 	}
 
 	for (const { filePath, direction } of filesToSearch) {
-		if (!fs.existsSync(filePath)) continue;
-		// FIX: Wrap read-modify-write in withFileLockSync to prevent concurrent
-		// updates from clobbering each other (each reply rewrites the whole file).
-		const found = withFileLockSync(filePath, () => {
-			const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
-			let localFound = false;
-			const updatedLines: string[] = [];
-			for (const line of lines) {
-				try {
-					const parsed = JSON.parse(line) as unknown;
-					const msg = parseMailboxMessage(parsed, direction);
-					if (msg && msg.id === originalMessageId) {
-						msg.repliedAt = new Date().toISOString();
-						msg.replyContent = replyContent;
-						updatedLines.push(JSON.stringify(redactSecrets(msg)));
-						localFound = true;
-					} else {
+		const archives = listMailboxArchives(filePath);
+		if (fs.existsSync(filePath)) {
+			// Path 1 (original behavior): the message still lives in the LIVE
+			// file — rewrite its line in place.
+			// FIX: Wrap read-modify-write in withFileLockSync to prevent concurrent
+			// updates from clobbering each other (each reply rewrites the whole file).
+			const found = withFileLockSync(filePath, () => {
+				const lines = fs.readFileSync(filePath, "utf-8").split(/\r?\n/).filter(Boolean);
+				let localFound = false;
+				const updatedLines: string[] = [];
+				for (const line of lines) {
+					try {
+						const parsed = JSON.parse(line) as unknown;
+						const msg = parseMailboxMessage(parsed, direction);
+						if (msg && msg.id === originalMessageId) {
+							msg.repliedAt = new Date().toISOString();
+							msg.replyContent = replyContent;
+							updatedLines.push(JSON.stringify(redactSecrets(msg)));
+							localFound = true;
+						} else {
+							updatedLines.push(line);
+						}
+					} catch {
 						updatedLines.push(line);
 					}
-				} catch {
-					updatedLines.push(line);
 				}
-			}
-			if (localFound) {
-				atomicWriteFile(filePath, `${updatedLines.join("\n")}\n`);
-			}
-			return localFound;
+				if (localFound) {
+					atomicWriteFile(filePath, `${updatedLines.join("\n")}\n`);
+				}
+				return localFound;
+			});
+			if (found) return;
+		}
+		if (archives.length === 0) continue;
+		// Path 2 (R7-3): the original was rotated into an archive. Archives are
+		// immutable (see safeReadMailboxFile) — do NOT rewrite them; append a
+		// compensating record carrying the reply metadata to the LIVE file.
+		// The id-based last-wins merge makes it win over the archived original.
+		const archived = archives
+			.flatMap((archivePath) => cachedMailboxRead(archivePath, direction))
+			.find((message) => message.id === originalMessageId);
+		if (!archived) continue;
+		const compensating: MailboxMessage = {
+			...archived,
+			repliedAt: new Date().toISOString(),
+			replyContent,
+		};
+		withFileLockSync(filePath, () => {
+			// Recreate the live file if it went missing — the archives in this
+			// directory prove the mailbox itself is valid.
+			if (!fs.existsSync(filePath)) atomicWriteFile(filePath, "");
+			fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets(compensating))}\n`, "utf-8");
+			// The append may itself trigger rotation — safe: the compensating
+			// record then lands in the NEWEST archive, which sorts after the
+			// original's archive in the merge order, so it still wins by id.
+			rotateMailboxFileIfNeeded(filePath);
 		});
-		if (found) return;
+		return;
 	}
 	// Not finding the original is non-fatal; the reply is still delivered.
 }
@@ -1224,9 +1299,27 @@ export function validateMailbox(
 	ensureRunMailbox(manifest);
 	const issues: MailboxValidationIssue[] = [];
 	const repaired: string[] = [];
+	// L-9 (2026-10-16): validate + repair the TASK mailboxes
+	// (`mailbox/tasks/<id>/<direction>.jsonl`) with the same line-parse
+	// semantics as the run-level files — enumerate the tasks dir the same way
+	// updateMailboxMessageReply does. Rotated `*.archive.jsonl` files are
+	// immutable history and are deliberately NOT repaired.
+	const filesToValidate: Array<{ filePath: string; direction: MailboxDirection }> = [];
 	for (const direction of ["inbox", "outbox"] as const) {
+		filesToValidate.push({ filePath: mailboxFile(manifest, direction), direction });
+	}
+	const tasksDir = safeMailboxTasksRoot(manifest);
+	if (fs.existsSync(tasksDir)) {
+		for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			for (const direction of ["inbox", "outbox"] as const) {
+				filesToValidate.push({ filePath: mailboxFile(manifest, direction, entry.name), direction });
+			}
+		}
+	}
+	for (const { filePath, direction } of filesToValidate) {
 		if (options.signal?.aborted) break;
-		const filePath = mailboxFile(manifest, direction);
+		if (!fs.existsSync(filePath)) continue;
 		// FIX: Wrap read + optional repair in withFileLockSync so concurrent appends
 		// don't race with the read-modify-write. Mailbox files are capped at 10MB
 		// (MAILBOX_ARCHIVE_THRESHOLD_BYTES), so the per-call memory is bounded.
@@ -1254,7 +1347,9 @@ export function validateMailbox(
 		});
 	}
 	const delivery = readDeliveryState(manifest);
-	const allMessages = readMailbox(manifest);
+	// L-9: delivery-entry coverage now includes task mailbox messages
+	// (readAllMessages walks the global files AND every task mailbox).
+	const allMessages = [...readAllMessages(manifest, "inbox"), ...readAllMessages(manifest, "outbox")];
 	for (const message of allMessages) {
 		if (options.signal?.aborted) break;
 		if (!delivery.messages[message.id])

package/src/state/decision-ledger.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { assertSafePathId } from "../utils/safe-paths.ts";
 import { withFileLockSync } from "./coordination/locks.ts";
@@ -145,6 +146,12 @@ export function appendEntry(runId: string, entry: RolloutEntry): RolloutEntry {
 
 /**
  * Read all entries from the decision ledger.
+ *
+ * P-3 (DR-04 round-7): tolerant parse — a corrupt line (partial write, manual
+ * edit, disk garbage) is SKIPPED, not thrown: one bad tail line must not take
+ * down every reader of the ledger. Unparseable lines are logged ONCE per read
+ * (with the count) via logInternalError; valid lines are preserved. The reader
+ * never throws.
  */
 export function getLedger(runId: string): RolloutEntry[] {
 	assertSafePathId("runId", runId);
@@ -154,15 +161,47 @@ export function getLedger(runId: string): RolloutEntry[] {
 		return [];
 	}
 
-	const content = readFileSync(ledgerPath, "utf-8");
+	let content: string;
+	try {
+		content = readFileSync(ledgerPath, "utf-8");
+	} catch (error) {
+		// P-3: read failure (EACCES, transient EAGAIN, …) — warn and treat as
+		// empty rather than throwing out of a status/summary reader.
+		logInternalError("decision-ledger.getLedger", error, `run=${runId}`, "warn");
+		return [];
+	}
 	if (!content.trim()) {
 		return [];
 	}
 
-	return content
-		.split("\n")
-		.filter((line) => line.trim())
-		.map((line) => JSON.parse(line) as RolloutEntry);
+	return parseLedgerLines(content, runId, "decision-ledger.getLedger");
+}
+
+/**
+ * P-3 (DR-04 round-7): parse JSONL ledger lines tolerantly — valid lines are
+ * kept, unparseable lines are skipped and reported ONCE per call with a count
+ * (plus a bounded preview) so a corrupt tail is visible without flooding.
+ */
+function parseLedgerLines(content: string, runId: string, scope: string): RolloutEntry[] {
+	const entries: RolloutEntry[] = [];
+	const skipped: string[] = [];
+	for (const line of content.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			entries.push(JSON.parse(line) as RolloutEntry);
+		} catch {
+			skipped.push(line.slice(0, 80));
+		}
+	}
+	if (skipped.length > 0) {
+		logInternalError(
+			scope,
+			new Error(`skipped ${skipped.length} unparseable decision-ledger line(s)`),
+			`run=${runId} lines=${JSON.stringify(skipped)}`,
+			"warn",
+		);
+	}
+	return entries;
 }
 
 /**
@@ -181,13 +220,22 @@ function readTailEntries(runId: string, n: number = 10): RolloutEntry[] {
 		return [];
 	}
 
-	const content = readFileSync(ledgerPath, "utf-8");
+	let content: string;
+	try {
+		content = readFileSync(ledgerPath, "utf-8");
+	} catch (error) {
+		// P-3: same tolerant-read contract as getLedger — the append path must
+		// not throw out of the file-lock callback because the tail was unreadable.
+		logInternalError("decision-ledger.readTailEntries", error, `run=${runId}`, "warn");
+		return [];
+	}
 	if (!content.trim()) {
 		return [];
 	}
 
-	const lines = content.split("\n").filter((line) => line.trim());
-	return lines.slice(-n).map((line) => JSON.parse(line) as RolloutEntry);
+	// P-3: skip unparseable lines first, THEN take the tail — otherwise a
+	// single corrupt tail line would slice garbage into the coherence window.
+	return parseLedgerLines(content, runId, "decision-ledger.readTailEntries").slice(-n);
 }
 
 /**

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

@@ -522,7 +522,15 @@ function cursorResultFromEvents(
 	// streaming consumers. No-rotation case: no archives exist → behavior is
 	// byte-identical to before (mergeArchiveTailEvents returns liveEvents).
 	const merged = mergeArchiveTailEvents(readArchiveTailEvents(eventsPath, sinceSeq), filtered);
-	const events = limit !== undefined ? merged.slice(0, limit) : merged;
+	// FS3 (fix): seq-sort before the limit slice. File-order slicing on a
+	// documented non-monotonic log can deliver an early high seq inside the
+	// first `limit` events; nextSeq=max-delivered then permanently skips every
+	// undelivered lower-seq event for paging consumers resuming from nextSeq.
+	// Sort ONLY under a limit: the no-limit path delivers every event (nextSeq
+	// = true max ⇒ nothing skippable) and keeps its historical FILE-order
+	// contract (pinned by event-log-torn-poison.test.ts AC7, U22 Phase 1).
+	const events =
+		limit !== undefined ? [...merged].sort((a, b) => (a.metadata?.seq ?? 0) - (b.metadata?.seq ?? 0)).slice(0, limit) : merged;
 	const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
 	return {
 		events,
@@ -782,7 +790,11 @@ export function readEventsCursor(eventsPath: string, options: EventCursorOptions
 		const filtered = safeItems.filter((event) => (event.metadata?.seq ?? 0) > sinceSeq);
 		const merged = mergeArchiveTailEvents(drainedArchiveEvents, filtered);
 		const limit = positiveInteger(options.limit);
-		const events = limit !== undefined ? merged.slice(0, limit) : merged;
+		// FS3 (fix): seq-sort before the limit slice — see cursorResultFromEvents.
+		// Sort ONLY under a limit (no-limit keeps the historical file-order
+		// contract; nothing is skippable when everything is delivered).
+		const events =
+			limit !== undefined ? [...merged].sort((a, b) => (a.metadata?.seq ?? 0) - (b.metadata?.seq ?? 0)).slice(0, limit) : merged;
 		const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
 		// BR-08: `read.state.byteOffset` sits past the ENTIRE delta read above —
 		// including the events the `limit` slice just dropped. Handing that back