gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

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

@@ -99,16 +99,17 @@ function capPreamble(preamble: string): string {
 function formatExecutorConstraints(
   sessionContextWindow?: number,
   modelRegistry?: MinimalModelRegistry,
+  sessionProvider?: string,
 ): string {
   let windowTokens: number;
   try {
     const prefs = loadEffectiveGSDPreferences();
-    windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow);
+    windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow, sessionProvider);
   } catch (e) {
     logWarning("prompt", `resolveExecutorContextWindow failed: ${(e as Error).message}`);
     // Delegate to the budget engine without prefs (the path that just threw)
     // so DEFAULT_CONTEXT_WINDOW stays the single source of truth.
-    windowTokens = resolveExecutorContextWindow(undefined, undefined, sessionContextWindow);
+    windowTokens = resolveExecutorContextWindow(undefined, undefined, sessionContextWindow, sessionProvider);
   }
   const budgets = computeBudgets(windowTokens);
   const { min, max } = budgets.taskCountRange;
@@ -1287,6 +1288,95 @@ export async function buildDiscussMilestonePrompt(
   return basePrompt;
 }
 
+/**
+ * Build a prompt for the workflow-preferences unit type (deep mode).
+ * Default-writing stage: records high-impact workflow defaults in
+ * .gsd/PREFERENCES.md. Runs ONCE per project, early
+ * in deep-mode bootstrap before discuss-project.
+ */
+export async function buildWorkflowPreferencesPrompt(
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
+  return loadPrompt("guided-workflow-preferences", {
+    workingDirectory: base,
+    structuredQuestionsAvailable,
+  });
+}
+
+/**
+ * Build a prompt for the research-project (parallel) unit type (deep mode).
+ * Orchestrator that spawns 4 parallel Task() calls covering stack, features,
+ * architecture, and pitfalls. Each subagent writes its findings to .gsd/research/.
+ * Fires after research-decision marker says "research" and project research files
+ * are missing. Skipped entirely if user picked "skip".
+ */
+export async function buildResearchProjectPrompt(
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
+  return loadPrompt("guided-research-project", {
+    workingDirectory: base,
+    structuredQuestionsAvailable,
+  });
+}
+
+/**
+ * Build a prompt for the research-decision unit type (deep mode).
+ * Fixed-question stage: asks "research first or skip?" via ask_user_questions
+ * and writes .gsd/runtime/research-decision.json. Fires after discuss-requirements
+ * and before research-project-parallel.
+ */
+export async function buildResearchDecisionPrompt(
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
+  return loadPrompt("guided-research-decision", {
+    workingDirectory: base,
+    structuredQuestionsAvailable,
+  });
+}
+
+/**
+ * Build a prompt for the discuss-project unit type (deep mode).
+ * Project-level interview: produces .gsd/PROJECT.md.
+ * Fires before any milestone-level work when planning_depth === "deep" and
+ * PROJECT.md is missing.
+ */
+export async function buildDiscussProjectPrompt(
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
+  const inlinedTemplates = inlineTemplate("project", "Project");
+
+  return loadPrompt("guided-discuss-project", {
+    workingDirectory: base,
+    inlinedTemplates,
+    structuredQuestionsAvailable,
+    commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
+  });
+}
+
+/**
+ * Build a prompt for the discuss-requirements unit type (deep mode).
+ * Requirements-level interview: produces .gsd/REQUIREMENTS.md using the
+ * structured R### format. Reads PROJECT.md as authoritative context.
+ * Fires when planning_depth === "deep", PROJECT.md exists, and REQUIREMENTS.md is missing.
+ */
+export async function buildDiscussRequirementsPrompt(
+  base: string,
+  structuredQuestionsAvailable = "false",
+): Promise<string> {
+  const inlinedTemplates = inlineTemplate("requirements", "Requirements");
+
+  return loadPrompt("guided-discuss-requirements", {
+    workingDirectory: base,
+    inlinedTemplates,
+    structuredQuestionsAvailable,
+    commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
+  });
+}
+
 export async function buildResearchMilestonePrompt(mid: string, midTitle: string, base: string): Promise<string> {
   // #4782 phase 3: research-milestone migrated through the composer.
   // Declared inline order: milestone-context, project, requirements,
@@ -1538,10 +1628,11 @@ async function renderSlicePrompt(options: {
   extraVars?: Record<string, string>;
   sessionContextWindow?: number;
   modelRegistry?: MinimalModelRegistry;
+  sessionProvider?: string;
 }): Promise<string> {
   const {
     mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {},
-    sessionContextWindow, modelRegistry,
+    sessionContextWindow, modelRegistry, sessionProvider,
   } = options;
 
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
@@ -1594,7 +1685,7 @@ async function renderSlicePrompt(options: {
   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")}`);
-  const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry);
+  const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry, sessionProvider);
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
   const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
 
@@ -1628,6 +1719,7 @@ export async function buildPlanSlicePrompt(
     softScopeHint?: string;
     sessionContextWindow?: number;
     modelRegistry?: MinimalModelRegistry;
+    sessionProvider?: string;
     /** Failure context from a prior pre-exec gate run (#4551). When present, a
      *  "Fix these specific issues" section is appended so the LLM addresses the
      *  exact problems instead of producing an identical plan that fails again. */
@@ -1671,6 +1763,7 @@ export async function buildPlanSlicePrompt(
     prependBlocks,
     sessionContextWindow: options?.sessionContextWindow,
     modelRegistry: options?.modelRegistry,
+    sessionProvider: options?.sessionProvider,
   });
 }
 
@@ -1683,7 +1776,7 @@ export async function buildPlanSlicePrompt(
  */
 export async function buildRefineSlicePrompt(
   mid: string, _midTitle: string, sid: string, sTitle: string, base: string, level?: InlineLevel,
-  options?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry },
+  options?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry; sessionProvider?: string },
 ): Promise<string> {
   // Pull the stored sketch scope from the DB — the hard constraint we plan within.
   let sketchScope = "";
@@ -1712,6 +1805,7 @@ export async function buildRefineSlicePrompt(
     extraVars: { sketchScope },
     sessionContextWindow: options?.sessionContextWindow,
     modelRegistry: options?.modelRegistry,
+    sessionProvider: options?.sessionProvider,
   });
 }
 
