taskplane 0.29.2 → 0.30.0

package/extensions/taskplane/cleanup.ts

@@ -64,7 +64,10 @@ export interface PostIntegrateCleanupResult {
  * @param batchId - Batch ID to scope deletion
  * @returns Cleanup result with counts and warnings
  */
-export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIntegrateCleanupResult {
+export function cleanupPostIntegrate(
+	stateRoot: string,
+	batchId: string,
+): PostIntegrateCleanupResult {
 	const result: PostIntegrateCleanupResult = {
 		telemetryFilesDeleted: 0,
 		mergeFilesDeleted: 0,
@@ -116,10 +119,11 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 		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"))
-				)) {
+				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++;
@@ -140,7 +144,9 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 			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}`);
+			result.warnings.push(
+				`Failed to delete mailbox directory ${mailboxBatchDir}: ${(err as Error).message}`,
+			);
 		}
 	}
 
@@ -151,7 +157,9 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
 			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}`);
+			result.warnings.push(
+				`Failed to delete context-snapshots directory ${snapshotBatchDir}: ${(err as Error).message}`,
+			);
 		}
 	}
 
@@ -163,7 +171,12 @@ export function cleanupPostIntegrate(stateRoot: string, batchId: string): PostIn
  */
 export function formatPostIntegrateCleanup(result: PostIntegrateCleanupResult): string {
 	const parts: string[] = [];
-	const totalDeleted = result.telemetryFilesDeleted + result.mergeFilesDeleted + result.promptFilesDeleted + result.mailboxDirsDeleted + result.snapshotDirsDeleted;
+	const totalDeleted =
+		result.telemetryFilesDeleted +
+		result.mergeFilesDeleted +
+		result.promptFilesDeleted +
+		result.mailboxDirsDeleted +
+		result.snapshotDirsDeleted;
 
 	if (totalDeleted > 0) {
 		const segments: string[] = [];
@@ -287,26 +300,32 @@ export function sweepStaleArtifacts(
 	};
 
 	// Sweep telemetry files
-	sweepDir(join(stateRoot, ".pi", "telemetry"), (name) =>
-		name.endsWith(".jsonl") ||
-		name.endsWith("-exit.json") ||
-		(name.startsWith("lane-prompt-") && name.endsWith(".txt")),
+	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")),
+	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"),
+	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"),
+	sweepDir(
+		join(stateRoot, ".pi"),
+		(name) => name.startsWith("lane-state-") && name.endsWith(".json"),
 	);
 
 	// Sweep stale batch directories under a parent (mailbox, context-snapshots, verification)
@@ -328,7 +347,9 @@ export function sweepStaleArtifacts(
 				}
 			}
 		} catch (err: unknown) {
-			result.warnings.push(`Failed to read ${label} directory ${parentDir}: ${(err as Error).message}`);
+			result.warnings.push(
+				`Failed to read ${label} directory ${parentDir}: ${(err as Error).message}`,
+			);
 		}
 	};
 
