@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

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

@@ -11,7 +11,7 @@
  */
 
 import { readdirSync, existsSync, realpathSync, statSync, Dirent } from "node:fs";
-import { join, dirname, normalize, resolve } from "node:path";
+import { join, dirname, normalize, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
@@ -379,21 +379,26 @@ export function resolveGsdPathContract(
   const resolvedWorkRoot = resolve(workRoot || process.cwd());
   const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
   if (isWorktree && !originalProjectRoot?.trim()) {
-    const projectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
-    if (projectGsd) {
+    const rawProjectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
+    if (rawProjectGsd) {
+      // Canonicalize the `.gsd` root so the DB path matches what every other
+      // accessor (gsdRoot/gsdProjectionRoot) returns — otherwise an unresolved
+      // symlink (e.g. `/mnt/c/.../.gsd` → native ext4 on WSL) selects the wrong
+      // journal mode and yields a fragile, move-prone handle. See issue #1239.
+      const projectGsd = normalizeRealPath(rawProjectGsd);
       return {
         projectRoot: dirname(dirname(projectGsd)),
         workRoot: resolvedWorkRoot,
         projectGsd,
-        worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+        worktreeGsd: normalizeRealPath(join(resolvedWorkRoot, ".gsd")),
         projectDb: join(projectGsd, "gsd.db"),
         isWorktree,
       };
     }
   }
   const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
-  const projectGsd = join(projectRoot, ".gsd");
-  const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+  const projectGsd = normalizeRealPath(join(projectRoot, ".gsd"));
+  const worktreeGsd = isWorktree ? normalizeRealPath(join(resolvedWorkRoot, ".gsd")) : null;
 
   return {
     projectRoot,
@@ -696,7 +701,16 @@ function pickPreferredPhaseDir(phasesDir: string, matches: string[]): string {
   return best;
 }
 
-function phaseDirMatchesMilestoneId(dirName: string, milestoneId: string, phaseNum: number): boolean {
+function slugLooksLikeTeamSuffixProjection(slugPart: string): boolean {
+  return /^[a-z0-9]{6}(-|$)/.test(slugPart);
+}
+
+function phaseDirMatchesMilestoneId(
+  dirName: string,
+  milestoneId: string,
+  phaseNum: number,
+  allowTeamSuffixSlugs = false,
+): boolean {
   const numMatch = dirName.match(/^(\d+)-(.*)$/);
   if (!numMatch || parseInt(numMatch[1]!, 10) !== phaseNum) return false;
   const slugPart = numMatch[2]!;
@@ -704,8 +718,8 @@ function phaseDirMatchesMilestoneId(dirName: string, milestoneId: string, phaseN
   if (suffix) {
     return slugPart === suffix || slugPart.startsWith(`${suffix}-`);
   }
-  // Plain sequential IDs must not resolve to unique-suffix phase dirs.
-  return !/^[a-z0-9]{6}(-|$)/.test(slugPart);
+  if (slugLooksLikeTeamSuffixProjection(slugPart) && !allowTeamSuffixSlugs) return false;
+  return true;
 }
 
 function resolvePhaseDir(basePath: string, milestoneId: string): string | null {
@@ -726,6 +740,15 @@ function resolvePhaseDir(basePath: string, milestoneId: string): string | null {
           matches.push(entry.name);
         }
       }
+      // Bare milestone ids may only have a suffixed team-mode projection on disk.
+      if (matches.length === 0 && !milestoneIdUniqueSuffix(milestoneId)) {
+        for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          if (phaseDirMatchesMilestoneId(entry.name, milestoneId, phaseNum, true)) {
+            matches.push(entry.name);
+          }
+        }
+      }
     } catch {
       // unreadable — fall through
     }
@@ -898,10 +921,24 @@ export function resolveTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
   taskId: string, suffix: string
 ): string | null {
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  if (!phaseDir) return null;
+
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+
+  if (suffix !== "PLAN" && !isLegacy) {
+    const flatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
+    return existsSync(flatPath) ? flatPath : null;
+  }
+
   const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
-  if (!tDir) return null;
-  const file = resolveFile(tDir, taskId, suffix);
-  return file ? join(tDir, file) : null;
+  if (tDir) {
+    const file = resolveFile(tDir, taskId, suffix);
+    if (file) return join(tDir, file);
+  }
+
+  return null;
 }
 
 // ─── Relative Path Builders (for prompts — .gsd/milestones/...) ────────────
@@ -936,31 +973,41 @@ export function relMilestonePath(basePath: string, milestoneId: string, title?:
 }
 
 /**
- * Build relative .gsd/ path to a milestone file.
- * Layout-aware: uses resolveMilestoneFile to find NN-SUFFIX.md (flat-phase)
- * or M001-SUFFIX.md (legacy). Falls back to a layout-appropriate canonical
- * name when the file doesn't exist yet.
+ * Build the canonical absolute write target for a milestone file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveMilestoneFile first.
  */
-export function relMilestoneFile(
-  basePath: string, milestoneId: string, suffix: string
+export function targetMilestoneFile(
+  basePath: string, milestoneId: string, suffix: string, title?: string
 ): string {
-  const mRel = relMilestonePath(basePath, milestoneId);
-  // resolveMilestoneFile checks NN-SUFFIX.md (flat-phase) and MID-SUFFIX.md (legacy).
-  const absFile = resolveMilestoneFile(basePath, milestoneId, suffix);
-  if (absFile) {
-    const fileName = absFile.split(/[/\\]/).pop()!;
-    return `${mRel}/${fileName}`;
-  }
-  // File doesn't exist yet — use layout-aware fallback filename.
   const mDir = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
   const isLegacy = mDir
     ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-    : false;
+    : isLegacyMilestonesLayout(basePath);
+  const dir = mDir ?? join(
+    isLegacy ? legacyBase : milestonesDir(basePath),
+    isLegacy ? milestoneId : canonicalPhaseDirName(milestoneId, title),
+  );
   const fileName = isLegacy
     ? `${milestoneId}-${suffix}.md`
     : `${String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0")}-${suffix}.md`;
-  return `${mRel}/${fileName}`;
+  return join(dir, fileName);
+}
+
+/**
+ * Build relative .gsd/ path to a milestone file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relMilestoneFile(
+  basePath: string, milestoneId: string, suffix: string, title?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveMilestoneFile(basePath, milestoneId, suffix) ?? targetMilestoneFile(basePath, milestoneId, suffix, title),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -992,34 +1039,44 @@ export function relSlicePath(
 }
 
 /**
- * Build relative .gsd/ path to a slice file.
- * Layout-aware: legacy uses S01-SUFFIX.md; flat-phase uses NN-MM-SUFFIX.md.
- *
- * @param milestoneTitle - Optional milestone title forwarded to relSlicePath /
- *   relMilestonePath for title-aware flat-phase fallback dir naming. Only used
- *   when the phase directory does not yet exist on disk.
+ * Build the canonical absolute write target for a slice file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveSliceFile first.
  */
-export function relSliceFile(
+export function targetSliceFile(
   basePath: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
 ): string {
-  const sRel = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, suffix);
-  if (absPath) {
-    const fileName = absPath.split(/[/\\]/).pop()!;
-    return `${sRel}/${fileName}`;
-  }
-  // Fallback when file doesn't exist yet — use layout-aware filename.
   const mDir = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
   const isLegacy = mDir
     ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-    : false;
-  if (isLegacy) {
-    return `${sRel}/${sliceId}-${suffix}.md`;
-  }
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  return `${sRel}/${planFileName(phaseNum, planNum, suffix)}`;
+    : isLegacyMilestonesLayout(basePath);
+  const milestoneDir = mDir
+    ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestoneTitle));
+  const slicesDir = join(milestoneDir, "slices");
+  const dir = isLegacy
+    ? join(slicesDir, resolveDir(slicesDir, sliceId) ?? sliceId)
+    : milestoneDir;
+  const fileName = isLegacy
+    ? `${sliceId}-${suffix}.md`
+    : planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), suffix);
+  return join(dir, fileName);
+}
+
+/**
+ * Build relative .gsd/ path to a slice file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relSliceFile(
+  basePath: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveSliceFile(basePath, milestoneId, sliceId, suffix)
+      ?? targetSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -1031,7 +1088,7 @@ export function relSliceFile(
  */
 export function relTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