@@ -1724,6 +1818,8 @@ export interface ExecuteTaskPromptOptions {
   sessionContextWindow?: number;
   /** Model registry forwarded to the budget engine for executor-model lookup. */
   modelRegistry?: MinimalModelRegistry;
+  /** Session model provider, used for provider-specific effective context windows. */
+  sessionProvider?: string;
 }
 
 export async function buildExecuteTaskPrompt(
@@ -1815,7 +1911,7 @@ export async function buildExecuteTaskPrompt(
 
   // Compute verification budget for the executor's context window (issue #707)
   const prefs = loadEffectiveGSDPreferences();
-  const contextWindow = resolveExecutorContextWindow(opts.modelRegistry, prefs?.preferences, opts.sessionContextWindow);
+  const contextWindow = resolveExecutorContextWindow(opts.modelRegistry, prefs?.preferences, opts.sessionContextWindow, opts.sessionProvider);
   const budgets = computeBudgets(contextWindow);
   const verificationBudget = `~${Math.round(budgets.verificationBudgetChars / 1000)}K chars`;
 
@@ -2498,7 +2594,7 @@ export async function buildReactiveExecutePrompt(
   mid: string, midTitle: string, sid: string, sTitle: string,
   readyTaskIds: string[], base: string,
   subagentModel?: string,
-  opts?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry },
+  opts?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry; sessionProvider?: string },
 ): Promise<string> {
   const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
 
@@ -2544,6 +2640,7 @@ export async function buildReactiveExecutePrompt(
         carryForwardPaths: depPaths,
         sessionContextWindow: opts?.sessionContextWindow,
         modelRegistry: opts?.modelRegistry,
+        sessionProvider: opts?.sessionProvider,
       },
     );
 

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

@@ -55,6 +55,8 @@ import {
   diagnoseExpectedArtifact,
 } from "./auto-artifact-paths.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
