gsd-pi 2.44.0 → 2.45.0-dev.e0ee972

package/src/resources/extensions/gsd/auto/infra-errors.ts

@@ -18,6 +18,9 @@ export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "EDQUOT",   // disk quota exceeded
   "EMFILE",   // too many open files (process)
   "ENFILE",   // too many open files (system)
+  "ECONNREFUSED", // connection refused (offline / local server down)
+  "ENOTFOUND",    // DNS lookup failed (offline / no network)
+  "ENETUNREACH",  // network unreachable (offline / no route)
 ]);
 
 /**

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

@@ -27,7 +27,10 @@ import { debugLog } from "../debug-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { PROJECT_FILES } from "../detection.js";
+import { MergeConflictError } from "../git-service.js";
 import { join } from "node:path";
+import { existsSync, cpSync } from "node:fs";
+import { logWarning, logError } from "../workflow-logger.js";
 
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 
@@ -162,8 +165,8 @@ export async function runPreDispatch(
       debugLog("autoLoop", { phase: "exit", reason: "health-gate-failed" });
       return { action: "break", reason: "health-gate-failed" };
     }
-  } catch {
-    // Non-fatal
+  } catch (e) {
+    logWarning("engine", "Pre-dispatch health gate threw unexpectedly", { error: String(e) });
   }
 
   // Sync project root artifacts into worktree
@@ -233,26 +236,24 @@ export async function runPreDispatch(
     loopState.stuckRecoveryAttempts = 0;
 
     // Worktree lifecycle on milestone transition — merge current, enter next
-    deps.resolver.mergeAndExit(s.currentMilestoneId!, ctx.ui);
-
-    // Opt-in: create draft PR on milestone completion
-    if (prefs?.git?.auto_pr) {
-      try {
-        const { createDraftPR } = await import("../git-service.js");
-        const prUrl = createDraftPR(
-          s.basePath,
-          s.currentMilestoneId!,
-          `[GSD] ${s.currentMilestoneId} complete`,
-          `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+    try {
+      deps.resolver.mergeAndExit(s.currentMilestoneId!, ctx.ui);
+    } catch (mergeErr) {
+      if (mergeErr instanceof MergeConflictError) {
+        // Real code conflicts — stop the loop instead of retrying forever (#2330)
+        ctx.ui.notify(
+          `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
+          "error",
         );
-        if (prUrl) {
-          ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-        }
-      } catch {
-        // Non-fatal — PR creation is best-effort
+        await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+        return { action: "break", reason: "merge-conflict" };
       }
+      // Non-conflict merge errors — log and continue
+      logWarning("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId!, error: String(mergeErr) });
     }
 
+    // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
+
     deps.invalidateAllCaches();
 
     state = await deps.deriveState(s.basePath);
@@ -279,11 +280,21 @@ export async function runPreDispatch(
     // Reset completed-units tracking for the new milestone — stale entries
     // from the previous milestone cause the dispatch loop to skip units
     // that haven't actually been completed in the new milestone's context.
+    // Archive the old completed-units.json instead of wiping it (#2313).
     s.completedUnits = [];
     try {
       const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
+      if (existsSync(completedKeysPath) && s.currentMilestoneId) {
+        const archivePath = join(
+          gsdRoot(s.basePath),
+          `completed-units-${s.currentMilestoneId}.json`,
+        );
+        cpSync(completedKeysPath, archivePath);
+      }
       atomicWriteSync(completedKeysPath, JSON.stringify([], null, 2));
-    } catch { /* non-fatal */ }
+    } catch (e) {
+      logWarning("engine", "Failed to archive completed-units on milestone transition", { error: String(e) });
+    }
 
     // Rebuild STATE.md immediately so it reflects the new active milestone.
     // This bypasses the 30-second throttle in the normal rebuild path —
@@ -291,8 +302,8 @@ export async function runPreDispatch(
     // immediate write.
     try {
       await deps.rebuildState(s.basePath);
-    } catch {
-      // Non-fatal — STATE.md will be rebuilt on the next regular cycle
+    } catch (e) {
+      logWarning("engine", "STATE.md rebuild failed after milestone transition", { error: String(e) });
     }
   }
 
