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

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

@@ -30,13 +30,18 @@ import {
   buildSliceFileName,
 } from "./paths.js";
 import { parseRoadmap } from "./parsers-legacy.js";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { validateArtifact } from "./schemas/validate.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
 import { hasImplementationArtifacts } from "./auto-recovery.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import {
   buildDiscussMilestonePrompt,
+  buildDiscussProjectPrompt,
+  buildDiscussRequirementsPrompt,
+  buildResearchDecisionPrompt,
+  buildResearchProjectPrompt,
   buildResearchMilestonePrompt,
   buildPlanMilestonePrompt,
   buildResearchSlicePrompt,
@@ -63,6 +68,16 @@ import { getMilestonePipelineVariant } from "./milestone-scope-classifier.js";
 import { EXECUTION_ENTRY_PHASES, hasFinalizedMilestoneContext } from "./uok/plan-v2.js";
 import { isAutoActive } from "./auto.js";
 import { markDepthVerified } from "./bootstrap/write-gate.js";
+import { ensureWorkflowPreferencesCaptured } from "./planning-depth.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
+import {
+  PROJECT_RESEARCH_INFLIGHT_MARKER,
+} from "./project-research-policy.js";
+import {
+  isWorkflowPrefsCaptured,
+  resolveDeepProjectSetupState,
+  type DeepProjectSetupStage,
+} from "./deep-project-setup-policy.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -91,11 +106,19 @@ export interface DispatchContext {
   sessionContextWindow?: number;
   /** Model registry forwarded to the budget engine so it can look up the configured executor model. */
   modelRegistry?: MinimalModelRegistry;
+  /** Session model provider, used for provider-specific effective context windows. */
+  sessionProvider?: string;
 }
 
 type ReassessmentChecker = typeof checkNeedsReassessment;
+type ResearchProjectPromptBuilder = typeof buildResearchProjectPrompt;
 
 let reassessmentChecker: ReassessmentChecker = checkNeedsReassessment;
+let researchProjectPromptBuilder: ResearchProjectPromptBuilder = buildResearchProjectPrompt;
+
+function shouldBypassMilestoneDepthGateInAuto(prefs: GSDPreferences | undefined): boolean {
+  return isAutoActive() && prefs?.planning_depth !== "deep";
+}
 
 export function setReassessmentCheckerForTest(checker: ReassessmentChecker): () => void {
   const previous = reassessmentChecker;
@@ -105,6 +128,14 @@ export function setReassessmentCheckerForTest(checker: ReassessmentChecker): ()
   };
 }
 