+import { validateArtifact } from "./schemas/validate.js";
+import { getProjectResearchStatus } from "./project-research-policy.js";
 
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
@@ -65,6 +67,29 @@ export {
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
+function hasCapturedWorkflowPrefs(base: string): boolean {
+  const prefsPath = resolveExpectedArtifactPath("workflow-preferences", "WORKFLOW-PREFS", base);
+  if (!prefsPath || !existsSync(prefsPath)) return false;
+  const content = readFileSync(prefsPath, "utf-8");
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return !!match && /^workflow_prefs_captured:\s*true\s*$/m.test(match[1]);
+}
+
+function hasValidResearchDecision(base: string): boolean {
+  const decisionPath = resolveExpectedArtifactPath("research-decision", "RESEARCH-DECISION", base);
+  if (!decisionPath || !existsSync(decisionPath)) return false;
+  try {
+    const cfg = JSON.parse(readFileSync(decisionPath, "utf-8")) as Record<string, unknown>;
+    return cfg.decision === "research" || cfg.decision === "skip";
+  } catch {
+    return false;
+  }
+}
+
+function hasCompleteProjectResearch(base: string): boolean {
+  return getProjectResearchStatus(base).complete;
+}
+
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
  * files) in git history. The primary signal is the branch diff against the
@@ -364,6 +389,28 @@ export function verifyExpectedArtifact(
     return !content.includes("**Scope:** active");
   }
 
