@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/src/resources/extensions/gsd/blocked-models.ts

@@ -23,6 +23,15 @@ interface BlockedModelsFile {
   blocked: BlockedModelEntry[];
 }
 
+interface TemporaryBlockedModelEntry {
+  provider: string;
+  id: string;
+  reason: string;
+  blockedUntil: number;
+}
+
+const temporaryBlockedModels = new Map<string, TemporaryBlockedModelEntry>();
+
 function blockedModelsPath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "blocked-models.json");
 }
@@ -31,6 +40,10 @@ function modelKey(provider: string, id: string): string {
   return `${provider.toLowerCase()}/${id.toLowerCase()}`;
 }
 
+function temporaryModelKey(basePath: string, provider: string, id: string): string {
+  return `${basePath}:${modelKey(provider, id)}`;
+}
+
 function readFileSafe(path: string): BlockedModelsFile {
   if (!existsSync(path)) return { version: 1, blocked: [] };
   try {
@@ -66,6 +79,42 @@ export function isModelBlocked(
   );
 }
 
+export function blockModelUntil(
+  basePath: string,
+  provider: string,
+  id: string,
+  blockedUntil: number,
+  reason: string,
+): void {
+  const key = temporaryModelKey(basePath, provider, id);
+  if (blockedUntil <= Date.now()) {
+    temporaryBlockedModels.delete(key);
+    return;
+  }
+  temporaryBlockedModels.set(key, { provider, id, reason, blockedUntil });
+}
+
+export function isModelTemporarilyUnavailable(
+  basePath: string,
+  provider: string | undefined,
+  id: string | undefined,
+  now = Date.now(),
+): boolean {
+  if (!provider || !id) return false;
+  const key = temporaryModelKey(basePath, provider, id);
+  const entry = temporaryBlockedModels.get(key);
+  if (!entry) return false;
+  if (entry.blockedUntil <= now) {
+    temporaryBlockedModels.delete(key);
+    return false;
+  }
+  return true;
+}
+
+export function clearTemporaryModelBlocksForTest(): void {
+  temporaryBlockedModels.clear();
+}
+
 export function blockModel(
   basePath: string,
   provider: string,

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

@@ -19,6 +19,7 @@ import {
   isAutoCompletionStopInProgress,
   pauseAuto,
   setCurrentDispatchedModelId,
+  setCurrentUnitModelForRecovery,
 } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
@@ -41,12 +42,10 @@ import {
   isTransient,
   type ErrorClass,
 } from "../error-classifier.js";
-import { blockModel, isModelBlocked } from "../blocked-models.js";
+import { blockModel, blockModelUntil, isModelBlocked, isModelTemporarilyUnavailable } 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;
@@ -145,9 +144,14 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
       const nextModelId = getNextFallbackModel(cursorModelId, modelConfig);
       if (!nextModelId) break;
       const candidate = resolveModelId(nextModelId, availableModels, rejectedProvider);
-      if (candidate && !isModelBlocked(basePath, candidate.provider, candidate.id)) {
+      if (
+        candidate &&
+        !isModelBlocked(basePath, candidate.provider, candidate.id) &&
+        !isModelTemporarilyUnavailable(basePath, candidate.provider, candidate.id)
+      ) {
         const ok = await pi.setModel(candidate, { persist: false });
         if (ok) {
+          setCurrentUnitModelForRecovery(candidate);
           setCurrentDispatchedModelId({ provider: candidate.provider, id: candidate.id });
           switchedNotify(`${candidate.provider}/${candidate.id}`);
           pi.sendMessage(
@@ -165,7 +169,8 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
   if (
     sessionModel &&
     !(sessionModel.provider === rejectedProvider && sessionModel.id === rejectedId) &&
-    !isModelBlocked(basePath, sessionModel.provider, sessionModel.id)
+    !isModelBlocked(basePath, sessionModel.provider, sessionModel.id) &&
+    !isModelTemporarilyUnavailable(basePath, sessionModel.provider, sessionModel.id)
   ) {
     const startModel = availableModels.find(
       (m) => m.provider === sessionModel.provider && m.id === sessionModel.id,
@@ -173,6 +178,7 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
     if (startModel) {
       const ok = await pi.setModel(startModel, { persist: false });
       if (ok) {
+        setCurrentUnitModelForRecovery(startModel);
         setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
         switchedNotify(`${startModel.provider}/${startModel.id}`);
         pi.sendMessage(
@@ -627,7 +633,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,
@@ -678,6 +684,16 @@ export async function handleAgentEnd(
       if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") {
         cls.retryAfterMs = Math.min(cls.retryAfterMs, 30_000);
       }
+      const dash = getAutoDashboardData();
+      if (dash.basePath && ctx.model?.provider && ctx.model?.id) {
+        blockModelUntil(
+          dash.basePath,
+          ctx.model.provider,
+          ctx.model.id,
+          Date.now() + cls.retryAfterMs,
+          rawErrorMsg || displayMsg || "rate limit",
+        );
+      }
     }
 
     // ── 2. Decide & Act ──────────────────────────────────────────────────
@@ -723,9 +739,14 @@ export async function handleAgentEnd(
             retryState.networkRetryCount = 0;
             retryState.currentRetryModelId = undefined;
             const modelToSet = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
-            if (modelToSet) {
+            const modelUnavailable = dash.basePath && modelToSet
+              ? isModelBlocked(dash.basePath, modelToSet.provider, modelToSet.id) ||
+                isModelTemporarilyUnavailable(dash.basePath, modelToSet.provider, modelToSet.id)
+              : false;
+            if (modelToSet && !modelUnavailable) {
               const ok = await pi.setModel(modelToSet, { persist: false });
               if (ok) {
+                setCurrentUnitModelForRecovery(modelToSet);
                 setCurrentDispatchedModelId({ provider: modelToSet.provider, id: modelToSet.id });
                 ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -739,11 +760,17 @@ export async function handleAgentEnd(
       // Try restoring session model
       const sessionModel = getAutoModeStartModel();
       if (sessionModel) {
-        if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
+        const dash = getAutoDashboardData();
+        const sessionModelUnavailable = dash.basePath
+          ? isModelBlocked(dash.basePath, sessionModel.provider, sessionModel.id) ||
+            isModelTemporarilyUnavailable(dash.basePath, sessionModel.provider, sessionModel.id)
+          : false;
+        if (!sessionModelUnavailable && (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider)) {
           const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
           if (startModel) {
             const ok = await pi.setModel(startModel, { persist: false });
             if (ok) {
+              setCurrentUnitModelForRecovery(startModel);
               setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
               retryState.networkRetryCount = 0;
               retryState.currentRetryModelId = undefined;

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,16 @@
 // 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 +46,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 +62,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 {
@@ -110,8 +86,30 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
   const baseBash = createBashTool(fallbackRoot, {
     spawnHook: (ctx) => ctx,
   });
+  // The auto-mode stalled-tool watchdog only exists in GSD/auto-mode, so the
+  // watchdog verbiage is injected here (the GSD-registered tool) rather than in
+  // core bash.ts, which is reused by non-GSD embeddings that have no watchdog.
+  const WATCHDOG_DETAIL =
+    "Genuine hangs are caught by the auto-mode stalled-tool watchdog (stalled: 5m / idle: 10m / soft: 20m / hard: 30m).";
+  const gsdBashDescription = `${(baseBash as any).description} ${WATCHDOG_DETAIL}`;
+  const gsdBashParameters = (() => {
+    const params: any = (baseBash as any).parameters;
+    if (!params?.properties?.timeout) return params;
+    return {
+      ...params,
+      properties: {
+        ...params.properties,
+        timeout: {
+          ...params.properties.timeout,
+          description: `${params.properties.timeout.description} ${WATCHDOG_DETAIL}`,
+        },
+      },
+    };
+  })();
   const dynamicBash = {
     ...baseBash,
+    description: gsdBashDescription,
+    parameters: gsdBashParameters,
     execute: async (
       toolCallId: string,
       params: { command: string; timeout?: number },
@@ -123,11 +121,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       const fresh = createBashTool(basePath, {
         spawnHook: (spawnCtx) => ({ ...spawnCtx, cwd: basePath }),
       });
-      const paramsWithTimeout = {
-        ...params,
-        timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
-      };
-      return (fresh as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   };
   pi.registerTool(dynamicBash as any);

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

@@ -137,8 +137,8 @@ export function registerExecTools(pi: ExtensionAPI): void {
     parameters: Type.Object({
       query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
       runtime: Type.Optional(
-        Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
-          description: "Restrict to one runtime.",
+        Type.String({
+          description: "Restrict to one runtime: bash, node, or python.",
         }),
       ),
       failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),

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