gsd-pi 2.34.0 → 2.35.0-dev.34ce717

package/src/resources/extensions/gsd/health-widget.ts

@@ -9,41 +9,37 @@
  */
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import type { GSDState } from "./types.js";
 import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
 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";
-
-// ── Types ──────────────────────────────────────────────────────────────────────
-
-interface HealthWidgetData {
-  hasProject: boolean;
-  budgetCeiling: number | undefined;
-  budgetSpent: number;
-  providerIssue: string | null;      // compact summary from summariseProviderIssues()
-  environmentErrorCount: number;
-  environmentWarningCount: number;
-  lastRefreshed: number;
-}
+import { deriveState, invalidateStateCache } from "./state.js";
+import {
+  buildHealthLines,
+  detectHealthWidgetProjectState,
+  type HealthWidgetData,
+} from "./health-widget-core.js";
 
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-function loadHealthWidgetData(basePath: string): HealthWidgetData {
-  let hasProject = false;
+function loadBaseHealthWidgetData(basePath: string): HealthWidgetData {
   let budgetCeiling: number | undefined;
   let budgetSpent = 0;
   let providerIssue: string | null = 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;
     }
@@ -63,7 +59,7 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData {
   } catch { /* non-fatal */ }
 
   return {
-    hasProject,
+    projectState,
     budgetCeiling,
     budgetSpent,
     providerIssue,
@@ -73,54 +69,88 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData {
   };
 }
 
-// ── Rendering ──────────────────────────────────────────────────────────────────
-
-function formatCost(n: number): string {
-  return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+function compactText(text: string, max = 64): string {
+  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: HealthWidgetData): string[] {
-  if (!data.hasProject) {
-    return ["  GSD  No project loaded — run /gsd to start"];
+function summarizeExecutionStatus(state: GSDState): string {
+  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";
   }
+}
 
-  const parts: string[] = [];
-
-  // 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 summarizeExecutionTarget(state: GSDState): string {
+  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);
   }
+}
 
-  // 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)}`);
-  }
+async function enrichHealthWidgetData(basePath: string, baseData: HealthWidgetData): Promise<HealthWidgetData> {
+  if (baseData.projectState !== "active") return baseData;
 
-  // Provider issue (if any)
-  if (data.providerIssue) {
-    parts.push(data.providerIssue);
-  }
+  try {
+    invalidateStateCache();
+    const state = await deriveState(basePath);
 
-  // Environment issues
-  if (data.environmentErrorCount > 0) {
-    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
-  } else if (data.environmentWarningCount > 0) {
-    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
-  }
+    if (state.activeMilestone) {
+      // Warm the slice-progress cache so estimateTimeRemaining() has data
+      updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
+    }
 
-  return [`  ${parts.join("  │  ")}`];
+    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(),
+    };
+  } catch {
+    return baseData;
+  }
 }
 
 // ── Widget init ────────────────────────────────────────────────────────────────