+  if (unitType === "workflow-preferences") {
+    return hasCapturedWorkflowPrefs(base);
+  }
+
+  if (unitType === "discuss-project") {
+    const projectPath = resolveExpectedArtifactPath(unitType, unitId, base);
+    return !!projectPath && existsSync(projectPath) && validateArtifact(projectPath, "project").ok;
+  }
+
+  if (unitType === "discuss-requirements") {
+    const requirementsPath = resolveExpectedArtifactPath(unitType, unitId, base);
+    return !!requirementsPath && existsSync(requirementsPath) && validateArtifact(requirementsPath, "requirements").ok;
+  }
+
+  if (unitType === "research-decision") {
+    return hasValidResearchDecision(base);
+  }
+
+  if (unitType === "research-project") {
+    return hasCompleteProjectResearch(base);
+  }
+
   // Reactive-execute: verify that each dispatched task's summary exists.
   // The unitId encodes the batch: "{mid}/{sid}/reactive+T02,T03"
   if (unitType === "reactive-execute") {
@@ -667,6 +714,9 @@ export function writeBlockerPlaceholder(
   if (!absPath) return null;
   const dir = dirname(absPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const recoveryLine = unitType === "research-project"
+    ? "This placeholder was written by auto-mode so the project research gate can stop fail-closed."
+    : "This placeholder was written by auto-mode so the pipeline can advance.";
   const content = [
     `# BLOCKER — auto-mode recovery failed`,
     ``,
@@ -674,7 +724,7 @@ export function writeBlockerPlaceholder(
     ``,
     `**Reason**: ${reason}`,
     ``,
-    `This placeholder was written by auto-mode so the pipeline can advance.`,
+    recoveryLine,
     `Review and replace this file before relying on downstream artifacts.`,
   ].join("\n");
   writeFileSync(absPath, content, "utf-8");

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

@@ -648,7 +648,22 @@ export async function bootstrapAutoSession(
       hasSurvivorBranch = false;
     }
 
-    if (!hasSurvivorBranch) {
+    const deepProjectStagePending = !hasSurvivorBranch
+      ? (await import("./auto-dispatch.js")).hasPendingDeepStage(
+          loadEffectiveGSDPreferences(base)?.preferences,
+          base,
+        )
+      : false;
+
+    if (deepProjectStagePending) {
+      // Deep project-level setup runs before the first milestone exists. Let
+      // the auto loop dispatch workflow-preferences / project / requirements
+      // units instead of recursing back through showSmartEntry while this
+      // bootstrap still holds the session lock.
+      s.currentMilestoneId = null;
+    }
+
+    if (!hasSurvivorBranch && !deepProjectStagePending) {
       // No active work — start a new milestone via discuss flow
       if (!state.activeMilestone || state.phase === "complete") {
         // Guard against recursive dialog loop (#1348):
@@ -724,7 +739,7 @@ export async function bootstrapAutoSession(
     }
 
     // Unreachable safety check
-    if (!state.activeMilestone) {
+    if (!state.activeMilestone && !deepProjectStagePending) {
       const { showSmartEntry } = await import("./guided-flow.js");
       await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
       return releaseLockAndReturn();
@@ -758,7 +773,7 @@ export async function bootstrapAutoSession(
     s.resourceVersionOnStart = readResourceVersion();
     s.pendingQuickTasks = [];
     s.currentUnit = null;
-    s.currentMilestoneId = state.activeMilestone?.id ?? null;
+    s.currentMilestoneId = deepProjectStagePending ? null : state.activeMilestone?.id ?? null;
     s.originalModelId = startModelSnapshot?.id ?? ctx.model?.id ?? null;
     s.originalModelProvider = startModelSnapshot?.provider ?? ctx.model?.provider ?? null;
     s.originalThinkingLevel = startThinkingSnapshot ?? null;
@@ -922,11 +937,22 @@ export async function bootstrapAutoSession(
       (m) => m.status !== "complete" && m.status !== "parked",
     ).length;
     const scopeMsg =
-      pendingCount > 1
+      deepProjectStagePending
+        ? "Will run project setup before milestone planning."
+        : pendingCount > 1
         ? `Will loop through ${pendingCount} milestones.`
         : "Will loop until milestone complete.";
     ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
+    const providerReportedWindow = ctx.model?.contextWindow ?? 0;
+    const contextOverride = loadEffectiveGSDPreferences(base)?.preferences.context_window_override;
+    if (providerReportedWindow > 500_000 && contextOverride === undefined) {
+      ctx.ui.notify(
+        `Model reports a ${Math.round(providerReportedWindow / 1000)}K context window. If the provider's real API limit is lower, set context_window_override in .gsd/PREFERENCES.md so wrap-up signals fire before context overflow.`,
+        "warning",
+      );
+    }
+
     // Show dynamic routing status so users know upfront if models will be
     // downgraded for simple tasks (#3962).
     // Use the same effective logic as selectAndApplyModel: check flat-rate
@@ -976,30 +1002,32 @@ export async function bootstrapAutoSession(
     writeLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown");
 
     // Secrets collection gate
-    const mid = state.activeMilestone!.id;
-    try {
-      const manifestStatus = await getManifestStatus(base, mid, s.originalBasePath || base);
-      if (manifestStatus && manifestStatus.pending.length > 0) {
-        const result = await collectSecretsFromManifest(base, mid, ctx);
-        if (
-          result &&
-          result.applied &&
-          result.skipped &&
-          result.existingSkipped
-        ) {
-          ctx.ui.notify(
-            `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
-            "info",
-          );
-        } else {
-          ctx.ui.notify("Secrets collection skipped.", "info");
+    const mid = state.activeMilestone?.id;
+    if (mid) {
+      try {
+        const manifestStatus = await getManifestStatus(base, mid, s.originalBasePath || base);
+        if (manifestStatus && manifestStatus.pending.length > 0) {
+          const result = await collectSecretsFromManifest(base, mid, ctx);
+          if (
+            result &&
+            result.applied &&
+            result.skipped &&
+            result.existingSkipped
+          ) {
+            ctx.ui.notify(
+              `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
+              "info",
+            );
+          } else {
+            ctx.ui.notify("Secrets collection skipped.", "info");
+          }
         }
+      } catch (err) {
+        ctx.ui.notify(
+          `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
+          "warning",
+        );
       }
-    } catch (err) {
-      ctx.ui.notify(
-        `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
-        "warning",
-      );
     }
 
     // Self-heal: remove stale .git/index.lock.

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

@@ -19,6 +19,7 @@ import {
 import { existsSync } from "node:fs";
 
 import { bumpAndResolveSynthetic } from "./auto/resolve.js";
+import { finalizeProjectResearchTimeout } from "./project-research-policy.js";
 
 export interface RecoveryContext {
   basePath: string;
@@ -172,6 +173,27 @@ export async function recoverTimedOutUnit(
 
   const expected = diagnoseExpectedArtifact(unitType, unitId, basePath) ?? "required durable artifact";
 
+  if (unitType === "research-project") {
+    const outcome = finalizeProjectResearchTimeout(
+      basePath,
+      `${reason} timeout recovery finalized project research before all dimensions completed.`,
+    );
+    writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+      phase: outcome.kind === "global-blocker" ? "skipped" : "finalized",
+      recoveryAttempts: recoveryAttempts + 1,
+      lastRecoveryReason: reason,
+    });
+    const message = outcome.kind === "completed"
+      ? `Project research ${reason} timeout: research artifacts are already terminal; advancing.`
+      : outcome.kind === "partial-blockers"
+        ? `Project research ${reason} timeout: wrote blocker files for missing dimensions and advancing with partial research.`
+        : `Project research ${reason} timeout: wrote PROJECT-RESEARCH-BLOCKER.md and stopping fail-closed.`;
+    ctx.ui.notify(message, outcome.kind === "global-blocker" ? "error" : "warning");
+    unitRecoveryCount.delete(recoveryKey);
+    bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
+    return "recovered";
+  }
+
   // Check if the artifact already exists on disk — agent may have written it
   // without signaling completion.
   const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);

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

@@ -10,7 +10,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 type { AutoSupervisorConfig, GSDPreferences } from "./preferences.js";
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
 import {
   getInFlightToolCount,
@@ -40,6 +40,33 @@ export interface SupervisionContext {
   taskEstimate?: string;
 }
 
+export const PROJECT_RESEARCH_SOFT_TIMEOUT_MINUTES = 3;
+export const PROJECT_RESEARCH_HARD_TIMEOUT_MINUTES = 5;
+
+export function resolveUnitSupervisionTimeouts(
+  unitType: string,
+  supervisor: AutoSupervisorConfig,
+  timeoutScale: number,
+): { softTimeoutMs: number; idleTimeoutMs: number; hardTimeoutMs: number } {
+  const softMinutes = supervisor.soft_timeout_minutes ?? 0;
+  const idleMinutes = supervisor.idle_timeout_minutes ?? 0;
+  const hardMinutes = supervisor.hard_timeout_minutes ?? 0;
+
+  if (unitType === "research-project") {
+    return {
+      softTimeoutMs: Math.min(softMinutes, PROJECT_RESEARCH_SOFT_TIMEOUT_MINUTES) * 60 * 1000,
+      idleTimeoutMs: idleMinutes * 60 * 1000,
+      hardTimeoutMs: Math.min(hardMinutes, PROJECT_RESEARCH_HARD_TIMEOUT_MINUTES) * 60 * 1000,
+    };
+  }
+
+  return {
+    softTimeoutMs: softMinutes * 60 * 1000 * timeoutScale,
+    idleTimeoutMs: idleMinutes * 60 * 1000,
+    hardTimeoutMs: hardMinutes * 60 * 1000 * timeoutScale,
+  };
+}
+
 /**
  * Set up all four supervision timers for the current unit:
  * 1. Soft timeout warning (wrapup)
@@ -111,9 +138,14 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
     ? Math.min(MAX_TIMEOUT_SCALE, Math.max(1, estimateMinutes / 10))
     : 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;
+  const supervisionTimeouts = resolveUnitSupervisionTimeouts(
+    unitType,
+    supervisor,
+    timeoutScale,
+  );
+  const softTimeoutMs = supervisionTimeouts.softTimeoutMs;
+  const idleTimeoutMs = supervisionTimeouts.idleTimeoutMs;
+  const hardTimeoutMs = supervisionTimeouts.hardTimeoutMs;
 
   // ── 1. Soft timeout warning ──
   s.wrapupWarningHandle = setTimeout(() => {
@@ -277,6 +309,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
     ctx.modelRegistry as Parameters<typeof resolveExecutorContextWindow>[0],
     prefs as Parameters<typeof resolveExecutorContextWindow>[1],
     ctx.model?.contextWindow,
+    ctx.model?.provider,
   );
   const continueHereThreshold = computeBudgets(executorContextWindow).continueThresholdPercent;
   s.continueHereHandle = setInterval(() => {
@@ -324,4 +357,3 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
     }
   }, 15_000);
 }
-

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

@@ -19,7 +19,6 @@ import {
   lstatSync as lstatSyncFn,
 } from "node:fs";
 import { isAbsolute, join, sep as pathSep } from "node:path";
-import { homedir } from "node:os";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import {
   reconcileWorktreeDb,
@@ -55,6 +54,7 @@ import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } fr
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import {
   nativeGetCurrentBranch,
   nativeDetectMainBranch,
@@ -75,10 +75,17 @@ import {
   nativeIsAncestor,
   nativeMergeAbort,
 } from "./native-git-bridge.js";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
+const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
+  "workflow-preferences-WORKFLOW-PREFS.json",
+  "discuss-project-PROJECT.json",
+  "discuss-requirements-REQUIREMENTS.json",
+  "research-decision-RESEARCH-DECISION.json",
+  "research-project-RESEARCH-PROJECT.json",
+]);
 
 // ─── Shared Constants & Helpers ─────────────────────────────────────────────
 
@@ -478,7 +485,7 @@ export function syncStateToProjectRoot(
  */
 export function readResourceVersion(): string | null {
   const agentDir =
-    process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
+    process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   try {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -541,9 +548,9 @@ export function escapeStaleWorktree(base: string): string {
   // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
   // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
   // resolved through the symlink. Returning ~ would be catastrophic (#1676).
-  const candidateGsd = join(projectRoot, ".gsd").replaceAll("\\", "/");
-  const gsdHomePath = gsdHome.replaceAll("\\", "/");
-  if (candidateGsd === gsdHomePath || candidateGsd.startsWith(gsdHomePath + "/")) {
+  const candidateGsd = normalizeWorktreePathForCompare(join(projectRoot, ".gsd"));
+  const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
+  if (candidateGsd === gsdHomeNorm || candidateGsd.startsWith(gsdHomeNorm + "/")) {
     // Don't chdir to home — return base unchanged.
     // resolveProjectRoot() in worktree.ts has the full git-file-based recovery
     // and will be called by the caller (startAuto → projectRoot()).
@@ -578,6 +585,27 @@ export function cleanStaleRuntimeUnits(
   try {
     for (const file of readdirSync(runtimeUnitsDir)) {
       if (!file.endsWith(".json")) continue;
+      if (LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES.has(file)) {
+        try {
+          unlinkSync(join(runtimeUnitsDir, file));
+          cleaned++;
+        } catch (err) {
+          /* non-fatal */
+          logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        continue;
+      }
+      const staleDiscussMatch = file.match(/^discuss-milestone-(.+)\.json$/);
+      if (staleDiscussMatch && !MILESTONE_ID_RE.test(staleDiscussMatch[1])) {
+        try {
+          unlinkSync(join(runtimeUnitsDir, file));
+          cleaned++;
+        } catch (err) {
+          /* non-fatal */
+          logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        continue;
+      }
       const midMatch = file.match(/(M\d+(?:-[a-z0-9]{6})?)/);
       if (!midMatch) continue;
       if (hasMilestoneSummary(midMatch[1])) {
@@ -2372,5 +2400,20 @@ export function mergeMilestoneToMain(
   originalBase = null;
   nudgeGitBranchCache(previousCwd);
 
+  // 15. Anchor cwd at the project root on success-return. Step 12 removed
+  // the worktree dir; if cwd was inside it, every subsequent process.cwd()
+  // would throw ENOENT and trip auto/run-unit.ts:50's session-failed cancel
+  // path (the de73fb43d regression that closes headless gsd auto). Step 3
+  // already chdir'd here, but defending the success-return contract makes
+  // future maintainers safe against intervening chdir's between step 3 and
+  // here.
+  try {
+    // process.cwd() can throw ENOENT when cwd was removed, so attempt
+    // recovery directly.
+    process.chdir(originalBasePath_);
+  } catch (err) {
+    logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
   return { commitMessage, pushed, prCreated, codeFilesChanged };
 }