pi-crew 0.11.21 → 0.11.22

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/event-log-rotation.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { atomicWriteFile } from "../atomic-write.ts";
-import { type TeamEvent, withEventLogLockSync } from "./event-log.ts";
+import { type TeamEvent, withEventLogAppendLockSync, withEventLogLockSync } from "./event-log.ts";
 import { poisonMarkerPath } from "./poison-marker.ts";
 
 /**
@@ -169,7 +169,11 @@ export interface CompactionResult {
  * 5. If events were lost, append them
  * 6. Return compaction stats
  */
-export function compactEventLog(eventsPath: string, config?: Partial<RotationConfig>): CompactionResult | undefined {
+export function compactEventLog(
+	eventsPath: string,
+	config?: Partial<RotationConfig>,
+	options?: CompactionLockOptions,
+): CompactionResult | undefined {
 	// US-001 (2026-09-22): lock-scope reduction. The expensive part is the READ +
 	// parse of the whole log (prepareCompaction). It is read-only, so it does NOT
 	// need the append lock: hold the lock ONLY for the write+recover phase
@@ -196,7 +200,15 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
 	// log grew unbounded until events were silently dropped past 50MB).
 	const prepared = prepareCompaction(eventsPath, config);
 	if (!prepared) return undefined;
-	return compactPreparedEventLog(eventsPath, prepared);
+	return compactPreparedEventLog(eventsPath, prepared, options);
+}
+
+/** Options for the locked write phase of compaction. `lock` is forwarded to
+ * `withEventLogAppendLockSync` (and transitively `withEventLogLockSync`) so
+ * callers/tests can bound the wait — the defaults (5s timeout / 10s stale)
+ * mirror both existing lock families. */
+export interface CompactionLockOptions {
+	lock?: { timeoutMs?: number; staleMs?: number };
 }
 
 /**
@@ -212,15 +224,81 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
  * ones it never saw. So under the lock we read the bytes appended after the
  * snapshot offset and append them to the write. Appenders hold the same lock,
  * so this read is a complete tail snapshot.
+ *
+ * R4-2 (DR-02 Wave 2, 2026-10-15): the write phase now ADDITIONALLY acquires the
+ * async family's `.alock` (sync-mode, via `withEventLogAppendLockSync`) BEFORE
+ * `readTailSince`/the `atomicWriteFile` rename, releasing it only after the C2
+ * recovery check completes. Rationale: async-family appends hold `.alock`
+ * ACROSS await gaps (`open(eventsPath, "a")` → `appendFile`); running the rename
+ * under `.mkdirlock` alone let it interleave with that gap, orphaning the
+ * appender's fd — its event landed on the old inode and was silently lost (C2
+ * only re-splices the `kept` window). Holding `.alock` across the whole write
+ * phase excludes in-flight async appends cross-process (same on-disk lock dir
+ * + pid-file protocol). Lock order stays strictly `.mkdirlock` → `.alock` (the
+ * async family never takes `.mkdirlock`), so no deadlock. NOT archive-style by
+ * lead decision: rotation's rename-to-archive already preserves in-flight fds
+ * (ST-8), so only compaction's inode-replacing write needed the guard.
  */
 export function compactPreparedEventLog(
 	eventsPath: string,
 	prepared: { lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] },
+	options?: CompactionLockOptions,
 ): CompactionResult | undefined {
-	return withEventLogLockSync(eventsPath, () => {
+	// R7-2 (DR-04, 2026-10-16): the write phase is now `applyCompactionAppendGuarded`
+	// (below) — `.alock` nested inside the `.mkdirlock` held here, plus the
+	// mandatory `readTailSince` splice. This wrapper keeps the historical
+	// locked entry point (public API + tests) with identical semantics.
+	return withEventLogLockSync(eventsPath, () => applyCompactionAppendGuarded(eventsPath, prepared, options), options?.lock);
+}
+
+/** R7-2 (DR-04, 2026-10-16): options for `applyCompactionAppendGuarded`.
+ * `lock` is forwarded to `withEventLogAppendLockSync` so callers/tests can
+ * bound the wait; `holdsAppendLock` declares the caller's lock state (see the
+ * helper docblock). */
+export interface ApplyCompactionGuardOptions extends CompactionLockOptions {
+	/** Pass `true` ONLY when the caller ALREADY holds the async family's
+	 * `.alock` (i.e. the guarded apply runs inside `withEventLogLockAsync`).
+	 * The on-disk lock is NOT re-entrant — re-acquiring our own `.alock` in
+	 * sync mode can only end in the bounded timeout (sleepSync starves the
+	 * very in-process holder that must release it). With `true` the helper
+	 * only tail-merges; with `false`/omitted it acquires `.alock` itself. */
+	holdsAppendLock?: boolean;
+}
+
+/**
+ * R7-2 (DR-04, 2026-10-16): the guarded write phase for INLINE compaction
+ * call sites (the overflow/rotation-tick paths inside event-log.ts) that
+ * previously called `prepareCompaction` + `applyCompactionUnlocked` bare —
+ * no `.alock` and no tail-merge, so the inode-replacing write could interleave
+ * with an in-flight async-family append parked between `open()` and
+ * `appendFile()` (its fd kept pointing at the renamed-away inode → silent
+ * loss; C2 recovery only re-splices the `kept` window), and sync-family bytes
+ * appended between the prepare-read and the write were clobbered.
+ *
+ * Contract:
+ *  - ALWAYS merges `readTailSince(eventsPath, prepared.originalSize)` into
+ *    `prepared.lines` before `applyCompactionUnlocked` — sync-family appenders
+ *    never hold `.alock`, so they can land in the prepare→apply window even
+ *    while an async-family caller holds `.alock`; the splice rescues them.
+ *  - `opts.holdsAppendLock === true` (caller is inside `withEventLogLockAsync`):
+ *    tail-merge ONLY — never re-acquire `.alock` (non-reentrant → self-timeout).
+ *  - `opts.holdsAppendLock` false/omitted (caller holds `.mkdirlock` — sync
+ *    family — or no lock): acquire `.alock` in sync mode nested inside the
+ *    held `.mkdirlock`, per the R4-2 lock order (`.mkdirlock` → `.alock`; the
+ *    async family never takes `.mkdirlock`, so no inversion). NEVER call this
+ *    with `false` while `.alock` is already held by this process.
+ */
+export function applyCompactionAppendGuarded(
+	eventsPath: string,
+	prepared: { lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] },
+	options?: ApplyCompactionGuardOptions,
+): CompactionResult | undefined {
+	const applyWithTailMerge = (): CompactionResult | undefined => {
 		const merged = { ...prepared, lines: prepared.lines + readTailSince(eventsPath, prepared.originalSize) };
 		return applyCompactionUnlocked(eventsPath, merged);
-	});
+	};
+	if (options?.holdsAppendLock) return applyWithTailMerge();
+	return withEventLogAppendLockSync(eventsPath, applyWithTailMerge, options?.lock);
 }
 
 /**