gsd-pi 2.35.0 → 2.36.0-dev.d612764

package/dist/resources/extensions/gsd/health-widget.js

@@ -11,21 +11,23 @@ import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.j
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
+import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands.js";
+import { deriveState, invalidateStateCache } from "./state.js";
+import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
 // ── Data loader ────────────────────────────────────────────────────────────────
-function loadHealthWidgetData(basePath) {
-    let hasProject = false;
+function loadBaseHealthWidgetData(basePath) {
     let budgetCeiling;
     let budgetSpent = 0;
     let providerIssue = null;
     let environmentErrorCount = 0;
     let environmentWarningCount = 0;
+    const projectState = detectHealthWidgetProjectState(basePath);
     try {
         const prefs = loadEffectiveGSDPreferences();
         budgetCeiling = prefs?.preferences?.budget_ceiling;
         const ledger = loadLedgerFromDisk(basePath);
         if (ledger) {
-            hasProject = true;
             const totals = getProjectTotals(ledger.units ?? []);
             budgetSpent = totals.cost;
         }
@@ -47,7 +49,7 @@ function loadHealthWidgetData(basePath) {
     }
     catch { /* non-fatal */ }
     return {
-        hasProject,
+        projectState,
         budgetCeiling,
         budgetSpent,
         providerIssue,
@@ -56,50 +58,85 @@ function loadHealthWidgetData(basePath) {
         lastRefreshed: Date.now(),
     };
 }
-// ── Rendering ──────────────────────────────────────────────────────────────────
-function formatCost(n) {
-    return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+function compactText(text, max = 64) {
+    const trimmed = text.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, max - 1).trimEnd()}…`;
 }
-/**
- * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
- */
-export function buildHealthLines(data) {
-    if (!data.hasProject) {
-        return ["  GSD  No project loaded — run /gsd to start"];
-    }
-    const parts = [];
-    // System status signal
-    const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
-    if (totalIssues === 0) {
-        parts.push("● System OK");
-    }
-    else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-        parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
-    }
-    else {
-        parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+function summarizeExecutionStatus(state) {
+    switch (state.phase) {
+        case "blocked": return "Blocked";
+        case "paused": return "Paused";
+        case "complete": return "Complete";
+        case "executing": return "Executing";
+        case "planning": return "Planning";
+        case "pre-planning": return "Pre-planning";
+        case "summarizing": return "Summarizing";
+        case "validating-milestone": return "Validating";
+        case "completing-milestone": return "Completing";
+        case "needs-discussion": return "Needs discussion";
+        case "replanning-slice": return "Replanning";
+        default: return "Active";
     }
-    // Budget
-    if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
-        const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-        parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
-    }
-    else if (data.budgetSpent > 0) {
-        parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
-    }
-    // Provider issue (if any)
-    if (data.providerIssue) {
-        parts.push(data.providerIssue);
+}
+function summarizeExecutionTarget(state) {
+    switch (state.phase) {
+        case "needs-discussion":
+            return state.activeMilestone ? `Discuss ${state.activeMilestone.id}` : "Discuss milestone draft";
+        case "pre-planning":
+            return state.activeMilestone ? `Plan ${state.activeMilestone.id}` : "Research & plan milestone";
+        case "planning":
+            return state.activeSlice ? `Plan ${state.activeSlice.id}` : "Plan next slice";
+        case "executing":
+            return state.activeTask ? `Execute ${state.activeTask.id}` : "Execute next task";
+        case "summarizing":
+            return state.activeSlice ? `Complete ${state.activeSlice.id}` : "Complete current slice";
+        case "validating-milestone":
+            return state.activeMilestone ? `Validate ${state.activeMilestone.id}` : "Validate milestone";
+        case "completing-milestone":
+            return state.activeMilestone ? `Complete ${state.activeMilestone.id}` : "Complete milestone";
+        case "replanning-slice":
+            return state.activeSlice ? `Replan ${state.activeSlice.id}` : "Replan current slice";
+        case "blocked":
+            return `waiting on ${compactText(state.blockers[0] ?? state.nextAction, 56)}`;
+        case "paused":
+            return compactText(state.nextAction || "waiting to resume", 56);
+        case "complete":
+            return "All milestones complete";
+        default:
+            return compactText(describeNextUnit(state).label, 56);
     }
-    // Environment issues
-    if (data.environmentErrorCount > 0) {
-        parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+}
+async function enrichHealthWidgetData(basePath, baseData) {
+    if (baseData.projectState !== "active")
+        return baseData;
+    try {
+        invalidateStateCache();
+        const state = await deriveState(basePath);
+        if (state.activeMilestone) {
+            // Warm the slice-progress cache so estimateTimeRemaining() has data
+            updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
+        }
+        return {
+            ...baseData,
+            executionPhase: state.phase,
+            executionStatus: summarizeExecutionStatus(state),
+            executionTarget: summarizeExecutionTarget(state),
+            nextAction: state.nextAction,
+            blocker: state.blockers[0] ?? null,
+            activeMilestoneId: state.activeMilestone?.id,
+            activeSliceId: state.activeSlice?.id,
+            activeTaskId: state.activeTask?.id,
+            progress: state.progress,
+            eta: state.phase === "blocked" || state.phase === "paused" || state.phase === "complete"
+                ? null
+                : estimateTimeRemaining(),
+        };
     }
-    else if (data.environmentWarningCount > 0) {
-        parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+    catch {
+        return baseData;
     }
-    return [`  ${parts.join("  │  ")}`];
 }
 // ── Widget init ────────────────────────────────────────────────────────────────
 const REFRESH_INTERVAL_MS = 60_000;
@@ -112,19 +149,33 @@ export function initHealthWidget(ctx) {
         return;
     const basePath = projectRoot();
     // String-array fallback — used in RPC mode (factory is a no-op there)
-    const initialData = loadHealthWidgetData(basePath);
+    const initialData = loadBaseHealthWidgetData(basePath);
     ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
     // Factory-based widget for TUI mode — replaces the string-array above
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
         let data = initialData;
         let cachedLines;
-        const refreshTimer = setInterval(() => {
+        let refreshInFlight = false;
+        const refresh = async () => {
+            if (refreshInFlight)
+                return;
+            refreshInFlight = true;
             try {
-                data = loadHealthWidgetData(basePath);
+                const baseData = loadBaseHealthWidgetData(basePath);
+                data = await enrichHealthWidgetData(basePath, baseData);
                 cachedLines = undefined;
                 _tui.requestRender();
             }
             catch { /* non-fatal */ }
+            finally {
+                refreshInFlight = false;
+            }
+        };
+        // Fire first enrichment immediately. requestRender() inside is a no-op
+        // if the widget has not yet rendered, so this is safe before factory return.
+        void refresh();
+        const refreshTimer = setInterval(() => {
+            void refresh();
         }, REFRESH_INTERVAL_MS);
         return {
             render(_width) {

package/dist/resources/extensions/gsd/index.js

@@ -46,33 +46,22 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-function loadAgentInstructions() {
-    const parts = [];
-    const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-    if (existsSync(globalPath)) {
-        try {
-            const content = readFileSync(globalPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
-        }
-        catch { /* non-fatal — skip unreadable file */ }
-    }
-    const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-    if (existsSync(projectPath)) {
-        try {
-            const content = readFileSync(projectPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
+import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js";
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+function warnDeprecatedAgentInstructions() {
+    const paths = [
+        join(homedir(), ".gsd", "agent-instructions.md"),
+        join(process.cwd(), ".gsd", "agent-instructions.md"),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            console.warn(`[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+                `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+                `See https://github.com/gsd-build/GSD-2/issues/1492`);
         }
-        catch { /* non-fatal — skip unreadable file */ }
     }
-    if (parts.length === 0)
-        return null;
-    return parts.join("\n\n");
 }
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
@@ -140,7 +129,16 @@ export default function (pi) {
                 // Pipe closed — nothing we can write; just exit cleanly
                 process.exit(0);
             }
-            // Re-throw anything that isn't EPIPE so real crashes still surface
+            if (err.code === "ENOENT" &&
+                err.syscall?.startsWith("spawn")) {
+                // spawn ENOENT — command not found (e.g., npx on Windows).
+                // This surfaces as an uncaught exception from child_process but
+                // is not a fatal process error. Log and continue instead of
+                // crashing auto-mode (#1384).
+                process.stderr.write(`[gsd] spawn ENOENT: ${err.path ?? "unknown"} — command not found\n`);
+                return;
+            }
+            // Re-throw anything that isn't EPIPE/ENOENT so real crashes still surface
             throw err;
         };
         process.on("uncaughtException", _gsdEpipeGuard);
