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

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

@@ -81,6 +81,7 @@ import {
   resolveAutoSupervisorConfig,
   loadEffectiveGSDPreferences,
   getIsolationMode,
+  resolveEffectiveUnitIsolationMode,
 } from "./preferences.js";
 import { playNotificationBell, sendDesktopNotification } from "./notifications.js";
 import type { GSDPreferences } from "./preferences.js";
@@ -185,6 +186,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 +227,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 +322,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 {
@@ -329,6 +331,11 @@ import {
 } from "./db/auto-workers.js";
 import { releaseMilestoneLease } from "./db/milestone-leases.js";
 import { normalizeRealPath } from "./paths.js";
+import {
+  formatStopNoticePrefix,
+  isBlockedStopReason,
+  stopNoticeDisplayReason,
+} from "./stop-notice.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -353,19 +360,7 @@ export function formatAutoStopNotification(prefix: string, totals: { cost: numbe
   ].join("\n");
 }
 
-function isBlockedStopReason(reason?: string | null): boolean {
-  return /^Blocked:\s*/i.test(reason ?? "");
-}
-
-function formatAutoStopDisplayReason(reason?: string | null): string {
-  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
-}
-
-export function formatAutoStopNotificationPrefix(reason?: string | null): string {
-  const displayReason = formatAutoStopDisplayReason(reason);
-  const prefix = isBlockedStopReason(reason) ? "Auto-mode blocked" : "Auto-mode stopped";
-  return displayReason ? `${prefix} — ${displayReason}` : prefix;
-}
+export { formatStopNoticePrefix as formatAutoStopNotificationPrefix } from "./stop-notice.js";
 
 function clearSessionModelOverrideForCommandSession(ctx?: ExtensionContext | null): void {
   const sessionId =
@@ -633,22 +628,24 @@ export function shouldUseWorktreeIsolation(basePath?: string): boolean {
 
 type AutoIsolationMode = ReturnType<typeof getIsolationMode>;
 
-function resolveEffectiveUnitIsolationMode(
-  configuredMode: AutoIsolationMode,
-  isolationDegraded: boolean,
-): AutoIsolationMode {
-  return configuredMode === "worktree" && isolationDegraded ? "branch" : configuredMode;
-}
-
 export function _resolveEffectiveUnitIsolationModeForTest(
   configuredMode: AutoIsolationMode,
   isolationDegraded: boolean,
+  strandedRecoveryIsolationMode: "worktree" | "branch" | null = null,
 ): AutoIsolationMode {
-  return resolveEffectiveUnitIsolationMode(configuredMode, isolationDegraded);
+  return resolveEffectiveUnitIsolationMode(
+    configuredMode,
+    isolationDegraded,
+    strandedRecoveryIsolationMode,
+  );
 }
 
 function getEffectiveUnitIsolationMode(basePath: string): AutoIsolationMode {
-  return resolveEffectiveUnitIsolationMode(getIsolationMode(basePath), s.isolationDegraded);
+  return resolveEffectiveUnitIsolationMode(
+    getIsolationMode(basePath),
+    s.isolationDegraded,
+    s.strandedRecoveryIsolationMode,
+  );
 }
 
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
@@ -791,6 +788,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 +820,7 @@ export function getAutoDashboardData(): AutoDashboardData {
     pendingCaptureCount,
     rtkSavings,
     rtkEnabled,
+    toolSurface: runtimeSnapshot.toolSurface,
   };
 }
 
@@ -1459,8 +1458,8 @@ export async function stopAuto(
 ): Promise<void> {
   if (!s.active && !s.paused) return;
   const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
-  const stopNotificationPrefix = formatAutoStopNotificationPrefix(reason);
-  const displayReason = formatAutoStopDisplayReason(reason);
+  const stopNotificationPrefix = formatStopNoticePrefix(reason);
+  const displayReason = stopNoticeDisplayReason(reason);
   const isHeadlessStop = process.env.GSD_HEADLESS === "1";
   const completionStopRequested = Boolean(options.completionWidget);
   const preserveCloseoutTranscript = !isHeadlessStop && (
@@ -1476,12 +1475,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 +1678,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 +2146,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 +2155,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
       return new GitServiceImpl(basePath, gitConfig);
     },
     worktreeProjection: new WorktreeStateProjection(),
-    mergeMilestoneToMain,
+    mergeMilestoneToMain: createMilestoneMergeTransaction(mergeMilestoneToMain),
   };
 }
 

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -43,10 +43,8 @@ import {
 } from "../error-classifier.js";
 import { blockModel, isModelBlocked } from "../blocked-models.js";
 import { getProjectGSDPreferencesPath } from "../preferences.js";
-import {
-  formatProviderErrorGuidance,
-  resolveProviderErrorGuidance,
-} from "../provider-error-guidance.js";
+import { resolveProviderErrorGuidance } from "../provider-error-guidance.js";
+import { formatGuidance } from "../guidance.js";
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
@@ -627,7 +625,7 @@ export async function handleAgentEnd(
         preferencesPath: dash.basePath ? getProjectGSDPreferencesPath(dash.basePath) : undefined,
         hasConfiguredFallbacks: (modelConfig?.fallbacks.length ?? 0) > 0,
       });