@@ -351,7 +372,11 @@ 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) {
+	if (
+		result.staleFilesDeleted === 0 &&
+		result.staleDirsDeleted === 0 &&
+		result.warnings.length === 0
+	) {
 		return ""; // Nothing to report
 	}
 	const parts: string[] = [];
@@ -621,27 +646,27 @@ export function cleanupPriorBatchArtifacts(
 	};
 
 	// 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")),
+	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")),
+	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"),
-	);
+	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"),
-	);
+	cleanDir(piDir, (name) => name.startsWith("lane-state-") && name.endsWith(".json"));
 
 	// Clean batch-scoped directories (mailbox, context-snapshots)
 	const cleanBatchDirs = (parentDir: string): void => {
@@ -678,7 +703,9 @@ 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)`);
+		parts.push(
+			`🧹 Prior batch cleanup: removed ${result.itemsDeleted} artifact(s) from previous batch(es)`,
+		);
 	}
 	for (const warning of result.warnings) {
 		parts.push(`  ⚠️ ${warning}`);
@@ -706,10 +733,7 @@ export interface PreflightCleanupResult {
  * @param deps - Sweep dependencies (active batch check)
  * @returns Combined cleanup result
  */
-export function runPreflightCleanup(
-	stateRoot: string,
-	deps: SweepDeps,
-): PreflightCleanupResult {
+export function runPreflightCleanup(stateRoot: string, deps: SweepDeps): PreflightCleanupResult {
 	const sweep = sweepStaleArtifacts(stateRoot, deps);
 	const rotation = rotateSupervisorLogs(stateRoot);
 	return { sweep, rotation };
@@ -724,10 +748,15 @@ 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)) {
+	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)`);
+		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)`);
 	}
 

package/extensions/taskplane/config-loader.ts

@@ -43,9 +43,9 @@ import type {
 	OrchestratorSection,
 	WorkspaceSectionConfig,
 	GlobalPreferences,
+	DeepPartial,
 } from "./config-schema.ts";
 
-
 // ── Error Types ──────────────────────────────────────────────────────
 
 /**
@@ -72,7 +72,6 @@ export class ConfigLoadError extends Error {
 	}
 }
 
-
 // ── Deep Clone Helper ────────────────────────────────────────────────
 
 /** Deep clone a config object to avoid cross-call mutation. */
@@ -80,7 +79,6 @@ function deepClone<T>(obj: T): T {
 	return JSON.parse(JSON.stringify(obj));
 }
 
-
 // ── Deep Merge Helper ────────────────────────────────────────────────
 
 /**
@@ -176,12 +174,16 @@ function migrateGlobalPreferences(raw: Record<string, any>, prefsPath: string):
 	}
 	if (raw.orchestrator?.orchestrator?.spawnMode === "tmux") {
 		raw.orchestrator.orchestrator.spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated global preference: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`);