-  taskId: string, suffix: string
+  taskId: string, suffix: string, milestoneTitle?: string
 ): string {
   const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
   const phaseDir = resolveMilestonePath(basePath, milestoneId);
@@ -1044,6 +1101,6 @@ export function relTaskFile(
   if (suffix === "PLAN") {
     return relSliceFile(basePath, milestoneId, sliceId, "PLAN");
   }
-  const relS = relSlicePath(basePath, milestoneId, sliceId);
+  const relS = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
   return `${relS}/${buildTaskFileName(taskId, suffix)}`;
 }

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

@@ -11,6 +11,7 @@ import type {
   HookStatusEntry,
   PostUnitGateBlock,
 } from "./types.js";
+import type { SidecarItem } from "./auto/session.js";
 import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
 // Re-export resolveHookArtifactPath so existing importers still work.
@@ -75,6 +76,37 @@ export function restoreHookState(basePath: string): void {
   getOrCreateRegistry().restoreState(basePath);
 }
 
+/**
+ * Reconcile a restored `activeHook` against the session's sidecar queue.
+ *
+ * The registry persists `activeHook` to disk but the pending hook *dispatch*
+ * lives only on the non-persisted `s.sidecarQueue`. After a pause/resume or
+ * crash-recovery, `restoreHookState` re-hydrates `activeHook` while the dispatch
+ * is gone, so the registry believes a hook is in-flight but nothing will ever
+ * complete it — and the next unrelated unit's close-out is falsely charged
+ * against the stale hook and blocked. Re-enqueue the missing dispatch so the
+ * hook actually runs, restoring the invariant that a persisted `activeHook`
+ * always has a live dispatch (#1246).
+ */
+export function reconcileRestoredHookDispatch(
+  basePath: string,
+  sidecarQueue: SidecarItem[],
+): void {
+  const dispatch = getOrCreateRegistry().getPendingHookDispatch(basePath);
+  if (!dispatch) return;
+  const alreadyQueued = sidecarQueue.some(
+    item => item.kind === "hook" && item.unitType === dispatch.unitType,
+  );
+  if (alreadyQueued) return;
+  sidecarQueue.push({
+    kind: "hook",
+    unitType: dispatch.unitType,
+    unitId: dispatch.unitId,
+    prompt: dispatch.prompt,
+    model: dispatch.model,
+  });
+}
+
 export function clearPersistedHookState(basePath: string): void {
   getOrCreateRegistry().clearPersistedState(basePath);
 }

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

@@ -23,7 +23,7 @@ import type {
   GSDModelPhaseKey,
   GSDThinkingConfig,
   ResolvedModelConfig,
-  AutoSupervisorConfig,
+  ResolvedAutoSupervisorConfig,
 } from "./preferences-types.js";
 import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { getUnitPhaseChain } from "./unit-registry.js";
@@ -86,6 +86,40 @@ function resolveWinningPhase(
   return undefined;
 }
 
+/**
+ * Normalize a single model field into a {@link ResolvedModelConfig}.
+ *
+ * Accepts either the legacy bare-string form or the extended object form
+ * (`{ model, provider?, fallbacks? }`). This is the shared normalization used
+ * for phase buckets so sibling single-model fields — `post_unit_hooks[].model`,
+ * `auto_supervisor.model`, and `reactive_execution.subagent_model` — honor
+ * `fallbacks[]` identically rather than accepting a bare string only (#1229).
+ *
+ * Returns undefined for an unset, blank, or model-less field.
+ */
+export function normalizeModelFieldConfig(
+  field: string | GSDPhaseModelConfig | undefined,
+): ResolvedModelConfig | undefined {
+  if (!field) return undefined;
+  if (typeof field === "string") {
+    return field.trim() ? { primary: field, fallbacks: [] } : undefined;
+  }
+  if (!field.model) return undefined;
+  // When provider is explicitly set, prepend it to the model ID so the
+  // resolution code in auto.ts can do an explicit provider match.
+  const primary = field.provider && !field.model.includes("/")
+    ? `${field.provider}/${field.model}`
+    : field.model;
+  // Carry the per-field `thinking` sub-field through so the dispatch site can
+  // prefer it over the session/floor level, mirroring phase-inline thinking
+  // (#1269). `undefined` is preserved as absent so behavior is unchanged.
+  return {
+    primary,
+    fallbacks: field.fallbacks ?? [],
+    ...(field.thinking ? { thinking: field.thinking } : {}),
+  };
+}
+
 /**
  * Resolve model and fallbacks for a given auto-mode unit type.
  * Returns the primary model and ordered fallbacks, or undefined if not configured.
@@ -93,6 +127,15 @@ function resolveWinningPhase(
  * Supports both legacy string format and extended object format:
  * - Legacy: `planning: claude-opus-4-6`
  * - Extended: `planning: { model: claude-opus-4-6, fallbacks: [glm-5, minimax-m2.5] }`
+ *
+ * Hook unit types (`hook/<name>`) resolve against the matching
+ * `post_unit_hooks[]` entry's `model` field so hook sessions honor the same
+ * `fallbacks[]` chain as phase buckets — the recovery path can then switch to
+ * a fallback provider instead of hard-failing (and potentially pausing) the
+ * run on a transient provider trip (#1229).
+ *
+ * The synthetic `supervisor` unit type resolves against `auto_supervisor.model`
+ * for supervisor interventions (wrap-up warnings, timeout recovery).
  */
 export function resolveModelWithFallbacksForUnit(
   unitType: string,
@@ -107,27 +150,26 @@ export function resolveModelWithFallbacksForUnit(
     ...(skipProfileDefaults ? { skipProfileDefaults: true } : {}),
   };
   const prefs = loadEffectiveGSDPreferences(basePath, loadOpts);
-  const chain = phaseChainForUnit(unitType);
-  if (!chain) return undefined;
-  const winner = resolveWinningPhase(prefs?.preferences?.models as GSDModelConfigV2 | undefined, chain);
-  if (!winner) return undefined;
-  const phaseConfig = winner.config;
 
-  // Normalize: string -> { model, fallbacks: [] }
-  if (typeof phaseConfig === "string") {
-    return { primary: phaseConfig, fallbacks: [] };
+  // Supervisor interventions resolve against `auto_supervisor.model` (#1229).
+  if (unitType === "supervisor") {
+    return normalizeModelFieldConfig(prefs?.preferences?.auto_supervisor?.model);
   }
 
-  // When provider is explicitly set, prepend it to the model ID so the
-  // resolution code in auto.ts can do an explicit provider match.
-  const primary = phaseConfig.provider && !phaseConfig.model.includes("/")
-    ? `${phaseConfig.provider}/${phaseConfig.model}`
-    : phaseConfig.model;
+  // Hook sessions resolve against their own `post_unit_hooks[].model` field,
+  // which now shares the phase-bucket object form (#1229).
+  if (unitType.startsWith("hook/")) {
+    const hookName = unitType.slice("hook/".length);
+    const hooks = prefs?.preferences?.post_unit_hooks;
+    const hook = Array.isArray(hooks) ? hooks.find((h) => h.name === hookName) : undefined;
+    return normalizeModelFieldConfig(hook?.model);
+  }
 
-  return {
-    primary,
-    fallbacks: phaseConfig.fallbacks ?? [],
-  };
+  const chain = phaseChainForUnit(unitType);
+  if (!chain) return undefined;
+  const winner = resolveWinningPhase(prefs?.preferences?.models as GSDModelConfigV2 | undefined, chain);
+  if (!winner) return undefined;
+  return normalizeModelFieldConfig(winner.config);
 }
 
 /**
@@ -157,6 +199,14 @@ export function resolveThinkingLevelForUnit(
   basePath?: string,
   availableModelIds?: string[],
 ): GSDThinkingLevel | undefined {
+  // Single-field configs — `auto_supervisor.model` and `post_unit_hooks[].model`
+  // — carry their own inline `thinking` on the object model form and have no
+  // phase-bucket chain, so the walk below never covers them. Resolve their
+  // per-field level directly (#1269).
+  if (unitType === "supervisor" || unitType.startsWith("hook/")) {
+    return resolveModelWithFallbacksForUnit(unitType, basePath, availableModelIds)?.thinking;
+  }
+
   const loadOpts = availableModelIds !== undefined ? { availableModelIds } : undefined;
   const prefs = loadEffectiveGSDPreferences(basePath, loadOpts)?.preferences;
   if (!prefs) return undefined;
@@ -425,16 +475,20 @@ export function resolveDynamicRoutingConfig(): DynamicRoutingConfig {
   };
 }
 
-export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
+export function resolveAutoSupervisorConfig(): ResolvedAutoSupervisorConfig {
   const prefs = loadEffectiveGSDPreferences();
   const configured = prefs?.preferences.auto_supervisor ?? {};
 
+  const modelConfig = normalizeModelFieldConfig(configured.model);
+
   return {
     soft_timeout_minutes: configured.soft_timeout_minutes ?? 20,
     idle_timeout_minutes: configured.idle_timeout_minutes ?? 10,
     hard_timeout_minutes: configured.hard_timeout_minutes ?? 30,
     stalled_tool_timeout_minutes: configured.stalled_tool_timeout_minutes ?? 5,
-    ...(configured.model ? { model: configured.model } : {}),
+    ...(modelConfig
+      ? { model: modelConfig.primary, modelFallbacks: modelConfig.fallbacks }
+      : {}),
   };
 }
 

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

@@ -5,11 +5,11 @@
  * to absolute filesystem paths, plus skill discovery and staleness config.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { getSkillDirectories } from "@gsd/pi-coding-agent";
 import { gsdHome } from "./gsd-home.js";
-import { statSync } from "node:fs";
 
 import type {
   GSDPreferences,
@@ -25,26 +25,20 @@ export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolution
 /**
  * Known skill directories for **preference reference resolution** (bare skill names).
  *
- * Search order (first match wins):
- * 1. ~/.gsd/agent/skills/ (GSD bundled)
- * 2. ~/.agents/skills/ (ecosystem global)
- * 3. .agents/skills/ (project ecosystem)
- * 4. ~/.claude/skills/ and .claude/skills/ (Claude Code compatibility)
+ * Sourced from the shared taxonomy (`@gsd/pi-coding-agent` `getSkillDirectories`)
+ * so preference resolution, mid-session discovery, and the PackageManager
+ * catalog all agree on which directories exist. The `method` is derived from
+ * each entry's scope.
  *
  * Note: the ResourceLoader catalog uses PackageManager precedence instead —
  * project `.gsd/skills` and `.agents/skills` can override bundled GSD skills
  * on name collision. See docs/dev/what-is-pi/09-the-customization-stack.md.
  */
 export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> {
-  const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [
-    { dir: join(gsdHome(), "agent", "skills"), method: "user-skill" },
-    { dir: join(homedir(), ".agents", "skills"), method: "user-skill" },
-    { dir: join(cwd, ".agents", "skills"), method: "project-skill" },
-    // Claude Code official skill directories
-    { dir: join(homedir(), ".claude", "skills"), method: "user-skill" },
-    { dir: join(cwd, ".claude", "skills"), method: "project-skill" },
-  ];
-  return dirs;
+  return getSkillDirectories({ cwd, gsdHome: gsdHome() }).map((entry) => ({
+    dir: entry.path,
+    method: entry.scope === "project" ? "project-skill" : "user-skill",
+  }));
 }
 
 /**

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

@@ -312,12 +312,24 @@ export interface GSDModelConfigV2 {
 export interface ResolvedModelConfig {
   primary: string;
   fallbacks: string[];
+  /**
+   * Per-field reasoning level carried from the object model form's `thinking`
+   * sub-field (e.g. `{ model, thinking: high }` on `post_unit_hooks[].model`,
+   * `auto_supervisor.model`, or `reactive_execution.subagent_model`). Applied at
+   * the dispatch site in preference to the session/floor level (#1269).
+   */
+  thinking?: GSDThinkingLevel;
 }
 
 export type SkillDiscoveryMode = "auto" | "suggest" | "off";
 
 export interface AutoSupervisorConfig {
-  model?: string;
+  /**
+   * Model ID for the supervisor process. Accepts a bare model ID or the
+   * extended `{ model, provider?, fallbacks? }` object form for parity with
+   * phase buckets (#1229). Resolution normalizes it to the primary model ID.
+   */
+  model?: string | GSDPhaseModelConfig;
   soft_timeout_minutes?: number;
   idle_timeout_minutes?: number;
   hard_timeout_minutes?: number;
@@ -331,6 +343,17 @@ export interface AutoSupervisorConfig {
   stalled_tool_timeout_minutes?: number;
 }
 
+/**
+ * The supervisor config after resolution by `resolveAutoSupervisorConfig`.
+ * Identical to {@link AutoSupervisorConfig} except `model` is always the
+ * normalized primary model ID string and `modelFallbacks` carries the ordered
+ * fallback chain from the object form accepted in preferences (#1229).
+ */
+export type ResolvedAutoSupervisorConfig = Omit<AutoSupervisorConfig, "model"> & {
+  model?: string;
+  modelFallbacks?: string[];
+};
+
 export interface RemoteQuestionsConfig {
   channel: "slack" | "discord" | "telegram";
   channel_id: string | number;

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

@@ -22,6 +22,7 @@ import {
   SKILL_ACTIONS,
   type WorkflowMode,
   type GSDPreferences,
+  type GSDPhaseModelConfig,
   type GSDSkillRule,
   type GSDThinkingLevel,
 } from "./preferences-types.js";
@@ -41,6 +42,62 @@ const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
   "snapshot",
   "status-only",
 ]);
+/**
+ * Sanitize a single model field that accepts either a bare model ID or the
+ * extended `{ model, provider?, fallbacks? }` object form used by phase buckets
+ * (#1229). Returns the sanitized value, or undefined when unset/invalid (in
+ * which case an error describing `label` is pushed onto `errors`).
+ */
+function sanitizeModelField(
+  raw: unknown,
+  label: string,
+  errors: string[],
+  warnings?: string[],
+): string | GSDPhaseModelConfig | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      errors.push(`${label} must not be an empty string`);
+      return undefined;
+    }
+    return trimmed;
+  }
+  if (raw && typeof raw === "object") {
+    const obj = raw as Record<string, unknown>;
+    const model = typeof obj.model === "string" ? obj.model.trim() : "";
+    if (!model) {
+      errors.push(`${label} object form requires a non-empty "model"`);
+      return undefined;
+    }
+    const sanitized: GSDPhaseModelConfig = { model };
+    if (typeof obj.provider === "string" && obj.provider.trim()) {
+      sanitized.provider = obj.provider.trim();
+    }
+    if (obj.fallbacks !== undefined) {
+      const fallbacks = normalizeStringArray(obj.fallbacks);
+      if (fallbacks.length > 0) sanitized.fallbacks = fallbacks;
+    }
+    // Preserve the object form's `thinking` sub-field so the dispatch site can
+    // pin the hook/supervisor/subagent reasoning level (#1269). An illegal level
+    // is warned-and-stripped, mirroring inline per-phase thinking, so a typo can't
+    // reach the resolver and be treated as explicit configuration.
+    if (obj.thinking !== undefined) {
+      if (VALID_THINKING_LEVELS.has(obj.thinking as GSDThinkingLevel)) {
+        sanitized.thinking = obj.thinking as GSDThinkingLevel;
+      } else {
+        warnings?.push(
+          `${label} thinking "${String(obj.thinking)}" is not a valid thinking level ` +
+          `(off, minimal, low, medium, high, xhigh) — ignored`,
+        );
+      }
+    }
+    return sanitized;
+  }
+  errors.push(`${label} must be a string or an object with a "model" field`);
+  return undefined;
+}
+
 const VALID_POST_UNIT_HOOK_CRITICALITIES = new Set(["advisory", "blocking"]);
 const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
   "retry-unit",
