@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

package/src/resources/extensions/gsd/guided-flow.ts

@@ -76,9 +76,24 @@ import {
   countUnmappedActiveRequirements,
   showRequirementsBacklogReview,
 } from "./requirements-backlog.js";
-import { selectAndApplyModel } from "./auto-model-selection.js";
+import { selectAndApplyModel, getRegisteredToolSnapshot } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { supportsStructuredQuestions } from "./workflow-mcp.js";
+import {
+  detectWorkflowMcpLaunchConfig,
+  resolveWorkflowMcpProjectRoot,
+  supportsStructuredQuestions,
+} from "./workflow-mcp.js";
+import { usesWorkflowMcpTransport } from "./question-transport.js";
+import {
+  getCachedWorkflowMcpProbe,
+  probeAndCacheWorkflowMcp,
+  warmWorkflowMcpProbeInBackground,
+  workflowMcpProbeAdvertisesSurface,
+  WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+} from "./workflow-mcp-readiness-cache.js";
+import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import {
   runPreparation,
@@ -560,6 +575,93 @@ export function resolveGuidedDispatchProjectRoot(basePath?: string): string {
   return basePath ?? process.cwd();
 }
 
+/**
+ * Wait until the workflow MCP server is reachable and advertising its tool
+ * surface. Returns failure details when timed out, or null when ready (or MCP
+ * is not the transport). Called inside dispatchWorkflow() so every guided-flow
+ * dispatch path is gated automatically.
+ */
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+
+export interface WorkflowMcpReadinessFailure {
+  server: string;
+  error?: string;
+}
+
+async function awaitWorkflowMcpReadiness(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  basePath: string,
+  options: {
+    unitType?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+    probeTimeoutMs?: number;
+    probe?: typeof probeAndCacheWorkflowMcp;
+  } = {},
+): Promise<WorkflowMcpReadinessFailure | null> {
+  const provider = ctx.model?.provider;
+  const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined;
+  if (!usesWorkflowMcpTransport(authMode, ctx.model?.baseUrl)) return null;
+
+  const projectRoot = resolveWorkflowMcpProjectRoot(basePath);
+  const launch = detectWorkflowMcpLaunchConfig(projectRoot);
+  if (!launch) return null;
+
+  const requiredTools = options.unitType
+    ? getRequiredWorkflowToolsForUnit(options.unitType).filter(isWorkflowToolSurfaceName)
+    : [];
+  const coversExpectedSurface = (tools: readonly string[]) =>
+    requiredTools.length > 0
+      ? probeCoversRequiredWorkflowTools(tools, requiredTools)
+      : workflowMcpProbeAdvertisesSurface(tools);
+
+  const serverPrefix = `mcp__${launch.name}__`;
+  const systemPrompt = () => typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : "";
+  const systemPromptCoversExpectedSurface = () => {
+    const prompt = systemPrompt();
+    return requiredTools.length > 0
+      ? requiredTools.every((tool) => prompt.includes(`${serverPrefix}${tool}`))
+      : prompt.includes(serverPrefix);
+  };
+  const sessionAlreadyReady = () =>
+    coversExpectedSurface(getRegisteredToolSnapshot(pi)) ||
+    systemPromptCoversExpectedSurface();
+  if (sessionAlreadyReady()) return null;
+
+  if (coversExpectedSurface(getCachedWorkflowMcpProbe(projectRoot)?.tools ?? [])) {
+    return null;
+  }
+
+  const probe = options.probe ?? probeAndCacheWorkflowMcp;
+  const probeTimeoutMs = options.probeTimeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS;
+
+  ctx.ui.setStatus("gsd-step", `Waiting for ${launch.name} MCP server…`);
+  let lastError: string | undefined;
+  const deadline = Date.now() + (options.timeoutMs ?? MCP_READINESS_TIMEOUT_MS);
+  const pollMs = options.pollMs ?? MCP_READINESS_POLL_MS;
+  while (Date.now() < deadline) {
+    if (sessionAlreadyReady()) {
+      ctx.ui.setStatus("gsd-step", "");
+      return null;
+    }
+
+    const result = await probe(projectRoot, { timeoutMs: probeTimeoutMs });
+    if (result.ok && coversExpectedSurface(result.tools)) {
+      ctx.ui.setStatus("gsd-step", "");
+      return null;
+    }
+    lastError = result.error;
+
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  ctx.ui.setStatus("gsd-step", "");
+  return lastError ? { server: launch.name, error: lastError } : { server: launch.name };
+}
+
+export const _awaitWorkflowMcpReadinessForTest = awaitWorkflowMcpReadiness;
+
 /**
  * Read GSD-WORKFLOW.md and dispatch it to the LLM with a contextual note.
  * This is the only way the wizard triggers work — everything else is the LLM's job.
@@ -621,6 +723,29 @@ async function dispatchWorkflow(
       ctx.ui.notify(compatibilityError, "error");
       return;
     }
+
+    // ── Live MCP readiness gate ────────────────────────────────────────
+    // Units with required workflow tools must not dispatch until the MCP
+    // surface covers that exact contract; otherwise the model can race into
+    // "No such tool available" before recovery sees a clean readiness error.
+    warmWorkflowMcpProbeInBackground(projectRoot);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+    const strictBlocking = requiredWorkflowTools.length > 0
+      && (process.env.GSD_GUIDED_MCP_BLOCKING ?? "").trim() !== "0";
+    if (strictBlocking) {
+      // If the workflow MCP server is configured but still connecting, wait
+      // for it instead of dispatching into a child session that will abort.
+      const readinessFailure = await awaitWorkflowMcpReadiness(pi, ctx, projectRoot, { unitType });
+      if (readinessFailure) {
+        const detail = readinessFailure.error ? ` ${readinessFailure.error}` : "";
+        ctx.ui.notify(
+          `GSD workflow server "${readinessFailure.server}" did not connect in time.${detail} ` +
+          `Run \`/gsd mcp check ${readinessFailure.server}\` for details.`,
+          "warning",
+        );
+        return;
+      }
+    }
   }
 
   // Scope tools for guided workflow turns (#2949, token-consumption savings).
@@ -1703,6 +1828,7 @@ export async function showSmartEntry(
   options?: { step?: boolean },
 ): Promise<void> {
   const stepMode = options?.step ?? true;
+  warmWorkflowMcpProbeInBackground(basePath);
 
   // ── Clear stale milestone ID reservations from previous cancelled sessions ──
   // Reservations only need to survive within a single /gsd interaction.

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

@@ -4,7 +4,7 @@
 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 { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
@@ -22,7 +22,31 @@ export const HEALTH_WIDGET_ACTIVE_HINTS =
 
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-function loadHealthWidgetData(basePath: string): HealthWidgetData {
+// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
+// so it is treated like the other expensive checks: skipped on first paint,
+// run only by the background refresh.
+function loadLastCommitInfo(basePath: string): { epoch: number | null; message: string | null } {
+  try {
+    if (nativeIsRepo(basePath)) {
+      const branch = nativeGetCurrentBranch(basePath);
+      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+      if (epoch > 0) {
+        return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
+      }
+    }
+  } catch { /* non-fatal */ }
+  return { epoch: null, message: null };
+}
+
+function loadHealthWidgetData(
+  basePath: string,
+  options?: { includeChecks?: boolean },
+): HealthWidgetData {
+  // `includeChecks` gates the expensive subprocess-backed checks (provider +
+  // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
+  // synchronous render passes `false` so first paint is never blocked on them;
+  // the async refresh (off the first-paint path) runs the full suite.
+  const includeChecks = options?.includeChecks ?? true;
   let budgetCeiling: number | undefined;
   let budgetSpent = 0;
   let providerIssue: string | null = null;
@@ -44,40 +68,73 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData {
     }
   } catch { /* non-fatal */ }
 
