gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/model-router.ts

@@ -320,11 +320,8 @@ export function getEligibleModels(
     // Exact match
     if (availableModelIds.includes(explicitModel)) return [explicitModel];
     // Provider-prefix-stripped match
-    const match = availableModelIds.find(id => {
-      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
-      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
-      return bareAvail === bareExplicit;
-    });
+    const bareExplicit = bareModelId(explicitModel);
+    const match = availableModelIds.find(id => bareModelId(id) === bareExplicit);
     if (match) return [match];
   }
 
@@ -430,12 +427,38 @@ export function resolveModelForComplexity(
 
   // Downgrade-only: if requested tier >= configured tier, no change
   if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
+    // If the configured primary is directly available, use it
+    if (isModelAvailable(configuredPrimary, availableModelIds)) {
+      return {
+        modelId: configuredPrimary,
+        fallbacks: phaseConfig.fallbacks,
+        tier: requestedTier,
+        wasDowngraded: false,
+        reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+        selectionMethod: "tier-only",
+      };
+    }
+
+    // Configured primary is unavailable (e.g. Anthropic model configured but
+    // running on a non-Anthropic provider). Find the best available model at
+    // the same capability tier so routing still works cross-provider.
+    const crossProviderEquivalent = findModelForTier(
+      configuredTier,
+      routingConfig,
+      availableModelIds,
+      routingConfig.cross_provider !== false,
+    );
+
     return {
-      modelId: configuredPrimary,
-      fallbacks: phaseConfig.fallbacks,
+      modelId: crossProviderEquivalent ?? configuredPrimary,
+      fallbacks: crossProviderEquivalent
+        ? [...phaseConfig.fallbacks.filter(f => f !== crossProviderEquivalent), configuredPrimary]
+        : phaseConfig.fallbacks,
       tier: requestedTier,
       wasDowngraded: false,
-      reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+      reason: crossProviderEquivalent
+        ? `cross-provider ${configuredTier}-tier equivalent`
+        : `tier ${requestedTier} >= configured ${configuredTier}`,
       selectionMethod: "tier-only",
     };
   }
@@ -519,8 +542,131 @@ export function defaultRoutingConfig(): DynamicRoutingConfig {
   };
 }
 
+// ─── Tier-Based Model Resolution (for profile defaults) ─────────────────────
+
+/**
+ * Fallback-only canonical model IDs per tier. Returned when the
+ * available-model list is empty (e.g., preferences are loaded before the
+ * model registry is populated at bootstrap), or when a non-empty registry has
+ * no model at the requested tier.
+ *
+ * Precedence (resolveModelForTier):
+ *   1. configured `tier_models[tier]` (via getEligibleModels) — exact/bare match
+ *   2. cheapest available model whose tier matches `tier`
+ *   3. CANONICAL_TIER_MODELS[tier] as last-resort fallback
+ */
+const CANONICAL_TIER_MODELS: Record<ComplexityTier, string> = {
+  light: "claude-haiku-4-5",
+  standard: "claude-sonnet-4-6",
+  heavy: "claude-opus-4-6",
+};
+
+export function canonicalModelForTier(tier: ComplexityTier): string {
+  return CANONICAL_TIER_MODELS[tier];
+}
+
+/**
+ * Single source of truth for tier-based model selection.
+ * Returns the cheapest available model whose capability tier matches `tier`,
+ * honoring `routingConfig.tier_models[tier]` when set. Returns undefined when
+ * no available model matches the tier.
+ *
+ * `crossProvider`: when false, restricts the search to models that share the
+ * canonical (Anthropic) provider for the tier. When true, any provider is
+ * eligible.
+ */
+function findModelForTier(
+  tier: ComplexityTier,
+  routingConfig: DynamicRoutingConfig,
+  availableModelIds: string[],
+  crossProvider: boolean,
+): string | undefined {
+  const eligible = getEligibleModels(tier, availableModelIds, routingConfig);
+  if (eligible.length === 0) return undefined;
+
+  if (crossProvider) {
+    return eligible[0];
+  }
+
+  // Same-provider only: keep models whose bare ID matches a canonical
+  // Anthropic ID at this tier (i.e., a claude-* model in the tier map).
+  const sameProvider = eligible.filter(id => {
+    const bare = bareModelId(id);
+    return MODEL_CAPABILITY_TIER[bare] === tier && bare.startsWith("claude-");
+  });
+  return sameProvider[0];
+}
+
+/**
+ * Resolve a concrete model ID for a given capability tier using the
+ * available model list. Provider-agnostic: picks the best available
+ * model at the requested tier.
+ *
+ * Precedence:
+ *   1. configured `tier_models[tier]`, if provided and available
+ *   2. tier-matching model from any provider in `availableModelIds`
+ *   3. canonical Anthropic ID as a fallback only when nothing else matches
+ *      (or `availableModelIds` is empty, e.g., during early bootstrap)
+ *
+ * @param tier              The capability tier to resolve
+ * @param availableModelIds List of available model IDs (REQUIRED for
+ *                          provider-agnostic resolution; pass [] only when
+ *                          the model registry is genuinely unavailable)
+ * @param routingConfig     Optional routing config, or legacy crossProvider boolean
+ * @param crossProvider     Whether to consider models from other providers
+ */
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  crossProvider?: boolean,
+): string;
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  routingConfig?: DynamicRoutingConfig,
+  crossProvider?: boolean,
+): string;
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  routingConfigOrCrossProvider: DynamicRoutingConfig | boolean = defaultRoutingConfig(),
+  crossProvider?: boolean,
+): string {
+  const routingConfig = typeof routingConfigOrCrossProvider === "boolean"
+    ? defaultRoutingConfig()
+    : { ...defaultRoutingConfig(), ...routingConfigOrCrossProvider };
+  const allowCrossProvider = typeof routingConfigOrCrossProvider === "boolean"
+    ? routingConfigOrCrossProvider
+    : crossProvider ?? routingConfig.cross_provider !== false;
+
+  // No available models known — return canonical fallback
+  if (availableModelIds.length === 0) {
+    return canonicalModelForTier(tier);
+  }
+
+  // Cross-provider tier search
+  const resolved = findModelForTier(tier, routingConfig, availableModelIds, allowCrossProvider);
+  return resolved
+    ? normalizeResolvedTierModelId(resolved, tier, routingConfig)
+    : canonicalModelForTier(tier);
+}
+
 // ─── Internal ────────────────────────────────────────────────────────────────
 
