gsd-pi 2.78.1-dev.9d08d820b → 2.78.1-dev.b0759e59b

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])) {
@@ -858,6 +886,22 @@ export function syncWorktreeStateBack(
   return { synced };
 }
 
+function syncCurrentMilestoneStateAfterMerge(
+  mainBasePath: string,
+  worktreePath: string,
+  milestoneId: string,
+): { synced: string[] } {
+  const mainGsd = gsdRoot(mainBasePath);
+  const wtGsd = gsdRoot(worktreePath);
+  const synced: string[] = [];
+
+  if (isSamePath(mainGsd, wtGsd)) return { synced };
+  if (!existsSync(wtGsd) || !existsSync(mainGsd)) return { synced };
+
+  syncMilestoneDir(wtGsd, mainGsd, milestoneId, synced);
+  return { synced };
+}
+
 /**
  * Sync a single milestone directory from worktree to main.
  * Copies milestone-level .md files, slice-level files, and task summaries.
@@ -1245,7 +1289,14 @@ export function createAutoWorktree(
     const integrationBranch =
       readIntegrationBranch(basePath, milestoneId) ?? undefined;
     const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    const startPoint = integrationBranch ?? gitPrefs?.main_branch ?? undefined;
+    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 ?? undefined;
     info = createWorktree(basePath, milestoneId, {
       branch,
       startPoint,
@@ -1425,20 +1476,20 @@ export function teardownAutoWorktree(
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath: string): boolean {
-  const cwd = process.cwd();
-  if (!isGsdWorktreePath(cwd)) return false;
+  const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+  if (!isGsdWorktreePath(targetPath)) return false;
 
   const projectRoot = resolveWorktreeProjectRoot(basePath, originalBase);
-  const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+  const targetProjectRoot = resolveWorktreeProjectRoot(targetPath, originalBase);
   if (
     normalizeWorktreePathForCompare(projectRoot) !==
-    normalizeWorktreePathForCompare(cwdProjectRoot)
+    normalizeWorktreePathForCompare(targetProjectRoot)
   ) {
     return false;
   }
 
   try {
-    const branch = nativeGetCurrentBranch(cwd);
+    const branch = nativeGetCurrentBranch(targetPath);
     return branch.startsWith("milestone/");
   } catch {
     return false;
@@ -1593,7 +1644,10 @@ function autoCommitDirtyState(cwd: string): boolean {
     return result !== null;
   } catch (e) {
     debugLog("autoCommitDirtyState", { error: String(e) });
-    return false;
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Failed to auto-commit dirty worktree state before milestone merge: ${e instanceof Error ? e.message : String(e)}`,
+    );
   }
 }
 
@@ -2194,6 +2248,27 @@ export function mergeMilestoneToMain(
   // 9a-iii. Restore sheltered queued milestone directories (#2505).
   restoreShelter();
 
+  // 9a-iv. Preserve current milestone artifacts that may be untracked in git.
+  // syncWorktreeStateBack intentionally skips the current milestone before the
+  // squash merge to avoid conflicting with the merge content. Once the squash
+  // commit is complete, copy those files back so summaries, validation, and
+  // task outputs survive worktree teardown in external/.gitignored .gsd setups.
+  try {
+    const { synced } = syncCurrentMilestoneStateAfterMerge(
+      originalBasePath_,
+      worktreeCwd,
+      milestoneId,
+    );
+    if (synced.length > 0) {
+      debugLog("mergeMilestoneToMain", {
+        phase: "current-milestone-sync-after-merge",
+        synced: synced.length,
+      });
+    }
+  } catch (err) {
+    logWarning("worktree", `current milestone sync after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
   // 9b. Safety check (#1792): if nothing was committed, verify the milestone
   // work is already on the integration branch before allowing teardown.
   // Compare only non-.gsd/ paths — .gsd/ state files diverge normally and
@@ -2260,7 +2335,7 @@ export function mergeMilestoneToMain(
 
   // 10. Auto-push if enabled
   let pushed = false;
-  if (prefs.auto_push === true && !nothingToCommit) {
+  if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
     const remote = prefs.remote ?? "origin";
     try {
       execFileSync("git", ["push", remote, mainBranch], {
@@ -2311,9 +2386,10 @@ export function mergeMilestoneToMain(
   //     through when the code is genuinely already on the integration branch.
 
   // 11a. Pre-teardown safety net (#1853): if the worktree still has uncommitted
-  // changes (e.g. nativeHasChanges cache returned stale false, or auto-commit
-  // silently failed), force one final commit so code is not destroyed by
-  // `git worktree remove --force`.
+  // changes (e.g. nativeHasChanges cache returned stale false), abort teardown.
+  // Committing here would be too late: the squash merge to the integration
+  // branch already happened, so a new milestone-branch commit would not be
+  // included and branch deletion could drop the only ref to that work.
   //
   // Guard: only run when worktreeCwd is on the milestone branch (#2929).
   // In parallel mode or branch-mode merges, worktreeCwd may be the project
@@ -2332,17 +2408,17 @@ export function mergeMilestoneToMain(
       try {
         const dirtyCheck = nativeWorkingTreeStatus(worktreeCwd);
         if (dirtyCheck) {
-          debugLog("mergeMilestoneToMain", {
-            phase: "pre-teardown-dirty",
-            worktreeCwd,
-            status: dirtyCheck.slice(0, 200),
-          });
-          nativeAddAllWithExclusions(worktreeCwd, RUNTIME_EXCLUSION_PATHS);
-          nativeCommit(worktreeCwd, "chore: pre-teardown auto-commit of uncommitted worktree changes");
+          process.chdir(previousCwd);
+          throw new GSDError(
+            GSD_GIT_ERROR,
+            `Milestone worktree still has uncommitted changes after squash merge. ` +
+              `Aborting teardown to preserve ${milestoneBranch}. Status:\n${dirtyCheck}`,
+          );
         }
       } catch (e) {
+        if (e instanceof GSDError) throw e;
         debugLog("mergeMilestoneToMain", {
-          phase: "pre-teardown-commit-error",
+          phase: "pre-teardown-dirty-check-error",
           error: String(e),
         });
       }
@@ -2372,5 +2448,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 };
 }

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

@@ -128,7 +128,6 @@ import {
 } from "./metrics.js";
 import { setLogBasePath, logWarning, logError } 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";
@@ -217,9 +216,13 @@ import {
 } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop } from "./auto/loop.js";
+import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto/resolve.js";
+import type { LoopDeps } from "./auto/loop-deps.js";
+import type { ErrorContext } from "./auto/types.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
+import { validateDirectory } from "./validate-directory.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -250,6 +253,7 @@ export type {
   StartModel,
 } 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).
@@ -373,10 +377,7 @@ export function startAutoDetached(
 
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath?: string): boolean {
-  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 */
@@ -1167,8 +1168,7 @@ export async function pauseAuto(
       milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-    mkdirSync(runtimeDir, { recursive: true });
-    writeFileSync(
+    atomicWriteSync(
       join(runtimeDir, "paused-session.json"),
       JSON.stringify(pausedMeta, null, 2),
       "utf-8",
@@ -1189,6 +1189,19 @@ export async function pauseAuto(
     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());
@@ -1432,6 +1445,12 @@ export async function startAuto(
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
 
+  const dirCheck = validateDirectory(base);
+  if (dirCheck.severity === "blocked") {
+    ctx.ui.notify(dirCheck.reason!, "error");
+    return;
+  }
+
   // Heal .gsd.migrating before any branching — covers both fresh-start and
   // resume paths (#4416). The matching call in auto-start.ts covers the
   // bootstrap-only path; this call ensures the resume path is also protected.
@@ -1651,7 +1670,7 @@ export async function startAuto(
     // 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
@@ -1864,16 +1883,21 @@ export async function dispatchHookUnit(
   hookModel: string | undefined,
   targetBasePath: string,
 ): Promise<boolean> {
+  const wasActive = s.active;
+  const previousBasePath = s.basePath;
+  const previousCurrentUnit = s.currentUnit ? { ...s.currentUnit } : null;
+
   if (!s.active) {
     s.active = true;
     s.stepMode = true;
     s.cmdCtx = ctx as ExtensionCommandContext;
-    s.basePath = targetBasePath;
     s.autoStartTime = Date.now();
     s.currentUnit = null;
     s.pendingQuickTasks = [];
   }
 
+  s.basePath = targetBasePath;
+
   const hookUnitType = `hook/${hookName}`;
   const hookStartedAt = Date.now();
 
@@ -1883,6 +1907,23 @@ export async function dispatchHookUnit(
     startedAt: hookStartedAt,
   };
 
+  // Ensure cwd matches basePath BEFORE newSession() captures it (#1389).
+  // newSession() snapshots process.cwd() during construction; chdir-ing
+  // afterward leaves the session rooted to whatever cwd was when the call
+  // was made. Must be synchronous — no awaits between chdir and newSession.
+  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch (err) {
+    const msg = `Failed to chdir before hook newSession (basePath: ${s.basePath}): ${err instanceof Error ? err.message : String(err)}`;
+    logWarning("engine", msg, { file: "auto.ts", basePath: s.basePath, error: err instanceof Error ? err.message : String(err) });
+    ctx.ui.notify(`${msg}. Cancelling hook dispatch to avoid running in the wrong directory.`, "error");
+    if (wasActive) {
+      s.basePath = previousBasePath;
+      s.currentUnit = previousCurrentUnit;
+    } else {
+      s.reset();
+    }
+    return false;
+  }
+
   const result = await s.cmdCtx!.newSession();
   if (result.cancelled) {
     await stopAuto(ctx, pi);
@@ -1939,11 +1980,6 @@ export async function dispatchHookUnit(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
 
-  // Ensure cwd matches basePath before hook dispatch (#1389)
-  try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch (err) {
-    logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-  }
-
   debugLog("dispatchHookUnit", {
     phase: "send-message",
     promptLength: hookPrompt.length,

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
 import {
+  checkDeepProjectSetupAfterTurn,
   checkAutoStartAfterDiscuss,
   maybeHandleReadyPhraseWithoutFiles,
   maybeHandleEmptyIntentTurn,
@@ -11,8 +12,9 @@ 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 { isSessionSwitchInFlight, resolveAgentEnd } from "../auto/resolve.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 {
@@ -46,6 +48,14 @@ export function resetTransientRetryState(): void {
   resetRetryState(retryState);
 }
 
+function resolveAgentEndBasePath(): string | undefined {
+  try {
+    return resolveProjectRoot(process.cwd());
+  } catch {
+    return undefined;
+  }
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -95,6 +105,15 @@ export async function handleAgentEnd(
   // 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;

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -4,6 +4,7 @@ import { Text } from "@gsd/pi-tui";
 
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
@@ -26,6 +27,16 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+function requirementRootWriteGuard(operation: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
+  const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+  if (!guard.block) return null;
+  return {
+    content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
+    details: { operation, error: "root_artifact_write_blocked" },
+    isError: true,
+  };
+}
+
 /**
  * Read a tool result's structured payload, accommodating MCP's `details` →
  * `structuredContent` rename (#4472, #4477). In-process executions still
@@ -130,6 +141,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
 
   const requirementUpdateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("update_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -208,6 +221,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
   const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("save_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -253,13 +268,28 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Requirement IDs are auto-assigned — never provide an ID manually.",
     promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
     promptGuidelines: [
-      "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+      "Use gsd_requirement_save when recording a new capability, quality attribute, constraint, or anti-feature requirement.",
+      "Use one of these classes: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, anti-feature.",
       "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
       "class, description, why, and source are required. All other fields are optional.",
       "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
     ],
     parameters: Type.Object({
-      class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+      class: StringEnum([
+        "core-capability",
+        "primary-user-loop",
+        "launchability",
+        "continuity",
+        "failure-visibility",
+        "integration",
+        "quality-attribute",
+        "operability",
+        "admin/support",
+        "compliance/security",
+        "differentiator",
+        "constraint",
+        "anti-feature",
+      ], { description: "Requirement class" }),
       description: Type.String({ description: "Short description of the requirement" }),
       why: Type.String({ description: "Why this requirement matters" }),
       source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
@@ -305,17 +335,18 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Computes the file path from milestone/slice/task IDs automatically.",
     promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
     promptGuidelines: [
-      "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).",
-      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+      "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT).",
+      "milestone_id is required for milestone/slice/task artifacts. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT.",
       "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.",
+      "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
+      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
       "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
     ],
     parameters: Type.Object({
-      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
       slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
       task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }),
+      artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
       content: Type.String({ description: "The full markdown content of the artifact" }),
     }),
     execute: summarySaveExecute,