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

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,8 +1,10 @@
 // gsd-pi + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
 import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
-import { clearPathCache } from "../paths.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, } from "../auto.js";
+import { clearPathCache, gsdRoot } from "../paths.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, setCurrentUnitModelForRecovery, } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchAbortGraceActive, isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled, } from "../auto/resolve.js";
@@ -10,12 +12,14 @@ import { shouldIgnoreAgentEndForActiveUnit } from "../auto/unit-runner-events.js
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
-import { clearGuidedUnitContext } from "../guided-unit-context.js";
+import { scheduleFallbackContinuation } from "./fallback-continuation.js";
+import { clearGuidedUnitContext, getGuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } 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;
 function isObjectRecord(value) {
@@ -76,10 +80,15 @@ export function isUserInitiatedAbortMessage(message) {
         return false;
     return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
 }
-export function shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg) {
+export function shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg, deferCheckMsg = rawErrorMsg) {
     if (!isTransient(cls) || cls.kind === "rate-limit")
         return false;
-    return !/retry failed after \d+ attempts:/i.test(rawErrorMsg);
+    // Empty rawErrorMsg means the SDK terminated the session without providing an
+    // error string — core is done, not mid-retry.  GSD must schedule its own
+    // retry rather than silently deferring to a core that has already exited.
+    if (!rawErrorMsg)
+        return false;
+    return !/retry failed after \d+ attempts:/i.test(deferCheckMsg);
 }
 /** Try configured fallbacks, then the auto-mode start model. Returns true if switched. */
 async function tryProviderModelFallback(params) {
@@ -95,12 +104,15 @@ async function tryProviderModelFallback(params) {
             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({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+                    scheduleFallbackContinuation(pi);
                     return true;
                 }
             }
@@ -110,14 +122,16 @@ async function tryProviderModelFallback(params) {
     const sessionModel = getAutoModeStartModel();
     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);
         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({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+                scheduleFallbackContinuation(pi);
                 return true;
             }
         }
@@ -270,6 +284,86 @@ export function suppressTerminalDeletedWorktreeMessageEnd(event) {
     logWarning("bootstrap", `Suppressing stale deleted-worktree provider error during terminal completion reroot: ${displayMsg || rawErrorMsg}`);
     return true;
 }
+function modelLabel(ctx) {
+    const provider = ctx.model?.provider;
+    const id = ctx.model?.id;
+    return provider && id ? `${provider}/${id}` : "unknown model";
+}
+function isFatalManualGuidedTerminalFailure(lastMsg) {
+    if (!isObjectRecord(lastMsg) || !("stopReason" in lastMsg))
+        return false;
+    if (lastMsg.stopReason === "error") {
+        const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+        if (isUserInitiatedAbortMessage(rawErrorMsg))
+            return false;
+        return true;
+    }
+    if (lastMsg.stopReason !== "aborted")
+        return false;
+    const content = "content" in lastMsg ? lastMsg.content : undefined;
+    const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
+    return hasErrorMessage || !_hasEmptyAgentEndContent(content);
+}
+function terminalFailureDetail(lastMsg) {
+    if (!isObjectRecord(lastMsg))
+        return "Provider turn ended with an unknown terminal error.";
+    const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+    const content = "content" in lastMsg ? lastMsg.content : undefined;
+    const displayMsg = resolveAgentEndErrorDisplay(rawErrorMsg, content).replace(/\s+/g, " ").trim();
+    if (displayMsg)
+        return displayMsg.length > 300 ? `${displayMsg.slice(0, 300)}...` : displayMsg;
+    return lastMsg.stopReason === "aborted"
+        ? "Provider turn aborted with error context."
+        : "Provider stream ended with stopReason=error.";
+}
+function nextManualActivitySequence(activityDir) {
+    let maxSeq = 0;
+    try {
+        for (const file of readdirSync(activityDir)) {
+            const match = /^(\d+)-/.exec(file);
+            if (match)
+                maxSeq = Math.max(maxSeq, Number.parseInt(match[1], 10));
+        }
+    }
+    catch {
+        return "001";
+    }
+    return String(maxSeq + 1).padStart(3, "0");
+}
+function writeManualGuidedTerminalErrorActivity(basePath, unitType, model, detail, stopReason) {
+    const activityDir = join(gsdRoot(basePath), "activity");
+    mkdirSync(activityDir, { recursive: true });
+    const seq = nextManualActivitySequence(activityDir);
+    const safeUnitType = unitType.replace(/[^a-z0-9_.-]+/gi, "-");
+    const markerPath = join(activityDir, `${seq}-${safeUnitType}-manual-terminal-provider-error.jsonl`);
+    const message = `Manual guided ${unitType} turn ended with provider ${String(stopReason)} on ${model}: ${detail}`;
+    writeFileSync(markerPath, JSON.stringify({
+        type: "message",
+        message: {
+            role: "toolResult",
+            toolCallId: "manual-guided-terminal-provider-error",
+            toolName: "provider",
+            isError: true,
+            content: [{ type: "text", text: message }],
+        },
+    }) + "\n", "utf-8");
+}
+function observeManualDiscussTerminalError(ctx, lastMsg, guidedUnit) {
+    if (!guidedUnit?.unitType.startsWith("discuss-"))
+        return;
+    if (!isFatalManualGuidedTerminalFailure(lastMsg))
+        return;
+    const model = modelLabel(ctx);
+    const detail = terminalFailureDetail(lastMsg);
+    ctx.ui.notify(`Manual /gsd discuss ${guidedUnit.unitType} ended with a provider error on ${model}: ${detail}`, "warning");
+    try {
+        writeManualGuidedTerminalErrorActivity(guidedUnit.basePath, guidedUnit.unitType, model, detail, isObjectRecord(lastMsg) ? lastMsg.stopReason : "unknown");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("bootstrap", `Failed to write manual guided terminal-error activity marker: ${message}`);
+    }
+}
 async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -308,7 +402,9 @@ export async function handleAgentEnd(pi, event, ctx) {
     // rejected" loop even though the files are on disk.
     clearPathCache();
     const basePath = resolveAgentEndBasePath();
-    clearGuidedUnitContext(basePath);
+    const lastMsg = event.messages[event.messages.length - 1];
+    const guidedUnit = basePath ? getGuidedUnitContext(basePath) ?? getGuidedUnitContext() : getGuidedUnitContext();
+    clearGuidedUnitContext(guidedUnit?.basePath ?? basePath);
     try {
         if (await checkDeepProjectSetupAfterTurn(event, ctx, basePath)) {
             return;
@@ -335,12 +431,13 @@ export async function handleAgentEnd(pi, event, ctx) {
     // discussions (where isAutoActive may be false) still get recovered.
     if (maybeHandleEmptyIntentTurn(event, isAutoActive(), basePath))
         return;
-    if (!isAutoActive())
+    if (!isAutoActive()) {
+        observeManualDiscussTerminalError(ctx, lastMsg, guidedUnit);
         return;
+    }
     if (shouldIgnoreAgentEndForActiveUnit(event)) {
         return;
     }
-    const lastMsg = event.messages[event.messages.length - 1];
     if (isSessionSwitchInFlight()) {
         _handleSessionSwitchAgentEnd(lastMsg, resolveAgentEndCancelled);
         return;
@@ -428,9 +525,9 @@ export async function handleAgentEnd(pi, event, ctx) {
             });
             return;
         }
-        // #3588: When errorMessage is uninformative, extract the real error from
-        // the assistant message text content for display purposes only.
-        // Classification still uses rawErrorMsg to avoid false positives from prose.
+        // #3588/#956: When errorMessage is uninformative, extract the real error
+        // from assistant text. Prefer rawErrorMsg for classification to avoid
+        // prose false-positives, but use display text when rawErrorMsg is empty.
         const displayMsg = resolveAgentEndErrorDisplay(rawErrorMsg, "content" in lastMsg ? lastMsg.content : undefined);
         if (isAutoCompletionStopInProgress() &&
             isTerminalDeletedWorktreeProviderError(`${rawErrorMsg}\n${displayMsg}`)) {
@@ -440,8 +537,8 @@ export async function handleAgentEnd(pi, event, ctx) {
         }
         const errorDetail = displayMsg ? `: ${displayMsg}` : "";
         const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
-        // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
-        const cls = classifyError(rawErrorMsg, explicitRetryAfterMs);
+        // ── 1. Classify, preserving non-empty errorMessage precedence ──────
+        const cls = classifyError(rawErrorMsg || displayMsg, explicitRetryAfterMs);
         // ── 1a. Unsupported-model: provider rejected this model for the current
         //        account/plan at request time (#4513).  Persist a block so the
         //        same dead model isn't reselected on the next /gsd auto restart,
@@ -486,7 +583,7 @@ export async function handleAgentEnd(pi, event, ctx) {
                 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,
                 rawErrorMsg,
@@ -510,10 +607,30 @@ export async function handleAgentEnd(pi, event, ctx) {
         // Core retries transient failures in-session after this handler.
         // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
         // but let rate-limit continue into model fallback logic below (#4373).
-        if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg)) {
+        if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg, rawErrorMsg || displayMsg)) {
             return;
         }
+        // ── Tool-schema overload: the active model repeatedly emitted tool-call
+        //    arguments that fail schema validation (e.g. a model whose tool-call
+        //    grammar can't satisfy GSD's schemas). Before hard-pausing, try the
+        //    unit's configured fallbacks and the auto-mode start model — the model
+        //    the user actually selected. This lets auto-mode recover by switching
+        //    back to a schema-capable model instead of aborting outright (#813).
+        //    Do not persistently block the model: schema-overload is request-shape
+        //    specific, mirroring the model-error path above.
         if (cls.kind === "tool-schema") {
+            const dash = getAutoDashboardData();
+            const switched = await tryProviderModelFallback({
+                ctx,
+                pi,
+                rejectedProvider: ctx.model?.provider,
+                rejectedId: ctx.model?.id,
+                basePath: dash.basePath,
+                unitType: dash.currentUnit?.type,
+                switchedNotify: (label) => ctx.ui.notify(`Switched to ${label} after repeated tool schema validation failures.`, "warning"),
+            });
+            if (switched)
+                return;
             await pauseAutoForProviderError(ctx.ui, errorDetail, () => pauseAuto(ctx, pi, {
                 message: `Tool schema error${errorDetail}`,
                 category: "tool-schema",
@@ -525,13 +642,19 @@ export async function handleAgentEnd(pi, event, ctx) {
             });
             return;
         }
-        // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli)
+        // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli, google-antigravity)
         // which use per-user quotas with shorter windows (#2922).
         if (cls.kind === "rate-limit") {
             const currentProvider = ctx.model?.provider;
-            if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") {
+            if (currentProvider === "openai-codex"
+                || currentProvider === "google-gemini-cli"
+                || currentProvider === "google-antigravity") {
                 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 ──────────────────────────────────────────────────
         // --- Network errors: same-model retry with backoff ---
@@ -560,46 +683,22 @@ export async function handleAgentEnd(pi, event, ctx) {
         // --- Transient errors: try model fallback first, then pause ---
         // Rate limits are often per-model, so switching models can bypass them.
         if (cls.kind === "rate-limit" || cls.kind === "network" || cls.kind === "server" || cls.kind === "connection" || cls.kind === "stream") {
-            // Try model fallback
             const dash = getAutoDashboardData();
-            if (dash.currentUnit) {
-                const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
-                if (modelConfig && modelConfig.fallbacks.length > 0) {
-                    const availableModels = ctx.modelRegistry.getAvailable();
-                    const nextModelId = getNextFallbackModel(ctx.model?.id, modelConfig);
-                    if (nextModelId) {
-                        retryState.networkRetryCount = 0;
-                        retryState.currentRetryModelId = undefined;
-                        const modelToSet = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
-                        if (modelToSet) {
-                            const ok = await pi.setModel(modelToSet, { persist: false });
-                            if (ok) {
-                                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 });
-                                return;
-                            }
-                        }
-                    }
-                }
-            }
-            // Try restoring session model
-            const sessionModel = getAutoModeStartModel();
-            if (sessionModel) {
-                if (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) {
-                            setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
-                            retryState.networkRetryCount = 0;
-                            retryState.currentRetryModelId = undefined;
-                            ctx.ui.notify(`Model error${errorDetail}. Restored session model: ${sessionModel.provider}/${sessionModel.id} and resuming.`, "warning");
-                            pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
-                            return;
-                        }
-                    }
-                }
+            const switched = await tryProviderModelFallback({
+                ctx,
+                pi,
+                rejectedProvider: ctx.model?.provider,
+                rejectedId: ctx.model?.id,
+                basePath: dash.basePath,
+                unitType: dash.currentUnit?.type,
+                switchedNotify: (label) => {
+                    retryState.networkRetryCount = 0;
+                    retryState.currentRetryModelId = undefined;
+                    ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${label} and resuming.`, "warning");
+                },
+            });
+            if (switched) {
+                return;
             }
         }
         // --- Transient fallback: pause with auto-resume ---

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -2,6 +2,7 @@
 // File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type, StringEnum } from "@gsd/pi-ai";
 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";
 import { importWorkflowExecutorsModule } from "../workflow-mcp.js";
@@ -10,6 +11,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() {
     return importWorkflowExecutorsModule();
 }
@@ -41,6 +43,13 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         execute,
     });
 }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but varies by schema
+function registerWorkflowTool(pi, toolDef) {
+    pi.registerTool(toolDef);
+    for (const alias of aliasesForWorkflowTool(toolDef.name)) {
+        registerAlias(pi, toolDef, alias, toolDef.name);
+    }
+}
 function requirementRootWriteGuard(operation, basePath) {
     const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(basePath), "REQUIREMENTS");
     if (!guard.block)
@@ -155,8 +164,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(decisionSaveTool);
-    registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
+    registerWorkflowTool(pi, decisionSaveTool);
     // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
     const requirementUpdateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -241,8 +249,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(requirementUpdateTool);
-    registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
+    registerWorkflowTool(pi, requirementUpdateTool);
     // ─── gsd_requirement_save ─────────────────────────────────────────────
     const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -340,8 +347,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(requirementSaveTool);
-    registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
+    registerWorkflowTool(pi, requirementSaveTool);
     // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
     const summarySaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         try {
@@ -368,13 +374,17 @@ export function registerDbTools(pi) {
             "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, theme) {
@@ -397,8 +407,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(summarySaveTool);
-    registerAlias(pi, summarySaveTool, "gsd_save_summary", "gsd_summary_save");
+    registerWorkflowTool(pi, summarySaveTool);
     // ─── gsd_uat_result_save ─────────────────────────────────────────────────
     const uatResultSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeUatResultSave } = await loadWorkflowExecutors();
@@ -480,7 +489,7 @@ export function registerDbTools(pi) {
             return new Text(theme.fg("success", `UAT ${d?.sliceId ?? ""}: ${d?.verdict ?? "saved"}`), 0, 0);
         },
     };
-    pi.registerTool(uatResultSaveTool);
+    registerWorkflowTool(pi, uatResultSaveTool);
     // ─── gsd_milestone_generate_id (formerly gsd_generate_milestone_id) ────
     const milestoneGenerateIdExecute = async (_toolCallId, _params, _signal, _onUpdate, _ctx) => {
         try {
@@ -566,8 +575,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(milestoneGenerateIdTool);
-    registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
+    registerWorkflowTool(pi, milestoneGenerateIdTool);
     // ─── gsd_plan_milestone (gsd_milestone_plan alias) ─────────────────────
     const planMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executePlanMilestone } = await loadWorkflowExecutors();
@@ -633,8 +641,7 @@ export function registerDbTools(pi) {
         }),
         execute: planMilestoneExecute,
     };
-    pi.registerTool(planMilestoneTool);
-    registerAlias(pi, planMilestoneTool, "gsd_milestone_plan", "gsd_plan_milestone");
+    registerWorkflowTool(pi, planMilestoneTool);
     // ─── gsd_plan_slice (gsd_slice_plan alias) ─────────────────────────────
     const planSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executePlanSlice } = await loadWorkflowExecutors();
@@ -678,8 +685,7 @@ export function registerDbTools(pi) {
         }),
         execute: planSliceExecute,
     };
-    pi.registerTool(planSliceTool);
-    registerAlias(pi, planSliceTool, "gsd_slice_plan", "gsd_plan_slice");
+    registerWorkflowTool(pi, planSliceTool);
     // ─── gsd_plan_task (gsd_task_plan alias) ───────────────────────────────
     const planTaskExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -748,8 +754,7 @@ export function registerDbTools(pi) {
         }),
         execute: planTaskExecute,
     };
-    pi.registerTool(planTaskTool);
-    registerAlias(pi, planTaskTool, "gsd_task_plan", "gsd_plan_task");
+    registerWorkflowTool(pi, planTaskTool);
     // ─── gsd_task_complete (gsd_complete_task alias) ────────────────────────
     const taskCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeTaskComplete } = await loadWorkflowExecutors();
@@ -809,8 +814,7 @@ export function registerDbTools(pi) {
         }),
         execute: taskCompleteExecute,
     };
-    pi.registerTool(taskCompleteTool);
-    registerAlias(pi, taskCompleteTool, "gsd_complete_task", "gsd_task_complete");
+    registerWorkflowTool(pi, taskCompleteTool);
     // ─── gsd_slice_complete (gsd_complete_slice alias) ─────────────────────
     const sliceCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeSliceComplete } = await loadWorkflowExecutors();
@@ -875,8 +879,7 @@ export function registerDbTools(pi) {
         }),
         execute: sliceCompleteExecute,
     };
-    pi.registerTool(sliceCompleteTool);
-    registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete");
+    registerWorkflowTool(pi, sliceCompleteTool);
     // ─── gsd_skip_slice (#3477 / #3487) ───────────────────────────────────
     const skipSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -941,7 +944,7 @@ export function registerDbTools(pi) {
             };
         }
     };
-    pi.registerTool({
+    registerWorkflowTool(pi, {
         name: "gsd_skip_slice",
         label: "Skip Slice",
         description: "Mark a slice as skipped so auto-mode advances past it without executing. " +
@@ -1000,8 +1003,7 @@ export function registerDbTools(pi) {
         }),
         execute: milestoneCompleteExecute,
     };
-    pi.registerTool(milestoneCompleteTool);
-    registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
+    registerWorkflowTool(pi, milestoneCompleteTool);
     // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
     const milestoneValidateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeValidateMilestone } = await loadWorkflowExecutors();
@@ -1035,8 +1037,7 @@ export function registerDbTools(pi) {
         }),
         execute: milestoneValidateExecute,
     };
-    pi.registerTool(milestoneValidateTool);
-    registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
+    registerWorkflowTool(pi, milestoneValidateTool);
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeReplanSlice } = await loadWorkflowExecutors();
@@ -1078,8 +1079,7 @@ export function registerDbTools(pi) {
         }),
         execute: replanSliceExecute,
     };
-    pi.registerTool(replanSliceTool);
-    registerAlias(pi, replanSliceTool, "gsd_slice_replan", "gsd_replan_slice");
+    registerWorkflowTool(pi, replanSliceTool);
     // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
     const reassessRoadmapExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeReassessRoadmap } = await loadWorkflowExecutors();
@@ -1126,8 +1126,7 @@ export function registerDbTools(pi) {
         }),
         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.
     const reopenTaskExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -1190,8 +1189,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenTaskExecute,
     };
-    pi.registerTool(reopenTaskTool);
-    registerAlias(pi, reopenTaskTool, "gsd_reopen_task", "gsd_task_reopen");
+    registerWorkflowTool(pi, reopenTaskTool);
     // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
     const reopenSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -1253,8 +1251,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenSliceExecute,
     };
-    pi.registerTool(reopenSliceTool);
-    registerAlias(pi, reopenSliceTool, "gsd_reopen_slice", "gsd_slice_reopen");
+    registerWorkflowTool(pi, reopenSliceTool);
     // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
     const reopenMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -1314,8 +1311,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenMilestoneExecute,
     };
-    pi.registerTool(reopenMilestoneTool);
-    registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
+    registerWorkflowTool(pi, reopenMilestoneTool);
     // ─── gsd_save_gate_result ──────────────────────────────────────────────
     const saveGateResultExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeSaveGateResult } = await loadWorkflowExecutors();
@@ -1378,5 +1374,5 @@ export function registerDbTools(pi) {
             return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
         },
     };
-    pi.registerTool(saveGateResultTool);
+    registerWorkflowTool(pi, saveGateResultTool);
 }