@@ -535,6 +533,10 @@ export default function (pi) {
         const stopContextTimer = debugTime("context-inject");
         const systemContent = loadPrompt("system");
         const loadedPreferences = loadEffectiveGSDPreferences();
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            ctx.ui.notify("cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.", "info");
+        }
         let preferenceBlock = "";
         if (loadedPreferences) {
             const cwd = process.cwd();
@@ -580,12 +582,8 @@ export default function (pi) {
                 newSkillsBlock = formatSkillsXml(newSkills);
             }
         }
-        // Load agent instructions (global + project)
-        let agentInstructionsBlock = "";
-        const agentInstructions = loadAgentInstructions();
-        if (agentInstructions) {
-            agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-        }
+        // Warn if deprecated agent-instructions.md files are still present
+        warnDeprecatedAgentInstructions();
         const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
         // Worktree context — override the static CWD in the system prompt
         let worktreeBlock = "";
@@ -628,7 +626,7 @@ export default function (pi) {
                 "Write every .gsd artifact in the worktree path above, never in the main project tree.",
             ].join("\n");
         }
-        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
         stopContextTimer({
             systemPromptSize: fullSystem.length,
             injectionSize: injection?.length ?? 0,

package/dist/resources/extensions/gsd/migrate-external.js

@@ -5,10 +5,11 @@
  * `~/.gsd/projects/<hash>/` state directory. After migration, a
  * symlink replaces the original directory so all paths remain valid.
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
+import { hasGitTrackedGsdFiles } from "./gitignore.js";
 /**
  * Migrate a legacy in-project `.gsd/` directory to external storage.
  *
@@ -42,6 +43,27 @@ export function migrateToExternalState(basePath) {
     catch (err) {
         return { migrated: false, error: `Cannot stat .gsd: ${getErrorMessage(err)}` };
     }
+    // Skip if .gsd/ contains git-tracked files — the project intentionally
+    // keeps .gsd/ in version control and migration would destroy that.
+    if (hasGitTrackedGsdFiles(basePath)) {
+        return { migrated: false };
+    }
+    // Skip if .gsd/worktrees/ has active worktree directories (#1337).
+    // On Windows, active git worktrees hold OS-level directory handles that
+    // prevent rename/delete. Attempting migration causes EBUSY and data loss.
+    const worktreesDir = join(localGsd, "worktrees");
+    if (existsSync(worktreesDir)) {
+        try {
+            const entries = readdirSync(worktreesDir, { withFileTypes: true });
+            if (entries.some(e => e.isDirectory())) {
+                return { migrated: false };
+            }
+        }
+        catch {
+            // Can't read worktrees dir — skip migration to be safe
+            return { migrated: false };
+        }
+    }
     const externalPath = externalGsdRoot(basePath);
     const migratingPath = join(basePath, ".gsd.migrating");
     try {
@@ -89,7 +111,38 @@ export function migrateToExternalState(basePath) {
         }
         // Create symlink .gsd -> external path
         symlinkSync(externalPath, localGsd, "junction");
-        // Remove .gsd.migrating
+        // Verify the symlink resolves correctly before removing the backup (#1377).
+        // On Windows, junction creation can silently succeed but resolve to the wrong
+        // target, or the external dir may not be accessible. If verification fails,
+        // restore from the backup.
+        try {
+            const resolved = realpathSync(localGsd);
+            const resolvedExternal = realpathSync(externalPath);
+            if (resolved !== resolvedExternal) {
+                // Symlink points to wrong target — restore backup
+                try {
+                    rmSync(localGsd, { force: true });
+                }
+                catch { /* may not exist */ }
+                renameSync(migratingPath, localGsd);
+                return { migrated: false, error: `Migration verification failed: symlink resolves to ${resolved}, expected ${resolvedExternal}` };
+            }
+            // Verify we can read through the symlink
+            readdirSync(localGsd);
+        }
+        catch (verifyErr) {
+            // Symlink broken or unreadable — restore backup
+            try {
+                rmSync(localGsd, { force: true });
+            }
+            catch { /* may not exist */ }
+            try {
+                renameSync(migratingPath, localGsd);
+            }
+            catch { /* best-effort restore */ }
+            return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
+        }
+        // Remove .gsd.migrating only after symlink is verified
         rmSync(migratingPath, { recursive: true, force: true });
         return { migrated: true };
     }