+		console.error(
+			`[taskplane] Auto-migrated global preference: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`,
+		);
 		migrated = true;
 	}
 	if (raw.taskRunner?.worker?.spawnMode === "tmux") {
 		raw.taskRunner.worker.spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated global preference: taskRunner.worker.spawnMode "tmux" → "subprocess"`);
+		console.error(
+			`[taskplane] Auto-migrated global preference: taskRunner.worker.spawnMode "tmux" → "subprocess"`,
+		);
 		migrated = true;
 	}
 	if (migrated) {
@@ -191,15 +193,18 @@ function migrateGlobalPreferences(raw: Record<string, any>, prefsPath: string):
 			renameSync(tmpPath, prefsPath);
 			console.error(`[taskplane] Preferences file updated: ${prefsPath}`);
 		} catch (err) {
-			console.error(`[taskplane] Warning: could not persist preferences migration to disk: ${err instanceof Error ? err.message : err}`);
+			console.error(
+				`[taskplane] Warning: could not persist preferences migration to disk: ${err instanceof Error ? err.message : err}`,
+			);
 		}
 	}
 	return migrated;
 }
 
 /** Reset migration guard (for testing). @internal */
-export function _resetMigrationGuard(): void { _projectMigrationDone = false; }
-
+export function _resetMigrationGuard(): void {
+	_projectMigrationDone = false;
+}
 
 // ── YAML snake_case → camelCase Mapping ──────────────────────────────
 
@@ -300,7 +305,8 @@ function mapTaskRunnerYaml(raw: any): Partial<TaskRunnerSection> {
 
 	// Record sections with structural inner keys
 	if (raw.task_areas) result.taskAreas = convertRecordSection(raw.task_areas);
-	if (raw.standards_overrides) result.standardsOverrides = convertRecordSection(raw.standards_overrides);
+	if (raw.standards_overrides)
+		result.standardsOverrides = convertRecordSection(raw.standards_overrides);
 
 	// Flat record sections (keys are identifiers, values are strings)
 	if (raw.reference_docs) result.referenceDocs = preserveRecord(raw.reference_docs);
@@ -341,7 +347,8 @@ function mapOrchestratorYaml(raw: any): Partial<OrchestratorSection> {
 	if (raw.assignment) {
 		result.assignment = {};
 		if (raw.assignment.strategy !== undefined) result.assignment.strategy = raw.assignment.strategy;
-		if (raw.assignment.size_weights) result.assignment.sizeWeights = preserveRecord(raw.assignment.size_weights);
+		if (raw.assignment.size_weights)
+			result.assignment.sizeWeights = preserveRecord(raw.assignment.size_weights);
 	}
 
 	// pre_warm: auto_detect is structural, commands is user-defined, always is array
@@ -398,9 +405,11 @@ function normalizeWorkspaceSection(
 		};
 	}
 
-	const defaultRepo = typeof rawRouting.defaultRepo === "string" ? rawRouting.defaultRepo.trim() : "";
+	const defaultRepo =
+		typeof rawRouting.defaultRepo === "string" ? rawRouting.defaultRepo.trim() : "";
 	const tasksRoot = typeof rawRouting.tasksRoot === "string" ? rawRouting.tasksRoot.trim() : "";
-	let taskPacketRepo = typeof rawRouting.taskPacketRepo === "string" ? rawRouting.taskPacketRepo.trim() : "";
+	let taskPacketRepo =
+		typeof rawRouting.taskPacketRepo === "string" ? rawRouting.taskPacketRepo.trim() : "";
 
 	if (!taskPacketRepo && defaultRepo) {
 		taskPacketRepo = defaultRepo;
@@ -426,7 +435,6 @@ function normalizeWorkspaceSection(
 	};
 }
 
-
 // ── Config File Path Resolution ──────────────────────────────────────
 
 /**
@@ -464,7 +472,7 @@ function resolveConfigFilePath(configRoot: string, filename: string): string {
  * Returns the parsed config or null if the file doesn't exist.
  * Throws ConfigLoadError for malformed JSON or unsupported versions.
  */
-function loadJsonConfig(configRoot: string): Partial<TaskplaneConfig> | null {
+function loadJsonConfig(configRoot: string): DeepPartial<TaskplaneConfig> | null {
 	const jsonPath = resolveConfigFilePath(configRoot, PROJECT_CONFIG_FILENAME);
 	if (!existsSync(jsonPath)) return null;
 
@@ -490,7 +498,7 @@ function loadJsonConfig(configRoot: string): Partial<TaskplaneConfig> | null {
 		throw new ConfigLoadError(
 			"CONFIG_VERSION_MISSING",
 			`${jsonPath} is missing required field "configVersion". ` +
-			`Expected configVersion: ${CONFIG_VERSION}.`,
+				`Expected configVersion: ${CONFIG_VERSION}.`,
 		);
 	}
 
@@ -498,15 +506,23 @@ function loadJsonConfig(configRoot: string): Partial<TaskplaneConfig> | null {
 		throw new ConfigLoadError(
 			"CONFIG_VERSION_UNSUPPORTED",
 			`${jsonPath} has configVersion ${parsed.configVersion}, but this version of Taskplane ` +
-			`only supports configVersion ${CONFIG_VERSION}. Please upgrade Taskplane.`,
+				`only supports configVersion ${CONFIG_VERSION}. Please upgrade Taskplane.`,
 		);
 	}
 
-	const overrides: Partial<TaskplaneConfig> = {};
-	if (parsed.taskRunner && typeof parsed.taskRunner === "object" && !Array.isArray(parsed.taskRunner)) {
+	const overrides: DeepPartial<TaskplaneConfig> = {};
+	if (
+		parsed.taskRunner &&
+		typeof parsed.taskRunner === "object" &&
+		!Array.isArray(parsed.taskRunner)
+	) {
 		overrides.taskRunner = deepClone(parsed.taskRunner);
 	}
-	if (parsed.orchestrator && typeof parsed.orchestrator === "object" && !Array.isArray(parsed.orchestrator)) {
+	if (
+		parsed.orchestrator &&
+		typeof parsed.orchestrator === "object" &&
+		!Array.isArray(parsed.orchestrator)
+	) {
 		overrides.orchestrator = deepClone(parsed.orchestrator);
 	}
 	if (parsed.workspace) {
@@ -519,7 +535,6 @@ function loadJsonConfig(configRoot: string): Partial<TaskplaneConfig> | null {
 	return overrides;
 }
 
-
 // ── YAML Loading ─────────────────────────────────────────────────────
 
 /**
@@ -612,7 +627,6 @@ function loadWorkspaceYaml(configRoot: string): WorkspaceSectionConfig | undefin
 	}
 }
 
-
 // ── Global Preferences (Layer 2) ─────────────────────────────────────
 
 /**
@@ -703,7 +717,12 @@ export function loadGlobalPreferencesWithMeta(): GlobalPreferencesLoadResult {
 		};
 	}
 
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || Object.keys(parsed).length === 0) {
+	if (
+		!parsed ||
+		typeof parsed !== "object" ||
+		Array.isArray(parsed) ||
+		Object.keys(parsed).length === 0
+	) {
 		return {
 			preferences: bootstrapGlobalPreferencesFile(prefsPath),
 			wasBootstrapped: true,
@@ -730,7 +749,9 @@ export function loadGlobalPreferences(): GlobalPreferences {
  * Unknown keys are silently dropped — this is the Layer 2 boundary guardrail.
  */
 function normalizePreferenceThinkingMode(value: unknown): string {
-	const cleaned = String(value ?? "").trim().toLowerCase();
+	const cleaned = String(value ?? "")
+		.trim()
+		.toLowerCase();
 	if (!cleaned || cleaned === "inherit") return "";
 	if (cleaned === "on") return "high";
 	if (["off", "minimal", "low", "medium", "high", "xhigh"].includes(cleaned)) {
@@ -739,7 +760,9 @@ function normalizePreferenceThinkingMode(value: unknown): string {
 	return "";
 }
 
-function extractInitAgentDefaults(rawInitDefaults: unknown): GlobalPreferences["initAgentDefaults"] | undefined {
+function extractInitAgentDefaults(
+	rawInitDefaults: unknown,
+): GlobalPreferences["initAgentDefaults"] | undefined {
 	if (!rawInitDefaults || typeof rawInitDefaults !== "object" || Array.isArray(rawInitDefaults)) {
 		return undefined;
 	}
@@ -750,9 +773,12 @@ function extractInitAgentDefaults(rawInitDefaults: unknown): GlobalPreferences["
 	if (typeof raw.workerModel === "string") extracted.workerModel = raw.workerModel;
 	if (typeof raw.reviewerModel === "string") extracted.reviewerModel = raw.reviewerModel;
 	if (typeof raw.mergeModel === "string") extracted.mergeModel = raw.mergeModel;
-	if (raw.workerThinking !== undefined) extracted.workerThinking = normalizePreferenceThinkingMode(raw.workerThinking);
-	if (raw.reviewerThinking !== undefined) extracted.reviewerThinking = normalizePreferenceThinkingMode(raw.reviewerThinking);
-	if (raw.mergeThinking !== undefined) extracted.mergeThinking = normalizePreferenceThinkingMode(raw.mergeThinking);
+	if (raw.workerThinking !== undefined)
+		extracted.workerThinking = normalizePreferenceThinkingMode(raw.workerThinking);
+	if (raw.reviewerThinking !== undefined)
+		extracted.reviewerThinking = normalizePreferenceThinkingMode(raw.reviewerThinking);
+	if (raw.mergeThinking !== undefined)
+		extracted.mergeThinking = normalizePreferenceThinkingMode(raw.mergeThinking);
 
 	return Object.keys(extracted).length > 0 ? extracted : undefined;
 }
@@ -764,7 +790,10 @@ function extractConfigOverrideSection(rawSection: unknown): Record<string, any>
 	return deepClone(rawSection as Record<string, any>);
 }
 
-function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: string): GlobalPreferences {
+function extractAllowlistedPreferences(
+	raw: Record<string, any>,
+	prefsPath: string,
+): GlobalPreferences {
 	migrateGlobalPreferences(raw, prefsPath);
 
 	const prefs: GlobalPreferences = {};
@@ -821,27 +850,46 @@ function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: stri
  * Preferences-only fields (`dashboardPort`, `initAgentDefaults`) are preserved
  * in `GlobalPreferences` but intentionally not merged into runtime config.
  */
-export function applyGlobalPreferences(config: TaskplaneConfig, prefs: GlobalPreferences): TaskplaneConfig {
+export function applyGlobalPreferences(
+	config: TaskplaneConfig,
+	prefs: GlobalPreferences,
+): TaskplaneConfig {
 	// Helper: only apply non-empty string values
 	const applyStr = (val: string | undefined, setter: (v: string) => void) => {
 		if (val !== undefined && val !== "") setter(val);
 	};
 
 	// 1) Legacy flat aliases
-	applyStr(prefs.operatorId, (v) => { config.orchestrator.orchestrator.operatorId = v; });
-	applyStr(prefs.sessionPrefix, (v) => { config.orchestrator.orchestrator.sessionPrefix = v; });
-	applyStr(prefs.workerModel, (v) => { config.taskRunner.worker.model = v; });
-	applyStr(prefs.reviewerModel, (v) => { config.taskRunner.reviewer.model = v; });
-	applyStr(prefs.mergeModel, (v) => { config.orchestrator.merge.model = v; });
-	applyStr(prefs.mergeThinking, (v) => { config.orchestrator.merge.thinking = v; });
-	applyStr(prefs.supervisorModel, (v) => { config.orchestrator.supervisor.model = v; });
+	applyStr(prefs.operatorId, (v) => {
+		config.orchestrator.orchestrator.operatorId = v;
+	});
+	applyStr(prefs.sessionPrefix, (v) => {
+		config.orchestrator.orchestrator.sessionPrefix = v;
+	});
+	applyStr(prefs.workerModel, (v) => {
+		config.taskRunner.worker.model = v;
+	});
+	applyStr(prefs.reviewerModel, (v) => {
+		config.taskRunner.reviewer.model = v;
+	});
+	applyStr(prefs.mergeModel, (v) => {
+		config.orchestrator.merge.model = v;
+	});
+	applyStr(prefs.mergeThinking, (v) => {
+		config.orchestrator.merge.thinking = v;
+	});
+	applyStr(prefs.supervisorModel, (v) => {
+		config.orchestrator.supervisor.model = v;
+	});
 
 	// spawnMode: enum — apply if defined (not a string-empty check)
+	// TP-195: dropped dead `prefs.spawnMode === "tmux"` migration check.
+	// `prefs.spawnMode` is typed as `"subprocess"` only (see
+	// `GlobalPreferences.spawnMode` in config-schema.ts). Raw input is
+	// migrated upstream at line ~169 BEFORE assignment to the typed
+	// `prefs` object, so by this point the value is already "subprocess"
+	// or undefined — the comparison can never be true. Behavior-neutral.
 	if (prefs.spawnMode !== undefined) {
-		if (prefs.spawnMode === "tmux") {
-			prefs.spawnMode = "subprocess";
-			console.error(`[taskplane] Auto-migrated runtime preference: spawnMode "tmux" → "subprocess"`);
-		}
 		config.orchestrator.orchestrator.spawnMode = prefs.spawnMode;
 	}
 
@@ -862,11 +910,15 @@ export function applyGlobalPreferences(config: TaskplaneConfig, prefs: GlobalPre
 	// Runtime safety: nested legacy values may arrive through config-shaped overrides.
 	if ((config.orchestrator.orchestrator as Record<string, any>).spawnMode === "tmux") {
 		config.orchestrator.orchestrator.spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated runtime global preference: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`);
