taskplane 0.24.21 → 0.24.22

package/extensions/taskplane/config-loader.ts

@@ -1,19 +1,16 @@
 /**
- * Unified config loader for taskplane-config.json with YAML fallback
- * and user preferences (Layer 2) merge.
+ * Unified config loader for taskplane-config.json with YAML fallback.
  *
- * Layer 1 — Project config precedence:
- *   1. `.pi/taskplane-config.json` exists and is valid → use it
- *   2. `.pi/taskplane-config.json` exists but malformed → throw with clear error
- *   3. `.pi/taskplane-config.json` exists but unsupported configVersion → throw
- *   4. JSON absent + one/both YAML files present → read YAML, map to unified shape
- *   5. None present → return cloned defaults
+ * Effective precedence:
+ *   1. Schema defaults (internal)
+ *   2. Global preferences (`~/.pi/agent/taskplane/preferences.json`)
+ *   3. Project overrides (`taskplane-config.json` or YAML fallback)
  *
- * Layer 2 — User preferences:
- *   After loading Layer 1, reads `~/.pi/agent/taskplane/preferences.json`
- *   (or `$PI_CODING_AGENT_DIR/taskplane/preferences.json`) and applies
- *   allowlisted user-scoped fields on top. Unknown keys are ignored.
- *   Malformed preferences fall back to defaults silently.
+ * Project config is treated as sparse overrides. Missing project fields
+ * fall through to global preferences, then schema defaults.
+ *
+ * Global preferences parsing is allowlist-based. Unknown top-level keys are
+ * ignored, and malformed preferences fall back to defaults silently.
  *
  * Path resolution:
  *   Resolves config paths relative to `configRoot`. Callers should pass
@@ -33,18 +30,17 @@ import {
 	CONFIG_VERSION,
 	PROJECT_CONFIG_FILENAME,
 	DEFAULT_PROJECT_CONFIG,
-	DEFAULT_TASK_RUNNER_SECTION,
-	DEFAULT_ORCHESTRATOR_SECTION,
-	DEFAULT_USER_PREFERENCES,
-	USER_PREFERENCES_FILENAME,
-	USER_PREFERENCES_SUBDIR,
+	DEFAULT_GLOBAL_PREFERENCES,
+	DEFAULT_BOOTSTRAP_GLOBAL_PREFERENCES,
+	GLOBAL_PREFERENCES_FILENAME,
+	GLOBAL_PREFERENCES_SUBDIR,
 } from "./config-schema.ts";
 import type {
 	TaskplaneConfig,
 	TaskRunnerSection,
 	OrchestratorSection,
 	WorkspaceSectionConfig,
-	UserPreferences,
+	GlobalPreferences,
 } from "./config-schema.ts";
 
 
@@ -154,102 +150,36 @@ function normalizeInheritanceAliases(config: TaskplaneConfig): void {
 let _projectMigrationDone = false;
 
 /**
- * Auto-migrate legacy TMUX fields in project config.
- *
- * Precedence: if both `sessionPrefix` and `tmuxPrefix` exist, the new
- * key (`sessionPrefix`) wins. `tmuxPrefix` is only used when `sessionPrefix`
- * is absent. This matches the principle that explicit new-format config
- * takes priority over legacy fields.
- *
- * Writes back to disk atomically (tmp + rename) on first migration.
- * Idempotent — safe to call multiple times per load cycle (skips after first).
- *
- * @returns true if any migrations were applied
- */
-function migrateProjectConfig(config: TaskplaneConfig, configRoot: string): boolean {
-	if (_projectMigrationDone) return false;
-
-	let migrated = false;
-	const orchestratorCore = config.orchestrator?.orchestrator as Record<string, unknown> | undefined;
-	if (orchestratorCore && hasOwn(orchestratorCore, "tmuxPrefix")) {
-		// Use tmuxPrefix if sessionPrefix is absent, undefined, or still the default.
-		// An explicit non-default sessionPrefix takes priority over legacy tmuxPrefix.
-		const currentPrefix = orchestratorCore.sessionPrefix;
-		const isDefault = currentPrefix === undefined || currentPrefix === "orch";
-		if (isDefault) {
-			(orchestratorCore as any).sessionPrefix = orchestratorCore.tmuxPrefix;
-		}
-		delete orchestratorCore.tmuxPrefix;
-		console.error(`[taskplane] Auto-migrated: orchestrator.orchestrator.tmuxPrefix → sessionPrefix`);
-		migrated = true;
-	}
-	if (orchestratorCore?.spawnMode === "tmux") {
-		(orchestratorCore as any).spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`);
-		migrated = true;
-	}
-	const workerConfig = config.taskRunner?.worker as Record<string, unknown> | undefined;
-	if (workerConfig?.spawnMode === "tmux") {
-		(workerConfig as any).spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated: taskRunner.worker.spawnMode "tmux" → "subprocess"`);
-		migrated = true;
-	}
-
-	if (migrated) {
-		// Write back atomically (tmp + rename) to prevent corruption
-		try {
-			const jsonPath = join(configRoot, ".pi", "taskplane-config.json");
-			if (existsSync(jsonPath)) {
-				const raw = JSON.parse(readFileSync(jsonPath, "utf-8"));
-				// Apply same renames to the raw JSON (consistent precedence)
-				if (raw.orchestrator?.orchestrator?.tmuxPrefix !== undefined) {
-					const rawPrefix = raw.orchestrator.orchestrator.sessionPrefix;
-					if (rawPrefix === undefined || rawPrefix === "orch") {
-						raw.orchestrator.orchestrator.sessionPrefix = raw.orchestrator.orchestrator.tmuxPrefix;
-					}
-					delete raw.orchestrator.orchestrator.tmuxPrefix;
-				}
-				if (raw.orchestrator?.orchestrator?.spawnMode === "tmux") {
-					raw.orchestrator.orchestrator.spawnMode = "subprocess";
-				}
-				if (raw.taskRunner?.worker?.spawnMode === "tmux") {
-					raw.taskRunner.worker.spawnMode = "subprocess";
-				}
-				const tmpPath = jsonPath + ".migration-tmp";
-				writeFileSync(tmpPath, JSON.stringify(raw, null, 2) + "\n");
-				renameSync(tmpPath, jsonPath);
-				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}`);
-		}
-	}
-
-	_projectMigrationDone = true;
-	return migrated;
-}
-
-/**
- * Auto-migrate legacy TMUX fields in user preferences.
+ * Auto-migrate legacy TMUX fields in global preferences.
  *
  * Same precedence: new key wins if both exist.
  * Writes back atomically (tmp + rename).
  *
  * @returns true if any migrations were applied
  */
-function migrateUserPreferences(raw: Record<string, any>, prefsPath: string): boolean {
+function migrateGlobalPreferences(raw: Record<string, any>, prefsPath: string): boolean {
 	let migrated = false;
 	if (hasOwn(raw, "tmuxPrefix")) {
 		if (!hasOwn(raw, "sessionPrefix") || raw.sessionPrefix === undefined) {
 			raw.sessionPrefix = raw.tmuxPrefix;
 		}
 		delete raw.tmuxPrefix;
-		console.error(`[taskplane] Auto-migrated user preference: tmuxPrefix → sessionPrefix`);
+		console.error(`[taskplane] Auto-migrated global preference: tmuxPrefix → sessionPrefix`);
 		migrated = true;
 	}
 	if (raw.spawnMode === "tmux") {
 		raw.spawnMode = "subprocess";
-		console.error(`[taskplane] Auto-migrated user preference: spawnMode "tmux" → "subprocess"`);
+		console.error(`[taskplane] Auto-migrated global preference: spawnMode "tmux" → "subprocess"`);
+		migrated = true;
+	}
+	if (raw.orchestrator?.orchestrator?.spawnMode === "tmux") {
+		raw.orchestrator.orchestrator.spawnMode = "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"`);
 		migrated = true;
 	}
 	if (migrated) {
@@ -532,7 +462,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): TaskplaneConfig | null {
+function loadJsonConfig(configRoot: string): Partial<TaskplaneConfig> | null {
 	const jsonPath = resolveConfigFilePath(configRoot, PROJECT_CONFIG_FILENAME);
 	if (!existsSync(jsonPath)) return null;
 
@@ -570,22 +500,21 @@ function loadJsonConfig(configRoot: string): TaskplaneConfig | null {
 		);
 	}
 
-	// Deep merge with cloned defaults
-	const config = deepClone(DEFAULT_PROJECT_CONFIG);
-	if (parsed.taskRunner) {
-		deepMerge(config.taskRunner, parsed.taskRunner);
+	const overrides: Partial<TaskplaneConfig> = {};
+	if (parsed.taskRunner && typeof parsed.taskRunner === "object" && !Array.isArray(parsed.taskRunner)) {
+		overrides.taskRunner = deepClone(parsed.taskRunner);
 	}
-	if (parsed.orchestrator) {
-		deepMerge(config.orchestrator, parsed.orchestrator);
+	if (parsed.orchestrator && typeof parsed.orchestrator === "object" && !Array.isArray(parsed.orchestrator)) {
+		overrides.orchestrator = deepClone(parsed.orchestrator);
 	}
 	if (parsed.workspace) {
 		const normalizedWorkspace = normalizeWorkspaceSection(parsed.workspace, jsonPath);
 		if (normalizedWorkspace) {
-			config.workspace = normalizedWorkspace;
+			overrides.workspace = normalizedWorkspace;
 		}
 	}
 
-	return config;
+	return overrides;
 }
 
 
@@ -598,28 +527,24 @@ function loadJsonConfig(configRoot: string): TaskplaneConfig | null {
  * flat layout (`<root>/task-runner.yaml`) — see `resolveConfigFilePath`.
  * Maps snake_case YAML keys to the camelCase TaskRunnerSection shape.
  * Uses section-aware mapping that preserves user-defined record keys.
- * Returns cloned defaults if the file doesn't exist or is malformed.
+ * Returns sparse overrides (empty object when missing/malformed).
  */
-function loadTaskRunnerYaml(configRoot: string): TaskRunnerSection {
+function loadTaskRunnerYaml(configRoot: string): Partial<TaskRunnerSection> {
 	const yamlPath = resolveConfigFilePath(configRoot, "task-runner.yaml");
-	if (!existsSync(yamlPath)) return deepClone(DEFAULT_TASK_RUNNER_SECTION);
+	if (!existsSync(yamlPath)) return {};
 
 	try {
 		const raw = readFileSync(yamlPath, "utf-8");
 		const loaded = yamlParse(raw) as any;
-		if (!loaded || typeof loaded !== "object") return deepClone(DEFAULT_TASK_RUNNER_SECTION);
+		if (!loaded || typeof loaded !== "object") return {};
 
 		// Section-aware mapping: structural keys → camelCase, record keys → preserved
 		const mapped = mapTaskRunnerYaml(loaded);
 
-		// Deep merge with cloned defaults
-		const section = deepClone(DEFAULT_TASK_RUNNER_SECTION);
-		deepMerge(section, mapped);
-
 		// Post-process taskAreas: trim repoId, drop whitespace-only values
 		// (matches legacy loadTaskRunnerConfig behavior from config.ts)
-		if (section.taskAreas) {
-			for (const area of Object.values(section.taskAreas)) {
+		if (mapped.taskAreas) {
+			for (const area of Object.values(mapped.taskAreas)) {
 				if (area.repoId !== undefined) {
 					const trimmed = typeof area.repoId === "string" ? area.repoId.trim() : "";
 					if (trimmed) {
@@ -631,9 +556,9 @@ function loadTaskRunnerYaml(configRoot: string): TaskRunnerSection {
 			}
 		}
 
-		return section;
+		return mapped;
 	} catch {
-		return deepClone(DEFAULT_TASK_RUNNER_SECTION);
+		return {};
 	}
 }
 
@@ -644,27 +569,21 @@ function loadTaskRunnerYaml(configRoot: string): TaskRunnerSection {
  * flat layout (`<root>/task-orchestrator.yaml`) — see `resolveConfigFilePath`.
  * Maps snake_case YAML keys to the camelCase OrchestratorSection shape.
  * Uses section-aware mapping that preserves user-defined record keys.
- * Returns cloned defaults if the file doesn't exist or is malformed.
+ * Returns sparse overrides (empty object when missing/malformed).
  */
-function loadOrchestratorYaml(configRoot: string): OrchestratorSection {
+function loadOrchestratorYaml(configRoot: string): Partial<OrchestratorSection> {
 	const yamlPath = resolveConfigFilePath(configRoot, "task-orchestrator.yaml");
-	if (!existsSync(yamlPath)) return deepClone(DEFAULT_ORCHESTRATOR_SECTION);
+	if (!existsSync(yamlPath)) return {};
 
 	try {
 		const raw = readFileSync(yamlPath, "utf-8");
 		const loaded = yamlParse(raw) as any;
-		if (!loaded || typeof loaded !== "object") return deepClone(DEFAULT_ORCHESTRATOR_SECTION);
+		if (!loaded || typeof loaded !== "object") return {};
 
 		// Section-aware mapping: structural keys → camelCase, record keys → preserved
-		const mapped = mapOrchestratorYaml(loaded);
-
-		// Deep merge with cloned defaults
-		const section = deepClone(DEFAULT_ORCHESTRATOR_SECTION);
-		deepMerge(section, mapped);
-
-		return section;
+		return mapOrchestratorYaml(loaded);
 	} catch {
-		return deepClone(DEFAULT_ORCHESTRATOR_SECTION);
+		return {};
 	}
 }
 
@@ -692,10 +611,10 @@ function loadWorkspaceYaml(configRoot: string): WorkspaceSectionConfig | undefin
 }
 
 
-// ── User Preferences (Layer 2) ───────────────────────────────────────
+// ── Global Preferences (Layer 2) ─────────────────────────────────────
 
 /**
- * Resolve the absolute path to the user preferences file.
+ * Resolve the absolute path to the global preferences file.
  *
  * Resolution order:
  *   1. `PI_CODING_AGENT_DIR` env → `<value>/taskplane/preferences.json`
@@ -704,61 +623,104 @@ function loadWorkspaceYaml(configRoot: string): WorkspaceSectionConfig | undefin
  * Uses `os.homedir()` for cross-platform home resolution
  * (USERPROFILE on Windows, HOME on Unix) and `path.join()` for separators.
  */
-export function resolveUserPreferencesPath(): string {
+export function resolveGlobalPreferencesPath(): string {
 	const agentDir = process.env.PI_CODING_AGENT_DIR;
 	if (agentDir) {
-		return join(agentDir, USER_PREFERENCES_SUBDIR, USER_PREFERENCES_FILENAME);
+		return join(agentDir, GLOBAL_PREFERENCES_SUBDIR, GLOBAL_PREFERENCES_FILENAME);
+	}
+	return join(homedir(), ".pi", "agent", GLOBAL_PREFERENCES_SUBDIR, GLOBAL_PREFERENCES_FILENAME);
+}
+
+/** Result envelope for global preferences loading. */
+export interface GlobalPreferencesLoadResult {
+	preferences: GlobalPreferences;
+	wasBootstrapped: boolean;
+}
+
+/** Persist preferences JSON atomically (temp file + rename). */
+function writePreferencesAtomically(prefsPath: string, prefs: GlobalPreferences): void {
+	const tmpPath = `${prefsPath}.tmp-${process.pid}-${Date.now()}`;
+	writeFileSync(tmpPath, JSON.stringify(prefs, null, 2) + "\n", "utf-8");
+	renameSync(tmpPath, prefsPath);
+}
+
+/**
+ * Write first-install bootstrap preferences to disk and return the in-memory seed.
+ */
+function bootstrapGlobalPreferencesFile(prefsPath: string): GlobalPreferences {
+	const bootstrapPrefs = deepClone(DEFAULT_BOOTSTRAP_GLOBAL_PREFERENCES);
+	try {
+		const dir = join(prefsPath, "..");
+		mkdirSync(dir, { recursive: true });
+		writePreferencesAtomically(prefsPath, bootstrapPrefs);
+	} catch {
+		// Best-effort; if we can't create, still return bootstrap defaults in-memory.
 	}
-	return join(homedir(), ".pi", "agent", USER_PREFERENCES_SUBDIR, USER_PREFERENCES_FILENAME);
+	return bootstrapPrefs;
 }
 
 /**
- * Load user preferences from `~/.pi/agent/taskplane/preferences.json`.
+ * Load global preferences plus bootstrap metadata.
  *
  * Behavior:
- * - If file doesn't exist: auto-create with empty defaults `{}`, return defaults
- * - If file is malformed JSON: log warning, return defaults (non-destructive)
- * - Unknown keys are silently ignored (only allowlisted fields extracted)
- * - Returns a fresh UserPreferences object on each call
- *
- * @returns Parsed UserPreferences (only recognized fields)
+ * - If file doesn't exist: bootstrap preferences on disk and mark bootstrapped
+ * - If file is empty/malformed/invalid: re-bootstrap preferences and mark bootstrapped
+ * - Unknown keys are silently ignored (allowlist extraction)
  */
-export function loadUserPreferences(): UserPreferences {
-	const prefsPath = resolveUserPreferencesPath();
+export function loadGlobalPreferencesWithMeta(): GlobalPreferencesLoadResult {
+	const prefsPath = resolveGlobalPreferencesPath();
 
 	if (!existsSync(prefsPath)) {
-		// Auto-create with empty defaults on first access
-		try {
-			const dir = join(prefsPath, "..");
-			mkdirSync(dir, { recursive: true });
-			writeFileSync(prefsPath, JSON.stringify(DEFAULT_USER_PREFERENCES, null, 2) + "\n", "utf-8");
-		} catch {
-			// Best-effort; if we can't create, just return defaults
-		}
-		return { ...DEFAULT_USER_PREFERENCES };
+		return {
+			preferences: bootstrapGlobalPreferencesFile(prefsPath),
+			wasBootstrapped: true,
+		};
 	}
 
 	let raw: string;
 	try {
 		raw = readFileSync(prefsPath, "utf-8");
 	} catch {
-		return { ...DEFAULT_USER_PREFERENCES };
+		return { preferences: deepClone(DEFAULT_GLOBAL_PREFERENCES), wasBootstrapped: false };
+	}
+
+	if (!raw.trim()) {
+		return {
+			preferences: bootstrapGlobalPreferencesFile(prefsPath),
+			wasBootstrapped: true,
+		};
 	}
 
 	let parsed: any;
 	try {
 		parsed = JSON.parse(raw);
 	} catch {
-		// Malformed JSON — return defaults without overwriting (non-destructive)
-		return { ...DEFAULT_USER_PREFERENCES };
+		return {
+			preferences: bootstrapGlobalPreferencesFile(prefsPath),
+			wasBootstrapped: true,
+		};
 	}
 
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { ...DEFAULT_USER_PREFERENCES };
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || Object.keys(parsed).length === 0) {
+		return {
+			preferences: bootstrapGlobalPreferencesFile(prefsPath),
+			wasBootstrapped: true,
+		};
 	}
 
-	// Extract only allowlisted fields — unknown keys are ignored
-	return extractAllowlistedPreferences(parsed, prefsPath);
+	return {
+		preferences: extractAllowlistedPreferences(parsed, prefsPath),
+		wasBootstrapped: false,
+	};
+}
+
+/**
+ * Load global preferences from `~/.pi/agent/taskplane/preferences.json`.
+ *
+ * @returns Parsed GlobalPreferences (only recognized fields)
+ */
+export function loadGlobalPreferences(): GlobalPreferences {
+	return loadGlobalPreferencesWithMeta().preferences;
 }
 
 /**
@@ -767,18 +729,21 @@ export function loadUserPreferences(): UserPreferences {
  */
 function normalizePreferenceThinkingMode(value: unknown): string {
 	const cleaned = String(value ?? "").trim().toLowerCase();
-	if (cleaned === "on") return "on";
-	if (cleaned === "off") return "off";
+	if (!cleaned || cleaned === "inherit") return "";
+	if (cleaned === "on") return "high";
+	if (["off", "minimal", "low", "medium", "high", "xhigh"].includes(cleaned)) {
+		return cleaned;
+	}
 	return "";
 }
 
-function extractInitAgentDefaults(rawInitDefaults: unknown): UserPreferences["initAgentDefaults"] | undefined {
+function extractInitAgentDefaults(rawInitDefaults: unknown): GlobalPreferences["initAgentDefaults"] | undefined {
 	if (!rawInitDefaults || typeof rawInitDefaults !== "object" || Array.isArray(rawInitDefaults)) {
 		return undefined;
 	}
 
 	const raw = rawInitDefaults as Record<string, unknown>;
-	const extracted: NonNullable<UserPreferences["initAgentDefaults"]> = {};
+	const extracted: NonNullable<GlobalPreferences["initAgentDefaults"]> = {};
 
 	if (typeof raw.workerModel === "string") extracted.workerModel = raw.workerModel;
 	if (typeof raw.reviewerModel === "string") extracted.reviewerModel = raw.reviewerModel;
@@ -790,11 +755,34 @@ function extractInitAgentDefaults(rawInitDefaults: unknown): UserPreferences["in
 	return Object.keys(extracted).length > 0 ? extracted : undefined;
 }
 
-function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: string): UserPreferences {
-	migrateUserPreferences(raw, prefsPath);
+function extractConfigOverrideSection(rawSection: unknown): Record<string, any> | undefined {
+	if (!rawSection || typeof rawSection !== "object" || Array.isArray(rawSection)) {
+		return undefined;
+	}
+	return deepClone(rawSection as Record<string, any>);
+}
+
+function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: string): GlobalPreferences {
+	migrateGlobalPreferences(raw, prefsPath);
 
-	const prefs: UserPreferences = {};
+	const prefs: GlobalPreferences = {};
 
+	const taskRunnerOverrides = extractConfigOverrideSection(raw.taskRunner);
+	if (taskRunnerOverrides) {
+		prefs.taskRunner = taskRunnerOverrides as GlobalPreferences["taskRunner"];
+	}
+
+	const orchestratorOverrides = extractConfigOverrideSection(raw.orchestrator);
+	if (orchestratorOverrides) {
+		prefs.orchestrator = orchestratorOverrides as GlobalPreferences["orchestrator"];
+	}
+
+	const workspaceOverrides = extractConfigOverrideSection(raw.workspace);
+	if (workspaceOverrides) {
+		prefs.workspace = workspaceOverrides as GlobalPreferences["workspace"];
+	}
+
+	// Legacy flat aliases (backward compatibility for existing preferences.json files)
 	if (typeof raw.operatorId === "string") prefs.operatorId = raw.operatorId;
 	if (typeof raw.sessionPrefix === "string") {
 		prefs.sessionPrefix = raw.sessionPrefix;
@@ -807,6 +795,8 @@ function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: stri
 	if (typeof raw.mergeModel === "string") prefs.mergeModel = raw.mergeModel;
 	if (typeof raw.mergeThinking === "string") prefs.mergeThinking = raw.mergeThinking;
 	if (typeof raw.supervisorModel === "string") prefs.supervisorModel = raw.supervisorModel;
+
+	// Preferences-only fields (intentionally not merged into runtime config)
 	if (typeof raw.dashboardPort === "number" && Number.isFinite(raw.dashboardPort)) {
 		prefs.dashboardPort = raw.dashboardPort;
 	}
@@ -819,34 +809,23 @@ function extractAllowlistedPreferences(raw: Record<string, any>, prefsPath: stri
 }
 
 /**
- * Apply user preferences (Layer 2) onto a project config (Layer 1).
+ * Apply global preferences (Layer 2) onto a project config (Layer 1).
  *
- * Only allowlisted fields are applied. User preferences win for Layer 2
- * fields; all other config fields (Layer 1) are left untouched.
+ * Merge order inside Layer 2:
+ *   1. Legacy flat aliases (for backward compatibility)
+ *   2. Config-shaped nested overrides (`taskRunner` / `orchestrator` / `workspace`)
+ *      Nested overrides intentionally win when both styles are present.
  *
- * Mutates `config` in place and returns it for chaining.
- *
- * Empty-string preference values are treated as "not set" and do NOT
- * override the project config value. This lets users clear a preference
- * by deleting the field or setting it to "".
- *
- * Mapping table:
- *   prefs.operatorId    → config.orchestrator.orchestrator.operatorId
- *   prefs.sessionPrefix → config.orchestrator.orchestrator.sessionPrefix
- *   prefs.spawnMode     → config.orchestrator.orchestrator.spawnMode
- *   prefs.workerModel   → config.taskRunner.worker.model
- *   prefs.reviewerModel → config.taskRunner.reviewer.model
- *   prefs.mergeModel    → config.orchestrator.merge.model
- *   prefs.supervisorModel → config.orchestrator.supervisor.model
- *   prefs.dashboardPort → (no config target yet — stored only)
- *   prefs.initAgentDefaults → (preferences-only; consumed by CLI init flow)
+ * Preferences-only fields (`dashboardPort`, `initAgentDefaults`) are preserved
+ * in `GlobalPreferences` but intentionally not merged into runtime config.
  */
-export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPreferences): 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; });
@@ -864,8 +843,29 @@ export function applyUserPreferences(config: TaskplaneConfig, prefs: UserPrefere
 		config.orchestrator.orchestrator.spawnMode = prefs.spawnMode;
 	}
 
-	// dashboardPort: no config schema target yet — intentionally not applied
-	// It can be read directly from loadUserPreferences() by consumers that need it.
+	// 2) Config-shaped nested overrides
+	if (prefs.taskRunner) {
+		deepMerge(config.taskRunner as Record<string, any>, prefs.taskRunner as Record<string, any>);
+	}
+	if (prefs.orchestrator) {
+		deepMerge(config.orchestrator as Record<string, any>, prefs.orchestrator as Record<string, any>);
+	}
+	if (prefs.workspace) {
+		if (!config.workspace || typeof config.workspace !== "object") {
+			config.workspace = {} as TaskplaneConfig["workspace"];
+		}
+		deepMerge(config.workspace as Record<string, any>, prefs.workspace as Record<string, any>);
+	}
+
+	// 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"`);
+	}
+	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"`);
+	}
 
 	return config;
 }
@@ -932,105 +932,142 @@ export function resolveConfigRoot(cwd: string, pointerConfigRoot?: string): stri
 	return cwd;
 }
 
+function mergeProjectOverrides(config: TaskplaneConfig, overrides: Partial<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>);
+	}
+	if (overrides.workspace) {
+		if (!config.workspace || typeof config.workspace !== "object") {
+			config.workspace = {} as TaskplaneConfig["workspace"];
+		}
+		deepMerge(config.workspace as Record<string, any>, overrides.workspace as Record<string, any>);
+	}
+}
+
+function migrateProjectOverrides(overrides: Partial<TaskplaneConfig>, configRoot: string): boolean {
+	if (_projectMigrationDone) return false;
+
+	let migrated = false;
+	const orchestratorCore = overrides.orchestrator?.orchestrator as Record<string, unknown> | undefined;
+	if (orchestratorCore && hasOwn(orchestratorCore, "tmuxPrefix")) {
+		const currentPrefix = orchestratorCore.sessionPrefix;
+		const isDefault = currentPrefix === undefined || currentPrefix === "orch";
+		if (isDefault) {
+			(orchestratorCore as any).sessionPrefix = orchestratorCore.tmuxPrefix;
+		}
+		delete orchestratorCore.tmuxPrefix;
+		console.error(`[taskplane] Auto-migrated: orchestrator.orchestrator.tmuxPrefix → sessionPrefix`);
+		migrated = true;
+	}
+	if (orchestratorCore?.spawnMode === "tmux") {
+		(orchestratorCore as any).spawnMode = "subprocess";
+		console.error(`[taskplane] Auto-migrated: orchestrator.orchestrator.spawnMode "tmux" → "subprocess"`);
+		migrated = true;
+	}
+
+	const workerConfig = overrides.taskRunner?.worker as Record<string, unknown> | undefined;
+	if (workerConfig?.spawnMode === "tmux") {
+		(workerConfig as any).spawnMode = "subprocess";
+		console.error(`[taskplane] Auto-migrated: taskRunner.worker.spawnMode "tmux" → "subprocess"`);
+		migrated = true;
+	}
+
+	if (migrated) {
+		try {
+			const jsonPath = resolveConfigFilePath(configRoot, PROJECT_CONFIG_FILENAME);
+			if (existsSync(jsonPath)) {
+				const raw = JSON.parse(readFileSync(jsonPath, "utf-8"));
+				if (raw.orchestrator?.orchestrator?.tmuxPrefix !== undefined) {
+					const rawPrefix = raw.orchestrator.orchestrator.sessionPrefix;
+					if (rawPrefix === undefined || rawPrefix === "orch") {
+						raw.orchestrator.orchestrator.sessionPrefix = raw.orchestrator.orchestrator.tmuxPrefix;
+					}
+					delete raw.orchestrator.orchestrator.tmuxPrefix;
+				}
+				if (raw.orchestrator?.orchestrator?.spawnMode === "tmux") {
+					raw.orchestrator.orchestrator.spawnMode = "subprocess";
+				}
+				if (raw.taskRunner?.worker?.spawnMode === "tmux") {
+					raw.taskRunner.worker.spawnMode = "subprocess";
+				}
+
+				const tmpPath = jsonPath + ".migration-tmp";
+				writeFileSync(tmpPath, JSON.stringify(raw, null, 2) + "\n");
+				renameSync(tmpPath, jsonPath);
+				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}`);
+		}
+	}
+
+	_projectMigrationDone = true;
+	return migrated;
+}
+
+export function loadProjectOverrides(configRoot: string): Partial<TaskplaneConfig> {
+	const jsonOverrides = loadJsonConfig(configRoot);
+	if (jsonOverrides !== null) {
+		return jsonOverrides;
+	}
+
+	const taskRunner = loadTaskRunnerYaml(configRoot);
+	const orchestrator = loadOrchestratorYaml(configRoot);
+	const workspace = loadWorkspaceYaml(configRoot);
+
+	const overrides: Partial<TaskplaneConfig> = {};
+	if (Object.keys(taskRunner).length > 0) overrides.taskRunner = taskRunner;
+	if (Object.keys(orchestrator).length > 0) overrides.orchestrator = orchestrator;
+	if (workspace) overrides.workspace = workspace;
+	return overrides;
+}
+
 /**
  * Load the unified project configuration.
  *
  * Precedence (layered):
- *   Layer 1 — Project config:
- *     1. `.pi/taskplane-config.json` — JSON-first (new format)
- *     2. `.pi/task-runner.yaml` + `.pi/task-orchestrator.yaml` — YAML fallback
- *        (+ optional `.pi/taskplane-workspace.yaml` workspace section mapping)
- *     3. Defaults — if no config files exist
- *
- *   Layer 2 — User preferences (applied on top of Layer 1):
- *     Reads `~/.pi/agent/taskplane/preferences.json` and overrides only
- *     allowlisted user-scoped fields. See `applyUserPreferences()` for
- *     the field mapping.
+ *   1. Schema defaults
+ *   2. Global preferences (`~/.pi/agent/taskplane/preferences.json`)
+ *   3. Project overrides (`taskplane-config.json` or YAML fallback)
  *
- * Config root resolution order:
- *   1. cwd has config files → use cwd (local override)
- *   2. pointerConfigRoot has config files → use it (pointer redirect, workspace mode)
- *   3. TASKPLANE_WORKSPACE_ROOT has config files → use it (legacy fallback)
- *   4. Fall back to cwd (loaders will return defaults)
- *
- * @param cwd - Current working directory (project root or worktree)
- * @param pointerConfigRoot - Resolved config root from pointer file (optional).
- *   Callers in workspace mode should resolve the pointer via `resolvePointer()`
- *   and pass `result.configRoot` here. In repo mode, omit or pass undefined.
- * @returns Unified TaskplaneConfig — always a fresh deep-cloned object
- * @throws ConfigLoadError if JSON exists but is malformed or has unsupported version
+ * Project config is treated as sparse overrides. Missing fields in project
+ * config fall through to global preferences, then schema defaults.
  */
 export function loadProjectConfig(cwd: string, pointerConfigRoot?: string): TaskplaneConfig {
 	const configRoot = resolveConfigRoot(cwd, pointerConfigRoot);
+	const config = deepClone(DEFAULT_PROJECT_CONFIG);
 
-	// Layer 1: Project config
-	let config: TaskplaneConfig;
-
-	// Try JSON first
-	const jsonConfig = loadJsonConfig(configRoot);
-	if (jsonConfig !== null) {
-		config = jsonConfig;
-	} else {
-		// Fall back to YAML
-		const taskRunner = loadTaskRunnerYaml(configRoot);
-		const orchestrator = loadOrchestratorYaml(configRoot);
-		const workspace = loadWorkspaceYaml(configRoot);
-		config = {
-			configVersion: CONFIG_VERSION,
-			taskRunner,
-			orchestrator,
-			...(workspace ? { workspace } : {}),
-		};
-	}
-
-	_projectMigrationDone = false; // Reset guard for each top-level load
-	migrateProjectConfig(config, configRoot);
+	// Layer 2 baseline: global preferences on top of defaults
+	const prefs = loadGlobalPreferences();
+	applyGlobalPreferences(config, prefs);
 
-	// Layer 2: User preferences (allowlisted fields only)
-	const prefs = loadUserPreferences();
-	applyUserPreferences(config, prefs);
-	// No second migrateProjectConfig call needed — idempotency guard + prefs
-	// can’t re-introduce tmux fields (migrateUserPreferences already ran).
+	// Layer 1 project overrides: sparse config merged on top
+	const overrides = loadProjectOverrides(configRoot);
+	_projectMigrationDone = false;
+	migrateProjectOverrides(overrides, configRoot);
+	mergeProjectOverrides(config, overrides);
 
 	normalizeInheritanceAliases(config);
 	return config;
 }
 
 /**
- * Load Layer 1 config only (project config without user preferences).
- *
- * Returns the project config merged with defaults, but WITHOUT applying
- * Layer 2 user preferences. Used by the settings TUI write-back to
- * bootstrap a JSON config file from YAML-only projects without
- * accidentally embedding user preferences into the project config.
- *
- * @param cwd - Current working directory (project root or worktree)
- * @param pointerConfigRoot - Optional pointer-resolved config root (workspace mode)
- * @returns Layer 1 TaskplaneConfig — always a fresh deep-cloned object
- * @throws ConfigLoadError if JSON exists but is malformed or has unsupported version
+ * Load project overrides merged with schema defaults, without applying
+ * global preferences. Used by settings write-back code paths that must
+ * avoid embedding global baseline values into project config.
  */
 export function loadLayer1Config(cwd: string, pointerConfigRoot?: string): TaskplaneConfig {
 	const configRoot = resolveConfigRoot(cwd, pointerConfigRoot);
+	const config = deepClone(DEFAULT_PROJECT_CONFIG);
+	const overrides = loadProjectOverrides(configRoot);
 
-	// Try JSON first
-	const jsonConfig = loadJsonConfig(configRoot);
-	if (jsonConfig !== null) {
-		migrateProjectConfig(jsonConfig, configRoot);
-		normalizeInheritanceAliases(jsonConfig);
-		return jsonConfig;
-	}
+	_projectMigrationDone = false;
+	migrateProjectOverrides(overrides, configRoot);
+	mergeProjectOverrides(config, overrides);
 
-	// Fall back to YAML
-	const taskRunner = loadTaskRunnerYaml(configRoot);
-	const orchestrator = loadOrchestratorYaml(configRoot);
-	const workspace = loadWorkspaceYaml(configRoot);
-	const config: TaskplaneConfig = {
-		configVersion: CONFIG_VERSION,
-		taskRunner,
-		orchestrator,
-		...(workspace ? { workspace } : {}),
-	};
-	migrateProjectConfig(config, configRoot);
 	normalizeInheritanceAliases(config);
 	return config;
 }