pi-crew 0.7.4 → 0.7.6

package/src/runtime/stale-reconciler.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { errors } from "../errors.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { checkProcessLiveness } from "./process-status.ts";
 import { saveRunManifest } from "../state/state-store.ts";
@@ -272,6 +273,23 @@ function getRunningTaskStaleness(
 /**
  * Repair a stale run by marking it as failed and cancelling running tasks.
  */
+/**
+ * E3/E1 (Round 15): Build a human-actionable error string for a stale-reconciled
+ * task. Explains WHY the run was marked stale (the detected reason) and gives
+ * concrete remediation, instead of the bare 'Stale run reconciled: <reason>'.
+ * Now returns a structured CrewError (E012) so callers also get a machine-
+ * readable code + help hint; `.message` carries the same rich text as before.
+ */
+function buildStaleReconcileError(task: TeamTaskState, reason: string): Error {
+	const heartbeatAgeSeconds = task.heartbeat?.lastSeenAt ? Math.round((Date.now() - new Date(task.heartbeat.lastSeenAt).getTime()) / 1000) : undefined;
+	return errors.runStale(reason, heartbeatAgeSeconds);
+}
+
+/** @deprecated use buildStaleReconcileError (returns a structured CrewError). Kept for any external callers. */
+function formatStaleReconcileError(task: TeamTaskState, reason: string): string {
+	return buildStaleReconcileError(task, reason).message;
+}
+
 function repairStaleRun(
 	manifest: TeamRunManifest,
 	tasks: TeamTaskState[],
@@ -288,7 +306,8 @@ function repairStaleRun(
 				...task,
 				status: "cancelled" as const,
 				finishedAt: now,
-				error: `Stale run reconciled: ${reason}`,
+				// E3/E1 (Round 15): structured CrewError (E012) with code + help hint.
+				error: buildStaleReconcileError(task, reason).message,
 			};
 		}
 		return task;
@@ -466,9 +485,13 @@ export interface OrphanReconcileResult {
  */
 export function reconcileOrphanedTempWorkspaces(
 	now = Date.now(),
-	options?: { cleanupOrphanedTempDirs?: boolean },
+	options?: { cleanupOrphanedTempDirs?: boolean; tmpDir?: string; scanBatchSize?: number },
 ): OrphanReconcileResult {
-	const tmpDir = getSafeTempDir();
+	// Injectable tmpDir + scanBatchSize for deterministic unit testing
+	// (Round 19: tests must not depend on global /tmp cleanliness; the
+	// production ORPHAN_TEMP_SCAN_BATCH_SIZE cap could exclude a test's dir
+	// when leftover dirs accumulate). Defaults remain os.tmpdir() + the cap.
+	const tmpDir = options?.tmpDir ?? getSafeTempDir();
 	if (!tmpDir) return { repaired: 0, cleanedDirs: 0 };
 	let repaired = 0;
 	let cleanedDirs = 0;
@@ -477,10 +500,11 @@ export function reconcileOrphanedTempWorkspaces(
 		// Sort for deterministic order; cap to ORPHAN_TEMP_SCAN_BATCH_SIZE per
 		// tick to avoid main-thread stalls when /tmp has thousands of
 		// pi-crew-* dirs from past interrupted test runs.
+		const scanBatch = options?.scanBatchSize ?? ORPHAN_TEMP_SCAN_BATCH_SIZE;
 		const candidates = entries
 			.filter((e) => e.isDirectory() && e.name.startsWith("pi-crew-"))
 			.sort((a, b) => a.name.localeCompare(b.name))
-			.slice(0, ORPHAN_TEMP_SCAN_BATCH_SIZE);
+			.slice(0, scanBatch);
 		for (const entry of candidates) {
 			if (!entry.isDirectory() || !entry.name.startsWith("pi-crew-"))
 				continue;

package/src/runtime/task-runner.ts

@@ -11,6 +11,7 @@ import type {
 	VerificationEvidence,
 } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { errors } from "../errors.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEventAsync, appendEventFireAndForget } from "../state/event-log.ts";
 import { saveRunManifest } from "../state/state-store.ts";
@@ -288,7 +289,19 @@ export async function runTeamTask(
 				});
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
-				throw new Error(`preStepScript failed: ${input.step.preStepScript}: ${msg}`);
+				const exitCode = (err as NodeJS.ErrnoException & { status?: number }).status;
+				// E1 (Round 15): structured CrewError with code E009 + help hint,
+				// instead of a raw Error. Surfaces the script path, exit code, and stderr.
+				// Round 21 (E4): if preStepOptional is set, a failing hook is NON-FATAL.
+				// Log a warning + emit a 'warning' event, then proceed without the
+				// pre-step output rather than aborting the task (advisory hooks).
+				if (input.step.preStepOptional) {
+					const warnMsg = `[preStepOptional] pre-step hook '${input.step.preStepScript}' failed (exit ${exitCode ?? "?"}) but preStepOptional=true; continuing without its output.`;
+					try { appendEventFireAndForget(manifest.eventsPath, { type: "hook.pre_step_optional_failed", runId: manifest.runId, taskId: task.id, message: warnMsg, data: { script: input.step.preStepScript, exitCode: exitCode ?? null } }); } catch { /* best-effort event log */ }
+					preStepOutput = undefined;
+				} else {
+					throw errors.preStepFailed(input.step.preStepScript, exitCode, msg);
+				}
 			}
 		}
 
@@ -383,6 +396,7 @@ export async function runTeamTask(
 			let lastAgentRecordPersistedAt = 0;
 			let lastHeartbeatPersistedAt = 0;
 			let lastRunProgressPersistedAt = 0;
+			let lastTaskProgressPersistedAt = 0;
 			let lastRunProgressSummary: ProgressEventSummary | undefined;
 			const persistHeartbeat = (force = false): void => {
 				const now = Date.now();
@@ -573,26 +587,23 @@ export async function runTeamTask(
 								const eventLine = typeof event === "object" && !Array.isArray(event) ? JSON.stringify(event) : String(event);
 								fs.appendFileSync(bgLogPath, `${eventLine}\n`);
 							}
-							// Apply agentProgress update first, then persist, then update in-memory array.
-							// This ensures disk state is always >= in-memory state, preventing
-							// fresher in-memory state from being lost on crash.
-							tasks = persistSingleTaskUpdate(manifest, tasks, {
-								...task,
-								agentProgress: applyAgentProgressEvent(
-									task.agentProgress ?? emptyCrewAgentProgress(),
-									event,
-									task.startedAt,
-								),
-							});
-							task = {
-								...task,
-								agentProgress: applyAgentProgressEvent(
-									task.agentProgress ?? emptyCrewAgentProgress(),
-									event,
-									task.startedAt,
-								),
-							};
+							// Always keep in-memory agentProgress fresh (cheap) so the UI/events see
+							// the latest progress, but THROTTLE the disk persist. Previously this
+							// did a full locked read-parse-write of tasks.json on EVERY child JSON
+							// event — a 200-event task produced 200 such cycles (Round 15 P1).
+							// Final state is force-flushed on task completion (persistHeartbeat(true)).
+							const nextProgress = applyAgentProgressEvent(
+								task.agentProgress ?? emptyCrewAgentProgress(),
+								event,
+								task.startedAt,
+							);
+							task = { ...task, agentProgress: nextProgress };
 							tasks = updateTask(tasks, task);
+							const progressNow = Date.now();
+							if (progressNow - lastTaskProgressPersistedAt >= 500) {
+								tasks = persistSingleTaskUpdate(manifest, tasks, task);
+								lastTaskProgressPersistedAt = progressNow;
+							}
 							// Bridge event to UI event bus for near-instant updates
 							const bridgeEvent = bridgeEventFromJsonEvent(
 								manifest.runId,
@@ -701,6 +712,15 @@ export async function runTeamTask(
 						? childResult.stderr ||
 							`Child Pi exited with ${childResult.exitCode}`
 						: undefined);
+				// E1/E7 (Round 15): when the child timed out, surface a structured
+				// CrewError (E007) so users get a code + actionable help hint instead
+				// of a bare 'no new output for N ms'. We keep .message as the task error.
+				if (childResult.exitStatus?.timedOut) {
+					error = errors.childTimeout({
+						taskId: task.id,
+						stderr: childResult.stderr,
+					}).message;
+				}
 				persistHeartbeat(true);
 				persistChildProgress({ type: "attempt_finished" }, true);
 				const attempt: ModelAttemptSummary = {
@@ -724,6 +744,16 @@ export async function runTeamTask(
 				if (!nextModel || !isRetryableModelFailure(error)) break;
 				logs.push(formatModelAttemptNote(attempt, nextModel), "");
 			}
+			// E2 (Round 15): when the fallback chain was used and STILL failed, surface
+			// that explicitly. Without this the task error only shows the last
+			// attempt's raw failure, so users can't tell whether to fix an API key,
+			// upgrade a plan, or change the model config. Include the chain tried +
+			// the final reason.
+			if (error && modelAttempts.length > 1) {
+				// E2/E1 (Round 15): structured CrewError (E008). Build via the factory so
+				// the error carries a code + help hint; keep its .message as the task error.
+				error = errors.modelExhausted(modelAttempts.map((a) => a.model), error).message;
+			}
 			// NEW-8 fix: register all attempt transcripts as artifacts, not just the used one.
 			// Earlier failed attempts' transcripts exist on disk but were invisible to the artifact system.
 			const successfulAttemptIndex = modelAttempts.findIndex(

package/src/runtime/team-runner.ts

@@ -455,6 +455,15 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 
 		return result;
 	} catch (error) {
+		// Round 27 (BUG 1): the success path calls stopTeamHeartbeat() but this
+			// catch path did NOT. The team heartbeat is a non-unref'd setInterval
+			// (30s) that deliberately keeps the event loop alive — without this
+			// call, a failed team run leaves the interval firing forever and the
+			// foreground pi process hangs (never returns to the prompt); in
+			// background-runner mode the worker never exits. clearInterval is
+			// idempotent so a double-call (if this runs after the success path)
+			// is harmless.
+		stopTeamHeartbeat();
 		// P1: Catch unhandled errors — ensure manifest/tasks/agents are terminal so they don't stay "running" forever.
 		const message = error instanceof Error ? error.message : String(error);
 		// Reload manifest with lock to avoid stale data overwriting concurrent writes.
@@ -922,8 +931,16 @@ tasks = mergeResult.resultTasks;
 		await saveRunTasksAsync(finalManifest, tasks);
 	});
 	manifest = finalManifest;
-	// Save health snapshot on run completion
-	const crewRoot = path.dirname(path.dirname(finalManifest.stateRoot));
+	// Save health snapshot on run completion.
+	// BUG A (pts/2 hang investigation 2026-06-16): stateRoot = `<crewRoot>/state/runs/<runId>`,
+	// so the crew root is THREE dirnames up, not two. Two dirnames gave `<crewRoot>/state`
+	// (the state dir), and HealthStore then joined HEALTH_DIR (`.crew/state/health`)
+	// onto it → `<crewRoot>/state/.crew/state/health` — a double-joined BOGUS path.
+	// That wrote health snapshots to a nonexistent subtree (silently breaking the
+	// health feature) AND created junk dirs that the recursive state watcher then
+	// attached extra inotify watches to. Fix: compute the real crew root (3 up)
+	// and make HEALTH_DIR relative to it.
+	const crewRoot = path.dirname(path.dirname(path.dirname(finalManifest.stateRoot)));
 	const healthStore = new HealthStore(crewRoot);
 	healthStore.saveSnapshot({
 		runId: finalManifest.runId,

package/src/runtime/verification-gates.ts

@@ -57,7 +57,12 @@ export const CARGO_RUST_GATES: Array<{ name: string; command: string; critical:
  * Execute a single command and capture output.
  */
 /** Characters/patterns that indicate dangerous shell metacharacters. */
-const DANGEROUS_SHELL_PATTERNS = /(?:;|&&|\|\||\$\(|`|\$\{|\b(eval|exec)\b|>>|<[^&])/;
+// 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
+// secrets into captured gate output, e.g. `echo $ANTHROPIC_API_KEY`).
+// $+word-char is blocked; special vars like $?/$$/$! are left alone. Built-in
+// gates use only `2>&1` (no $VAR), so this does not break them.
+const DANGEROUS_SHELL_PATTERNS = /(?:;|&&|\|\||\$\(|`|\$\{|\$\w|\b(eval|exec)\b|>>|<[^^&]|[\r\n])/;
 // Note: single `>` is NOT blocked here because `2>&1` is a safe redirect used by built-in gates.
 // `>>` (append) is still blocked. `<` without `&` (input redirect) is still blocked.
 
@@ -66,7 +71,22 @@ const DANGEROUS_SHELL_PATTERNS = /(?:;|&&|\|\||\$\(|`|\$\{|\b(eval|exec)\b|>>|<[
  * Rejects commands with shell metacharacters that could enable injection.
  * Allows: pipes (|), redirection of stderr (2>&1), and basic npm/cargo/npx commands.
  */
+/** @internal — exported for injection-guard unit testing (Round 25). */
+export function __test__validateGateCommand(command: string): void {
+	validateGateCommand(command);
+}
+
 function validateGateCommand(command: string): void {
+	// Round 25 (VULN-3): check the ORIGINAL command for raw newlines BEFORE
+	// normalization. The regex below runs on the NORMALIZED command (which
+	// collapses \s+ incl. newlines to a single space), so a newline would be
+	// hidden from it - but `sh -c` treats a raw newline as a command
+	// separator, enabling injection (e.g. `npm test\nrm -rf x`).
+	if (/[\r\n]/.test(command)) {
+		throw new Error(
+			`Security: verification gate command rejected (raw newline - potential command injection): ${JSON.stringify(command)}`,
+		);
+	}
 	const normalized = command
 		.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')  // ANSI escape sequences
 		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '')  // control chars

package/src/runtime/workspace-tree.ts

@@ -252,7 +252,7 @@ function applyLineCap(
 	return { lines: kept, elided: removable.length };
 }
 
-// ── Public API ─────────────────────────────────────────────────────────
+// ── Public API ────────────────────────────────────────────────────────
 
 const emptyResult = (rootPath: string): WorkspaceTree => ({
 	rootPath,
@@ -261,11 +261,35 @@ const emptyResult = (rootPath: string): WorkspaceTree => ({
 	totalLines: 0,
 });
 
+/**
+ * Per-cwd TTL cache for the rendered workspace tree. Workers in the same run
+ * share a cwd, so the recursive walk was previously repeated once per task
+ * (Round 15 P4). The tree is informational context for the worker; short-lived
+ * staleness is acceptable, so a 30s TTL is safe and keeps prompts fresh during
+ * long active runs while eliminating redundant walks.
+ */
+const TREE_CACHE_TTL_MS = 30_000;
+interface CachedTree {
+	tree: WorkspaceTree;
+	expiresAt: number;
+}
+const treeCache = new Map<string, CachedTree>();
+
+function treeCacheKey(cwd: string, options?: WorkspaceTreeOptions): string {
+	// Cache is keyed on the inputs that affect the walk output.
+	return `${path.resolve(cwd)}|${options?.maxDepth ?? ""}|${options?.dirLimit ?? ""}|${options?.lineCap ?? ""}`;
+}
+
 export async function buildWorkspaceTree(
 	cwd: string,
 	options?: WorkspaceTreeOptions,
 ): Promise<WorkspaceTree> {
 	const rootPath = path.resolve(cwd);
+	const cacheKey = treeCacheKey(cwd, options);
+	const cached = treeCache.get(cacheKey);
+	if (cached && cached.expiresAt > Date.now()) {
+		return cached.tree;
+	}
 	try {
 		const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
 		const dirLimit = options?.dirLimit ?? DEFAULT_DIR_LIMIT;
@@ -286,12 +310,14 @@ export async function buildWorkspaceTree(
 		const { lines: capped, elided } = applyLineCap(lines, lineCap);
 		const rendered = capped.map((l) => l.text).join("\n");
 
-		return {
+		const result: WorkspaceTree = {
 			rootPath,
 			rendered,
 			truncated: dirTruncated || elided > 0,
 			totalLines: capped.length,
 		};
+		treeCache.set(cacheKey, { tree: result, expiresAt: Date.now() + TREE_CACHE_TTL_MS });
+		return result;
 	} catch {
 		return emptyResult(rootPath);
 	}

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

@@ -135,6 +135,13 @@ export const TeamToolParams = Type.Object({
 			description: "Run in background when execution support is enabled.",
 		}),
 	),
+	details: Type.Optional(
+		Type.Boolean({
+			default: true,
+			description:
+				"(status) Output detail level. true (default) = full status (task graph, agents, effectiveness, events). false = compact summary (status, goal, task counts, and only failed/attention task errors) for quick checks.",
+		}),
+	),
 	workspaceMode: Type.Optional(
 		Type.Union([Type.Literal("single"), Type.Literal("worktree")], {
 			description:
@@ -318,6 +325,8 @@ export interface TeamToolParamsValue {
 	taskId?: string;
 	message?: string;
 	async?: boolean;
+	/** (status) Output detail level. false = compact summary. Default: true (full). */
+	details?: boolean;
 	workspaceMode?: "single" | "worktree";
 	context?: "fresh" | "fork";
 	cwd?: string;

package/src/state/blob-store.ts

@@ -190,16 +190,18 @@ export function writeBlob(artifactsRoot: string, input: {
 			metadataWritten = true;
 		});
 	} catch (error) {
-		// Issue 4 fix: Clean up orphaned blob if metadata write fails.
-		// If metadata write fails (e.g., concurrent conflict), the blob content
-		// is orphaned since no metadata references it. Clean it up to reclaim space.
-		// Issue 8 fix: Do NOT delete blob content on metadata failure.
-		// If metadata write fails due to concurrent conflict (different values),
-		// the blob content is still valid. Another process has written metadata
-		// referencing this blob - deleting the blob would orphan their metadata.
-		// The caller can retry the metadata write if needed.
-		// However, if metadata was never written (metadataWritten === false),
-		// the blob is orphaned and should be cleaned up.
+		// Round 24 (BUG 4 note): the catch block previously checked
+		// `if (!blobContentWritten)` — the WRONG variable (the local comment said
+		// `metadataWritten === false`). For a CONTENT-ADDRESSED store the blob path
+		// is the content hash, so the blob may be referenced by another process's
+		// metadata even when OUR metadata write failed (e.g. a concurrent conflict
+		// where the peer already wrote metadata for the same hash). Deleting it
+		// would orphan their metadata. The safe behavior is therefore to NEVER
+		// delete on a metadata write failure and let the periodic
+		// cleanupOrphanedBlobs() reclaim genuinely-orphaned blobs. The guard below
+		// only removes a blob when its CONTENT was never written (a stray/partial
+		// file from a failed content write) — which is the only unambiguously-safe
+		// case to clean up here.
 		if (!blobContentWritten) {
 			try { fs.rmSync(blobPath, { force: true }); } catch { /* best-effort */ }
 		}

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

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import { readEvents } from "./event-log.ts";
+import { readEvents, type TeamEvent } from "./event-log.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { withEventLogLockSync } from "./event-log.ts";
@@ -65,6 +65,25 @@ 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.
+	//
+	// NOTE (Round 24 BUG 1): callers ALREADY holding the event-log lock (e.g.
+	// appendEventInsideLock in event-log.ts) must 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));
+}
+
+/** 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. */
+export function prepareCompaction(eventsPath: string, config?: Partial<RotationConfig>):
+	{ lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] } | undefined {
 	if (!fs.existsSync(eventsPath)) return undefined;
 	const cfg = resolveConfig(config);
 	let originalSize: number;
@@ -74,79 +93,73 @@ export function compactEventLog(eventsPath: string, config?: Partial<RotationCon
 	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 };
+}
 
-	// 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.
-	return withEventLogLockSync(eventsPath, () => {
-		try {
-			atomicWriteFile(eventsPath, lines);
-		} catch (err) {
-			// Concurrent write conflict — skip compaction this cycle
-			logInternalError("event-log-rotation.compact", err, `eventsPath=${eventsPath}`);
-			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.
-		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) {
-				// No data loss — either events were appended and kept, or nothing happened.
-				return {
-					originalSize,
-					compactedSize: fs.statSync(eventsPath).size,
-					eventsRemoved: originalCount - kept.length,
-					eventsKept: kept.length + Math.max(0, afterWrite.length - kept.length),
-				};
-			}
-			// afterWrite.length < kept.length — events were lost during compaction window.
-			// Find missing events and re-append them.
-			// FIX: Use sequence numbers for comparison instead of JSON.stringify.
-			const afterSeqs = new Set(afterWrite.map((e) => e.metadata?.seq).filter((s): s is number => s !== undefined));
-			const missingEvents = kept.filter((e) => e.metadata?.seq === undefined || !afterSeqs.has(e.metadata.seq));
-			let recoveredCount = 0;
-			let recoveryFailed = false;
-			if (missingEvents.length > 0) {
-				// BUGFIX (Round 12 C2): the previous loop called atomicWriteFile PER event,
-				// which REPLACES the entire file each iteration — destroying the
-				// compacted log and all previously-recovered events, leaving only the
-				// LAST missing event. FIX: accumulate all missing events into one
-				// string and append in a single write (appendFileSync appends without
-				// destroying existing content).
-				const recoveryLines = missingEvents.map((e) => JSON.stringify(e) + "\n").join("");
-				try {
-					fs.appendFileSync(eventsPath, recoveryLines);
-					recoveredCount = missingEvents.length;
-				} catch (err) {
-					recoveryFailed = true;
-					logInternalError("event-log-rotation.recovery", err, `eventsPath=${eventsPath} lostEvents=${missingEvents.length}`);
-				}
-			}
+/** Round 24 (BUG 1): the write+recover phase of compaction. Assumes the
+ * caller ALREADY holds the event-log lock (or accepts the unlocked race). */
+export function applyCompactionUnlocked(
+	eventsPath: string,
+	prepared: { lines: string; originalSize: number; originalCount: number; kept: TeamEvent[] },
+): CompactionResult | undefined {
+	const { lines, originalSize, originalCount, kept } = prepared;
+	try {
+		atomicWriteFile(eventsPath, lines);
+	} catch (err) {
+		// Concurrent write conflict — skip compaction this cycle
+		logInternalError("event-log-rotation.compact", err, `eventsPath=${eventsPath}`);
+		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.
+	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) {
 			return {
 				originalSize,
 				compactedSize: fs.statSync(eventsPath).size,
 				eventsRemoved: originalCount - kept.length,
-				eventsKept: kept.length + recoveredCount,
-				recoveryFailed,
-			};
-		} catch {
-			// Post-write verification failed — compaction likely succeeded.
-			const compactedSize = fs.statSync(eventsPath).size;
-			return {
-				originalSize,
-				compactedSize,
-				eventsRemoved: originalCount - kept.length,
-				eventsKept: kept.length,
+				eventsKept: kept.length + Math.max(0, afterWrite.length - 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));
+		const missingEvents = kept.filter((e) => e.metadata?.seq === undefined || !afterSeqs.has(e.metadata.seq));
+		let recoveredCount = 0;
+		let recoveryFailed = false;
+		if (missingEvents.length > 0) {
+			const recoveryLines = missingEvents.map((e) => JSON.stringify(e) + "\n").join("");
+			try {
+				fs.appendFileSync(eventsPath, recoveryLines);
+				recoveredCount = missingEvents.length;
+			} catch (err) {
+				recoveryFailed = true;
+				logInternalError("event-log-rotation.recovery", err, `eventsPath=${eventsPath} lostEvents=${missingEvents.length}`);
+			}
+		}
+		return {
+			originalSize,
+			compactedSize: fs.statSync(eventsPath).size,
+			eventsRemoved: originalCount - kept.length,
+			eventsKept: kept.length + recoveredCount,
+			recoveryFailed,
+		};
+	} catch {
+		// Post-write verification failed — compaction likely succeeded.
+		return {
+			originalSize,
+			compactedSize: fs.statSync(eventsPath).size,
+			eventsRemoved: originalCount - kept.length,
+			eventsKept: kept.length,
+		};
+	}
 }
 
 /**
@@ -161,33 +174,41 @@ export function rotateEventLog(eventsPath: string): boolean {
 	// 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.
-	return withEventLogLockSync(eventsPath, () => {
-		try {
-			const ts = new Date().toISOString().replace(/[:.]/g, "-");
-			let archivePath = `${eventsPath}.${ts}.archive.jsonl`;
-			// Round 12: avoid timestamp collisions when two rotations happen within
-			// the same millisecond (copyFileSync would silently overwrite the
-			// first archive). Append a counter until the path is free.
-			let collision = 1;
-			while (fs.existsSync(archivePath)) {
-				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);
-			fs.writeFileSync(eventsPath, "", "utf-8");
-			return true;
-		} catch (error) {
-			logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);
-			return false;
+	//
+	// 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));
+}
+
+/** 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 {
+	if (!fs.existsSync(eventsPath)) return false;
+	try {
+		const ts = new Date().toISOString().replace(/[:.]/g, "-");
+		let archivePath = `${eventsPath}.${ts}.archive.jsonl`;
+		// Round 12: avoid timestamp collisions when two rotations happen within
+		// the same millisecond (copyFileSync would silently overwrite the
+		// first archive). Append a counter until the path is free.
+		let collision = 1;
+		while (fs.existsSync(archivePath)) {
+			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);
+		fs.writeFileSync(eventsPath, "", "utf-8");
+		return true;
+	} catch (error) {
+		logInternalError("event-log.rotate", error, `eventsPath=${eventsPath}`);
+		return false;
+	}
 }
 
 export interface EventLogStats {