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

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

@@ -44,6 +44,8 @@ import {
 import { logWarning } from "./workflow-logger.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { readUnitRuntimeRecord, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
+import { describeMilestoneReadinessPhase } from "./milestone-readiness.js";
+import type { ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 
 const ACTIVE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 
@@ -85,6 +87,8 @@ export interface AutoDashboardData {
   rtkEnabled?: boolean;
   /** Cross-process: another auto-mode session detected via auto.lock (PID, startedAt) */
   remoteSession?: { pid: number; startedAt: string; unitType: string; unitId: string };
+  /** Last typed tool-surface snapshot for active auto-mode scoping/debugging. */
+  toolSurface?: ToolSurfaceSnapshot | null;
 }
 
 export interface CompletionDashboardSnapshot {
@@ -189,6 +193,18 @@ export function unitPhaseLabel(unitType: string): string {
   }
 }
 
+export function formatToolSurfaceSnapshot(snapshot: ToolSurfaceSnapshot | null | undefined): string | null {
+  if (!snapshot) return null;
+  const counts = [
+    `model ${snapshot.modelFacingToolNames.length}`,
+    `registered ${snapshot.registeredToolNames.length}`,
+    `scoped ${snapshot.scopedToolNames.length}`,
+    `presented ${snapshot.presentedToolNames.length}`,
+  ];
+  const label = snapshot.unitType ?? snapshot.phase ?? snapshot.source;
+  return `${label}: ${counts.join(" / ")}`;
+}
+
 function peekNext(unitType: string, state: GSDState): string {
   // Show active hook info in progress display
   const activeHookState = getActiveHook();
@@ -224,12 +240,10 @@ export function describeNextUnit(state: GSDState): { label: string; description:
   const sTitle = state.activeSlice?.title;
   const tid = state.activeTask?.id;
   const tTitle = state.activeTask?.title;
+  const readinessDescription = describeMilestoneReadinessPhase(state.phase);
+  if (readinessDescription) return readinessDescription;
 
   switch (state.phase) {
-    case "needs-discussion":
-      return { label: "Discuss milestone draft", description: "Milestone has a draft context — needs discussion before planning." };
-    case "pre-planning":
-      return { label: "Research & plan milestone", description: "Scout the landscape and create the roadmap." };
     case "planning":
       return { label: `Plan ${sid}: ${sTitle}`, description: "Research and decompose into tasks." };
     case "executing":

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

@@ -112,9 +112,9 @@ import { runTurnGitAction } from "./git-service.js";
 import { parseUnitId } from "./unit-id.js";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
 import {
-  checkCloseoutConsistencyGate,
-  formatCloseoutConsistencyBlock,
-} from "./closeout-consistency-gate.js";
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -153,6 +153,8 @@ export interface DispatchContext {
   sessionProvider?: string;
   /** Active tools in the current session, used for transport preflight checks. */
   activeTools?: string[];
+  /** Registered tools in the current session, used for run-uat tools re-scoped at dispatch. */
+  registeredTools?: string[];
   /** Session model base URL, used for transport preflight checks. */
   sessionBaseUrl?: string;
   /** Session model auth mode, used for transport preflight checks. */
@@ -734,7 +736,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "run-uat (post-completion)",
-    match: async ({ state, mid, basePath, prefs, sessionProvider, sessionAuthMode, activeTools, sessionBaseUrl }) => {
+    match: async ({
+      state,
+      mid,
+      basePath,
+      prefs,
+      sessionProvider,
+      sessionAuthMode,
+      activeTools,
+      registeredTools,
+      sessionBaseUrl,
+    }) => {
       const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs);
       if (!needsRunUat) return null;
       const { sliceId, uatType } = needsRunUat;
@@ -753,6 +765,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const browserToolError = getUatBrowserToolSupportError({
         uatType,
         activeTools,
+        registeredTools,
         milestoneId: mid,
         sliceId,
       });
@@ -1745,11 +1758,11 @@ export const DISPATCH_RULES: DispatchRule[] = [
           };
         }
         if (milestone) {
-          const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-          if (!closeoutGate.ok) {
+          const closeoutProof = proveMilestoneCloseout(mid, { refreshFromDisk: true });
+          if (!closeoutProof.ok) {
             return {
               action: "stop",
-              reason: formatCloseoutConsistencyBlock(closeoutGate),
+              reason: formatCloseoutProofBlock(closeoutProof),
               level: "warning",
             };
           }

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -122,6 +122,14 @@ export function getToolBaselineSnapshot(pi: ExtensionAPI): string[] {
   return [...new Set([...baseline, ...live])];
 }
 
+export function getRegisteredToolSnapshot(pi: ExtensionAPI): string[] {
+  if (typeof pi.getAllTools !== "function") return getToolBaselineSnapshot(pi);
+  const names = pi.getAllTools()
+    .map((tool) => tool.name)
+    .filter((name): name is string => typeof name === "string" && name.length > 0);
+  return [...new Set(names)];
+}
+
 /**
  * Models eligible for the pre-dispatch policy gate. Prefer registry-available
  * models; when that list is empty (common after worktree resume before registry

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

@@ -49,7 +49,8 @@ import { regenerateIfMissing } from "./workflow-projections.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { isDbAvailable, getDbPath, refreshOpenDatabaseFromDisk, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { renderPlanCheckboxes, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
 import { consumeSignal } from "./session-status-io.js";
@@ -1273,9 +1274,9 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
     await new Promise(r => setTimeout(r, 100));
   }
 
-  const dbPath = getDbPath();
+  const dbPath = getWorkflowDatabasePath();
   if (isDbAvailable() && dbPath && dbPath !== ":memory:") {
-    const refreshed = refreshOpenDatabaseFromDisk();
+    const refreshed = refreshWorkflowDatabaseFromDisk();
     if (!refreshed) {
       logWarning("db", "post-unit database refresh failed; derived state may be stale");
     }

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

@@ -36,8 +36,18 @@ 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,
+  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";
@@ -48,6 +58,7 @@ import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-acti
 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 { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 
@@ -287,6 +298,39 @@ function prependContextModeToBlock(
   return `${contextMode}\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 ─────────────────────────────────────────────────────
 
 /**
@@ -1976,6 +2020,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 +2356,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);
@@ -2510,7 +2568,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 +2579,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 +2715,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 +2757,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 +2773,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 +2893,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).

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

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

@@ -66,7 +66,13 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, getAllMilestones, insertMilestone, openDatabase, getDbStatus, updateMilestoneStatus } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getAllMilestones, insertMilestone, updateMilestoneStatus } from "./gsd-db.js";
+import {
+  getWorkflowDatabaseStatus,
+  openExistingWorkflowDatabase,
+  openWorkflowDatabase,
+  resolveProjectRootDbPath,
+} from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { extractVerdict } from "./verdict-parser.js";
@@ -92,7 +98,6 @@ import {
 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,
@@ -150,10 +155,9 @@ export async function openProjectDbIfPresent(basePath: string): Promise<void> {
   const gsdDbPath = resolveProjectRootDbPath(basePath);
   if (!existsSync(gsdDbPath) || isDbAvailable()) return;
 
-  try {
-    openDatabase(gsdDbPath);
-  } catch (err) {
-    logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`);
+  const result = openExistingWorkflowDatabase(basePath);
+  if (!result.ok && result.reason === "open-failed") {
+    logWarning("engine", `gsd-db: failed to open existing database: ${result.error?.message ?? "open failed"}`);
   }
 }
 
@@ -1673,21 +1677,14 @@ export async function bootstrapAutoSession(
 
     // ── DB lifecycle ──
     const gsdDbPath = resolveProjectRootDbPath(s.basePath);
-    const gsdDirPath = join(s.basePath, ".gsd");
-    if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
-      try {
-        const { openDatabase: openDb } = await import("./gsd-db.js");
-        openDb(gsdDbPath);
-      } catch (err) {
-        logError("engine", `failed to initialize project database: ${(err as Error).message}`);
-      }
+    const initialDbOpen = openWorkflowDatabase(s.basePath);
+    if (!initialDbOpen.ok && initialDbOpen.reason === "open-failed") {
+      logError("engine", `failed to initialize project database: ${initialDbOpen.error?.message ?? "open failed"}`);
     }
     if (_shouldAbortBootstrapForUnavailableDbForTest(gsdDbPath, isDbAvailable())) {
-      try {
-        const { openDatabase: openDb } = await import("./gsd-db.js");
-        openDb(gsdDbPath);
-      } catch (err) {
-        logError("engine", `failed to open existing database: ${(err as Error).message}`);
+      const retryDbOpen = openWorkflowDatabase(s.basePath);
+      if (!retryDbOpen.ok && retryDbOpen.reason === "open-failed") {
+        logError("engine", `failed to open existing database: ${retryDbOpen.error?.message ?? "open failed"}`);
       }
     }
 
@@ -1697,7 +1694,7 @@ export async function bootstrapAutoSession(
     // call returns "db_unavailable", triggering artifact-retry which
     // re-dispatches the same task — producing an infinite loop (#2419).
     if (existsSync(gsdDbPath) && !isDbAvailable()) {
-      const dbStatus = getDbStatus();
+      const dbStatus = getWorkflowDatabaseStatus();
       const phaseHint = dbStatus.lastPhase === "open"
         ? "The database file could not be opened"
         : dbStatus.lastPhase === "initSchema"