-      const guidanceText = formatProviderErrorGuidance(guidance);
+      const guidanceText = formatGuidance(guidance);
 
       await pauseForProviderModelRejection(ctx, pi, {
         errorDetail,

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

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

@@ -2,16 +2,17 @@
 // File Purpose: Registers workspace-aware dynamic filesystem and shell tools.
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
-import { setLogBasePath, logWarning } from "../workflow-logger.js";
-import { resolveGsdPathContract } from "../paths.js";
+import { logWarning } from "../workflow-logger.js";
+import { openWorkflowDatabase } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { worktreesDirs } from "../worktree-placement.js";
 
 export function safeWorkspaceCwd(): string {
   try {
@@ -46,13 +47,15 @@ export function resolveWorkflowToolBasePath(
     const worktree = getAutoWorktreePath(projectRoot, milestoneId);
     if (worktree) return worktree;
   } else {
-    const worktreesDir = join(projectRoot, ".gsd", "worktrees");
-    if (existsSync(worktreesDir)) {
+    const live: string[] = [];
+    for (const worktreesDir of worktreesDirs(projectRoot)) {
+      if (!existsSync(worktreesDir)) continue;
       try {
-        const live = readdirSync(worktreesDir)
-          .map((name) => join(worktreesDir, name))
-          .filter((p) => existsSync(join(p, ".git")));
-        if (live.length === 1) return live[0]!;
+        live.push(
+          ...readdirSync(worktreesDir)
+            .map((name) => join(worktreesDir, name))
+            .filter((p) => existsSync(join(p, ".git"))),
+        );
       } catch (err) {
         logWarning(
           "bootstrap",
@@ -60,49 +63,23 @@ export function resolveWorkflowToolBasePath(
         );
       }
     }
+    if (live.length === 1) return live[0]!;
   }
   return cwd;
 }
 
-/**
- * Resolve the correct DB path for the current working directory.
- * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
- * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise
- * returns `<basePath>/.gsd/gsd.db`.
- */
-export function resolveProjectRootDbPath(basePath: string): string {
-  return resolveGsdPathContract(basePath).projectDb;
-}
+export { resolveProjectRootDbPath } from "../db-workspace.js";
 
 export async function ensureDbOpen(basePath: string = safeWorkspaceCwd()): Promise<boolean> {
-  try {
-    const db = await import("../gsd-db.js");
-    const contract = resolveGsdPathContract(basePath);
-    const dbPath = contract.projectDb;
-    const gsdDir = contract.projectGsd;
-    const projectRoot = dirname(dirname(dbPath));
-
-    // Open existing DB file (may be at project root for worktrees)
-    if (existsSync(dbPath)) {
-      const opened = db.openDatabase(dbPath);
-      if (opened) setLogBasePath(projectRoot);
-      return opened;
-    }
-
-    // No DB file — create an empty authoritative DB. Markdown migration is
-    // explicit-only; runtime startup must not import projections into state.
-    if (existsSync(gsdDir)) {
-      const opened = db.openDatabase(dbPath);
-      if (opened) setLogBasePath(projectRoot);
-      return opened;
-    }
+  const result = openWorkflowDatabase(basePath);
+  if (result.ok) return true;
 
+  if (result.reason === "missing-gsd-dir") {
     logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
-    return false;
-  } catch (err) {
-    logWarning("bootstrap", `ensureDbOpen failed: ${(err as Error).message ?? String(err)}`);
-    return false;
+  } else {
+    logWarning("bootstrap", `ensureDbOpen failed: ${result.error?.message ?? "open failed"}`);
   }
+  return false;
 }
 
 export function registerDynamicTools(pi: ExtensionAPI): void {

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

@@ -5,6 +5,7 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen, resolveCtxCwd } from "./dynamic-tools.js";
+import { checkpointWorkflowDatabase } from "../db-workspace.js";
 
 
 export function registerQueryTools(pi: ExtensionAPI): void {
@@ -57,8 +58,7 @@ export function registerQueryTools(pi: ExtensionAPI): void {
           details: { operation: "checkpoint_db", error: "db_unavailable" },
         };
       }
-      const { checkpointDatabase } = await import("../gsd-db.js");
-      checkpointDatabase();
+      checkpointWorkflowDatabase();
       return {
         content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
         details: { operation: "checkpoint_db", status: "ok" },

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -17,6 +17,7 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
 // queued listener registration as a microtask — any CMUX_CHANNELS emit fired
@@ -37,6 +38,12 @@ const EPIPE_STORM_WINDOW_MS = 10_000;
 let epipeCount = 0;
 let epipeWindowStart = 0;
 
+export const CRITICAL_GSD_WORKFLOW_TOOL_NAMES = [...new Set(
+  Object.values(UNIT_TOOL_CONTRACTS)
+    .flatMap((contract) => contract.requiredWorkflowTools)
+    .filter((toolName) => toolName.startsWith("gsd_")),
+)].sort();
+
 /** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
  *  re-enter this handler and re-loop. */
 function safeStderr(msg: string): void {
@@ -133,6 +140,21 @@ export function installEpipeGuard(): void {
   }
 }
 
+function assertCriticalGsdWorkflowToolsRegistered(pi: ExtensionAPI): void {
+  if (typeof pi.getAllTools !== "function") return;
+
+  const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+  const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
+  if (missing.length === 0) return;
+
+  const message = [
+    `Critical GSD workflow tool registration failed; missing required tool(s): ${missing.join(", ")}.`,
+    "Check earlier bootstrap warnings for the registration slot that failed.",
+  ].join(" ");
+  logWarning("bootstrap", message);
+  throw new Error(message);
+}
+
 export function registerGsdExtension(pi: ExtensionAPI): void {
   // Note: registerGSDCommand is called by index.ts before this function,
   // so we intentionally skip it here to avoid double-registration.
@@ -214,4 +236,6 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
       );
     }
   }
+
+  assertCriticalGsdWorkflowToolsRegistered(pi);
 }