pi-crew 0.9.55 → 0.9.57

package/src/state/{locks.ts → coordination/locks.ts}

@@ -2,11 +2,11 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_LOCKS } from "../config/defaults.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { sleepSync } from "../utils/sleep.ts";
-import { isSymlinkSafePath } from "./atomic-write.ts";
-import type { TeamRunManifest } from "./types.ts";
+import { DEFAULT_LOCKS } from "../../config/defaults.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { sleepSync } from "../../utils/sleep.ts";
+import { isSymlinkSafePath } from "../atomic-write.ts";
+import type { TeamRunManifest } from "../types.ts";
 
 export interface RunLockOptions {
 	staleMs?: number;
@@ -381,15 +381,25 @@ export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunL
 	// append, or even the lock acquisition itself) would race with the lock.
 	const lockFile = `${filePath}.flock`;
 	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
-	// FIX (Round 29): re-entrance guard — mirrors withRunLockSync below.
-	// When the same call stack already holds the file lock (e.g.
-	// registerWorker -> cleanupOrphanWorkers -> readRegistry), the second
-	// acquisition would otherwise read its own freshly-written lock file
-	// (same pid, fresh createdAt), fail the steal check, and deadlock for
-	// the full staleMs window. Strace-confirmed in
-	// .github/issues/pre-existing-2026-06-10/04-orphan-worker-registry-tests.md:75-86.
-	const existingToken = fileLockHeldByUs.get(lockFile);
-	if (existingToken) {
+	// ST-14: re-entrance guard is scoped to the current async context, mirroring
+	// the H-1 fix for withRunLockSync (lockCtx). Previously this used the
+	// process-global fileLockHeldByUs map, so a re-entrance decision in one
+	// async context could leak into another (same bug class as H-1).
+	// fileLockSyncCtx (AsyncLocalStorage) scopes the held set to the current
+	// async context: a call from a DIFFERENT async context sees no held set
+	// and properly serializes against the on-disk lock. True nested calls in
+	// the SAME async context still bypass via fileLockSyncCtx.getStore().
+	if (fileLockSyncCtx.getStore()?.has(lockFile)) {
+		return fn();
+	}
+	// Cross-tier bypass: if withFileLockAsync currently holds the .flock in
+	// THIS process, bypass to avoid a sleepSync deadlock (the sync retry loop
+	// blocks the event loop, starving the async holder). In production this
+	// never fires: child-process mode uses sync-only mailbox operations;
+	// live-session mode uses async-only. Mirrors the symmetric check in
+	// withFileLockAsync. fileLockHeldByUs remains process-global by design —
+	// it tracks actual on-disk holds, not re-entrance.
+	if (fileLockHeldByUs.get(lockFile)) {
 		return fn();
 	}
 	// FIX: Validate the parent directory is not a symlink BEFORE calling mkdirSync.
@@ -422,14 +432,27 @@ export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunL
 		}
 	}
 	if (token === "") throw new Error(`Run '${path.basename(lockFile)}' is locked by another operation.`);
-	fileLockHeldByUs.set(lockFile, token);
-	try {
-		return fn();
-	} finally {
-		// Token-guarded release: don't rm the lock if it has been stolen.
-		fileLockHeldByUs.delete(lockFile);
-		releaseLock(lockFile, token);
-	}
+	// ST-14: enter a new async context carrying the held set, mirroring
+	// withRunLockSync's lockCtx.run pattern. Nested same-context calls see
+	// the held set and bypass (re-entrant); cross-context callers do not.
+	const prevHeld = fileLockSyncCtx.getStore() ?? new Set<string>();
+	const newHeld = new Set(prevHeld);
+	newHeld.add(lockFile);
+	return fileLockSyncCtx.run(newHeld, () => {
+		fileLockHeldByUs.set(lockFile, token);
+		// ST-3-FIX: register the SYNC hold separately so withFileLockAsync's bypass
+		// can detect it WITHOUT seeing async's own holds (which would break
+		// async↔async mutual exclusion).
+		fileSyncLockHeldByUs.add(lockFile);
+		try {
+			return fn();
+		} finally {
+			// Token-guarded release: don't rm the lock if it has been stolen.
+			fileLockHeldByUs.delete(lockFile);
+			fileSyncLockHeldByUs.delete(lockFile);
+			releaseLock(lockFile, token);
+		}
+	});
 }
 
 // H-1: track re-entrant run-lock acquisitions PER ASYNC CONTEXT (not process-global).