+export function setResearchProjectPromptBuilderForTest(builder: ResearchProjectPromptBuilder): () => void {
+  const previous = researchProjectPromptBuilder;
+  researchProjectPromptBuilder = builder;
+  return () => {
+    researchProjectPromptBuilder = previous;
+  };
+}
+
 export interface DispatchRule {
   /** Human-readable name for debugging and test identification */
   name: string;
@@ -112,6 +143,15 @@ export interface DispatchRule {
   match: (ctx: DispatchContext) => Promise<DispatchAction | null>;
 }
 
+export type DeepProjectStage =
+  DeepProjectSetupStage;
+
+export type DeepStageGate =
+  | { status: "not-applicable"; stage: null; reason: string }
+  | { status: "complete"; stage: null; reason: string }
+  | { status: "pending"; stage: DeepProjectStage; reason: string }
+  | { status: "blocked"; stage: DeepProjectStage; reason: string };
+
 async function readUatGateVerdict(
   basePath: string,
   mid: string,
@@ -144,6 +184,25 @@ async function readUatGateVerdict(
   return null;
 }
 
+/**
+ * Deep planning mode: check whether any project-level stage gate
+ * (workflow-preferences, discuss-project, discuss-requirements,
+ * research-decision, research-project) still has work pending.
+ *
+ * Used by the milestone-level discuss rules to yield to project-level
+ * deep-mode rules when the project hasn't finished its setup interview.
+ * Returns false in light mode (or when prefs absent) so the milestone
+ * rules behave exactly as before.
+ */
+export function getDeepStageGate(prefs: GSDPreferences | undefined, basePath: string): DeepStageGate {
+  return resolveDeepProjectSetupState(prefs, basePath);
+}
+
+export function hasPendingDeepStage(prefs: GSDPreferences | undefined, basePath: string): boolean {
+  const gate = getDeepStageGate(prefs, basePath);
+  return gate.status === "pending" || gate.status === "blocked";
+}
+
 function missingSliceStop(mid: string, phase: string): DispatchAction {
   return {
     action: "stop",
@@ -305,19 +364,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
     // Fire BEFORE the execution-entry phase rules so we redispatch to
     // `discuss-milestone` instead of hitting the plan-v2 gate.
     name: "execution-entry phase (no context) → discuss-milestone",
-    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
       if (!EXECUTION_ENTRY_PHASES.has(state.phase)) return null;
+      if (!MILESTONE_ID_RE.test(mid)) return null;
       // Align with the plan-v2 gate's lookup semantics: whitespace-only counts
       // as missing, and an auto worktree may fall back to GSD_PROJECT_ROOT.
       if (hasFinalizedMilestoneContext(basePath, mid)) return null;
-      // H6 fix (#4973): In auto-mode there is no human to answer the
-      // depth-verification ask_user_questions, so the write-gate deadlocks.
-      // Pre-mark the milestone as depth-verified so gsd_summary_save({artifact_type:"CONTEXT"})
-      // is not blocked. Safe ordering: session_switch fires clearDiscussionFlowState()
-      // (register-hooks.ts:106) before before_agent_start, which fires before resolveDispatch
-      // reaches this match fn — so this call always happens after any session-switch reset.
-      // Interactive sessions (isAutoActive()===false) are unaffected.
-      if (isAutoActive()) {
+      // H6 fix (#4973): non-deep auto-mode has no human to answer the
+      // depth-verification question, so pre-marking avoids a write-gate
+      // deadlock. Deep planning is still user-driven even inside auto-mode,
+      // so it must wait for explicit approval instead of taking this bypass.
+      if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
         markDepthVerified(mid, basePath);
       }
       return {
@@ -454,12 +511,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "needs-discussion → discuss-milestone",
-    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
       if (state.phase !== "needs-discussion") return null;
-      // H6 fix (#4973): auto-mark depth-verified so the write-gate does not
-      // deadlock in non-interactive (auto-mode) runs. See ordering note at
-      // "execution-entry phase (no context) → discuss-milestone" above.
-      if (isAutoActive()) {
+      // Deep mode bypass: yield to the project-level deep stage gates
+      // (workflow-prefs, discuss-project, discuss-requirements,
+      // research-decision, research-project) when any of them still have
+      // work pending. Without this guard, the milestone discuss rule wins
+      // before the deep rules ever get a chance to fire.
+      if (hasPendingDeepStage(prefs, basePath)) return null;
+      // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
+      // pre-verify deep planning's user-facing milestone approval gate.
+      if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
         markDepthVerified(mid, basePath);
       }
       return {
@@ -475,17 +537,156 @@ export const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    // Deep mode stage gate: workflow preferences not yet captured.
+    // This used to dispatch an agent unit, but the step is deterministic
+    // defaults-writing. Keep it in-process so missing preferences cannot loop
+    // on the same no-input unit until stuck detection fires.
+    name: "deep: pre-planning (no workflow prefs) → workflow-preferences",
+    match: async ({ state, basePath, prefs }) => {
+      if (prefs?.planning_depth !== "deep") return null;
+      if (state.phase !== "pre-planning" && state.phase !== "needs-discussion") return null;
+      if (isWorkflowPrefsCaptured(basePath)) return null; // already captured — fall through
+      ensureWorkflowPreferencesCaptured(basePath);
+      return null;
+    },
+  },
+  {
+    // Deep mode stage gate: PROJECT.md missing or invalid.
+    // Fires only when planning_depth === "deep" and PROJECT.md is missing/invalid.
+    // Project-level interview must complete before any milestone-level discussion.
+    // Light mode (default) skips this rule entirely — falls through to milestone rules.
+    name: "deep: pre-planning (no PROJECT) → discuss-project",
+    match: async ({ state, basePath, prefs, structuredQuestionsAvailable }) => {
+      if (prefs?.planning_depth !== "deep") return null;
+      if (state.phase !== "pre-planning" && state.phase !== "needs-discussion") return null;
+      const projectPath = join(gsdRoot(basePath), "PROJECT.md");
+      if (existsSync(projectPath) && validateArtifact(projectPath, "project").ok) return null; // PROJECT.md valid — fall through
+      return {
+        action: "dispatch",
+        unitType: "discuss-project",
+        unitId: "PROJECT",
+        prompt: await buildDiscussProjectPrompt(basePath, structuredQuestionsAvailable),
+      };
+    },
+  },
+  {
+    // Deep mode stage gate: REQUIREMENTS.md missing or invalid.
+    // Fires only when planning_depth === "deep", PROJECT.md is valid, and
+    // REQUIREMENTS.md is missing/invalid.
+    // Falls through in light mode or when REQUIREMENTS.md already exists and is valid.
+    name: "deep: pre-planning (no REQUIREMENTS) → discuss-requirements",
+    match: async ({ state, basePath, prefs, structuredQuestionsAvailable }) => {
+      if (prefs?.planning_depth !== "deep") return null;
+      if (state.phase !== "pre-planning" && state.phase !== "needs-discussion") return null;
+      const projectPath = join(gsdRoot(basePath), "PROJECT.md");
+      if (!existsSync(projectPath) || !validateArtifact(projectPath, "project").ok) return null; // PROJECT.md missing/invalid — earlier rule handles
+      const requirementsPath = join(gsdRoot(basePath), "REQUIREMENTS.md");
+      if (existsSync(requirementsPath) && validateArtifact(requirementsPath, "requirements").ok) return null; // REQUIREMENTS.md valid — fall through
+      return {
+        action: "dispatch",
+        unitType: "discuss-requirements",
+        unitId: "REQUIREMENTS",
+        prompt: await buildDiscussRequirementsPrompt(basePath, structuredQuestionsAvailable),
+      };
+    },
+  },
+  {
+    // Deep mode research gate: capture user's research decision.
+    // Fires after discuss-requirements (REQUIREMENTS.md exists) when no decision
+    // marker has been written yet. Asks one yes/no question via ask_user_questions
+    // and writes .gsd/runtime/research-decision.json. Downstream research-project
+    // rule reads the marker to decide whether to fan out 4 parallel research subagents.
+    // Light mode skips entirely.
+    name: "deep: pre-planning (no research decision) → research-decision",
+    match: async ({ state, basePath, prefs, structuredQuestionsAvailable }) => {
+      if (prefs?.planning_depth !== "deep") return null;
+      if (state.phase !== "pre-planning" && state.phase !== "needs-discussion") return null;
+      const gate = resolveDeepProjectSetupState(prefs, basePath);
+      if (gate.status !== "pending" || gate.stage !== "research-decision") return null;
+      return {
+        action: "dispatch",
+        unitType: "research-decision",
+        unitId: "RESEARCH-DECISION",
+        prompt: await buildResearchDecisionPrompt(basePath, structuredQuestionsAvailable),
+      };
+    },
+  },
+  {
+    // Deep mode parallel research.
+    // Fires when planning_depth === "deep", REQUIREMENTS.md exists,
+    // research-decision marker says "research", and any of the 4 project
+    // research files is missing. Spawns one orchestrator session that fans
+    // out 4 parallel subagents (stack, features, architecture, pitfalls).
+    // Skipped entirely when user chose "skip" at the research-decision gate.
+    name: "deep: pre-planning (research approved, files missing) → research-project",
+    match: async ({ state, basePath, prefs, structuredQuestionsAvailable }) => {
+      if (prefs?.planning_depth !== "deep") return null;
+      if (state.phase !== "pre-planning" && state.phase !== "needs-discussion") return null;
+      const gate = resolveDeepProjectSetupState(prefs, basePath);
+      if (gate.status === "blocked" && gate.stage === "project-research") {
+        return {
+          action: "stop" as const,
+          reason: gate.reason,
+          level: "warning" as const,
+        };
+      }
+      if (gate.status !== "pending" || gate.stage !== "project-research") return null;
+      // Idempotency guard: one orchestrator owns the project research fan-out
+      // until guided-research-project.md deletes this marker during closeout.
+      const runtimeDir = join(gsdRoot(basePath), "runtime");
+      const inflightMarkerPath = join(runtimeDir, PROJECT_RESEARCH_INFLIGHT_MARKER);
+      const researchInFlightStop = {
+        action: "stop" as const,
+        reason:
+          "Project research is already in progress. Wait for it to finish, or clear `.gsd/runtime/research-project-inflight` if the prior run crashed.",
+        level: "info" as const,
+      };
+      if (existsSync(inflightMarkerPath)) return researchInFlightStop;
+      mkdirSync(runtimeDir, { recursive: true });
+      try {
+        writeFileSync(
+          inflightMarkerPath,
+          JSON.stringify({ started: new Date().toISOString() }) + "\n",
+          { encoding: "utf-8", flag: "wx" },
+        );
+      } catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "EEXIST") {
+          return researchInFlightStop;
+        }
+        throw err;
+      }
+      try {
+        const prompt = await researchProjectPromptBuilder(basePath, structuredQuestionsAvailable);
+        return {
+          action: "dispatch",
+          unitType: "research-project",
+          unitId: "RESEARCH-PROJECT",
+          prompt,
+        };
+      } catch (err) {
+        try {
+          if (existsSync(inflightMarkerPath)) unlinkSync(inflightMarkerPath);
+        } catch (cleanupErr) {
+          logWarning(
+            "dispatch",
+            `failed to remove research-project in-flight marker after prompt assembly error: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
+          );
+        }
+        throw err;
+      }
+    },
+  },
   {
     name: "pre-planning (no context) → discuss-milestone",
-    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
       if (state.phase !== "pre-planning") return null;
       const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
       const hasContext = !!(contextFile && (await loadFile(contextFile)));
       if (hasContext) return null; // fall through to next rule
-      // H6 fix (#4973): auto-mark depth-verified so the write-gate does not
-      // deadlock in non-interactive (auto-mode) runs. See ordering note at
-      // "execution-entry phase (no context) → discuss-milestone" above.
-      if (isAutoActive()) {
+      // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
+      // pre-verify deep planning's user-facing milestone approval gate.
+      if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
         markDepthVerified(mid, basePath);
       }
       return {
@@ -661,7 +862,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
     // auto-heal without either adding an explicit `setSliceSketchFlag(..., false)`
     // call here or doing so inside the plan-slice tool handler.
     name: "refining → refine-slice",
-    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry, sessionProvider }) => {
       if (state.phase !== "refining") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice.id;
@@ -686,7 +887,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           unitId: `${mid}/${sid}`,
           prompt: await buildPlanSlicePrompt(
             mid, midTitle, sid, sTitle, basePath, undefined,
-            { ...(softScopeHint ? { softScopeHint } : {}), sessionContextWindow, modelRegistry },
+            { ...(softScopeHint ? { softScopeHint } : {}), sessionContextWindow, modelRegistry, sessionProvider },
           ),
         };
       }
@@ -696,14 +897,14 @@ export const DISPATCH_RULES: DispatchRule[] = [
         unitId: `${mid}/${sid}`,
         prompt: await buildRefineSlicePrompt(
           mid, midTitle, sid, sTitle, basePath, undefined,
-          { sessionContextWindow, modelRegistry },
+          { sessionContextWindow, modelRegistry, sessionProvider },
         ),
       };
     },
   },
   {
     name: "planning → plan-slice",
-    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry, session }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry, sessionProvider, session }) => {
       if (state.phase !== "planning") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -732,7 +933,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           sTitle,
           basePath,
           undefined,
-          { sessionContextWindow, modelRegistry, priorPreExecFailure },
+          { sessionContextWindow, modelRegistry, sessionProvider, priorPreExecFailure },
         ),
       };
     },
@@ -793,7 +994,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → reactive-execute (parallel dispatch)",
-    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry }) => {
+    match: async ({ state, mid, midTitle, basePath, prefs, sessionContextWindow, modelRegistry, sessionProvider }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return null; // fall through
 
@@ -896,7 +1097,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
             selected,
             basePath,
             subagentModel,
-            { sessionContextWindow, modelRegistry },
+            { sessionContextWindow, modelRegistry, sessionProvider },
           ),
         };
       } catch (err) {
@@ -908,7 +1109,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task (recover missing task plan → plan-slice)",
-    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry }) => {
+    match: async ({ state, mid, midTitle, basePath, sessionContextWindow, modelRegistry, sessionProvider }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -933,7 +1134,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
             sTitle,
             basePath,
             undefined,
-            { sessionContextWindow, modelRegistry },
+            { sessionContextWindow, modelRegistry, sessionProvider },
           ),
         };
       }
@@ -943,7 +1144,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "executing → execute-task",
-    match: async ({ state, mid, basePath, sessionContextWindow, modelRegistry }) => {
+    match: async ({ state, mid, basePath, sessionContextWindow, modelRegistry, sessionProvider }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
@@ -962,7 +1163,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
           tid,
           tTitle,
           basePath,
-          { sessionContextWindow, modelRegistry },
+          { sessionContextWindow, modelRegistry, sessionProvider },
         ),
       };
     },
@@ -1207,6 +1408,17 @@ import { getRegistry } from "./rule-registry.js";
 export async function resolveDispatch(
   ctx: DispatchContext,
 ): Promise<DispatchAction> {
+  const activeMid = ctx.state.activeMilestone?.id;
+  if (activeMid && ctx.mid !== activeMid) {
+    return {
+      action: "stop",
+      reason:
+        `Dispatch milestone mismatch: context mid "${ctx.mid}" does not match active milestone "${activeMid}". ` +
+        "This usually means a project-level deep setup pseudo-id leaked into milestone dispatch; rerun /gsd auto after setup state is reconciled.",
+      level: "warning",
+    };
+  }
+
   // Delegate to registry when available
   try {
     const registry = getRegistry();

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

@@ -16,6 +16,7 @@ import { deriveState } from "./state.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { isAwaitingUserInput } from "./user-input-boundary.js";
 import {
   resolveSliceFile,
   resolveSlicePath,
@@ -62,7 +63,7 @@ import { validateFileChanges } from "./safety/file-change-validator.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
 import { resolveExpectedArtifactPath as resolveArtifactForContent } from "./auto-artifact-paths.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getIsolationMode, loadEffectiveGSDPreferences } from "./preferences.js";
 import { getSliceTasks } from "./gsd-db.js";
 import { runPreExecutionChecks, type PreExecutionResult } from "./pre-execution-checks.js";
 import { writePreExecutionEvidence, type PreExecutionCheckJSON } from "./verification-evidence.js";
@@ -73,6 +74,11 @@ import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
 import { detectAbandonMilestone } from "./abandon-detect.js";
 import { isDeterministicPolicyError } from "./auto-tool-tracking.js";
+import {
+  clearProjectResearchInflightMarker,
+  finalizeProjectResearchTimeout,
+} from "./project-research-policy.js";
+import { validateArtifact } from "./schemas/validate.js";
 
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
@@ -288,6 +294,7 @@ export function buildStepCompleteMessage(nextState: import("./types.js").GSDStat
 export interface PreVerificationOpts {
   skipSettleDelay?: boolean;
   skipWorktreeSync?: boolean;
+  agentEndMessages?: unknown[];
 }
 
 export interface PostUnitContext {
@@ -301,6 +308,46 @@ export interface PostUnitContext {
   updateProgressWidget: (ctx: ExtensionContext, unitType: string, unitId: string, state: import("./types.js").GSDState) => void;
 }
 
+export const USER_DRIVEN_DEEP_UNITS = new Set([
+  "discuss-project",
+  "discuss-requirements",
+  "discuss-milestone",
+  "research-decision",
+]);
+export { isAwaitingUserInput } from "./user-input-boundary.js";
+
+function artifactValidationKind(unitType: string): "project" | "requirements" | null {
+  if (unitType === "discuss-project") return "project";
+  if (unitType === "discuss-requirements") return "requirements";
+  return null;
+}
+
+function describeArtifactVerificationFailure(unitType: string, unitId: string, basePath: string): string {
+  const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
+  if (!artifactPath) {
+    return `Artifact verification failed: ${unitType} "${unitId}" has no resolvable artifact path.`;
+  }
+  const relPath = relative(basePath, artifactPath);
+  if (!existsSync(artifactPath)) {
+    return `Artifact verification failed: ${relPath} was not found on disk after unit execution.`;
+  }
+
+  const validationKind = artifactValidationKind(unitType);
+  if (validationKind) {
+    const result = validateArtifact(artifactPath, validationKind);
+    if (!result.ok) {
+      const errors = result.errors
+        .slice(0, MAX_NOTIFICATION_DETAILS)
+        .map((error) => `${error.code}: ${error.message}`)
+        .join("; ");
+      return `Artifact verification failed: ${relPath} exists but is invalid${errors ? ` (${errors})` : ""}.`;
+    }
+  }
+
+  const expected = diagnoseExpectedArtifact(unitType, unitId, basePath);
+  return `Artifact verification failed: ${relPath} exists but did not satisfy the ${unitType} completion contract${expected ? ` (${expected})` : ""}.`;
+}
+
 export async function autoCommitUnit(
   basePath: string,
   unitType: string,
@@ -650,7 +697,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         const prefs = prefsResult?.preferences;
         const { getCollapseCadence, mergeSliceToMain } = await import("./slice-cadence.js");
         if (getCollapseCadence(prefs) !== "slice") return;
-        if (prefs?.git?.isolation !== "worktree") return;
+        if (getIsolationMode(s.originalBasePath || s.basePath) !== "worktree") return;
         if (s.isolationDegraded) return;
 
         const projectRoot = s.originalBasePath || s.basePath;
@@ -922,13 +969,49 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         }
       }
 
+      if (s.currentUnit.type === "research-project") {
+        try {
+          clearProjectResearchInflightMarker(s.basePath);
+        } catch (e) {
+          debugLog("postUnit", { phase: "research-project-inflight-cleanup", error: String(e) });
+        }
+      }
+
+      if (!triggerArtifactVerified && s.currentUnit.type === "research-project") {
+        const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`;
+        const outcome = finalizeProjectResearchTimeout(
+          s.basePath,
+          "Project research unit ended before all required dimensions produced durable files.",
+        );
+        s.pendingVerificationRetry = null;
+        s.verificationRetryCount.delete(retryKey);
+        triggerArtifactVerified = verifyExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath);
+        if (triggerArtifactVerified) {
+          invalidateAllCaches();
+          ctx.ui.notify(
+            outcome.kind === "partial-blockers"
+              ? "Project research finished partially; wrote blockers for missing dimensions and advancing without rerunning all scouts."
+              : "Project research artifacts are now terminal.",
+            "warning",
+          );
+        } else {
+          ctx.ui.notify(
+            "Project research produced no usable research files; wrote PROJECT-RESEARCH-BLOCKER.md and continuing fail-closed.",
+            "error",
+          );
+          return "continue";
+        }
+      }
+
       // When artifact verification fails for a unit type that has a known expected
-      // artifact, return "retry" so the caller re-dispatches with failure context
+      // artifact, ask the caller to retry so it re-dispatches with failure context
       // instead of blindly re-dispatching the same unit (#1571).
       // Retries are capped at MAX_ARTIFACT_VERIFICATION_RETRIES to prevent
       // unbounded loops (#2007).
       //
       // Pre-checks short-circuit retry for known-unrecoverable failures:
+      // - User-input waits in deep setup: pause instead of retrying or writing
+      //   placeholders while the agent is waiting for approval.
       // - Deterministic policy rejection (#4973): structural write-gate failure
       //   that will recur on every retry, so write a blocker placeholder.
       // - DB infra failure (#2517): completion tool returned db_unavailable, so
@@ -936,11 +1019,24 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       // - Tool invocation error (#2883/#3595): malformed JSON args or queued
       //   user message — retry will produce the same failure.
       //
-      // #4973: Deterministic policy rejections (e.g. context_write_blocked from the
-      // write-gate) are checked FIRST — before the DB-availability check — because
-      // they are structural gates that will fire on every retry regardless of DB or
-      // model tier. Short-circuit immediately by writing a blocker placeholder.
-      if (!triggerArtifactVerified && s.lastToolInvocationError && isDeterministicPolicyError(s.lastToolInvocationError)) {
+      // User-driven deep setup prompts may ask for approval before the final
+      // root artifact write. If a premature write hits the write gate in the
+      // same turn, the user wait is the meaningful state; pause instead of
+      // writing a placeholder over PROJECT/REQUIREMENTS.
+      if (!triggerArtifactVerified && USER_DRIVEN_DEEP_UNITS.has(s.currentUnit.type) && isAwaitingUserInput(opts?.agentEndMessages)) {
+        debugLog("postUnit", {
+          phase: "artifact-verify-awaiting-user",
+          unitType: s.currentUnit.type,
+          unitId: s.currentUnit.id,
+        });
+        ctx.ui.notify(
+          `${s.currentUnit.type} ${s.currentUnit.id} is waiting for your input — pausing auto-mode instead of retrying the missing artifact.`,
+          "info",
+        );
+        s.lastToolInvocationError = null;
+        await pauseAuto(ctx, pi);
+        return "dispatched";
+      } else if (!triggerArtifactVerified && s.lastToolInvocationError && isDeterministicPolicyError(s.lastToolInvocationError)) {
         const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`;
         debugLog("postUnit", { phase: "deterministic-policy-error-placeholder", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
         const reason = `Deterministic policy rejection for ${s.currentUnit.type} "${s.currentUnit.id}": ${s.lastToolInvocationError}. Retrying cannot resolve this gate — writing blocker placeholder to advance pipeline.`;
@@ -977,11 +1073,16 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         if (hasExpectedArtifact) {
           const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`;
           const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
+          const failureDetails = describeArtifactVerificationFailure(
+            s.currentUnit.type,
+            s.currentUnit.id,
+            s.basePath,
+          );
           if (attempt > MAX_ARTIFACT_VERIFICATION_RETRIES) {
             s.verificationRetryCount.delete(retryKey);
             debugLog("postUnit", { phase: "artifact-verify-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });
             ctx.ui.notify(
-              `Artifact still missing for ${s.currentUnit.type} ${s.currentUnit.id} after ${MAX_ARTIFACT_VERIFICATION_RETRIES} retries — pausing auto-mode`,
+              `${failureDetails} Pausing auto-mode after ${MAX_ARTIFACT_VERIFICATION_RETRIES} retries.`,
               "error",
             );
             await pauseAuto(ctx, pi);
@@ -990,12 +1091,12 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           s.verificationRetryCount.set(retryKey, attempt);
           s.pendingVerificationRetry = {
             unitId: s.currentUnit.id,
-            failureContext: `Artifact verification failed: expected artifact for ${s.currentUnit.type} "${s.currentUnit.id}" was not found on disk after unit execution (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
+            failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
             attempt,
           };
           debugLog("postUnit", { phase: "artifact-verify-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });
           ctx.ui.notify(
-            `Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — retrying (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES})`,
+            `${failureDetails} Retrying (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
             "warning",
           );
           return "retry";