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

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

@@ -287,10 +287,23 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
   }, 15000);
 
   // ── 3. Hard timeout ──
-  s.unitTimeoutHandle = setTimeout(async () => {
+  const hardTimeoutBody = async () => {
     try {
       s.unitTimeoutHandle = null;
       if (!s.active) return;
+      // User-interactive tools (ask_user_questions, secure_env_collect) block
+      // waiting for human input by design. Unlike the idle watchdog (above),
+      // the hard timeout had no interactive exemption, so a long human
+      // deliberation crossing the hard cap would still closeout + recover
+      // (triggerTurn) and abort the turn hosting the elicitation, reintroducing
+      // the self-cancel loop on slow answers (#2676). Re-arm instead of firing
+      // while a human is being asked, mirroring the idle watchdog's
+      // refresh-and-return. Conditional on hasInteractiveToolInFlight(), so a
+      // genuinely hung non-interactive unit still hits the hard cap.
+      if (getInFlightToolCount() > 0 && hasInteractiveToolInFlight()) {
+        s.unitTimeoutHandle = setTimeout(hardTimeoutBody, hardTimeoutMs);
+        return;
+      }
       const expectedCurrentUnit = s.currentUnit
         ? { type: s.currentUnit.type, id: s.currentUnit.id, startedAt: s.currentUnit.startedAt }
         : null;
@@ -323,7 +336,8 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
         logWarning("timer", `notification failed: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-  }, hardTimeoutMs);
+  };
+  s.unitTimeoutHandle = setTimeout(hardTimeoutBody, hardTimeoutMs);
 
   // ── 4. Context-pressure continue-here monitor ──
   if (s.continueHereHandle) {

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -19,6 +19,17 @@ const inFlightTools = new Map<string, InFlightTool>();
  */
 const INTERACTIVE_TOOLS = new Set(["ask_user_questions", "secure_env_collect"]);
 
+/**
+ * Mode-agnostic refcount of in-flight interactive elicitations that are an
+ * active human boundary (the model ASKED via ask_user_questions). Unlike the
+ * `inFlightTools` Map, this is NOT gated by auto-session.active, so it is true
+ * in FOREGROUND (where s.active is false). Kept SEPARATE from inFlightTools so
+ * getInFlightToolCount()/getOldestInFlightToolAgeMs()/hasInteractiveToolInFlight()
+ * and the auto-watchdog accounting are byte-for-byte unchanged. A refcount (not
+ * a boolean) handles nested/back-to-back elicitations in a single turn.
+ */
+let interactiveElicitationDepth = 0;
+
 /**
  * Mark a tool execution as in-flight.
  * Records start time and tool name so the idle watchdog can detect tools
@@ -36,6 +47,29 @@ export function markToolEnd(toolCallId: string): void {
   inFlightTools.delete(toolCallId);
 }
 
+/**
+ * Mark an interactive elicitation (the model asking via ask_user_questions) as
+ * in flight. Ungated by auto-session.active so it is observable in foreground.
+ */
+export function markInteractiveElicitationStart(): void {
+  interactiveElicitationDepth++;
+}
+
+/**
+ * Mark an interactive elicitation as completed. Idempotent below zero.
+ */
+export function markInteractiveElicitationEnd(): void {
+  if (interactiveElicitationDepth > 0) interactiveElicitationDepth--;
+}
+
+/**
+ * Returns true if any interactive elicitation is currently the active human
+ * boundary. True in ALL modes (foreground and auto) while one is in flight.
+ */
+export function isInteractiveElicitationInFlight(): boolean {
+  return interactiveElicitationDepth > 0;
+}
+
 /**
  * Returns the age (ms) of the oldest currently in-flight tool, or 0 if none.
  */
@@ -84,6 +118,7 @@ export function hasInteractiveToolInFlight(): boolean {
  */
 export function clearInFlightTools(): void {
   inFlightTools.clear();
+  interactiveElicitationDepth = 0;
 }
 
 // ─── Tool invocation error classification (#2883) ────────────────────────

package/src/resources/extensions/gsd/auto-unit-tool-scope.ts

@@ -3,32 +3,18 @@ import {
   AUTO_UNIT_SCOPED_TOOLS,
   getForbiddenGsdToolReason,
 } from "./unit-tool-contracts.js";
+import {
+  WORKFLOW_TOOL_ALIAS_PAIRS,
+  canonicalWorkflowSurfaceToolName,
+  isWorkflowSurfaceAliasTool,
+  stripMcpToolPrefix,
+} from "./workflow-tool-surface.js";
 
 export {
   AUTO_UNIT_SCOPED_TOOLS,
   RUN_UAT_BROWSER_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
 
-const WORKFLOW_TOOL_ALIASES: Record<string, string> = {
-  gsd_save_decision: "gsd_decision_save",
-  gsd_update_requirement: "gsd_requirement_update",
-  gsd_save_requirement: "gsd_requirement_save",
-  gsd_save_summary: "gsd_summary_save",
-  gsd_generate_milestone_id: "gsd_milestone_generate_id",
-  gsd_milestone_plan: "gsd_plan_milestone",
-  gsd_slice_plan: "gsd_plan_slice",
-  gsd_task_plan: "gsd_plan_task",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_complete_slice: "gsd_slice_complete",
-  gsd_milestone_complete: "gsd_complete_milestone",
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_complete_task: "gsd_task_complete",
-  gsd_reopen_task: "gsd_task_reopen",
-  gsd_reopen_slice: "gsd_slice_reopen",
-  gsd_reopen_milestone: "gsd_milestone_reopen",
-};
-
 const EXECUTE_TASK_UNIT_TYPES = new Set([
   "execute-task",
   "execute-task-simple",
@@ -55,7 +41,7 @@ const EXTRA_SCOPED_GSD_LIFECYCLE_TOOLS = [
 const SCOPED_GSD_LIFECYCLE_TOOLS = new Set(
   [
     ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
-    ...Object.values(WORKFLOW_TOOL_ALIASES),
+    ...WORKFLOW_TOOL_ALIAS_PAIRS.map(({ canonical }) => canonical),
     ...EXTRA_SCOPED_GSD_LIFECYCLE_TOOLS,
   ]
     .filter((tool) => tool.startsWith("gsd_"))
@@ -72,19 +58,12 @@ type AutoUnitToolScopeResult = {
   displayReason?: string;
 };
 
-function stripMcpToolPrefix(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
-
 export function canonicalWorkflowToolName(toolName: string): string {
-  const base = stripMcpToolPrefix(toolName);
-  return WORKFLOW_TOOL_ALIASES[base] ?? base;
+  return canonicalWorkflowSurfaceToolName(toolName);
 }
 
 export function isWorkflowAliasTool(toolName: string): boolean {
-  return Object.prototype.hasOwnProperty.call(WORKFLOW_TOOL_ALIASES, stripMcpToolPrefix(toolName));
+  return isWorkflowSurfaceAliasTool(toolName);
 }
 
 function hardBlockReason(unitType: string, what: string): string {

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

@@ -16,13 +16,13 @@
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath, resolveMilestoneFile } from "./paths.js";
+import { resolveMilestoneValidationVerdict } from "./milestone-validation-verdict.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getTask, getSliceTasks, getMilestoneSlices } from "./gsd-db.js";
 import type { TaskRow } from "./db-task-slice-rows.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences-types.js";
-import { extractVerdict } from "./verdict-parser.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
 import { parseRoadmap } from "./parsers-legacy.js";
@@ -269,28 +269,27 @@ async function runValidateMilestonePostCheck(
     mid,
     `${mid}-VALIDATION.md`,
   );
-  if (!validationFile) {
+  const validationContent = await loadFile(validationFile);
+  if (validationContent !== null && validationContent.trim() === "") {
     if (await reassessmentInvalidatedValidation()) {
       clearValidationRetry();
       return "continue";
     }
     return setToolFailureRetry(
-      "You must call gsd_validate_milestone to persist the validation results. No VALIDATION.md was created.",
+      "You must call gsd_validate_milestone to persist the validation results. VALIDATION.md exists but is empty.",
     );
   }
 
-  const validationContent = await loadFile(validationFile);
-  if (!validationContent) {
+  const verdict = await resolveMilestoneValidationVerdict(s.basePath, mid);
+  if (!verdict) {
     if (await reassessmentInvalidatedValidation()) {
       clearValidationRetry();
       return "continue";
     }
     return setToolFailureRetry(
-      "You must call gsd_validate_milestone to persist the validation results. VALIDATION.md exists but is empty.",
+      "You must call gsd_validate_milestone to persist the validation results. No VALIDATION.md was created.",
     );
   }
-
-  const verdict = extractVerdict(validationContent);
   if (verdict === "needs-attention") {
     ctx.ui.notify(
       `Milestone ${mid} validation returned verdict=needs-attention. Pausing for human review.`,

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

@@ -28,10 +28,12 @@ import {
   getMilestone,
   getMilestoneSlices,
   getSliceTasks,
-  closeDatabase,
-  openDatabase,
-  getDbPath,
 } from "./gsd-db.js";
+import {
+  closeWorkflowDatabase,
+  getWorkflowDatabasePath,
+  openWorkflowDatabasePath,
+} from "./db-workspace.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { gsdRoot, resolveGsdPathContract } from "./paths.js";
@@ -53,8 +55,11 @@ import {
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
 import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
-import { MergeConflictError, createDraftPR, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import { buildPrEvidence } from "./pr-evidence.js";
+import { MergeConflictError, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
+import {
+  buildPullRequestEvidence,
+  createDraftPullRequestFromEvidence,
+} from "./pull-request-process.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -86,16 +91,14 @@ import {
 } from "./native-git-bridge.js";
 import {
   CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
-  checkCloseoutConsistencyGate,
-  formatCloseoutConsistencyBlock,
 } from "./closeout-consistency-gate.js";
+import {
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
 import { gsdHome } from "./gsd-home.js";
 import { type MilestoneScope, type GsdWorkspace, createWorkspace } from "./workspace.js";
-import {
-  _finalizeProjectionForMergeImpl,
-  _projectRootToWorktreeImpl,
-  _projectWorktreeToRootImpl,
-} from "./worktree-state-projection.js";
+import { WorktreeStateProjection } from "./worktree-state-projection.js";
 
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
@@ -584,7 +587,7 @@ export function syncProjectRootToWorktree(
   worktreePath_: string,
   milestoneId: string | null,
 ): void {
-  _projectRootToWorktreeImpl(projectRoot, worktreePath_, milestoneId);
+  new WorktreeStateProjection().projectRootToWorktreePaths(projectRoot, worktreePath_, milestoneId);
 }
 
 /**
@@ -597,7 +600,7 @@ export function syncStateToProjectRoot(
   projectRoot: string,
   milestoneId: string | null,
 ): void {
-  _projectWorktreeToRootImpl(worktreePath_, projectRoot, milestoneId);
+  new WorktreeStateProjection().projectWorktreeToRootPaths(worktreePath_, projectRoot, milestoneId);
 }
 
 // ─── Resource Staleness ───────────────────────────────────────────────────
@@ -960,7 +963,11 @@ export function syncWorktreeStateBack(
   worktreePath: string,
   milestoneId: string,
 ): { synced: string[] } {
-  return _finalizeProjectionForMergeImpl(mainBasePath, worktreePath, milestoneId);
+  return new WorktreeStateProjection().finalizeProjectionForMergePaths(
+    mainBasePath,
+    worktreePath,
+    milestoneId,
+  );
 }
 export { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 
@@ -1782,10 +1789,10 @@ export function mergeMilestoneToMain(
     const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
     const mainDbPath = contract.projectDb;
     try {
-      const activeDbPath = getDbPath();
+      const activeDbPath = getWorkflowDatabasePath();
       if (activeDbPath && _shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
-        closeDatabase();
-        if (!openDatabase(mainDbPath)) {
+        closeWorkflowDatabase();
+        if (!openWorkflowDatabasePath(mainDbPath)) {
           throw new Error(`cannot open project DB at ${mainDbPath}`);
         }
       }
@@ -1798,9 +1805,9 @@ export function mergeMilestoneToMain(
       throw new GSDError(GSD_GIT_ERROR, `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`);
     }
 
-    const closeoutGate = checkCloseoutConsistencyGate(milestoneId);
-    if (!closeoutGate.ok) {
-      throw new GSDError(GSD_GIT_ERROR, formatCloseoutConsistencyBlock(closeoutGate));
+    const closeoutProof = proveMilestoneCloseout(milestoneId);
+    if (!closeoutProof.ok) {
+      throw new GSDError(GSD_GIT_ERROR, formatCloseoutProofBlock(closeoutProof));
     }
   }
 
@@ -2127,10 +2134,10 @@ export function mergeMilestoneToMain(
   // stashing so Windows releases the handles; reopen after. No-op on
   // POSIX, where advisory locks don't block git.
   const needsDbCycle = process.platform === "win32" && isDbAvailable();
-  const dbPathToReopen = needsDbCycle ? getDbPath() : null;
+  const dbPathToReopen = needsDbCycle ? getWorkflowDatabasePath() : null;
   if (needsDbCycle) {
     try {
-      closeDatabase();
+      closeWorkflowDatabase();
     } catch (err) {
       logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -2180,7 +2187,7 @@ export function mergeMilestoneToMain(
     : nativeMergeSquash(originalBasePath_, milestoneBranch);
   if (needsDbCycle && dbPathToReopen) {
     try {
-      openDatabase(dbPathToReopen);
+      openWorkflowDatabasePath(dbPathToReopen);
     } catch (err) {
       logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -2544,7 +2551,7 @@ export function mergeMilestoneToMain(
             stdio: ["ignore", "pipe", "pipe"],
             encoding: "utf-8",
           });
-          const prEvidence = buildPrEvidence({
+          const prEvidence = buildPullRequestEvidence({
             milestoneId,
             milestoneTitle,
             changeType: "feat",
@@ -2553,7 +2560,7 @@ export function mergeMilestoneToMain(
             rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
             how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
           });
-          const prUrl = createDraftPR(originalBasePath_, milestoneId, prEvidence.title, prEvidence.body, {
+          const prUrl = createDraftPullRequestFromEvidence(originalBasePath_, milestoneId, prEvidence, {
             head: milestoneBranch,
             base: prTarget,
           });

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

@@ -185,6 +185,7 @@ import {
 } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
+import { createMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
 
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
@@ -225,8 +226,8 @@ import {
   getMilestoneSlices,
   getSlice,
   getTask,
-  refreshOpenDatabaseFromDisk,
 } from "./gsd-db.js";
+import { closeWorkflowDatabase } from "./db-workspace.js";
 import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
 import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
@@ -320,7 +321,7 @@ export type {
   UnitRouting,
   StartModel,
 } from "./auto/session.js";
-import { autoSession as s } from "./auto-runtime-state.js";
+import { autoSession as s, getAutoRuntimeSnapshot } from "./auto-runtime-state.js";
 import { gsdHome } from "./gsd-home.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import {
@@ -791,6 +792,7 @@ export { type AutoDashboardData } from "./auto-dashboard.js";
 
 export function getAutoDashboardData(): AutoDashboardData {
   const ledger = getLedger();
+  const runtimeSnapshot = getAutoRuntimeSnapshot();
   const totals = ledger ? getProjectTotals(ledger.units) : null;
   const sessionId = s.cmdCtx?.sessionManager?.getSessionId?.() ?? null;
   const rtkSavings = sessionId && s.basePath
@@ -822,6 +824,7 @@ export function getAutoDashboardData(): AutoDashboardData {
     pendingCaptureCount,
     rtkSavings,
     rtkEnabled,
+    toolSurface: runtimeSnapshot.toolSurface,
   };
 }
 
@@ -1476,12 +1479,17 @@ export async function stopAuto(
   // worktree was active, and whether the current milestone was merged before
   // stopAuto. The unmerged-work warning is only meaningful for real worktrees.
   try {
-    const { emitAutoExit, normalizeAutoExitReason } = await import("./worktree-telemetry.js");
+    const {
+      autoExitReasonForTerminalOutcome,
+      emitAutoExit,
+      normalizeAutoExitReason,
+    } = await import("./worktree-telemetry.js");
     // Normalize the free-form reason to a closed set so the telemetry
     // aggregator buckets stably. Raw detail is preserved in the phases.ts
     // notification and the notify'd error string.
     const rawReason = reason ?? "stop";
-    const normalizedReason = normalizeAutoExitReason(rawReason);
+    const normalizedReason = autoExitReasonForTerminalOutcome(options.terminalOutcome)
+      ?? normalizeAutoExitReason(rawReason);
     const telemetryBase = s.originalBasePath || s.basePath;
     emitAutoExit(telemetryBase, {
       reason: normalizedReason,
@@ -1674,8 +1682,7 @@ export async function stopAuto(
     // ── Step 6: DB cleanup ──
     if (isDbAvailable()) {
       try {
-        const { closeDatabase } = await import("./gsd-db.js");
-        closeDatabase();
+        closeWorkflowDatabase();
       } catch (e) {
         debugLog("db-close-failed", {
           error: e instanceof Error ? e.message : String(e),
@@ -2143,7 +2150,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
   //   C4 (#5627) — GitServiceImpl constructor → gitServiceFactory
   //
   // Final WorktreeLifecycleDeps shape: 3 fields (gitServiceFactory,
-  // worktreeProjection, mergeMilestoneToMain). Down from 18 at slice-7
+  // worktreeProjection, mergeMilestoneToMain transaction runner). Down from 18 at slice-7
   // closure.
   return {
     gitServiceFactory: (basePath: string) => {
@@ -2152,7 +2159,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
       return new GitServiceImpl(basePath, gitConfig);
     },
     worktreeProjection: new WorktreeStateProjection(),
-    mergeMilestoneToMain,
+    mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
   };
 }
 

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

@@ -12,6 +12,7 @@ import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
 import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 import { prepareSaveGateResultArguments } from "../tools/save-gate-result-args.js";
+import { aliasesForWorkflowTool } from "../workflow-tool-surface.js";
 
 async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow-tool-executors.js")> {
   return importWorkflowExecutorsModule();
@@ -53,6 +54,14 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but varies by schema
+function registerWorkflowTool(pi: ExtensionAPI, toolDef: any): void {
+  pi.registerTool(toolDef);
+  for (const alias of aliasesForWorkflowTool(toolDef.name)) {
+    registerAlias(pi, toolDef, alias, toolDef.name);
+  }
+}
+
 function requirementRootWriteGuard(operation: string, basePath: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
   const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(basePath), "REQUIREMENTS");
   if (!guard.block) return null;
@@ -171,8 +180,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(decisionSaveTool);
-  registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
+  registerWorkflowTool(pi, decisionSaveTool);
 
   // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
 
@@ -252,8 +260,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(requirementUpdateTool);
-  registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
+  registerWorkflowTool(pi, requirementUpdateTool);
 
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
@@ -355,8 +362,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(requirementSaveTool);
-  registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
+  registerWorkflowTool(pi, requirementSaveTool);
 
   // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
 
@@ -413,8 +419,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(summarySaveTool);
-  registerAlias(pi, summarySaveTool, "gsd_save_summary", "gsd_summary_save");
+  registerWorkflowTool(pi, summarySaveTool);
 
   // ─── gsd_uat_result_save ─────────────────────────────────────────────────
 
@@ -503,7 +508,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(uatResultSaveTool);
+  registerWorkflowTool(pi, uatResultSaveTool);
 
   // ─── gsd_milestone_generate_id (formerly gsd_generate_milestone_id) ────
 
@@ -592,8 +597,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(milestoneGenerateIdTool);
-  registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
+  registerWorkflowTool(pi, milestoneGenerateIdTool);
 
   // ─── gsd_plan_milestone (gsd_milestone_plan alias) ─────────────────────
 
@@ -664,8 +668,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: planMilestoneExecute,
   };
 
-  pi.registerTool(planMilestoneTool);
-  registerAlias(pi, planMilestoneTool, "gsd_milestone_plan", "gsd_plan_milestone");
+  registerWorkflowTool(pi, planMilestoneTool);
 
   // ─── gsd_plan_slice (gsd_slice_plan alias) ─────────────────────────────
 
@@ -714,8 +717,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: planSliceExecute,
   };
 
-  pi.registerTool(planSliceTool);
-  registerAlias(pi, planSliceTool, "gsd_slice_plan", "gsd_plan_slice");
+  registerWorkflowTool(pi, planSliceTool);
 
   // ─── gsd_plan_task (gsd_task_plan alias) ───────────────────────────────
 
@@ -788,8 +790,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: planTaskExecute,
   };
 
-  pi.registerTool(planTaskTool);
-  registerAlias(pi, planTaskTool, "gsd_task_plan", "gsd_plan_task");
+  registerWorkflowTool(pi, planTaskTool);
 
   // ─── gsd_task_complete (gsd_complete_task alias) ────────────────────────
 
@@ -857,8 +858,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: taskCompleteExecute,
   };
 
-  pi.registerTool(taskCompleteTool);
-  registerAlias(pi, taskCompleteTool, "gsd_complete_task", "gsd_task_complete");
+  registerWorkflowTool(pi, taskCompleteTool);
 
   // ─── gsd_slice_complete (gsd_complete_slice alias) ─────────────────────
 
@@ -943,8 +943,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: sliceCompleteExecute,
   };
 
-  pi.registerTool(sliceCompleteTool);
-  registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete");
+  registerWorkflowTool(pi, sliceCompleteTool);
 
   // ─── gsd_skip_slice (#3477 / #3487) ───────────────────────────────────
 
@@ -1016,7 +1015,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
   };
 
-  pi.registerTool({
+  registerWorkflowTool(pi, {
     name: "gsd_skip_slice",
     label: "Skip Slice",
     description:
@@ -1081,8 +1080,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: milestoneCompleteExecute,
   };
 
-  pi.registerTool(milestoneCompleteTool);
-  registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
+  registerWorkflowTool(pi, milestoneCompleteTool);
 
   // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
 
@@ -1121,8 +1119,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: milestoneValidateExecute,
   };
 
-  pi.registerTool(milestoneValidateTool);
-  registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
+  registerWorkflowTool(pi, milestoneValidateTool);
 
   // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
 
@@ -1172,8 +1169,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: replanSliceExecute,
   };
 
-  pi.registerTool(replanSliceTool);
-  registerAlias(pi, replanSliceTool, "gsd_slice_replan", "gsd_replan_slice");
+  registerWorkflowTool(pi, replanSliceTool);
 
   // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
 
@@ -1231,8 +1227,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: reassessRoadmapExecute,
   };
 
-  pi.registerTool(reassessRoadmapTool);
-  registerAlias(pi, reassessRoadmapTool, "gsd_roadmap_reassess", "gsd_reassess_roadmap");
+  registerWorkflowTool(pi, reassessRoadmapTool);
 
   // ─── gsd_task_reopen (gsd_reopen_task alias) ───────────────────────────
   // Single-writer v3, Stream 3: reversibility tools for closed units.
@@ -1299,8 +1294,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: reopenTaskExecute,
   };
 
-  pi.registerTool(reopenTaskTool);
-  registerAlias(pi, reopenTaskTool, "gsd_reopen_task", "gsd_task_reopen");
+  registerWorkflowTool(pi, reopenTaskTool);
 
   // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
 
@@ -1366,8 +1360,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: reopenSliceExecute,
   };
 
-  pi.registerTool(reopenSliceTool);
-  registerAlias(pi, reopenSliceTool, "gsd_reopen_slice", "gsd_slice_reopen");
+  registerWorkflowTool(pi, reopenSliceTool);
 
   // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
 
@@ -1431,8 +1424,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     execute: reopenMilestoneExecute,
   };
 
-  pi.registerTool(reopenMilestoneTool);
-  registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
+  registerWorkflowTool(pi, reopenMilestoneTool);
 
   // ─── gsd_save_gate_result ──────────────────────────────────────────────
 
@@ -1500,5 +1492,5 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(saveGateResultTool);
+  registerWorkflowTool(pi, saveGateResultTool);
 }