@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -3,6 +3,7 @@
 import { Type, StringEnum } from "@gsd/pi-ai";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
+import { SUMMARY_SAVE_CONTENT_MAX_LENGTH } from "@opengsd/contracts";
 
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen, resolveCtxCwd, resolveWorkflowToolBasePath } from "./dynamic-tools.js";
@@ -12,6 +13,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 +55,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 +181,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 +261,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 +363,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) ──────────────────────
 
@@ -386,13 +393,17 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
       "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
       "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
+      `Keep each content payload under ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters; save large context incrementally with CONTEXT-DRAFT/PROJECT-DRAFT/REQUIREMENTS-DRAFT instead of one oversized call.`,
     ],
     parameters: Type.Object({
       milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
       slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
       task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
       artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
-      content: Type.String({ description: "The full markdown content of the artifact" }),
+      content: Type.String({
+        description: `The full markdown content of the artifact. Maximum ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save.`,
+        maxLength: SUMMARY_SAVE_CONTENT_MAX_LENGTH,
+      }),
     }),
     execute: summarySaveExecute,
     renderCall(args: any, theme: any) {
@@ -413,8 +424,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 +513,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     },
   };
 
-  pi.registerTool(uatResultSaveTool);
+  registerWorkflowTool(pi, uatResultSaveTool);
 
   // ─── gsd_milestone_generate_id (formerly gsd_generate_milestone_id) ────
 
@@ -592,8 +602,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 +673,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 +722,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 +795,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 +863,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 +948,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 +1020,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
   };
 
-  pi.registerTool({
+  registerWorkflowTool(pi, {
     name: "gsd_skip_slice",
     label: "Skip Slice",
     description:
@@ -1081,8 +1085,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 +1124,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 +1174,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 +1232,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 +1299,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 +1365,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 +1429,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 +1497,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,21 @@
 // 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 {
+  getWorkflowDatabaseStatus,
+  openWorkflowDatabase,
+  type WorkflowDatabaseOpenResult,
+  type WorkflowDatabaseStatus,
+} 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 +51,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 +67,68 @@ 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";
+
+type WorkflowDatabaseOpenFailure = Extract<WorkflowDatabaseOpenResult, { ok: false }>;
+
+function sqliteProviderHint(status: WorkflowDatabaseStatus, nodeVersion: string): string {
+  if (status.provider) return `Provider: ${status.provider}.`;
+
+  const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+  if (Number.isFinite(major) && major < 22) {
+    return (
+      `No SQLite provider available. Upgrade Node to >= 22.0.0 (current: v${nodeVersion}), ` +
+      "use the packaged GSD runtime, or install/restore better-sqlite3 in this runtime."
+    );
+  }
+
+  return (
+    "No SQLite provider available. Use a Node build with node:sqlite enabled, " +
+    "run the packaged GSD runtime, or install/restore better-sqlite3 in this runtime."
+  );
 }
 
-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;
-    }
+function dbOpenPhaseHint(status: WorkflowDatabaseStatus): string {
+  if (status.lastPhase === "open") return "The database file could not be opened";
+  if (status.lastPhase === "initSchema") return "The database schema could not be initialized";
+  if (status.lastPhase === "vacuum-recovery") return "Corruption recovery (VACUUM) failed";
+  if (status.attempted) return "The database could not be opened";
+  return "The database provider could not be loaded";
+}
 
-    // 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;
-    }
+export function formatWorkflowDatabaseOpenFailure(
+  result: WorkflowDatabaseOpenFailure,
+  status?: WorkflowDatabaseStatus,
+  nodeVersion: string = process.versions.node,
+): string {
+  if (result.reason === "missing-gsd-dir") {
+    return `ensureDbOpen failed — no .gsd directory found at ${result.location.projectGsd}`;
+  }
 
-    logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
-    return false;
-  } catch (err) {
-    logWarning("bootstrap", `ensureDbOpen failed: ${(err as Error).message ?? String(err)}`);
-    return false;
+  if (result.reason === "missing-database") {
+    return `ensureDbOpen failed — no GSD database found at ${result.location.projectDb}`;
   }
+
+  const resolvedStatus = status ?? getWorkflowDatabaseStatus();
+  const detail = result.error?.message ?? resolvedStatus.lastError?.message ?? "";
+  const detailSuffix = detail ? ` (${detail})` : "";
+  return (
+    `ensureDbOpen failed for ${result.location.projectDb}: ` +
+    `${dbOpenPhaseHint(resolvedStatus)}${detailSuffix}. ${sqliteProviderHint(resolvedStatus, nodeVersion)}`
+  );
+}
+
+export async function ensureDbOpen(basePath: string = safeWorkspaceCwd()): Promise<boolean> {
+  const result = openWorkflowDatabase(basePath);
+  if (result.ok) return true;
+
+  logWarning("bootstrap", formatWorkflowDatabaseOpenFailure(result));
+  return false;
 }
 
 export function registerDynamicTools(pi: ExtensionAPI): void {
@@ -110,8 +136,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 +171,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

@@ -72,6 +72,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeUatExec(params as Parameters<typeof executeUatExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });
@@ -119,6 +120,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });
@@ -137,8 +139,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/fallback-continuation.ts