@@ -443,16 +466,36 @@ export function withFileLockSync<T>(filePath: string, fn: () => T, options: RunL
 // async context (e.g. handleResume -> executeTeamRun -> executeTeamRunCore) still
 // bypass via lockCtx.getStore(), avoiding the deadlock the bypass was designed for.
 const lockCtx = new AsyncLocalStorage<Set<string>>();
-// Round 29: parallel map for withFileLockSync re-entrance. See the comment
-// at the top of withFileLockSync for the full deadlock mechanism.
+// ST-14: track re-entrant withFileLockSync acquisitions PER ASYNC CONTEXT
+// (not process-global), mirroring the H-1 fix (lockCtx) for withRunLockSync.
+// Previously withFileLockSync used the process-global fileLockHeldByUs map for
+// re-entrance detection, so a re-entrance hit/miss decision in one async context
+// could leak into another (same bug class as H-1). fileLockSyncCtx scopes the
+// held set to the current async context.
+const fileLockSyncCtx = new AsyncLocalStorage<Set<string>>();
+// Round 29: process-global map for cross-tier sync↔async coordination. Set by
+// BOTH withFileLockSync and withFileLockAsync when they hold the on-disk .flock.
+// Consumed by withFileLockSync's bypass (detects when ASYNC holds the .flock, so
+// the sync retry loop doesn't sleepSync-block the event loop and starve the
+// async holder). NOT a re-entrance guard — re-entrance is tracked per async
+// context (fileLockSyncCtx for sync, fileAsyncLockCtx for async).
 const fileLockHeldByUs = new Map<string, string>(); // lockFile -> token
+// ST-3-FIX: process-global set populated ONLY by withFileLockSync when it holds
+// the on-disk .flock. Consumed by withFileLockAsync's bypass to detect SYNC
+// holds (so async skips sleepSync-wait when sync holds, preventing sync↔async
+// deadlock). SEPARATE from fileLockHeldByUs so that a SECOND concurrent ASYNC
+// caller does NOT see the FIRST async caller's hold and bypass — that broke
+// async↔async mutual exclusion (the in-process promise chain + on-disk .flock
+// were both skipped). fileLockHeldByUs is set by BOTH tiers; this set is
+// SYNC-only.
+const fileSyncLockHeldByUs = new Set<string>(); // lockFile (held by sync path)
 
 // --- 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.
+// Two-tier: in-process promise chain (serialize within this process) + on-disk
+// .flock (serialize cross-process via O_EXCL + async retry). The on-disk tier
+// was added in ST-3 to fix message loss when the sync append path
+// (withFileLockSync, also .flock) and the async append path (previously
+// in-process only) ran concurrently across processes on the same mailbox file.
 const fileAsyncLocks = new Map<string, Promise<unknown>>();
 
 // FIND-02 follow-up (P3): re-entrance guard for the async file lock, mirroring
@@ -465,37 +508,74 @@ const fileAsyncLocks = new Map<string, Promise<unknown>>();
 const fileAsyncLockCtx = new AsyncLocalStorage<Set<string>>();
 
 export async function withFileLockAsync<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+	const lockFile = `${filePath}.flock`;
 	// 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)) {
+	// Same semantics as the sync guard in withFileLockSync (fileLockSyncCtx,
+	// ST-14) and the async guard in withRunLock (lockCtx).
+	if (fileAsyncLockCtx.getStore()?.has(lockFile)) {
+		return await fn();
+	}
+	// Cross-tier bypass for SYNC holds: if withFileLockSync currently holds the
+	// .flock in this process, bypass to avoid a sleepSync deadlock (the sync
+	// retry loop blocks the event loop, starving our async holder). In production
+	// this never fires: child-process mode uses sync-only mailbox operations;
+	// live-session mode uses async-only. The bypass is safe for O_APPEND writes
+	// on POSIX (the mailbox append path).
+	// ST-3-FIX: consult fileSyncLockHeldByUs (SYNC-only) — NOT fileLockHeldByUs.
+	// Previously this checked fileLockHeldByUs, which withFileLockAsync ALSO
+	// populates (~line 536), so a SECOND concurrent ASYNC caller for the same
+	// file saw the FIRST async caller's hold and bypassed BOTH the in-process
+	// promise chain AND the on-disk .flock → broke async↔async mutual exclusion.
+	// Checking the SYNC-only set restores async↔async serialization while
+	// preserving sync↔async deadlock prevention.
+	if (fileSyncLockHeldByUs.has(lockFile)) {
 		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();
+	held.add(lockFile);
+	const prev = fileAsyncLocks.get(lockFile) ?? 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 next = prev.then(() =>
+		fileAsyncLockCtx.run(held, async () => {
+			// ST-3: cross-process tier — acquire the on-disk .flock so that a
+			// concurrent process (sync append, reply-rewrite) cannot interleave.
+			// acquireLockWithRetryAsync uses `await sleep` (timer), NOT sleepSync,
+			// so the event loop is not blocked during contention.
+			if (!isSymlinkSafePath(path.dirname(lockFile))) throw new Error("Refusing: parent of lock directory is a symlink");
+			fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+			const token = await acquireLockWithRetryAsync(lockFile, DEFAULT_STALE_MS, "file");
+			// Register in fileLockHeldByUs so a concurrent withFileLockSync in
+			// THIS process detects our hold and bypasses (prevents sleepSync
+			// deadlock). See the bypass check at the top of this function.
+			fileLockHeldByUs.set(lockFile, token);
+			try {
+				return await fn();
+			} finally {
+				fileLockHeldByUs.delete(lockFile);
+				releaseLock(lockFile, token);
+			}
+		}),
+	);
 	const stored = next.then(
 		() => undefined,
 		() => undefined,
 	);
-	fileAsyncLocks.set(filePath, stored);
+	fileAsyncLocks.set(lockFile, 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);
+		if (fileAsyncLocks.get(lockFile) === stored) {
+			fileAsyncLocks.delete(lockFile);
 		}
 	}
 }

