taskplane 0.25.8 → 0.27.0

package/README.md

@@ -71,14 +71,17 @@ pi install -l npm:taskplane
 ## Quickstart
 
 ### 1. Initialize a project (to scaffold settings)
+This step assumes you have installed Taskplane using one of the above options. 
+
 (NOTE: if 'my-project' is a monorepo, be sure to run git init first. Taskplane uses git worktrees to isolate agent coding until you're ready to merge back to your default branch.)
+
 ```bash
 cd my-project
 taskplane init
 ```
 You'll answer a few questions. You can usually just accept the defaults. 
 
-This creates config files in `.pi/`, agent prompts, two example tasks, and adds `.gitignore` entries for runtime artifacts. On first install, init bootstraps global preferences at `~/.pi/agent/taskplane/preferences.json` with thinking defaults set to `high` for worker & reviewer, and off for merger. Init auto-detects whether you're in a single repo or a multi-repo workspace. See the [install tutorial](docs/tutorials/install.md) for workspace mode and other scenarios.
+This creates: config files in `.pi/`, agent prompts, two example tasks, and adds `.gitignore` entries for runtime artifacts. On first install, init bootstraps global preferences at `~/.pi/agent/taskplane/preferences.json` with thinking defaults set to `high` for worker & reviewer, and off for merger. Init auto-detects whether you're in a monorepo or a polyrepo workspace. See the [install tutorial](docs/tutorials/install.md) for workspace mode and other scenarios.
 
 Already have a task folder (for example `docs/task-management`)? Use:
 

package/bin/rpc-wrapper.mjs

@@ -294,7 +294,6 @@ function displayProgress(state) {
  * Per RPC protocol spec: split on \n, strip optional trailing \r,
  * do NOT use Node readline (splits on U+2028/U+2029).
  *
- * Reuses the proven pattern from task-runner.ts:910-975.
  */
 function attachJsonlReader(stream, onLine) {
 	const decoder = new StringDecoder("utf8");

package/bin/taskplane.mjs

@@ -787,18 +787,24 @@ export async function collectInitAgentConfig({
 	return initAgentConfig;
 }
 
+/** Normalize a path string to forward slashes (for config file output). */
+function fwdSlash(p) {
+	return typeof p === "string" ? p.replace(/\\/g, "/") : p;
+}
+
 export function generateProjectConfig(vars, _initAgentConfig = null) {
+	const tasksRoot = fwdSlash(vars.tasks_root);
 	const projectConfig = {
 		configVersion: 1,
 		taskRunner: {
 			project: { name: vars.project_name, description: "" },
-			paths: { tasks: vars.tasks_root },
+			paths: { tasks: tasksRoot },
 			testing: { commands: buildTestingCommands(vars) },
 			taskAreas: {
 				[vars.default_area]: {
-					path: vars.tasks_root,
+					path: tasksRoot,
 					prefix: vars.default_prefix,
-					context: `${vars.tasks_root}/CONTEXT.md`,
+					context: `${tasksRoot}/CONTEXT.md`,
 				},
 			},
 		},
@@ -820,10 +826,11 @@ export function generateProjectConfig(vars, _initAgentConfig = null) {
 }
 
 function generateWorkspaceYaml(repoNames, defaultRepo, tasksRoot) {
+	const normalizedTasksRoot = fwdSlash(tasksRoot);
 	const reposBlock = repoNames
 		.map((name) => `  ${name}:\n    path: "${name}"`)
 		.join("\n");
-	return `repos:\n${reposBlock}\nrouting:\n  tasks_root: "${tasksRoot}"\n  default_repo: "${defaultRepo}"\n  task_packet_repo: "${defaultRepo}"\n`;
+	return `repos:\n${reposBlock}\nrouting:\n  tasks_root: "${normalizedTasksRoot}"\n  default_repo: "${defaultRepo}"\n  task_packet_repo: "${defaultRepo}"\n`;
 }
 
 function readWorkspaceJson(configRepoRoot) {
@@ -1923,7 +1930,7 @@ async function cmdInit(args) {
 				default_branch: "main",
 			})),
 			routing: {
-				tasks_root: vars.tasks_root,
+				tasks_root: fwdSlash(vars.tasks_root),
 				default_repo: configRepoName,
 				strict: false,
 			},
@@ -3184,7 +3191,7 @@ ${c.bold}Examples:${c.reset}
 ${c.bold}Getting started:${c.reset}
   1. pi install npm:taskplane       # Install the pi package
   2. cd my-project && taskplane init    # Scaffold project config
-  3. pi                             # Start pi — /task and /orch are ready
+  3. pi                             # Start pi — /orch is ready
 `);
 }
 

package/dashboard/public/app.js

@@ -1379,6 +1379,49 @@ function renderSupervisorConversation(supervisor) {
   $supervisorConversationSection.innerHTML = html;
 }
 
+/**
+ * Human-readable labels for supervisor recovery action identifiers.
+ * The supervisor LLM writes snake_case action names to actions.jsonl.
+ * This map translates them to operator-friendly labels for the dashboard.
+ */
+const RECOVERY_ACTION_LABELS = {
+  // Conflict resolution
+  conflict_resolve_checkout_ours:   "Auto-resolved merge conflict (kept task changes)",
+  conflict_resolve_checkout_theirs: "Auto-resolved merge conflict (kept base changes)",
+  conflict_resolve_manual:          "Manual conflict resolution applied",
+
+  // Merge agent
+  merge_retry:                      "Retried merge agent",
+  merge_session_kill:               "Terminated stalled merge agent",
+  merge_force:                      "Forced merge with partial results",
+
+  // Worker / task
+  worker_wrap_up:                   "Sent wrap-up signal to stalled worker",
+  task_retry:                       "Retried failed task",
+  task_skip:                        "Skipped task — unblocked dependents",
+  wave_force_merge:                 "Force-merged wave with mixed results",
+
+  // Git / worktree
+  lock_clear:                       "Cleared stale git lock file",
+  worktree_remove:                  "Removed stale worktree",
+  worktree_prune:                   "Pruned stale worktrees",
+
+  // Batch lifecycle
+  abort_hard:                       "Hard-aborted batch",
+  batch_resume:                     "Resumed batch after recovery",
+  supervisor_handoff:               "Supervisor session handoff",
+
+  // Diagnostics (usually not shown — filtered as non-recovery)
+  initial_status_check:             "Checked initial batch status",
+  completion_status_check:          "Verified batch completion status",
+  read_state:                       "Read batch state",
+};
+
+/** Format a recovery action type string into a human-readable label. */
+function formatRecoveryActionLabel(type) {
+  return RECOVERY_ACTION_LABELS[type] || type.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
 /** Merge supervisor actions and Tier 0 recovery events into a unified timeline.
  *  Actions from actions.jsonl and recovery events from events.jsonl are combined
  *  and sorted chronologically (per R002: show both Tier 0 and supervisor actions).
@@ -1451,7 +1494,7 @@ function renderSupervisorActions(supervisor) {
     html += `  <div class="supervisor-action-right">`;
     html += `    <div class="supervisor-action-header">`;
     if (tier) html += `<span class="supervisor-action-tier">${tier}</span>`;
-    html += `      <span class="supervisor-action-type">${escapeHtml(type)}</span>`;
+    html += `      <span class="supervisor-action-type" title="${escapeHtml(type)}">${escapeHtml(formatRecoveryActionLabel(type))}</span>`;
     if (target) html += `<span class="supervisor-action-target">${escapeHtml(target)}</span>`;
     if (outcome) html += `<span class="supervisor-action-outcome ${outcomeCls}">${escapeHtml(outcome)}</span>`;
     html += `    </div>`;

package/extensions/task-orchestrator.ts

@@ -18,7 +18,7 @@
  *   .pi/task-orchestrator.yaml  — orchestrator-specific settings
  *   .pi/task-runner.yaml        — task areas, worker/reviewer config (shared)
  *
- * Usage: pi -e extensions/task-orchestrator.ts -e extensions/task-runner.ts
+ * Usage: pi -e extensions/task-orchestrator.ts
  */
 
 // Re-export all named exports for tests and other consumers

package/extensions/taskplane/abort.ts

@@ -85,7 +85,8 @@ export function selectAbortTargetSessions(
 			laneId: lane.laneId,
 			taskId: currentTask?.taskId || null,
 			worktreePath: lane.worktreePath,
-			taskFolder: currentTask?.task.taskFolder || null,
+			// TP-169: Guard against null task stubs from reconstructAllocatedLanes
+			taskFolder: currentTask?.task?.taskFolder || null,
 		});
 	}
 

package/extensions/taskplane/agent-host.ts

@@ -136,6 +136,23 @@ export interface AgentHostOptions {
 	packet?: PacketPaths | null;
 	/** Extra environment variables for the child process */
 	env?: Record<string, string>;
+	/**
+	 * Callback invoked when agent_end fires, before stdin is closed.
+	 * Receives the last assistant message text.
+	 * Return a string to send as a new prompt (re-prompt the agent),
+	 * or null to close the session normally.
+	 *
+	 * @since TP-172
+	 */
+	onPrematureExit?: (assistantMessage: string) => Promise<string | null>;
+	/**
+	 * Maximum number of exit interceptions before forcing session close.
+	 * Prevents infinite loops where the callback always returns a new prompt.
+	 * Default: 2
+	 *
+	 * @since TP-172
+	 */
+	maxExitInterceptions?: number;
 }
 
 /**
@@ -235,6 +252,7 @@ export function spawnAgent(
 	const cliPath = resolvePiCliPath();
 	const closeDelayMs = opts.closeDelayMs ?? 100;
 	const timeoutMs = opts.timeoutMs ?? 0;
+	const maxExitInterceptions = opts.maxExitInterceptions ?? 3;
 
 	// Build Pi CLI arguments
 	const piArgs: string[] = [cliPath, "--mode", "rpc", "--no-session"];
@@ -275,6 +293,12 @@ export function spawnAgent(
 	let contextUsage: AgentHostResult["contextUsage"] = null;
 	let stderrBuffer = "";
 	const STDERR_MAX = 2048;
+	/** Last assistant message text captured from message_end events (TP-172) */
+	let lastAssistantMessage = "";
+	/** Number of times exit interception has occurred (TP-172) */
+	let exitInterceptionCount = 0;
+	/** Whether the current turn had any tool calls (TP-172: text-only gate) */
+	let currentTurnHadToolCalls = false;
 
 	// Timeout
 	let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
@@ -538,6 +562,8 @@ export function spawnAgent(
 							const content = extractAssistantText(event.message);
 							if (content) {
 								emitEvent("assistant_message", { text: truncatePayload(content, MAX_CONV_PAYLOAD_CHARS) });
+								// TP-172: Track last assistant message for exit interception
+								lastAssistantMessage = content;
 							}
 						}
 						// Request session stats immediately on first assistant message,
@@ -560,6 +586,7 @@ export function spawnAgent(
 					}
 					case "tool_execution_start": {
 						toolCalls++;
+						currentTurnHadToolCalls = true;
 						const toolName = event.toolName || "tool";
 						const argPreview = typeof event.args === "string" ? event.args.slice(0, 300) :
 							(event.args && typeof Object.values(event.args)[0] === "string" ? String(Object.values(event.args)[0]).slice(0, 300) : "");
@@ -602,7 +629,79 @@ export function spawnAgent(
 					}
 					case "agent_end": {
 						agentEnded = true;
-						closeStdin();
+						// TP-172: Exit interception — intercept any exit when callback
+						// is provided and under limit. The callback (lane-runner) decides
+						// whether the worker made progress. We don't gate on tool calls
+						// because workers commonly use tools (reads/greps) then exit
+						// with a text declaration ("Now let me fix this:") without
+						// actually making the edit.
+						const shouldIntercept = opts.onPrematureExit
+							&& exitInterceptionCount < maxExitInterceptions;
+						if (shouldIntercept) {
+							exitInterceptionCount++;
+							const INTERCEPTION_TIMEOUT_MS = 120_000; // 2 minute safety timeout
+							// Wrap in Promise.resolve().then() to catch synchronous throws
+							const interceptPromise = Promise.resolve().then(() =>
+								opts.onPrematureExit!(lastAssistantMessage));
+							const timeoutPromise = new Promise<null>((res) =>
+								setTimeout(() => res(null), INTERCEPTION_TIMEOUT_MS));
+							Promise.race([interceptPromise, timeoutPromise])
+								.then(
+									(newPrompt: string | null) => {
+										if (newPrompt && !stdinClosed && proc.stdin && !proc.stdin.destroyed) {
+											// Re-prompt the agent with supervisor guidance
+											agentEnded = false; // Reset for the new turn
+											currentTurnHadToolCalls = false; // Reset for new turn
+											proc.stdin.write(JSON.stringify({ type: "prompt", message: newPrompt }) + "\n");
+											emitEvent("exit_intercepted", {
+												interceptionCount: exitInterceptionCount,
+												assistantMessage: truncatePayload(lastAssistantMessage, 500),
+												supervisorConsulted: true,
+												action: "reprompt",
+												newPromptPreview: truncatePayload(newPrompt, MAX_CONV_PAYLOAD_CHARS),
+											});
+										} else {
+											// Callback returned null or stdin already closed — close session
+											const reason = stdinClosed ? "stdin_closed"
+												: newPrompt === null ? "callback_returned_null"
+												: "unknown";
+											emitEvent("exit_intercepted", {
+												interceptionCount: exitInterceptionCount,
+												assistantMessage: truncatePayload(lastAssistantMessage, 500),
+												supervisorConsulted: true,
+												action: "close",
+												reason,
+											});
+											closeStdin();
+										}
+									},
+									(err: unknown) => {
+										// Callback rejected — emit single diagnostic event and close
+										const msg = err instanceof Error ? err.message : String(err);
+										emitEvent("exit_intercepted", {
+											interceptionCount: exitInterceptionCount,
+											assistantMessage: truncatePayload(lastAssistantMessage, 500),
+											supervisorConsulted: false,
+											action: "close",
+											reason: "callback_error",
+											error: msg,
+										});
+										closeStdin();
+									},
+								);
+						} else {
+							// No callback, had tool calls, or interception limit reached — close normally
+							if (opts.onPrematureExit && exitInterceptionCount >= maxExitInterceptions) {
+								emitEvent("exit_intercepted", {
+									interceptionCount: exitInterceptionCount,
+									assistantMessage: truncatePayload(lastAssistantMessage, 500),
+									supervisorConsulted: false,
+									action: "close",
+									reason: "max_interceptions_reached",
+								});
+							}
+							closeStdin();
+						}
 						break;
 					}
 				}

package/extensions/taskplane/cleanup.ts

@@ -1,19 +1,26 @@
 /**
  * Artifact cleanup and log rotation for orchestrator runtime files.
  *
- * Three cleanup layers prevent unbounded disk growth:
+ * 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 and
- *    merge artifacts older than 7 days. Catches files missed by Layer 1
- *    (e.g., aborted batches, manual branch deletions).
+ * 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
@@ -177,8 +184,8 @@ export function formatPostIntegrateCleanup(result: PostIntegrateCleanupResult):
 
 // ── Layer 2: Age-Based Preflight Sweep ──────────────────────────────
 
-/** Default max age for stale artifacts (7 days in milliseconds). */
-export const STALE_ARTIFACT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** 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.
@@ -215,13 +222,16 @@ export interface SweepDeps {
  * - `.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: 7 days)
+ * @param maxAgeMs - Maximum file age in milliseconds (default: 3 days)
  * @returns Sweep result with count and warnings
  */
 export function sweepStaleArtifacts(
@@ -289,7 +299,17 @@ export function sweepStaleArtifacts(
 		(name.startsWith("merge-request-") && name.endsWith(".txt")),
 	);
 
-	// Sweep stale batch directories under a parent (mailbox, context-snapshots)
+	// 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 {
@@ -318,6 +338,9 @@ export function sweepStaleArtifacts(
 	// 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;
 }
 
@@ -336,7 +359,7 @@ export function formatPreflightSweep(result: PreflightSweepResult): string {
 		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 ")} (>7 days old)`);
+		parts.push(`🧹 Preflight cleanup: removed ${segments.join(" and ")} (>3 days old)`);
 	}
 	for (const warning of result.warnings) {
 		parts.push(`  ⚠️ ${warning}`);
@@ -424,6 +447,245 @@ export function formatLogRotation(result: LogRotationResult): string {
 	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 ──────────────────────────────────────
 
 /**
@@ -466,7 +728,7 @@ export function formatPreflightCleanup(result: PreflightCleanupResult): string {
 		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 ")} (>7 days old)`);
+		parts.push(`removed ${segments.join(" and ")} (>3 days old)`);
 	}
 
 	// Layer 3: log rotation