gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -1,7 +1,13 @@
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
-import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
+import {
+  checkAutoStartAfterDiscuss,
+  maybeHandleReadyPhraseWithoutFiles,
+  maybeHandleEmptyIntentTurn,
+  resetEmptyTurnCounter,
+} from "../guided-flow.js";
+import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
@@ -16,10 +22,19 @@ import {
   isTransient,
   type ErrorClass,
 } from "../error-classifier.js";
+import { blockModel, isModelBlocked } from "../blocked-models.js";
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
-const MAX_TRANSIENT_AUTO_RESUMES = 8;
+/**
+ * Cap on auto-resume attempts for sustained transient-provider errors.
+ *
+ * Exported so tests assert against the shared constant instead of
+ * regex-scraping the source literal (see #4837). Raising this value to
+ * handle longer provider overloads should update the single constant; the
+ * test in provider-errors.test.ts consumes it directly.
+ */
+export const MAX_TRANSIENT_AUTO_RESUMES = 8;
 
 /**
  * Reset the module-level retry state so a resumed auto-session starts fresh.
@@ -70,10 +85,34 @@ export async function handleAgentEnd(
   event: { messages: any[] },
   ctx: ExtensionContext,
 ): Promise<void> {
+  // #4648 — Invalidate the directory-listing cache before any artifact-existence
+  // checks. The LLM may have written milestone files (CONTEXT.md, ROADMAP.md,
+  // PROJECT.md, REQUIREMENTS.md) via tool calls during the turn that just
+  // ended. `paths.ts` caches readdir() results without a TTL, so without this
+  // flush, `resolveMilestoneFile` returns the pre-write listing and the guards
+  // below (`checkAutoStartAfterDiscuss` and `maybeHandleReadyPhraseWithoutFiles`)
+  // falsely report files as missing — producing a spurious "ready signal
+  // rejected" loop even though the files are on disk.
+  clearPathCache();
+
   if (checkAutoStartAfterDiscuss()) {
     clearDiscussionFlowState();
     return;
   }
+
+  // #4573 — When the LLM emits "Milestone X ready." but the required files
+  // are missing, `checkAutoStartAfterDiscuss` returns false silently. Surface
+  // that and nudge the LLM to complete the writes before the user hits the
+  // downstream "All milestones complete" warning loop.
+  if (maybeHandleReadyPhraseWithoutFiles(event)) return;
+
+  // #4573 — Empty-turn recovery: if the LLM announced intent in prose but
+  // emitted no tool calls, nudge it to execute. Fires only when auto-mode is
+  // active or a discussion autostart is pending (non-auto interactive discuss
+  // is user-driven). Runs before `isAutoActive` early return so pending
+  // discussions (where isAutoActive may be false) still get recovered.
+  if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
+
   if (!isAutoActive()) return;
   if (isSessionSwitchInFlight()) return;
 
@@ -124,6 +163,102 @@ export async function handleAgentEnd(
     // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
     const cls = classifyError(rawErrorMsg, 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,
+    //        then try a fallback before pausing.
+    if (cls.kind === "unsupported-model") {
+      const dash = getAutoDashboardData();
+      const rejectedProvider = ctx.model?.provider;
+      const rejectedId = ctx.model?.id;
+      if (dash.basePath && rejectedProvider && rejectedId) {
+        try {
+          blockModel(dash.basePath, rejectedProvider, rejectedId, rawErrorMsg || "unsupported for account");
+          ctx.ui.notify(
+            `Blocked ${rejectedProvider}/${rejectedId} for this project — provider rejected it for the current account.`,
+            "warning",
+          );
+        } catch (err) {
+          const m = err instanceof Error ? err.message : String(err);
+          logWarning("bootstrap", `Failed to persist blocked model: ${m}`);
+        }
+      }
+
+      // Try configured fallback chain, skipping anything already blocked.
+      if (dash.currentUnit && dash.basePath) {
+        const modelConfig = resolveModelWithFallbacksForUnit(dash.currentUnit.type);
+        if (modelConfig && modelConfig.fallbacks.length > 0) {
+          const availableModels = ctx.modelRegistry.getAvailable();
+          let cursorModelId: string | undefined = ctx.model?.id;
+          while (true) {
+            const nextModelId = getNextFallbackModel(cursorModelId, modelConfig);
+            if (!nextModelId) break;
+            const candidate = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
+            if (candidate && !isModelBlocked(dash.basePath, candidate.provider, candidate.id)) {
+              const ok = await pi.setModel(candidate, { persist: false });
+              if (ok) {
+                setCurrentDispatchedModelId({ provider: candidate.provider, id: candidate.id });
+                ctx.ui.notify(
+                  `Switched to fallback ${candidate.provider}/${candidate.id} after account entitlement rejection.`,
+                  "warning",
+                );
+                pi.sendMessage(
+                  { customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false },
+                  { triggerTurn: true },
+                );
+                return;
+              }
+            }
+            cursorModelId = nextModelId;
+          }
+        }
+
+        // Fallback chain exhausted — try the auto-mode start model if it isn't
+        // the same one we just blocked and isn't itself blocked.
+        const sessionModel = getAutoModeStartModel();
+        if (
+          sessionModel &&
+          !(sessionModel.provider === rejectedProvider && sessionModel.id === rejectedId) &&
+          !isModelBlocked(dash.basePath, sessionModel.provider, sessionModel.id)
+        ) {
+          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 });
+              ctx.ui.notify(
+                `Restored auto-mode start model ${startModel.provider}/${startModel.id} after entitlement rejection.`,
+                "warning",
+              );
+              pi.sendMessage(
+                { customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false },
+                { triggerTurn: true },
+              );
+              return;
+            }
+          }
+        }
+      }
+
+      // No usable fallback — pause with a clearly named message.
+      const blockedLabel = rejectedProvider && rejectedId ? `${rejectedProvider}/${rejectedId}` : "current model";
+      const pauseDetail = `Model ${blockedLabel} blocked for this account${errorDetail}. Configure a different model and restart /gsd auto.`;
+      await pauseAutoForProviderError(ctx.ui, pauseDetail, () =>
+        pauseAuto(ctx, pi, {
+          message: pauseDetail,
+          category: "provider",
+          isTransient: false,
+        }),
+      {
+        isRateLimit: false,
+        isTransient: false,
+        retryAfterMs: 0,
+      });
+      return;
+    }
+
     // ── 1b. Defer to Core RetryHandler for most transient errors ────────
     // Core retries transient failures in-session after this handler.
     // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
@@ -239,6 +374,9 @@ export async function handleAgentEnd(
   // ── Success path ─────────────────────────────────────────────────────────
   try {
     resetRetryState(retryState);
+    // #4573 — Reset the empty-turn counter on any successful agent turn so
+    // transient stalls don't accumulate across independent units.
+    resetEmptyTurnCounter();
     resolveAgentEnd(event);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

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

@@ -35,6 +35,19 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+/**
+ * Read a tool result's structured payload, accommodating MCP's `details` →
+ * `structuredContent` rename (#4472, #4477). In-process executions still
+ * deliver the payload on `result.details`; MCP-routed executions deliver it
+ * on `result.structuredContent` (post `adaptExecutorResult` transform). All
+ * `renderResult` callbacks in this file route through this helper so a future
+ * field rename only needs to be applied in one place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
+function readDetails(result: any): any {
+  return result?.details ?? result?.structuredContent;
+}
+
 export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
 
@@ -110,7 +123,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -188,7 +201,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -273,7 +286,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -322,7 +335,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(text, 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -406,7 +419,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
     },
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
         return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
       }
@@ -478,6 +491,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       definitionOfDone: Type.Optional(Type.Array(Type.String(), { description: "Definition of done bullets" })),
       requirementCoverage: Type.Optional(Type.String({ description: "Requirement coverage text" })),
       boundaryMapMarkdown: Type.Optional(Type.String({ description: "Boundary map markdown block" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planMilestoneExecute,
   };
@@ -524,6 +540,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),
       integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })),
       observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planSliceExecute,
   };
@@ -594,6 +613,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       inputs: Type.Array(Type.String(), { description: "Input files or references" }),
       expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
       observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planTaskExecute,
   };
@@ -661,6 +683,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ]),
         { description: "Array of verification evidence entries" },
       )),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'task verified after retry')" })),
     }),
     execute: taskCompleteExecute,
   };
@@ -758,6 +783,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ]),
         { description: "Upstream slice dependencies consumed" },
       )),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'all tasks verified')" })),
     }),
     execute: sliceCompleteExecute,
   };
@@ -892,6 +920,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       lessonsLearned: Type.Optional(Type.Array(Type.String(), { description: "Lessons learned during the milestone" })),
       followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
       deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'milestone validation passed')" })),
     }),
     execute: milestoneCompleteExecute,
   };
@@ -976,6 +1007,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         { description: "Tasks to upsert (update existing or insert new)" },
       ),
       removedTaskIds: Type.Array(Type.String(), { description: "Task IDs to remove from the slice" }),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'blocker discovered during execution')" })),
     }),
     execute: replanSliceExecute,
   };
@@ -1031,6 +1065,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ),
         removed: Type.Array(Type.String(), { description: "Slice IDs to remove" }),
       }, { description: "Slice changes to apply" }),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'slice S01 completed, reassessing remaining roadmap')" })),
     }),
     execute: reassessRoadmapExecute,
   };
@@ -1038,6 +1075,203 @@ export function registerDbTools(pi: ExtensionAPI): void {
   pi.registerTool(reassessRoadmapTool);
   registerAlias(pi, reassessRoadmapTool, "gsd_roadmap_reassess", "gsd_reassess_roadmap");
 
+  // ─── gsd_task_reopen (gsd_reopen_task alias) ───────────────────────────
+  // Single-writer v3, Stream 3: reversibility tools for closed units.
+
+  const reopenTaskExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen task." }],
+        details: { operation: "reopen_task", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenTask } = await import("../tools/reopen-task.js");
+      const result = await handleReopenTask(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening task: ${result.error}` }],
+          details: { operation: "reopen_task", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+        details: {
+          operation: "reopen_task",
+          milestoneId: result.milestoneId,
+          sliceId: result.sliceId,
+          taskId: result.taskId,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_task tool failed: ${msg}`, { tool: "gsd_task_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening task: ${msg}` }],
+        details: { operation: "reopen_task", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenTaskTool = {
+    name: "gsd_task_reopen",
+    label: "Reopen Task",
+    description:
+      "Reset a completed task back to 'pending' so it can be re-done. Cleans up SUMMARY.md so the DB-filesystem reconciler does not auto-correct the task back to complete. " +
+      "Both the parent slice and milestone must still be open — use gsd_slice_reopen first if the slice has been closed.",
+    promptSnippet: "Reopen a completed GSD task (resets status to pending, removes SUMMARY.md)",
+    promptGuidelines: [
+      "Use gsd_task_reopen when a completed task needs to be re-done (e.g. verification missed a regression, requirements changed).",
+      "Will fail if the parent slice or milestone is already closed — reopen those first.",
+      "Will fail if the task is not currently 'complete' — there is nothing to reopen.",
+      "Use the canonical name gsd_task_reopen; gsd_reopen_task is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      taskId: Type.String({ description: "Task ID (e.g. T01)" }),
+      reason: Type.Optional(Type.String({ description: "Why the task is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'regression discovered post-completion')" })),
+    }),
+    execute: reopenTaskExecute,
+  };
+
+  pi.registerTool(reopenTaskTool);
+  registerAlias(pi, reopenTaskTool, "gsd_reopen_task", "gsd_task_reopen");
+
+  // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
+
+  const reopenSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen slice." }],
+        details: { operation: "reopen_slice", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenSlice } = await import("../tools/reopen-slice.js");
+      const result = await handleReopenSlice(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening slice: ${result.error}` }],
+          details: { operation: "reopen_slice", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened slice ${result.sliceId} (${result.milestoneId}); reset ${result.tasksReset} task(s) to pending.` }],
+        details: {
+          operation: "reopen_slice",
+          milestoneId: result.milestoneId,
+          sliceId: result.sliceId,
+          tasksReset: result.tasksReset,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_slice tool failed: ${msg}`, { tool: "gsd_slice_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening slice: ${msg}` }],
+        details: { operation: "reopen_slice", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenSliceTool = {
+    name: "gsd_slice_reopen",
+    label: "Reopen Slice",
+    description:
+      "Reset a completed slice back to 'in_progress' and reset ALL of its tasks back to 'pending'. Cleans up SUMMARY.md / UAT.md and per-task summaries. " +
+      "Reopening a slice means re-doing the work — partial resets create ambiguous state, so all tasks are reset.",
+    promptSnippet: "Reopen a completed GSD slice (resets all tasks to pending, removes summaries)",
+    promptGuidelines: [
+      "Use gsd_slice_reopen when a completed slice needs to be re-done (e.g. integration issue surfaced, requirements changed).",
+      "All tasks within the slice are reset to 'pending' — there is no partial-reopen.",
+      "Will fail if the parent milestone is already closed — reopen the milestone first.",
+      "Will fail if the slice is not currently 'complete' — there is nothing to reopen.",
+      "Use the canonical name gsd_slice_reopen; gsd_reopen_slice is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      reason: Type.Optional(Type.String({ description: "Why the slice is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'cross-slice regression discovered')" })),
+    }),
+    execute: reopenSliceExecute,
+  };
+
+  pi.registerTool(reopenSliceTool);
+  registerAlias(pi, reopenSliceTool, "gsd_reopen_slice", "gsd_slice_reopen");
+
+  // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
+
+  const reopenMilestoneExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen milestone." }],
+        details: { operation: "reopen_milestone", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenMilestone } = await import("../tools/reopen-milestone.js");
+      const result = await handleReopenMilestone(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening milestone: ${result.error}` }],
+          details: { operation: "reopen_milestone", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened milestone ${result.milestoneId}; reset ${result.slicesReset} slice(s) and ${result.tasksReset} task(s).` }],
+        details: {
+          operation: "reopen_milestone",
+          milestoneId: result.milestoneId,
+          slicesReset: result.slicesReset,
+          tasksReset: result.tasksReset,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_milestone tool failed: ${msg}`, { tool: "gsd_milestone_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening milestone: ${msg}` }],
+        details: { operation: "reopen_milestone", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenMilestoneTool = {
+    name: "gsd_milestone_reopen",
+    label: "Reopen Milestone",
+    description:
+      "Reset a closed milestone back to 'active', all of its slices to 'in_progress', and all tasks to 'pending'. " +
+      "Cleans up MILESTONE-SUMMARY.md, slice summaries, and task summaries so the DB-filesystem reconciler does not auto-correct status back to complete.",
+    promptSnippet: "Reopen a closed GSD milestone (resets slices and tasks, removes summaries)",
+    promptGuidelines: [
+      "Use gsd_milestone_reopen when a closed milestone needs to be re-done (e.g. validation failure surfaced after closure).",
+      "All slices reset to 'in_progress' and all tasks reset to 'pending' — no partial reopen.",
+      "Will fail if the milestone is not currently closed — there is nothing to reopen.",
+      "Use the canonical name gsd_milestone_reopen; gsd_reopen_milestone is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      reason: Type.Optional(Type.String({ description: "Why the milestone is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'post-closure validation failure')" })),
+    }),
+    execute: reopenMilestoneExecute,
+  };
+
+  pi.registerTool(reopenMilestoneTool);
+  registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
+
   // ─── gsd_save_gate_result ──────────────────────────────────────────────
 
   const saveGateResultExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
@@ -1074,13 +1308,31 @@ export function registerDbTools(pi: ExtensionAPI): void {
       text += theme.fg("dim", ` → ${args.verdict ?? ""}`);
       return new Text(text, 0, 0);
     },
+    /**
+     * Render the save_gate_result tool output for the TUI.
+     *
+     * Prefers structured fields, but falls back to `content[0].text` when the
+     * structured payload is empty. Defensive: the structural fix on this
+     * branch plumbs `details` through MCP via `structuredContent`, but older
+     * hosts, a future handler that forgets `structuredContent`, or any drop
+     * of non-standard return fields would otherwise render as
+     * "undefined: undefined". Same fallback applies to error rendering, and
+     * we strip a leading `Error:` from the fallback text to avoid producing
+     * `Error: Error: ...`.
+     */
     renderResult(result: any, _options: any, theme: any) {
-      const d = result.details;
+      const d = readDetails(result);
       if (result.isError || d?.error) {
-        return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+        const rawMsg = d?.error ?? result.content?.[0]?.text ?? "unknown";
+        const msg = rawMsg.replace(/^\s*Error:\s*/i, "");
+        return new Text(theme.fg("error", `Error: ${msg}`), 0, 0);
+      }
+      if (!d?.gateId || !d?.verdict) {
+        const text = result.content?.[0]?.text ?? "Gate result saved";
+        return new Text(theme.fg("success", text), 0, 0);
       }
-      const color = d?.verdict === "flag" ? "warning" : "success";
-      return new Text(theme.fg(color, `${d?.gateId}: ${d?.verdict}`), 0, 0);
+      const color = d.verdict === "flag" ? "warning" : "success";
+      return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
     },
   };