@opengsd/gsd-pi 1.5.0-dev.4fb2d460 → 1.5.0-dev.c4c8885f

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-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"]);

package/src/resources/extensions/gsd/rule-registry.ts

@@ -22,8 +22,9 @@ import type {
 } from "./types.js";
 import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { parseUnitId } from "./unit-id.js";
+import { resolveMilestonePath } from "./paths.js";
 import { queryJournal, type JournalEntry } from "./journal.js";
 import { readUnitRuntimeRecord, type UnitRuntimePhase } from "./unit-runtime.js";
 import { extractFrontmatterVerdict } from "./verdict-parser.js";
@@ -32,13 +33,45 @@ import { extractFrontmatterVerdict } from "./verdict-parser.js";
 
 export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
   const { milestone, slice, task } = parseUnitId(unitId);
-  if (task !== undefined && slice !== undefined) {
-    return join(basePath, ".gsd", "milestones", milestone, "slices", slice, "tasks", `${task}-${artifactName}`);
+
+  // Prefer the active phase directory (flat-phase layout: .gsd/phases/<NN>-.../).
+  // Configured gate artifacts are canonical phase-level files (e.g.
+  // BROWSER-RUNTIME-EVIDENCE.md), so resolve the exact declared name first,
+  // then a task-prefixed variant for retry sentinels / rework briefs.
+  const candidates: string[] = [];
+  const phaseDir = resolveMilestonePath(basePath, milestone);
+  const isFlatPhaseDir = phaseDir !== null
+    && !(dirname(phaseDir).endsWith("/milestones") || dirname(phaseDir).endsWith("\\milestones"));
+  if (isFlatPhaseDir) {
+    candidates.push(join(phaseDir, artifactName));
+    if (task !== undefined) {
+      candidates.push(join(phaseDir, `${task}-${artifactName}`));
+    }
   }
-  if (slice !== undefined) {
-    return join(basePath, ".gsd", "milestones", milestone, "slices", slice, artifactName);
+
+  // Legacy nested layout fallbacks (.gsd/milestones/<M>/slices/<S>/tasks/...).
+  const legacyBase = join(basePath, ".gsd", "milestones", milestone);
+  let legacyDefault: string;
+  if (task !== undefined && slice !== undefined) {
+    legacyDefault = join(legacyBase, "slices", slice, "tasks", `${task}-${artifactName}`);
+    candidates.push(legacyDefault);
+    candidates.push(join(legacyBase, "slices", slice, "tasks", artifactName));
+    candidates.push(join(legacyBase, "slices", slice, artifactName));
+  } else if (slice !== undefined) {
+    legacyDefault = join(legacyBase, "slices", slice, artifactName);
+    candidates.push(legacyDefault);
+  } else {
+    legacyDefault = join(legacyBase, artifactName);
   }
-  return join(basePath, ".gsd", "milestones", milestone, artifactName);
+  candidates.push(join(legacyBase, artifactName));
+
+  const existing = candidates.find((candidate) => existsSync(candidate));
+  if (existing) return existing;
+
+  // Nothing on disk yet: prefer the active phase path when the phase dir is
+  // known, otherwise fall back to the legacy default (preserves pre-flat-phase
+  // behavior for missing-artifact diagnostics).
+  return isFlatPhaseDir ? join(phaseDir!, artifactName) : legacyDefault;
 }
 
 // ─── Dispatch Rule Conversion ──────────────────────────────────────────────
@@ -126,6 +159,13 @@ export class RuleRegistry {
     forceRun?: boolean;
   }> = [];
   cycleCounts: Map<string, number> = new Map();
+  /**
+   * Cycle keys that have already been granted a one-shot re-dispatch after a
+   * lost/interrupted dispatch (hook charged a cycle but never produced its own
+   * unit-end). Bounds the dispatch-cycle refund to exactly one per gate so a
+   * hook that repeatedly fails to complete cannot loop forever.
+   */
+  redispatchedGateKeys: Set<string> = new Set();
   retryPending: boolean = false;
   retryTrigger: { unitType: string; unitId: string; retryArtifact?: string } | null = null;
   hookFailure: HookFailureState | null = null;
@@ -364,6 +404,14 @@ export class RuleRegistry {
       pendingRetry: false,
     };
 
+    return this._buildHookDispatch(config, triggerUnitId);
+  }
+
+  /** Construct the sidecar dispatch for a hook without mutating registry state. */
+  private _buildHookDispatch(
+    config: PostUnitHookConfig,
+    triggerUnitId: string,
+  ): HookDispatchResult {
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
     let prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
@@ -375,12 +423,29 @@ export class RuleRegistry {
     return {
       hookName: config.name,
       prompt,
-      model: config.model,
+      // Model selection (including fallbacks[]) is handled by
+      // resolveModelWithFallbacksForUnit for the `hook/<name>` unit type (#1229).
       unitType: `hook/${config.name}`,
       unitId: triggerUnitId,
     };
   }
 
+  /**
+   * Reconstruct the in-flight hook's dispatch from the restored `activeHook`
+   * state, without mutating the registry. Used to reconcile a persisted
+   * `activeHook` whose session-local dispatch was lost across a pause/resume
+   * or crash-recovery, so the hook actually runs instead of being charged
+   * against the next unrelated unit's close-out (#1246).
+   */
+  getPendingHookDispatch(basePath: string): HookDispatchResult | null {
+    if (!this.activeHook) return null;
+    const config = resolvePostUnitHooks(basePath).find(
+      h => h.name === this.activeHook!.hookName,
+    );
+    if (!config) return null;
+    return this._buildHookDispatch(config, this.activeHook.triggerUnitId);
+  }
+
   private _assessHookCompletion(
     basePath: string,
     hook: HookExecutionState,
@@ -503,6 +568,30 @@ export class RuleRegistry {
     observedCleanExecution: boolean,
   ): HookDispatchResult | null {
     if (!observedCleanExecution) {
+      // The hook was charged a cycle at dispatch but never produced its own
+      // unit-end — its dispatch was lost/interrupted (pause/resume, crash
+      // recovery). Refund that dispatch-consumed cycle exactly once so the gate
+      // is re-dispatched at least once instead of hard-blocking on a hook that
+      // never actually ran.
+      //
+      // This refund is intentionally UNCONDITIONAL on the first lost dispatch —
+      // it must NOT be gated on `currentCycle >= max_cycles`. A lost dispatch is
+      // a non-run: charging its cycle at dispatch time must not consume the
+      // hook's real-run budget. Gating the refund on "budget already exhausted"
+      // lets a lost dispatch below max_cycles silently eat a genuine cycle, so
+      // the hook gets one fewer real run than configured — reintroducing #1244
+      // for max_cycles >= 2 (see the "does not steal a real-run cycle" test).
+      // The redispatchedGateKeys flag bounds this to a single refund per gate,
+      // so repeated lost dispatches still terminate (total dispatches never
+      // exceed max_cycles + 1) and a hook that keeps failing blocks normally.
+      const cycleKey = hookCycleKey(config, hook);
+      if (!this.redispatchedGateKeys.has(cycleKey)) {
+        this.redispatchedGateKeys.add(cycleKey);
+        const currentCycle = this.cycleCounts.get(cycleKey);
+        if (typeof currentCycle === "number" && currentCycle > 0) {
+          this.cycleCounts.set(cycleKey, currentCycle - 1);
+        }
+      }
       return this._rerunGateOrBlock(config, hook, basePath, {
         reason: `hook/${config.name} did not complete cleanly before the trigger unit resumed`,
       });
@@ -839,6 +928,7 @@ export class RuleRegistry {
     this.activeHook = null;
     this.hookQueue = [];
     this.cycleCounts.clear();
+    this.redispatchedGateKeys.clear();
     this.retryPending = false;
     this.retryTrigger = null;
     this.hookFailure = null;
@@ -855,6 +945,7 @@ export class RuleRegistry {
   persistState(basePath: string): void {
     const state: PersistedHookState = {
       cycleCounts: Object.fromEntries(this.cycleCounts),
+      redispatchedGateKeys: Array.from(this.redispatchedGateKeys),
       activeHook: this.activeHook ? { ...this.activeHook } : null,
       hookQueue: this.hookQueue.map(entry => ({
         hookName: entry.config.name,
@@ -888,6 +979,14 @@ export class RuleRegistry {
           }
         }
       }
+      this.redispatchedGateKeys.clear();
+      if (Array.isArray(state.redispatchedGateKeys)) {
+        for (const key of state.redispatchedGateKeys) {
+          if (typeof key === "string") {
+            this.redispatchedGateKeys.add(key);
+          }
+        }
+      }
       this.activeHook = state.activeHook && typeof state.activeHook === "object"
         ? { ...state.activeHook }
         : null;
@@ -918,7 +1017,7 @@ export class RuleRegistry {
       if (existsSync(filePath)) {
         writeFileSync(
           filePath,
-          JSON.stringify({ cycleCounts: {}, activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2),
+          JSON.stringify({ cycleCounts: {}, redispatchedGateKeys: [], activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2),
           "utf-8",
         );
       }
@@ -1014,7 +1113,10 @@ export class RuleRegistry {
     return {
       hookName: hook.name,
       prompt,
-      model: hook.model,
+      // Model selection (including fallbacks[]) is resolved by dispatchHookUnit
+      // via resolveModelWithFallbacksForUnit for the `hook/<name>` unit type,
+      // matching the auto-mode path. Emitting the primary-only model here would
+      // discard the configured fallback chain (#1229).
       unitType: `hook/${hook.name}`,
       unitId,
     };

package/src/resources/extensions/gsd/state-reconciliation/drift/artifact-db.ts

@@ -213,21 +213,13 @@ function detectArtifactDbStatusDriftForMilestone(
 
     for (const task of tasks) {
       if (isClosedStatus(task.status)) continue;
-      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-      let diskTaskSummary = resolveTaskFile(
+      const diskTaskSummary = resolveTaskFile(
         basePath,
         milestoneId,
         slice.id,
         task.id,
         "SUMMARY",
       );
-      if (!diskTaskSummary) {
-        const phaseDir = resolveMilestonePath(basePath, milestoneId);
-        if (phaseDir) {
-          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-          if (existsSync(flatSummary)) diskTaskSummary = flatSummary;
-        }
-      }
       if (!diskTaskSummary || !existsSync(diskTaskSummary)) continue;
       addUniqueDrift(drifts, seen, {
         kind: "artifact-db-status-divergence",

package/src/resources/extensions/gsd/state-reconciliation/drift/completion.ts

@@ -20,11 +20,9 @@ import {
 } from "../../gsd-db.js";
 import {
   resolveMilestoneFile,
-  resolveMilestonePath,
   resolveSliceFile,
   resolveTaskFile,
 } from "../../paths.js";
-import { join } from "node:path";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -105,23 +103,13 @@ function collectMilestoneCompletionDrift(
     for (const task of getSliceTasks(mid, slice.id)) {
       if (!COMPLETE_STATUSES.has(task.status)) continue;
       if (task.completed_at !== null) continue;
-      // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md.
-      // Legacy: resolveTaskFile returns the tasks/TID/TID-SUMMARY.md path.
-      let taskSummary = resolveTaskFile(
+      const taskSummary = resolveTaskFile(
         ctx.basePath,
         mid,
         slice.id,
         task.id,
         "SUMMARY",
       );
-      // Flat-phase fallback: check the phase dir directly
-      if (!taskSummary) {
-        const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-        if (phaseDir) {
-          const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-          if (existsSync(flatSummary)) taskSummary = flatSummary;
-        }
-      }
       if (taskSummary && existsSync(taskSummary)) {
         drifts.push({
           kind: "missing-completion-timestamp",
@@ -182,15 +170,7 @@ export function repairMissingCompletionTimestamp(
       task.completed_at !== null ||
       !COMPLETE_STATUSES.has(task.status)
     ) return;
-    // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-    let summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
-    if (!summary) {
-      const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-      if (phaseDir) {
-        const flatSummary = join(phaseDir, `${tid}-SUMMARY.md`);
-        if (existsSync(flatSummary)) summary = flatSummary;
-      }
-    }
+    const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
     const ts = summary ? summaryMtimeIso(summary) : null;
     if (!ts) return;
     updateTaskStatus(mid, sid, tid, task.status, ts);

package/src/resources/extensions/gsd/state-reconciliation/index.ts

@@ -73,6 +73,20 @@ export async function reconcileBeforeDispatch(
   if (!deps.dryRun) {
     const { capturePlanningCompatIfNeeded } = await import("../compat/planning-compat.js");
     await capturePlanningCompatIfNeeded(basePath);
+
+    // Self-heal phantom projection entries (#1257): a renamed/removed phase
+    // directory leaves stale `.compat.json` projection paths that no detector
+    // ever prunes (they all skip missing files), so the marker drifts from disk
+    // reality permanently. Drop entries whose backing file is gone before the
+    // detect passes run. Gated on !dryRun to keep detection read-only.
+    const { pruneOrphanedProjectionEntries } = await import("../compat/compat-marker.js");
+    const prunedCount = pruneOrphanedProjectionEntries(basePath);
+    if (prunedCount > 0) {
+      logWarning(
+        "reconcile",
+        `pruned ${prunedCount} orphaned projection entr${prunedCount === 1 ? "y" : "ies"} from .compat.json (backing file no longer on disk)`,
+      );
+    }
   }
 
   for (let pass = 0; pass < MAX_PASSES; pass++) {

package/src/resources/extensions/gsd/tests/auto-orchestrator.test.ts

@@ -797,9 +797,11 @@ test("stuck-loop: empty ring on a freshly constructed orchestrator advances norm
   assert.equal(result.kind, "advanced");
 });
 
-test("stuck-loop: partial fill of mixed units does not block", async (t) => {
+test("stuck-loop: distinct units making forward progress do not block", async (t) => {
+  // Healthy forward progress visits new units every advance — no key repeats,
+  // so no oscillation/repeat rule fires even once the window is full.
   let i = 0;
-  const sequence = ["M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B", "M001/S01/A", "M001/S01/B"];
+  const sequence = ["M001/S01/A", "M001/S01/B", "M001/S01/C", "M001/S01/D", "M001/S01/E", "M001/S01/F"];
   const f = makeFixture({
     dispatch: () => ({ action: "dispatch", unitType: "execute-task", unitId: sequence[i++ % sequence.length], prompt: "p" }),
   });
@@ -811,6 +813,43 @@ test("stuck-loop: partial fill of mixed units does not block", async (t) => {
   }
 });
 
+test("stuck-loop #1225: two-unit oscillation blocks once the window saturates", async (t) => {
+  // Reproduces the execute-task ↔ complete-slice loop: a slice gate keeps
+  // reopening the same task, so two keys alternate forever. Neither key ever
+  // saturates the window on its own, so the old matchingCount>=SIZE gate never
+  // consulted detect-stuck and the loop ran until an external kill. The window
+  // still fills, so detect-stuck's oscillation/repeat rules must now fire.
+  let i = 0;
+  const sequence: Array<{ unitType: string; unitId: string }> = [
+    { unitType: "execute-task", unitId: "M001/S01/T01" },
+    { unitType: "complete-slice", unitId: "M001/S01" },
+  ];
+  const f = makeFixture({
+    dispatch: () => {
+      const next = sequence[i++ % sequence.length];
+      return { action: "dispatch", unitType: next.unitType, unitId: next.unitId, prompt: "p" };
+    },
+  });
+  t.after(() => f.cleanup());
+
+  let blocked: Awaited<ReturnType<typeof f.orchestrator.advance>> | undefined;
+  for (let round = 0; round < STUCK_WINDOW_SIZE; round++) {
+    const result = await f.orchestrator.advance();
+    if (result.kind === "blocked") {
+      blocked = result;
+      break;
+    }
+  }
+
+  assert.ok(blocked, "oscillation must be detected once the window saturates");
+  if (!blocked || blocked.kind !== "blocked") return;
+  assert.equal(blocked.action, "stop");
+  assert.ok(
+    blocked.reason.startsWith("stuck-loop:"),
+    `expected stuck-loop verdict, got: ${blocked.reason}`,
+  );
+});
+
 test("stuck-loop: ring saturated with same unit blocks with action 'stop' and stuck-loop reason", async (t) => {
   const f = makeFixture();
   t.after(() => f.cleanup());