@@ -322,25 +333,20 @@ export async function runPreDispatch(
     if (incomplete.length === 0 && state.registry.length > 0) {
       // All milestones complete — merge milestone branch before stopping
       if (s.currentMilestoneId) {
-        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-
-        // Opt-in: create draft PR on milestone completion
-        if (prefs?.git?.auto_pr) {
-          try {
-            const { createDraftPR } = await import("../git-service.js");
-            const prUrl = createDraftPR(
-              s.basePath,
-              s.currentMilestoneId,
-              `[GSD] ${s.currentMilestoneId} complete`,
-              `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+        try {
+          deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+        } catch (mergeErr) {
+          if (mergeErr instanceof MergeConflictError) {
+            ctx.ui.notify(
+              `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
+              "error",
             );
-            if (prUrl) {
-              ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-            }
-          } catch {
-            // Non-fatal — PR creation is best-effort
+            await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+            return { action: "break", reason: "merge-conflict" };
           }
         }
+
+        // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
       }
       deps.sendDesktopNotification(
         "GSD",
@@ -422,25 +428,20 @@ export async function runPreDispatch(
   if (state.phase === "complete") {
     // Milestone merge on complete (before closeout so branch state is clean)
     if (s.currentMilestoneId) {
-      deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-
-      // Opt-in: create draft PR on milestone completion
-      if (prefs?.git?.auto_pr) {
-        try {
-          const { createDraftPR } = await import("../git-service.js");
-          const prUrl = createDraftPR(
-            s.basePath,
-            s.currentMilestoneId,
-            `[GSD] ${s.currentMilestoneId} complete`,
-            `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`,
+      try {
+        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+      } catch (mergeErr) {
+        if (mergeErr instanceof MergeConflictError) {
+          ctx.ui.notify(
+            `Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`,
+            "error",
           );
-          if (prUrl) {
-            ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-          }
-        } catch {
-          // Non-fatal — PR creation is best-effort
+          await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+          return { action: "break", reason: "merge-conflict" };
         }
       }
+
+      // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
     }
     deps.sendDesktopNotification(
       "GSD",
@@ -860,6 +861,7 @@ export async function runUnitPhase(
       lastProgressAt: s.currentUnit.startedAt,
       progressCount: 0,
       lastProgressKind: "dispatch",
+      recoveryAttempts: 0, // Reset so re-dispatched units get full recovery budget (#2322)
     },
   );
 
@@ -921,8 +923,8 @@ export async function runUnitPhase(
         (decisionsContent?.length ?? 0) +
         (requirementsContent?.length ?? 0) +
         (projectContent?.length ?? 0);
-    } catch {
-      // Non-fatal
+    } catch (e) {
+      logWarning("engine", "Baseline char count measurement failed", { error: String(e) });
     }
   }
 
@@ -932,9 +934,7 @@ export async function runUnitPhase(
   } catch (reorderErr) {
     const msg =
       reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
-    process.stderr.write(
-      `[gsd] prompt reorder failed (non-fatal): ${msg}\n`,
-    );
+    logWarning("engine", "Prompt reorder failed", { error: msg });
   }
 
   // Select and apply model (with tier escalation on retry — normal units only)
@@ -1137,7 +1137,9 @@ export async function runUnitPhase(
       const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
       const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
       atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
-    } catch { /* non-fatal: disk flush failure */ }
+    } catch (e) {
+      logWarning("engine", "Failed to flush completed-units to disk", { error: String(e) });
+    }
 
     deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
     s.unitDispatchCount.delete(`${unitType}/${unitId}`);

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

@@ -11,6 +11,7 @@ import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
 import type { UnitResult } from "./types.js";
 import { _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
 import { debugLog } from "../debug-logger.js";
+import { logWarning, logError } from "../workflow-logger.js";
 
 /**
  * Execute a single unit: create a new session, send the prompt, and await
@@ -85,7 +86,9 @@ export async function runUnit(
     if (process.cwd() !== s.basePath) {
       process.chdir(s.basePath);
     }
-  } catch { /* non-fatal — chdir may fail if dir was removed */ }
+  } catch (e) {
+    logWarning("engine", "Failed to chdir to basePath before dispatch", { basePath: s.basePath, error: String(e) });
+  }
 
   // ── Send the prompt ──
   debugLog("runUnit", { phase: "send-message", unitType, unitId });
@@ -115,8 +118,8 @@ export async function runUnit(
     if (typeof cmdCtxAny?.clearQueue === "function") {
       (cmdCtxAny.clearQueue as () => unknown)();
     }
-  } catch {
-    // Non-fatal — clearQueue may not be available in all contexts
+  } catch (e) {
+    logWarning("engine", "clearQueue failed after unit completion", { error: String(e) });
   }
 
   return result;

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

@@ -1307,6 +1307,12 @@ export async function buildCompleteMilestonePrompt(
     roadmapPath: roadmapRel,
     inlinedContext,
     milestoneSummaryPath,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1390,6 +1396,12 @@ export async function buildValidateMilestonePrompt(
     inlinedContext,
     validationPath: validationOutputPath,
     remediationRound: String(remediationRound),
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1500,6 +1512,12 @@ export async function buildRunUatPrompt(
     uatResultPath,
     uatType,
     inlinedContext,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      sliceId,
+      extraContext: [inlinedContext],
+    }),
   });
 }
 
@@ -1552,11 +1570,16 @@ export async function buildReassessRoadmapPrompt(
     milestoneTitle: midTitle,
     completedSliceId,
     roadmapPath: roadmapRel,
-    completedSliceSummaryPath: summaryRel,
     assessmentPath,
     inlinedContext,
     deferredCaptures,
     commitInstruction: reassessCommitInstruction,
+    skillActivation: buildSkillActivationBlock({
+      base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      extraContext: [inlinedContext, deferredCaptures],
+    }),
   });
 }
 

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

@@ -297,11 +297,14 @@ export async function bootstrapAutoSession(
       }
     }
 
