taskplane 0.16.0 → 0.18.0

package/dashboard/server.cjs

@@ -295,8 +295,18 @@ function tailJsonlFile(filePath) {
     return []; // No new data
   }
 
-  // Read new bytes from offset to end of file
-  const bytesToRead = fileSize - tailState.offset;
+  // Cap read size per tick to avoid ERR_STRING_TOO_LONG on large files.
+  // If there's more data remaining, the next SSE tick will pick up the rest.
+  const MAX_TAIL_BYTES = 10 * 1024 * 1024; // 10 MB per tick
+
+  // Skip-to-tail on fresh dashboard start with large files.
+  // The partial-line handling below already discards the first partial line.
+  if (tailState.offset === 0 && fileSize > MAX_TAIL_BYTES) {
+    tailState.offset = fileSize - MAX_TAIL_BYTES;
+  }
+
+  // Read new bytes from offset, capped to MAX_TAIL_BYTES
+  const bytesToRead = Math.min(fileSize - tailState.offset, MAX_TAIL_BYTES);
   const buf = Buffer.alloc(bytesToRead);
   let fd;
   try {
@@ -311,7 +321,7 @@ function tailJsonlFile(filePath) {
     return []; // Read error — try again next tick
   }
   fs.closeSync(fd);
-  tailState.offset = fileSize;
+  tailState.offset += bytesToRead;
 
   // Split into lines, preserving partial trailing line
   const chunk = tailState.partial + buf.toString("utf-8");
@@ -452,8 +462,11 @@ function loadTelemetryData(batchState) {
                 ? (usage.cost.total || 0)
                 : (typeof usage.cost === "number" ? usage.cost : 0);
             }
-            const totalTokens = usage.totalTokens
+            // Include cacheRead: totalTokens from pi excludes cache reads,
+            // but cached tokens still consume context window capacity.
+            const rawTotal = usage.totalTokens
               || ((usage.input || 0) + (usage.output || 0));
+            const totalTokens = rawTotal + (usage.cacheRead || 0);
             if (totalTokens > acc.latestTotalTokens) {
               acc.latestTotalTokens = totalTokens;
             }

package/extensions/task-runner.ts

@@ -1204,7 +1204,10 @@ function spawnAgent(opts: {
 								// Use totalTokens (cumulative) — works across providers.
 								// Anthropic reports small `input` per-turn but growing `totalTokens`.
 								// OpenAI reports growing `input` but also growing `totalTokens`.
-								const tokens = (usage as any).totalTokens || ((usage as any).input + (usage as any).output) || 0;
+								// Include cacheRead: pi's totalTokens excludes cache reads,
+								// but cached tokens still consume context window capacity.
+								const rawTokens = (usage as any).totalTokens || ((usage as any).input + (usage as any).output) || 0;
+								const tokens = rawTokens + ((usage as any).cacheRead || 0);
 								if (tokens > 0) {
 									const pct = (tokens / opts.contextWindow) * 100;
 									opts.onContextPct?.(pct);
@@ -1380,9 +1383,13 @@ function tailSidecarJsonl(filePath: string, tailState: SidecarTailState): Sideca
 							? (usage.cost.total || 0)
 							: (typeof usage.cost === "number" ? usage.cost : 0);
 					}
-					// totalTokens is cumulative (grows each turn) — use latest value
-					const totalTokens = usage.totalTokens
+					// totalTokens is cumulative (grows each turn) — use latest value.
+					// Include cacheRead tokens: pi's totalTokens and the
+					// input+output fallback both exclude cache reads, but cached
+					// tokens still consume context window capacity.
+					const rawTotal = usage.totalTokens
 						|| ((usage.input || 0) + (usage.output || 0));
+					const totalTokens = rawTotal + (usage.cacheRead || 0);
 					if (totalTokens > delta.latestTotalTokens) {
 						delta.latestTotalTokens = totalTokens;
 					}

package/extensions/taskplane/cleanup.ts

@@ -0,0 +1,416 @@
+/**
+ * Artifact cleanup and log rotation for orchestrator runtime files.
+ *
+ * Three 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).
+ *
+ * 3. **Size-Capped Log Rotation** — Rotates append-only supervisor logs
+ *    (events.jsonl, actions.jsonl) at a 5MB threshold during preflight.
+ *    Keeps one .old generation.
+ *
+ * All cleanup is **non-fatal** — failures warn but never block execution.
+ *
+ * @module orch/cleanup
+ * @since TP-065
+ */
+import { existsSync, readdirSync, statSync, unlinkSync, renameSync, mkdirSync } from "fs";
+import { join } from "path";
+
+// ── 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;
+	/** 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,
+		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}`);
+		}
+	}
+
+	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;
+
+	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`);
+		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 (7 days in milliseconds). */
+export const STALE_ARTIFACT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Result of a preflight age-based sweep.
+ */
+export interface PreflightSweepResult {
+	/** Number of stale files deleted */
+	staleFilesDeleted: 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
+ *
+ * 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)
+ * @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,
+		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")),
+	);
+
+	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.warnings.length === 0) {
+		return ""; // Nothing to report
+	}
+	const parts: string[] = [];
+	if (result.staleFilesDeleted > 0) {
+		parts.push(`🧹 Preflight cleanup: removed ${result.staleFilesDeleted} stale artifact(s) (>7 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");
+}
+
+// ── 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) {
+		parts.push(`removed ${result.sweep.staleFilesDeleted} stale artifact(s) (>7 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("; ")}`;
+}

package/extensions/taskplane/engine.ts

@@ -16,12 +16,13 @@ import { applyMergeRetryLoop, computeCleanupGatePolicy, computeMergeFailurePolic
 import type { CleanupGateRepoFailure } from "./messages.ts";
 import { assembleDiagnosticInput, emitDiagnosticReports } from "./diagnostic-reports.ts";
 import { resolveOperatorId } from "./naming.ts";
-import { applyPartialProgressToOutcomes, buildTier0EventBase, deleteBatchState, emitEngineEvent, emitTier0Event, loadBatchHistory, persistRuntimeState, saveBatchHistory, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
+import { applyPartialProgressToOutcomes, buildTier0EventBase, deleteBatchState, emitEngineEvent, emitTier0Event, loadBatchHistory, loadBatchState, persistRuntimeState, saveBatchHistory, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { listOrchSessions } from "./sessions.ts";
 import { buildEngineEventBase, defaultResilienceState, FATAL_DISCOVERY_CODES, generateBatchId, TIER0_RETRYABLE_CLASSIFICATIONS, TIER0_RETRY_BUDGETS, tier0ScopeKey, tier0WaveScopeKey } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, BatchHistorySummary, BatchTaskSummary, BatchWaveSummary, DiscoveryResult, EngineEventCallback, EscalationContext, LaneExecutionResult, LaneTaskOutcome, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, TaskRunnerConfig, Tier0EscalationPattern, Tier0RecoveryPattern, TokenCounts, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph, computeWaves, resolveBaseBranch, resolveRepoRoot, validateGraph } from "./waves.ts";
 import { deleteBranchBestEffort, forceCleanupWorktree, formatPreflightResults, listWorktrees, preserveFailedLaneProgress, removeAllWorktrees, removeWorktree, runPreflight, safeResetWorktree, sleepSync } from "./worktree.ts";
+import { runPreflightCleanup, formatPreflightCleanup } from "./cleanup.ts";
 
 // ── Tier 0: Automatic Recovery Helpers (TP-039) ─────────────────────
 
@@ -853,6 +854,39 @@ export async function executeOrchBatch(
 		return;
 	}
 
+	// ── TP-065: Preflight artifact cleanup (Layer 2 + Layer 3) ───
+	// Sweep stale artifacts and rotate oversized logs before batch starts.
+	// Always non-fatal — failures warn but never block batch execution.
+	try {
+		// Layer 2: Age-based sweep of stale telemetry/merge artifacts (>7 days)
+		const sweepResult = sweepStaleArtifacts(stateRoot, {
+			isBatchActive: () => {
+				// Check persisted state — a prior batch may still be active
+				try {
+					const state = loadBatchState(stateRoot);
+					if (state && state.phase !== "completed" && state.phase !== "failed" && state.phase !== "stopped") {
+						return true;
+					}
+				} catch { /* state unreadable — safe to sweep */ }
+				return false;
+			},
+			now: () => Date.now(),
+		});
+		const sweepMsg = formatPreflightSweep(sweepResult);
+		if (sweepMsg) {
+			onNotify(sweepMsg, "info");
+		}
+
+		// Layer 3: Size-capped rotation of supervisor append-only logs
+		const rotationResult = rotateSupervisorLogs(stateRoot);
+		const rotationMsg = formatLogRotation(rotationResult);
+		if (rotationMsg) {
+			onNotify(rotationMsg, "info");
+		}
+	} catch {
+		// Non-fatal — never block batch start for cleanup errors
+	}
+
 	// Discovery — task area paths in task-runner.yaml are workspace-relative.
 	// In repo mode workspaceRoot === repoRoot, so this is always correct.
 	const discoveryRoot = workspaceRoot ?? cwd;

package/extensions/taskplane/extension.ts

@@ -47,6 +47,7 @@ import { buildExecutionContext } from "./workspace.ts";
 import { openSettingsTui } from "./settings-tui.ts";
 import { loadProjectConfig } from "./config-loader.ts";
 import { runMigrations } from "./migrations.ts";
+import { cleanupPostIntegrate, formatPostIntegrateCleanup, sweepStaleArtifacts, formatPreflightSweep, rotateSupervisorLogs, formatLogRotation } from "./cleanup.ts";
 import {
 	activateSupervisor,
 	deactivateSupervisor,
@@ -977,6 +978,12 @@ export function buildIntegrationExecutor(repoRoot: string, opId?: string): Integ
 				deleteStaleBranches(repoRoot, opId, context.batchId);
 				dropBatchAutostash(repoRoot, context.batchId);
 			} catch { /* best effort — don't fail integration for cleanup errors */ }
+
+			// TP-065: Post-integrate artifact cleanup (Layer 1).
+			// Also runs on the supervisor auto-integration path.
+			try {
+				cleanupPostIntegrate(repoRoot, context.batchId);
+			} catch { /* best effort — don't fail integration for cleanup errors */ }
 		}
 
 		return result;
@@ -2282,6 +2289,29 @@ export default function (pi: ExtensionAPI) {
 
 		try { deleteBatchState(repoRoot); } catch { /* best effort */ }
 
+		// ── TP-065: Post-integrate artifact cleanup (Layer 1) ────
+		// Delete batch-specific telemetry and merge result files.
+		// Non-fatal — failures warn but don't block integration.
+		if (batchId) {
+			try {
+				const artifactCleanup = cleanupPostIntegrate(repoRoot, batchId);
+				const totalCleaned = artifactCleanup.telemetryFilesDeleted + artifactCleanup.mergeFilesDeleted + artifactCleanup.promptFilesDeleted;
+				if (totalCleaned > 0) {
+					outputLines.push(
+						`🧹 Cleaned up ${artifactCleanup.telemetryFilesDeleted} telemetry file(s), ` +
+						`${artifactCleanup.mergeFilesDeleted} merge result(s), ` +
+						`${artifactCleanup.promptFilesDeleted} prompt file(s) for batch ${batchId}`,
+					);
+				}
+				if (artifactCleanup.warnings.length > 0) {
+					hasWarning = true;
+					outputLines.push(`⚠️ Artifact cleanup warnings: ${artifactCleanup.warnings.join("; ")}`);
+				}
+			} catch {
+				// Non-fatal — never block integration for cleanup failures
+			}
+		}
+
 		const integrationSummary = wsConfig
 			? `✅ Integrated ${resolvedOrchBranch} across ${reposToIntegrate.length} repo(s).\n${repoMessages.join("\n")}\n${totalCommits} total commit(s) applied.`
 			: `${repoMessages[0] || "✅ Integrated."}\n${commitsAhead} commit(s) applied.`;

package/extensions/taskplane/index.ts

@@ -25,3 +25,4 @@ export * from "./workspace.ts";
 export * from "./diagnostics.ts";
 export * from "./supervisor.ts";
 export * from "./migrations.ts";
+export * from "./cleanup.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/local/task-worker.md

@@ -19,6 +19,7 @@ name: task-worker
   - Review protocol (inline reviews via review_step tool when available)
   - Review response handling
   - Test execution strategy (targeted tests during steps, full suite at gate)
+  - File reading strategy (grep-first for large files, context budget awareness)
 
   Add project-specific rules below. Common examples:
   - Preferred package manager (pnpm, yarn, bun)

package/templates/agents/task-worker.md

@@ -265,4 +265,41 @@ checkpoints protect against regressions even when intermediate steps use targete
 2. The merge agent (before merging to the orchestrator branch)
 3. CI (before merging to main)
 
+## File Reading Strategy (Context Budget)
+
+Your context window is finite. Reading large files whole wastes budget and risks
+triggering the context-pressure safety net (85% → wrap-up, 95% → kill).
+Use targeted reads instead:
+
+### Pattern: grep-first, read-with-offset
+
+1. **Locate** the relevant section with `grep` or `find`:
+   ```
+   grep -n "function buildPrompt" extensions/task-runner.ts
+   ```
+2. **Read** just that region with `offset` and `limit`:
+   ```
+   read extensions/task-runner.ts (offset: 1773, limit: 50)
+   ```
+3. **Edit** surgically with exact `oldText → newText`
+
+### When to read a full file
+
+- Files under ~500 lines — read the whole thing, it's fine
+- Config files, test files, templates — usually small enough to read fully
+- New files you're creating — read after writing to verify
+
+### When NOT to read a full file
+
+- Source files over ~1000 lines — grep first, read the relevant region
+- Generated files, lock files, large data files — almost never need full reads
+- Files you've already read this session — re-read only the changed region
+
+### Getting a file outline
+
+To understand a large file's structure without reading it all:
+```bash
+grep -n "^function\|^export\|^class\|^interface\|^const.*=" file.ts | head -50
+```
+