+  if (includeChecks) {
+    try {
+      const providerResults = runProviderChecks();
+      providerIssue = summariseProviderIssues(providerResults);
+    } catch { /* non-fatal */ }
+
+    try {
+      const envResults = runEnvironmentChecks(basePath);
+      for (const r of envResults) {
+        if (r.status === "error") environmentErrorCount++;
+        else if (r.status === "warning") environmentWarningCount++;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // ── Last commit info ── (git spawns — gated like the other expensive checks)
+  if (includeChecks) {
+    const commit = loadLastCommitInfo(basePath);
+    lastCommitEpoch = commit.epoch;
+    lastCommitMessage = commit.message;
+  }
+
+  return {
+    projectState,
+    budgetCeiling,
+    budgetSpent,
+    providerIssue,
+    environmentErrorCount,
+    environmentWarningCount,
+    lastCommitEpoch,
+    lastCommitMessage,
+    lastRefreshed: Date.now(),
+  };
+}
+
+// Non-blocking variant used by the widget's background refresh: the cheap fields
+// come from the synchronous snapshot, then provider + environment checks are
+// layered in off the event-loop critical path (env checks run concurrently via
+// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
+// its initial enrichment or its 60s refresh.
+async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidgetData> {
+  const data = loadHealthWidgetData(basePath, { includeChecks: false });
+  let providerIssue = data.providerIssue;
+  let environmentErrorCount = 0;
+  let environmentWarningCount = 0;
+
   try {
-    const providerResults = runProviderChecks();
-    providerIssue = summariseProviderIssues(providerResults);
+    providerIssue = summariseProviderIssues(runProviderChecks());
   } catch { /* non-fatal */ }
 
   try {
-    const envResults = runEnvironmentChecks(basePath);
+    const envResults = await runEnvironmentChecksAsync(basePath);
     for (const r of envResults) {
       if (r.status === "error") environmentErrorCount++;
       else if (r.status === "warning") environmentWarningCount++;
     }
   } catch { /* non-fatal */ }
 
-  // ── Last commit info ──
-  try {
-    if (nativeIsRepo(basePath)) {
-      const branch = nativeGetCurrentBranch(basePath);
-      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-      if (epoch > 0) {
-        lastCommitEpoch = epoch;
-        lastCommitMessage = nativeCommitSubject(basePath, branch || "HEAD") || null;
-      }
-    }
-  } catch { /* non-fatal */ }
+  const commit = loadLastCommitInfo(basePath);
 
   return {
-    projectState,
-    budgetCeiling,
-    budgetSpent,
+    ...data,
     providerIssue,
     environmentErrorCount,
     environmentWarningCount,
-    lastCommitEpoch,
-    lastCommitMessage,
+    lastCommitEpoch: commit.epoch,
+    lastCommitMessage: commit.message,
     lastRefreshed: Date.now(),
   };
 }
@@ -95,8 +152,13 @@ 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);
+  // String-array fallback — used in RPC mode (factory is a no-op there).
+  // Skip the expensive provider/environment doctor checks here: this runs
+  // synchronously on the interactive-startup path, where running them would
+  // block first paint by ~0.9s (lsof/docker probes, otherwise run again
+  // immediately by the factory below). The factory's async refresh fills in
+  // real health once the screen is up.
+  const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above
@@ -110,7 +172,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       if (refreshInFlight) return;
       refreshInFlight = true;
       try {
-        data = loadHealthWidgetData(basePath);
+        data = await loadHealthWidgetDataAsync(basePath);
         cachedLines = undefined;
         if (!isDisposed) _tui.requestRender();
       } catch { /* non-fatal */ } finally {
@@ -118,9 +180,11 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       }
     };
 