@@ -0,0 +1,31 @@
+// gsd-pi + src/resources/extensions/gsd/bootstrap/fallback-continuation.ts - Dispatches the post-fallback-switch continuation on a fresh turn.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+/**
+ * Dispatch the post-fallback continuation on a *fresh* turn after the current
+ * run settles.
+ *
+ * #804: At `agent_end` time the agent's run is still tearing down — its
+ * `isStreaming` flag stays `true` until `finishRun()` clears it in the `finally`
+ * block that fires *after* the awaited `agent_end` listeners return (see
+ * pi-agent-core/src/agent.ts processEvents comment). A synchronous
+ * `sendMessage({ triggerTurn: true, deliverAs: "steer" })` from inside that
+ * listener is therefore routed down the `isStreaming` branch and queued as a
+ * steering message against the turn that just errored out — which is never
+ * consumed, so the fallback model is selected but no new turn ever starts (the
+ * reported symptom: "switched but work stays stopped").
+ *
+ * Deferring to a macrotask lets `finishRun()` flip `isStreaming` to `false`
+ * first; the plain `triggerTurn` (no `deliverAs`) then dispatches a fresh turn
+ * on the freshly-selected fallback model, mirroring the network-retry path.
+ */
+export function scheduleFallbackContinuation(pi: ExtensionAPI): void {
+  setTimeout(() => {
+    pi.sendMessage(
+      { customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false },
+      { triggerTurn: true },
+    );
+  }, 0);
+}

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

@@ -16,7 +16,8 @@ import { registerScheduleWakeupTool } from "./schedule-wakeup-tool.js";
 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 { logWarning, isGsdExtensionStderrEnabled } 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,9 +38,16 @@ 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 {
+  if (!isGsdExtensionStderrEnabled()) return;
   try {
     process.stderr.write(msg);
   } catch { /* stderr is also broken; nothing we can do */ }
@@ -133,6 +141,41 @@ export function installEpipeGuard(): void {
   }
 }
 
+/**
+ * Assert that critical GSD workflow tools were registered.
+ *
+ * During extension loading, getAllTools() is a throwing stub
+ * ("Extension runtime not initialized") that only becomes real after
+ * runner.bindCore(). Calling it here used to throw, propagating to index.ts's
+ * catch and firing "Extension setup partially failed" — which, under Claude
+ * Code CLI, left the model's tool surface incomplete and trapped units in a
+ * finalize-retry loop. Tolerate the pre-bind throw and defer the real check to
+ * the first before_agent_start (where applyMinimalGsdToolSurface already
+ * re-reads the registered surface post-bind).
+ */
+function assertCriticalGsdWorkflowToolsRegistered(pi: ExtensionAPI): void {
+  if (typeof pi.getAllTools !== "function") return;
+
+  let registered: Set<string>;
+  try {
+    registered = new Set(pi.getAllTools().map((tool) => tool.name));
+  } catch {
+    // Pre-bind runtime: getAllTools() is not yet wired. The critical-tools
+    // invariant is re-checked post-bind during the first before_agent_start.
+    return;
+  }
+
+  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 +257,6 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
       );
     }
   }
+
+  assertCriticalGsdWorkflowToolsRegistered(pi);
 }