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

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -77,17 +77,17 @@ function capPreamble(preamble) {
  * Uses the budget engine to compute task count ranges and inline context budgets
  * based on the configured executor model's context window.
  */
-function formatExecutorConstraints(sessionContextWindow, modelRegistry) {
+function formatExecutorConstraints(sessionContextWindow, modelRegistry, sessionProvider) {
     let windowTokens;
     try {
         const prefs = loadEffectiveGSDPreferences();
-        windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow);
+        windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow, sessionProvider);
     }
     catch (e) {
         logWarning("prompt", `resolveExecutorContextWindow failed: ${e.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;
@@ -1136,6 +1136,73 @@ export async function buildDiscussMilestonePrompt(mid, midTitle, base, structure
     }
     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, structuredQuestionsAvailable = "false") {
+    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, structuredQuestionsAvailable = "false") {
+    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, structuredQuestionsAvailable = "false") {
+    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, structuredQuestionsAvailable = "false") {
+    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, structuredQuestionsAvailable = "false") {
+    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, midTitle, base) {
     // #4782 phase 3: research-milestone migrated through the composer.
     // Declared inline order: milestone-context, project, requirements,
@@ -1367,7 +1434,7 @@ export async function buildResearchSlicePrompt(mid, _midTitle, sid, sTitle, base
  * sketch-scope constraint).
  */
 async function renderSlicePrompt(options) {
-    const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {}, sessionContextWindow, modelRegistry, } = options;
+    const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {}, sessionContextWindow, modelRegistry, sessionProvider, } = options;
     const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
     const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
     const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
@@ -1417,7 +1484,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.";
     return loadPrompt(promptTemplate, {
@@ -1474,6 +1541,7 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
         prependBlocks,
         sessionContextWindow: options?.sessionContextWindow,
         modelRegistry: options?.modelRegistry,
+        sessionProvider: options?.sessionProvider,
     });
 }
 /**
@@ -1508,6 +1576,7 @@ export async function buildRefineSlicePrompt(mid, _midTitle, sid, sTitle, base,
         extraVars: { sketchScope },
         sessionContextWindow: options?.sessionContextWindow,
         modelRegistry: options?.modelRegistry,
+        sessionProvider: options?.sessionProvider,
     });
 }
 export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, level) {
@@ -1573,7 +1642,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const overridesSection = formatOverridesSection(activeOverrides);
     // 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`;
     // Truncate carry-forward section when it exceeds 40% of inline context budget.
@@ -2243,6 +2312,7 @@ export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, rea
             carryForwardPaths: depPaths,
             sessionContextWindow: opts?.sessionContextWindow,
             modelRegistry: opts?.modelRegistry,
+            sessionProvider: opts?.sessionProvider,
         });
         const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
         subagentSections.push([

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -25,10 +25,35 @@ import { execFileSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { resolveExpectedArtifactPath, 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 };
 export { classifyMilestoneSummaryContent, } from "./milestone-summary-classifier.js";
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
+function hasCapturedWorkflowPrefs(base) {
+    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) {
+    const decisionPath = resolveExpectedArtifactPath("research-decision", "RESEARCH-DECISION", base);
+    if (!decisionPath || !existsSync(decisionPath))
+        return false;
+    try {
+        const cfg = JSON.parse(readFileSync(decisionPath, "utf-8"));
+        return cfg.decision === "research" || cfg.decision === "skip";
+    }
+    catch {
+        return false;
+    }
+}
+function hasCompleteProjectResearch(base) {
+    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
@@ -296,6 +321,23 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         const content = readFileSync(overridesPath, "utf-8");
         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") {
@@ -599,6 +641,9 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
     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`,
         ``,
@@ -606,7 +651,7 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
         ``,
         `**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/dist/resources/extensions/gsd/auto-start.js

@@ -474,7 +474,17 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             // Clear survivor flag — finalization is done
             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):
@@ -536,7 +546,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // 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();
@@ -568,7 +578,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         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;
@@ -713,10 +723,17 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         ctx.ui.setWidget("gsd-health", undefined);
         const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
         const pendingCount = (state.registry ?? []).filter((m) => m.status !== "complete" && m.status !== "parked").length;
-        const scopeMsg = pendingCount > 1
-            ? `Will loop through ${pendingCount} milestones.`
-            : "Will loop until milestone complete.";
+        const scopeMsg = 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
@@ -749,24 +766,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         updateSessionLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown");
         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/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -7,6 +7,7 @@ import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecover
 import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, writeBlockerPlaceholder, } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
 import { bumpAndResolveSynthetic } from "./auto/resolve.js";
+import { finalizeProjectResearchTimeout } from "./project-research-policy.js";
 export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rctx) {
     // Note on turn epoch: the bump is intentionally NOT unconditional at
     // function entry. Two branches below (the "steering retry" paths) keep
@@ -110,6 +111,23 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         return "paused";
     }
     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/dist/resources/extensions/gsd/auto-timers.js

@@ -16,6 +16,25 @@ import { saveActivityLog } from "./activity-log.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
 import { resolveAgentEndCancelled } from "./auto/resolve.js";
 import { logWarning, logError } from "./workflow-logger.js";
+export const PROJECT_RESEARCH_SOFT_TIMEOUT_MINUTES = 3;
+export const PROJECT_RESEARCH_HARD_TIMEOUT_MINUTES = 5;
+export function resolveUnitSupervisionTimeouts(unitType, supervisor, timeoutScale) {
+    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)
@@ -81,9 +100,10 @@ export function startUnitSupervision(sctx) {
     const timeoutScale = estimateMinutes && estimateMinutes > 0
         ? 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(() => {
         s.wrapupWarningHandle = null;
@@ -233,7 +253,7 @@ export function startUnitSupervision(sctx) {
         clearInterval(s.continueHereHandle);
         s.continueHereHandle = null;
     }
-    const executorContextWindow = resolveExecutorContextWindow(ctx.modelRegistry, prefs, ctx.model?.contextWindow);
+    const executorContextWindow = resolveExecutorContextWindow(ctx.modelRegistry, prefs, ctx.model?.contextWindow, ctx.model?.provider);
     const continueHereThreshold = computeBudgets(executorContextWindow).continueThresholdPercent;
     s.continueHereHandle = setInterval(() => {
         if (!s.active || !s.currentUnit || !s.cmdCtx)

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -7,7 +7,6 @@
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, statSync, 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, isDbAvailable, getMilestone, getMilestoneSlices, closeDatabase, openDatabase, getDbPath, } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -21,10 +20,18 @@ 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, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, } from "./native-git-bridge.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "./gsd-home.js";
 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 ─────────────────────────────────────────────
 /**
  * Root-level .gsd/ state files synced between worktree and project root.
@@ -374,7 +381,7 @@ export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId)
  * doesn't falsely trigger staleness (#804).
  */
 export function readResourceVersion() {
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
+    const agentDir = 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"));
@@ -432,9 +439,9 @@ export function escapeStaleWorktree(base) {
     // 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()).
@@ -466,6 +473,29 @@ export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
         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;
@@ -2076,5 +2106,20 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // 14. Clear module state
     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 };
 }

package/dist/resources/extensions/gsd/auto.js

@@ -38,7 +38,6 @@ import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
 import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { preflightCleanRoot, postflightPopStash } from "./clean-root-preflight.js";
-import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
@@ -82,6 +81,7 @@ import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
 import { autoSession as s } from "./auto-runtime-state.js";
+import { gsdHome } from "./gsd-home.js";
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
 // This file must NOT declare module-level `let` or `var` variables for state.
@@ -178,11 +178,7 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
 }
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath) {
-    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-    if (prefs?.isolation === "worktree")
-        return true;
-    // Default is false — worktree isolation requires explicit opt-in
-    return false;
+    return getIsolationMode(basePath) === "worktree";
 }
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
 /** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
@@ -893,6 +889,19 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
         }
         s.currentUnit = null;
     }
+    // Keep STATE.md aligned with the DB-backed state before releasing pause state.
+    // Without this, an interrupted deep run can leave STATE.md saying "no active
+    // milestone" even after the DB/disk reconciliation has recovered the next unit.
+    if (s.basePath) {
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("pause-rebuild-state-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
     if (lockBase()) {
         releaseSessionLock(lockBase());
         clearLock(lockBase());
@@ -1295,7 +1304,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
         // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
         // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent");
+        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
         const pkgRoot = process.env.GSD_PKG_ROOT;
         const resourceLoaderPath = pkgRoot
             ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,11 +1,12 @@
 import { logWarning } from "../workflow-logger.js";
-import { checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
+import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
 import { resolveModelId } from "../auto-model-selection.js";
+import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
@@ -30,6 +31,14 @@ export const MAX_TRANSIENT_AUTO_RESUMES = 8;
 export function resetTransientRetryState() {
     resetRetryState(retryState);
 }
+function resolveAgentEndBasePath() {
+    try {
+        return resolveProjectRoot(process.cwd());
+    }
+    catch {
+        return undefined;
+    }
+}
 async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -67,6 +76,15 @@ export async function handleAgentEnd(pi, event, ctx) {
     // falsely report files as missing — producing a spurious "ready signal
     // rejected" loop even though the files are on disk.
     clearPathCache();
+    try {
+        if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+            return;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
+    }
     if (checkAutoStartAfterDiscuss()) {
         clearDiscussionFlowState();
         return;