+/**
+ * Check whether a model ID is present in the available models list.
+ * Handles bare IDs ("claude-opus-4-6") and provider-prefixed IDs ("anthropic/claude-opus-4-6").
+ */
+function isModelAvailable(modelId: string, availableModelIds: string[]): boolean {
+  if (availableModelIds.includes(modelId)) return true;
+  // Strip provider prefix for comparison. Treat trailing-slash IDs ("provider/")
+  // as no-bare-ID rather than empty-string match (which would erroneously match
+  // any other "provider/" ID).
+  const bare = bareModelId(modelId);
+  if (!bare) return false;
+  return availableModelIds.some(id => bareModelId(id) === bare);
+}
+
 function getModelTier(modelId: string): ComplexityTier {
   // Strip provider prefix if present
   const bareId = bareModelId(modelId);
@@ -563,8 +709,25 @@ function getModelCost(modelId: string): number {
   return 999;
 }
 
+function normalizeResolvedTierModelId(
+  modelId: string,
+  tier: ComplexityTier,
+  routingConfig: DynamicRoutingConfig,
+): string {
+  const explicitModel = routingConfig.tier_models?.[tier];
+  if (explicitModel?.includes("/")) {
+    return modelId;
+  }
+
+  const bareId = bareModelId(modelId);
+  return MODEL_CAPABILITY_TIER[bareId] ? bareId : modelId;
+}
+
 function bareModelId(modelId: string): string {
-  return modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+  if (!modelId.includes("/")) return modelId;
+  // .pop() never returns undefined on a non-empty string but ?? guards future
+  // refactors and avoids the misleading non-null assertion.
+  return modelId.split("/").pop() ?? modelId;
 }
 
 // ─── Provider-specific Tool Limits ─────────────────────────────────────────

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isInfrastructureError } from "./auto/infra-errors.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -846,6 +847,10 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
     });
   } catch (err: unknown) {
     const stderr = (err as { stderr?: string })?.stderr ?? "";
+    const infraCode = isInfrastructureError(err) ?? isInfrastructureError(stderr);
+    if (infraCode) {
+      throw err;
+    }
     // git exits 1 when pathspec exclusions reference paths already covered
     // by .gitignore. The staging itself succeeds — only suppress that case.
     if (stderr.includes("ignored by one of your .gitignore files")) {
@@ -860,7 +865,8 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
       fallbackStageWithSymlinkedDotGsd(basePath);
       return;
     }
-    throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);
+    const stderrDetail = stderr.trim() ? `; stderr: ${stderr.trim()}` : "";
+    throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}${stderrDetail}`);
   }
 }
 

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

@@ -10,7 +10,8 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { DynamicRoutingConfig } from "./model-router.js";
-import { defaultRoutingConfig } from "./model-router.js";
+import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
+import type { ComplexityTier } from "./complexity-classifier.js";
 import type { TokenProfile, InlineLevel } from "./types.js";
 
 import type {
@@ -43,7 +44,7 @@ export function resolveModelForUnit(unitType: string): string | undefined {
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
  */
 export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedModelConfig | undefined {
-  const prefs = loadEffectiveGSDPreferences();
+  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
   if (!prefs?.preferences.models) return undefined;
   const m = prefs.preferences.models as GSDModelConfigV2;
 
@@ -132,7 +133,7 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
 export function resolveDefaultSessionModel(
   sessionProvider?: string,
 ): { provider: string; id: string } | undefined {
-  const prefs = loadEffectiveGSDPreferences();
+  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
   if (!prefs?.preferences.models) return undefined;
 
   const m = prefs.preferences.models as GSDModelConfigV2;
@@ -358,22 +359,86 @@ export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
 
 const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
 
+/**
+ * Per-phase tier intentions for each token profile.
+ * Profiles express capability tiers, not model IDs. Concrete model
+ * resolution happens at runtime via resolveModelForTier() which is
+ * provider-agnostic — it picks the best available model at each tier.
+ */
+const PROFILE_TIER_MAP: Record<TokenProfile, Record<string, ComplexityTier>> = {
+  budget: {
+    planning: "standard",
+    research: "light",
+    execution: "standard",
+    execution_simple: "light",
+    completion: "light",
+    subagent: "light",
+  },
+  balanced: {
+    planning: "standard",
+    research: "standard",
+    execution: "standard",
+    execution_simple: "light",
+    completion: "light",
+    subagent: "light",
+  },
+  quality: {
+    planning: "heavy",
+    research: "standard",
+    execution: "standard",
+    execution_simple: "light",
+    completion: "light",
+    subagent: "standard",
+  },
+  // burn-max intentionally omits a tier map: it never writes model defaults
+  // (it preserves the user's explicit model selection), so resolveProfileDefaults
+  // skips model resolution for this profile.
+  "burn-max": {},
+};
+
 /**
  * Resolve profile defaults for a given token profile tier.
  * Returns a partial GSDPreferences that is used as the base layer --
  * explicit user preferences always override these defaults.
+ *
+ * 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.
+ *
+ * @param profile           The token profile to resolve
+ * @param availableModelIds Optional list of available model IDs for cross-provider resolution.
+ *                          Undefined means the registry is unavailable.
+ * @param routingConfig     Optional routing config for tier model pins.
  */
-export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPreferences> {
+export function resolveProfileDefaults(
+  profile: TokenProfile,
+  availableModelIds?: string[],
+  routingConfig: DynamicRoutingConfig = defaultRoutingConfig(),
+): Partial<GSDPreferences> {
+  // burn-max never writes model defaults — preserve user-selected models.
+  // For the other three profiles, derive concrete model IDs from the tier map
+  // against the available-model list when the registry is provided. If callers
+  // omit the registry entirely, use canonical fallbacks explicitly.
+  const tierMap = PROFILE_TIER_MAP[profile];
+  const resolveTierModel = (tier: ComplexityTier): string => Array.isArray(availableModelIds)
+    ? resolveModelForTier(tier, availableModelIds, routingConfig)
+    : canonicalModelForTier(tier);
+  const models: GSDModelConfigV2 | undefined = profile === "burn-max"
+    ? undefined
+    : {
+        planning: resolveTierModel(tierMap.planning),
+        research: resolveTierModel(tierMap.research),
+        execution: resolveTierModel(tierMap.execution),
+        execution_simple: resolveTierModel(tierMap.execution_simple),
+        completion: resolveTierModel(tierMap.completion),
+        subagent: resolveTierModel(tierMap.subagent),
+      };
+
   switch (profile) {
     case "budget":
       return {
-        models: {
-          planning: "claude-sonnet-4-5-20250514",
-          execution: "claude-sonnet-4-5-20250514",
-          execution_simple: "claude-haiku-4-5-20250414",
-          completion: "claude-haiku-4-5-20250414",
-          subagent: "claude-haiku-4-5-20250414",
-        },
+        models,
         phases: {
           skip_research: true,
           skip_reassess: true,
@@ -383,9 +448,7 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
       };
     case "balanced":
       return {
-        models: {
-          subagent: "claude-sonnet-4-5-20250514",
-        },
+        models,
         phases: {
           skip_research: true,
           skip_reassess: true,
@@ -394,7 +457,7 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
       };
     case "quality":
       return {
-        models: {},
+        models,
         phases: {
           skip_research: true,
           skip_slice_research: true,
@@ -420,6 +483,14 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
   }
 }
 
+/**
+ * Get the tier intentions for a profile without resolving to model IDs.
+ * Useful for display, debugging, and testing.
+ */
+export function getProfileTierMap(profile: TokenProfile): Record<string, ComplexityTier> {
+  return { ...PROFILE_TIER_MAP[profile] };
+}
+
 /**
  * Resolve the effective token profile from preferences.
  * Returns "balanced" when no profile is set (D046).
@@ -465,3 +536,18 @@ export function resolveSearchProviderFromPreferences(): GSDPreferences["search_p
   const prefs = loadEffectiveGSDPreferences();
   return prefs?.preferences.search_provider;
 }
+
+/**
+ * Resolve provider IDs excluded from model selection/routing.
+ * Returns a normalized, de-duplicated list.
+ */
+export function resolveDisabledModelProvidersFromPreferences(): string[] {
+  const prefs = loadEffectiveGSDPreferences();
+  const raw = prefs?.preferences.disabled_model_providers;
+  if (!Array.isArray(raw)) return [];
+  return Array.from(new Set(
+    raw
+      .map((provider) => provider.trim())
+      .filter((provider) => provider.length > 0),
+  ));
+}

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

@@ -114,6 +114,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "post_unit_hooks",
   "pre_dispatch_hooks",
   "dynamic_routing",
+  "disabled_model_providers",
   "uok",
   "token_profile",
   "phases",
@@ -132,6 +133,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "service_tier",
   "forensics_dedup",
   "show_token_cost",
+  "min_request_interval_ms",
   "stale_commit_threshold_minutes",
   "context_management",
   "experimental",
@@ -320,6 +322,8 @@ export interface GSDPreferences {
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
   dynamic_routing?: DynamicRoutingConfig;
+  /** Provider IDs to exclude from /model and automatic model routing while leaving tool auth intact. */
+  disabled_model_providers?: string[];
   /** Unified Orchestration Kernel controls (default-on, with opt-out and emergency legacy fallback). */
   uok?: UokPreferences;
   /** Per-model capability overrides. Deep-merged with built-in profiles for capability-aware routing (ADR-004). */
@@ -365,6 +369,8 @@ export interface GSDPreferences {
   forensics_dedup?: boolean;
   /** Opt-in: show per-prompt and cumulative session token cost in the footer. Default: false. */
   show_token_cost?: boolean;
+  /** Proactive rate limiting: minimum milliseconds between auto-mode LLM requests. Prevents 429s on rate-limited providers. 0 = disabled (default). */
+  min_request_interval_ms?: number;
   /**
    * Minutes without a commit before flagging uncommitted changes as stale.
    * When the threshold is exceeded and the working tree is dirty, doctor will

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

@@ -610,6 +610,27 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Disabled Model Providers ───────────────────────────────────────
+  if (preferences.disabled_model_providers !== undefined) {
+    if (Array.isArray(preferences.disabled_model_providers)) {
+      const allStrings = preferences.disabled_model_providers.every(
+        (provider: unknown) => typeof provider === "string",
+      );
+      if (!allStrings) {
+        errors.push("disabled_model_providers must be an array of strings");
+      } else {
+        const normalized = preferences.disabled_model_providers
+          .map((provider) => provider.trim())
+          .filter((provider) => provider.length > 0);
+        if (normalized.length > 0) {
+          validated.disabled_model_providers = Array.from(new Set(normalized));
+        }
+      }
+    } else {
+      errors.push("disabled_model_providers must be an array of strings");
+    }
+  }
+
   // ─── Context Management ──────────────────────────────────────────────
   if (preferences.context_management !== undefined) {
     if (typeof preferences.context_management === "object" && preferences.context_management !== null) {
@@ -1101,6 +1122,20 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Auto-Mode Request Interval ───────────────────────────────────
+  if (preferences.min_request_interval_ms !== undefined) {
+    if (
+      typeof preferences.min_request_interval_ms === "number" &&
+      Number.isFinite(preferences.min_request_interval_ms) &&
+      preferences.min_request_interval_ms >= 0 &&
+      preferences.min_request_interval_ms <= 2_147_483_647
+    ) {
+      validated.min_request_interval_ms = Math.floor(preferences.min_request_interval_ms);
+    } else {
+      errors.push("min_request_interval_ms must be a non-negative number <= 2147483647");
+    }
+  }
+
   // ─── Experimental Features ────────────────────────────────────────
   if (preferences.experimental !== undefined) {
     if (typeof preferences.experimental === "object" && preferences.experimental !== null) {

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

@@ -89,10 +89,12 @@ export {
   resolveDynamicRoutingConfig,
   resolveAutoSupervisorConfig,
   resolveProfileDefaults,
+  getProfileTierMap,
   resolveEffectiveProfile,
   resolveInlineLevel,
   resolveContextSelection,
   resolveSearchProviderFromPreferences,
+  resolveDisabledModelProvidersFromPreferences,
 } from "./preferences-models.js";
 
 // ─── Path Constants & Getters ───────────────────────────────────────────────
@@ -146,7 +148,10 @@ export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferenc
     ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
 
-export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
+export function loadEffectiveGSDPreferences(
+  basePath?: string,
+  opts?: { availableModelIds?: string[] },
+): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
   const projectPreferences = loadProjectGSDPreferences(basePath);
 
@@ -175,7 +180,11 @@ export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPrefere
   // Explicit user preferences always override profile defaults.
   const profile = result.preferences.token_profile as TokenProfile | undefined;
   if (profile) {
-    const profileDefaults = _resolveProfileDefaults(profile);
+    const profileDefaults = _resolveProfileDefaults(
+      profile,
+      opts?.availableModelIds,
+      result.preferences.dynamic_routing,
+    );
     result = {
       ...result,
       preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
@@ -380,6 +389,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
       ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
       : undefined,
+    disabled_model_providers: mergeStringLists(
+      base.disabled_model_providers,
+      override.disabled_model_providers,
+    ),
     uok: (base.uok || override.uok)
       ? {
           enabled: override.uok?.enabled ?? base.uok?.enabled,
@@ -433,6 +446,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     service_tier: override.service_tier ?? base.service_tier,
     forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
     show_token_cost: override.show_token_cost ?? base.show_token_cost,
+    min_request_interval_ms: override.min_request_interval_ms ?? base.min_request_interval_ms,
     codebase: (base.codebase || override.codebase)
       ? {
           ...(base.codebase ?? {}),

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -7,14 +7,13 @@
  * Templates live at prompts/ relative to this module's directory.
  * They use {{variableName}} syntax for substitution.
  *
- * All templates are eagerly loaded into cache at module init via warmCache().
- * This prevents a running session from being invalidated when another `gsd`
- * launch overwrites ~/.gsd/agent/ with newer templates via initResources().
- * Without eager caching, the in-memory extension code (which knows variable
- * set A) can read a newer template from disk (which expects variable set B),
- * causing a "template declares {{X}} but no value was provided" crash
- * mid-session — especially for late-loading templates like complete-milestone
- * that aren't read until the end of a long auto-mode run.
+ * Templates are snapshotted shortly after module init via warmCache().
+ * This keeps import/extension-registration fast while still preventing a
+ * running session from being invalidated when another `gsd` launch overwrites
+ * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * in-memory extension code (which knows variable set A) can read a newer
+ * template from disk (which expects variable set B), causing a
+ * "template declares {{X}} but no value was provided" crash mid-session.
  */
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
@@ -82,8 +81,8 @@ export function getTemplatesDir(): string {
   return templatesDir;
 }
 
-// Cache all templates eagerly at module load — a running session uses the
-// template versions that were on disk at startup, immune to later overwrites.
+// Cache all templates from a startup snapshot — a running session uses the
+// template versions that were on disk near startup, immune to later overwrites.
 const templateCache = new Map<string, string>();
 
 /**
@@ -124,8 +123,23 @@ function warmCache(): void {
   }
 }
 
-// Snapshot all templates at module load time
-warmCache();
+let warmCacheScheduled = false;
+
+function scheduleWarmCache(): void {
+  if (warmCacheScheduled) return;
+  warmCacheScheduled = true;
+
+  const run = () => {
+    warmCache();
+  };
+
+  const timer = setTimeout(run, 1000);
+  timer.unref?.();
+}
+
+// Snapshot the full prompt/template tree after import so extension startup only
+// pays for prompts that are actually needed immediately.
+scheduleWarmCache();
 
 /**
  * Load a prompt template and substitute variables.

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

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

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

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
+- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.