gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

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

@@ -1,14 +1,14 @@
 /**
- * Post-unit processing for handleAgentEnd — auto-commit, doctor run,
+ * Post-unit processing for auto-loop — auto-commit, doctor run,
  * state rebuild, worktree sync, DB dual-write, hooks, triage, and
  * quick-task dispatch.
  *
- * Split into two functions called sequentially by handleAgentEnd with
+ * Split into two functions called sequentially by auto-loop with
  * the verification gate between them:
  *   1. postUnitPreVerification() — commit, doctor, state rebuild, worktree sync, artifact verification
  *   2. postUnitPostVerification() — DB dual-write, hooks, triage, quick-tasks
  *
- * Extracted from handleAgentEnd() in auto.ts.
+ * Extracted from the pre-loop agent_end handler in auto.ts.
  */
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
@@ -99,7 +99,7 @@ function enqueueSidecar(
  *  next actual task commit via `smartStage()`. */
 const LIFECYCLE_ONLY_UNITS = new Set([
   "research-milestone", "discuss-milestone", "discuss-slice", "plan-milestone",
-  "validate-milestone", "research-slice", "plan-slice",
+  "validate-milestone", "research-slice", "plan-slice", "refine-slice",
   "replan-slice", "complete-slice", "run-uat",
   "reassess-roadmap", "rewrite-docs",
 ]);
@@ -190,7 +190,7 @@ export function detectRogueFileWrites(
     if (!hasPlanningState) {
       rogues.push({ path: roadmapPath, unitType, unitId });
     }
-  } else if (unitType === "plan-slice" || unitType === "replan-slice") {
+  } else if (unitType === "plan-slice" || unitType === "refine-slice" || unitType === "replan-slice") {
     if (!mid || !sid) return [];
 
     const planPath = resolveSliceFile(basePath, mid, sid, "PLAN");
@@ -735,7 +735,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         try {
           const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
           if (mid && sid) {
-            const regenerated = regenerateIfMissing(s.basePath, mid, sid, "PLAN");
+            const regenerated = await regenerateIfMissing(s.basePath, mid, sid, "PLAN");
             if (regenerated) {
               // Re-check after regeneration
               triggerArtifactVerified = verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
@@ -1020,10 +1020,12 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
     }
   }
 
-  // ── Pre-execution checks (after plan-slice completes) ──
+  // ── Pre-execution checks (after plan-slice or ADR-011 refine-slice completes) ──
+  // Both emit the same PLAN.md + task artifacts via gsd_plan_slice, so the
+  // same structural validation applies to both.
   if (
     s.currentUnit &&
-    s.currentUnit.type === "plan-slice"
+    (s.currentUnit.type === "plan-slice" || s.currentUnit.type === "refine-slice")
   ) {
     const currentUnit = s.currentUnit;
     let preExecPauseNeeded = false;

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

@@ -35,14 +35,56 @@ import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
+import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
 
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 
+/**
+ * Historical static ceiling for the preamble cap. Kept as an upper bound even
+ * after context-window-aware sizing so large-window users don't suddenly see
+ * 10× looser caps than before. Small-window users get a tighter cap derived
+ * from their configured executor window.
+ */
 const MAX_PREAMBLE_CHARS = 30_000;
 
+/**
+ * Resolve prompt budgets from the configured executor context window.
+ *
+ * The prompt builders here don't have access to the runtime model registry
+ * (they're called from many non-ctx sites), so `resolveExecutorContextWindow`
+ * is fed the user-configurable `context_window_override` preference as the
+ * `sessionContextWindow` fallback. That preference exists specifically to
+ * cover small-window local models (e.g. 32K lemonade/llama.cpp servers) whose
+ * n_ctx is not discoverable through the model registry. Issue #4435.
+ */
+function resolvePromptBudgets(): ReturnType<typeof computeBudgets> {
+  try {
+    const prefs = loadEffectiveGSDPreferences();
+    const sessionWindow = prefs?.preferences.context_window_override;
+    const windowTokens = resolveExecutorContextWindow(undefined, prefs?.preferences, sessionWindow);
+    return computeBudgets(windowTokens);
+  } catch (e) {
+    logWarning("prompt", `resolvePromptBudgets failed: ${(e as Error).message}`);
+    return computeBudgets(200_000);
+  }
+}
+
+/**
+ * Character budget for dependency/prior slice summaries injected into dispatch
+ * prompts. Scales with the executor's configured context window (issue #4435).
+ */
+function resolveSummaryBudgetChars(): number {
+  return resolvePromptBudgets().summaryBudgetChars;
+}
+
 function capPreamble(preamble: string): string {
-  if (preamble.length <= MAX_PREAMBLE_CHARS) return preamble;
-  return truncateAtSectionBoundary(preamble, MAX_PREAMBLE_CHARS).content;
+  // Cap inlined context at min(historical 30K ceiling, scaled inline budget).
+  // The ceiling preserves pre-fix behavior for large-window users; the scaled
+  // budget tightens the cap for small-window users whose true safe limit is
+  // below 30K. `computeBudgets` allocates 40% of total chars to inline context.
+  const budget = Math.min(MAX_PREAMBLE_CHARS, resolvePromptBudgets().inlineContextBudgetChars);
+  if (preamble.length <= budget) return preamble;
+  return truncateAtSectionBoundary(preamble, budget).content;
 }
 
 // ─── Executor Constraints ─────────────────────────────────────────────────────
@@ -75,7 +117,18 @@ function formatExecutorConstraints(): string {
   ].join("\n");
 }
 
-function buildSourceFilePaths(
+/**
+ * Returns a markdown bullet list of known context file paths for the given
+ * milestone (and optionally slice). Falls back to a generic tool-agnostic
+ * instruction when no GSD artifacts are found.
+ *
+ * @param base - Absolute path to the project root.
+ * @param mid  - Milestone ID (e.g. `"M001"`).
+ * @param sid  - Optional slice ID (e.g. `"S01"`). When provided, the slice
+ *   RESEARCH file is preferred over the milestone-level one.
+ * @returns Markdown string of file path bullets, or a fallback instruction.
+ */
+export function buildSourceFilePaths(
   base: string,
   mid: string,
   sid?: string,
@@ -126,7 +179,7 @@ function buildSourceFilePaths(
 
   return paths.length > 0
     ? paths.join("\n")
-    : "- Use `rg --files` and targeted reads to identify the relevant source files before planning.";
+    : "- Use the Grep/Glob/Read tools to identify the relevant source files before planning.";
 }
 
 // ─── Inline Helpers ───────────────────────────────────────────────────────
@@ -997,14 +1050,19 @@ export async function checkNeedsRunUat(
  * as a seed when present. The discussion agent interviews the user, writes
  * a full CONTEXT.md, and the phase transitions to pre-planning automatically.
  */
-export async function buildDiscussMilestonePrompt(mid: string, midTitle: string, base: string): Promise<string> {
+export async function buildDiscussMilestonePrompt(
+  mid: string,
+  midTitle: string,
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
   const discussTemplates = inlineTemplate("context", "Context");
 
   const basePrompt = loadPrompt("guided-discuss-milestone", {
     milestoneId: mid,
     milestoneTitle: midTitle,
     inlinedTemplates: discussTemplates,
-    structuredQuestionsAvailable: "false",
+    structuredQuestionsAvailable,
     commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
     fastPathInstruction: "",
   });
@@ -1182,7 +1240,7 @@ export async function buildResearchSlicePrompt(
 
   inlined.push(inlineTemplate("research", "Research"));
 
-  const depContent = await inlineDependencySummaries(mid, sid, base);
+  const depContent = await inlineDependencySummaries(mid, sid, base, resolveSummaryBudgetChars());
   const activeOverrides = await loadActiveOverrides(base);
   const overridesInline = formatOverridesSection(activeOverrides);
   if (overridesInline) inlined.unshift(overridesInline);
@@ -1211,10 +1269,28 @@ export async function buildResearchSlicePrompt(
   });
 }
 
-export async function buildPlanSlicePrompt(
-  mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
-): Promise<string> {
-  const inlineLevel = level ?? resolveInlineLevel();
+/**
+ * Shared assembly for plan-slice and refine-slice prompts. Both builders need
+ * the same inlined context (roadmap excerpt, slice context, research, decisions,
+ * requirements, knowledge, graph subgraph, templates, dependency summaries,
+ * overrides). Extracted to prevent drift between the two sites.
+ *
+ * `prependBlocks` are pushed onto the start of the inlined array BEFORE any
+ * shared content, so callers can add unit-specific headers (e.g., the refine
+ * sketch-scope constraint).
+ */
+async function renderSlicePrompt(options: {
+  mid: string;
+  sid: string;
+  sTitle: string;
+  base: string;
+  level: InlineLevel;
+  promptTemplate: "plan-slice" | "refine-slice";
+  prependBlocks?: string[];
+  extraVars?: Record<string, string>;
+}): Promise<string> {
+  const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {} } = options;
+
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
@@ -1222,18 +1298,17 @@ export async function buildPlanSlicePrompt(
   const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
   const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
 
-  const inlined: string[] = [];
+  const inlined: string[] = [...prependBlocks];
 
-  // Inject phase handoff anchor from research phase (if available)
+  // Phase handoff anchor from research phase (if available)
   const researchSliceAnchor = readPhaseAnchor(base, mid, "research-slice");
   if (researchSliceAnchor) inlined.push(formatAnchorForPrompt(researchSliceAnchor));
 
-  // Use roadmap excerpt instead of full roadmap for context reduction
-  const roadmapExcerptPS = await inlineRoadmapExcerpt(base, mid, sid);
-  if (roadmapExcerptPS) {
-    inlined.push(roadmapExcerptPS);
+  // Roadmap excerpt with full-roadmap fallback
+  const roadmapExcerpt = await inlineRoadmapExcerpt(base, mid, sid);
+  if (roadmapExcerpt) {
+    inlined.push(roadmapExcerpt);
   } else {
-    // Fall back to full roadmap if excerpt fails
     inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
   }
 
@@ -1241,42 +1316,36 @@ export async function buildPlanSlicePrompt(
   if (sliceCtxInline) inlined.push(sliceCtxInline);
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
   if (researchInline) inlined.push(researchInline);
-  if (inlineLevel !== "minimal") {
-    // Derive scope from slice title for decision filtering (R005)
-    const derivedScopePS = deriveSliceScope(sTitle);
-    const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScopePS, inlineLevel);
+
+  if (level !== "minimal") {
+    const derivedScope = deriveSliceScope(sTitle);
+    const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScope, level);
     if (decisionsInline) inlined.push(decisionsInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel);
+    const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, level);
     if (requirementsInline) inlined.push(requirementsInline);
   }
 
-  // Use scoped knowledge based on slice title keywords
-  const keywordsPS = extractKeywords(sTitle);
-  const knowledgeInlinePS = await inlineKnowledgeScoped(base, keywordsPS);
-  if (knowledgeInlinePS) inlined.push(knowledgeInlinePS);
+  const knowledgeInline = await inlineKnowledgeScoped(base, extractKeywords(sTitle));
+  if (knowledgeInline) inlined.push(knowledgeInline);
 
-  // Knowledge graph: subgraph for this slice (graceful — skipped if no graph.json)
-  const graphBlockPS = await inlineGraphSubgraph(base, `${sid} ${sTitle}`, { budget: 3000 });
-  if (graphBlockPS) inlined.push(graphBlockPS);
+  const graphBlock = await inlineGraphSubgraph(base, `${sid} ${sTitle}`, { budget: 3000 });
+  if (graphBlock) inlined.push(graphBlock);
 
   inlined.push(inlineTemplate("plan", "Slice Plan"));
-  if (inlineLevel === "full") {
+  if (level === "full") {
     inlined.push(inlineTemplate("task-plan", "Task Plan"));
   }
 
-  const depContent = await inlineDependencySummaries(mid, sid, base);
-  const planActiveOverrides = await loadActiveOverrides(base);
-  const planOverridesInline = formatOverridesSection(planActiveOverrides);
-  if (planOverridesInline) inlined.unshift(planOverridesInline);
+  const depContent = await inlineDependencySummaries(mid, sid, base, resolveSummaryBudgetChars());
+  const overridesInline = formatOverridesSection(await loadActiveOverrides(base));
+  if (overridesInline) inlined.unshift(overridesInline);
 
   const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
-
-  // Build executor context constraints from the budget engine
   const executorContextConstraints = formatExecutorConstraints();
-
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
   const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
-  return loadPrompt("plan-slice", {
+
+  return loadPrompt(promptTemplate, {
     workingDirectory: base,
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
     slicePath: relSlicePath(base, mid, sid),
@@ -1295,6 +1364,68 @@ export async function buildPlanSlicePrompt(
       sliceTitle: sTitle,
       extraContext: [inlinedContext, depContent],
     }),
+    ...extraVars,
+  });
+}
+
+export async function buildPlanSlicePrompt(
+  mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
+  options?: { softScopeHint?: string },
+): Promise<string> {
+  const prependBlocks: string[] = [];
+  // ADR-011: when the refining-phase dispatch rule gracefully downgrades to
+  // plan-slice (progressive_planning was toggled off mid-milestone), it
+  // forwards the stored sketch_scope as a SOFT hint — context, not a hard
+  // constraint. The planner is free to expand beyond it.
+  if (options?.softScopeHint && options.softScopeHint.trim().length > 0) {
+    prependBlocks.push(
+      `## Prior Sketch Scope (soft hint — non-binding)\n\n${options.softScopeHint.trim()}\n\n` +
+      `This scope was captured during an earlier progressive-planning pass that was later disabled. Treat it as context only — you may plan beyond it if the work genuinely requires more scope. Do NOT treat this as a hard boundary.`,
+    );
+  }
+  return renderSlicePrompt({
+    mid, sid, sTitle, base,
+    level: level ?? resolveInlineLevel(),
+    promptTemplate: "plan-slice",
+    prependBlocks,
+  });
+}
+
+/**
+ * ADR-011 refine-slice: expand a sketch into a full plan using the current
+ * codebase state and prior slice summary. Mechanically similar to plan-slice
+ * but framed as a *transformation* (sketch → full plan) rather than a
+ * blank-sheet planning pass. Reuses inlineDependencySummaries for prior
+ * slice SUMMARY and inlines the stored sketch_scope as a hard constraint.
+ */
+export async function buildRefineSlicePrompt(
+  mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
+): Promise<string> {
+  // Pull the stored sketch scope from the DB — the hard constraint we plan within.
+  let sketchScope = "";
+  try {
+    const { isDbAvailable, getSlice } = await import("./gsd-db.js");
+    if (isDbAvailable()) {
+      sketchScope = getSlice(mid, sid)?.sketch_scope ?? "";
+    }
+  } catch {
+    sketchScope = "";
+  }
+
+  const prependBlocks: string[] = [];
+  if (sketchScope.trim().length > 0) {
+    prependBlocks.push(
+      `## Sketch Scope (hard constraint)\n\n${sketchScope.trim()}\n\n` +
+      `Treat this as the authoritative boundary for the slice. Do not plan work outside this scope; if the scope is too narrow, surface it as a deviation rather than expanding silently.`,
+    );
+  }
+
+  return renderSlicePrompt({
+    mid, sid, sTitle, base,
+    level: level ?? resolveInlineLevel(),
+    promptTemplate: "refine-slice",
+    prependBlocks,
+    extraVars: { sketchScope },
   });
 }
 
@@ -1412,7 +1543,28 @@ export async function buildExecuteTaskPrompt(
     ? `### Runtime Context\nSource: \`.gsd/RUNTIME.md\`\n\n${runtimeContent.trim()}`
     : "";
 
-  const phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
+  let phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
+
+  // ADR-011 Phase 2: inject any resolved-but-unapplied escalation override
+  // into this task's prompt. Claim is atomic via DB UPDATE WHERE IS NULL, so
+  // if a parallel build already injected it, we skip. Feature-gated by
+  // phases.mid_execution_escalation. Prepended to phaseAnchorSection so it
+  // appears near the top of the prompt above planning anchors.
+  if (prefs?.preferences?.phases?.mid_execution_escalation === true) {
+    try {
+      const { claimOverrideForInjection } = await import("./escalation.js");
+      const claimed = claimOverrideForInjection(base, mid, sid);
+      if (claimed) {
+        const block = claimed.injectionBlock + "\n\n---\n\n";
+        phaseAnchorSection = phaseAnchorSection
+          ? `${block}${phaseAnchorSection}`
+          : block;
+      }
+    } catch (escalationErr) {
+      // Escalation module unavailable or threw — log and proceed.
+      logWarning("prompt", `escalation override injection failed: ${(escalationErr as Error).message}`);
+    }
+  }
 
   // Task-scoped gates owned by execute-task (Q5/Q6/Q7). Pull only the
   // gates that plan-slice actually seeded for this task — tasks with no
@@ -1593,6 +1745,14 @@ export async function buildCompleteMilestonePrompt(
 
   const milestoneSummaryPath = join(base, `${relMilestonePath(base, mid)}/${mid}-SUMMARY.md`);
 
+  const learningsRelPath = join(relMilestonePath(base, mid), `${mid}-LEARNINGS.md`);
+  const learningsAbsPath = join(base, learningsRelPath);
+  const extractLearningsSteps = buildExtractionStepsBlock({
+    milestoneId: mid,
+    outputPath: learningsAbsPath,
+    relativeOutputPath: learningsRelPath,
+  });
+
   return loadPrompt("complete-milestone", {
     workingDirectory: base,
     milestoneId: mid,
@@ -1600,6 +1760,7 @@ export async function buildCompleteMilestonePrompt(
     roadmapPath: roadmapRel,
     inlinedContext,
     milestoneSummaryPath,
+    extractLearningsSteps,
     skillActivation: buildSkillActivationBlock({
       base,
       milestoneId: mid,

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

@@ -261,6 +261,45 @@ export function verifyExpectedArtifact(
     return true;
   }
 
+  // #4414: research-slice parallel-research sentinel. The unitId
+  // `{mid}/parallel-research` is not a real slice — it triggers a single agent
+  // that fans out research across multiple slices. Verify success by checking
+  // that every slice which was "research-ready" in the roadmap now has a
+  // RESEARCH file. Without this, resolveExpectedArtifactPath returns null and
+  // the retry/escalation machinery silently re-dispatches forever.
+  //
+  // NOTE: this predicate mirrors the dispatch rule at
+  // auto-dispatch.ts parallel-research-slices — keep the two in sync.
+  if (unitType === "research-slice" && unitId.endsWith("/parallel-research")) {
+    const { milestone: mid } = parseUnitId(unitId);
+    if (!mid) return false;
+    const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
+    if (!roadmapFile || !existsSync(roadmapFile)) {
+      logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap missing`);
+      return false;
+    }
+    try {
+      const roadmap = parseLegacyRoadmap(readFileSync(roadmapFile, "utf-8"));
+      const milestoneResearchFile = resolveMilestoneFile(base, mid, "RESEARCH");
+      for (const slice of roadmap.slices) {
+        if (slice.done) continue;
+        if (milestoneResearchFile && slice.id === "S01") continue;
+        const depsComplete = (slice.depends ?? []).every((depId) =>
+          !!resolveSliceFile(base, mid, depId, "SUMMARY"),
+        );
+        if (!depsComplete) continue;
+        if (!resolveSliceFile(base, mid, slice.id, "RESEARCH")) {
+          logWarning("recovery", `verify-fail ${unitType} ${unitId}: slice ${slice.id} missing RESEARCH`);
+          return false;
+        }
+      }
+      return true;
+    } catch (err) {
+      logWarning("recovery", `parallel-research verification failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }
+  }
+
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
   // For unit types with no verifiable artifact (null path), the parent directory
   // is missing on disk — treat as stale completion state so the key gets evicted (#313).
@@ -455,6 +494,14 @@ export function writeBlockerPlaceholder(
   ].join("\n");
   writeFileSync(absPath, content, "utf-8");
 
+  // #4414: Clear caches so subsequent dispatch guards (e.g.
+  // resolveMilestoneFile) see the placeholder file. Without this, the
+  // cached directory listing is stale and the dispatch rule re-fires,
+  // producing an infinite loop despite the placeholder being on disk.
+  // Matches the pattern used in verifyExpectedArtifact above.
+  clearPathCache();
+  clearParseCache();
+
   // Mark the task/slice as complete in the DB so verifyExpectedArtifact passes.
   // Without this, the DB status stays "pending" and the dispatch loop
   // re-derives the same unit indefinitely (#2531, #2653).
@@ -462,7 +509,22 @@ export function writeBlockerPlaceholder(
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     const ts = new Date().toISOString();
     if (unitType === "execute-task" && mid && sid && tid) {
-      try { updateTaskStatus(mid, sid, tid, "complete", ts); } catch (e) { logWarning("recovery", `updateTaskStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`); }
+      try {
+        updateTaskStatus(mid, sid, tid, "complete", ts);
+        const planPath = resolveSliceFile(base, mid, sid, "PLAN");
+        if (planPath && existsSync(planPath)) {
+          const planContent = readFileSync(planPath, "utf-8");
+          const updatedPlan = planContent.replace(
+            new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
+            `$1[x] **${tid}:`,
+          );
+          if (updatedPlan !== planContent) {
+            atomicWriteSync(planPath, updatedPlan);
+          }
+        }
+      } catch (e) {
+        logWarning("recovery", `updateTaskStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`);
+      }
       // Append event so worktree reconciliation can replay this recovery completion
       try { appendEvent(base, { cmd: "complete-task", params: { milestoneId: mid, sliceId: sid, taskId: tid }, ts, actor: "system", trigger_reason: "blocker-placeholder-recovery" }); } catch (e) { logWarning("recovery", `appendEvent failed for task recovery: ${e instanceof Error ? e.message : String(e)}`); }
     }

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

@@ -464,11 +464,12 @@ export async function bootstrapAutoSession(
     // Detect survivor milestone branches in both pre-planning and complete phases.
     // In phase=complete, the milestone artifacts exist but finalization (merge,
     // worktree cleanup) was never run — the survivor branch must be merged.
+    // Applies to both worktree and branch isolation modes.
     let hasSurvivorBranch = false;
     if (
       state.activeMilestone &&
       (state.phase === "pre-planning" || state.phase === "complete") &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       !detectWorktreeName(base) &&
       !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)
     ) {
@@ -711,7 +712,7 @@ export async function bootstrapAutoSession(
 
     if (
       s.currentMilestoneId &&
-      shouldUseWorktreeIsolation() &&
+      getIsolationMode() !== "none" &&
       !detectWorktreeName(base) &&
       !isUnderGsdWorktrees(base)
     ) {
@@ -837,10 +838,11 @@ export async function bootstrapAutoSession(
     const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
     const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
     const effectivelyEnabled = routingConfig.enabled
-      && !(effectiveProvider && isFlatRateProvider(
-        effectiveProvider,
-        buildFlatRateContext(effectiveProvider, ctx, bannerPrefs),
-      ));
+      && (routingConfig.allow_flat_rate_providers
+        || !(effectiveProvider && isFlatRateProvider(
+          effectiveProvider,
+          buildFlatRateContext(effectiveProvider, ctx, bannerPrefs),
+        )));
 
     // The actual ceiling may come from tier_models.heavy, not the start model.
     const effectiveCeiling = (routingConfig.enabled && routingConfig.tier_models?.heavy)

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

@@ -5,9 +5,9 @@
  * dependency audits, handles auto-fix retry logic, and writes
  * verification evidence JSON.
  *
- * Extracted from handleAgentEnd() in auto.ts. Returns a sentinel
- * value instead of calling return/pauseAuto directly — the caller
- * checks the result and handles control flow.
+ * Extracted from the pre-loop agent_end handler in auto.ts. Returns a
+ * sentinel value instead of calling return/pauseAuto directly — the
+ * caller checks the result and handles control flow.
  */
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";

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

@@ -60,6 +60,7 @@ import {
   nativeAddPaths,
   nativeRmForce,
   nativeBranchDelete,
+  nativeBranchForceReset,
   nativeBranchExists,
   nativeDiffNumstat,
   nativeUpdateRef,
@@ -921,10 +922,74 @@ export function runWorktreePostCreateHook(
 
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
 
+/** Returns the git branch name for a milestone worktree (`milestone/<MID>`). */
 export function autoWorktreeBranch(milestoneId: string): string {
   return `milestone/${milestoneId}`;
 }
 
+// ─── Branch-mode Entry ─────────────────────────────────────────────────────
+
+/**
+ * Enter branch isolation mode for a milestone.
+ *
+ * Creates `milestone/<MID>` from the integration branch (if it doesn't
+ * exist yet) and checks out to it.  No worktree directory is created — the
+ * project root is the working copy; only HEAD changes.
+ *
+ * Uses the same 3-tier integration-branch fallback as createAutoWorktree:
+ *   1. META.json recorded integration branch
+ *   2. git.main_branch preference
+ *   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+ */
+export function enterBranchModeForMilestone(
+  basePath: string,
+  milestoneId: string,
+): void {
+  const branch = autoWorktreeBranch(milestoneId);
+  const branchExists = nativeBranchExists(basePath, branch);
+
+  if (!branchExists) {
+    // Create the milestone branch from the integration branch start-point.
+    const integrationBranch =
+      readIntegrationBranch(basePath, milestoneId) ?? undefined;
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+    // Validate main_branch preference exists in the repo before using it —
+    // a stale preference (e.g. "master" when repo uses "main") would cause
+    // nativeBranchForceReset to fail with a bad start-point reference.
+    const validatedPrefBranch =
+      gitPrefs?.main_branch &&
+      typeof gitPrefs.main_branch === "string" &&
+      gitPrefs.main_branch.length > 0 &&
+      nativeBranchExists(basePath, gitPrefs.main_branch)
+        ? gitPrefs.main_branch
+        : undefined;
+    const startPoint =
+      integrationBranch ??
+      validatedPrefBranch ??
+      nativeDetectMainBranch(basePath);
+
+    // nativeBranchForceReset creates (or resets) branch at startPoint,
+    // then checkout switches HEAD to it.
+    nativeBranchForceReset(basePath, branch, startPoint);
+    debugLog("auto-worktree", {
+      action: "enterBranchMode",
+      milestoneId,
+      branch,
+      startPoint,
+      created: true,
+    });
+  } else {
+    debugLog("auto-worktree", {
+      action: "enterBranchMode",
+      milestoneId,
+      branch,
+      reused: true,
+    });
+  }
+
+  nativeCheckoutBranch(basePath, branch);
+}
+
 // ─── Public API ────────────────────────────────────────────────────────────
 
 /**