@@ -476,7 +533,15 @@ export function validatePreferences(preferences: GSDPreferences): {
   // ─── Auto Supervisor ────────────────────────────────────────────────
   if (preferences.auto_supervisor !== undefined) {
     if (preferences.auto_supervisor && typeof preferences.auto_supervisor === "object") {
-      validated.auto_supervisor = preferences.auto_supervisor;
+      // Validate `model` through the shared sanitizer so the
+      // `{ model, provider?, fallbacks? }` object form is rejected on the same
+      // terms as its post_unit_hooks / reactive_execution siblings (#1229).
+      // Other supervisor fields pass through unchanged.
+      const supervisor = { ...preferences.auto_supervisor };
+      if (supervisor.model !== undefined) {
+        supervisor.model = sanitizeModelField(supervisor.model, "auto_supervisor.model", errors, warnings);
+      }
+      validated.auto_supervisor = supervisor;
     } else {
       errors.push("auto_supervisor must be an object");
     }
@@ -568,8 +633,9 @@ export function validatePreferences(preferences: GSDPreferences): {
         const mc = typeof hook.max_cycles === "number" ? hook.max_cycles : Number(hook.max_cycles);
         validHook.max_cycles = Number.isFinite(mc) ? Math.max(1, Math.min(10, Math.round(mc))) : 1;
       }
-      if (typeof hook.model === "string" && hook.model.trim()) {
-        validHook.model = hook.model.trim();
+      const hookModel = sanitizeModelField(hook.model, `post_unit_hooks "${name}" model`, errors, warnings);
+      if (hookModel !== undefined) {
+        validHook.model = hookModel;
       }
       if (typeof hook.artifact === "string" && hook.artifact.trim()) {
         validHook.artifact = hook.artifact.trim();
@@ -1021,12 +1087,14 @@ export function validatePreferences(preferences: GSDPreferences): {
         }
       }
 
-      if (re.subagent_model !== undefined) {
-        if (typeof re.subagent_model === "string" && re.subagent_model.length > 0) {
-          validRe.subagent_model = re.subagent_model;
-        } else {
-          errors.push("reactive_execution.subagent_model must be a non-empty string");
-        }
+      const subagentModel = sanitizeModelField(
+        re.subagent_model,
+        "reactive_execution.subagent_model",
+        errors,
+        warnings,
+      );
+      if (subagentModel !== undefined) {
+        validRe.subagent_model = subagentModel;
       }
 
       const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode", "subagent_model"]);