+		console.error(
+			`[taskplane] Auto-migrated runtime global preference: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`,
+		);
 	}
 	if ((config.taskRunner.worker as Record<string, any>).spawnMode === "tmux") {
 		config.taskRunner.worker.spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated runtime global preference: taskRunner.worker.spawnMode "tmux" → "subprocess"`);
+		console.error(
+			`[taskplane] Auto-migrated runtime global preference: taskRunner.worker.spawnMode "tmux" → "subprocess"`,
+		);
 	}
 
 	return config;
@@ -891,11 +943,7 @@ export function hasConfigFiles(root: string): boolean {
 	// coordination file, not a project config). Without this distinction,
 	// workspace root's .pi/taskplane-workspace.yaml causes resolveConfigRoot
 	// to short-circuit before checking the pointer-resolved config root (#424).
-	const files = [
-		PROJECT_CONFIG_FILENAME,
-		"task-runner.yaml",
-		"task-orchestrator.yaml",
-	];
+	const files = [PROJECT_CONFIG_FILENAME, "task-runner.yaml", "task-orchestrator.yaml"];
 	for (const f of files) {
 		if (existsSync(join(root, ".pi", f)) || existsSync(join(root, f))) return true;
 	}
@@ -937,12 +985,18 @@ export function resolveConfigRoot(cwd: string, pointerConfigRoot?: string): stri
 	return cwd;
 }
 
-function mergeProjectOverrides(config: TaskplaneConfig, overrides: Partial<TaskplaneConfig>): void {
+function mergeProjectOverrides(
+	config: TaskplaneConfig,
+	overrides: DeepPartial<TaskplaneConfig>,
+): void {
 	if (overrides.taskRunner) {
 		deepMerge(config.taskRunner as Record<string, any>, overrides.taskRunner as Record<string, any>);
 	}
 	if (overrides.orchestrator) {
-		deepMerge(config.orchestrator as Record<string, any>, overrides.orchestrator as Record<string, any>);
+		deepMerge(
+			config.orchestrator as Record<string, any>,
+			overrides.orchestrator as Record<string, any>,
+		);
 	}
 	if (overrides.workspace) {
 		if (!config.workspace || typeof config.workspace !== "object") {
@@ -952,11 +1006,27 @@ function mergeProjectOverrides(config: TaskplaneConfig, overrides: Partial<Taskp
 	}
 }
 
-function migrateProjectOverrides(overrides: Partial<TaskplaneConfig>, configRoot: string): boolean {
+// TP-195: switched parameter to `DeepPartial<TaskplaneConfig>` to match the
+// nested-section partial shape produced by `loadProjectOverrides` (the YAML
+// loaders return `Partial<TaskRunnerSection>` etc., which `Partial<TaskplaneConfig>`
+// rejects — it makes top-level fields optional but inner sections stay full).
+function migrateProjectOverrides(
+	overrides: DeepPartial<TaskplaneConfig>,
+	configRoot: string,
+): boolean {
 	if (_projectMigrationDone) return false;
 
 	let migrated = false;
-	const orchestratorCore = overrides.orchestrator?.orchestrator as Record<string, unknown> | undefined;
+	// TP-195: 2-step `as unknown as` widening. The structurally-typed
+	// `OrchestratorCoreConfig` is being treated as a property bag for
+	// migration purposes (legacy `tmuxPrefix` -> `sessionPrefix`,
+	// `spawnMode "tmux"` -> `"subprocess"`). Both source and target
+	// types are object-shaped at runtime; the cast is structurally
+	// legitimate, just outside the narrow set of conversions TS allows
+	// in a single step.
+	const orchestratorCore = overrides.orchestrator?.orchestrator as unknown as
+		| Record<string, unknown>
+		| undefined;
 	if (orchestratorCore && hasOwn(orchestratorCore, "tmuxPrefix")) {
 		const currentPrefix = orchestratorCore.sessionPrefix;
 		const isDefault = currentPrefix === undefined || currentPrefix === "orch";
@@ -969,11 +1039,17 @@ function migrateProjectOverrides(overrides: Partial<TaskplaneConfig>, configRoot
 	}
 	if (orchestratorCore?.spawnMode === "tmux") {
 		(orchestratorCore as any).spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`);
