@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/packages/mcp-server/dist/workflow-tools.js

@@ -8,8 +8,11 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
-import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES, CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES, WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES, } from "@opengsd/contracts";
+import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES, CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES, WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES, SUMMARY_SAVE_CONTENT_MAX_LENGTH, } from "@opengsd/contracts";
 import { logAliasUsage } from "./alias-telemetry.js";
+async function importBridgeModule() {
+    return importLocalModule("../../../src/resources/extensions/gsd/mcp-bridge.js");
+}
 let workflowToolExecutorsPromise = null;
 let workflowExecutionQueue = Promise.resolve();
 let workflowWriteGatePromise = null;
@@ -106,37 +109,51 @@ function extractMilestoneId(parsed) {
  * the shared project `.gsd/` and auto-mode's verifyExpectedArtifact (which
  * uses the worktree `.gsd/`) fails, triggering a guaranteed retry per unit.
  */
+/**
+ * Containers a GSD worktree may live in: canonical .gsd-worktrees/ first,
+ * legacy .gsd/worktrees/ second. Boundary copy of `worktreesDirs` in
+ * src/resources/extensions/gsd/worktree-placement.ts — the MCP server cannot
+ * statically import the extension tree. Keep the two lists synchronized.
+ */
+function worktreeContainers(projectRoot) {
+    return [join(projectRoot, ".gsd-worktrees"), join(projectRoot, ".gsd", "worktrees")];
+}
 function resolveActiveWorktreeBasePath(projectRoot, milestoneId) {
     if (!milestoneId)
         return null;
-    const wtPath = join(projectRoot, ".gsd", "worktrees", milestoneId);
-    if (!existsSync(wtPath))
-        return null;
-    // Sanity check: a real git worktree has a `.git` file with a gitdir pointer.
-    // Bare directories without it shouldn't hijack the write path.
-    if (!existsSync(join(wtPath, ".git")))
-        return null;
-    return wtPath;
+    for (const container of worktreeContainers(projectRoot)) {
+        const wtPath = join(container, milestoneId);
+        if (!existsSync(wtPath))
+            continue;
+        // Sanity check: a real git worktree has a `.git` file with a gitdir pointer.
+        // Bare directories without it shouldn't hijack the write path.
+        if (!existsSync(join(wtPath, ".git")))
+            continue;
+        return wtPath;
+    }
+    return null;
 }
 /**
  * Fallback when the tool call has no milestoneId: if exactly one auto-worktree
- * exists under `<projectRoot>/.gsd/worktrees/`, treat it as the active one.
+ * exists across the project's worktree containers, treat it as the active one.
  * Multiple worktrees → ambiguous, return null and let writes go to project root.
  */
 function resolveSoleActiveWorktree(projectRoot) {
-    const worktreesDir = join(projectRoot, ".gsd", "worktrees");
-    if (!existsSync(worktreesDir))
-        return null;
-    let entries;
-    try {
-        entries = readdirSync(worktreesDir);
-    }
-    catch {
-        return null;
+    const live = [];
+    for (const worktreesDir of worktreeContainers(projectRoot)) {
+        if (!existsSync(worktreesDir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(worktreesDir);
+        }
+        catch {
+            continue;
+        }
+        live.push(...entries
+            .map((name) => join(worktreesDir, name))
+            .filter((p) => existsSync(join(p, ".git"))));
     }
-    const live = entries
-        .map((name) => join(worktreesDir, name))
-        .filter((p) => existsSync(join(p, ".git")));
     if (live.length !== 1)
         return null;
     return live[0];
@@ -269,7 +286,7 @@ function getWriteGateModuleCandidates() {
         warnCustomWorkflowModule("GSD_WORKFLOW_WRITE_GATE_MODULE", explicitModule);
         candidates.push(explicitModule.startsWith("file:") ? explicitModule : toFileUrl(explicitModule));
     }
-    candidates.push(...buildBridgeImportCandidates("../../../src/resources/extensions/gsd/bootstrap/write-gate.js")
+    candidates.push(...buildBridgeImportCandidates("../../../src/resources/extensions/gsd/mcp-bridge.js")
         .map((p) => new URL(p, import.meta.url).href));
     return [...new Set(candidates)];
 }
@@ -319,10 +336,27 @@ async function importLocalModule(relativePath) {
     }
     throw lastErr;
 }
+async function importWorkflowRuntimeModule(relativePath) {
+    const rawCandidates = import.meta.url.includes("/src/") || import.meta.url.includes("\\src\\")
+        ? _buildImportCandidates(relativePath)
+        : buildBridgeImportCandidates(relativePath);
+    const candidates = rawCandidates
+        .map((p) => new URL(p, import.meta.url).href);
+    let lastErr;
+    for (const candidate of candidates) {
+        try {
+            return await import(candidate);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
 async function loadProjectPreferences(projectDir) {
-    const { loadEffectiveGSDPreferences } = await importLocalModule("../../../src/resources/extensions/gsd/preferences.js");
+    const bridge = await importBridgeModule();
     try {
-        return loadEffectiveGSDPreferences(projectDir).preferences;
+        return bridge.loadEffectiveGSDPreferences(projectDir).preferences;
     }
     catch {
         return null;
@@ -366,6 +400,17 @@ async function getWorkflowToolExecutors() {
     }
     return workflowToolExecutorsPromise;
 }
+/**
+ * Eagerly load and shape-check the workflow executor and write-gate bridges.
+ * The stdio CLI awaits this at startup so a broken bridge fails the spawn
+ * with an actionable error instead of presenting an available-looking tool
+ * surface that errors on the first call. Shares the cached promises the tool
+ * handlers use, so a successful warm-up also removes first-call import latency.
+ */
+export async function warmWorkflowToolBridges() {
+    await getWorkflowToolExecutors();
+    await getWorkflowWriteGateModule();
+}
 async function getWorkflowWriteGateModule() {
     if (!workflowWriteGatePromise) {
         workflowWriteGatePromise = (async () => {
@@ -455,18 +500,15 @@ function isPlainObject(value) {
 async function runSerializedWorkflowOperation(fn) {
     // The shared DB adapter and workflow log base path are process-global, so
     // workflow MCP mutations must not overlap within a single server process.
-    // A per-operation deadline prevents a single stuck call from wedging every
-    // subsequent write for the lifetime of the process.
+    // A per-operation deadline prevents a single stuck call from wedging its
+    // caller for the lifetime of the process.
     //
-    // Known limitation: on timeout we surface an error and release the queue,
-    // but Promise.race cannot cancel the underlying `fn()` — it may continue
-    // running in the background and overlap with the next admitted operation.
-    // Proper cancellation requires threading an AbortSignal through every
-    // workflow executor (`workflow-tool-executors.ts` and friends), which is
-    // a larger change. The current trade-off: risk a theoretical overlap after
-    // a 5-minute wall-clock timeout vs permanently wedging the server. The
-    // overlap window is bounded by how long the zombie `fn()` keeps running;
-    // in practice DB writes complete quickly even when the caller gave up.
+    // Promise.race cannot cancel the underlying `fn()`. On timeout, surface an
+    // error to the caller but keep the queue held until `fn()` actually settles
+    // so a retry cannot overlap with the still-running operation. True
+    // cancellation remains a larger deferred design: it requires threading an
+    // AbortSignal through every workflow executor (`workflow-tool-executors.ts`
+    // and friends).
     const prior = workflowExecutionQueue;
     let release;
     workflowExecutionQueue = new Promise((resolve) => {
@@ -474,18 +516,21 @@ async function runSerializedWorkflowOperation(fn) {
     });
     await prior;
     const timeoutMs = getWorkflowOpTimeoutMs();
+    const operationPromise = Promise.resolve().then(fn);
+    let timedOut = false;
     try {
         if (timeoutMs === 0) {
-            return await fn();
+            return await operationPromise;
         }
         let timer;
         const timeoutPromise = new Promise((_, reject) => {
             timer = setTimeout(() => {
+                timedOut = true;
                 reject(new Error(`Workflow operation exceeded ${timeoutMs}ms deadline (GSD_MCP_WORKFLOW_TIMEOUT_MS)`));
             }, timeoutMs);
         });
         try {
-            return await Promise.race([fn(), timeoutPromise]);
+            return await Promise.race([operationPromise, timeoutPromise]);
         }
         finally {
             if (timer)
@@ -493,13 +538,22 @@ async function runSerializedWorkflowOperation(fn) {
         }
     }
     finally {
-        release();
+        if (timedOut) {
+            void operationPromise.then(release, release);
+        }
+        else {
+            release();
+        }
     }
 }
+/** @internal — exported for testing only */
+export function _runSerializedWorkflowOperationForTest(fn) {
+    return runSerializedWorkflowOperation(fn);
+}
 async function runSerializedWorkflowDbOperation(projectDir, fn) {
     return runSerializedWorkflowOperation(async () => {
-        const { ensureDbOpen } = await importLocalModule("../../../src/resources/extensions/gsd/bootstrap/dynamic-tools.js");
-        const dbAvailable = await ensureDbOpen(projectDir);
+        const bridge = await importBridgeModule();
+        const dbAvailable = await bridge.ensureDbOpen(projectDir);
         if (!dbAvailable) {
             throw new Error("GSD database is not available");
         }
@@ -595,23 +649,22 @@ async function inferSaveGateResultScope(projectDir, prepared) {
         return out;
     if (!gateId)
         return out;
-    const { ensureDbOpen } = await importLocalModule("../../../src/resources/extensions/gsd/bootstrap/dynamic-tools.js");
-    if (!(await ensureDbOpen(projectDir)))
+    const bridge = await importBridgeModule();
+    if (!(await bridge.ensureDbOpen(projectDir)))
         return out;
-    const db = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js");
-    if (!db.getMilestoneSlices || !db.getPendingGates || !db.getGateResults)
+    if (!bridge.getMilestoneSlices || !bridge.getPendingGates || !bridge.getGateResults)
         return out;
     const milestoneFilter = stringValue(out.milestoneId);
     const sliceFilter = stringValue(out.sliceId);
     const milestones = milestoneFilter
         ? [{ id: milestoneFilter }]
-        : (db.getAllMilestones?.() ?? []).filter((milestone) => stringValue(milestone.id));
+        : (bridge.getAllMilestones?.() ?? []).filter((milestone) => stringValue(milestone.id));
     const candidates = [];
     for (const milestone of milestones) {
         const milestoneId = stringValue(milestone.id);
         if (!milestoneId)
             continue;
-        const slices = db.getMilestoneSlices(milestoneId)
+        const slices = bridge.getMilestoneSlices(milestoneId)
             .filter((slice) => {
             const sliceId = stringValue(slice.id);
             return sliceId && (!sliceFilter || sliceId === sliceFilter);
@@ -621,8 +674,8 @@ async function inferSaveGateResultScope(projectDir, prepared) {
             if (!sliceId)
                 continue;
             const rows = [
-                ...db.getPendingGates(milestoneId, sliceId),
-                ...db.getGateResults(milestoneId, sliceId),
+                ...bridge.getPendingGates(milestoneId, sliceId),
+                ...bridge.getGateResults(milestoneId, sliceId),
             ];
             for (const row of rows) {
                 if (stringValue(row.gate_id)?.toUpperCase() !== gateId)
@@ -657,8 +710,8 @@ async function handleSaveGateResult(projectDir, args) {
 }
 async function ensureMilestoneDbRow(milestoneId) {
     try {
-        const { insertMilestone } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js");
-        insertMilestone({ id: milestoneId, status: "queued" });
+        const bridge = await importBridgeModule();
+        bridge.insertMilestone({ id: milestoneId, status: "queued" });
     }
     catch {
         // Ignore pre-existing rows or transient DB availability issues.
@@ -666,8 +719,8 @@ async function ensureMilestoneDbRow(milestoneId) {
 }
 async function findDatabaseMilestoneIds() {
     try {
-        const { getAllMilestones } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js");
-        return (getAllMilestones?.() ?? [])
+        const bridge = await importBridgeModule();
+        return (bridge.getAllMilestones?.() ?? [])
             .map((milestone) => {
             const id = milestone?.id;
             return typeof id === "string" ? id : null;
@@ -687,7 +740,8 @@ async function findDatabaseMilestoneIds() {
  * from an earlier call to this same tool.
  */
 async function generateOrReuseMilestoneId(projectDir) {
-    const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId, milestoneIdSort, } = await importLocalModule("../../../src/resources/extensions/gsd/milestone-ids.js");
+    const bridge = await importBridgeModule();
+    const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId, milestoneIdSort, } = bridge;
     const reserved = claimReservedId();
     if (reserved) {
         await ensureMilestoneDbRow(reserved);
@@ -701,7 +755,7 @@ async function generateOrReuseMilestoneId(projectDir) {
         ]),
     ];
     // Attempt ghost-ID reuse before falling back to max+1.
-    const { isReusableGhostMilestone } = await importLocalModule("../../../src/resources/extensions/gsd/state.js");
+    const { isReusableGhostMilestone } = bridge;
     const sorted = [...allIds].sort(milestoneIdSort);
     for (const candidate of sorted) {
         if (isReusableGhostMilestone(projectDir, candidate)) {
@@ -709,7 +763,7 @@ async function generateOrReuseMilestoneId(projectDir) {
             return candidate;
         }
     }
-    const prefsMod = await importLocalModule("../../../src/resources/extensions/gsd/preferences.js").catch(() => null);
+    const prefsMod = await importBridgeModule().catch(() => null);
     // Graceful degradation: a corrupt preferences file should not crash
     // milestone-id generation. Fall back to non-unique IDs if anything
     // throws here — matches the pre-fix behavior for missing prefs.
@@ -733,6 +787,71 @@ const projectDirParam = z
     .optional()
     .describe("Optional. Omit this field — the server defaults to its current working directory, which is already the correct project or worktree root.");
 const unknownRecord = z.record(z.string(), z.unknown());
+/** Split "id — detail" / "id - detail" pairs used by legacy string payloads. */
+function splitPair(value) {
+    const match = value.match(/^(.+?)\s*(?:—|-)\s+(.+)$/);
+    return match ? [match[1].trim(), match[2].trim()] : [value.trim(), ""];
+}
+/** Accept string or string[] at runtime; emit array-only JSON Schema (no anyOf). */
+const optionalStringOrStringArray = () => z.preprocess((value) => (value == null ? value : Array.isArray(value) ? value : [value]), z.array(z.string()).optional());
+function optionalStructuredStringArray(itemSchema, coerceString) {
+    return z.preprocess((value) => {
+        if (value == null)
+            return value;
+        if (!Array.isArray(value))
+            return value;
+        return value.map((item) => (typeof item === "string" ? coerceString(item) : item));
+    }, z.array(itemSchema).optional());
+}
+const requirementAdvancedItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    const [id, how] = splitPair(value);
+    return { id, how };
+}, z.object({ id: z.string(), how: z.string() }));
+const requirementValidatedItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    const [id, proof] = splitPair(value);
+    return { id, proof };
+}, z.object({ id: z.string(), proof: z.string() }));
+const requirementInvalidatedItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    const [id, what] = splitPair(value);
+    return { id, what };
+}, z.object({ id: z.string(), what: z.string() }));
+const filesModifiedItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    const [path, description] = splitPair(value);
+    return { path, description };
+}, z.object({ path: z.string(), description: z.string() }));
+const requiresItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    const [slice, provides] = splitPair(value);
+    return { slice, provides };
+}, z.object({ slice: z.string(), provides: z.string() }));
+// Accept either a string (legacy command-only form) or the structured object.
+// Mirrors `normalizeVerificationEvidence` in the executor: strings are coerced
+// into the canonical object shape before Zod validates, so the emitted JSON
+// Schema stays a single object type (no anyOf/oneOf) for Moonshot/Kimi.
+const verificationEvidenceItemSchema = z.preprocess((value) => {
+    if (typeof value !== "string")
+        return value;
+    return {
+        command: value,
+        exitCode: -1,
+        verdict: "unknown (coerced from string)",
+        durationMs: 0,
+    };
+}, z.object({
+    command: z.string(),
+    exitCode: z.number(),
+    verdict: z.string(),
+    durationMs: z.number(),
+}));
 const nonEmptyString = (field) => z.string().trim().min(1, `${field} must be a non-empty string`);
 // Optional non-empty string: accepts omitted/undefined but rejects "" or
 // whitespace. Mirrors executor guards of the form
@@ -973,48 +1092,51 @@ const sliceCompleteParams = {
     sliceTitle: z.string().describe("Title of the slice"),
     oneLiner: z.string().describe("One-line summary of what the slice accomplished"),
     narrative: z.string().describe("Detailed narrative of what happened across all tasks"),
-    verification: z.string().describe("What was verified across all tasks"),
+    verification: z.string().optional().describe("What was verified across all tasks — if omitted, summary records verification as passed without detail."),
     uatContent: z.string().describe("UAT test content (markdown body)"),
     deviations: z.string().optional(),
     knownLimitations: z.string().optional(),
     followUps: z.string().optional(),
-    keyFiles: z.union([z.array(z.string()), z.string()]).optional(),
-    keyDecisions: z.union([z.array(z.string()), z.string()]).optional(),
-    patternsEstablished: z.union([z.array(z.string()), z.string()]).optional(),
-    observabilitySurfaces: z.union([z.array(z.string()), z.string()]).optional(),
-    provides: z.union([z.array(z.string()), z.string()]).optional(),
-    requirementsSurfaced: z.union([z.array(z.string()), z.string()]).optional(),
-    drillDownPaths: z.union([z.array(z.string()), z.string()]).optional(),
-    affects: z.union([z.array(z.string()), z.string()]).optional(),
-    requirementsAdvanced: z.array(z.union([
-        z.object({ id: z.string(), how: z.string() }),
-        z.string(),
-    ])).optional(),
-    requirementsValidated: z.array(z.union([
-        z.object({ id: z.string(), proof: z.string() }),
-        z.string(),
-    ])).optional(),
-    requirementsInvalidated: z.array(z.union([
-        z.object({ id: z.string(), what: z.string() }),
-        z.string(),
-    ])).optional(),
-    filesModified: z.array(z.union([
-        z.object({ path: z.string(), description: z.string() }),
-        z.string(),
-    ])).optional(),
-    requires: z.array(z.union([
-        z.object({ slice: z.string(), provides: z.string() }),
-        z.string(),
-    ])).optional(),
+    keyFiles: optionalStringOrStringArray(),
+    keyDecisions: optionalStringOrStringArray(),
+    patternsEstablished: optionalStringOrStringArray(),
+    observabilitySurfaces: optionalStringOrStringArray(),
+    provides: optionalStringOrStringArray(),
+    requirementsSurfaced: optionalStringOrStringArray(),
+    drillDownPaths: optionalStringOrStringArray(),
+    affects: optionalStringOrStringArray(),
+    requirementsAdvanced: optionalStructuredStringArray(requirementAdvancedItemSchema, (value) => {
+        const [id, how] = splitPair(value);
+        return { id, how };
+    }),
+    requirementsValidated: optionalStructuredStringArray(requirementValidatedItemSchema, (value) => {
+        const [id, proof] = splitPair(value);
+        return { id, proof };
+    }),
+    requirementsInvalidated: optionalStructuredStringArray(requirementInvalidatedItemSchema, (value) => {
+        const [id, what] = splitPair(value);
+        return { id, what };
+    }),
+    filesModified: optionalStructuredStringArray(filesModifiedItemSchema, (value) => {
+        const [path, description] = splitPair(value);
+        return { path, description };
+    }),
+    requires: optionalStructuredStringArray(requiresItemSchema, (value) => {
+        const [slice, provides] = splitPair(value);
+        return { slice, provides };
+    }),
 };
 const sliceCompleteSchema = z.object(sliceCompleteParams);
+export const _sliceCompleteSchemaForTest = sliceCompleteSchema;
 const summarySaveParams = {
     projectDir: projectDirParam,
     milestone_id: z.string().optional().describe("Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts."),
     slice_id: z.string().optional().describe("Slice ID (e.g. S01)"),
     task_id: z.string().optional().describe("Task ID (e.g. T01)"),
     artifact_type: z.string().describe("Artifact type to save (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT)"),
-    content: z.string().describe("The full markdown content of the artifact"),
+    content: z.string()
+        .max(SUMMARY_SAVE_CONTENT_MAX_LENGTH, `content must be at most ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save`)
+        .describe(`The full markdown content of the artifact. Maximum ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save.`),
 };
 const ROOT_SUMMARY_ARTIFACT_TYPES = new Set([
     "PROJECT",
@@ -1032,6 +1154,7 @@ const summarySaveSchema = z.object(summarySaveParams).superRefine((value, ctx) =
         });
     }
 });
+export const _summarySaveSchemaForTest = summarySaveSchema;
 const decisionSaveParams = {
     projectDir: projectDirParam,
     scope: z.string().describe("Scope of the decision (e.g. architecture, library, observability)"),
@@ -1118,15 +1241,7 @@ const taskCompleteParams = {
         recommendationRationale: z.string().describe("Why the recommendation — 1-2 sentences."),
         continueWithDefault: z.boolean().describe("When true, the recommendation is recorded as the default, but auto-mode still pauses until the user resolves via /gsd escalate resolve."),
     }).optional().describe("ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true."),
-    verificationEvidence: z.array(z.union([
-        z.object({
-            command: z.string(),
-            exitCode: z.number(),
-            verdict: z.string(),
-            durationMs: z.number(),
-        }),
-        z.string(),
-    ])).optional().describe("Verification evidence entries"),
+    verificationEvidence: z.array(verificationEvidenceItemSchema).optional().describe("Verification evidence entries"),
 };
 const taskCompleteSchema = z.object(taskCompleteParams);
 const taskReopenParams = {
@@ -1251,7 +1366,11 @@ const uatResultSaveParams = {
     checks: z.array(uatCheckSchema).min(1).describe("Structured check results"),
     presentation: uatPresentationSchema.describe("Tool-presentation evidence"),
     notes: z.string().optional().describe("Overall verdict rationale"),
-    attempt: z.union([z.number().int().min(1), z.literal("auto")]).optional().describe("Attempt number or auto"),
+    // Accept number (e.g. 1) or string (e.g. "1", "auto") and coerce to string
+    // before validation, so the emitted JSON Schema stays a single primitive type
+    // (no anyOf/oneOf) for Moonshot/Kimi. The executor still treats "auto" and
+    // numeric strings as previously.
+    attempt: z.preprocess((value) => (typeof value === "number" ? String(value) : value), z.string().optional()).describe("Attempt number or auto"),
     previousAttemptId: z.string().optional(),
 };
 const uatResultSaveSchema = z.object(uatResultSaveParams);
@@ -1283,9 +1402,9 @@ const resumeSchema = z.object(resumeParams);
 function wrapServerWithErrorHandler(realServer) {
     return {
         tool(name, description, params, handler) {
-            return realServer.tool(name, description, params, async (args) => {
+            return realServer.tool(name, description, params, async (args, extra) => {
                 try {
-                    return await handler(args);
+                    return await handler(args, extra);
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -1318,8 +1437,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_decision_save", projectDir);
         const result = await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { saveDecisionToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return saveDecisionToDb(params, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.saveDecisionToDb(params, projectDir);
         });
         return { content: [{ type: "text", text: `Saved decision ${result.id}` }] };
     });
@@ -1329,8 +1448,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_decision_save", projectDir);
         const result = await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { saveDecisionToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return saveDecisionToDb(params, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.saveDecisionToDb(params, projectDir);
         });
         return { content: [{ type: "text", text: `Saved decision ${result.id}` }] };
     });
@@ -1339,8 +1458,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, id, ...updates } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_update", projectDir);
         await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { updateRequirementInDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return updateRequirementInDb(id, updates, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.updateRequirementInDb(id, updates, projectDir);
         });
         return { content: [{ type: "text", text: `Updated requirement ${id}` }] };
     });
@@ -1350,8 +1469,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, id, ...updates } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_update", projectDir);
         await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { updateRequirementInDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return updateRequirementInDb(id, updates, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.updateRequirementInDb(id, updates, projectDir);
         });
         return { content: [{ type: "text", text: `Updated requirement ${id}` }] };
     });
@@ -1360,8 +1479,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_save", projectDir);
         const result = await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { saveRequirementToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return saveRequirementToDb(params, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.saveRequirementToDb(params, projectDir);
         });
         return { content: [{ type: "text", text: `Saved requirement ${result.id}` }] };
     });
@@ -1371,8 +1490,8 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, ...params } = parsed;
         await enforceWorkflowWriteGate("gsd_requirement_save", projectDir);
         const result = await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { saveRequirementToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js");
-            return saveRequirementToDb(params, projectDir);
+            const bridge = await importBridgeModule();
+            return bridge.saveRequirementToDb(params, projectDir);
         });
         return { content: [{ type: "text", text: `Saved requirement ${result.id}` }] };
     });
@@ -1473,14 +1592,13 @@ export function registerWorkflowTools(realServer, options = {}) {
         await enforceWorkflowWriteGate("gsd_skip_slice", projectDir, milestoneId);
         await runSerializedWorkflowDbOperation(projectDir, async () => {
             const { handleSkipSlice } = await importLocalModule("../../../src/resources/extensions/gsd/tools/skip-slice.js");
-            const { invalidateStateCache } = await importLocalModule("../../../src/resources/extensions/gsd/state.js");
-            const { rebuildState } = await importLocalModule("../../../src/resources/extensions/gsd/doctor.js");
+            const bridge = await importBridgeModule();
             const result = handleSkipSlice({ milestoneId, sliceId, reason });
             if (result.error) {
                 throw new Error(result.error);
             }
-            invalidateStateCache();
-            await rebuildState(projectDir);
+            bridge.invalidateStateCache();
+            await bridge.rebuildState(projectDir);
         });
         return {
             content: [{ type: "text", text: `Skipped slice ${sliceId} (${milestoneId}). Reason: ${reason ?? "User-directed skip"}.` }],
@@ -1608,8 +1726,8 @@ export function registerWorkflowTools(realServer, options = {}) {
     server.tool("gsd_checkpoint_db", "Flush the SQLite WAL into gsd.db so git add stages the current GSD database state.", checkpointDbParams, async (args) => {
         const { projectDir } = parseWorkflowArgs(checkpointDbSchema, args);
         await runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { checkpointDatabase } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js");
-            checkpointDatabase();
+            const bridge = await importBridgeModule();
+            bridge.checkpointDatabase();
         });
         return {
             content: [{
@@ -1621,29 +1739,31 @@ export function registerWorkflowTools(realServer, options = {}) {
     });
     server.tool("gsd_journal_query", "Query the structured event journal for auto-mode iterations.", journalQueryParams, async (args) => {
         const { projectDir, limit, ...filters } = parseWorkflowArgs(journalQuerySchema, args);
-        const { queryJournal } = await importLocalModule("../../../src/resources/extensions/gsd/journal.js");
-        const entries = queryJournal(projectDir, filters).slice(0, limit ?? 100);
+        const bridge = await importBridgeModule();
+        const entries = bridge.queryJournal(projectDir, filters).slice(0, limit ?? 100);
         if (entries.length === 0) {
             return { content: [{ type: "text", text: "No matching journal entries found." }] };
         }
         return { content: [{ type: "text", text: JSON.stringify(entries, null, 2) }] };
     });
-    server.tool("gsd_uat_exec", "Run one UAT-scoped bash/node/python check with milestone/slice/check metadata. Evidence persists under .gsd/exec with kind=uat_exec.", uatExecParams, async (args) => {
+    server.tool("gsd_uat_exec", "Run one UAT-scoped bash/node/python check with milestone/slice/check metadata. Evidence persists under .gsd/exec with kind=uat_exec.", uatExecParams, async (args, extra) => {
         const { projectDir, ...params } = parseWorkflowArgs(uatExecSchema, args);
         await enforceWorkflowWriteGate("gsd_uat_exec", projectDir);
         const { executeUatExec } = await importLocalModule("../../../src/resources/extensions/gsd/tools/exec-tool.js");
         return adaptExecutorResult(await runSerializedWorkflowOperation(async () => executeUatExec(params, {
             baseDir: projectDir,
             preferences: await loadProjectPreferences(projectDir),
+            signal: extra?.signal,
         })));
     });
-    server.tool("gsd_exec", "Run a short bash/node/python script in the project directory. Capped stdout/stderr and metadata persist under .gsd/exec; only a digest returns to MCP.", execParams, async (args) => {
+    server.tool("gsd_exec", "Run a short bash/node/python script in the project directory. Capped stdout/stderr and metadata persist under .gsd/exec; only a digest returns to MCP.", execParams, async (args, extra) => {
         const { projectDir, ...params } = parseWorkflowArgs(execSchema, args);
         await enforceWorkflowWriteGate("gsd_exec", projectDir);
         const { executeGsdExec } = await importLocalModule("../../../src/resources/extensions/gsd/tools/exec-tool.js");
         return adaptExecutorResult(await runSerializedWorkflowOperation(async () => executeGsdExec(params, {
             baseDir: projectDir,
             preferences: await loadProjectPreferences(projectDir),
+            signal: extra?.signal,
         })));
     });
     server.tool("gsd_exec_search", "Search prior gsd_exec runs from .gsd/exec/*.meta.json without re-running them.", execSearchParams, async (args) => {
@@ -1701,7 +1821,7 @@ export function registerWorkflowTools(realServer, options = {}) {
         const { projectDir, ...params } = parseWorkflowArgs(captureThoughtSchema, args);
         await enforceWorkflowWriteGate("gsd_capture_thought", projectDir);
         return runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { executeMemoryCapture } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            const { executeMemoryCapture } = await importWorkflowRuntimeModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
             return executeMemoryCapture(params);
         });
     });
@@ -1730,7 +1850,7 @@ export function registerWorkflowTools(realServer, options = {}) {
     server.tool("gsd_memory_query", "Search the GSD memory store by keyword. Returns ranked memories with id, category, content, confidence, scope, and tags. Mirrors the in-process memory_query tool for external MCP clients.", memoryQueryParams, async (args) => {
         const { projectDir, ...params } = parseWorkflowArgs(memoryQuerySchema, args);
         return runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { executeMemoryQuery } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            const { executeMemoryQuery } = await importWorkflowRuntimeModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
             return executeMemoryQuery(params);
         });
     });
@@ -1751,7 +1871,7 @@ export function registerWorkflowTools(realServer, options = {}) {
     server.tool("gsd_memory_graph", "Inspect the relationship graph between memories. mode=query walks edges from a given memoryId. mode=build is a placeholder reserved for future graph rebuilds. Distinct from gsd_graph (project knowledge graph) — see ADR-013.", memoryGraphParams, async (args) => {
         const { projectDir, ...params } = parseWorkflowArgs(memoryGraphSchema, args);
         return runSerializedWorkflowDbOperation(projectDir, async () => {
-            const { executeGsdGraph } = await importLocalModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
+            const { executeGsdGraph } = await importWorkflowRuntimeModule("../../../src/resources/extensions/gsd/tools/memory-tools.js");
             return executeGsdGraph(params);
         });
     });