taskplane 0.15.0 → 0.17.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");

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

@@ -46,6 +46,8 @@ import {
 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,
@@ -976,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;
@@ -1493,6 +1501,23 @@ export default function (pi: ExtensionAPI) {
 			};
 		}
 
+		// TP-063: Run additive migrations before batch start (primary trigger).
+		// Non-fatal — failures warn but never block batch execution.
+		try {
+			const migrationResult = runMigrations(execCtx.repoRoot);
+			if (migrationResult.messages.length > 0) {
+				ctx.ui.notify(migrationResult.messages.join("\n"), "info");
+			}
+			if (migrationResult.errors.length > 0) {
+				ctx.ui.notify(
+					`⚠️ Migration warnings:\n${migrationResult.errors.map(e => `  ⚠ ${e.id}: ${e.error}`).join("\n")}`,
+					"warning",
+				);
+			}
+		} catch {
+			// Swallow — migrations must never block /orch
+		}
+
 		// TP-128: Transition from routing-mode supervisor to batch execution
 		if (supervisorState.active && supervisorState.routingContext) {
 			await deactivateSupervisor(pi, supervisorState);
@@ -2264,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.`;
@@ -2853,6 +2901,19 @@ export default function (pi: ExtensionAPI) {
 			supervisorConfig = { ...DEFAULT_SUPERVISOR_CONFIG };
 		}
 
+		// TP-063: Run additive migrations on session start (safety net trigger).
+		// This ensures migrations run even if the user doesn't invoke /orch.
+		// Non-fatal — failures are silently swallowed so startup is never blocked.
+		try {
+			const migrationResult = runMigrations(execCtx.repoRoot);
+			if (migrationResult.messages.length > 0) {
+				ctx.ui.notify(migrationResult.messages.join("\n"), "info");
+			}
+			// Errors on session_start are silent — avoid noisy warnings at startup
+		} catch {
+			// Swallow — migrations must never block session startup
+		}
+
 		// Set status line
 		const areaCount = Object.keys(runnerConfig.task_areas).length;
 		const modeLabel = execCtx.mode === "workspace" ? "workspace" : "repo";

package/extensions/taskplane/index.ts

@@ -24,3 +24,5 @@ export * from "./abort.ts";
 export * from "./workspace.ts";
 export * from "./diagnostics.ts";
 export * from "./supervisor.ts";
+export * from "./migrations.ts";
+export * from "./cleanup.ts";

package/extensions/taskplane/migrations.ts

@@ -0,0 +1,275 @@
+/**
+ * Additive Upgrade Migrations for Taskplane
+ *
+ * Provides a lightweight migration runner that applies additive-only
+ * changes (e.g., creating missing scaffold files) when extensions load
+ * or `/orch` starts. Migrations never overwrite existing files.
+ *
+ * Migration state is tracked in `.pi/taskplane.json` under the
+ * `migrations` key, preserving all existing version-tracker fields.
+ *
+ * @module migrations
+ * @since TP-063
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/**
+ * Metadata for a single additive migration.
+ */
+export interface Migration {
+	/** Unique, stable identifier (e.g., "add-supervisor-local-template-v1") */
+	id: string;
+	/** Human-readable description for logs */
+	description: string;
+	/**
+	 * Execute the migration. Should only create files that don't exist.
+	 *
+	 * @param projectRoot - Project root directory
+	 * @param packageRoot - Taskplane package root (for template resolution)
+	 * @returns A short message describing what was created, or null if skipped (already exists)
+	 * @throws If the migration cannot complete (e.g., missing template source)
+	 */
+	run(projectRoot: string, packageRoot: string): string | null;
+}
+
+/**
+ * Record of a single applied migration in `.pi/taskplane.json`.
+ */
+export interface AppliedMigration {
+	/** ISO timestamp when the migration was applied */
+	appliedAt: string;
+}
+
+/**
+ * The `migrations` section within `.pi/taskplane.json`.
+ */
+export interface MigrationState {
+	applied: Record<string, AppliedMigration>;
+}
+
+/**
+ * Shape of `.pi/taskplane.json` (partial — only fields we read/write).
+ * Other fields (version, installedAt, lastUpgraded, components) are
+ * preserved as-is during read-modify-write.
+ */
+export interface TaskplaneMeta {
+	[key: string]: unknown;
+	migrations?: MigrationState;
+}
+
+/**
+ * Result of running migrations.
+ */
+export interface MigrationRunResult {
+	/** Migration IDs that were applied in this run */
+	applied: string[];
+	/** Migration IDs that were skipped (already applied or target exists) */
+	skipped: string[];
+	/** Migrations that failed with errors (non-fatal — logged and skipped) */
+	errors: Array<{ id: string; error: string }>;
+	/** Human-readable messages for each applied migration */
+	messages: string[];
+}
+
+// ── Meta File Helpers ────────────────────────────────────────────────
+
+const TASKPLANE_META_FILENAME = "taskplane.json";
+
+/**
+ * Load `.pi/taskplane.json`, returning its content or an empty object
+ * if the file doesn't exist or is malformed.
+ *
+ * Never throws — returns `{}` for any read/parse error.
+ */
+export function loadTaskplaneMeta(projectRoot: string): TaskplaneMeta {
+	const metaPath = join(projectRoot, ".pi", TASKPLANE_META_FILENAME);
+	try {
+		if (!existsSync(metaPath)) return {};
+		const raw = readFileSync(metaPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+		return parsed as TaskplaneMeta;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Save `.pi/taskplane.json`, merging the provided meta with any
+ * existing content. Creates the `.pi/` directory if needed.
+ *
+ * Performs a shallow merge at the top level — existing keys not in
+ * `meta` are preserved. The `migrations` key is always taken from
+ * the provided `meta` object (deep replacement).
+ */
+export function saveTaskplaneMeta(projectRoot: string, meta: TaskplaneMeta): void {
+	const piDir = join(projectRoot, ".pi");
+	mkdirSync(piDir, { recursive: true });
+
+	const metaPath = join(piDir, TASKPLANE_META_FILENAME);
+
+	// Read existing content to preserve version-tracker fields
+	let existing: TaskplaneMeta = {};
+	try {
+		if (existsSync(metaPath)) {
+			const raw = readFileSync(metaPath, "utf-8");
+			const parsed = JSON.parse(raw);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				existing = parsed as TaskplaneMeta;
+			}
+		}
+	} catch {
+		// Existing file unreadable — start fresh but we'll overwrite only our keys
+	}
+
+	// Merge: existing fields preserved, our fields override
+	const merged = { ...existing, ...meta };
+	writeFileSync(metaPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+
+// ── Package Root Resolution ──────────────────────────────────────────
+
+/**
+ * Resolve the taskplane package root directory.
+ *
+ * Uses ESM `import.meta.url` to compute the path deterministically.
+ * The package root is two levels up from this file:
+ *   `<package-root>/extensions/taskplane/migrations.ts`
+ *
+ * @param importMetaUrl - Pass `import.meta.url` from the calling module
+ * @returns Absolute path to the package root
+ */
+export function resolvePackageRoot(importMetaUrl?: string): string {
+	const url = importMetaUrl ?? import.meta.url;
+	const thisDir = dirname(fileURLToPath(url));
+	// extensions/taskplane/ → extensions/ → package root
+	return join(thisDir, "..", "..");
+}
+
+// ── Migration Registry ──────────────────────────────────────────────
+
+/**
+ * Registry of all additive migrations, ordered by creation date.
+ *
+ * New migrations are appended to this array. Each migration must:
+ * - Have a unique, stable `id` (never renamed after release)
+ * - Only create files that don't exist (additive-only)
+ * - Throw on unrecoverable errors (e.g., missing template source)
+ * - Return null if the target already exists (skip)
+ */
+export const MIGRATION_REGISTRY: Migration[] = [
+	{
+		id: "add-supervisor-local-template-v1",
+		description: "Create .pi/agents/supervisor.md from template if missing",
+		run(projectRoot: string, packageRoot: string): string | null {
+			const targetPath = join(projectRoot, ".pi", "agents", "supervisor.md");
+
+			// Skip if file already exists — never overwrite
+			if (existsSync(targetPath)) {
+				return null;
+			}
+
+			// Resolve template source
+			const templatePath = join(packageRoot, "templates", "agents", "local", "supervisor.md");
+			if (!existsSync(templatePath)) {
+				throw new Error(
+					`Migration template not found: ${templatePath}. ` +
+					`This may indicate a packaging issue with the taskplane package.`,
+				);
+			}
+
+			// Create target directory and copy template
+			mkdirSync(dirname(targetPath), { recursive: true });
+			copyFileSync(templatePath, targetPath);
+
+			return "Created .pi/agents/supervisor.md from template";
+		},
+	},
+];
+
+// ── Migration Runner ─────────────────────────────────────────────────
+
+/**
+ * Run all pending additive migrations.
+ *
+ * Loads migration state from `.pi/taskplane.json`, runs only unapplied
+ * migrations from the registry, and persists applied IDs + timestamps.
+ *
+ * Each migration is individually try/caught:
+ * - Success → recorded as applied, message logged
+ * - Skip (returns null) → recorded as applied (target already exists)
+ * - Error → logged and skipped (NOT recorded — will be retried next time)
+ *
+ * @param projectRoot - Project root directory
+ * @param packageRoot - Taskplane package root (for template resolution).
+ *                      If omitted, resolved from import.meta.url.
+ * @returns Migration run result with applied/skipped/error details
+ */
+export function runMigrations(
+	projectRoot: string,
+	packageRoot?: string,
+): MigrationRunResult {
+	const pkgRoot = packageRoot ?? resolvePackageRoot();
+	const result: MigrationRunResult = {
+		applied: [],
+		skipped: [],
+		errors: [],
+		messages: [],
+	};
+
+	// Load current state
+	const meta = loadTaskplaneMeta(projectRoot);
+	const migrationState: MigrationState = meta.migrations ?? { applied: {} };
+
+	let stateChanged = false;
+
+	for (const migration of MIGRATION_REGISTRY) {
+		// Skip already-applied migrations
+		if (migrationState.applied[migration.id]) {
+			result.skipped.push(migration.id);
+			continue;
+		}
+
+		try {
+			const message = migration.run(projectRoot, pkgRoot);
+
+			// Record as applied (whether it created something or skipped)
+			migrationState.applied[migration.id] = {
+				appliedAt: new Date().toISOString(),
+			};
+			stateChanged = true;
+
+			if (message) {
+				result.applied.push(migration.id);
+				result.messages.push(`📦 Migration: ${message}`);
+			} else {
+				// Target already existed — still mark as applied so we don't recheck
+				result.skipped.push(migration.id);
+			}
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			result.errors.push({ id: migration.id, error: errMsg });
+			// NOT recorded as applied — will be retried next time
+		}
+	}
+
+	// Persist state if anything changed
+	if (stateChanged) {
+		try {
+			saveTaskplaneMeta(projectRoot, { ...meta, migrations: migrationState });
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			result.errors.push({
+				id: "__state_save",
+				error: `Failed to persist migration state: ${errMsg}`,
+			});
+		}
+	}
+
+	return result;
+}

package/package.json

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