pi-crew 0.11.1 → 0.11.4

package/src/state/coordination/mailbox.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_MAILBOX } from "../../config/defaults.ts";
@@ -467,19 +468,20 @@ function readAllInboxMessages(manifest: TeamRunManifest): MailboxMessage[] {
 // FIND-01: in-process delivery cache to avoid O(N²) re-reads on every append.
 // Keyed by delivery file path; invalidated by mtime check on read + updated on
 // write. Team-runner is single-process so in-process caching is sufficient.
-const deliveryCache = new Map<string, { mtimeMs: number; state: MailboxDeliveryState }>();
+const deliveryCache = new Map<string, { mtimeMs: number; size: number; state: MailboxDeliveryState }>();
 const MAX_DELIVERY_CACHE_ENTRIES = 256;
 // R1 review fix: setDeliveryCacheEntry stores an immutable snapshot (deep
 // copy of `messages`) so callers mutating the returned state cannot corrupt
 // the cache (TOCTOU race), and bounds the map size with FIFO eviction to
 // prevent unbounded growth across runs.
-function setDeliveryCacheEntry(filePath: string, entry: { mtimeMs: number; state: MailboxDeliveryState }): void {
+function setDeliveryCacheEntry(filePath: string, entry: { mtimeMs: number; size: number; state: MailboxDeliveryState }): void {
 	if (deliveryCache.size >= MAX_DELIVERY_CACHE_ENTRIES) {
 		const oldest = deliveryCache.keys().next().value;
 		if (oldest !== undefined) deliveryCache.delete(oldest);
 	}
 	deliveryCache.set(filePath, {
 		mtimeMs: entry.mtimeMs,
+		size: entry.size,
 		state: { ...entry.state, messages: { ...entry.state.messages } },
 	});
 }
@@ -497,7 +499,7 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 		return { messages: {}, updatedAt: new Date().toISOString() };
 	}
 	const cached = deliveryCache.get(filePath);
-	if (cached && cached.mtimeMs === stat.mtimeMs) {
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
 		// R2 review fix: return a copy so callers mutating the result cannot
 		// leak into the cached snapshot (residual TOCTOU: the cache holds the
 		// snapshot until the next write replaces it; without this copy, a
@@ -517,7 +519,7 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 			messages,
 			updatedAt: typeof obj.updatedAt === "string" ? obj.updatedAt : new Date().toISOString(),
 		};
-		setDeliveryCacheEntry(filePath, { mtimeMs: stat.mtimeMs, state });
+		setDeliveryCacheEntry(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, state });
 		return state;
 	} catch (error) {
 		// NEW-R4: a corrupt delivery.json was previously swallowed silently, returning
@@ -543,22 +545,146 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 	}
 }
 