package/dist/resources/extensions/gsd/milestone-ids.js

@@ -67,8 +67,9 @@ export function findMilestoneIds(basePath) {
             .filter((d) => d.isDirectory())
             .map((d) => {
             const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-            return match ? match[1] : d.name;
-        });
+            return match ? match[1] : null;
+        })
+            .filter((id) => id !== null);
         // Apply custom queue order if available, else fall back to numeric sort
         const customOrder = loadQueueOrder(basePath);
         return sortByQueueOrder(ids, customOrder);

package/dist/resources/extensions/gsd/notifications.js

@@ -2,13 +2,22 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
  */
 export function sendDesktopNotification(title, message, level = "info", kind = "complete") {
-    if (!shouldSendDesktopNotification(kind))
+    const loaded = loadEffectiveGSDPreferences()?.preferences;
+    if (!shouldSendDesktopNotification(kind, loaded?.notifications))
         return;
+    const cmux = resolveCmuxConfig(loaded);
+    if (cmux.notifications) {
+        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+        if (delivered)
+            return;
+        emitOsc777Notification(title, message);
+    }
     try {
         const command = buildDesktopNotificationCommand(process.platform, title, message, level);
         if (!command)

package/dist/resources/extensions/gsd/paths.js

@@ -9,7 +9,8 @@
  * via prefix matching, so existing projects work without migration.
  */
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
@@ -263,15 +264,81 @@ const LEGACY_GSD_ROOT_FILES = {
     OVERRIDES: "overrides.md",
     KNOWLEDGE: "knowledge.md",
 };
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+const gsdRootCache = new Map();
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache() {
+    gsdRootCache.clear();
+}
+/**
+ * Resolve the `.gsd` directory for a given project base path.
+ *
+ * Probe order:
+ *   1. basePath/.gsd         — fast path (common case)
+ *   2. git rev-parse root    — handles cwd-is-a-subdirectory
+ *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
+ *   4. basePath/.gsd         — creation fallback (init scenario)
+ *
+ * Result is cached per basePath for the process lifetime.
+ */
 export function gsdRoot(basePath) {
-    const local = join(basePath, ".gsd");
+    const cached = gsdRootCache.get(basePath);
+    if (cached)
+        return cached;
+    const result = probeGsdRoot(basePath);
+    gsdRootCache.set(basePath, result);
+    return result;
+}
+function probeGsdRoot(rawBasePath) {
+    // 1. Fast path — check the input path directly
+    const local = join(rawBasePath, ".gsd");
+    if (existsSync(local))
+        return local;
+    // Resolve symlinks so path comparisons work correctly across platforms
+    // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
+    let basePath;
     try {
-        const resolved = realpathSync(local);
-        if (resolved !== local)
-            return resolved; // symlink resolved
+        basePath = realpathSync.native(rawBasePath);
+    }
+    catch {
+        basePath = rawBasePath;
+    }
+    // 2. Git root anchor — used as both probe target and walk-up boundary
+    //    Only walk if we're inside a git project — prevents escaping into
+    //    unrelated filesystem territory when running outside any repo.
+    let gitRoot = null;
+    try {
+        const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: basePath,
+            encoding: "utf-8",
+        });
+        if (out.status === 0) {
+            const r = out.stdout.trim();
+            if (r)
+                gitRoot = normalize(r);
+        }
+    }
+    catch { /* git not available */ }
+    if (gitRoot) {
+        const candidate = join(gitRoot, ".gsd");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
+    if (gitRoot && basePath !== gitRoot) {
+        let cur = dirname(basePath);
+        while (cur !== basePath) {
+            const candidate = join(cur, ".gsd");
+            if (existsSync(candidate))
+                return candidate;
+            if (cur === gitRoot)
+                break;
+            basePath = cur;
+            cur = dirname(cur);
+        }
     }
-    catch { /* doesn't exist yet — fall through */ }
-    return local; // backwards compat: unmigrated projects
+    // 4. Fallback for init/creation
+    return local;
 }
 export function milestonesDir(basePath) {
     return join(gsdRoot(basePath), "milestones");

package/dist/resources/extensions/gsd/post-unit-hooks.js

@@ -111,10 +111,13 @@ function dequeueNextHook(basePath) {
         };
         // Build the prompt with variable substitution
         const [mid, sid, tid] = triggerUnitId.split("/");
-        const prompt = config.prompt
+        let prompt = config.prompt
             .replace(/\{milestoneId\}/g, mid ?? "")
             .replace(/\{sliceId\}/g, sid ?? "")
             .replace(/\{taskId\}/g, tid ?? "");
+        // Inject browser safety instruction for hooks that may use browser tools (#1345).
+        // Vite HMR and other persistent connections prevent networkidle from resolving.
+        prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
         return {
             hookName: config.name,
             prompt,

package/dist/resources/extensions/gsd/preferences-types.js

@@ -47,6 +47,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "budget_enforcement",
     "context_pause_threshold",
     "notifications",
+    "cmux",
     "remote_questions",
     "git",
     "post_unit_hooks",
@@ -63,6 +64,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "search_provider",
     "compression_strategy",
     "context_selection",
+    "widget_mode",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -14,9 +14,24 @@ export function validatePreferences(preferences) {
     const warnings = [];
     const validated = {};
     // ─── Unknown Key Detection ──────────────────────────────────────────
+    // Common key migration hints for pi-level settings that don't map to GSD prefs
+    const KEY_MIGRATION_HINTS = {
+        taskIsolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        task_isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+        manage_gitignore: 'use "git.manage_gitignore" instead',
+        auto_push: 'use "git.auto_push" instead',
+        main_branch: 'use "git.main_branch" instead',
+    };
     for (const key of Object.keys(preferences)) {
         if (!KNOWN_PREFERENCE_KEYS.has(key)) {
-            warnings.push(`unknown preference key "${key}" — ignored`);
+            const hint = KEY_MIGRATION_HINTS[key];
+            if (hint) {
+                warnings.push(`unknown preference key "${key}" — ${hint}`);
+            }
+            else {
+                warnings.push(`unknown preference key "${key}" — ignored`);
+            }
         }
     }
     if (preferences.version !== undefined) {
@@ -210,6 +225,35 @@ export function validatePreferences(preferences) {
             errors.push("notifications must be an object");
         }
     }
+    // ─── Cmux ───────────────────────────────────────────────────────────────
+    if (preferences.cmux !== undefined) {
+        if (preferences.cmux && typeof preferences.cmux === "object") {
+            const cmux = preferences.cmux;
+            const validatedCmux = {};
+            if (cmux.enabled !== undefined)
+                validatedCmux.enabled = !!cmux.enabled;
+            if (cmux.notifications !== undefined)
+                validatedCmux.notifications = !!cmux.notifications;
+            if (cmux.sidebar !== undefined)
+                validatedCmux.sidebar = !!cmux.sidebar;
+            if (cmux.splits !== undefined)
+                validatedCmux.splits = !!cmux.splits;
+            if (cmux.browser !== undefined)
+                validatedCmux.browser = !!cmux.browser;
+            const knownCmuxKeys = new Set(["enabled", "notifications", "sidebar", "splits", "browser"]);
+            for (const key of Object.keys(cmux)) {
+                if (!knownCmuxKeys.has(key)) {
+                    warnings.push(`unknown cmux key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validatedCmux).length > 0) {
+                validated.cmux = validatedCmux;
+            }
+        }
+        else {
+            errors.push("cmux must be an object");
+        }
+    }
     // ─── Remote Questions ───────────────────────────────────────────────
     if (preferences.remote_questions !== undefined) {
         if (preferences.remote_questions && typeof preferences.remote_questions === "object") {

package/dist/resources/extensions/gsd/preferences.js

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 import { MODE_DEFAULTS, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
 import { formatSkillRef } from "./preferences-skills.js";
@@ -79,6 +80,17 @@ export function loadEffectiveGSDPreferences() {
             ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
         };
     }
+    // Apply token-profile defaults as the lowest-priority layer so that
+    // `token_profile: budget` sets models and phase-skips automatically.
+    // Explicit user preferences always override profile defaults.
+    const profile = result.preferences.token_profile;
+    if (profile) {
+        const profileDefaults = _resolveProfileDefaults(profile);
+        result = {
+            ...result,
+            preferences: mergePreferences(profileDefaults, result.preferences),
+        };
+    }
     // Apply mode defaults as the lowest-priority layer
     if (result.preferences.mode) {
         result = {
@@ -162,6 +174,9 @@ function mergePreferences(base, override) {
         notifications: (base.notifications || override.notifications)
             ? { ...(base.notifications ?? {}), ...(override.notifications ?? {}) }
             : undefined,
+        cmux: (base.cmux || override.cmux)
+            ? { ...(base.cmux ?? {}), ...(override.cmux ?? {}) }
+            : undefined,
         remote_questions: override.remote_questions
             ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
             : base.remote_questions,