package/src/state/{mailbox.ts → coordination/mailbox.ts}

@@ -1,12 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DEFAULT_MAILBOX } from "../config/defaults.ts";
-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 { DEFAULT_MAILBOX } from "../../config/defaults.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactSecrets } from "../../utils/redaction.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { TeamRunManifest } from "../types.ts";
 import { withFileLockAsync, withFileLockSync } from "./locks.ts";
-import type { TeamRunManifest } from "./types.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
 export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
@@ -555,11 +554,18 @@ export function appendMailboxMessage(
 		repliedAt: message.repliedAt,
 		replyContent: message.replyContent,
 	};
-	// H2 fix: wrap append in cross-process lock to prevent interleaving on Windows.
+	// ST-3: collapse to ONE lock namespace (.flock) for ALL mailbox-file
+	// operations — sync append, async append, and full-file rewrite. Previously
+	// this used withEventLogLockSync (.mkdirlock) while async append used an
+	// in-process promise chain (no on-disk artifact) and reply-rewrite used
+	// withFileLockSync (.flock). The three DISJOINT namespaces let concurrent
+	// operations interleave, silently losing messages (especially during the
+	// rotation rename↔recreate window). Now all three use withFileLockSync /
+	// withFileLockAsync — both backed by the same .flock sidecar.
 	// B8: rotation (rename + recreate) also runs INSIDE the lock so it is serialized
 	// with appends — otherwise a concurrent append between rename and recreate can
 	// be truncated to an empty file.
