@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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

@@ -36,8 +36,19 @@ import {
 } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeContextModeInstructions, composeInlinedContext, composeUnitContext, type ArtifactResolver, type ContextModeRenderMode, type ExcerptResolver } from "./unit-context-composer.js";
-import { resolveManifest } from "./unit-context-manifest.js";
+import {
+  composeContextModeInstructions,
+  composeContractedUnitContext,
+  composeInlinedContext,
+  composeToolSurfaceInstructions,
+  composeUnitContext,
+  type ArtifactResolver,
+  type ComposedUnitContextBlock,
+  type ContextModeRenderMode,
+  type ExcerptResolver,
+} from "./unit-context-composer.js";
+import { resolveManifest, type ArtifactKey } from "./unit-context-manifest.js";
+import { compileUnitContextContract, type UnitPromptContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
@@ -47,7 +58,12 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent, type UatType } from "./uat-policy.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
+import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 
@@ -281,10 +297,45 @@ function prependContextModeToBlock(
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
+  const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
   const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-  if (!contextMode) return block;
-  if (!block.trim()) return contextMode;
-  return `${contextMode}\n\n${block}`;
+  const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+  if (!guidance) return block;
+  if (!block.trim()) return guidance;
+  return `${guidance}\n\n${block}`;
+}
+
+function requireUnitPromptContextContract(unitType: string): UnitPromptContextContract {
+  const result = compileUnitContextContract(unitType);
+  if (result.ok) return result.contract;
+  throw new Error(result.detail);
+}
+
+function requireComposedArtifactBlock(
+  blocks: readonly ComposedUnitContextBlock[],
+  unitType: string,
+  key: ArtifactKey,
+): string {
+  const block = blocks.find((item) => item.key === key);
+  if (!block) {
+    throw new Error(`Unit Context Contract for ${unitType} did not compose required artifact ${key}`);
+  }
+  return block.body;
+}
+
+function renderExecuteTaskOnDemandContext(
+  base: string,
+  mid: string,
+  sid: string,
+  artifacts: readonly ArtifactKey[],
+): string {
+  if (!artifacts.includes("slice-research")) return "";
+  const researchPath = relSliceFile(base, mid, sid, "RESEARCH");
+  return [
+    "## On-demand Context",
+    "",
+    `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
+  ].join("\n");
 }
 
 // ─── Executor Constraints ─────────────────────────────────────────────────────
@@ -925,7 +976,7 @@ export async function inlineDecisionsFromDb(
 
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(
   base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
@@ -935,14 +986,28 @@ export async function inlineRequirementsFromDb(
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ milestoneId, sliceId });
+      let requirements = queryRequirements({ milestoneId, sliceId });
+      let broadenedScope = false;
+      if (requirements.length === 0 && sliceId) {
+        requirements = queryRequirements({ milestoneId });
+        broadenedScope = true;
+      }
+      if (requirements.length === 0 && milestoneId) {
+        requirements = queryRequirements({ status: "active" });
+        broadenedScope = true;
+      }
       if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
+        // Use compact format for non-full levels, milestone-scoped calls, and
+        // any cascade stage that broadened past the originally requested scope —
+        // a slice-scoped "full" call that fell through to the project-wide
+        // active fallback must not format those rows as full requirements.
+        const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+        const formatted = useCompact
           ? formatRequirementsCompact(requirements)
           : formatRequirementsForPrompt(requirements);
         return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
       }
+      return null;
     }
   } catch (err) {
     logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1398,6 +1463,40 @@ export async function checkNeedsReassessment(
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(
+  base: string,
+  mid: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  let summaryContent = "";
+  try {
+    const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+    if (summaryPath) {
+      summaryContent = (await loadFile(summaryPath)) ?? "";
+    }
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+
 export async function checkNeedsRunUat(
   base: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
 ): Promise<{ sliceId: string; uatType: UatType } | null> {
@@ -1426,7 +1525,8 @@ export async function checkNeedsRunUat(
             if (assessmentContent && hasVerdict(assessmentContent)) continue;
           }
           if (!shouldDispatchUatForContent(uatContent, prefs)) continue;
-          return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+          const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+          return { sliceId: sid, uatType };
         }
         return null;
       }
@@ -1459,7 +1559,8 @@ export async function checkNeedsRunUat(
       if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
     }
     if (!shouldDispatchUatForContent(uatContentFb, prefs)) continue;
-    return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+    const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+    return { sliceId: uatSid, uatType };
   }
   return null;
 }
@@ -1976,6 +2077,12 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   } else {
     trackPromptContext(contextTelemetry, "knowledge", "skipped", null, "missing");
   }
+  const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+  if (webAppUatGuidance) {
+    pushTracked("web-app-uat", webAppUatGuidance);
+  } else {
+    trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+  }
   pushTracked("templates", inlineTemplate("roadmap", "Roadmap"));
   if (inlineLevel === "full") {
     pushTracked("templates", inlineTemplate("decisions", "Decisions"));
@@ -2306,6 +2413,14 @@ async function renderSlicePrompt(options: {
     trackPromptContext(contextTelemetry, "graph-subgraph", "skipped", null, "missing");
   }
 
+  const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+  if (webAppUatGuidance) {
+    inlined.push(webAppUatGuidance);
+    trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+  } else {
+    trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+  }
+
   const planTemplateInline = level === "minimal" ? inlineCompactTemplate("plan", "Slice Plan") : inlineTemplate("plan", "Slice Plan");
   inlined.push(planTemplateInline);
   trackPromptContext(contextTelemetry, "templates", "inline", planTemplateInline);
@@ -2412,6 +2527,9 @@ export async function buildPlanSlicePrompt(
       `Either (a) add an earlier task that creates X on disk before the task that needs it, ` +
       `or (b) if this task IS the one that creates X, move X from inputs to expected_output. ` +
       `Do NOT put X in a task's expected_output if that task only reads or verifies X — only tasks that actually write X to disk should list it in expected_output.\n` +
+      `- **"[file] X: ... GSD planning artifacts are projections preloaded as context / written by workflow tools"**: ` +
+      `Remove X from the task's inputs, files, and expectedOutput entirely. Planning artifacts (anything under .gsd/, .planning/, or .audits/, or names like M001-CONTEXT.md / S01-PLAN.md) are preloaded as context and written by workflow tools — ` +
+      `do NOT add a task that creates X and do NOT move X to expectedOutput.\n` +
       `- **"[file] X: Task T_early reads X but it's created by task T_late (sequence violation)"**: ` +
       `Either (a) reorder tasks so T_late (the creator) runs before T_early (the reader), ` +
       `or (b) if T_late doesn't actually create X (it only reads/tests it), remove X from T_late's expected_output entirely.\n` +
@@ -2510,7 +2628,7 @@ export async function buildExecuteTaskPrompt(
   const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
   const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
   const taskPlanRelPath = relSlicePath(base, mid, sid) + `/tasks/${tid}-PLAN.md`;
-  const taskPlanInline = taskPlanContent
+  const taskPlanContext = taskPlanContent
     ? [
       "## Inlined Task Plan (authoritative local execution contract)",
       `Source: \`${taskPlanRelPath}\``,
@@ -2521,12 +2639,12 @@ export async function buildExecuteTaskPrompt(
       "## Inlined Task Plan (authoritative local execution contract)",
       `Task plan not found at dispatch time. Read \`${taskPlanRelPath}\` before executing.`,
     ].join("\n");
-  trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanInline, taskPlanContent ? undefined : "missing at dispatch");
+  trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanContext, taskPlanContent ? undefined : "missing at dispatch");
 
   const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN");
   const slicePlanContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
-  const slicePlanExcerpt = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
-  trackPromptContext(contextTelemetry, "slice-plan", slicePlanExcerpt ? "excerpt" : "skipped", slicePlanExcerpt, slicePlanExcerpt ? undefined : "missing");
+  const slicePlanContext = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
+  trackPromptContext(contextTelemetry, "slice-plan", slicePlanContext ? "excerpt" : "skipped", slicePlanContext, slicePlanContext ? undefined : "missing");
 
   // Check for continue file (new naming or legacy)
   const continueFile = resolveSliceFile(base, mid, sid, "CONTINUE");
@@ -2657,6 +2775,37 @@ export async function buildExecuteTaskPrompt(
   }
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates, inlineLevel);
 
+  const contextContract = requireUnitPromptContextContract("execute-task");
+  const contractedContext = await composeContractedUnitContext(contextContract, {
+    base: { unitType: "execute-task", basePath: base, milestoneId: mid, sliceId: sid, taskId: tid },
+    resolveArtifact: async (key) => {
+      switch (key) {
+        case "task-plan":
+          return taskPlanContext;
+        case "slice-plan":
+          return slicePlanContext;
+        case "prior-task-summaries":
+          return finalCarryForward;
+        case "templates":
+          return inlinedTemplates;
+        default:
+          return null;
+      }
+    },
+  });
+  const taskPlanInline = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "task-plan");
+  const slicePlanExcerpt = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "slice-plan");
+  const contractedCarryForward = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "prior-task-summaries");
+  const contractedTemplates = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "templates");
+  const onDemandContext = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  trackPromptContext(
+    contextTelemetry,
+    "slice-research",
+    onDemandContext ? "on-demand" : "skipped",
+    onDemandContext,
+    onDemandContext ? undefined : "not declared by contract",
+  );
+
   const prompt = loadPrompt("execute-task", {
     overridesSection,
     runtimeContext,
@@ -2668,11 +2817,12 @@ export async function buildExecuteTaskPrompt(
     taskPlanPath: taskPlanRelPath,
     taskPlanInline,
     slicePlanExcerpt,
-    carryForwardSection: finalCarryForward,
+    carryForwardSection: contractedCarryForward,
     resumeSection,
     priorTaskLines: priorLines,
+    onDemandContext,
     taskSummaryPath,
-    inlinedTemplates,
+    inlinedTemplates: contractedTemplates,
     verificationBudget,
     gatesToClose,
     skillActivation: buildSkillActivationBlock({
@@ -2683,7 +2833,7 @@ export async function buildExecuteTaskPrompt(
       taskId: tid,
       taskTitle: tTitle,
       taskPlanContent,
-      extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+      extraContext: [taskPlanInline, slicePlanExcerpt, contractedCarryForward, resumeSection],
       unitType: "execute-task",
     }),
   });
@@ -2803,6 +2953,14 @@ export async function buildCompleteSlicePrompt(
     }
   }
 
+  const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+  if (webAppUatGuidance && body) {
+    body = `${webAppUatGuidance}\n\n---\n\n${body}`;
+    trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+  } else {
+    trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, webAppUatGuidance ? "missing composed body" : "not a web app");
+  }
+
   // Overrides section prepends to the top of the inlined context —
   // standard pattern for slice-level builders (until composer v2 lands
   // the prepend contract).
