@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/auto/loop-deps.ts

@@ -52,6 +52,7 @@ export type PauseAutoUnitIdentity = {
 
 export interface PauseAutoOptions {
   expectedCurrentUnit?: PauseAutoUnitIdentity | null;
+  abortActiveTurn?: boolean;
 }
 
 type PauseAutoFn = (
@@ -79,6 +80,7 @@ export interface LoopDeps {
   ) => Promise<void>;
   pauseAuto: PauseAutoFn;
   clearUnitTimeout: () => void;
+  checkpointWorkflowDatabase?: () => void;
   updateProgressWidget: (
     ctx: ExtensionContext,
     unitType: string,

package/src/resources/extensions/gsd/auto/loop.ts

@@ -175,6 +175,7 @@ function resolveCompletionStopFromOutcome(
 // tolerates — same behavior as a fresh session.
 const STUCK_RECOVERY_ATTEMPTS_KEY = "stuck_recovery_attempts";
 const MAX_CONSECUTIVE_ALREADY_ACTIVE_SKIPS = 3;
+const MAX_CONSECUTIVE_ORCHESTRATION_SKIPS = 3;
 const ORCHESTRATION_MISSING_REASON =
   "Auto Orchestration Module is not wired; cannot dispatch built-in GSD Unit.";
 
@@ -186,7 +187,20 @@ function loadStuckState(s: AutoSession): { recentUnits: Array<{ key: string }>;
   const scopeId = stableStuckStateScopeId(s);
   if (!scopeId) return { recentUnits: [], stuckRecoveryAttempts: 0 };
   try {
-    const recentUnits = getRecentUnitKeysForProjectRoot(scopeId, STUCK_WINDOW_SIZE);
+    // Scope the stuck window to the CURRENT session (trace_id) so stale
+    // finalize-retry entries from previous sessions don't fire detectStuck
+    // Rule 1 on the first iteration — killing auto-mode before any new
+    // dispatch runs (#852). A prior session's two consecutive finalize-retry
+    // failures would otherwise permanently block every new session.
+    //
+    // s.currentTraceId is only set inside the first loop iteration (line ~443),
+    // so at this call-site it is always null for a fresh session. Return []
+    // directly in that case — no prior dispatch has occurred in this session,
+    // so the stuck window is trivially empty and the DB query is skipped.
+    const recentUnits =
+      s.currentTraceId != null
+        ? getRecentUnitKeysForProjectRoot(scopeId, STUCK_WINDOW_SIZE, s.currentTraceId)
+        : [];
     const stuckRecoveryAttempts =
       getRuntimeKv<number>("global", scopeId, STUCK_RECOVERY_ATTEMPTS_KEY) ?? 0;
     return { recentUnits, stuckRecoveryAttempts };
@@ -406,6 +420,8 @@ export async function autoLoop(
   let consecutiveErrors = 0;
   let consecutiveCooldowns = 0;
   let consecutiveAlreadyActiveSkips = 0;
+  let consecutiveOrchestrationSkips = 0;
+  let lastOrchestrationSkipKey: string | null = null;
   const recentErrorMessages: string[] = [];
 
   while (s.active) {
@@ -925,12 +941,53 @@ export async function autoLoop(
 
           if (orchestrationResult.kind === "skipped") {
             s.pendingOrchestrationDispatch = null;
+            // Idempotent re-poll skips are benign (an active unit is still running).
+            // The orchestrator's own stuck-window detection handles the truly-stuck case.
+            // Do not count these toward the consecutive-skip streak.
+            if (orchestrationResult.reason === "idempotent advance: unit already active") {
+              emitIterationEnd({ skipped: true });
+              completeIteration();
+              finishTurn("skipped");
+              continue;
+            }
+            const skipState = orchestrationResult.stateSnapshot;
+            const skipKey = [
+              orchestrationResult.reason,
+              skipState?.phase,
+              skipState?.activeMilestone?.id,
+              skipState?.activeSlice?.id,
+              skipState?.activeTask?.id,
+            ].join("|");
+            consecutiveOrchestrationSkips = skipKey === lastOrchestrationSkipKey
+              ? consecutiveOrchestrationSkips + 1
+              : 1;
+            lastOrchestrationSkipKey = skipKey;
+            if (consecutiveOrchestrationSkips >= MAX_CONSECUTIVE_ORCHESTRATION_SKIPS) {
+              const msg = `Orchestration skipped ${consecutiveOrchestrationSkips} consecutive attempts without progress. Pausing auto-mode for manual recovery.`;
+              ctx.ui.notify(msg, "error");
+              await deps.pauseAuto(ctx, pi, {
+                message: msg,
+                category: "unknown",
+              }, {
+                expectedCurrentUnit: null,
+              });
+              finishTurn("paused", "manual-attention", orchestrationResult.reason ?? "orchestration-skipped");
+              finishIncompleteIteration({
+                status: "paused",
+                reason: orchestrationResult.reason ?? "orchestration-skipped",
+                failureClass: "manual-attention",
+              });
+              break;
+            }
             emitIterationEnd({ skipped: true });
             completeIteration();
             finishTurn("skipped");
             continue;
           }
 
+          consecutiveOrchestrationSkips = 0;
+          lastOrchestrationSkipKey = null;
+
           if (orchestrationResult.kind === "paused") {
             s.pendingOrchestrationDispatch = null;
             finishIncompleteIteration({
@@ -1331,7 +1388,17 @@ export async function autoLoop(
         finalizeResult.action === "break"
           ? { action: "break", reason: finalizeResult.reason }
           : finalizeResult.action === "continue"
-            ? { action: "continue" }
+            ? {
+                action: "continue",
+                // Surface the specific verification failure (e.g. "roadmap has
+                // zero slices") in the ledger/stuck-loop reason instead of the
+                // opaque bare "finalize-retry" token. The retry paths in
+                // runFinalize set s.pendingVerificationRetry.failureContext
+                // from describeArtifactVerificationFailure before returning
+                // continue; it is cleared on the next dispatch, so reading it
+                // here captures the reason for THIS finalize (#852 follow-up).
+                failureDetail: s.pendingVerificationRetry?.failureContext,
+              }
             : { action: "next" },
       );
       if (finalizeDecision.action === "stop") {

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -76,6 +76,8 @@ import { join } from "node:path";
 import { evaluateAllCompleteSettlement } from "../milestone-settlement.js";
 import { hasHeldMilestoneLease, reclaimMissingMilestoneLease } from "./milestone-lease-reclaim.js";
 
+type UokFlags = ReturnType<typeof resolveUokFlags>;
+
 function now(): number {
   return Date.now();
 }
@@ -211,6 +213,9 @@ export async function decideOrchestratorDispatch(
     ctx.modelRegistry,
     activeDispatchBasePath,
     resolveProfileAnchorProvider(ctx.model?.provider, session?.autoModeStartModel?.provider),
+    activeSession?.autoModeStartModel
+      ? `${activeSession.autoModeStartModel.provider}/${activeSession.autoModeStartModel.id}`
+      : undefined,
   )?.preferences;
   if (!active) {
     if (state.phase !== "pre-planning") return null;
@@ -514,6 +519,19 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
   // ── UokGateAdapter (folded) ──────────────────────────────────────────────
 
+  private resolveUokGateContext(): { activeBasePath: string; uokFlags: UokFlags } {
+    const activeBasePath = this.getLiveDispatchBasePath();
+    const prefs = loadEffectiveGSDPreferencesWithRegistry(
+      this.ctx.modelRegistry,
+      activeBasePath,
+      resolveProfileAnchorProvider(this.ctx.model?.provider, this.s.autoModeStartModel?.provider),
+      this.s.autoModeStartModel
+        ? `${this.s.autoModeStartModel.provider}/${this.s.autoModeStartModel.id}`
+        : undefined,
+    )?.preferences;
+    return { activeBasePath, uokFlags: resolveUokFlags(prefs) };
+  }
+
   private async emitUokGate(input: {
     gateId: string;
     gateType: "policy" | "execution";
@@ -522,15 +540,11 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     rationale: string;
     findings?: string;
     milestoneId?: string;
+    activeBasePath: string;
+    uokFlags: UokFlags;
   }): Promise<void> {
-    const activeBasePath = this.getLiveDispatchBasePath();
-    const prefs = loadEffectiveGSDPreferencesWithRegistry(
-      this.ctx.modelRegistry,
-      activeBasePath,
-      resolveProfileAnchorProvider(this.ctx.model?.provider, this.s.autoModeStartModel?.provider),
-    )?.preferences;
-    const uokFlags = resolveUokFlags(prefs);
-    if (!uokFlags.gates) return;
+    if (!input.uokFlags.gates) return;
+    const activeBasePath = input.activeBasePath;
     const milestoneId = input.milestoneId ?? this.s.currentMilestoneId ?? undefined;
     try {
       const { UokGateRunner } = await import("../uok/gate-runner.js");
@@ -717,7 +731,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return new GitServiceImpl(basePath, gitConfig);
       },
       worktreeProjection: new WorktreeStateProjection(),
-      mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
+      mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
     });
   }
 
@@ -912,12 +926,17 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
-    // #482: the DB dispatch ledger is the source of truth across sessions.
-    // Discard any in-memory window and rebuild it from the ledger so a unit
-    // that was re-dispatched in previous sessions is detected as stuck here
-    // instead of silently re-dispatching forever.
+    // #852: a fresh user-triggered session must start with a clean stuck window.
+    // Cross-session rehydration at start() was removed because it caused false
+    // stuck-loop verdicts when prior sessions left consecutive finalize-retry
+    // entries in unit_dispatches — the new session would be killed before its
+    // first dispatch ran. Within-session stuck detection (accumulated through
+    // recordDispatch() calls during advance()) remains fully active and catches
+    // genuine stuck patterns after STUCK_WINDOW_SIZE dispatches.
+    //
+    // resume() retains cross-session rehydration: an interrupted session resuming
+    // after a crash should see the dispatch history it had been accumulating.
     this.dispatchHistory.clearOnRecovery();
-    this.dispatchHistory.rehydrate();
     this.lastStuckRecoveryKey = null;
     this.lastDerivedPhase = null;
     this.status.phase = "running";
@@ -932,10 +951,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     const stopAdvanceTimer = debugTime("orchestrator-advance");
     try {
       this.ensureLockOwnership();
+      const uokGateContext = this.resolveUokGateContext();
 
       const staleMsg = this.checkResourcesStale();
       if (staleMsg) {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "resource-version-guard",
           gateType: "policy",
           outcome: "fail",
@@ -949,6 +970,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
       await this.emitUokGate({
+        ...uokGateContext,
         gateId: "resource-version-guard",
         gateType: "policy",
         outcome: "pass",
@@ -959,6 +981,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       const gate = await this.preAdvanceGate();
       if (gate.kind === "fail") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -977,6 +1000,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       }
       if (gate.kind === "threw") {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "manual-attention",
@@ -987,6 +1011,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         // intentional fall-through: matches runPreDispatch behaviour
       } else {
         await this.emitUokGate({
+          ...uokGateContext,
           gateId: "pre-dispatch-health-gate",
           gateType: "execution",
           outcome: "pass",

package/src/resources/extensions/gsd/auto/run-unit.ts

@@ -26,7 +26,7 @@ import { debugLog } from "../debug-logger.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { resolveAutoSupervisorConfig } from "../preferences.js";
 import { readUnitRuntimeRecord, type AutoUnitRuntimeRecord } from "../unit-runtime.js";
-import { consumeAutoWakeup } from "./schedule-wakeup.js";
+import { clearAutoWakeup, consumeAutoWakeup } from "./schedule-wakeup.js";
 import { applyUnitSkillVisibility } from "../skill-scope.js";
 
 const UNIT_FAILSAFE_BUFFER_MS = 30_000;
@@ -248,7 +248,7 @@ export async function runUnit(
     ((supervisor.idle_timeout_minutes ?? 10) * 60 * 1000) + UNIT_FAILSAFE_BUFFER_MS,
   );
   let unitTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
-  let result: UnitResult;
+  let result: UnitResult = { status: "cancelled" };
   try {
     const awaitAgentEndWithTimeout = (agentEndPromise: Promise<UnitResult>): Promise<UnitResult> => {
       const timeoutResult = new Promise<UnitResult>((resolve) => {
@@ -360,6 +360,9 @@ export async function runUnit(
     }
   } finally {
     if (unitTimeoutHandle) clearTimeout(unitTimeoutHandle);
+    if (result.status !== "completed") {
+      clearAutoWakeup(s.basePath, unitType, unitId);
+    }
     ctx.ui.setWorkingMessage?.(undefined);
     setVisibleSkills?.(undefined);
   }

package/src/resources/extensions/gsd/auto/schedule-wakeup.ts

@@ -35,6 +35,14 @@ export function consumeAutoWakeup(
   return wakeup;
 }
 
+export function clearAutoWakeup(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+): void {
+  pendingWakeups.delete(wakeupKey(basePath, unitType, unitId));
+}
+
 export function _resetAutoWakeupsForTest(): void {
   pendingWakeups.clear();
 }

package/src/resources/extensions/gsd/auto/session.ts

@@ -30,6 +30,7 @@ import { normalizeRealPath } from "../paths.js";
 import type { MilestoneScope } from "../workspace.js";
 import type { RootDirtySnapshot } from "../root-write-leak-guard.js";
 import type { MilestoneSettlementOutcome } from "../milestone-settlement.js";
+import type { ToolSurfaceSnapshot } from "../tool-surface-snapshot.js";
 
 // ─── Exported Types ──────────────────────────────────────────────────────────
 
@@ -55,6 +56,7 @@ export type ThinkingLevelSnapshot = ReturnType<ExtensionAPI["getThinkingLevel"]>
 export interface PendingVerificationRetry {
   unitId: string;
   failureContext: string;
+  signature?: string;
   attempt: number;
 }
 
@@ -160,6 +162,9 @@ export class AutoSession {
   currentMilestoneId: string | null = null;
   readonly sourceObservations = new SourceObservationStore();
 
+  /** Live tool-surface snapshot for dashboard / runtime telemetry while auto is active. */
+  toolSurfaceSnapshot: ToolSurfaceSnapshot | null = null;
+
   // ── Model state ──────────────────────────────────────────────────────────
   autoModeStartModel: StartModel | null = null;
   /** Explicit /gsd model pin captured at bootstrap (session-scoped policy override). */
@@ -207,6 +212,13 @@ export class AutoSession {
    * the issues after MAX_PRE_EXEC_RETRIES re-attempts.
    */
   readonly preExecRetryCount: Map<string, number> = new Map();
+  /**
+   * Tracks how many times each slice unit has been re-dispatched to plan-slice
+   * because task plan files were missing. Keyed by unitId (e.g. "M001/S01").
+   * Separate from preExecRetryCount so pre-exec gate failures do not block or
+   * conflate with missing-task-plan recovery.
+   */
+  readonly missingTaskPlanRetryCount: Map<string, number> = new Map();
 
   // ── Tool invocation errors (#2883) ──────────────────────────────────
   /** Set when a GSD tool execution ends with isError due to malformed/truncated
@@ -367,6 +379,7 @@ export class AutoSession {
 
     // Unit
     this.clearCurrentUnit();
+    this.toolSurfaceSnapshot = null;
     this.currentTraceId = null;
     this.currentTurnId = null;
     this.currentUnitRouting = null;
@@ -407,6 +420,7 @@ export class AutoSession {
     this.consecutiveCompleteBootstraps = 0;
     this.lastPreExecFailure = null;
     this.preExecRetryCount.clear();
+    this.missingTaskPlanRetryCount.clear();
     this.lastToolInvocationError = null;
     this.toolUnavailableRetries = 0;
     this.lastUnitAgentEndMessages = null;

package/src/resources/extensions/gsd/auto/verification-retry-policy.ts

@@ -63,7 +63,9 @@ export function decideVerificationRetry(input: {
   }
 
   const key = verificationRetryKey(unitType, retryInfo.unitId);
-  const failureHash = hashVerificationFailureContext(retryInfo.failureContext);
+  const failureHash = hashVerificationFailureContext(
+    retryInfo.signature ?? retryInfo.failureContext,
+  );
   if (input.previousFailureHash === failureHash) {
     return {
       action: "pause",

package/src/resources/extensions/gsd/auto/workflow-kernel.ts

@@ -34,7 +34,7 @@ export type EngineDispatchDecision =
 
 export type FinalizeInput =
   | { action: "break"; reason?: string }
-  | { action: "continue" }
+  | { action: "continue"; failureDetail?: string }
   | { action: "next" };
 
 export type FinalizeDecision =
@@ -46,7 +46,14 @@ export type FinalizeDecision =
     }
   | {
       action: "retry";
-      ledgerErrorSummary: "finalize-retry";
+      /**
+       * Stable `"finalize-retry"` prefix plus, when available, the specific
+       * verification failure (e.g. `finalize-retry: roadmap has zero slices`).
+       * The prefix keeps legacy ledger filters matching; the suffix makes a
+       * stuck-loop kill message actionable instead of the opaque bare token
+       * that forced a full forensics dive to diagnose (#852 follow-up).
+       */
+      ledgerErrorSummary: string;
     }
   | { action: "complete" }
   | { action: "complete-and-break" };
@@ -295,6 +302,16 @@ function isCompleteAndBreakReason(
   );
 }
 
+/** Strip per-attempt counter suffixes so detect-stuck Rule 1 can match repeats. */
+const FAILURE_DETAIL_ATTEMPT_SUFFIX_RE = /\s*\(attempt\s+\d+(?:\/\d+)?\)\.?$/i;
+
+function failureDetailForLedger(detail: string | undefined): string | undefined {
+  const trimmed = detail?.trim();
+  if (!trimmed) return undefined;
+  const normalized = trimmed.replace(FAILURE_DETAIL_ATTEMPT_SUFFIX_RE, "").trim();
+  return normalized || undefined;
+}
+
 export function decideFinalizeResult(input: FinalizeInput): FinalizeDecision {
   if (input.action === "break") {
     const reason = input.reason ?? "unknown";
@@ -310,9 +327,14 @@ export function decideFinalizeResult(input: FinalizeInput): FinalizeDecision {
   }
 
   if (input.action === "continue") {
+    // Carry the specific verification failure (e.g. "roadmap has zero slices",
+    // "15-SUMMARY.md was not found on disk") into the ledger summary so the
+    // stuck-loop kill message is actionable. The `finalize-retry` prefix is
+    // preserved so legacy ledger filters and dashboards still match (#852).
+    const detail = failureDetailForLedger(input.failureDetail);
     return {
       action: "retry",
-      ledgerErrorSummary: "finalize-retry",
+      ledgerErrorSummary: detail ? `finalize-retry: ${detail}` : "finalize-retry",
     };
   }
 

package/src/resources/extensions/gsd/auto-artifact-paths.ts

@@ -8,17 +8,22 @@
 
 import {
   gsdRoot,
-  gsdProjectionRoot,
   resolveDir,
   resolveFile,
+  resolveMilestonePath,
+  resolveMilestoneFile,
+  resolveSliceFile,
   relMilestoneFile,
   relSliceFile,
-  buildMilestoneFileName,
-  buildSliceFileName,
   buildTaskFileName,
+  resolveSlicePath,
+  resolveTasksDir,
+  dirIsMetaOnlyLegacyMilestone,
 } from "./paths.js";
+import { milestoneIdToPhaseNum } from "./layout-policy.js";
 import { parseUnitId } from "./unit-id.js";
-import { join } from "node:path";
+import { dirname, join, relative } from "node:path";
+import { existsSync } from "node:fs";
 
 function resolveMilestoneArtifactPath(
   base: string,
@@ -27,8 +32,54 @@ function resolveMilestoneArtifactPath(
 ): string | null {
   const existing = resolveProjectedMilestoneFile(base, mid, suffix) ?? resolveProjectMilestoneFile(base, mid, suffix);
   if (existing) return existing;
-  const dir = resolveProjectedMilestonePath(base, mid) ?? resolveProjectMilestonePath(base, mid);
-  return dir ? join(dir, buildMilestoneFileName(mid, suffix)) : null;
+  // Try projected (worktree) path, then project-root path. Both can return
+  // either a legacy (milestones/<MID>/) or flat-phase (phases/NN-slug/) dir.
+  const dir = resolveProjectedMilestonePath(base, mid) ?? resolveProjectMilestonePath(base, mid) ?? resolveMilestonePath(base, mid);
+  if (dir) {
+    // The filename depends on the LAYOUT of the resolved directory, not on
+    // which resolver found it. A flat-phase dir (phases/NN-slug/) uses the
+    // phase-number prefix (15-CONTEXT.md); a legacy dir (milestones/<MID>/)
+    // uses the milestone-id prefix (M015-CONTEXT.md). Building the wrong
+    // filename for the resolved dir produces existsSync-false paths that trap
+    // the unit in a finalize-retry loop (#852).
+    //
+    // Layout is determined structurally from the resolved directory's parent
+    // segment name, NOT by comparing against a root-anchored legacyMilestonesDir
+    // base path. On a canonical worktree (<project>/.gsd-worktrees/M001/),
+    // legacyMilestonesDir uses gsdProjectionRoot (the worktree .gsd) while
+    // resolveProjectMilestonePath uses gsdRoot (the project .gsd) — two
+    // different roots. A dir returned by resolveProjectMilestonePath would
+    // fail the startsWith check against the worktree root and incorrectly
+    // produce a flat-phase filename for a legacy directory (#bugbot c5ee8eba).
+    const parentDir = dirname(dir);
+    const isLegacy = parentDir.endsWith("/milestones") || parentDir.endsWith("\\milestones");
+    const phaseNum = milestoneIdToPhaseNum(mid);
+    const filename = isLegacy
+      ? `${mid}-${suffix}.md`
+      : `${String(phaseNum).padStart(2, "0")}-${suffix}.md`;
+    return join(dir, filename);
+  }
+  return null;
+}
+
+/**
+ * Build the layout-aware filename for a milestone artifact suffix.
+ * Exported so other callers (e.g. verification diagnostics) use the same
+ * naming policy: flat-phase dirs use the phase-number prefix (15-CONTEXT.md),
+ * legacy dirs use the milestone-id prefix (M015-CONTEXT.md).
+ *
+ * Layout is determined structurally: dirs whose immediate parent is named
+ * "milestones" are legacy; all others are flat-phase. This avoids the
+ * root-path ambiguity between gsdProjectionRoot (worktree .gsd) and gsdRoot
+ * (project .gsd) that caused wrong filenames on canonical worktrees.
+ */
+export function buildMilestoneArtifactFilename(mid: string, suffix: string, dir: string): string {
+  const parentDir = dirname(dir);
+  const isLegacy = parentDir.endsWith("/milestones") || parentDir.endsWith("\\milestones");
+  const phaseNum = milestoneIdToPhaseNum(mid);
+  return isLegacy
+    ? `${mid}-${suffix}.md`
+    : `${String(phaseNum).padStart(2, "0")}-${suffix}.md`;
 }
 
 function resolveSliceArtifactPath(
@@ -39,14 +90,30 @@ function resolveSliceArtifactPath(
 ): string | null {
   const existing = resolveProjectedSliceFile(base, mid, sid, suffix) ?? resolveProjectSliceFile(base, mid, sid, suffix);
   if (existing) return existing;
-  const dir = resolveProjectedSlicePath(base, mid, sid) ?? resolveProjectSlicePath(base, mid, sid);
-  return dir ? join(dir, buildSliceFileName(sid, suffix)) : null;
+  // Flat-phase: plan files live at phases/NN-slug/NN-MM-SUFFIX.md — resolveSliceFile handles both layouts.
+  const flatPhase = resolveSliceFile(base, mid, sid, suffix);
+  if (flatPhase) return flatPhase;
+  // File doesn't exist yet — use relSliceFile for the layout-aware canonical path.
+  // buildSliceFileName(sid) only has sliceId → MM-SUFFIX.md, wrong for both layouts.
+  return join(base, relSliceFile(base, mid, sid, suffix));
 }
 
 function resolveProjectMilestonePath(base: string, mid: string): string | null {
   const milestonesDir = join(gsdRoot(base), "milestones");
   const dir = resolveDir(milestonesDir, mid);
-  return dir ? join(milestonesDir, dir) : null;
+  if (!dir) return null;
+  // git-service.ts creates milestones/<MID>/ for integration-branch metadata
+  // (<MID>-META.json) even in flat-phase projects. A dir that holds ONLY
+  // *-META.json files must not be treated as a real legacy milestone dir —
+  // otherwise this early-return resolves CONTEXT/ROADMAP/SUMMARY to the legacy
+  // path (milestones/<MID>/<MID>-<SUFFIX>.md) before the flat-phase fallback
+  // can run, trapping the unit in a finalize-retry loop (#852 follow-up).
+  //
+  // We use dirIsMetaOnlyLegacyMilestone rather than !dirIsContentBearingLegacyMilestone
+  // so that an EMPTY dir (a new milestone before any content is written) is NOT
+  // blocked — it is a valid legacy target that write-paths should resolve to.
+  if (dirIsMetaOnlyLegacyMilestone(join(milestonesDir, dir))) return null;
+  return join(milestonesDir, dir);
 }
 
 function resolveProjectMilestoneFile(base: string, mid: string, suffix: string): string | null {
@@ -72,16 +139,11 @@ function resolveProjectSliceFile(base: string, mid: string, sid: string, suffix:
 }
 
 function resolveProjectedMilestonePath(base: string, mid: string): string | null {
-  const milestonesDir = join(gsdProjectionRoot(base), "milestones");
-  const dir = resolveDir(milestonesDir, mid);
-  return dir ? join(milestonesDir, dir) : null;
+  return resolveMilestonePath(base, mid);
 }
 
 function resolveProjectedMilestoneFile(base: string, mid: string, suffix: string): string | null {
-  const dir = resolveProjectedMilestonePath(base, mid);
-  if (!dir) return null;
-  const file = resolveFile(dir, mid, suffix);
-  return file ? join(dir, file) : null;
+  return resolveMilestoneFile(base, mid, suffix);
 }
 
 function resolveProjectedSlicePath(base: string, mid: string, sid: string): string | null {
@@ -155,10 +217,12 @@ export function resolveExpectedArtifactPath(
       return resolveSliceArtifactPath(base, mid, sid!, "ASSESSMENT");
     }
     case "execute-task": {
-      const dir = resolveProjectedSlicePath(base, mid, sid!) ?? resolveProjectSlicePath(base, mid, sid!);
-      return dir && tid
-        ? join(dir, "tasks", buildTaskFileName(tid, "SUMMARY"))
-        : null;
+      const slicePath = resolveProjectedSlicePath(base, mid, sid!)
+        ?? resolveProjectSlicePath(base, mid, sid!)
+        ?? resolveSlicePath(base, mid, sid!);
+      if (!slicePath || !tid) return null;
+      const tasksDir = resolveTasksDir(base, mid, sid!) ?? slicePath;
+      return join(tasksDir, buildTaskFileName(tid, "SUMMARY"));
     }
     case "complete-slice": {
       return resolveSliceArtifactPath(base, mid, sid!, "SUMMARY");
@@ -251,3 +315,48 @@ export function diagnoseExpectedArtifact(
       return null;
   }
 }
+
+export interface SliceResearchLocation {
+  /** Absolute path when research exists; null when missing. */
+  absolutePath: string | null;
+  /** Prompt-friendly relative path when research exists. */
+  relativePath: string | null;
+}
+
+/**
+ * Resolve slice RESEARCH with worktree projection first, then canonical
+ * project-root path. Shared by dispatch rules, execute-task prompts, and
+ * artifact verification.
+ */
+export function resolveSliceResearchLocation(
+  basePath: string,
+  mid: string,
+  sid: string,
+): SliceResearchLocation {
+  const projectedFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
+  if (projectedFile) {
+    return {
+      absolutePath: projectedFile,
+      relativePath: relSliceFile(basePath, mid, sid, "RESEARCH"),
+    };
+  }
+
+  const canonicalPath = resolveExpectedArtifactPath("research-slice", `${mid}/${sid}`, basePath);
+  if (canonicalPath && existsSync(canonicalPath)) {
+    return {
+      absolutePath: canonicalPath,
+      relativePath: relative(basePath, canonicalPath),
+    };
+  }
+
+  return { absolutePath: null, relativePath: null };
+}
+
+/** Returns the absolute RESEARCH path when it exists, otherwise null. */
+export function resolveExistingSliceResearchPath(
+  basePath: string,
+  mid: string,
+  sid: string,
+): string | null {
+  return resolveSliceResearchLocation(basePath, mid, sid).absolutePath;
+}

package/src/resources/extensions/gsd/auto-budget.ts

@@ -79,7 +79,9 @@ export function resolveCompactionThresholdPercent(raw: number | undefined): numb
   return value <= 1 ? value * 100 : value;
 }
 
-export function shouldRerootStepSessionForContext(
+export const HARD_CONTEXT_REROOT_THRESHOLD_PERCENT = 90;
+
+export function shouldWarnStepSessionForContext(
   contextPercent: number | null | undefined,
   compactionThresholdPercent?: number,
 ): boolean {
@@ -88,3 +90,12 @@ export function shouldRerootStepSessionForContext(
     resolveCompactionThresholdPercent(compactionThresholdPercent),
   ) === "pause";
 }
+
+export function shouldRerootStepSessionForContext(
+  contextPercent: number | null | undefined,
+): boolean {
+  return getContextPauseAction(
+    contextPercent,
+    HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
+  ) === "pause";
+}