@@ -137,20 +167,34 @@ export function initHealthWidget(ctx: ExtensionContext): void {
   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: string[] | undefined;
+    let refreshInFlight = false;
 
-    const refreshTimer = setInterval(() => {
+    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 */ }
+      } 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 {

package/src/resources/extensions/gsd/index.ts

@@ -66,32 +66,24 @@ 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(): string | null {
-  const parts: string[] = [];
-
-  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);
-    } catch { /* non-fatal — skip unreadable file */ }
+// ── 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(): void {
+  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`,
+      );
+    }
   }
-
-  if (parts.length === 0) return null;
-  return parts.join("\n\n");
 }
 
 // ── Depth verification state ──────────────────────────────────────────────
@@ -175,7 +167,16 @@ export default function (pi: ExtensionAPI) {
         // 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 as NodeJS.ErrnoException).code === "ENOENT" &&
+          (err as any).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 as any).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);
@@ -673,12 +674,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // 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());
 
@@ -723,7 +720,7 @@ export default function (pi: ExtensionAPI) {
       ].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/src/resources/extensions/gsd/migrate-external.ts

@@ -6,10 +6,11 @@
  * 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";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -51,6 +52,28 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     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");
 
@@ -99,7 +122,29 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     // 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/src/resources/extensions/gsd/milestone-ids.ts

@@ -80,8 +80,9 @@ export function findMilestoneIds(basePath: string): string[] {
       .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 is string => id !== null);
 
     // Apply custom queue order if available, else fall back to numeric sort
     const customOrder = loadQueueOrder(basePath);

package/src/resources/extensions/gsd/paths.ts

@@ -10,7 +10,8 @@
  */
 
 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, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 
@@ -277,15 +278,80 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   KNOWLEDGE: "knowledge.md",
 };
 
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+
+const gsdRootCache = new Map<string, string>();
+
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache(): void {
+  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: string): string {
-  const local = join(basePath, ".gsd");
-  try {
-    const resolved = realpathSync(local);
-    if (resolved !== local) return resolved; // symlink resolved
-  } catch { /* doesn't exist yet — fall through */ }
-  return local; // backwards compat: unmigrated projects
+  const cached = gsdRootCache.get(basePath);
+  if (cached) return cached;
+
+  const result = probeGsdRoot(basePath);
+  gsdRootCache.set(basePath, result);
+  return result;
 }
 
+function probeGsdRoot(rawBasePath: string): string {
+  // 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: string;
+  try { 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: string | null = 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);
+    }
+  }
+
+  // 4. Fallback for init/creation
+  return local;
+}
 export function milestonesDir(basePath: string): string {
   return join(gsdRoot(basePath), "milestones");
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -149,11 +149,15 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
 
     // 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/src/resources/extensions/gsd/preferences-validation.ts

@@ -33,9 +33,24 @@ export function validatePreferences(preferences: GSDPreferences): {
   const validated: GSDPreferences = {};
 
   // ─── Unknown Key Detection ──────────────────────────────────────────
+  // Common key migration hints for pi-level settings that don't map to GSD prefs
+  const KEY_MIGRATION_HINTS: Record<string, string> = {
+    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`);
+      }
     }
   }
 
@@ -586,5 +601,43 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Auto Visualize ─────────────────────────────────────────────────
+  if (preferences.auto_visualize !== undefined) {
+    if (typeof preferences.auto_visualize === "boolean") {
+      validated.auto_visualize = preferences.auto_visualize;
+    } else {
+      errors.push("auto_visualize must be a boolean");
+    }
+  }
+
+  // ─── Auto Report ────────────────────────────────────────────────────
+  if (preferences.auto_report !== undefined) {
+    if (typeof preferences.auto_report === "boolean") {
+      validated.auto_report = preferences.auto_report;
+    } else {
+      errors.push("auto_report must be a boolean");
+    }
+  }
+
+  // ─── Compression Strategy ───────────────────────────────────────────
+  if (preferences.compression_strategy !== undefined) {
+    const validStrategies = new Set(["truncate", "compress"]);
+    if (typeof preferences.compression_strategy === "string" && validStrategies.has(preferences.compression_strategy)) {
+      validated.compression_strategy = preferences.compression_strategy as GSDPreferences["compression_strategy"];
+    } else {
+      errors.push(`compression_strategy must be one of: truncate, compress`);
+    }
+  }
+
+  // ─── Context Selection ──────────────────────────────────────────────
+  if (preferences.context_selection !== undefined) {
+    const validModes = new Set(["full", "smart"]);
+    if (typeof preferences.context_selection === "string" && validModes.has(preferences.context_selection)) {
+      validated.context_selection = preferences.context_selection as GSDPreferences["context_selection"];
+    } else {
+      errors.push(`context_selection must be one of: full, smart`);
+    }
+  }
+
   return { preferences: validated, errors, warnings };
 }

package/src/resources/extensions/gsd/preferences.ts

@@ -15,9 +15,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
-import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
   MODE_DEFAULTS,
@@ -141,6 +142,18 @@ export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
     };
   }
 
+  // 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 as TokenProfile | undefined;
+  if (profile) {
+    const profileDefaults = _resolveProfileDefaults(profile);
+    result = {
+      ...result,
+      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+    };
+  }
+
   // Apply mode defaults as the lowest-priority layer
   if (result.preferences.mode) {
     result = {
@@ -252,6 +265,8 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     search_provider: override.search_provider ?? base.search_provider,
     compression_strategy: override.compression_strategy ?? base.compression_strategy,
     context_selection: override.context_selection ?? base.context_selection,
+    auto_visualize: override.auto_visualize ?? base.auto_visualize,
+    auto_report: override.auto_report ?? base.auto_report,
   };
 }
 

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -28,6 +28,8 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -67,4 +67,6 @@ If verdict is `needs-remediation`:
 
 **You MUST write `{{validationPath}}` before finishing.**
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."