@@ -3456,15 +3614,30 @@ export async function buildRunUatPrompt(
     null,
     cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget",
   );
+  const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+  const uatType = uatPolicy.effectiveType;
+  const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+    ? [
+      "## Runtime harness override",
+      "",
+      "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+      "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+      "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+      "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+      "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+      "",
+    ].join("\n")
+    : "";
   const inlinedContext = prependContextModeToBlock(
     "run-uat",
     base,
-    cappedInlinedContext,
+    runtimeHarnessOverride
+      ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+      : cappedInlinedContext,
   );
   emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-  const uatType = resolveEffectiveUatType(uatContent);
   const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
 
   return loadPrompt("run-uat", {
@@ -3749,18 +3922,22 @@ export async function buildReactiveExecutePrompt(
   const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
 
-  const prompt = loadPrompt("reactive-execute", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
-    readyTaskCount: String(readyTaskIds.length),
-    readyTaskList: readyTaskListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    inlinedTemplates,
-  });
+  const prompt = prependContextModeToBlock(
+    "reactive-execute",
+    base,
+    loadPrompt("reactive-execute", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      graphContext,
+      readyTaskCount: String(readyTaskIds.length),
+      readyTaskList: readyTaskListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+      inlinedTemplates,
+    }),
+  );
   emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
   return prompt;
 }