+const MAX_DELIVERY_MESSAGES = 10000;
+
+/**
+ * F09 (RR-016): an `acknowledged` delivery entry is the ONLY durable record
+ * that a message was handled — the inbox line keeps `status: "queued"` forever
+ * (nothing writes the ack back to the message), so `replayPendingMailboxMessages`
+ * keys on the delivery map. The old prune sorted `queued(0) < delivered(1) <
+ * acknowledged(2)` and kept `slice(0, MAX)`, i.e. it evicted ACKNOWLEDGED entries
+ * FIRST — the moment the cap was crossed, an acked message became replayable
+ * again, and it never self-healed (replay only writes "delivered"), so it was
+ * re-delivered on EVERY resume.
+ *
+ * Fix: the prune may only drop an acknowledged entry when the message it refers
+ * to is provably no longer replayable (absent from the whole replayable history:
+ * live inbox files + retained archives — the exact set `replayPendingMailboxMessages`
+ * reads). Non-acknowledged entries keep the previous eviction semantics
+ * (queued → delivered → acknowledged, oldest-inserted first within a tier).
+ *
+ * Acknowledged entries are tiny (`"<id>":"acknowledged"`), but they must not
+ * grow without bound either: a sweep that drops the PROVABLY-dead acks is run
+ * once the ack set is large enough to matter, and at most once per
+ * ACK_SWEEP_MIN_INTERVAL_MS (the sweep reads the mailbox history, so it is
+ * throttled rather than run on every append).
+ */
+const ACK_SWEEP_MIN_ACKS = 1000;
+const ACK_SWEEP_FORCE_ACKS = 5000;
+const ACK_SWEEP_MIN_INTERVAL_MS = 30_000;
+// Bounded FIFO (the asyncAgentReaderCache pattern) so a long-running process
+// cannot accumulate one timestamp per run ever seen.
+const ACK_SWEEP_TIMESTAMP_MAX_ENTRIES = 256;
+const lastAckSweepAt = new Map<string, number>();
+
+function recordAckSweep(filePath: string, at: number): void {
+	if (lastAckSweepAt.has(filePath)) lastAckSweepAt.delete(filePath);
+	lastAckSweepAt.set(filePath, at);
+	while (lastAckSweepAt.size > ACK_SWEEP_TIMESTAMP_MAX_ENTRIES) {
+		const oldest = lastAckSweepAt.keys().next().value;
+		if (oldest === undefined) break;
+		lastAckSweepAt.delete(oldest);
+	}
+}
+
+/** Ids of every message `replayPendingMailboxMessages` could return (live inbox
+ *  files + retained archives, run-level and per-task). Returns `undefined` when
+ *  the history could not be READ (fail-closed, review MAJOR 1): an unreadable
+ *  history must never be conflated with an empty one — the sweep treats an
+ *  empty set as "every ack is dead" and would delete all acknowledged entries,
+ *  replaying already-processed messages (the F09 bug class). */
+function collectReplayableInboxIds(manifest: TeamRunManifest): Set<string> | undefined {
+	const ids = new Set<string>();
+	try {
+		for (const message of readAllInboxMessages(manifest)) ids.add(message.id);
+	} catch (error) {
+		logInternalError("mailbox.collect-replayable-ids", error, `runId=${manifest.runId}`);
+		return undefined;
+	}
+	return ids;
+}
+
+/** Drop acknowledged entries whose message can no longer be replayed. Returns
+ *  the number of entries dropped. Never drops an entry whose message is still
+ *  in the replayable history. FAIL-CLOSED (review MAJOR 1): if the replayable
+ *  history cannot be read, the sweep aborts dropping NOTHING and does not
+ *  consume the throttle window (`recordAckSweep` is only recorded after a
+ *  successful read), so the next prune retries once the FS is readable. */
+function sweepDeadAcknowledgements(manifest: TeamRunManifest, state: MailboxDeliveryState): number {
+	const ackedIds = Object.entries(state.messages)
+		.filter(([, status]) => status === "acknowledged")
+		.map(([id]) => id);
+	if (ackedIds.length === 0) return 0;
+	const filePath = deliveryFile(manifest, true);
+	const now = Date.now();
+	const last = lastAckSweepAt.get(filePath) ?? 0;
+	// The sweep reads the whole replayable history, so it is time-throttled:
+	// at most once per ACK_SWEEP_MIN_INTERVAL_MS below ACK_SWEEP_FORCE_ACKS,
+	// and immediately above it so the ack set cannot grow unbounded.
+	const shouldSweep =
+		ackedIds.length >= ACK_SWEEP_FORCE_ACKS || (ackedIds.length >= ACK_SWEEP_MIN_ACKS && now - last >= ACK_SWEEP_MIN_INTERVAL_MS);
+	if (!shouldSweep) return 0;
+	const replayable = collectReplayableInboxIds(manifest);
+	if (replayable === undefined) return 0; // unreadable history → abort, keep every ack
+	recordAckSweep(filePath, now);
+	let dropped = 0;
+	for (const id of ackedIds) {
+		if (replayable.has(id)) continue;
+		delete state.messages[id];
+		dropped++;
+	}
+	return dropped;
+}
+
+function pruneDeliveryMessages(manifest: TeamRunManifest, state: MailboxDeliveryState): void {
+	const entries = Object.entries(state.messages);
+	const ackedCount = entries.reduce((count, [, status]) => (status === "acknowledged" ? count + 1 : count), 0);
+	if (ackedCount > ACK_SWEEP_MIN_ACKS) sweepDeadAcknowledgements(manifest, state);
+	const remaining = Object.entries(state.messages);
+	if (remaining.length <= MAX_DELIVERY_MESSAGES) return;
+	// Stable sort: within a status tier the previous insertion order (which is
+	// the order entries were first written) is preserved, so the eviction choice
+	// for non-acknowledged entries is unchanged from before this fix.
+	const sorted = [...remaining].sort(([, a], [, b]) => {
+		const order = { queued: 0, delivered: 1, acknowledged: 2 };
+		return (order[a] ?? 3) - (order[b] ?? 3);
+	});
+	const ackedAfterSweep = sorted.filter(([, status]) => status === "acknowledged").length;
+	if (ackedAfterSweep > MAX_DELIVERY_MESSAGES) {
+		// Pathological: more acks than the cap and every one of them still refers
+		// to a replayable message. Correctness (an acked message must never
+		// replay) wins over the memory bound — keep them and make it visible.
+		logInternalError(
+			"mailbox.delivery-ack-over-cap",
+			new Error(`delivery.json holds ${ackedAfterSweep} acknowledged entries for replayable messages (cap ${MAX_DELIVERY_MESSAGES})`),
+			`runId=${manifest.runId}`,
+			"warn",
+		);
+	}
+	const keptIds = new Set<string>();
+	let evictableBudget = Math.max(0, MAX_DELIVERY_MESSAGES - ackedAfterSweep);
+	for (const [id, status] of sorted) {
+		if (status === "acknowledged") {
+			keptIds.add(id);
+			continue;
+		}
+		if (evictableBudget > 0) {
+			keptIds.add(id);
+			evictableBudget--;
+		}
+	}
+	// Filter the ORIGINAL entry order so surviving entries keep their positions.
+	state.messages = Object.fromEntries(remaining.filter(([id]) => keptIds.has(id)));
+}
+
 function writeDeliveryState(
 	manifest: TeamRunManifest,
 	state: MailboxDeliveryState,
 	options?: { durability?: "full" | "best-effort" },
 ): void {
 	ensureRunMailbox(manifest);
-	// Prune oldest entries if capped
-	const MAX_DELIVERY_MESSAGES = 10000;
-	if (Object.keys(state.messages).length > MAX_DELIVERY_MESSAGES) {
-		const sorted = Object.entries(state.messages).sort(([, a], [, b]) => {
-			const order = { queued: 0, delivered: 1, acknowledged: 2 };
-			return (order[a] ?? 3) - (order[b] ?? 3);
-		});
-		const trimmed = sorted.slice(0, MAX_DELIVERY_MESSAGES);
-		state.messages = Object.fromEntries(trimmed);
-	}
+	// Prune oldest entries if capped (F09: acknowledged entries are protected).
+	pruneDeliveryMessages(manifest, state);
 	// F4: mailbox delivery is informational — accept losing the very last write on
 	// a hard crash (the next message will overwrite it on disk). Cheaper fsync on
 	// the hot path; terminal/reply paths still pass full durability below.
@@ -572,7 +698,7 @@ function writeDeliveryState(
 		// setDeliveryCacheEntry stores an immutable snapshot (deep copy of
 		// messages) so subsequent read-modify-write callers mutating the
 		// returned state cannot corrupt the cache.
-		setDeliveryCacheEntry(filePath, { mtimeMs: postStat.mtimeMs, state });
+		setDeliveryCacheEntry(filePath, { mtimeMs: postStat.mtimeMs, size: postStat.size, state });
 	} catch {
 		deliveryCache.delete(filePath);
 	}
@@ -601,7 +727,9 @@ export function appendMailboxMessage(
 	else ensureRunMailbox(manifest);
 	const createdAt = new Date().toISOString();
 	const complete: MailboxMessage = {
-		id: message.id ?? `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+		// RR-021 WI-4.3j: randomUUID instead of Date.now()+Math.random() —
+		// collision-free under the msg_ prefix, no clock-ordering leakage.
+		id: message.id ?? `msg_${randomUUID()}`,
 		runId: manifest.runId,
 		direction: message.direction,
 		from: message.from,
@@ -729,7 +857,9 @@ export async function appendMailboxMessageAsync(
 	else ensureRunMailbox(manifest);
 	const createdAt = new Date().toISOString();
 	const complete: MailboxMessage = {
-		id: message.id ?? `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+		// RR-021 WI-4.3j: randomUUID instead of Date.now()+Math.random() —
+		// collision-free under the msg_ prefix, no clock-ordering leakage.
+		id: message.id ?? `msg_${randomUUID()}`,
 		runId: manifest.runId,
 		direction: message.direction,
 		from: message.from,

package/src/state/crew-init.ts

@@ -13,10 +13,20 @@
  * The `node:path` import is retained as a *fallback* (only used when the
  * binding is healthy). Don't add new dependencies on other pi-crew modules.
  *
+ * TWO sanctioned exceptions (RR-020):
+ *   - `node:os` — a builtin like fs/path, used ONLY inside try/catch so a
+ *     jiti namespace race degrades to "no home/tmp boundary" (the pre-RR-020
+ *     walk) instead of crashing ensureCrewDirectory.
+ *   - `../utils/project-markers.ts` — a zero-import module of plain string
+ *     literals, so it cannot itself suffer the namespace race and it keeps
+ *     this resolver from drifting away from `src/utils/paths.ts`.
+ *
  * See: https://github.com/baphuongna/pi-crew/issues/28
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { PROJECT_DIR_MARKERS, PROJECT_FILE_MARKERS } from "../utils/project-markers.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { updateGitignore } from "./gitignore-manager.ts";
 
@@ -164,29 +174,94 @@ function safeResolve(p: string, pathDep?: typeof path): string {
 }
 
 function findProjectRoot(start: string, pathDep?: typeof path): string | undefined {
-	const dirMarkers = [".git", ".hg", ".svn"];
-	const fileMarkers = ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"];
-	// Use `parseRoot` (inlined above) to avoid `path.parse` for the critical
-	// termination root — fixes the jiti namespace race in issue #28.
-	const root = parseRoot(start);
+	// Marker lists come from src/utils/project-markers.ts (RR-020 Fix 1) so this
+	// resolver can never drift from src/utils/paths.ts:computeRepoRoot again —
+	// the drift resolved `parent/subproject` (.pi) to `parent/.crew` here while
+	// paths.ts resolved the same cwd to `subproject/.pi/teams` (two roots).
+	// The module has NO imports of its own, so it is safe under the jiti
+	// namespace race documented at the top of this file.
+	// RR-020 hardening (cold-verify round 2): the marker arrays are the ONE
+	// critical-path dependency on a static import binding. Under the jiti
+	// namespace race (issue #28) a binding can arrive undefined — degrade to the
+	// narrow `.git`-only probe (findProjectRoot then returns undefined more
+	// often, so computeCrewRoot anchors the crew root at the cwd — the same
+	// fallback paths.ts uses) instead of throwing inside ensureCrewDirectory,
+	// the very function hardened for #28. Mirrors the defensive style of
+	// safeJoin/safeDirname/parseRoot and the lazy updateGitignore import.
+	function markerLists(): { dirs: string[]; files: string[] } {
+		try {
+			if (Array.isArray(PROJECT_DIR_MARKERS) && Array.isArray(PROJECT_FILE_MARKERS)) {
+				return { dirs: PROJECT_DIR_MARKERS as string[], files: PROJECT_FILE_MARKERS as string[] };
+			}
+		} catch {
+			// namespace unavailable — fall through to the narrow probe
+		}
+		return { dirs: [".git"], files: [] };
+	}
+	const markers = markerLists();
+	const hasMarker = (dir: string): boolean =>
+		markers.dirs.some((marker) => fs.existsSync(safeJoin(dir, marker))) ||
+		markers.files.some((marker) => fs.existsSync(safeJoin(dir, marker)));
 	let current = safeResolve(start, pathDep);
+	// RR-020 cold-verify follow-up: match findRepoRoot (paths.ts) which
+	// realpaths the start BEFORE walking, so the boundary comparisons below
+	// compare canonical-to-canonical (macOS /var -> /private/var). Best-effort:
+	// ENOENT keeps the lexical path, exactly like findRepoRoot's fallback.
+	try {
+		current = fs.realpathSync(current);
+	} catch {
+		// keep the lexical resolution
+	}
+	// Use `parseRoot` (inlined above) to avoid `path.parse` for the critical
+	// termination root — fixes the jiti namespace race in issue #28. Computed
+	// from the RESOLVED `current` (post-realpath) so a root-prefix change
+	// through a symlink cannot desync `current !== root` (paths.ts computes
+	// path.parse on the realpath'd start for the same reason).
+	const root = parseRoot(current);
+	// RR-020 cold-verify follow-up (bug-029 parity): home/tmp boundary STOP.
+	// computeRepoRoot (paths.ts) refuses to check markers at $HOME or the temp
+	// root; this walk did not, so once the marker lists were unified onto the
+	// wide set, `$HOME/.pi` (created by userPiRoot()) became a marker HERE — a
+	// MARKERLESS cwd under $HOME resolved crew-init to $HOME (⇒
+	// $HOME/.pi/teams) while projectCrewRoot resolved to <cwd>/.crew: the
+	// two-roots bug Fix 1 was meant to kill, in a new shape. `os` access is
+	// defensive: under the jiti namespace race (issue #28) the binding can be
+	// undefined — degrade to "no boundary" (the pre-RR-020 walk), never crash.
+	let home: string | undefined;
+	let tempRoot: string | undefined;
+	try {
+		home = canonicalBoundary(os.homedir());
+		tempRoot = canonicalBoundary(os.tmpdir());
+	} catch {
+		home = undefined;
+		tempRoot = undefined;
+	}
+	const atBoundary = (dir: string): boolean => (home !== undefined && dir === home) || (tempRoot !== undefined && dir === tempRoot);
 	// Walk up to find project root
 	while (current !== root) {
-		for (const marker of dirMarkers) {
-			if (fs.existsSync(safeJoin(current, marker))) return current;
-		}
-		for (const marker of fileMarkers) {
-			if (fs.existsSync(safeJoin(current, marker))) return current;
-		}
+		// Stop walking before checking markers at home or temp root.
+		if (atBoundary(current)) return undefined;
+		if (hasMarker(current)) return current;
 		const parent = safeDirname(current);
 		if (parent === current) break;
 		current = parent;
 	}
 	// Check root as fallback
-	if (dirMarkers.some((m) => fs.existsSync(safeJoin(root, m)))) return root;
+	if (atBoundary(root)) return undefined;
+	if (hasMarker(root)) return root;
 	return undefined;
 }
 
+/** Canonicalize a boundary dir for comparison with the (realpath'd) walk.
+ *  Best-effort: an unresolvable path stays lexical. */
+function canonicalBoundary(p: string): string {
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+
 /**
  * Compute the crew root directory for a given working directory.
  * Matches src/utils/paths.ts:projectCrewRoot() logic.

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

@@ -114,6 +114,10 @@ export function readEvents(eventsPath: string): TeamEvent[] {
 
 export interface EventCursorOptions {
 	sinceSeq?: number;
+	/** Delivery cap for one read. When `limit` truncates the result, `events` is
+	 *  a PREFIX of everything available — resume from the returned `nextSeq`
+	 *  (never from `nextByteOffset`; see the continuation contract on
+	 *  `readEventsCursor`). */
 	limit?: number;
 	fromByteOffset?: number;
 	/** R-03: generation the caller captured on its previous read. When set, a
@@ -528,6 +532,30 @@ export function clearEventsCursorTailCache(eventsPath?: string): void {
 	cursorTailCache.delete(eventsPath);
 }
 
+/**
+ * Read team events with an optional incremental anchor (`sinceSeq`) plus a
+ * delivery cap (`limit`).
+ *
+ * Continuation / backpressure contract (BR-08):
+ *  - `nextSeq` is the continuation token for events that CARRY `metadata.seq`
+ *    (scheduler-emitted events): the max seq among the events DELIVERED by
+ *    this call — never a watermark past an undelivered event. Resume with
+ *    `{ sinceSeq: nextSeq }` (`>` comparison) to receive the rest.
+ *    LIMITS (cold-verify correction — documented, not fixed here): events
+ *    WITHOUT `metadata.seq` (e.g. the worker progress channel) are filtered
+ *    out of the sinceSeq path entirely, and DUPLICATE seqs cannot be paged
+ *    through by seq. Those cases need the `fromByteOffset` anchor.
+ *  - `total` is the number of events AVAILABLE for this read (after the
+ *    sinceSeq filter, before the `limit` slice) — EXCEPT that the tail cap
+ *    (TAIL_EVENT_CAP) may drop a prefix first, in which case `total` counts
+ *    only the retained suffix.
+ *  - `nextByteOffset` is an OPTIONAL incremental-read accelerator, and is only
+ *    returned when it is a SAFE resume anchor: on the `fromByteOffset` path it
+ *    is OMITTED whenever `limit` truncated the delta, because the underlying
+ *    offset then points past the ENTIRE delta (undelivered tail included) —
+ *    resuming from it would silently skip events. The default (non-byte)
+ *    path never returns it at all.
+ */
 export function readEventsCursor(eventsPath: string, options: EventCursorOptions = {}): EventCursorResult {
 	// Incremental byte-offset path: read only new bytes since last known offset
 	if (options.fromByteOffset !== undefined) {
@@ -558,11 +586,19 @@ export function readEventsCursor(eventsPath: string, options: EventCursorOptions
 		const limit = positiveInteger(options.limit);
 		const events = limit !== undefined ? merged.slice(0, limit) : merged;
 		const returnedMaxSeq = events.reduce((max, event) => Math.max(max, event.metadata?.seq ?? 0), sinceSeq);
+		// BR-08: `newState.byteOffset` sits past the ENTIRE delta read above —
+		// including the events the `limit` slice just dropped. Handing that back
+		// as `nextByteOffset` let a caller resume PAST events it never saw (silent
+		// loss: the delta read then returns an empty tail). Only expose the
+		// accelerator when this call delivered the whole delta; under truncation
+		// the caller must continue from `nextSeq` (see the doc comment on
+		// readEventsCursor).
+		const deliveredWholeDelta = limit === undefined || merged.length <= limit;
 		return {
 			events,
 			nextSeq: returnedMaxSeq,
 			total: merged.length,
-			nextByteOffset: newState.byteOffset,
+			...(deliveredWholeDelta ? { nextByteOffset: newState.byteOffset } : {}),
 			generation: liveGen,
 		};
 	}

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

@@ -169,18 +169,83 @@ export interface CompactionResult {
  * 6. Return compaction stats
  */
 export function compactEventLog(eventsPath: string, config?: Partial<RotationConfig>): CompactionResult | undefined {
-	const prepared = prepareCompaction(eventsPath, config);
-	if (!prepared) return undefined;
-	// FIX: Wrap entire read-compact-write-recover sequence in lock to prevent
-	// event loss during compaction. Without lock, events can be appended between
-	// read and write, lost silently.
+	// 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
+	// (applyCompactionUnlocked), which is what must be atomic w.r.t. appends.
+	//
+	// Why this is safe: appenders take the SAME lock, so an append can only land
+	// before our prepareCompaction read or after our applyCompactionUnlocked
+	// write — never inside the write. applyCompactionUnlocked already re-reads
+	// after the write and splices back any events that arrived in the window
+	// (C2 recovery), so no event is lost; it only becomes slightly more likely to
+	// splice, which is exactly the case it was built for.
+	//
+	// No concurrent-rotator guard is needed: this function is fully SYNCHRONOUS
+	// (prepareCompaction and withEventLogLockSync both block), so two calls on the
+	// same path cannot interleave within a process. An in-flight flag was tried
+	// and removed — it was untestable dead code (mutation survived), and the
+	// synchronous execution already serializes rotators. Cross-process rotators
+	// are serialized by the on-disk lock in withEventLogLockSync.
 	//
 	// NOTE (Round 24 BUG 1): callers ALREADY holding the event-log lock (e.g.
-	// appendEventInsideLock in event-log.ts) must call applyCompactionUnlocked
+	// appendEventInsideLock in event-log.ts) must still call applyCompactionUnlocked
 	// directly — calling compactEventLog from inside the lock deadlocks (the
 	// mkdir lock is not re-entrant → 5s timeout → compaction never ran → the
 	// log grew unbounded until events were silently dropped past 50MB).
-	return withEventLogLockSync(eventsPath, () => applyCompactionUnlocked(eventsPath, prepared));
+	const prepared = prepareCompaction(eventsPath, config);
+	if (!prepared) return undefined;
+	return compactPreparedEventLog(eventsPath, prepared);
+}
+
+/**
+ * US-001 phase 3 — the LOCKED write phase, extracted so the read→write race is
+ * deterministically testable: a caller (test) can run prepareCompaction, append
+ * to the file (simulating another process landing events in the window), then
+ * call this and assert nothing was lost.
+ *
+ * prepareCompaction reads OUTSIDE the lock, so an appender may have added events
+ * between that read and this write. applyCompactionUnlocked writes exactly
+ * `prepared.lines` (the kept window from the snapshot), which would CLOBBER those
+ * newer events; its C2 recovery only re-splices events that were in `kept`, not
+ * 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.
+ */
+export function compactPreparedEventLog(
+	eventsPath: string,
+	prepared: { lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] },
+): CompactionResult | undefined {
+	return withEventLogLockSync(eventsPath, () => {
+		const merged = { ...prepared, lines: prepared.lines + readTailSince(eventsPath, prepared.originalSize) };
+		return applyCompactionUnlocked(eventsPath, merged);
+	});
+}
+
+/**
+ * US-001: return the raw text appended to `filePath` after `offset`, or "" when
+ * nothing was appended / the file was replaced by a smaller one (a foreign
+ * rotation — caller then proceeds without a splice, which is the pre-US-001
+ * behaviour). Must be called while holding the event-log lock.
+ */
+function readTailSince(filePath: string, offset: number): string {
+	try {
+		const size = fs.statSync(filePath).size;
+		if (size <= offset) return "";
+		const fd = fs.openSync(filePath, "r");
+		try {
+			const length = size - offset;
+			const buf = Buffer.alloc(length);
+			const read = fs.readSync(fd, buf, 0, length, offset);
+			const tail = buf.subarray(0, read).toString("utf-8");
+			// Only splice complete lines (a partial trailing write would corrupt JSONL).
+			return tail.endsWith("\n") ? tail : tail.slice(0, tail.lastIndexOf("\n") + 1);
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch {
+		return "";
+	}
 }
 
 /** Round 24 (BUG 1): the lock-free pre-read for compaction. Safe to run

package/src/state/stores/active-run-registry.ts

@@ -61,6 +61,14 @@ function removeStaleRegistryLock(lockPath: string, staleMs: number): boolean {
 }
 
 function withRegistryLock<T>(fn: () => T): T {
+	// US-010 (2026-09-22): sleepSync below is INTENTIONAL — this lock is sync-only
+	// (fn is synchronous, and its callers at :352/:378 are sync). Converting the
+	// backoff to `await sleep` here would repeat the documented v0.9.26
+	// starvation: the sync spinner's sleepSync blocks the event loop while an
+	// in-process async holder's `await`-based release can never run. The lock is
+	// held only for a sub-millisecond read-modify-write and the loop is bounded by
+	// a 10s deadline, so blocking is bounded and rare (contention is cross-process
+	// only). See src/state/event-log/sequence-cache.ts:270 for the same reasoning.
 	const filePath = registryLockPath();
 	const staleMs = 30_000;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -84,7 +92,11 @@ function withRegistryLock<T>(fn: () => T): T {
 			break;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST") throw error;
+			// Windows lock contention surfaces as EPERM/EACCES/EBUSY (not EEXIST) while
+			// another handle holds the lock file open — cross-process contention in
+			// CI (run 36019884258). Treat as contention: bounded retry via the 10s
+			// deadline below, mirroring isLockContention() in coordination/locks.ts.
+			if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES" && code !== "EBUSY") throw error;
 			if (!removeStaleRegistryLock(filePath, staleMs) && Date.now() > deadline)
 				throw new Error("Active-run registry is locked by another operation.");
 			sleepSync(Math.min(250, 25 * 2 ** attempt));