+		console.error(
+			`[taskplane] Auto-migrated: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`,
+		);
 		migrated = true;
 	}
 
-	const workerConfig = overrides.taskRunner?.worker as Record<string, unknown> | undefined;
+	// TP-195: 2-step `as unknown as` widening (same rationale as the
+	// orchestratorCore cast above).
+	const workerConfig = overrides.taskRunner?.worker as unknown as
+		| Record<string, unknown>
+		| undefined;
 	if (workerConfig?.spawnMode === "tmux") {
 		(workerConfig as any).spawnMode = "subprocess";
 		console.error(`[taskplane] Auto-migrated: taskRunner.worker.spawnMode "tmux" → "subprocess"`);
@@ -1005,7 +1081,9 @@ function migrateProjectOverrides(overrides: Partial<TaskplaneConfig>, configRoot
 				console.error(`[taskplane] Config file updated: ${jsonPath}`);
 			}
 		} catch (err) {
-			console.error(`[taskplane] Warning: could not persist config migration to disk: ${err instanceof Error ? err.message : err}`);
+			console.error(
+				`[taskplane] Warning: could not persist config migration to disk: ${err instanceof Error ? err.message : err}`,
+			);
 		}
 	}
 
@@ -1013,7 +1091,12 @@ function migrateProjectOverrides(overrides: Partial<TaskplaneConfig>, configRoot
 	return migrated;
 }
 