@@ -3939,17 +4116,21 @@ export async function buildGateEvaluatePrompt(
     ].join("\n"));
   }
 
-  return loadPrompt("gate-evaluate", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
-    gateCount: String(pending.length),
-    gateList: gateListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-  });
+  return prependContextModeToBlock(
+    "gate-evaluate",
+    base,
+    loadPrompt("gate-evaluate", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      slicePlanContent: planContent,
+      gateCount: String(pending.length),
+      gateList: gateListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    }),
+  );
 }
 
 export async function buildRewriteDocsPrompt(

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

@@ -25,15 +25,13 @@ import {
   updateSliceStatus,
   insertSlice,
   getMilestone,
-  getMilestoneSlices,
-  getLatestAssessmentByScope,
   updateMilestoneStatus,
-  refreshOpenDatabaseFromDisk,
   getCompletedMilestoneTaskFileHints,
   getMilestoneCommitAttributionShas,
   recordMilestoneCommitAttribution,
   transaction,
 } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -72,7 +70,10 @@ import { isGsdWorktreePath } from "./worktree-root.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { loadAllCaptures, loadPendingCaptures } from "./captures.js";
-import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
+import {
+  proveMilestoneCloseout,
+  type CloseoutProofFailureReason,
+} from "./milestone-closeout-proof.js";
 
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
@@ -117,6 +118,19 @@ export type ArtifactRecoveryDbRefreshResult =
   | { ok: true }
   | { ok: false; fatal: boolean; message: string; reason: string };
 
+function closeoutProofRecoveryReason(reason: CloseoutProofFailureReason): string {
+  switch (reason) {
+    case "slice-missing":
+      return "complete-milestone-slices-missing";
+    case "summary-artifact-missing":
+      return "complete-milestone-summary-missing";
+    case "summary-artifact-failed":
+      return "complete-milestone-summary-failed";
+    default:
+      return `complete-milestone-${reason}`;
+  }
+}
+
 export function refreshRecoveryDbForArtifact(
   unitType: string,
   unitId: string,
@@ -125,7 +139,7 @@ export function refreshRecoveryDbForArtifact(
   if (unitType !== "plan-slice" && unitType !== "execute-task" && unitType !== "complete-milestone") return { ok: true };
   if (!isDbAvailable()) return { ok: true };
 
-  if (!refreshOpenDatabaseFromDisk()) {
+  if (!refreshWorkflowDatabaseFromDisk()) {
     return {
       ok: false,
       fatal: unitType === "execute-task" || unitType === "complete-milestone",
@@ -156,52 +170,29 @@ export function refreshRecoveryDbForArtifact(
     }
     if (isClosedStatus(milestone.status)) return { ok: true };
 
-    const validation = getLatestAssessmentByScope(mid, "milestone-validation");
-    if (validation?.status !== "pass") {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-validation-not-pass",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but milestone-validation is "${validation?.status ?? "absent"}" in the DB.`,
-      };
-    }
-
-    const slices = getMilestoneSlices(mid);
-    if (slices.length === 0) {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-slices-missing",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but no slices exist in the DB.`,
-      };
-    }
-    const openSlice = slices.find((slice) => !isClosedStatus(slice.status));
-    if (openSlice) {
-      return {
-        ok: false,
-        fatal: true,
-        reason: "complete-milestone-slice-open",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but slice ${openSlice.id} is still "${openSlice.status}" in the DB.`,
-      };
-    }
-    for (const slice of slices) {
-      const openTask = getSliceTasks(mid, slice.id).find((task) => !isClosedStatus(task.status));
-      if (openTask) {
+    const artifactBasePath = resolveArtifactVerificationBase(unitId, basePath);
+    const closeoutProof = proveMilestoneCloseout(mid, {
+      allowOpenMilestone: true,
+      summaryArtifactBasePath: artifactBasePath,
+      implementationEvidence: {
+        basePath,
+        requirement: "present",
+      },
+    });
+    if (!closeoutProof.ok) {
+      if (closeoutProof.reason === "implementation-evidence-missing") {
         return {
           ok: false,
           fatal: true,
-          reason: "complete-milestone-task-open",
-          message: `Stuck recovery found complete-milestone ${unitId} artifacts, but task ${slice.id}/${openTask.id} is still "${openTask.status}" in the DB.`,
+          reason: "complete-milestone-implementation-missing",
+          message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
         };
       }
-    }
-
-    if (hasImplementationArtifacts(basePath, mid) !== "present") {
       return {
         ok: false,
         fatal: true,
-        reason: "complete-milestone-implementation-missing",
-        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but implementation evidence is not present.`,
+        reason: closeoutProofRecoveryReason(closeoutProof.reason),
+        message: `Stuck recovery found complete-milestone ${unitId} artifacts, but ${closeoutProof.message}`,
       };
     }
 
@@ -535,7 +526,7 @@ export function verifyExpectedArtifact(
       try {
         let taskIds: string[] | null = null;
         if (isDbAvailable()) {
-          const refreshed = refreshOpenDatabaseFromDisk();
+          const refreshed = refreshWorkflowDatabaseFromDisk();
           if (refreshed) {
             const tasks = getSliceTasks(mid, sid);
             if (tasks.length > 0) taskIds = tasks.map(t => t.id);
@@ -642,14 +633,23 @@ export function verifyExpectedArtifact(
   // A milestone with only .gsd/ plan files and zero implementation code is
   // not genuinely complete — the LLM wrote plan files but skipped actual work.
   if (unitType === "complete-milestone") {
-    const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
-    if (summaryOutcome === "failure") return false;
     const { milestone: mid } = parseUnitId(unitId);
-    if (mid && isDbAvailable()) {
-      const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-      if (!closeoutGate.ok) return false;
+    if (!mid) return false;
+    const closeoutProof = proveMilestoneCloseout(mid, {
+      refreshFromDisk: true,
+      summaryArtifactBasePath: artifactBase,
+      implementationEvidence: {
+        basePath: base,
+        requirement: "not-absent",
+      },
+    });
+    if (!closeoutProof.ok) {
+      if (!isDbAvailable() && closeoutProof.reason === "db-unavailable") {
+        const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(absPath, "utf-8"));
+        return summaryOutcome !== "failure" && hasImplementationArtifacts(base, mid) !== "absent";
+      }
+      return false;
     }
-    if (hasImplementationArtifacts(base, mid) === "absent") return false;
   }
 
   return true;

package/src/resources/extensions/gsd/auto-runtime-state.ts

@@ -9,8 +9,23 @@ import {
   markToolEnd as markTrackedToolEnd,
   markToolStart as markTrackedToolStart,
 } from "./auto-tool-tracking.js";
+// Re-exported as a pure pass-through. Must stay UNGATED (no autoSession.active
+// argument, unlike markToolStart at the bottom of this file) so it is true in
+// foreground where the foreground approval-gate pause consults it.
+export { isInteractiveElicitationInFlight } from "./auto-tool-tracking.js";
+import {
+  createToolSurfaceSnapshot,
+  type ToolSurfaceSnapshot,
+  type ToolSurfaceSnapshotInput,
+} from "./tool-surface-snapshot.js";
+
+export type {
+  ToolSurfaceSnapshot,
+  ToolSurfaceSnapshotInput,
+} from "./tool-surface-snapshot.js";
 
 export const autoSession = new AutoSession();
+let currentToolSurfaceSnapshot: ToolSurfaceSnapshot | null = null;
 
 export type AutoRuntimeSnapshot = {
   active: boolean;
@@ -20,6 +35,7 @@ export type AutoRuntimeSnapshot = {
   orchestrationPhase?: "idle" | "running" | "paused" | "stopped" | "error";
   orchestrationTransitionCount?: number;
   orchestrationLastTransitionAt?: number;
+  toolSurface: ToolSurfaceSnapshot | null;
 };
 
 export function getAutoRuntimeSnapshot(): AutoRuntimeSnapshot {
@@ -32,9 +48,19 @@ export function getAutoRuntimeSnapshot(): AutoRuntimeSnapshot {
     orchestrationPhase: orchestrationStatus?.phase,
     orchestrationTransitionCount: orchestrationStatus?.transitionCount,
     orchestrationLastTransitionAt: orchestrationStatus?.lastTransitionAt,
+    toolSurface: autoSession.active || autoSession.paused ? currentToolSurfaceSnapshot : null,
   };
 }
 
+export function recordAutoToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  currentToolSurfaceSnapshot = createToolSurfaceSnapshot(input);
+  return currentToolSurfaceSnapshot;
+}
+
+export function clearAutoToolSurfaceSnapshot(): void {
+  currentToolSurfaceSnapshot = null;
+}
+
 export function isAutoActive(): boolean {
   return autoSession.active;
 }