@pi-agents/orchid 0.1.0-beta.0

package/src/orchestrator/cleanup.ts

@@ -0,0 +1,776 @@
+/**
+ * Artifact cleanup and log rotation for orchestrator runtime files.
+ *
+ * Five cleanup layers prevent unbounded disk growth:
+ *
+ * 1. **Post-Integrate Cleanup** — Deletes batch-specific telemetry and merge
+ *    result files after successful /orch-integrate. Scoped by batchId.
+ *
+ * 2. **Age-Based Preflight Sweep** — On /orch start, removes telemetry,
+ *    verification, conversation, lane-state, and merge artifacts older than
+ *    3 days. Catches files missed by Layer 1 (e.g., aborted batches,
+ *    manual branch deletions).
+ *
+ * 3. **Size-Capped Log Rotation** — Rotates append-only supervisor logs
+ *    (events.jsonl, actions.jsonl) at a 5MB threshold during preflight.
+ *    Keeps one .old generation.
+ *
+ * 4. **Telemetry Size Cap** — Enforces a 500MB cap on `.pi/telemetry/`
+ *    by evicting oldest files first when the directory exceeds the cap.
+ *
+ * 5. **Batch-Start Cleanup** — Removes artifacts from prior completed
+ *    batches when a new batch starts, protecting the current batch.
+ *
+ * All cleanup is **non-fatal** — failures warn but never block execution.
+ *
+ * @module orch/cleanup
+ * @since TP-065
+ */
+import { existsSync, readdirSync, statSync, unlinkSync, renameSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { MAILBOX_DIR_NAME } from "./types.ts";
+
+// ── Layer 1: Post-Integrate Cleanup ─────────────────────────────────
+
+/**
+ * Result of post-integrate artifact cleanup.
+ */
+export interface PostIntegrateCleanupResult {
+	/** Number of telemetry files deleted */
+	telemetryFilesDeleted: number;
+	/** Number of merge result/request files deleted */
+	mergeFilesDeleted: number;
+	/** Number of lane prompt files deleted */
+	promptFilesDeleted: number;
+	/** Number of mailbox batch directories deleted (0 or 1) */
+	mailboxDirsDeleted: number;
+	/** Number of context-snapshot batch directories deleted (0 or 1) */
+	snapshotDirsDeleted: number;
+	/** Warnings from non-fatal cleanup failures */
+	warnings: string[];
+}
+
+/**
+ * Clean up batch-specific telemetry and merge result files after integrate.
+ *
+ * Targets files whose names contain the batchId:
+ * - `.pi/telemetry/*-{batchId}-*.jsonl` — worker/merger sidecar files
+ * - `.pi/telemetry/*-{batchId}-*-exit.json` — exit summaries
+ * - `.pi/telemetry/lane-prompt-*.txt` — temporary prompt files (all, not scoped)
+ * - `.pi/merge-result-*-{batchId}.json` — merge result files
+ * - `.pi/merge-request-*-{batchId}.txt` — merge request files
+ *
+ * @param stateRoot - Root directory containing .pi/ (workspace root or repo root)
+ * @param batchId - Batch ID to scope deletion
+ * @returns Cleanup result with counts and warnings
+ */
+export function cleanupPostIntegrate(
+	stateRoot: string,
+	batchId: string,
+): PostIntegrateCleanupResult {
+	const result: PostIntegrateCleanupResult = {
+		telemetryFilesDeleted: 0,
+		mergeFilesDeleted: 0,
+		promptFilesDeleted: 0,
+		mailboxDirsDeleted: 0,
+		snapshotDirsDeleted: 0,
+		warnings: [],
+	};
+
+	if (!batchId) {
+		result.warnings.push("No batchId provided — skipping post-integrate cleanup");
+		return result;
+	}
+
+	// ── Telemetry files (.pi/telemetry/) ─────────────────────────
+	const telemetryDir = join(stateRoot, ".pi", "telemetry");
+	if (existsSync(telemetryDir)) {
+		try {
+			const entries = readdirSync(telemetryDir);
+			for (const entry of entries) {
+				// Delete batch-scoped sidecar/exit files containing the batchId
+				if (entry.includes(batchId) && (entry.endsWith(".jsonl") || entry.endsWith("-exit.json"))) {
+					try {
+						unlinkSync(join(telemetryDir, entry));
+						result.telemetryFilesDeleted++;
+					} catch (err: unknown) {
+						result.warnings.push(`Failed to delete telemetry file ${entry}: ${(err as Error).message}`);
+					}
+				}
+				// Delete all lane-prompt-*.txt files (not batch-scoped — they're
+				// temporary and should be cleaned up with any batch)
+				if (entry.startsWith("lane-prompt-") && entry.endsWith(".txt")) {
+					try {
+						unlinkSync(join(telemetryDir, entry));
+						result.promptFilesDeleted++;
+					} catch (err: unknown) {
+						result.warnings.push(`Failed to delete prompt file ${entry}: ${(err as Error).message}`);
+					}
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read telemetry directory: ${(err as Error).message}`);
+		}
+	}
+
+	// ── Merge result/request files (.pi/) ────────────────────────
+	const piDir = join(stateRoot, ".pi");
+	if (existsSync(piDir)) {
+		try {
+			const entries = readdirSync(piDir);
+			for (const entry of entries) {
+				if (
+					entry.includes(batchId) &&
+					((entry.startsWith("merge-result-") && entry.endsWith(".json")) ||
+						(entry.startsWith("merge-request-") && entry.endsWith(".txt")))
+				) {
+					try {
+						unlinkSync(join(piDir, entry));
+						result.mergeFilesDeleted++;
+					} catch (err: unknown) {
+						result.warnings.push(`Failed to delete merge file ${entry}: ${(err as Error).message}`);
+					}
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read .pi directory: ${(err as Error).message}`);
+		}
+	}
+
+	// ── Mailbox directory (.pi/mailbox/{batchId}/) ───────────
+	const mailboxBatchDir = join(stateRoot, ".pi", MAILBOX_DIR_NAME, batchId);
+	if (existsSync(mailboxBatchDir)) {
+		try {
+			rmSync(mailboxBatchDir, { recursive: true, force: true });
+			result.mailboxDirsDeleted = 1;
+		} catch (err: unknown) {
+			result.warnings.push(
+				`Failed to delete mailbox directory ${mailboxBatchDir}: ${(err as Error).message}`,
+			);
+		}
+	}
+
+	// ── Context snapshots directory (.pi/context-snapshots/{batchId}/) ──────
+	const snapshotBatchDir = join(stateRoot, ".pi", "context-snapshots", batchId);
+	if (existsSync(snapshotBatchDir)) {
+		try {
+			rmSync(snapshotBatchDir, { recursive: true, force: true });
+			result.snapshotDirsDeleted = 1;
+		} catch (err: unknown) {
+			result.warnings.push(
+				`Failed to delete context-snapshots directory ${snapshotBatchDir}: ${(err as Error).message}`,
+			);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Format post-integrate cleanup result for user-facing notification.
+ */
+export function formatPostIntegrateCleanup(result: PostIntegrateCleanupResult): string {
+	const parts: string[] = [];
+	const totalDeleted =
+		result.telemetryFilesDeleted +
+		result.mergeFilesDeleted +
+		result.promptFilesDeleted +
+		result.mailboxDirsDeleted +
+		result.snapshotDirsDeleted;
+
+	if (totalDeleted > 0) {
+		const segments: string[] = [];
+		if (result.telemetryFilesDeleted > 0) segments.push(`${result.telemetryFilesDeleted} telemetry`);
+		if (result.mergeFilesDeleted > 0) segments.push(`${result.mergeFilesDeleted} merge`);
+		if (result.promptFilesDeleted > 0) segments.push(`${result.promptFilesDeleted} prompt`);
+		if (result.mailboxDirsDeleted > 0) segments.push(`${result.mailboxDirsDeleted} mailbox`);
+		if (result.snapshotDirsDeleted > 0) segments.push(`${result.snapshotDirsDeleted} snapshots`);
+		parts.push(`🧹 Cleaned up ${totalDeleted} artifact file(s): ${segments.join(", ")}`);
+	}
+
+	for (const warning of result.warnings) {
+		parts.push(`  ⚠️ ${warning}`);
+	}
+
+	return parts.join("\n");
+}
+
+// ── Layer 2: Age-Based Preflight Sweep ──────────────────────────────
+
+/** Default max age for stale artifacts (3 days in milliseconds). */
+export const STALE_ARTIFACT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1000;
+
+/**
+ * Result of a preflight age-based sweep.
+ */
+export interface PreflightSweepResult {
+	/** Number of stale files deleted */
+	staleFilesDeleted: number;
+	/** Number of stale mailbox batch directories deleted */
+	staleDirsDeleted: number;
+	/** Whether the sweep was skipped (e.g., active batch) */
+	skipped: boolean;
+	/** Reason for skipping (if skipped) */
+	skipReason?: string;
+	/** Warnings from non-fatal cleanup failures */
+	warnings: string[];
+}
+
+/**
+ * Dependencies injected into sweepStaleArtifacts for testability.
+ */
+export interface SweepDeps {
+	/** Check if a batch is currently active (phase is not terminal). */
+	isBatchActive: () => boolean;
+	/** Get the current timestamp (for deterministic testing). */
+	now: () => number;
+}
+
+/**
+ * Sweep stale artifacts older than maxAgeMs during preflight.
+ *
+ * Targets:
+ * - `.pi/telemetry/*.jsonl` — sidecar files
+ * - `.pi/telemetry/*-exit.json` — exit summaries
+ * - `.pi/telemetry/lane-prompt-*.txt` — temporary prompt files
+ * - `.pi/merge-result-*.json` — merge result files
+ * - `.pi/merge-request-*.txt` — merge request files
+ * - `.pi/verification/*` — verification snapshots
+ * - `.pi/worker-conversation-*.jsonl` — worker conversation logs
+ * - `.pi/lane-state-*.json` — lane state files
+ *
+ * Uses file mtime for age detection. Skips files modified within maxAgeMs.
+ * If a batch is currently active (executing/merging), skips ALL cleanup.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param deps - Injectable dependencies for testability
+ * @param maxAgeMs - Maximum file age in milliseconds (default: 3 days)
+ * @returns Sweep result with count and warnings
+ */
+export function sweepStaleArtifacts(
+	stateRoot: string,
+	deps: SweepDeps,
+	maxAgeMs: number = STALE_ARTIFACT_MAX_AGE_MS,
+): PreflightSweepResult {
+	const result: PreflightSweepResult = {
+		staleFilesDeleted: 0,
+		staleDirsDeleted: 0,
+		skipped: false,
+		warnings: [],
+	};
+
+	// Guard: skip if batch is actively executing
+	try {
+		if (deps.isBatchActive()) {
+			result.skipped = true;
+			result.skipReason = "Active batch detected — skipping stale artifact sweep";
+			return result;
+		}
+	} catch {
+		// If we can't determine batch state, proceed cautiously
+	}
+
+	const now = deps.now();
+	const cutoff = now - maxAgeMs;
+
+	/**
+	 * Delete files older than cutoff from a directory, matching a filter.
+	 */
+	const sweepDir = (dir: string, filter: (name: string) => boolean): void => {
+		if (!existsSync(dir)) return;
+		try {
+			const entries = readdirSync(dir);
+			for (const entry of entries) {
+				if (!filter(entry)) continue;
+				const filePath = join(dir, entry);
+				try {
+					const stat = statSync(filePath);
+					if (!stat.isFile()) continue;
+					if (stat.mtimeMs < cutoff) {
+						unlinkSync(filePath);
+						result.staleFilesDeleted++;
+					}
+				} catch (err: unknown) {
+					result.warnings.push(`Failed to process ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read directory ${dir}: ${(err as Error).message}`);
+		}
+	};
+
+	// Sweep telemetry files
+	sweepDir(
+		join(stateRoot, ".pi", "telemetry"),
+		(name) =>
+			name.endsWith(".jsonl") ||
+			name.endsWith("-exit.json") ||
+			(name.startsWith("lane-prompt-") && name.endsWith(".txt")),
+	);
+
+	// Sweep merge result/request files
+	sweepDir(
+		join(stateRoot, ".pi"),
+		(name) =>
+			(name.startsWith("merge-result-") && name.endsWith(".json")) ||
+			(name.startsWith("merge-request-") && name.endsWith(".txt")),
+	);
+
+	// Sweep stale worker conversation logs (.pi/worker-conversation-*.jsonl)
+	sweepDir(
+		join(stateRoot, ".pi"),
+		(name) => name.startsWith("worker-conversation-") && name.endsWith(".jsonl"),
+	);
+
+	// Sweep stale lane state files (.pi/lane-state-*.json)
+	sweepDir(
+		join(stateRoot, ".pi"),
+		(name) => name.startsWith("lane-state-") && name.endsWith(".json"),
+	);
+
+	// Sweep stale batch directories under a parent (mailbox, context-snapshots, verification)
+	const sweepBatchDirs = (parentDir: string, label: string): void => {
+		if (!existsSync(parentDir)) return;
+		try {
+			const entries = readdirSync(parentDir);
+			for (const entry of entries) {
+				const entryPath = join(parentDir, entry);
+				try {
+					const stat = statSync(entryPath);
+					if (!stat.isDirectory()) continue;
+					if (stat.mtimeMs < cutoff) {
+						rmSync(entryPath, { recursive: true, force: true });
+						result.staleDirsDeleted++;
+					}
+				} catch (err: unknown) {
+					result.warnings.push(`Failed to process ${label} dir ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(
+				`Failed to read ${label} directory ${parentDir}: ${(err as Error).message}`,
+			);
+		}
+	};
+
+	// Sweep stale mailbox batch directories (.pi/mailbox/{batchId}/)
+	sweepBatchDirs(join(stateRoot, ".pi", MAILBOX_DIR_NAME), "mailbox");
+
+	// Sweep stale context-snapshot batch directories (.pi/context-snapshots/{batchId}/)
+	sweepBatchDirs(join(stateRoot, ".pi", "context-snapshots"), "context-snapshots");
+
+	// Sweep stale verification snapshot directories (.pi/verification/{opId}/)
+	sweepBatchDirs(join(stateRoot, ".pi", "verification"), "verification");
+
+	return result;
+}
+
+/**
+ * Format preflight sweep result for logging.
+ */
+export function formatPreflightSweep(result: PreflightSweepResult): string {
+	if (result.skipped) {
+		return `ℹ️ Preflight sweep skipped: ${result.skipReason}`;
+	}
+	if (
+		result.staleFilesDeleted === 0 &&
+		result.staleDirsDeleted === 0 &&
+		result.warnings.length === 0
+	) {
+		return ""; // Nothing to report
+	}
+	const parts: string[] = [];
+	if (result.staleFilesDeleted > 0 || result.staleDirsDeleted > 0) {
+		const segments: string[] = [];
+		if (result.staleFilesDeleted > 0) segments.push(`${result.staleFilesDeleted} stale artifact(s)`);
+		if (result.staleDirsDeleted > 0) segments.push(`${result.staleDirsDeleted} stale mailbox dir(s)`);
+		parts.push(`🧹 Preflight cleanup: removed ${segments.join(" and ")} (>3 days old)`);
+	}
+	for (const warning of result.warnings) {
+		parts.push(`  ⚠️ ${warning}`);
+	}
+	return parts.join("\n");
+}
+
+// ── Layer 3: Size-Capped Log Rotation ───────────────────────────────
+
+/** Default rotation threshold: 5MB. */
+export const LOG_ROTATION_THRESHOLD_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Result of log rotation.
+ */
+export interface LogRotationResult {
+	/** Files that were rotated */
+	rotated: string[];
+	/** Warnings from non-fatal rotation failures */
+	warnings: string[];
+}
+
+/**
+ * Rotate supervisor append-only logs at a size threshold.
+ *
+ * Checks `events.jsonl` and `actions.jsonl` in `.pi/supervisor/`.
+ * If a file exceeds the threshold, renames it to `.old` (overwriting
+ * any existing `.old`), allowing a fresh file to be created on next write.
+ *
+ * Only call during preflight (not mid-batch).
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param thresholdBytes - Maximum file size before rotation (default: 5MB)
+ * @returns Rotation result
+ */
+export function rotateSupervisorLogs(
+	stateRoot: string,
+	thresholdBytes: number = LOG_ROTATION_THRESHOLD_BYTES,
+): LogRotationResult {
+	const result: LogRotationResult = {
+		rotated: [],
+		warnings: [],
+	};
+
+	const supervisorDir = join(stateRoot, ".pi", "supervisor");
+	if (!existsSync(supervisorDir)) {
+		return result; // Nothing to rotate
+	}
+
+	const filesToRotate = ["events.jsonl", "actions.jsonl"];
+
+	for (const fileName of filesToRotate) {
+		const filePath = join(supervisorDir, fileName);
+		if (!existsSync(filePath)) continue;
+
+		try {
+			const stat = statSync(filePath);
+			if (!stat.isFile() || stat.size <= thresholdBytes) continue;
+
+			const oldPath = `${filePath}.old`;
+			renameSync(filePath, oldPath);
+			result.rotated.push(fileName);
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to rotate ${fileName}: ${(err as Error).message}`);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Format log rotation result for logging.
+ */
+export function formatLogRotation(result: LogRotationResult): string {
+	if (result.rotated.length === 0 && result.warnings.length === 0) {
+		return ""; // Nothing to report
+	}
+	const parts: string[] = [];
+	if (result.rotated.length > 0) {
+		parts.push(`🔄 Rotated ${result.rotated.length} supervisor log(s): ${result.rotated.join(", ")}`);
+	}
+	for (const warning of result.warnings) {
+		parts.push(`  ⚠️ ${warning}`);
+	}
+	return parts.join("\n");
+}
+
+// ── Layer 4: Telemetry Directory Size Cap ─────────────────────────────
+
+/** Default telemetry directory size cap: 500 MB. */
+export const TELEMETRY_SIZE_CAP_BYTES = 500 * 1024 * 1024;
+
+/**
+ * Result of telemetry size cap enforcement.
+ */
+export interface SizeCapResult {
+	/** Number of files deleted to bring directory under cap */
+	filesDeleted: number;
+	/** Total bytes freed */
+	bytesFreed: number;
+	/** Warnings from non-fatal failures */
+	warnings: string[];
+}
+
+/**
+ * Enforce a size cap on the telemetry directory by evicting oldest files first.
+ *
+ * Scans `.pi/telemetry/` and sums file sizes. If the total exceeds `capBytes`,
+ * deletes the oldest files (by mtime) until the total is under the cap.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param capBytes - Maximum allowed total size in bytes (default: 500MB)
+ * @returns Size cap enforcement result
+ */
+export function enforceTelemetrySizeCap(
+	stateRoot: string,
+	capBytes: number = TELEMETRY_SIZE_CAP_BYTES,
+): SizeCapResult {
+	const result: SizeCapResult = {
+		filesDeleted: 0,
+		bytesFreed: 0,
+		warnings: [],
+	};
+
+	const telemetryDir = join(stateRoot, ".pi", "telemetry");
+	if (!existsSync(telemetryDir)) return result;
+
+	// Collect all files with size and mtime
+	interface FileEntry {
+		name: string;
+		path: string;
+		size: number;
+		mtimeMs: number;
+	}
+
+	const files: FileEntry[] = [];
+	let totalSize = 0;
+
+	try {
+		const entries = readdirSync(telemetryDir);
+		for (const entry of entries) {
+			const filePath = join(telemetryDir, entry);
+			try {
+				const stat = statSync(filePath);
+				if (!stat.isFile()) continue;
+				files.push({ name: entry, path: filePath, size: stat.size, mtimeMs: stat.mtimeMs });
+				totalSize += stat.size;
+			} catch (err: unknown) {
+				result.warnings.push(`Failed to stat ${entry}: ${(err as Error).message}`);
+			}
+		}
+	} catch (err: unknown) {
+		result.warnings.push(`Failed to read telemetry directory: ${(err as Error).message}`);
+		return result;
+	}
+
+	if (totalSize <= capBytes) return result;
+
+	// Sort oldest first (lowest mtime first)
+	files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+	// Delete oldest files until under cap
+	for (const file of files) {
+		if (totalSize <= capBytes) break;
+		try {
+			unlinkSync(file.path);
+			totalSize -= file.size;
+			result.filesDeleted++;
+			result.bytesFreed += file.size;
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to delete ${file.name}: ${(err as Error).message}`);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Format size cap result for logging.
+ */
+export function formatSizeCap(result: SizeCapResult): string {
+	if (result.filesDeleted === 0 && result.warnings.length === 0) return "";
+	const parts: string[] = [];
+	if (result.filesDeleted > 0) {
+		const mbFreed = (result.bytesFreed / (1024 * 1024)).toFixed(1);
+		parts.push(`🧹 Telemetry size cap: deleted ${result.filesDeleted} file(s), freed ${mbFreed} MB`);
+	}
+	for (const warning of result.warnings) {
+		parts.push(`  ⚠️ ${warning}`);
+	}
+	return parts.join("\n");
+}
+
+// ── Layer 5: Batch-Start Cleanup of Prior Batch Artifacts ─────────────
+
+/**
+ * Result of prior-batch artifact cleanup.
+ */
+export interface PriorBatchCleanupResult {
+	/** Number of files/dirs deleted */
+	itemsDeleted: number;
+	/** Warnings from non-fatal failures */
+	warnings: string[];
+}
+
+/**
+ * Clean up artifacts from prior completed batches when a new batch starts.
+ *
+ * Removes batch-scoped files that may have been left behind by prior runs
+ * that were not integrated (e.g., aborted, crashed). Only cleans artifacts
+ * from batches that are NOT the currently active batch.
+ *
+ * Targets the same file patterns as `cleanupPostIntegrate` plus stale
+ * batch-state files.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param currentBatchId - The batch ID that is currently starting (will NOT be deleted)
+ * @returns Cleanup result
+ */
+export function cleanupPriorBatchArtifacts(
+	stateRoot: string,
+	currentBatchId: string,
+): PriorBatchCleanupResult {
+	const result: PriorBatchCleanupResult = {
+		itemsDeleted: 0,
+		warnings: [],
+	};
+
+	if (!currentBatchId) {
+		result.warnings.push("No currentBatchId provided — skipping prior batch cleanup");
+		return result;
+	}
+
+	const piDir = join(stateRoot, ".pi");
+	if (!existsSync(piDir)) return result;
+
+	// Helper: delete files in a directory matching a filter, skipping current batch
+	const cleanDir = (dir: string, filter: (name: string) => boolean): void => {
+		if (!existsSync(dir)) return;
+		try {
+			const entries = readdirSync(dir);
+			for (const entry of entries) {
+				if (!filter(entry)) continue;
+				if (entry.includes(currentBatchId)) continue; // Protect current batch
+				const filePath = join(dir, entry);
+				try {
+					const stat = statSync(filePath);
+					if (stat.isFile()) {
+						unlinkSync(filePath);
+						result.itemsDeleted++;
+					}
+				} catch (err: unknown) {
+					result.warnings.push(`Failed to delete ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read directory ${dir}: ${(err as Error).message}`);
+		}
+	};
+
+	// Clean telemetry files from prior batches
+	cleanDir(
+		join(piDir, "telemetry"),
+		(name) =>
+			name.endsWith(".jsonl") ||
+			name.endsWith("-exit.json") ||
+			(name.startsWith("lane-prompt-") && name.endsWith(".txt")),
+	);
+
+	// Clean merge result/request files from prior batches
+	cleanDir(
+		piDir,
+		(name) =>
+			(name.startsWith("merge-result-") && name.endsWith(".json")) ||
+			(name.startsWith("merge-request-") && name.endsWith(".txt")),
+	);
+
+	// Clean worker conversation logs from prior batches
+	cleanDir(piDir, (name) => name.startsWith("worker-conversation-") && name.endsWith(".jsonl"));
+
+	// Clean lane state files from prior batches
+	cleanDir(piDir, (name) => name.startsWith("lane-state-") && name.endsWith(".json"));
+
+	// Clean batch-scoped directories (mailbox, context-snapshots)
+	const cleanBatchDirs = (parentDir: string): void => {
+		if (!existsSync(parentDir)) return;
+		try {
+			const entries = readdirSync(parentDir);
+			for (const entry of entries) {
+				if (entry === currentBatchId) continue; // Protect current batch
+				const entryPath = join(parentDir, entry);
+				try {
+					const stat = statSync(entryPath);
+					if (!stat.isDirectory()) continue;
+					rmSync(entryPath, { recursive: true, force: true });
+					result.itemsDeleted++;
+				} catch (err: unknown) {
+					result.warnings.push(`Failed to delete batch dir ${entry}: ${(err as Error).message}`);
+				}
+			}
+		} catch (err: unknown) {
+			result.warnings.push(`Failed to read directory ${parentDir}: ${(err as Error).message}`);
+		}
+	};
+
+	cleanBatchDirs(join(piDir, MAILBOX_DIR_NAME));
+	cleanBatchDirs(join(piDir, "context-snapshots"));
+
+	return result;
+}
+
+/**
+ * Format prior batch cleanup result for logging.
+ */
+export function formatPriorBatchCleanup(result: PriorBatchCleanupResult): string {
+	if (result.itemsDeleted === 0 && result.warnings.length === 0) return "";
+	const parts: string[] = [];
+	if (result.itemsDeleted > 0) {
+		parts.push(
+			`🧹 Prior batch cleanup: removed ${result.itemsDeleted} artifact(s) from previous batch(es)`,
+		);
+	}
+	for (const warning of result.warnings) {
+		parts.push(`  ⚠️ ${warning}`);
+	}
+	return parts.join("\n");
+}
+
+// ── Combined Preflight Cleanup ──────────────────────────────────────
+
+/**
+ * Combined result of preflight cleanup (Layer 2 + Layer 3).
+ */
+export interface PreflightCleanupResult {
+	sweep: PreflightSweepResult;
+	rotation: LogRotationResult;
+}
+
+/**
+ * Run all preflight cleanup operations (Layer 2 + Layer 3).
+ *
+ * Called from the engine's preflight phase before batch starts.
+ * Always non-fatal.
+ *
+ * @param stateRoot - Root directory containing .pi/
+ * @param deps - Sweep dependencies (active batch check)
+ * @returns Combined cleanup result
+ */
+export function runPreflightCleanup(stateRoot: string, deps: SweepDeps): PreflightCleanupResult {
+	const sweep = sweepStaleArtifacts(stateRoot, deps);
+	const rotation = rotateSupervisorLogs(stateRoot);
+	return { sweep, rotation };
+}
+
+/**
+ * Format combined preflight cleanup result for user notification.
+ *
+ * Returns an empty string if nothing happened (no files cleaned/rotated).
+ */
+export function formatPreflightCleanup(result: PreflightCleanupResult): string {
+	const parts: string[] = [];
+
+	// Layer 2: age-based sweep
+	if (
+		!result.sweep.skipped &&
+		(result.sweep.staleFilesDeleted > 0 || result.sweep.staleDirsDeleted > 0)
+	) {
+		const segments: string[] = [];
+		if (result.sweep.staleFilesDeleted > 0)
+			segments.push(`${result.sweep.staleFilesDeleted} stale artifact(s)`);
+		if (result.sweep.staleDirsDeleted > 0)
+			segments.push(`${result.sweep.staleDirsDeleted} stale mailbox dir(s)`);
+		parts.push(`removed ${segments.join(" and ")} (>3 days old)`);
+	}
+
+	// Layer 3: log rotation
+	if (result.rotation.rotated.length > 0) {
+		parts.push(`rotated ${result.rotation.rotated.join(", ")} (>5 MB)`);
+	}
+
+	// Collect warnings from both layers
+	const warnings = [...result.sweep.warnings, ...result.rotation.warnings];
+	if (warnings.length > 0) {
+		parts.push(`⚠️ ${warnings.length} cleanup warning(s)`);
+	}
+
+	if (parts.length === 0) return "";
+	return `🧹 Preflight cleanup: ${parts.join("; ")}`;
+}