gsd-pi 2.78.1-dev.a7b6e59b7 → 2.78.1-dev.b0759e59b

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,46 @@ 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;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function hasCheckedTaskCompletionOnDisk(base: string, mid: string, sid: string, tid: string): boolean {
+  const tasksDir = resolveTasksDir(base, mid, sid);
+  if (!tasksDir) return false;
+  if (!existsSync(join(tasksDir, `${tid}-SUMMARY.md`))) return false;
+
+  const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
+  if (!planAbs || !existsSync(planAbs)) return false;
+
+  const planContent = readFileSync(planAbs, "utf-8");
+  const cbRe = new RegExp(`^\\s*-\\s+\\[[xX]\\]\\s+\\*\\*${escapeRegExp(tid)}:`, "m");
+  return cbRe.test(planContent);
+}
+
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
  * files) in git history. The primary signal is the branch diff against the
@@ -364,6 +406,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") {
@@ -527,28 +591,23 @@ export function verifyExpectedArtifact(
   }
 
   // execute-task: DB status is authoritative. Fall back to checked-checkbox
-  // detection when the DB is unavailable (unmigrated projects).
+  // detection when the DB is unavailable (unmigrated projects), or when the
+  // disk artifacts already reflect completion but the DB replay is one beat
+  // behind the completion write.
   if (unitType === "execute-task") {
     const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     if (mid && sid && tid) {
       const dbTask = getTask(mid, sid, tid);
       if (dbTask) {
-        // DB available — trust it
-        if (dbTask.status !== "complete" && dbTask.status !== "done") return false;
+        if (dbTask.status !== "complete" && dbTask.status !== "done" && !hasCheckedTaskCompletionOnDisk(base, mid, sid, tid)) {
+          return false;
+        }
       } else if (!isDbAvailable()) {
         // LEGACY: Pre-migration fallback for projects without DB.
         // Require a CHECKED checkbox — a bare heading or unchecked checkbox
         // does not prove gsd_complete_task ran. Summary file on disk alone
         // is not sufficient evidence (could be a rogue write) (#3607).
-        const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
-        if (planAbs && existsSync(planAbs)) {
-          const planContent = readFileSync(planAbs, "utf-8");
-          const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-          const cbRe = new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m");
-          if (!cbRe.test(planContent)) return false;
-        } else {
-          return false; // no plan file → cannot verify
-        }
+        if (!hasCheckedTaskCompletionOnDisk(base, mid, sid, tid)) return false;
       } else {
         // DB available but task row not found — completion tool never ran (#3607)
         return false;
@@ -667,6 +726,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 +736,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

@@ -81,13 +81,12 @@ import {
   readFileSync,
   readdirSync,
   rmSync,
-  statSync,
-  unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
 
 import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
+import { validateDirectory } from "./validate-directory.js";
 import {
   isCustomProvider,
   resolveDefaultSessionModel,
@@ -350,6 +349,12 @@ export async function bootstrapAutoSession(
     buildResolver,
   } = deps;
 
+  const dirCheck = validateDirectory(base);
+  if (dirCheck.severity === "blocked") {
+    ctx.ui.notify(dirCheck.reason!, "error");
+    return false;
+  }
+
   const lockResult = acquireSessionLock(base);
   if (!lockResult.acquired) {
     ctx.ui.notify(lockResult.reason, "error");
@@ -428,6 +433,16 @@ export async function bootstrapAutoSession(
       return releaseLockAndReturn();
     }
 
+    const gitLockFile = join(base, ".git", "index.lock");
+    if (existsSync(gitLockFile)) {
+      ctx.ui.notify(
+        "Git index lock is present at .git/index.lock. Another git process may be running; resolve the lock before starting GSD.",
+        "error",
+      );
+      debugLog("git-index-lock-present-preflight", { path: gitLockFile });
+      return releaseLockAndReturn();
+    }
+
     // Ensure git repo exists *locally* at base.
     // nativeIsRepo() uses `git rev-parse` which traverses up to parent dirs,
     // so a parent repo can make it return true even when base has no .git of
@@ -648,7 +663,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 +754,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 +788,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 +952,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,66 +1017,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");
-        }
-      }
-    } 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.
-    //
-    // Threshold raised from 60s → 5min because a 60s-old lock is not
-    // definitively stale: `git gc --auto` triggered by a heavy commit, NFS
-    // delays, or concurrent worktree writes can hold .git/index.lock for
-    // minutes on large repos. Force-removing a live lock causes the holder
-    // to encounter `fatal: Unable to create '.git/index.lock'` on its next
-    // write, or worse, operate on a partially-written index → corruption
-    // requiring `git fsck`/`git reset` to recover.
-    // (Issue #4980 CRIT-3)
-    try {
-      const gitLockFile = join(base, ".git", "index.lock");
-      if (existsSync(gitLockFile)) {
-        const lockAge = Date.now() - statSync(gitLockFile).mtimeMs;
-        const STALE_GIT_LOCK_THRESHOLD_MS = 5 * 60_000;
-        if (lockAge > STALE_GIT_LOCK_THRESHOLD_MS) {
-          unlinkSync(gitLockFile);
-          ctx.ui.notify(
-            `Removed stale .git/index.lock (age ${Math.round(lockAge / 1000)}s, > 5min threshold).`,
-            "warning",
-          );
-        } else {
-          // Lock present but not yet stale — surface so the user knows why
-          // git ops may be queueing instead of silently waiting.
-          debugLog("git-lock-present-not-stale", {
-            ageMs: lockAge,
-            thresholdMs: STALE_GIT_LOCK_THRESHOLD_MS,
-          });
+    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 (e) {
-      debugLog("git-lock-cleanup-failed", {
-        error: e instanceof Error ? e.message : String(e),
-      });
     }
 
     // Pre-flight: validate milestone queue

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);
 }
-