-	withEventLogLockSync(mailboxFile(manifest, complete.direction, complete.taskId), () => {
+	withFileLockSync(mailboxFile(manifest, complete.direction, complete.taskId), () => {
 		fs.appendFileSync(
 			mailboxFile(manifest, complete.direction, complete.taskId),
 			`${JSON.stringify(redactSecrets(complete))}\n`,

package/src/state/{schedule.ts → coordination/schedule.ts}

@@ -9,10 +9,10 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { logInternalError } from "../utils/internal-error.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
 
-import type { ScheduledTask, ScheduleStoreData } from "./types.ts";
+import type { ScheduledTask, ScheduleStoreData } from "../types.ts";
 
 export type DetectedSchedule =
 	| { type: "cron"; normalized: string }

package/src/state/{task-claims.ts → coordination/task-claims.ts}

@@ -1,5 +1,5 @@
 import { randomUUID, timingSafeEqual } from "node:crypto";
-import type { TeamTaskState } from "./types.ts";
+import type { TeamTaskState } from "../types.ts";
 
 export interface TaskClaimState {
 	owner: string;

package/src/state/decision-ledger.ts

@@ -2,7 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } fr
 import { dirname, join } from "node:path";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { assertSafePathId } from "../utils/safe-paths.ts";
-import { withFileLockSync } from "./locks.ts";
+import { withFileLockSync } from "./coordination/locks.ts";
 
 export interface CoherenceMark {
 	matchesPrior: boolean;

package/src/state/{event-log-rotation.ts → event-log/event-log-rotation.ts}

@@ -1,7 +1,112 @@
 import * as fs from "node:fs";
-import { logInternalError } from "../utils/internal-error.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
-import { readEvents, type TeamEvent, withEventLogLockSync } from "./event-log.ts";
+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";
+
+/**
+ * ST-11: Stream a JSONL file line-by-line using a bounded read buffer (8 KB
+ * chunks), invoking `onLine` for each non-empty line. Replaces the previous
+ * `readFileSync` approach that loaded the ENTIRE event log (up to 4 MB /
+ * 50 000 events) into a single string before splitting + JSON.parsing every
+ * line into an array. Memory is now bounded by the chunk size plus the
+ * longest single line, and parsing is interleaved with I/O so the append
+ * lock is held for less wall-clock time.
+ */
+function forEachLineSync(filePath: string, onLine: (line: string) => void): void {
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const chunkSize = 8192;
+		const buf = Buffer.alloc(chunkSize);
+		let leftover = "";
+		let offset = 0;
+		let bytesRead: number;
+		while ((bytesRead = fs.readSync(fd, buf, 0, chunkSize, offset)) > 0) {
+			offset += bytesRead;
+			leftover += buf.subarray(0, bytesRead).toString("utf-8");
+			let nl: number;
+			while ((nl = leftover.indexOf("\n")) >= 0) {
+				const line = leftover.slice(0, nl);
+				leftover = leftover.slice(nl + 1);
+				if (line.length > 0) onLine(line);
+			}
+		}
+		if (leftover.length > 0) {
+			// Trailing line without a final newline.
+			onLine(leftover);
+		}
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+/**
+ * ST-11: Stream the event log and keep only the last `maxKeep` valid (parseable)
+ * events using a fixed-size ring buffer. Bounds memory to O(maxKeep) event
+ * objects regardless of file size — previously the entire file was parsed
+ * into a single array just to `slice(-compactToCount)` it. Corrupt lines
+ * are skipped (matching `readEvents` behaviour). Returns the ordered
+ * last-N events and the total count of valid events seen.
+ */
+function readLastEvents(filePath: string, maxKeep: number): { events: TeamEvent[]; totalCount: number } {
+	if (maxKeep <= 0) {
+		let totalCount = 0;
+		forEachLineSync(filePath, (line) => {
+			try {
+				JSON.parse(line);
+				totalCount++;
+			} catch {
+				/* skip corrupt */
+			}
+		});
+		return { events: [], totalCount };
+	}
+	const ring: TeamEvent[] = new Array(maxKeep);
+	let ringFilled = 0;
+	let writeIdx = 0;
+	let totalCount = 0;
+	forEachLineSync(filePath, (line) => {
+		let event: TeamEvent;
+		try {
+			event = JSON.parse(line) as TeamEvent;
+		} catch {
+			return; // skip corrupt — not counted (matches readEvents)
+		}
+		ring[writeIdx] = event;
+		writeIdx = (writeIdx + 1) % maxKeep;
+		if (ringFilled < maxKeep) ringFilled++;
+		totalCount++;
+	});
+	const events: TeamEvent[] = [];
+	if (ringFilled < maxKeep) {
+		for (let i = 0; i < ringFilled; i++) events.push(ring[i]);
+	} else {
+		for (let i = 0; i < maxKeep; i++) events.push(ring[(writeIdx + i) % maxKeep]);
+	}
+	return { events, totalCount };
+}
+
+/**
+ * ST-11: Stream the event log to count valid events and collect their seq
+ * numbers, without materialising the full event array. Used by
+ * `applyCompactionUnlocked` for the post-write recovery check. Memory is
+ * bounded to the count + seq-set of the (small, post-compaction) file.
+ */
+function countEventsAndSeqs(filePath: string): { count: number; seqs: Set<number> } {
+	const seqs = new Set<number>();
+	let count = 0;
+	forEachLineSync(filePath, (line) => {
+		try {
+			const event = JSON.parse(line) as TeamEvent;
+			count++;
+			const seq = event.metadata?.seq;
+			if (typeof seq === "number") seqs.add(seq);
+		} catch {
+			/* skip corrupt */
+		}
+	});
+	return { count, seqs };
+}
 
 export interface RotationConfig {
 	maxFileSizeBytes: number;
@@ -80,7 +185,13 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
 
 /** Round 24 (BUG 1): the lock-free pre-read for compaction. Safe to run
  * outside the lock (read-only). Returns the compacted lines + stats needed
- * for the write phase. */
+ * for the write phase.
+ *
+ * ST-11: streams the event log line-by-line through a ring buffer instead of
+ * `readEvents` (full readFileSync + JSON.parse of every line into a single
+ * array). Memory is bounded to O(compactToCount) events regardless of file
+ * size, and the append lock is held for less time because parsing is
+ * interleaved with I/O rather than deferred until the entire file is loaded. */
 export function prepareCompaction(
 	eventsPath: string,
 	config?: Partial<RotationConfig>,
@@ -100,10 +211,8 @@ export function prepareCompaction(
 	} catch {
 		return undefined;
 	}
-	const allEvents = readEvents(eventsPath);
-	const originalCount = allEvents.length;
+	const { events: kept, totalCount: originalCount } = readLastEvents(eventsPath, cfg.compactToCount);
 	if (originalCount <= cfg.compactToCount) return undefined;
-	const kept = allEvents.slice(-cfg.compactToCount);
 	const lines = kept.map((e) => JSON.stringify(e)).join("\n") + "\n";
 	return { lines, originalSize, originalCount, kept };
 }
@@ -128,26 +237,21 @@ export function applyCompactionUnlocked(
 		return undefined;
 	}
 	// C2: Re-read to recover any events appended during the compaction window.
-	// Events appended during the compaction window are preserved because they
-	// appear in afterWrite and the condition afterWrite.length >= kept.length is
-	// true, so they are included in the return stats without entering the
-	// recovery branch.
+	// ST-11: stream the post-write file instead of `readEvents` (full
+	// readFileSync + JSON.parse per line into an array). We only need the event
+	// count and the set of seq numbers for the recovery check, so memory is
+	// bounded without materialising every event object.
 	try {
-		const afterWrite = readEvents(eventsPath);
-		// FIX: Check if events were actually lost (afterWrite.length < kept.length)
-		// rather than using appendedDuringWindow >= 0 which is always true.
-		// Also use sequence numbers for comparison instead of JSON.stringify
-		// which is fragile due to key ordering and floating point differences.
-		if (afterWrite.length >= kept.length) {
+		const { count: afterWriteCount, seqs: afterSeqs } = countEventsAndSeqs(eventsPath);
+		if (afterWriteCount >= kept.length) {
 			return {
 				originalSize,
 				compactedSize: fs.statSync(eventsPath).size,
 				eventsRemoved: originalCount - kept.length,
-				eventsKept: kept.length + Math.max(0, afterWrite.length - kept.length),
+				eventsKept: kept.length + Math.max(0, afterWriteCount - kept.length),
 			};
 		}
-		// afterWrite.length < kept.length — events were lost during compaction window.
-		const afterSeqs = new Set(afterWrite.map((e) => e.metadata?.seq).filter((s): s is number => s !== undefined));
+		// afterWriteCount < kept.length — events were lost during compaction window.
 		const missingEvents = kept.filter((e) => e.metadata?.seq === undefined || !afterSeqs.has(e.metadata.seq));
 		let recoveredCount = 0;
 		let recoveryFailed = false;
@@ -242,14 +346,40 @@ function bumpGenerationUnlocked(eventsPath: string): number {
 export function rotateEventLog(eventsPath: string): boolean {
 	if (!fs.existsSync(eventsPath)) return false;
 	// FIX: Wrap rotation in lock to prevent race conditions with concurrent readers.
-	// Order of operations: (1) create new empty file, (2) rename old file to archive.
-	// This ensures eventsPath always exists — a reader never sees a missing file.
+	// Order of operations: (1) rename old live file to archive, (2) create new
+	// empty live file. The rename is atomic (POSIX) so eventsPath is briefly
+	// absent between (1) and (2); readers using readEvents tolerate a missing
+	// file (return []). See rotateEventLogUnlocked for the ST-8 rationale.
 	//
 	// NOTE (Round 24 BUG 1): callers ALREADY holding the lock must call
 	// rotateEventLogUnlocked directly — this locked variant is NOT re-entrant.
 	return withEventLogLockSync(eventsPath, () => rotateEventLogUnlocked(eventsPath));
 }
 
+/** H2 retention: delete `<eventsPath>.*.archive.jsonl` files older than the window so
+ * they don't accumulate forever (mirrors notification/metric-sink rotateOldFiles). */
+const ARCHIVE_RETENTION_DAYS = 7;
+function sweepOldArchives(eventsPath: string, now = Date.now()): void {
+	const dir = path.dirname(eventsPath);
+	const base = path.basename(eventsPath);
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(dir);
+	} catch {
+		return;
+	}
+	const cutoff = now - ARCHIVE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+	for (const name of entries) {
+		if (!name.startsWith(`${base}.`) || !name.endsWith(".archive.jsonl")) continue;
+		const archivePath = path.join(dir, name);
+		try {
+			if (fs.statSync(archivePath).mtimeMs < cutoff) fs.unlinkSync(archivePath);
+		} catch (error) {
+			logInternalError("event-log.archive-sweep", error, `archivePath=${archivePath}`, "debug");
+		}
+	}
+}
+
 /** Round 24 (BUG 1): the lock-free core of rotation. Assumes the caller
  * already holds the event-log lock (or accepts the unlocked race). */
 export function rotateEventLogUnlocked(eventsPath: string): boolean {
@@ -265,19 +395,47 @@ export function rotateEventLogUnlocked(eventsPath: string): boolean {
 			archivePath = `${eventsPath}.${ts}.${collision}.archive.jsonl`;
 			collision++;
 		}
-		// BUGFIX (Round 12 C1): the previous order (atomicWriteFile empty THEN
-		// rename) destroyed ALL events — atomicWriteFile replaces the file
-		// in place, so the rename then moved an EMPTY file to the archive.
-		// FIX: copy current content to the archive first (archive is populated,
-		// original still intact), then truncate the original to empty in place.
-		// copyFileSync + writeFileSync("") ensures eventsPath ALWAYS exists
-		// (no missing-file window for concurrent readers).
-		fs.copyFileSync(eventsPath, archivePath);
-		atomicWriteFile(eventsPath, "");
+		// ST-8: rename+create instead of copy+truncate. The old approach
+		// (copyFileSync + atomicWriteFile("")) had two data-loss windows:
+		//
+		//   1. Copy window: events appended between copyFileSync and the
+		//      atomicWriteFile truncate landed on the OLD inode. After
+		//      atomicWriteFile replaced eventsPath with a new (empty) inode,
+		//      those appends were on an orphaned inode with no path → lost
+		//      forever once the writer's fd closed.
+		//   2. atomicWriteFile replaces the inode → any in-flight writer fd
+		//      (opened before rotation) continues writing to the old inode,
+		//      which is now orphaned.
+		//
+		// rename+create fixes both:
+		//   - rename(2) is atomic: the live log's inode moves to the archive
+		//     path in one step, carrying ALL pre-rotation content. No copy
+		//     window exists — there is nothing to lose between "read" and
+		//     "truncate" because both happen in the single rename syscall.
+		//   - In-flight writer fds that opened the old inode before the rename
+		//     continue writing to it — but it is now the ARCHIVE (it has a
+		//     path), so their appends are preserved, not orphaned. The next
+		//     append (all write paths open per-call) naturally opens the new
+		//     inode at eventsPath.
+		//   - The new live file is created with O_CREAT|O_EXCL ("wx"): if a
+		//     concurrent writer (different lock class — sync `.mkdirlock` vs
+		//     async `.alock` are separate) already recreated the file between
+		//     our rename and here, we leave their data intact (EEXIST → skip).
+		fs.renameSync(eventsPath, archivePath);
+		try {
+			const fd = fs.openSync(eventsPath, "wx", 0o644);
+			fs.closeSync(fd);
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+			// A concurrent writer recreated the file — their data is preserved.
+		}
 		// R-03: bump the generation sidecar so byte-offset cursor readers
 		// detect the truncation and reset (re-read from offset 0 of the new
 		// file), instead of reading past EOF and missing post-rotation events.
 		bumpGenerationUnlocked(eventsPath);
+		// H2: retention — sweep archive files older than the window so they don't
+		// accumulate forever (mirrors notification/metric-sink rotateOldFiles).
+		sweepOldArchives(eventsPath);
 		return true;
 	} catch (error) {
 		logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);