-    // 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();
+    // Fire the first full enrichment off the first-paint path. setTimeout(0)
+    // yields to the initial render + input loop, so the expensive doctor checks
+    // (provider + environment) never delay the moment the user sees the UI.
+    // requestRender() inside refresh repaints the widget once data is ready.
+    setTimeout(() => { void refresh(); }, 0);
 
     const refreshTimer = setInterval(() => {
       void refresh();

package/src/resources/extensions/gsd/mcp-bridge.ts

@@ -0,0 +1,39 @@
+// mcp-bridge.ts — stable runtime seam for MCP server consumption (phase 1).
+export {
+  loadWriteGateSnapshot,
+  shouldBlockPendingGateInSnapshot,
+  shouldBlockQueueExecutionInSnapshot,
+} from "./bootstrap/write-gate.js";
+export { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+export {
+  _getAdapter,
+  checkpointDatabase,
+  closeDatabase,
+  getAllMilestones,
+  getDb,
+  getGateResults,
+  getMilestoneSlices,
+  getPendingGates,
+  getSliceTasks,
+  insertDecision,
+  insertMilestone,
+  insertSlice,
+  openDatabase,
+  upsertMilestonePlanning,
+} from "./gsd-db.js";
+export { invalidateStateCache, isReusableGhostMilestone } from "./state.js";
+export { loadEffectiveGSDPreferences } from "./preferences.js";
+export {
+  saveDecisionToDb,
+  saveRequirementToDb,
+  updateRequirementInDb,
+} from "./db-writer.js";
+export { rebuildState } from "./doctor.js";
+export { queryJournal } from "./journal.js";
+export {
+  claimReservedId,
+  findMilestoneIds,
+  getReservedMilestoneIds,
+  milestoneIdSort,
+  nextMilestoneId,
+} from "./milestone-ids.js";

package/src/resources/extensions/gsd/memory-relations.ts

@@ -3,7 +3,7 @@
 // Phase 4 companion to memory-store.ts. Edges live in the `memory_relations`
 // table and are created by (a) explicit LINK actions emitted by the memory
 // extractor, or (b) future `/gsd memory link` CLI commands. All writes go
-// through the single-writer gate in `gsd-db.ts`.
+// through typed writer wrappers re-exported by `gsd-db.ts`.
 
 import {
   _getAdapter,

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -74,8 +74,8 @@ export function evaluateAllCompleteSettlement(
     action: "pause",
     message:
       `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
-      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
-    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` to finish the system-owned merge.`,
+    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
     milestoneId,
   };
 }

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

@@ -4,7 +4,12 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { sendRemoteNotification } from "../remote-questions/notify.js";
+import { sendRemoteNotification as _sendRemoteNotification } from "../remote-questions/notify.js";
+
+/** Swappable dispatcher for remote notifications — exported so tests can mock it. */
+export const remoteNotificationDispatcher = {
+  send: _sendRemoteNotification,
+};
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -30,28 +35,30 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
   projectName?: string,
+  deps: { notifications?: NotificationPreferences } = {},
 ): void {
   // When a projectName is provided and the title is the default "GSD",
   // replace it with a project-qualified title for multi-project clarity.
   if (projectName && title === "GSD") {
     title = formatNotificationTitle(projectName);
   }
-  const loaded = loadEffectiveGSDPreferences()?.preferences;
+  const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+  const notifications = deps.notifications ?? loadedPreferences?.notifications;
 
   // Remote notifications fire independently of desktop preferences.
   // sendRemoteNotification handles "not configured" gracefully (early return).
-  void sendRemoteNotification(title, message).catch(() => {});
+  void remoteNotificationDispatcher.send(title, message).catch(() => {});
 
-  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+  if (!shouldSendDesktopNotification(kind, notifications)) return;
 
   // cmux delivery and desktop delivery are independent — if cmux import or
   // delivery fails, we must still attempt the native desktop notification.
   const runCmux = async () => {
     try {
       const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
-      const cmux = resolveCmuxConfig(loaded);
+      const cmux = resolveCmuxConfig(loadedPreferences);
       if (cmux.notifications) {
-        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+        const delivered = CmuxClient.fromPreferences(loadedPreferences).notify(title, message);
         if (delivered) return true;
         emitOsc777Notification(title, message);
       }

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

@@ -94,8 +94,13 @@ function resolveWinningPhase(
  * - Legacy: `planning: claude-opus-4-6`
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
  */
-export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedModelConfig | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+export function resolveModelWithFallbacksForUnit(
+  unitType: string,
+  basePath?: string,
+  availableModelIds?: string[],
+): ResolvedModelConfig | undefined {
+  const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
   const chain = phaseChainForUnit(unitType);
   if (!chain) return undefined;
   const winner = resolveWinningPhase(prefs?.preferences?.models as GSDModelConfigV2 | undefined, chain);
@@ -141,8 +146,13 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
  * floor. Session level, defaults, the floor, and capability clamping are NOT
  * applied here.
  */
-export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] })?.preferences;
+export function resolveThinkingLevelForUnit(
+  unitType: string,
+  basePath?: string,
+  availableModelIds?: string[],
+): GSDThinkingLevel | undefined {
+  const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts)?.preferences;
   if (!prefs) return undefined;
   const chain = phaseChainForUnit(unitType);
   if (!chain) return undefined;
@@ -186,8 +196,10 @@ export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel
 export function resolveDefaultSessionModel(
   sessionProvider?: string,
   basePath?: string,
+  availableModelIds?: string[],
 ): { provider: string; id: string } | undefined {
-  const prefs = loadEffectiveGSDPreferences(basePath, { availableModelIds: [] });
+  const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
+  const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
   const models = prefs?.preferences?.models;
   if (!models) return undefined;
 
@@ -413,7 +425,10 @@ export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
 
 // ─── Token Profile Resolution ─────────────────────────────────────────────
 
-const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
+export const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
+
+/** D046: balanced is the implicit profile when `token_profile` is omitted. */
+export const DEFAULT_TOKEN_PROFILE: TokenProfile = "balanced";
 
 /**
  * Per-phase tier intentions for each token profile.
@@ -459,8 +474,11 @@ const PROFILE_TIER_MAP: Record<TokenProfile, Record<string, ComplexityTier>> = {
  *
  * Model IDs are resolved from capability tiers, not hardcoded to any
  * provider. When available models are known (runtime), the resolver picks
- * the best match across all configured providers. When not known (e.g.,
- * early startup), falls back to canonical Anthropic model IDs.
+ * the best match on the anchor provider (session / auto-start model). Callers
+ * scope the available-model list via `modelIdsForProfileResolution` so token
+ * profiles do not hop to a cheaper provider (e.g. Gemini Flash) when the user
+ * is working on OpenAI or Anthropic. When not known (e.g., early startup),
+ * falls back to canonical Anthropic model IDs.
  *
  * @param profile           The token profile to resolve
  * @param availableModelIds Optional list of available model IDs for cross-provider resolution.

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

@@ -20,7 +20,12 @@ import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { logWarning } from "./workflow-logger.js";
-import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
+import {
+  DEFAULT_TOKEN_PROFILE,
+  resolveProfileDefaults as _resolveProfileDefaults,
+  VALID_TOKEN_PROFILES,
+  resolveDisabledModelProvidersFromPreferences,
+} from "./preferences-models.js";
 import { nativeHasCommittedHead, nativeIsRepo } from "./native-git-bridge.js";
 
 import {
@@ -142,6 +147,90 @@ export function getProjectGSDPreferencesPath(basePath?: string): string {
   return projectPreferencesPath(basePath);
 }
 
+/** Minimal model-registry surface for provider-aware preference resolution. */
+export type PreferencesModelRegistry = {
+  getAvailable: () => ReadonlyArray<{ provider: string; id: string }>;
+};
+
+/** Format registry models the same way tier resolution and prefs persistence use. */
+export function availableModelIdsFromRegistry(registry: PreferencesModelRegistry): string[] {
+  return registry.getAvailable().map((m) => `${m.provider}/${m.id}`);
+}
+
+/**
+ * Keep only provider-qualified model IDs for a single provider (case-insensitive).
+ * Bare IDs are excluded — tier resolution requires provider/model form.
+ */
+export function restrictModelIdsToProvider(modelIds: string[], provider: string): string[] {
+  const normalized = provider.trim().toLowerCase();
+  if (!normalized) return modelIds;
+  return modelIds.filter((id) => {
+    const slash = id.indexOf("/");
+    if (slash <= 0) return false;
+    return id.slice(0, slash).toLowerCase() === normalized;
+  });
+}
+
+/**
+ * Model IDs for token-profile tier resolution. When an anchor provider is known
+ * (session model / auto-start snapshot), stay on that provider instead of picking
+ * the globally cheapest tier match across every logged-in provider (e.g. Gemini
+ * Flash beating GPT mini on cost).
+ */
+export function modelIdsForProfileResolution(
+  registry: PreferencesModelRegistry,
+  anchorProvider?: string,
+  disabledProviders?: string[],
+): string[] | undefined {
+  let all = availableModelIdsFromRegistry(registry);
+  if (disabledProviders?.length) {
+    const blocked = new Set(
+      disabledProviders.map((p) => p.trim().toLowerCase()).filter((p) => p.length > 0),
+    );
+    all = all.filter((id) => {
+      const slash = id.indexOf("/");
+      if (slash <= 0) return true;
+      return !blocked.has(id.slice(0, slash).toLowerCase());
+    });
+  }
+  if (all.length === 0) return undefined;
+  if (!anchorProvider?.trim()) return all;
+  // Stay on the anchor provider — do not fall back to the full registry when the
+  // scoped list is empty (that reintroduces cross-provider cost picks like Gemini).
+  return restrictModelIdsToProvider(all, anchorProvider);
+}
+
+/** Provider anchor for token-profile tier resolution (auto-start model wins). */
+export function resolveProfileAnchorProvider(
+  sessionProvider?: string,
+  autoModeStartProvider?: string | null,
+): string | undefined {
+  const start = autoModeStartProvider?.trim();
+  if (start) return start;
+  const session = sessionProvider?.trim();
+  return session || undefined;
+}
+
+/**
+ * Load effective preferences with token-profile tiers resolved against models
+ * the user can actually call (from the live registry), not canonical Anthropic
+ * fallbacks.
+ */
+export function loadEffectiveGSDPreferencesWithRegistry(
+  registry: PreferencesModelRegistry | undefined,
+  basePath?: string,
+  anchorProvider?: string,
+): LoadedGSDPreferences | null {
+  if (!registry) {
+    return loadEffectiveGSDPreferences(basePath);
+  }
+  const disabledProviders = resolveDisabledModelProvidersFromPreferences();
+  const availableModelIds = modelIdsForProfileResolution(registry, anchorProvider, disabledProviders);
+  if (!availableModelIds) {
+    return loadEffectiveGSDPreferences(basePath);
+  }
+  return loadEffectiveGSDPreferences(basePath, { availableModelIds });
+}
 
 /**
  * Normalize a value loaded from disk (or passed from another component) into
@@ -220,16 +309,27 @@ export function loadEffectiveGSDPreferences(
   // 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 explicitProfile = result.preferences.token_profile as TokenProfile | undefined;
+  let profileForDefaults: TokenProfile | undefined;
+  if (explicitProfile) {
+    if (VALID_TOKEN_PROFILES.has(explicitProfile)) {
+      profileForDefaults = explicitProfile;
+    }
+  } else {
+    profileForDefaults = DEFAULT_TOKEN_PROFILE;
+  }
+  if (profileForDefaults) {
     const profileDefaults = _resolveProfileDefaults(
-      profile,
+      profileForDefaults,
       opts?.availableModelIds,
       result.preferences.dynamic_routing,
     );
+    const defaultsToApply = explicitProfile
+      ? profileDefaults
+      : withoutProfilePhaseDefaults(profileDefaults);
     result = {
       ...result,
-      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+      preferences: mergePreferences(defaultsToApply as GSDPreferences, result.preferences),
     };
   }
 
@@ -246,6 +346,12 @@ export function loadEffectiveGSDPreferences(
   return result;
 }
 
+function withoutProfilePhaseDefaults(defaults: Partial<GSDPreferences>): Partial<GSDPreferences> {
+  if (defaults.phases === undefined) return defaults;
+  const { phases: _phases, ...rest } = defaults;
+  return rest;
+}
+
 function mergePreferenceMetadata(
   primary: LoadedGSDPreferences,
   secondary: LoadedGSDPreferences | null,