-export function loadProjectOverrides(configRoot: string): Partial<TaskplaneConfig> {
+// TP-195: return type widened from `Partial<TaskplaneConfig>` to
+// `DeepPartial<TaskplaneConfig>` so the nested `Partial<TaskRunnerSection>` /
+// `Partial<OrchestratorSection>` returned by the YAML loaders are
+// assignable. `Partial<TaskplaneConfig>` only relaxes top-level optionality
+// while keeping inner sections fully required.
+export function loadProjectOverrides(configRoot: string): DeepPartial<TaskplaneConfig> {
 	const jsonOverrides = loadJsonConfig(configRoot);
 	if (jsonOverrides !== null) {
 		return jsonOverrides;
@@ -1023,7 +1106,7 @@ export function loadProjectOverrides(configRoot: string): Partial<TaskplaneConfi
 	const orchestrator = loadOrchestratorYaml(configRoot);
 	const workspace = loadWorkspaceYaml(configRoot);
 
-	const overrides: Partial<TaskplaneConfig> = {};
+	const overrides: DeepPartial<TaskplaneConfig> = {};
 	if (Object.keys(taskRunner).length > 0) overrides.taskRunner = taskRunner;
 	if (Object.keys(orchestrator).length > 0) overrides.orchestrator = orchestrator;
 	if (workspace) overrides.workspace = workspace;
@@ -1077,7 +1160,6 @@ export function loadLayer1Config(cwd: string, pointerConfigRoot?: string): Taskp
 	return config;
 }
 
-
 // ── Backward-Compatible Adapters ─────────────────────────────────────
 
 // The following adapter functions convert the unified camelCase config
@@ -1090,7 +1172,9 @@ export function loadLayer1Config(cwd: string, pointerConfigRoot?: string): Taskp
  * to preserve record/dictionary keys verbatim (e.g., sizeWeights S/M/L,
  * preWarm.commands keys, etc.).
  */
-export function toOrchestratorConfig(config: TaskplaneConfig): import("./types.ts").OrchestratorConfig {
+export function toOrchestratorConfig(
+	config: TaskplaneConfig,
+): import("./types.ts").OrchestratorConfig {
 	const o = config.orchestrator;
 	return {
 		orchestrator: {