-    // Milestone branch recovery (#601)
+    // Milestone branch recovery (#601, #2358)
+    // 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.
     let hasSurvivorBranch = false;
     if (
       state.activeMilestone &&
-      state.phase === "pre-planning" &&
+      (state.phase === "pre-planning" || state.phase === "complete") &&
       shouldUseWorktreeIsolation() &&
       !detectWorktreeName(base) &&
       !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)
@@ -343,6 +346,26 @@ export async function bootstrapAutoSession(
       }
     }
 
+    // Survivor branch exists and milestone is complete (#2358):
+    // The milestone artifacts were written but finalization (merge, worktree
+    // cleanup) never ran. Run mergeAndExit to finalize, then re-derive state
+    // so the normal "all milestones complete" or "next milestone" path runs.
+    if (hasSurvivorBranch && state.phase === "complete") {
+      const mid = state.activeMilestone!.id;
+      ctx.ui.notify(
+        `Milestone ${mid} is complete but branch/worktree was not finalized. Running merge now.`,
+        "info",
+      );
+      const resolver = buildResolver();
+      resolver.mergeAndExit(mid, {
+        notify: ctx.ui.notify.bind(ctx.ui),
+      });
+      invalidateAllCaches();
+      state = await deriveState(base);
+      // Clear survivor flag — finalization is done
+      hasSurvivorBranch = false;
+    }
+
     if (!hasSurvivorBranch) {
       // No active work — start a new milestone via discuss flow
       if (!state.activeMilestone || state.phase === "complete") {
@@ -551,6 +574,20 @@ export async function bootstrapAutoSession(
       }
     }
 
+    // Gate: abort bootstrap if the DB file exists but the provider is
+    // still unavailable after both open attempts above. Without this,
+    // auto-mode starts but every gsd_task_complete / gsd_slice_complete
+    // call returns "db_unavailable", triggering artifact-retry which
+    // re-dispatches the same task — producing an infinite loop (#2419).
+    if (existsSync(gsdDbPath) && !isDbAvailable()) {
+      ctx.ui.notify(
+        "SQLite database exists but failed to open. Auto-mode cannot proceed without a working database provider. " +
+          "Check for corrupt gsd.db or missing native SQLite bindings.",
+        "error",
+      );
+      return releaseLockAndReturn();
+    }
+
     // Initialize metrics
     initMetrics(s.basePath);
 

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

@@ -8,6 +8,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "./unit-runtime.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveAutoSupervisorConfig } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
@@ -32,6 +33,8 @@ export interface SupervisionContext {
   buildSnapshotOpts: () => CloseoutOptions & Record<string, unknown>;
   buildRecoveryContext: () => RecoveryContext;
   pauseAuto: (ctx?: ExtensionContext, pi?: ExtensionAPI) => Promise<void>;
+  /** Optional task estimate string (e.g. "30m", "2h") for timeout scaling (#2243). */
+  taskEstimate?: string;
 }
 
 /**
@@ -41,13 +44,71 @@ export interface SupervisionContext {
  * 3. Hard timeout (pause + recovery)
  * 4. Context-pressure monitor (continue-here)
  */
+
+/**
+ * Parse a task estimate string (e.g. "30m", "2h", "1h30m") into minutes.
+ * Returns null if the string cannot be parsed.
+ */
+export function parseEstimateMinutes(estimate: string): number | null {
+  if (!estimate || typeof estimate !== "string") return null;
+  const trimmed = estimate.trim();
+  if (!trimmed) return null;
+
+  let totalMinutes = 0;
+  let matched = false;
+
+  // Match hours component
+  const hoursMatch = trimmed.match(/(\d+)\s*h/i);
+  if (hoursMatch) {
+    totalMinutes += Number(hoursMatch[1]) * 60;
+    matched = true;
+  }
+
+  // Match minutes component
+  const minutesMatch = trimmed.match(/(\d+)\s*m/i);
+  if (minutesMatch) {
+    totalMinutes += Number(minutesMatch[1]);
+    matched = true;
+  }
+
+  return matched ? totalMinutes : null;
+}
+
 export function startUnitSupervision(sctx: SupervisionContext): void {
   const { s, ctx, pi, unitType, unitId, prefs, buildSnapshotOpts, buildRecoveryContext, pauseAuto } = sctx;
 
   const supervisor = resolveAutoSupervisorConfig();
-  const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000;
-  const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;
-  const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000;
+
+  // Scale timeouts based on task estimate annotations (#2243).
+  // If the task has an est: annotation, use it to extend the hard and soft timeouts
+  // so longer tasks don't get prematurely timed out.
+  let taskEstimate = sctx.taskEstimate;
+  if (!taskEstimate && unitType === "task" && isDbAvailable()) {
+    // Look up the task estimate from the DB (#2243).
+    try {
+      if (s.currentMilestoneId) {
+        const slices = getMilestoneSlices(s.currentMilestoneId);
+        for (const slice of slices) {
+          const tasks = getSliceTasks(s.currentMilestoneId, slice.id);
+          const task = tasks.find(t => t.id === unitId);
+          if (task?.estimate) {
+            taskEstimate = task.estimate;
+            break;
+          }
+        }
+      }
+    } catch {
+      // Non-fatal — fall through with no estimate
+    }
+  }
+  const estimateMinutes = taskEstimate ? parseEstimateMinutes(taskEstimate) : null;
+  const timeoutScale = estimateMinutes && estimateMinutes > 0
+    ? Math.max(1, estimateMinutes / 10)  // 10min task = 1x, 30min = 3x, 2h = 12x
+    : 1;
+
+  const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
+  const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;  // idle not scaled — idle is idle
+  const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
 
   // ── 1. Soft timeout warning ──
   s.wrapupWarningHandle = setTimeout(() => {

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

@@ -93,6 +93,11 @@ export function syncStateToProjectRoot(
     { force: true },
   );
 
+  // 3. metrics.json — session cost/token tracking (#2313).
+  // Without this, metrics accumulated in the worktree are invisible from the
+  // project root and never appear in the dashboard or skill-health reports.
+  safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
+
   // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
   // Without this, a crash during a unit leaves the runtime record only in the
   // worktree. If the next session resolves basePath before worktree re-entry,

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

@@ -42,6 +42,7 @@ import {
 } from "./worktree.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import {
   nativeGetCurrentBranch,
@@ -162,6 +163,7 @@ export function syncGsdStateToWorktree(
     "OVERRIDES.md",
     "QUEUE.md",
     "completed-units.json",
+    "metrics.json",
   ];
   for (const f of rootFiles) {
     const src = join(mainGsd, f);
@@ -325,8 +327,9 @@ export function syncWorktreeStateBack(
   // ── 1. Sync root-level .gsd/ files back ──────────────────────────────
   // The worktree is authoritative — complete-milestone updates REQUIREMENTS,
   // PROJECT, etc. These must overwrite main's copies so they survive teardown.
-  // Also includes QUEUE.md and completed-units.json which are written during
-  // milestone closeout and lost on teardown without explicit sync (#1787).
+  // Also includes QUEUE.md, completed-units.json, and metrics.json which are
+  // written during milestone closeout and lost on teardown without explicit sync
+  // (#1787, #2313).
   const rootFiles = [
     "DECISIONS.md",
     "REQUIREMENTS.md",
@@ -335,6 +338,7 @@ export function syncWorktreeStateBack(
     "OVERRIDES.md",
     "QUEUE.md",
     "completed-units.json",
+    "metrics.json",
   ];
   for (const f of rootFiles) {
     const src = join(wtGsd, f);
@@ -697,7 +701,7 @@ export function createAutoWorktree(
   const hookError = runWorktreePostCreateHook(basePath, info.path);
   if (hookError) {
     // Non-fatal — log but don't prevent worktree usage
-    console.error(`[GSD] ${hookError}`);
+    logWarning("reconcile", hookError, { worktree: info.name });
   }
 
   const previousCwd = process.cwd();
@@ -790,10 +794,12 @@ export function teardownAutoWorktree(
   // backslashes (#1436), leaving ~1 GB+ orphaned directories.
   const wtDir = worktreePath(originalBasePath, milestoneId);
   if (existsSync(wtDir)) {
-    console.error(
-      `[GSD] WARNING: Worktree directory still exists after teardown: ${wtDir}\n` +
-        `  This is likely an orphaned directory consuming disk space.\n` +
-        `  Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`,
+    logWarning(
+      "reconcile",
+      `Worktree directory still exists after teardown: ${wtDir}. ` +
+        `This is likely an orphaned directory consuming disk space. ` +
+        `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`,
+      { worktree: milestoneId },
     );
     // Attempt a direct filesystem removal as a fallback
     try {
@@ -1320,9 +1326,9 @@ export function mergeMilestoneToMain(
     }
   }
 
-  // 9b. Auto-create PR if enabled (requires push_branches + push succeeded)
+  // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
   let prCreated = false;
-  if (prefs.auto_pr === true && pushed) {
+  if (prefs.auto_pr === true && !nothingToCommit) {
     const remote = prefs.remote ?? "origin";
     const prTarget = prefs.pr_target_branch ?? mainBranch;
     try {
@@ -1332,9 +1338,9 @@ export function mergeMilestoneToMain(
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf-8",
       });
-      // Create PR via gh CLI
+      // Create PR via gh CLI with explicit --head and --base (#2302)
       execFileSync("gh", [
-        "pr", "create",
+        "pr", "create", "--draft",
         "--base", prTarget,
         "--head", milestoneBranch,
         "--title", `Milestone ${milestoneId} complete`,

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

@@ -250,9 +250,9 @@ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-  if (prefs?.isolation === "none") return false;
-  if (prefs?.isolation === "branch") return false;
-  return true; // default: worktree
+  if (prefs?.isolation === "worktree") return true;
+  // Default is false — worktree isolation requires explicit opt-in
+  return false;
 }
 
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
@@ -610,14 +610,48 @@ export async function stopAuto(
     }
 
     // ── Step 4: Auto-worktree exit ──
+    // When the milestone is complete (has a SUMMARY), merge the worktree branch
+    // back to main so code isn't stranded on the worktree branch (#2317).
+    // For incomplete milestones, preserve the branch for later resumption.
     try {
       if (s.currentMilestoneId) {
         const notifyCtx = ctx
           ? { notify: ctx.ui.notify.bind(ctx.ui) }
           : { notify: () => {} };
-        buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
-          preserveBranch: true,
-        });
+        const resolver = buildResolver();
+
+        // Check if the milestone is complete — SUMMARY file is the authoritative signal.
+        let milestoneComplete = false;
+        try {
+          const summaryPath = resolveMilestoneFile(
+            s.originalBasePath || s.basePath,
+            s.currentMilestoneId,
+            "SUMMARY",
+          );
+          if (!summaryPath) {
+            // Also check in the worktree path (SUMMARY may not be synced yet)
+            const wtSummaryPath = resolveMilestoneFile(
+              s.basePath,
+              s.currentMilestoneId,
+              "SUMMARY",
+            );
+            milestoneComplete = wtSummaryPath !== null;
+          } else {
+            milestoneComplete = true;
+          }
+        } catch {
+          // Non-fatal — fall through to preserveBranch path
+        }
+
+        if (milestoneComplete) {
+          // Milestone is complete — merge worktree branch back to main
+          resolver.mergeAndExit(s.currentMilestoneId, notifyCtx);
+        } else {
+          // Milestone still in progress — preserve branch for later resumption
+          resolver.exitMilestone(s.currentMilestoneId, notifyCtx, {
+            preserveBranch: true,
+          });
+        }
       }
     } catch (e) {
       debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });